Skip to main content

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:

CodeNameDirectionFields (beyond type, documentId)
20helloC→Sauthor, protocolVersion
21welcomeS→CsessionId, snapshot: string|null, changes: string[], seq, logLength, compact, protocolVersion
22pushC→Schanges: string[]
23ackS→Cseq, count, logLength, compact
24changesS→otherschanges: string[], seq, from: string|null
25snapshotUploadC→Ssnapshot, upToSeq
26stateRequestC→S— (reply with a welcome, same sessionId)
5pingC→Stimestamp → reply pong (6) {originalTimestamp, responseTimestamp}
7errorS→Ccode, message
100–102awarenessC↔Spresence 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 protocolVersion with yours. When they differ, send an error (7) with the code UNSUPPORTED_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: its connectionStatus becomes unsupported (see Versions and compatibility).

What the server does​

  • Assign a sessionId per connection, and return it in the welcome.
  • Append pushed blobs to a log per room, with growing sequence numbers.
  • Put the last assigned seq on both the ack and the rebroadcast changes: clients rely on it to bound their snapshot uploads.
  • Serve snapshot + log on hello and on stateRequest.
  • On snapshotUpload, store the snapshot and truncate the log up to upToSeq.
  • 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.

Keep the copies in step

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.