Blazor Server Circuit Persistence With Proxy-Handled WebSocket Upgrades

Reconciling Circuit Lifecycle and Proxy Timeouts

Increasing AutoDisconnectTimeout does not prevent a reverse proxy from terminating an idle WebSocket. That setting only controls how long the server retains the circuit state after the connection is already lost. To prevent premature closure, you must ensure the SignalR heartbeat frequency is higher than the proxy's idle timeout threshold.

The Interaction Between Timeouts

In a Blazor Server deployment, three distinct timers interact. The most restrictive timer always wins:

• Proxy Idle Timeout: The duration of inactivity before the proxy closes the TCP connection.
• KeepAliveInterval: The frequency at which the server sends a "ping" to the client to keep the connection active.
• AutoDisconnectTimeout: The grace period the server allows for a client to reconnect before destroying the circuit state.

Implementation Steps for Persistence

To maintain a persistent connection and avoid circuit thrashing, apply the following configurations:

1. Align Heartbeats with Proxy Thresholds

Set the KeepAliveInterval to a value significantly lower than your proxy's idle timeout (e.g., if the proxy timeout is 60 seconds, set the interval to 15–30 seconds). This ensures the proxy sees constant traffic.

services.AddServerSideBlazor().AddHubOptions(options => {
    options.KeepAliveInterval = TimeSpan.FromSeconds(15);
});

2. Configure Proxy WebSocket Upgrades

The proxy must explicitly pass the Upgrade and Connection headers. Without these, the initial handshake fails or reverts to Long Polling, which is more susceptible to timeout-induced disconnects.

• NGINX: Ensure proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; are present.
• Azure App Service/AWS ALB: Enable "WebSockets" in the platform configuration settings.

3. Enforce Session Affinity (Sticky Sessions)

If using a load balancer, sticky sessions are mandatory. If a proxy terminates a connection and the client reconnects to a different server instance, the original circuit cannot be resumed, resulting in a full page reload and state loss.

Verification and Diagnostics

To verify the fix, use the Browser DevTools Network tab: filter for WS (WebSockets) and inspect the frames. You should see a consistent stream of ping/pong frames occurring at the interval defined in your KeepAliveInterval.

Missing Diagnostic Detail: Are you deploying to a multi-node cluster or a single server? If multi-node, the recommendation shifts from timeout tuning to verifying the Redis backplane or sticky session configuration.