Skip to navigation
Reference

Connection and authentication

View as Markdown

Use WSS with JSON text frames. The endpoint and permitted account scopes are supplied through arranged access.

server → hello
client → authenticate
client → subscribe
server → subscribed
server → matching batches → checkpoint → caught_up
server → live batches / checkpoints
client → ack after committing the checkpoint locally

There can be zero matching batches at the fixed cut. Checkpoint and caught_up still complete the catch-up phase. V1 has no authenticated frame.

Authentication and deadlines

authenticate.ticket contains the API key in JSON, never in a URL. Authenticate within hello.limits.authTimeoutMs, then subscribe within subscribeTimeoutMs. Stop frequent retries when access is rejected.

Client frames require version: 1 and the appropriate kind. Unknown fields in frames, filters and start objects are rejected. start must explicitly select live_cut or resume; it cannot be null.

Client IDs are 1–128 ASCII characters: letters, digits, ., :, _, -. Ticket and token values are 1–2048 ASCII characters: letters, digits, ., _, -. Their syntax does not establish credential validity. Copy issued values unchanged.

Sequence and heartbeat

Every server application frame has a decimal-string frameSequence. Hello starts at "1"; subsequent values increase by one. Reconnect creates a new sequence and connection ID.

Heartbeat uses native client WebSocket Ping and server Pong, echoing the Ping payload. These are not JSON ping messages and do not consume frame sequences. serverPingIntervalMs is null; it does not promise automatic server pings.

The implementation caps client frames at 262144 bytes and server frames at 20971520 bytes. These are shape/size bounds, not throughput guarantees or recommended frame sizes. Apply current account and runtime limits as well.

Keep TLS certificate validation enabled. After transport failure, preserve the committed checkpoint and follow recovery. Exact message definitions are in frames.