Skip to content
ChronactaChronactaChronacta Docs

WebSocket API (v2)

Enable with CHRONACTA_WS_ENABLED=true (listen address CHRONACTA_WS_ADDRESS, default 127.0.0.1:8082).

WebSocket routes mirror gRPC subscribe/read-all semantics. Paths are listed in pkg/openapi/grpc-http-map.yaml under websocket:.

Authentication

Section titled “Authentication”

Pass the same bearer token as gRPC via the Authorization header during the WebSocket upgrade. Query-string tokens are rejected unless CHRONACTA_WS_ALLOW_QUERY_TOKEN=true.

Endpoints

Section titled “Endpoints”
Path Purpose
GET /v1/ws/streams/{id} Live tail for one stream (maps to Subscribe)
GET /v1/ws/all Global tail via polling ReadAll ($all)

Each message is a JSON-encoded event object (same fields as gRPC/protobuf JSON).

Backpressure

Section titled “Backpressure”

Outbound messages are queued per connection (SendBuffer in wsgateway.Config, default 64). When the queue is full the gateway closes the tail with {"error":"websocket send buffer full"} instead of blocking the gRPC reader.

Example

Section titled “Example”
Terminal window
websocat -H="Authorization: Bearer $TOKEN" \
  ws://127.0.0.1:8082/v1/ws/streams/orders

Integration tests: pkg/wsgateway/integration_test.go.

Durable pull subscriptions remain on gRPC; see subscriptions.md.