From 9030c4843a62fca20101af84c2adaf967b9b7686 Mon Sep 17 00:00:00 2001 From: Joep Meindertsma Date: Fri, 25 Sep 2026 03:27:30 +0000 Subject: [PATCH] Move the server-only v2 frame codecs into a test helper encodeAuthOk, encodeError, encodeCommitOk(Slim), encodeChallenge, encodeSyncResend and decodeHelloCaps are frames only a server sends or reads. The browser client never calls them; only the tests do, to play the server. They now live in browser/lib/src/test-ws-v2-server.ts, and ws-v2.ts keeps only what the client uses. --- browser/lib/src/test-ws-v2-server.ts | 112 +++++++++++++++++++++++++++ browser/lib/src/websockets.test.ts | 12 +-- browser/lib/src/ws-v2.test.ts | 16 ++-- browser/lib/src/ws-v2.ts | 101 +----------------------- 4 files changed, 132 insertions(+), 109 deletions(-) create mode 100644 browser/lib/src/test-ws-v2-server.ts diff --git a/browser/lib/src/test-ws-v2-server.ts b/browser/lib/src/test-ws-v2-server.ts new file mode 100644 index 0000000000..1975182111 --- /dev/null +++ b/browser/lib/src/test-ws-v2-server.ts @@ -0,0 +1,112 @@ +/** + * The server's half of the v2 WebSocket codec, for tests only. + * + * The browser never sends AUTH_OK, ERROR, COMMIT_OK, CHALLENGE or SYNC_RESEND + * and never reads another client's HELLO capabilities, so these live outside + * `ws-v2.ts` and stay out of the shipped bundle. The tests use them to play + * the server against `WSClient`, and `ws-v2.test.ts` pins them to the golden + * vectors shared with `lib/src/sync/protocol.rs`. + */ +import { Tag } from './ws-v2.js'; + +const encoder = new TextEncoder(); +const decoder = new TextDecoder(); + +function writeU16(buf: Uint8Array, offset: number, value: number): void { + buf[offset] = (value >> 8) & 0xff; + buf[offset + 1] = value & 0xff; +} + +function readU16(buf: Uint8Array, offset: number): [number, number] { + return [(buf[offset] << 8) | buf[offset + 1], offset + 2]; +} + +/** AUTH_OK: `[0x02] [caps_json_utf8]?` — the payload is omitted for an empty + * list, as the pre-2026-09 server did. */ +export function encodeAuthOk(caps: readonly string[]): Uint8Array { + const payload = + caps.length > 0 ? encoder.encode(JSON.stringify(caps)) : new Uint8Array(0); + const buf = new Uint8Array(1 + payload.length); + buf[0] = Tag.AUTH_OK; + buf.set(payload, 1); + + return buf; +} + +/** ERROR: `[0x03] [request_id: u16] [code: u16] [message_utf8]`. */ +export function encodeError( + requestId: number, + code: number, + message: string, +): Uint8Array { + const messageBytes = encoder.encode(message); + const buf = new Uint8Array(5 + messageBytes.length); + buf[0] = Tag.ERROR; + writeU16(buf, 1, requestId); + writeU16(buf, 3, code); + buf.set(messageBytes, 5); + + return buf; +} + +/** COMMIT_OK, legacy full form: `[0x14] [request_id: u16] [commit_json]`. */ +export function encodeCommitOk( + requestId: number, + commitJson: string, +): Uint8Array { + const payload = encoder.encode(commitJson); + const buf = new Uint8Array(3 + payload.length); + buf[0] = Tag.COMMIT_OK; + writeU16(buf, 1, requestId); + buf.set(payload, 3); + + return buf; +} + +/** COMMIT_OK, slim form: `[0x14] [request_id: u16] [commit_id_utf8]`. What + * a server sends a client whose HELLO listed `commit-ok-slim`. */ +export function encodeCommitOkSlim( + requestId: number, + commitId: string, +): Uint8Array { + return encodeCommitOk(requestId, commitId); +} + +/** CHALLENGE: `[0x42] [nonce_utf8]`. */ +export function encodeChallenge(nonce: string): Uint8Array { + const payload = encoder.encode(nonce); + const buf = new Uint8Array(1 + payload.length); + buf[0] = Tag.CHALLENGE; + buf.set(payload, 1); + + return buf; +} + +/** SYNC_RESEND: `[0x38] [drive_utf8]`. */ +export function encodeSyncResend(drive: string): Uint8Array { + const payload = encoder.encode(drive); + const buf = new Uint8Array(1 + payload.length); + buf[0] = Tag.SYNC_RESEND; + buf.set(payload, 1); + + return buf; +} + +/** The capability names after the display name in a HELLO payload (after + * the tag byte). Empty for a malformed frame or a peer that sent none. */ +export function decodeHelloCaps(data: Uint8Array): string[] { + if (data.length < 2) return []; + const [len, off] = readU16(data, 0); + const rest = data.subarray(off + len); + if (rest.length === 0) return []; + + try { + const parsed = JSON.parse(decoder.decode(rest)); + + return Array.isArray(parsed) + ? parsed.filter((c): c is string => typeof c === 'string') + : []; + } catch { + return []; + } +} diff --git a/browser/lib/src/websockets.test.ts b/browser/lib/src/websockets.test.ts index de5a2d9248..0dff6f6917 100644 --- a/browser/lib/src/websockets.test.ts +++ b/browser/lib/src/websockets.test.ts @@ -8,18 +8,20 @@ import { ErrorCode, CLIENT_CAPABILITIES, decodeCommit, + encodeEphemeral, + decodeEphemeral, + EphemeralKind, + Flags, +} from './ws-v2.js'; +import { decodeHelloCaps, encodeChallenge, encodeCommitOkSlim, encodeSyncResend, - encodeEphemeral, - decodeEphemeral, - EphemeralKind, encodeCommitOk, encodeError, encodeAuthOk, - Flags, -} from './ws-v2.js'; +} from './test-ws-v2-server.js'; import { LoroLoader } from './loro-loader.js'; import type { Commit } from './commit.js'; import { serializeDeterministically } from './commit.js'; diff --git a/browser/lib/src/ws-v2.test.ts b/browser/lib/src/ws-v2.test.ts index 5d237e98ec..a272a88183 100644 --- a/browser/lib/src/ws-v2.test.ts +++ b/browser/lib/src/ws-v2.test.ts @@ -61,12 +61,6 @@ import { decodeChallenge, decodeCommit, decodeCommitOk, - decodeHelloCaps, - encodeAuthOk, - encodeChallenge, - encodeCommitOk, - encodeCommitOkSlim, - encodeError, encodeHello, decodeGet, decodeGetMany, @@ -76,7 +70,6 @@ import { decodeSyncDiff, decodeSyncOk, decodeSyncResend, - encodeSyncResend, decodeEphemeral, encodeEphemeral, EphemeralKind, @@ -96,6 +89,15 @@ import { encodeUnsub, Flags, } from './ws-v2.js'; +import { + decodeHelloCaps, + encodeAuthOk, + encodeChallenge, + encodeCommitOk, + encodeCommitOkSlim, + encodeError, + encodeSyncResend, +} from './test-ws-v2-server.js'; const vectors: Record = Object.fromEntries( ( diff --git a/browser/lib/src/ws-v2.ts b/browser/lib/src/ws-v2.ts index e6f8623bcb..6323236a21 100644 --- a/browser/lib/src/ws-v2.ts +++ b/browser/lib/src/ws-v2.ts @@ -248,92 +248,10 @@ export function encodeHello(name: string, caps: readonly string[]): Uint8Array { return buf; } -/** The capability names after the display name in a HELLO payload (after - * the tag byte). Empty for a malformed frame or a peer that sent none. */ -export function decodeHelloCaps(data: Uint8Array): string[] { - if (data.length < 2) return []; - const [len, off] = readU16(data, 0); - const rest = data.subarray(off + len); - if (rest.length === 0) return []; - - try { - const parsed = JSON.parse(decoder.decode(rest)); - - return Array.isArray(parsed) - ? parsed.filter((c): c is string => typeof c === 'string') - : []; - } catch { - return []; - } -} - -// ---- Server-sent frames ---- -// -// The browser never sends these; the encoders exist so the tests can play -// the server against the client, and so the golden vectors pin them on this -// side too. - -/** AUTH_OK: `[0x02] [caps_json_utf8]?` — the payload is omitted for an empty - * list, as the pre-2026-09 server did. */ -export function encodeAuthOk(caps: readonly string[]): Uint8Array { - const payload = - caps.length > 0 ? encoder.encode(JSON.stringify(caps)) : new Uint8Array(0); - const buf = new Uint8Array(1 + payload.length); - buf[0] = Tag.AUTH_OK; - buf.set(payload, 1); - - return buf; -} - -/** ERROR: `[0x03] [request_id: u16] [code: u16] [message_utf8]`. */ -export function encodeError( - requestId: number, - code: number, - message: string, -): Uint8Array { - const messageBytes = encoder.encode(message); - const buf = new Uint8Array(5 + messageBytes.length); - buf[0] = Tag.ERROR; - writeU16(buf, 1, requestId); - writeU16(buf, 3, code); - buf.set(messageBytes, 5); - - return buf; -} - -/** COMMIT_OK, legacy full form: `[0x14] [request_id: u16] [commit_json]`. */ -export function encodeCommitOk( - requestId: number, - commitJson: string, -): Uint8Array { - const payload = encoder.encode(commitJson); - const buf = new Uint8Array(3 + payload.length); - buf[0] = Tag.COMMIT_OK; - writeU16(buf, 1, requestId); - buf.set(payload, 3); - - return buf; -} - -/** COMMIT_OK, slim form: `[0x14] [request_id: u16] [commit_id_utf8]`. What - * a server sends a client whose HELLO listed `commit-ok-slim`. */ -export function encodeCommitOkSlim( - requestId: number, - commitId: string, -): Uint8Array { - return encodeCommitOk(requestId, commitId); -} - -/** CHALLENGE: `[0x42] [nonce_utf8]`. The server sends this; the encoder - * exists for tests and symmetry with the Rust codec. */ -export function encodeChallenge(nonce: string): Uint8Array { - const payload = encoder.encode(nonce); - const buf = new Uint8Array(1 + payload.length); - buf[0] = Tag.CHALLENGE; - buf.set(payload, 1); - - return buf; -} +// The encoders for frames only a server sends (AUTH_OK, ERROR, COMMIT_OK, +// CHALLENGE, SYNC_RESEND) and the HELLO capability decoder live in +// `test-ws-v2-server.ts`: the tests use them to play the server, and the +// shipped bundle does not need them. /** The nonce in a CHALLENGE payload (after the tag byte); `undefined` when * empty. */ @@ -924,17 +842,6 @@ export function decodeSyncResend(data: Uint8Array): string | undefined { return decoder.decode(data); } -/** SYNC_RESEND: `[0x38] [drive_utf8]`. Server-sent; the encoder is for - * tests and symmetry with the Rust codec. */ -export function encodeSyncResend(drive: string): Uint8Array { - const payload = encoder.encode(drive); - const buf = new Uint8Array(1 + payload.length); - buf[0] = Tag.SYNC_RESEND; - buf.set(payload, 1); - - return buf; -} - /** The `kind` byte of an EPHEMERAL frame (`protocol::ephemeral_kind`): which * live-collaboration channel it belongs to. */ export const EphemeralKind = {