J3vbandClaude Fable 5
1fe3df7962
* refactor(protocol): retire reserved voice_speakers and member_leave (S-15) Neither type was ever emitted by the server; B2-1 clears them from the schema before the epoch-1 wire fixtures are captured, so the frozen epoch does not carry two dead message types. Client: dropped the dead `ws.on(MEMBER_LEAVE)` / `ws.on(VOICE_SPEAKERS)` dispatcher handlers, the `MemberLeavePayload` type and both `ServerMessage` union members, and the tests that only exercised those WS paths. `removeMember` (member_ban) and `setSpeakers` (LiveKit ActiveSpeakers) stay live and keep their direct unit tests. * test(ws): capture the epoch-1 wire fixtures alpha.4 is the last client on the pre-epoch wire and B2-2 adds a protocol epoch to the auth handshake next, so record what epoch 1 actually looks like while it is still observable. TestEpoch1Fixtures drives eleven journeys through the ws package's in-process hub harness (full migrations, real hub, httptest WebSocket server) and compares each journey's per-connection frame sequence with a transcript under protocol/fixtures/epoch-1/: - fresh-connect, auth-failure, ping - chat-send-fanout, chat-edit-delete, reaction-add-remove - typing, mark-read, dm-send - resume-replay (last_seq + buffer-tier replay burst) - voice-join-e2ee-leave (join, both voice_state forms, announce and offer relay, leave) Volatile values are replaced by typed placeholders before both writing and comparison -- any key that is id/seq/last_seq, ends in _id (except channel_id and role_id) or _at, is timestamp/ts/last_seen, or contains token, becomes "<class:json-type>" so a field that changes type is still a diff, while everything else is compared verbatim. Regenerate with: go test ./ws -run TestEpoch1Fixtures -update Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(client): pin the epoch-1 auth frame contract Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(updater): pin the epoch-1 manifest and client-update shapes * test(ws): harden the epoch-1 fixtures against trailing frames and absent optionals Every journey now ends with the ping/pong barrier on each recorded connection, so a frame the server emits after the last read fails as `expected "pong", got "X"` instead of going unrecorded; auth-failure asserts the StatusPolicyViolation close instead, its socket being gone. alice carries a display name, avatar, about text, custom status, identity public key and an announce signature (bob carries none), so every optional field is frozen in its present form as well as its absent one — a rename or a retype of display_name or identity_public_key now moves a fixture. The typing journey focuses the channel on "a" before typing: without the subscription registerNow only makes for a focused client, its ping/pong proved nothing about excludeUserID. Comment fixes: the escaped placeholder form MarshalIndent would write, the real (headroom) reason for the raised read limit, a note that bare id and active_channel_id are normalised by design, and a .prettierignore line saying these fixtures are verified by the Go comparison, not by git diff. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(protocol): document the epoch-1 fixtures * docs(protocol): match the epoch-1 wire where the fixtures contradicted the doc - voice_state: note the unsequenced relay-to-joiner form (table row + section) - auth_error: correct the example message and list the real rejection messages - member_join/presence connect example: add the seq both frames actually carry - chat_message.user: document display_name - voice_join reply order: state that the joiner's own voice_state broadcast is not ordered against the other three frames * test(ws): freeze the null forms of auth_ok and member_join user fields buildAuthOK emits display_name/about/custom_status/avatar as always-present nulls, but only alice — who has all four set — ever authenticated on a recorded connection, so the fixtures froze those fields in their populated form alone. A rename, a retype or a dropped null would have moved nothing, on the very frame B2-2 edits. fresh-connect now records bob's handshake too, on a second connection: his auth_ok carries the four nulls, his member_join carries avatar null with display_name and identity_public_key omitted, and alice — idle by then, so her reads stay in hub order — records the same pair as an already-connected observer sees it. In voice-join-e2ee-leave bob answers alice's signed announce with a legacy unsigned one, which freezes the absent form of signature next to her present one. The auth frames the test writes now carry the correlation id the real client stamps on every frame (ws.ts send()); normalisation renders it <id:string>. expectClosed also asserts the close reason ("authentication failed"), not just code 1008 — HP-2 asks for both. Comment precision, no behaviour change: the barrier guarantee now states that pong may overtake a pending LOW-priority frame (writePump) and that no journey is affected because every barrier is sent on an idle connection; the ping-budget ceiling is six connections, not four; the typing journey cites handleChannelFocusV2 rather than registerNow as the subscribe site; resume-replay's b barrier explains why moving it past the resume would be a flake, not a fix; and the header notes that normalisation hides that chat_send_ok.id echoes the request id. The client contract test's cited range for ws.ts's send() call is 441-453, not 441-454. Regenerate with: go test ./ws -run TestEpoch1Fixtures -update Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(protocol): shape-not-value fixture rule, voice_max_video default, auth close code The fixture rule read "a fixture may only change with an epoch bump", which is false for the seeded values the transcripts record verbatim: role permission masks and colours, motd, server_name, voice_max_video, the voice_config preset. A migration that changes a default mask diffs fresh-connect.json, and the README told the author to revert a change that never touched the wire. Split the rule along shape versus value. A key set, a JSON type, a key appearing or disappearing, or per-connection frame order is a protocol change and earns fixtures/epoch-<n+1>/. A seeded default value is a seed change: regenerate in the same PR and read the diff frame by frame. Normalising those values is explicitly not the answer — a placeholder over a mask or over an enum such as voice_config.threshold_mode would hide the drift the fixtures exist to catch. Two wire facts corrected against the fixtures: - voice_max_video on an unconfigured channel is 25, not 0 (migration 004 is DEFAULT 25); the doc listed it among the zero values. - auth_error is followed by a close with code 1008 (policy violation) and reason "authentication failed" (serve.go:128), which the doc left as "closes the connection". Also: voice_speakers moves from discord-parity's "still dead" list to "came off the list" — it was retired earlier on this branch. And Kick says sessions are revoked and sockets drop on the next sweep, which is what ForceLogout does (moderation.go:236); it does not cut sockets. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(protocol): fixture rule covers enum vocabularies; header comment precision Re-check minors from the whole-branch review: a fixed-vocabulary value the client switches on is shape, not a seeded value; drop the false 'new default channel' clause (the seed asserts channel ids); the low-priority frame is presence_update, not connect presence. * docs(plans): record B2-1 evidence for HP-2 (PR #1435, fixture commit SHAs) * docs(protocol): additive changes stay within an epoch; bump only for what old clients cannot process Codex review on #1435: B2-2 keeps protocol_epoch = 1 while adding auth/ready/auth_error fields, which the previous wording would have called a break to revert. An epoch is a compatibility boundary, not a snapshot: additive keys regenerate in the same PR and are documented; removals, renames, retypes, dropped frames and reordering bump the epoch. The plan's B2-1 evidence records the refinement and hands B2-2/B2-4 the open questions (additive-tolerant replay of the epoch-1 transcript; epoch 0 vs 1 naming). * test(client): compare auth-frame key sets order-independently Codex review on #1435: Object.keys preserves insertion order, so a harmless property reorder in ws.ts would fail the pin. Key order has no wire meaning; the Go fixtures already compare with sorted keys. Sort both sides. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
4.2 KiB
protocol/
The cross-component WebSocket contract. It lives at the repository root
because neither side owns it: schema.json is the single source of truth for
the message-type constants both the Go server and the TypeScript client
compile against.
| File | Role |
|---|---|
schema.json |
Source of truth. Every wire message type, both directions |
fixtures/epoch-1/ |
Frozen wire transcripts for protocol epoch 1. Regenerated by the test, never hand-edited |
Two files are generated from it and must never be hand-edited:
Server/ws/message_types.goClient/src/lib/protocolTypes.ts
Changing the protocol
Edit schema.json, then regenerate both consumers with one command from the
repository root:
npm run generate
(Equivalently, make protocol-generate or go run ./cmd/genprotocol from
Server/ — the generator is a Go program, so it lives where the Go toolchain
already runs.)
Three gates reject a stale regeneration and one gate checks the schema against
the constants independently — .githooks/pre-commit, make protocol-verify in
CI, npm run check:server, and Server/ws/protocol_contract_test.go. There is
nothing extra to run.
Fixtures
fixtures/epoch-1/ holds one JSON file per journey (fresh connect, chat send,
voice join, ...). Within a file, each connection has its own list of frames in
order; frames on different connections are not related to each other —
cross-connection interleaving is timing-dependent and is not part of the
contract. Volatile values — ids, seqs, timestamps, tokens, user ids — are
replaced by typed placeholders such as "<id:number>", so a refactor that
keeps the wire shape leaves the file untouched, while a renamed, added or
removed key, or a type change, shows up as a diff.
TestEpoch1Fixtures in Server/ws drives the real server in-process and
compares its output against these files. It runs under go test ./..., so
npm run check:server and the Server Build & Test CI check already cover
it — there is nothing extra to run.
Regenerate with:
go test ./ws -run TestEpoch1Fixtures -update
from Server/, then read the diff frame by frame before committing it.
A fixture's shape may only change deliberately — and an epoch bump is for
what older clients cannot process. Within an epoch, a change an older client
can ignore — a new key, a new optional field — is allowed: regenerate
fixtures/epoch-<n>/ in the same PR, read the diff frame by frame, and
document the addition in docs/protocol.md. A change an older client cannot
process — a key removed, renamed, or retyped, a frame dropped, or the order of
frames on one connection changed — needs a new fixtures/epoch-<n+1>/
directory, with the old one kept as the record of what earlier clients speak.
A diff of that kind in a change that does not bump the epoch is a protocol
break to revert, not a refactor to accept. (Epoch negotiation itself is an
additive change and stays on epoch 1.)
A diff confined to a seeded default value is not a protocol change. The
fixtures record real values wherever they are deterministic — role permission
masks and colours, motd, server_name, a channel's voice_max_video, the
voice_config preset — so a migration that changes a default mask moves a
fixture without touching the wire. Regenerate in the same PR and read the diff
frame by frame. Normalising those values away is not
the answer: a placeholder over a mask or over an enum such as
voice_config.threshold_mode would hide exactly the drift these files exist to
catch.
A value drawn from a fixed vocabulary the client switches on — threshold_mode,
quality, status, replay_source, a channel type — is shape, not a seeded
value: renaming or dropping a member of it is a protocol change even though
only a value moved.
The narrative protocol reference is docs/protocol.md;
the blueprint is docs/architecture/websocket.md.