WebSocket

Optional WebSocket support via wsproto

2 min read 392 words

Overview

WebSocket support is provided via thewsprotolibrary. Install the extra:

uv add "bengal-pounce[ws]"

If wsprotois missing, WebSocket setup fails with an install hint: pip install bengal-pounce[ws].

Pounce supports:

  • Standard WebSocket — Upgrade from HTTP/1.1
  • WebSocket over HTTP/2 — Multiplexed with other HTTP/2 streams when both ws and h2extras are installed
  • Per-message compression — Via the negotiated permessage-deflate extension

ASGI WebSocket Lifecycle

WebSocket connections follow the ASGI WebSocket spec:

stateDiagram-v2 [*] --> Connect: websocket.connect Connect --> Accepted: websocket.accept Connect --> Rejected: websocket.close Rejected --> [*] Accepted --> Messaging: ready Messaging --> Messaging: websocket.receive / websocket.send Messaging --> Disconnected: websocket.disconnect Disconnected --> [*]
  1. Connect —websocket.connectevent received
  2. Accept/Reject — App sendswebsocket.accept or websocket.close
  3. Messages — Bidirectionalwebsocket.receive and websocket.send
  4. Disconnect —websocket.disconnectevent
async def websocket_app(scope, receive, send):
    assert scope["type"] == "websocket"

    # Wait for connection
    event = await receive()
    assert event["type"] == "websocket.connect"

    # Accept the connection
    await send({"type": "websocket.accept"})

    # Echo messages
    while True:
        event = await receive()
        if event["type"] == "websocket.disconnect":
            break
        await send({
            "type": "websocket.send",
            "text": event.get("text", ""),
        })

WebSocket over HTTP/2

When bothbengal-pounce[h2] and bengal-pounce[ws]are installed, WebSocket connections can use the HTTP/2 extended CONNECT method (RFC 8441). Treat this as a separately proven protocol path from HTTP/1 WebSocket support; keep deployment validation around accept/send/receive/close, stream reset, and missing-extra behavior.

WebSocket over HTTP/3 is not currently supported.

Configuration

WebSocket connections share some settings with HTTP connections:

Setting Default Applies To
websocket_compression True Allow permessage-deflate negotiation; compression remains off unless the client explicitly offers it
websocket_max_message_size 10,485,760(10 MB) Maximum WebSocket message size
max_connections 10,000 Total connections (HTTP + WebSocket)
shutdown_timeout 10.0 Graceful close during shutdown

Pounce never enables compression from configuration alone. It parses every Sec-WebSocket-Extensions offer, negotiates permessage-deflateand its window/context parameters through wsproto, and echoes only the agreed response. A client that does not offer the extension receives no Sec-WebSocket-Extensionsresponse and all outgoing frames remain uncompressed. The same rule applies to HTTP/1.1 Upgrade and RFC 8441 WebSocket over HTTP/2.

See Also