Skip to content

WebSocket Proxy

Purpose

Distributed WebSocket proxy service managing outbound connections to external WebSocket servers with auto-reconnection, correlated request-response messaging, pub/sub message routing, and cross-instance ownership with orphan reclamation.

Requirements

Requirement: External WebSocket Connection Lifecycle

The WebSocket Manager SHALL allow clients to connect to arbitrary external WebSocket servers, disconnect from them, and list all managed connections. Connections SHALL persist through service restarts.

Scenario: Connect to external WebSocket

  • WHEN a client requests a connection to a WebSocket URL
  • THEN the manager SHALL create and maintain a ClientWebSocket connection, persist the connection metadata to the Dapr state store, and return a unique connection ID

Scenario: List all connections

  • WHEN a client lists connections
  • THEN the manager SHALL return all active connections with their IDs, URLs, status, and topics

Scenario: Disconnect

  • WHEN a client disconnects a connection
  • THEN the manager SHALL close the WebSocket, cancel its receive loop, and remove connection state from both local and Dapr stores

Requirement: Messaging Modes

The WebSocket Manager SHALL support two correlation modes: Raw (fire-and-forget) and Managed (correlated request-response with JSON envelope).

Scenario: Raw message send

  • WHEN a client sends a raw message to a connection
  • THEN the message SHALL be sent as-is to the WebSocket without correlation tracking

Scenario: Managed request-response

  • WHEN a client sends a message in Managed mode
  • THEN the message SHALL be wrapped in a {"id": "<uuid>", "message": "<payload>"} envelope, and the response with matching id SHALL be returned

Scenario: Managed timeout

  • WHEN a managed request does not receive a correlated response within the configurable timeout
  • THEN a timeout error SHALL be returned to the caller

Requirement: Auto-Reconnection

Connections marked for auto-reconnect SHALL attempt reconnection with exponential backoff when the WebSocket drops.

Scenario: Connection drop with auto-reconnect

  • WHEN a connection with auto_reconnect=true loses its WebSocket
  • THEN the manager SHALL attempt reconnection up to a configurable maximum with exponential backoff (base delay doubling each attempt, capped at a maximum delay)

Scenario: Reconnection success

  • WHEN a reconnection attempt succeeds
  • THEN a new receive loop SHALL start and message delivery SHALL resume

Scenario: Reconnection exhausted

  • WHEN all reconnection attempts fail
  • THEN the connection SHALL transition to Disconnected status

Requirement: Pub/Sub Message Routing

Received WebSocket messages SHALL be forwardable to Dapr pub/sub topics. Each message SHALL include connection metadata in the published envelope.

Scenario: Start publishing

  • WHEN a client calls StartPublish on a connection with a topic name
  • THEN all subsequently received WebSocket messages SHALL be published to that Dapr topic

Scenario: Message envelope

  • WHEN a WebSocket message is published to Dapr
  • THEN the envelope SHALL contain WebsocketId, WebsocketUrl, Timestamp, and Payload

Scenario: Stop publishing

  • WHEN a client calls StopPublish on a connection
  • THEN message forwarding to Dapr SHALL stop

Requirement: Distributed Ownership

Each connection SHALL be owned by exactly one WebSocket Manager instance. Only the owning instance may manipulate a connection.

Scenario: Cross-instance access denied

  • WHEN a request targets a connection owned by a different instance
  • THEN the request SHALL fail with an ownership error

Requirement: Orphaned Connection Reclamation

When an owning instance dies, its connections SHALL be reclaimed by surviving instances after a grace period.

Scenario: Dead instance detection

  • WHEN a connection has been owned by an instance that is no longer known for longer than a configurable grace period
  • THEN a surviving instance SHALL reassign ownership and resume managing the connection

Scenario: Periodic reclamation sweep

  • WHEN the reclamation service runs on its configured interval
  • THEN it SHALL scan all connections in the state store and reclaim any belonging to unknown instances