[4.2] Add websocket callbacks

[T4rk1n]

Implements WebSocket-based callbacks for Dash, enabling real-time bidirectional communication between the renderer and backend. This replaces HTTP POST requests with persistent WebSocket connections for reduced latency and server-push capabilities.

Architecture

  ┌─────────────────────────────────────────────────────────────────────────┐                                                                                                                                               
  │ Browser Tab 1                          Browser Tab 2                    │                                                                                                                                              
  │ ┌─────────────┐                       ┌─────────────┐                   │                                                                                                                                               
  │ │  Renderer   │                       │  Renderer   │                   │                                                                                                                                               
  │ └──────┬──────┘                       └──────┬──────┘                   │                                                                                                                                               
  │        │ postMessage                         │ postMessage              │                                                                                                                                               
  │        └────────────┬───────────────────────┘                           │                                                                                                                                               
  │                     ▼                                                   │                                                                                                                                              
  │         ┌─────────────────────┐                                         │                                                                                                                                               
  │         │  SharedWorker       │  (one per origin)                       │                                                                                                                                               
  │         │  dash-ws-worker     │                                         │                                                                                                                                               
  │         └──────────┬──────────┘                                         │                                                                                                                                               
  └────────────────────│────────────────────────────────────────────────────┘                                                                                                                                               
                       │ WebSocket                                                                                                                                                                                          
                       ▼                                                                                                                                                                                                    
  ┌─────────────────────────────────────────────────────────────────────────┐                                                                                                                                               
  │ Server (FastAPI)                                                        │                                                                                                                                              
  │   WebSocket Endpoint: /_dash-ws-callback                                │                                                                                                                                              
  └─────────────────────────────────────────────────────────────────────────┘                                                                                                                                               

A SharedWorker maintains a single WebSocket connection shared across all browser tabs, routing messages between renderers and the server.

Usage

Use with fastapi pip install dash[fastapi]==4.2.0rc1 (when available).

# Enable WebSocket callbacks                                                                                                                                                                                              
  app = Dash(__name__, backend="fastapi", websocket_callbacks=True)                                                                                                                                                                            
                                                                                                                                                                                                                            
  @callback(Output("output", "children"), Input("input", "value"))                                                                                                                                                          
  async def update(value):                                                                                                                                                                                                        
      # Stream intermediate updates via WebSocket                                                                                                                                                                           
      ws = ctx.get_websocket                                                                                                                                                                                                
      if ws:                                                                                                                                                                                                                
          await ws.set_prop("progress", "value", 50)                                                                                                                                                                        
                                                                                                                                                                                                                            
      return f"Result: {value}"

Example app in wsapp.py (to be deleted before full release alongside quart_app.py)

[github-actions]

Thank you for your contribution to Dash! 🎉

This PR is exempt from requiring a linked issue due to its labels.

[BSd3v]

First, I want to say that this is a great step at the flexibility of Dash and reducing network load.

---

I have some concerns with security of the app level websockets that are currently implemented:

1. Initial Handshake Origin Validation

• Concern: The current implementation lacks strict validation of the Origin header during the WebSocket handshake.
• Risk: Without explicit origin validation, the app is exposed to Cross-Site WebSocket Hijacking and unauthorized domains opening connections, leading to data leakage or session compromise.
• Recommendation: Implement an explicit check to only allow upgrades (wss://) from trusted domains. Reject any connection attempts with a mismatched or missing Origin header.

2. Developer Control Over WebSocket and Disconnect

• Concern: The framework offers limited or no hooks for developers to explicitly close or disconnect specific WebSocket connections (e.g., on suspicious activity, user ban, or policy violation).
• Risk: Persistent, unattended connections could be abused, or connections that should be invalidated (e.g., on role change, session revoke) might remain open, with the app developer having no way to enforce disconnect logic.
• Recommendation: Add mechanisms for app-level code to enumerate active connections and forcibly close or invalidate sessions as needed (e.g., via a server API or callback).

3. Supporting Login/Logout and Session Lifecycle

• Concern: There is insufficient handling in the PR for session lifecycle events such as login, logout, or user switching.
• Risk: WebSocket connections might remain active after a user logs out or switches accounts. This can result in privilege escalation, session fixation, or data leaks across users or sessions.
• Recommendation: Tie the lifetime of a WebSocket connection to the authenticated user’s session. Enforce immediate disconnection on logout/session expiration, and require establishing a new, authenticated WebSocket on subsequent login.

[BSd3v]

Will this be able to be set as an environment variable?

[T4rk1n]

Yes, this is intended for embedded support.

[CNFeffery]

For some unknown reason, when testing the functionality of the current branch, I am unable to capture the corresponding WebSocket interface in the browser developer tools while the application is interacting normally:

---

After carefully studying the source code, it is found that this SharedWorker architecture allows packet capture in Chrome via chrome://inspect/#workers.

[T4rk1n]

For some unknown reason, when testing the functionality of the current branch, I am unable to capture the corresponding WebSocket interface in the browser developer tools while the application is interacting normally:

After carefully studying the source code, it is found that this SharedWorker architecture allows packet capture in Chrome via chrome://inspect/#workers.

Oh cool, I had noticed the shared worker was not connected in the firefox devtools, I think there is a flag we can put in the dev bundle.

[KoolADE85]

This is an awesome feature, and it's working well overall! 🎉
I left a couple comments around scalability/performance that I think we should look into.

[KoolADE85]

This execution flow blocks the ws event loop. If the callback is synchronous and slow, all other callbacks are blocked. And if the callback takes longer than the heartbeat, the client will disconnect and lose all pending callbacks.

You can see this by adding a simple time.sleep(15) to one of the callbacks in wsapp.py

I know FastAPI supplies a run_in_threadpool which may help - or perhaps we could leverage our own background callback code?

[KoolADE85]

When a disconnect happens, we should also cancel any pending callbacks. Currently, the loading state will stay on forever even if the socket reconnects.

[KoolADE85]

This reconnection path should reset the retryCount before creating the connection.

[KoolADE85]

This silently no-ops on Flask - I think we should raise or warn in this case since none of the websocket features they asked for are actually turned on.

[KoolADE85]

I'm a little concerned that this is executed with no queue or cap on the number of callbacks that can be executed at once.
I think with the REST callbacks, we are naturally protected from callback spamming because browsers only send a limited number of requests at once.
But with websockets, I think this could result in some sort of "callback storm" if the app is written for it. We should limit the max number of concurrent callbacks.