Protocol
The messages between one client and the server, and the one thing Twinstate requires of the connections that carry them.
The transport contract
For each client, a single, ordered, reliable, two-way stream carrying both requests and broadcasts.
This is a requirement, not a preference. The guarantee that a mutation's reply arrives after the broadcast containing its result — which is what makes confirmations flicker-free — depends on replies and broadcasts sharing one ordered stream. A design that sends mutations over HTTP and broadcasts over a WebSocket loses that ordering (Replicache, which works that way, has to carry confirmations inside its pull responses instead).
The two ends see the contract differently: a client has one connection; the server has one per client.
ts
interface ClientTransport {
send(frame: Frame): void; // in order
onFrame(listener: (frame: Frame) => void): void;
onOpen(listener: () => void): void;
onClose(listener: () => void): void;
stop(): void; // close and stop reconnecting: called when a tab stops: `incompatible` (its hello, or a record it cannot parse — not a single refused subscribe or mutate), `outdated`, or `protocolError`
}
interface ServerTransport {
onConnection(listener: (conn: Connection) => void): void;
}
interface Connection {
readonly id: string; // stable for the connection's life
send(frame: Frame): void; // to THIS client, in order
onFrame(listener: (frame: Frame) => void): void; // from this client
onClose(listener: () => void): void;
}Per-connection sends are what let the server reply done to one client only and deliver each topic only to its subscribers. A ClientTransport also owns liveness: reconnecting when the socket drops, heartbeats, and waking on online, pageshow and visibilitychange; the client only reacts to onOpen and onClose. twinstate/ws/server and twinstate/ws/client ship both ends over WebSocket. An application with its own multiplexed socket implements the two interfaces over one of its channels.
twinstate/testing includes a conformance test: it runs any pair of adapters against interleaved requests and broadcasts from several connections and fails if any client sees its frames out of order.
Messages
Every frame carries the protocol version v. Shapes are zod schemas exported from twinstate and validated on receipt at both ends.
Client → server
jsonc
// first frame on every connection: the lock revision this bundle was built with
{ "v": 1, "type": "hello", "revision": 12 }
// subscribe to the always-present state, or to one lazy root
{ "v": 1, "type": "subscribe", "topic": "instant", "since": { "epoch": "mf1b7c0q.a81mz0", "rev": 4815 }, "events": true }
// `events: true` only when re-subscribing a topic this page held when its connection dropped:
// then missed events are replayed with missed changes. A first subscribe (a cache resume,
// a lazy root opened again) omits it, and gets the changes only
{ "v": 1, "type": "subscribe", "topic": { "kind": "noteBody", "id": "n1" }, "since": null }
{ "v": 1, "type": "unsubscribe", "topic": { "kind": "noteBody", "id": "n1" } }
// a live, cursor-paginated window over a kind, or over one parent's children.
// A query topic is identified by kind + params (order, filter, parent); the window is not part of it.
{ "v": 1, "type": "subscribe",
"topic": { "query": "activity", "params": { "order": "at desc" } }, "window": { "first": 50 },
"since": null }
{ "v": 1, "type": "subscribe",
"topic": { "query": "message", "params": { "parent": "c7", "order": "at desc" } }, "window": { "first": 100 },
"since": null }
// load more: widen the same subscription (the server sends the next items after the current end)
{ "v": 1, "type": "window", "topic": { "query": "activity", "params": { "order": "at desc" } },
"window": { "first": 100 } }
// a mutation from the outbox; mutationId increases per clientId
{ "v": 1, "type": "mutate", "clientId": "ipad-1", "mutationId": 42,
"name": "pinNote", "args": { "id": "n1", "pinned": true }, "createdAt": 1790000000000 }
// an outbox that is empty and deleted: the server may forget this client's mutation ids
{ "v": 1, "type": "retire", "clientId": "ipad-1" }Server → client
jsonc
// changes on one topic from one flush (records a lazy root refs are included)
{ "v": 1, "type": "ops", "topic": "instant", "epoch": "mf3k2a1z.k3f9x2", "rev": 4816,
"ops": [
{ "kind": "note", "id": "n1", "patch": [ { "op": "replace", "path": ["title"], "value": "Plans" } ] },
{ "kind": "note", "id": "n8", "set": { "title": "New", "pinned": false, "updatedAt": "…" } }, // created
{ "kind": "note", "id": "n7", "del": true }
] }
{ "v": 1, "type": "ops", "topic": { "kind": "reply", "id": "r9" }, "epoch": "mf3k2a1z.k3f9x2", "rev": 4817,
"ops": [ { "kind": "reply", "id": "r9", "field": "text", "append": " next words", "at": 1842 } ] }
// a reset for a root that does not exist yet (created offline, create still in flight)
{ "v": 1, "type": "ops", "topic": { "kind": "noteBody", "id": "n9" }, "epoch": "mf3k2a1z.k3f9x2", "rev": 4818,
"reset": true, "absent": true, "ops": [] }
// a reset: the full contents of a topic, replacing whatever the client held
{ "v": 1, "type": "ops", "topic": "instant", "epoch": "mf3k2a1z.k3f9x2", "rev": 4816, "reset": true,
"ops": [ /* every record, as sets */ ] }
// events travel inside a topic's message, after its ops, and are kept in its ring like
// changes: a reconnect's resume (`events: true`) replays the missed ones still in the ring
// and younger than their maxAge; a first subscribe or a reset replays none.
// Each id (the epoch and a server-wide counter) lets one tab per device claim it
{ "v": 1, "type": "ops", "topic": "instant", "epoch": "mf3k2a1z.k3f9x2", "rev": 4819,
"ops": [ /* … */ ],
"events": [ { "id": "mf3k2a1z.k3f9x2:118", "name": "notice", "at": 1790000000900, "payload": { /* … */ } } ] }
// the answer to a compatible hello (the server's epoch): the client may now claim its device
// and re-subscribe
{ "v": 1, "type": "ready", "epoch": "mf3k2a1z.k3f9x2" }
// the answer to a hello whose revision cannot read what this server sends (or whose
// arguments it cannot accept), or a v it does not speak; nothing else is sent on that
// connection, and the app decides what to do (Twinstate never reloads)
{ "v": 1, "type": "incompatible", "revision": 14 }
// reserved, so refusing single kinds or mutations can come later without a protocol change:
// the same answer to one subscribe or one mutate, the connection staying open
{ "v": 1, "type": "incompatible", "revision": 14, "topic": { "kind": "noteBody", "id": "n1" } }
{ "v": 1, "type": "incompatible", "revision": 14, "clientId": "ipad-1", "mutationId": 44 }
// a frame the server cannot act on: malformed, naming a kind, mutation or query it does
// not have, or a window its query does not declare. The server then closes the
// connection, and the client calls its transport's stop() — no reconnect — and reports
// `protocolError` through useSyncStatus(), since a reconnect would only send the same
// frame again (a reload does too: it is a bug to fix, not a state to recover from). A compatible
// client never sends one (the lock covers everything it can send): it means a bug, in a
// transport or a hand-written client
{ "v": 1, "type": "protocolError", "detail": "window: order 'title asc' not declared" }
// the reply to one mutation, always after the ops carrying its result; it names the
// clientId because one connection can send for several outboxes (adopted from closed tabs)
{ "v": 1, "type": "done", "clientId": "ipad-1", "mutationId": 42, "result": "ok" }
{ "v": 1, "type": "done", "clientId": "ipad-1", "mutationId": 43, "result": "rejected", "reason": "invalid", "detail": "title: empty" }
// a handler threw something that is not a declared rejection: no detail leaves the server
{ "v": 1, "type": "done", "clientId": "ipad-1", "mutationId": 45, "result": "rejected", "reason": "error" }A server shutting down sends nothing special: the socket closes, and the client reconnects as it would after any drop, resuming every topic from its position.
Positions
A client keeps one position per topic: the (epoch, rev) of the last message it applied on that topic. rev is one server-wide counter (so changes on different topics can be ordered against each other), but each topic is resumed from its own position. Revisions are only compared within an epoch; a different epoch always means reset. An epoch is <boot time, base 36 milliseconds>.<random>: the server treats it as opaque, and only a client's persisted cache reads the time prefix, to keep the newer of two saved copies. See the server.
Versioning
v versions Twinstate's own frames and changes only when their shapes do. A client whose v the server does not speak is answered incompatible. There is no support for mixed protocol versions.
The registry — your kinds, mutations and events — is versioned by the lock: a client sends the lock revision its bundle was built with, and the server answers incompatible only if that revision cannot read what the server sends, or sends arguments the server no longer accepts. Additive changes leave older clients connected (see running clients). On incompatible, the client stays disconnected and reports it; whether to reload, and when, is the app's decision (onIncompatible, see the client). Outbox entries an older bundle wrote are checked by the client, strictly, after an upgrade, before they are sent (see the client). Old data on the server's disk is the one thing that is migrated (see changing a schema).