WebSocket Protocol

Use this page when building custom realtime clients, validating subscription event handling, or debugging stream behavior.

• Endpoint: ws://<host>:8080/v1/ws
• Transport: RFC 6455 WebSocket
• Encoding: JSON text frames, optional gzip-compressed binary frames from server

Connection and authentication

HTTP upgrade

Client opens GET /v1/ws. Server can reject before upgrade for shutdown state or origin-policy failure.

Post-connect auth (required)

{
  "type": "authenticate",
  "method": "jwt",
  "token": "<JWT_TOKEN>"
}

On success:

{
  "type": "auth_success",
  "user_id": "u_...",
  "role": "Dba"
}

On failure:

{
  "type": "auth_error",
  "message": "Invalid username or password"
}

Client messages

• authenticate
• subscribe
• next_batch
• unsubscribe

Server messages

• auth_success / auth_error
• subscription_ack
• initial_data_batch
• change (insert|update|delete)
• error

Limits and rates

• Max subscriptions per user: rate_limit.max_subscriptions_per_user (default 10)
• Hard cap per connection: 100
• Max incoming size: security.max_ws_message_size (default 1MB)
• Max message rate: rate_limit.max_messages_per_sec (default 50)
• Auth timeout: websocket.auth_timeout_secs (default 3)

For endpoint-level routing and auth matrix, see HTTP API Reference.