Relay protocol
A relay server never parses CRDT data, so its side of the protocol is just a JSON message contract over a WebSocket. It can be implemented on any runtime, including serverless hosts such as Cloudflare Workers with Durable Objects.
The Greyhound Markdown
app is a concrete example: its client uses WebSocketRelayClient from
crdt_socket_sync, while its server is a Cloudflare Worker in TypeScript
(server/,
run with wrangler): a TypeScript reference implementation of the contract
below.
Messages
Frames are JSON envelopes typed by an integer type code, with documentId
naming the room. CRDT change and snapshot payloads travel as opaque base64
strings. Your server must handle:
| Code | Name | Direction | Fields (beyond type, documentId) |
|---|---|---|---|
| 20 | hello | C→S | author, protocolVersion |
| 21 | welcome | S→C | sessionId, snapshot: string|null, changes: string[], seq, logLength, compact, protocolVersion |
| 22 | push | C→S | changes: string[] |
| 23 | ack | S→C | seq, count, logLength, compact |
| 24 | changes | S→others | changes: string[], seq, from: string|null |
| 25 | snapshotUpload | C→S | snapshot, upToSeq |
| 26 | stateRequest | C→S | — (reply with a welcome, same sessionId) |
| 5 | ping | C→S | timestamp → reply pong (6) {originalTimestamp, responseTimestamp} |
| 7 | error | S→C | code, message |
| 100–102 | awareness | C↔S | presence passthrough: keep the states of the open sessions in memory, and rebroadcast |
The protocol version
protocolVersion is an integer, currently 1. A frame without it is read as
1, the first version.
- On hello, compare the client's
protocolVersionwith yours. When they differ, send an error (7) with the codeUNSUPPORTED_PROTOCOL_VERSION, then close the connection. - On welcome, always send your own
protocolVersion. The client compares it with its own, and stops for good when they differ: itsconnectionStatusbecomesunsupported(see Versions and compatibility).
What the server does
- Assign a
sessionIdper connection, and return it in the welcome. - Append pushed blobs to a log per room, with growing sequence numbers.
- Put the last assigned
seqon both the ack and the rebroadcastchanges: clients rely on it to bound their snapshot uploads. - Serve
snapshot + logon hello and on stateRequest. - On
snapshotUpload, store the snapshot and truncate the log up toupToSeq. - Drive compaction: set
compact: true(rate-limited, one client per room) once the log passes your threshold.
See Relay mode for the flows these messages make.
Hard requirements
- Reply to every ping with a pong. The client treats a missing pong within its ping timeout (default 30 s) as a dead connection, and reconnects.
- Send the welcome within the client's handshake timeout (default 5 s;
set it with
WebSocketRelayClient(handshakeTimeout: ...)for hosts with cold starts).
Also accept binary inbound frames: the Dart client sends UTF-8 JSON as binary
WebSocket frames (decode them as text). Replies may be text frames. With the
default NoCompression, no compression handling is needed. To keep serverless
costs down, lengthen pingInterval / pingTimeout on the client, so idle rooms
are probed less often.
The relay protocol is versioned with the package. A change to it in
crdt_socket_sync has to reach every relay implementation, the TypeScript one
of Greyhound included. The relay checks the protocol version only: see
Versions and compatibility.