Circuit can be paused by Blazor when inactivity is detected

[ilonatommy]

Application configures the timeout for pause as opt-in feature. This value is treated as a suggestion for the framework, depending on UI state, deferral or rejection of pause can happen.

Some features are not available on all browsers. In this case [❌ browser name] is added to mark that they are not affected.

Pause deferral / rejection

Scenarios where auto pause according to hiddenDelayMilliseconds is not what we want. Some scenarios work as "veto" - e.g. edited input will stay edited until user comes back to it and cleans it manually, and some scenarios work as "deferral" - a job that is supposed to complete and should be awaited.

• Download that involves circuit (with DotNetStreamReference) [deferral]
• Upload that uses circuit (with JSStreamReference) [deferral]
• JSInterop callbacks in-flight [deferral]
• IBrowserFile circuit owned streams [deferral]
• edited inputs that saves values on focus-out (HTML input text/search/email/url/tel/password/number, textarea, content editable div, InputText) which are edited and focused. Edited == its content differs from the initial value sent by the server - similar to React's "dirty" field concept. [veto]
• custom element or same-origin iframe that contains any focused, edited HTML element from the previous point [veto]
• audio / video playing [veto]
• Picture in Picture opened (stops being a blocking factor after PiP is closed by user) [deferral] [❌ Firefox]
• Active Web Lock. It's easy to detect lock presence and defer pause but there's no public API to detect lock release. Long living lock can defer the pause forever, framework has to poll to try releasing. When lock is held, chromium heuristic doesn't let the tab get frozen so pause shouldn't happen either. [deferral]

In all these scenarios AutoPauseManager tracks the active work and waits until it is resolved, on the top of waiting for hiddenDelayMilliseconds to elapse. If visibility changes to visible during this wait, the pause doesn't happen.

Inputs that do not require blure/focus-out to preserve values: radio, checkbox, select, slider, date/time/datetime-local/month/week.

Risks:

• Potential data loss on pause if we are missing a scenario where input preserving is required but it's not discussed in this description. The initial review should focus on this aspect before analyzing the code. Inputs are taken from this doc. General ideas taken from Chrome scheduler.
• Edited HTML file input is a special case - it saves value to the browser on file selection but due to security reasons native input.files is read-only. Attempt to bind to it and restore it from persistance storage would cause browser exception. Bytes are saved at the server but <input type=file> won't know it after the resume. Loss of data on the client is accepted - developer can manually write e.g.

@using Microsoft.JSInterop
<input id="persist-upload" type="file" @onchange="HandlePersistedUpload" />
<span id="persist-upload-label">@PersistedUploadName</span>
@code {
   [PersistentState(AllowUpdates = true)] public string? PersistedUploadName {get; set;}
   private async Task HandlePersistedUpload(ChangeEventArgs _)
    {
        PersistedUploadName = await JS.InvokeAsync<string>("autoPauseTest.getFileName", "persist-upload");
    }
}

ToDo: add this snippet to documentation with description of not-supported scenario from Pause_BindWithPersistentStateOnFileInput_ThrowsInvalidStateError.

• E.g. custom DOM element with 3 embedded text input element, that preserves the state of all of them on a button click. 2 out of 3 inputs are edited, the user is on the 3rd one that is focused but not edited. Because focus is on a "clean" input and "dirty" inputs didn't have blazor's @binding, their focus out didn't save the values to server and the state is lost after tab change. We consider it by app design - custom element is responsible for saving the values. If the button was not pressed, it's okay to loose it.
• <canvas> do not have activeElement, drawing component state cannot be saved, we cannot check when it's "dirty" and we don't have an easy way to serialize it. It's the app responsibility to veto pause via Blazor.pause.waitFor or running autosave on each stroke.
• Closed shadow DOM - only the element's own code can reach inside, same mitigation as canvas.
• Cross-origin <iframe> and popups, from security reasons framework has no access to it, same mitigation as above.
• Active WebRTC connection - pause will not break the P2P connection but UI will be stale. Chromium has access to RTCPeerConnection and gets notified about its creation/destruction through internal callbacks. Monkey-patching RTCPeerConnection constructor is a risky change we would like to avoid. Mitigation: app tracks active connections and saves state in a Blazor.pause.waitFor handler.
• Capturing media (mic/camera/screen sharing) - same problem as WebRTC, chromium enumerates through media capture via internal MediaStreamManager. The only way to mimic it would be to monkey-patch its media getters - not acceptable. Mitigation: app that calls getUserMedia is responsible for saving state in a Blazor.pause.waitFor handler as long as the stream is alive.
• Active XRSession for VR/AR. same problem as above, XRSession is internal to chromium. Mitigation: app that opens the session should save state in a Blazor.pause.waitFor handler. [Safari ❌, Firefox ❌]
• Notification visible. Same as above.

Other

Cases independent from SignalR connection but chromium defers freeze for them:

• In-flight fetch. Chromium defers freeze because fetch request is handed from renderer process that chromium freezes. However, pause influences SignalR only that is independent from fetch.
• Open WebSocket, Service Worker event, Pending IndexedDB transaction - similar to fetch.
• Background sync registered, File System Access writable stream - similar to fetch [Safari ❌, Firefox ❌].
• Hardware connection, e.g. WebUSB, WebSerial, WebHID, WebBluetooth, casting screen. They are all affected by Chomium freezing rendering process but pausing SignalR doesn't affect them. We don't test these because CI doesn't offer hardware and mock tests do not provide more value than networking tests we did add. [Safari ❌, Firefox ❌]

Public API

C# Server Configuration

Auto-pause is configured by calling AddAutoPause on the circuit's BrowserOptions, which flow to the client:

// AutoPauseBrowserOptions (in Microsoft.AspNetCore.Components namespace)
public sealed class AutoPauseBrowserOptions
{
    public bool Enabled { get; set; }  = true;
    public TimeSpan HiddenDelay { get; set; } = TimeSpan.FromMinutes(2);
}

Registration extension (same namespace). Calling AddAutoPause is what enables the feature:

public static BrowserOptions AddAutoPause(this BrowserOptions options, Action<AutoPauseBrowserOptions>? configure = null);

Used via query string in tests (auto-pause=true&auto-pause-delay-ms=200) or via AddAutoPause in production apps:

app.MapRazorComponents<App>()
    .WithBrowserOptions(options => options.AddAutoPause(p => p.HiddenDelay = TimeSpan.FromSeconds(30)));

JS API

// Pause deferral handlers (available when autoPause is enabled)
Blazor.pause.waitFor(fn, options);
// fn:      (signal: AbortSignal, source?: string) => void | Promise<void>
// options: { source?: 'server' }   // omit for client/auto pauses

Blazor.pause.waitFor registers a callback invoked before pause. The callback receives an AbortSignal that aborts if the tab becomes visible (cancelling the pause). Use it to save state or veto pause by holding a long-running promise.

The same API serves every pause source, routed by the optional source: An untagged handler runs on every kind of pause. A handler registered with { source: 'server' } runs only on a server-initiated pause (Circuit.RequestCircuitPauseAsync). Any other label (the auto-pause package uses 'auto') runs only on client/auto pauses. This replaces the previous CircuitStartOptions.onPauseRequested callback, which is removed: server-pause deferrals are now registered the same way as every other deferral, just scoped with { source: 'server' }.

Fixes #64886

[Copilot]

Pull request overview

Copilot reviewed 72 out of 73 changed files in this pull request and generated 1 comment.

[oroztocil]

@ilonatommy @javiercn

When fixing the problem with resuming expired client-stored state (#64798), I proposed to Javier that we could add a separate property in CircuitOptions for configuring the expiration period specifically for the client-stored state. For context, when the client tries to resume the session, it sends its serialized state to the server - if the state is expired (as recognized by data protection from the baked-in expiration timestamp), the operation fails, the session cannot be resumed and the page is reloaded.

Currently, we are computing the expiration period as the maximum of PersistedCircuitInMemoryRetentionPeriod and PersistedCircuitDistributedRetentionPeriod. I argued that a separate setting would be less confusing and give users more flexibility - server-side persistence settings would not control client-side persistence. Javier did not see it as worth it to add another setting for this.

Now with pausing becoming a much more prominent feature, I would like to evaluate the question again. How do you feel about adding something like PersistedCircuitClientRetentionPeriod setting to control the expiration date of client-stored paused state? (It is fine if we do not change it, I just want this to be a deliberate choice.)

[javiercn]

@ilonatommy @javiercn

When fixing the problem with resuming expired client-stored state (#64798), I proposed to Javier that we could add a separate property in CircuitOptions for configuring the expiration period specifically for the client-stored state. For context, when the client tries to resume the session, it sends its serialized state to the server - if the state is expired (as recognized by data protection from the baked-in expiration timestamp), the operation fails, the session cannot be resumed and the page is reloaded.

Currently, we are computing the expiration period as the maximum of PersistedCircuitInMemoryRetentionPeriod and PersistedCircuitDistributedRetentionPeriod. I argued that a separate setting would be less confusing and give users more flexibility - server-side persistence settings would not control client-side persistence. Javier did not see it as worth it to add another setting for this.

Now with pausing becoming a much more prominent feature, I would like to evaluate the question again. How do you feel about adding something like PersistedCircuitClientRetentionPeriod setting to control the expiration date of client-stored paused state? (It is fine if we do not change it, I just want this to be a deliberate choice.)

I'm not sure what we are gaining from it. And it would imply even more complexity as we now would need to harmonize three separate settings. The server is always in control of what state is valid, and if we are already reloading when resume fails, I'm not sure what we gain from it.

Dropping the state on the client while is still usable is the worst thing that can happen on this feature, it breaks the session continuity, and in the case of a graceful pause, it introduced an issue that didn't exist before.

[oroztocil]

I'm not sure what we are gaining from it. And it would imply even more complexity as we now would need to harmonize three separate settings. The server is always in control of what state is valid, and if we are already reloading when resume fails, I'm not sure what we gain from it.

Dropping the state on the client while is still usable is the worst thing that can happen on this feature, it breaks the session continuity, and in the case of a graceful pause, it introduced an issue that didn't exist before.

What if the user wants short server-side retention period because they have limited server resources but they do not care how long the client holds the paused state? They would need an independent knob to turn.

[maraf]

Looks good to me 👍