Message Design and Serialization

// browser: offer v2 first, fall back to v1; the server answers with exactly one of them
const ws = new WebSocket("wss://chat.example.test/ws", ["chatterbox.v2", "chatterbox.v1"]);
ws.onopen = () => console.log("negotiated", ws.protocol); // "chatterbox.v1" or "chatterbox.v2"

{
  "v": 1, "type": "hello", "id": "01JAB3W6A1B2C3D4E5F6G7H8J9", "room": null, "ts": 0,
  "payload": {
    "token": "ticket-change-me",
    "client": "web/1.4",
    "resume": { "sessionId": "sess_01JAB3V0000000000000000000", "rooms": {"general":41} }
  }
}

{
  "v": 1, "type": "hello", "id": "s_01JAB3W7QA0000000000000000", "room": null, "ts": 1761300000000,
  "payload": {
    "ref": "01JAB3W6A1B2C3D4E5F6G7H8J9",
    "userId": "alice",
    "name": "Alice",
    "sessionId": "sess_01JAB3V0000000000000000000",
    "heartbeatMs": 20000,
    "maxFrameBytes": 16384,
    "resumed": true,
    "rooms": ["general"]
  }
}

{
  "v": 1, "type": "join", "id": "01JAB3W6B1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": { "since": 41 }
}

{
  "v": 1, "type": "leave", "id": "01JAB3W6C1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": {  }
}

{
  "v": 1, "type": "message", "id": "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", "room": "general", "ts": 0,
  "payload": {
    "text": "Hello, Chatterbox",
    "replyTo": null,
    "attachments": [
      {
        "url": "https://chat.example.test/files/menu.pdf",
        "name": "menu.pdf",
        "mime": "application/pdf",
        "size": 48213
      }
    ]
  }
}

{
  "v": 1, "type": "message", "id": "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", "room": "general", "ts": 1761300000000,
  "payload": {
    "from": { "userId": "alice", "name": "Alice" },
    "text": "Hello, Chatterbox",
    "replyTo": null,
    "attachments": [
      {
        "url": "https://chat.example.test/files/menu.pdf",
        "name": "menu.pdf",
        "mime": "application/pdf",
        "size": 48213
      }
    ],
    "seq": 42,
    "edited": false
  }
}

{
  "v": 1, "type": "edit", "id": "01JAB3WAE1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": { "target": "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", "text": "Hello, Chatterbox!" }
}

{
  "v": 1, "type": "edit", "id": "s_01JAB3W7QB0000000000000000", "room": "general", "ts": 1761300005000,
  "payload": {
    "target": "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA",
    "text": "Hello, Chatterbox!",
    "seq": 43,
    "editedAt": 1761300005000
  }
}

{
  "v": 1, "type": "react", "id": "01JAB3WAF1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": { "target": "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", "emoji": "👍", "op": "add" }
}

{
  "v": 1, "type": "react", "id": "s_01JAB3W7QC0000000000000000", "room": "general", "ts": 1761300006000,
  "payload": {
    "target": "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA",
    "emoji": "👍",
    "op": "add",
    "from": { "userId": "bob" },
    "seq": 44
  }
}

{
  "v": 1, "type": "typing", "id": "01JAB3WAG1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": { "state": "start" }
}

{
  "v": 1, "type": "typing", "id": "s_01JAB3W7QD0000000000000000", "room": "general", "ts": 1761300007000,
  "payload": { "userId": "bob", "state": "start" }
}

{
  "v": 1, "type": "receipt", "id": "01JAB3WAH1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": { "kind": "read", "upTo": 44 }
}

{
  "v": 1, "type": "receipt", "id": "s_01JAB3W7QE0000000000000000", "room": "general", "ts": 1761300008000,
  "payload": { "userId": "bob", "kind": "read", "upTo": 44 }
}

{
  "v": 1, "type": "presence", "id": "01JAB3WAJ1B2C3D4E5F6G7H8J9", "room": null, "ts": 0,
  "payload": { "status": "away" }
}

{
  "v": 1, "type": "presence", "id": "s_01JAB3W7QF0000000000000000", "room": "general", "ts": 1761300009000,
  "payload": { "userId": "alice", "name": "Alice", "status": "away" }
}

{
  "v": 1, "type": "history", "id": "01JAB3WAK1B2C3D4E5F6G7H8J9", "room": "general", "ts": 0,
  "payload": { "before": 42, "limit": 2 }
}

{
  "v": 1, "type": "ack", "id": "s_01JAB3W7QJ0000000000000000", "room": "general", "ts": 1761300013000,
  "payload": {
    "ref": "01JAB3WAK1B2C3D4E5F6G7H8J9",
    "ok": true,
    "seq": null,
    "dup": false,
    "result": {
      "messages": [
        {
          "v": 1,
          "type": "message",
          "id": "01JAB3W9D2F6G8H0J1K3M5N7P9",
          "room": "general",
          "ts": 1761299940000,
          "payload": {
            "from": { "userId": "bob", "name": "Bob" },
            "text": "Morning!",
            "replyTo": null,
            "attachments": [],
            "seq": 40,
            "edited": false
          }
        }
      ],
      "hasMore": true,
      "next": 40
    }
  }
}

/** A Lamport clock: a counter that never goes backwards and jumps ahead of anything it has seen. */
export class LamportClock {
  private time = 0;
  /** Call before sending: advances the clock and returns the timestamp to attach. */
  tick(): number { return ++this.time; }
  /** Call on receive: move past the sender's timestamp so causality is preserved. */
  observe(remote: number): number { this.time = Math.max(this.time, remote) + 1; return this.time; }
}

// Alice writes, Bob answers after reading it, Carol writes without having seen either.
const alice = new LamportClock(), bob = new LamportClock(), carol = new LamportClock();
const a1 = alice.tick();          // 1: "Shall we ship?"
bob.observe(a1);                  // Bob's clock becomes 2
const b1 = bob.tick();            // 3: "Yes" (a reply: causally after a1)
const c1 = carol.tick();          // 1: concurrent with a1, unrelated to the other two
console.log({ a1, b1, c1 });
if (!(a1 < b1)) throw new Error("a reply must carry a larger Lamport timestamp than its cause");
// Equal or unordered stamps are concurrent: break ties with (timestamp, userId) to get one total order everyone agrees on.
const order = [{ t: a1, u: "alice" }, { t: b1, u: "bob" }, { t: c1, u: "carol" }]
  .sort((x, y) => x.t - y.t || x.u.localeCompare(y.u)).map((e) => `${e.t}:${e.u}`);
console.log(order.join(" < "));

import { readFileSync } from "node:fs";
import { deflateRawSync } from "node:zlib";
import { encode as mpEncode, decode as mpDecode } from "@msgpack/msgpack";
import protobuf from "protobufjs";

const root = protobuf.parse(readFileSync(new URL("./chatterbox.proto", import.meta.url), "utf8"), { keepCase: false }).root;
const Envelope = root.lookupType("chatterbox.v1.Envelope");

const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
// ---- the same logical messages in every encoding
const ID = "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA";
const T0 = 1761300000000;
const long = "The kitchen team confirmed the new menu: starters at 12:00, mains at 13:30, dessert and coffee at 15:00. " +
  "Vegetarian and vegan options are marked with a leaf, allergens are listed per dish, and the printed copies arrive tomorrow morning. " +
  "Please react with a thumbs up when you have read this so that we can close the thread before the end of the day.";
const msg = (text: string, seq: number, id = ID, ts = T0) => ({
  v: 1, type: "message", id, room: "general", ts,
  payload: { from: { userId: "alice", name: "Alice" }, text, replyTo: null, attachments: [], seq, edited: false },
});
// deterministic pseudo-random chat text so the history page is not unrealistically repetitive
let seed = 7;
const rnd = () => (seed = (seed * 1103515245 + 12345) % 2147483648) / 2147483648;
const words = "lunch meeting tomorrow deploy staging release fixed review thanks coffee later build green failing retry cache design ticket sprint demo budget invoice train late sorry done agreed maybe monday".split(" ");
const chatter = (i: number) => Array.from({ length: 3 + Math.floor(rnd() * (i % 5 === 0 ? 22 : 9)) }, () => words[Math.floor(rnd() * words.length)]).join(" ");
const historyId = (i: number) => "01JAB3W7Q8" + Array.from({ length: 16 }, () => CROCKFORD[Math.floor(rnd() * 32)]).join("");
const samples: Record<string, any> = {
  "message, 17 characters": msg("Hello, Chatterbox", 42),
  [`message, ${long.length} characters`]: msg(long, 42),
  "typing start": { v: 1, type: "typing", id: "s_01JAB3W7QD".padEnd(28, "0"), room: "general", ts: T0, payload: { userId: "bob", state: "start" } },
  "ack": { v: 1, type: "ack", id: "s_01JAB3W7QG".padEnd(28, "0"), room: "general", ts: T0, payload: { ref: ID, ok: true, seq: 42, dup: false, result: {} } },
  "history page, 50 messages": {
    v: 1, type: "ack", id: "s_01JAB3W7QJ".padEnd(28, "0"), room: "general", ts: T0,
    payload: { ref: ID, ok: true, seq: null, dup: false, result: {
      messages: Array.from({ length: 50 }, (_, i) => msg(chatter(i), 100 + i, historyId(i), T0 - (50 - i) * 41000)),
      hasMore: true, next: 100 } },
  },
};

// ---- protobuf mapping (a real implementation would generate this with protoc / ts-proto)
function toProto(f: any): any {
  const base = { v: f.v, id: f.id, room: f.room ?? "", ts: f.ts };
  const p = f.payload;
  switch (f.type) {
    case "message": return { ...base, message: { text: p.text, from: { userId: p.from.userId, name: p.from.name }, seq: p.seq, edited: p.edited, attachments: p.attachments } };
    case "typing": return { ...base, typing: { start: p.state === "start", userId: p.userId } };
    case "ack": return { ...base, ack: { ref: p.ref, seq: p.seq ?? undefined, dup: p.dup, historyMessages: p.result.messages?.map(toProto), hasMore: p.result.hasMore ?? false, next: p.result.next } };
  }
}

// ---- hand-packed binary with DataView (fixed layout, no field names, no extensibility)
function ulidBytes(id: string): Uint8Array {
  const body = id.replace(/^s_/, "");
  let n = 0n;
  for (const ch of body) n = (n << 5n) | BigInt(CROCKFORD.indexOf(ch));
  const out = new Uint8Array(16);
  for (let i = 15; i >= 0; i--) { out[i] = Number(n & 0xffn); n >>= 8n; }
  return out;
}
const enc = new TextEncoder();
const dec = new TextDecoder();
const TYPE_CODE = { hello: 1, join: 2, leave: 3, message: 4, edit: 5, react: 6, typing: 7, receipt: 8, presence: 9, history: 10, ack: 11, error: 12 } as const;

class Writer {
  buf = new Uint8Array(65536); view = new DataView(this.buf.buffer); pos = 0;
  u8(v: number) { this.view.setUint8(this.pos, v); this.pos += 1; }
  u16(v: number) { this.view.setUint16(this.pos, v); this.pos += 2; }
  u32(v: number) { this.view.setUint32(this.pos, v); this.pos += 4; }
  f64(v: number) { this.view.setFloat64(this.pos, v); this.pos += 8; }
  bytes(b: Uint8Array) { this.buf.set(b, this.pos); this.pos += b.length; }
  str8(s: string) { const b = enc.encode(s); this.u8(b.length); this.bytes(b); }
  str16(s: string) { const b = enc.encode(s); this.u16(b.length); this.bytes(b); }
  done() { return this.buf.slice(0, this.pos); }
}
function packFrame(w: Writer, f: any): void {
  w.u8(f.v); w.u8(TYPE_CODE[f.type as keyof typeof TYPE_CODE]);
  w.bytes(ulidBytes(f.id));
  w.str8(f.room ?? ""); w.f64(f.ts);
  const p = f.payload;
  if (f.type === "message") { w.str8(p.from.userId); w.str8(p.from.name); w.u32(p.seq); w.u8(p.edited ? 1 : 0); w.u8(p.replyTo ? 1 : 0); w.u8(p.attachments.length); w.str16(p.text); }
  else if (f.type === "typing") { w.str8(p.userId); w.u8(p.state === "start" ? 1 : 0); }
  else if (f.type === "ack") {
    w.bytes(ulidBytes(p.ref)); w.u8((p.ok ? 1 : 0) | (p.dup ? 2 : 0)); w.u32(p.seq ?? 0);
    const msgs = p.result.messages;
    if (msgs) { w.u16(msgs.length); for (const m of msgs) packFrame(w, m); w.u32(p.result.next ?? 0); w.u8(p.result.hasMore ? 1 : 0); } else w.u16(0);
  }
}
function unpackMessageText(bin: Uint8Array): string { // enough of a decoder to prove the layout round-trips
  const v = new DataView(bin.buffer, bin.byteOffset, bin.byteLength);
  let pos = 2 + 16; pos += 1 + v.getUint8(pos); pos += 8;
  pos += 1 + v.getUint8(pos); pos += 1 + v.getUint8(pos); pos += 4 + 3;
  const len = v.getUint16(pos);
  return dec.decode(bin.subarray(pos + 2, pos + 2 + len));
}

// ---- measure
const rows: string[][] = [];
const pct = (n: number, base: number) => `${Math.round((n / base) * 100)}%`;
console.log("| Message | Encoding | Bytes | vs JSON | deflate (raw) | vs JSON deflate |");
console.log("|---|---|---:|---:|---:|---:|");
for (const [name, frame] of Object.entries(samples)) {
  const json = new TextEncoder().encode(JSON.stringify(frame));
  const mp = mpEncode(frame);
  const results: [string, Uint8Array][] = [["JSON", json], ["MessagePack", mp]];
  const pf = toProto(frame);
  const pb = Envelope.encode(Envelope.fromObject(pf)).finish();
  results.push(["Protocol Buffers", pb]);
  const w = new Writer(); packFrame(w, frame); const hp = w.done();
  results.push(["Hand-packed DataView", hp]);

  // correctness: every encoding decodes back to the same text
  const text = frame.payload.text ?? null;
  if (text) {
    if ((mpDecode(mp) as any).payload.text !== text) throw new Error("msgpack round trip");
    if ((Envelope.toObject(Envelope.decode(pb), { longs: Number }) as any).message.text !== text) throw new Error("protobuf round trip");
    if (unpackMessageText(hp) !== text) throw new Error("hand-packed round trip");
  }
  const jsonDeflate = deflateRawSync(json).length;
  for (const [enc_, bytes] of results) {
    const d = deflateRawSync(bytes).length;
    console.log(`| ${name} | ${enc_} | ${bytes.length} | ${pct(bytes.length, json.length)} | ${d} | ${pct(d, jsonDeflate)} |`);
  }
}

syntax = "proto3";
package chatterbox.v1;

// The envelope fields v, id, room and ts are the same as in JSON. The "type" field disappears: the
// populated member of the oneof IS the type. An empty room string stands for JSON null.
message Envelope {
  uint32 v = 1;
  string id = 2;
  string room = 3;
  uint64 ts = 4;
  oneof payload {
    Hello hello = 10;
    Join join = 11;
    Leave leave = 12;
    Message message = 13;
    Edit edit = 14;
    React react = 15;
    Typing typing = 16;
    Receipt receipt = 17;
    Presence presence = 18;
    History history = 19;
    Ack ack = 20;
    Error error = 21;
  }
}

message User { string user_id = 1; string name = 2; }
message Attachment { string url = 1; string name = 2; string mime = 3; uint32 size = 4; }

message Hello {
  string token = 1;            // client -> server
  string client = 2;           // client -> server
  string resume_session = 3;   // client -> server
  map<string, uint64> resume_rooms = 4;
  string ref = 5;              // server -> client from here on
  string user_id = 6;
  string name = 7;
  string session_id = 8;
  uint32 heartbeat_ms = 9;
  uint32 max_frame_bytes = 10;
  bool resumed = 11;
  repeated string rooms = 12;
}
message Join { optional uint64 since = 1; }
message Leave {}
message Message {
  string text = 1;
  optional string reply_to = 2;
  repeated Attachment attachments = 3;
  User from = 4;               // server -> client
  uint64 seq = 5;              // server -> client
  bool edited = 6;             // server -> client
}
message Edit { string target = 1; string text = 2; uint64 seq = 3; uint64 edited_at = 4; }
message React { string target = 1; string emoji = 2; bool remove = 3; string from_user_id = 4; uint64 seq = 5; }
message Typing { bool start = 1; string user_id = 2; }
message Receipt { bool read = 1; uint64 up_to = 2; string user_id = 3; }
message Presence { enum Status { ONLINE = 0; AWAY = 1; OFFLINE = 2; } Status status = 1; string user_id = 2; string name = 3; }
message History { optional uint64 before = 1; uint32 limit = 2; }
message Ack {
  string ref = 1;
  optional uint64 seq = 2;
  bool dup = 3;
  repeated Envelope history_messages = 4;   // result of a history request
  bool has_more = 5;
  optional uint64 next = 6;
}
message Error { string ref = 1; string code = 2; string message = 3; bool retryable = 4; }

const buf = new ArrayBuffer(8);
const view = new DataView(buf);
view.setUint32(0, 42);          // big-endian (network order) by default
view.setUint32(4, 42, true);    // little-endian only when the second argument is true
console.log(new Uint8Array(buf)); // Uint8Array(8) [0, 0, 0, 42, 42, 0, 0, 0]

import { z } from "zod";

export const PROTOCOL_VERSION = 1;
export const SUBPROTOCOL = "chatterbox.v1";
export const MAX_FRAME_BYTES = 16384;

// ---------------------------------------------------------------- primitives
export const ROOM_RE = /^[a-z0-9-]{1,64}$/;
const Room = z.string().regex(ROOM_RE);
/** Client ids: UUIDv7 or ULID, 26-36 characters. */
const ClientId = z.string().regex(/^[0-9A-Za-z-]{26,36}$/);
/** Server ids: "s_" followed by a ULID. */
const ServerId = z.string().regex(/^s_[0-9A-HJKMNP-TV-Z]{26}$/);
const Seq = z.int().min(1);
const Text = z.string().min(1).max(4000); // UTF-16 code units, i.e. String.length
const UserId = z.string().min(1).max(64);
const Emoji = z.string().refine((s) => [...new Intl.Segmenter().segment(s)].length === 1, "exactly one grapheme");
const Status = z.enum(["online", "away", "offline"]);

const Attachment = z.object({
  url: z.url().regex(/^https:\/\//),
  name: z.string().min(1).max(255),
  mime: z.string().min(3).max(127),
  size: z.int().min(0),
});

// ---------------------------------------------------------------- envelope factory
function envelope<T extends string, I extends z.ZodType, R extends z.ZodType, P extends z.ZodType>(
  type: T,
  id: I,
  room: R,
  payload: P,
) {
  return z.object({ v: z.literal(PROTOCOL_VERSION), type: z.literal(type), id, room, ts: z.int().min(0), payload });
}
const clientFrame = <T extends string, R extends z.ZodType, P extends z.ZodType>(t: T, room: R, p: P) =>
  envelope(t, ClientId, room, p);
const serverFrame = <T extends string, R extends z.ZodType, P extends z.ZodType>(t: T, room: R, p: P) =>
  envelope(t, ServerId, room, p);

const Empty = z.object({});
const Member = z.object({ userId: UserId, name: z.string(), status: Status });

// ---------------------------------------------------------------- client -> server
export const HelloC = clientFrame("hello", z.null(), z.object({
  token: z.string().min(1).optional(), // omitted when the connection is authenticated by a cookie
  client: z.string().min(1).max(64),
  resume: z.object({ sessionId: z.string().min(1), rooms: z.record(Room, Seq.or(z.literal(0))) }).optional(),
}));
export const Join = clientFrame("join", Room, z.object({ since: Seq.or(z.literal(0)).nullable() }));
export const Leave = clientFrame("leave", Room, Empty);
export const MessageC = clientFrame("message", Room, z.object({
  text: Text,
  replyTo: ClientId.nullable(),
  attachments: z.array(Attachment).max(5),
}));
export const Edit = clientFrame("edit", Room, z.object({ target: ClientId, text: Text }));
export const React = clientFrame("react", Room, z.object({
  target: ClientId,
  emoji: Emoji,
  op: z.enum(["add", "remove"]),
}));
export const TypingC = clientFrame("typing", Room, z.object({ state: z.enum(["start", "stop"]) }));
export const ReceiptC = clientFrame("receipt", Room, z.object({
  kind: z.enum(["delivered", "read"]),
  upTo: Seq,
}));
export const PresenceC = clientFrame("presence", z.null(), z.object({ status: z.enum(["online", "away"]) }));
export const History = clientFrame("history", Room, z.object({
  before: Seq.nullable(),
  limit: z.int().min(1).max(100).default(50),
}));

export const ClientFrame = z.discriminatedUnion("type", [
  HelloC, Join, Leave, MessageC, Edit, React, TypingC, ReceiptC, PresenceC, History,
]);

// ---------------------------------------------------------------- server -> client
export const HelloS = serverFrame("hello", z.null(), z.object({
  ref: ClientId,
  userId: UserId,
  name: z.string(),
  sessionId: z.string().min(1),
  heartbeatMs: z.int().min(1),
  maxFrameBytes: z.int().min(1),
  resumed: z.boolean(),
  rooms: z.array(Room),
}));
// A broadcast message keeps the CLIENT id, because the message id is the envelope id forever.
export const MessageS = clientFrame("message", Room, z.object({
  from: z.object({ userId: UserId, name: z.string() }),
  text: Text,
  replyTo: ClientId.nullable(),
  attachments: z.array(Attachment).max(5),
  seq: Seq,
  edited: z.boolean(),
}));
export const EditS = serverFrame("edit", Room, z.object({
  target: ClientId, text: Text, seq: Seq, editedAt: z.int().min(0),
}));
export const ReactS = serverFrame("react", Room, z.object({
  target: ClientId,
  emoji: Emoji,
  op: z.enum(["add", "remove"]),
  from: z.object({ userId: UserId }),
  seq: Seq,
}));
export const TypingS = serverFrame("typing", Room, z.object({
  userId: UserId, state: z.enum(["start", "stop"]),
}));
export const ReceiptS = serverFrame("receipt", Room, z.object({
  userId: UserId, kind: z.enum(["delivered", "read"]), upTo: Seq,
}));
export const PresenceS = serverFrame("presence", Room, z.object({
  userId: UserId, name: z.string(), status: Status,
}));
export const Ack = serverFrame("ack", Room.nullable(), z.object({
  ref: ClientId,
  ok: z.literal(true),
  seq: Seq.nullable(),
  dup: z.boolean(),
  result: z.record(z.string(), z.unknown()),
}));

/** Error codes with their HTTP-style status and whether a retry with the same id can succeed. */
export const ERROR_CODES = {
  bad_request: { status: 400, retryable: false },
  unauthorized: { status: 401, retryable: false },
  forbidden: { status: 403, retryable: false },
  not_found: { status: 404, retryable: false },
  conflict: { status: 409, retryable: false },
  too_large: { status: 413, retryable: false },
  unsupported_version: { status: 426, retryable: false },
  rate_limited: { status: 429, retryable: true },
  internal: { status: 500, retryable: true },
  unavailable: { status: 503, retryable: true },
} as const;
export type ErrorCode = keyof typeof ERROR_CODES;

export const ErrorFrame = serverFrame("error", Room.nullable(), z.object({
  ref: ClientId.nullable(),
  code: z.enum(Object.keys(ERROR_CODES) as [ErrorCode, ...ErrorCode[]]),
  message: z.string(),
  retryable: z.boolean(),
}));

export const ServerFrame = z.discriminatedUnion("type", [
  HelloS, MessageS, EditS, ReactS, TypingS, ReceiptS, PresenceS, Ack, ErrorFrame,
]);

// ---------------------------------------------------------------- inferred types
export type ClientFrameT = z.infer<typeof ClientFrame>;
export type ServerFrameT = z.infer<typeof ServerFrame>;
export type MessageFrame = z.infer<typeof MessageS>;
export type AckFrame = z.infer<typeof Ack>;
export type ErrorFrameT = z.infer<typeof ErrorFrame>;

/** Parse one inbound text frame. Never throws: callers answer failures with a bad_request error. */
export function parseClientFrame(text: string):
  | { ok: true; frame: ClientFrameT }
  | { ok: false; code: "bad_request" | "unsupported_version"; message: string; ref: string | null } {
  let raw: unknown;
  try {
    raw = JSON.parse(text);
  } catch {
    return { ok: false, code: "bad_request", message: "frame is not valid JSON", ref: null };
  }
  const obj = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};
  const ref = typeof obj.id === "string" && ClientId.safeParse(obj.id).success ? obj.id : null;
  if (obj.v !== PROTOCOL_VERSION) {
    return { ok: false, code: "unsupported_version", message: `unsupported protocol version ${String(obj.v)}`, ref };
  }
  const parsed = ClientFrame.safeParse(raw);
  if (!parsed.success) {
    const issue = parsed.error.issues[0];
    return { ok: false, code: "bad_request", message: `${issue.path.join(".") || "frame"}: ${issue.message}`, ref };
  }
  return { ok: true, frame: parsed.data };
}

/** One valid example frame per type and direction. The documentation page prints these exact frames. */
export interface Example { name: string; direction: "c2s" | "s2c"; frame: Record<string, unknown> }

const M1 = "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA";
const M2 = "01JAB3W9D2F6G8H0J1K3M5N7P9";
const SID = (n: string) => `s_01JAB3W7Q${n.padEnd(17, "0")}`;
const T0 = 1761300000000;

export const examples: Example[] = [
  { name: "hello (client)", direction: "c2s", frame: {
    v: 1, type: "hello", id: "01JAB3W6A1B2C3D4E5F6G7H8J9", room: null, ts: 0,
    payload: { token: "ticket-change-me", client: "web/1.4",
      resume: { sessionId: "sess_01JAB3V0000000000000000000", rooms: { general: 41 } } } } },
  { name: "hello (server)", direction: "s2c", frame: {
    v: 1, type: "hello", id: SID("A"), room: null, ts: T0,
    payload: { ref: "01JAB3W6A1B2C3D4E5F6G7H8J9", userId: "alice", name: "Alice", sessionId: "sess_01JAB3V0000000000000000000",
      heartbeatMs: 20000, maxFrameBytes: 16384, resumed: true, rooms: ["general"] } } },
  { name: "join", direction: "c2s", frame: {
    v: 1, type: "join", id: "01JAB3W6B1B2C3D4E5F6G7H8J9", room: "general", ts: 0, payload: { since: 41 } } },
  { name: "leave", direction: "c2s", frame: {
    v: 1, type: "leave", id: "01JAB3W6C1B2C3D4E5F6G7H8J9", room: "general", ts: 0, payload: {} } },
  { name: "message (client)", direction: "c2s", frame: {
    v: 1, type: "message", id: M1, room: "general", ts: 0,
    payload: { text: "Hello, Chatterbox", replyTo: null,
      attachments: [{ url: "https://chat.example.test/files/menu.pdf", name: "menu.pdf", mime: "application/pdf", size: 48213 }] } } },
  { name: "message (server)", direction: "s2c", frame: {
    v: 1, type: "message", id: M1, room: "general", ts: T0,
    payload: { from: { userId: "alice", name: "Alice" }, text: "Hello, Chatterbox", replyTo: null,
      attachments: [{ url: "https://chat.example.test/files/menu.pdf", name: "menu.pdf", mime: "application/pdf", size: 48213 }],
      seq: 42, edited: false } } },
  { name: "edit (client)", direction: "c2s", frame: {
    v: 1, type: "edit", id: "01JAB3WAE1B2C3D4E5F6G7H8J9", room: "general", ts: 0,
    payload: { target: M1, text: "Hello, Chatterbox!" } } },
  { name: "edit (server)", direction: "s2c", frame: {
    v: 1, type: "edit", id: SID("B"), room: "general", ts: T0 + 5000,
    payload: { target: M1, text: "Hello, Chatterbox!", seq: 43, editedAt: T0 + 5000 } } },
  { name: "react (client)", direction: "c2s", frame: {
    v: 1, type: "react", id: "01JAB3WAF1B2C3D4E5F6G7H8J9", room: "general", ts: 0,
    payload: { target: M1, emoji: "\u{1F44D}", op: "add" } } },
  { name: "react (server)", direction: "s2c", frame: {
    v: 1, type: "react", id: SID("C"), room: "general", ts: T0 + 6000,
    payload: { target: M1, emoji: "\u{1F44D}", op: "add", from: { userId: "bob" }, seq: 44 } } },
  { name: "typing (client)", direction: "c2s", frame: {
    v: 1, type: "typing", id: "01JAB3WAG1B2C3D4E5F6G7H8J9", room: "general", ts: 0, payload: { state: "start" } } },
  { name: "typing (server)", direction: "s2c", frame: {
    v: 1, type: "typing", id: SID("D"), room: "general", ts: T0 + 7000, payload: { userId: "bob", state: "start" } } },
  { name: "receipt (client)", direction: "c2s", frame: {
    v: 1, type: "receipt", id: "01JAB3WAH1B2C3D4E5F6G7H8J9", room: "general", ts: 0, payload: { kind: "read", upTo: 44 } } },
  { name: "receipt (server)", direction: "s2c", frame: {
    v: 1, type: "receipt", id: SID("E"), room: "general", ts: T0 + 8000, payload: { userId: "bob", kind: "read", upTo: 44 } } },
  { name: "presence (client)", direction: "c2s", frame: {
    v: 1, type: "presence", id: "01JAB3WAJ1B2C3D4E5F6G7H8J9", room: null, ts: 0, payload: { status: "away" } } },
  { name: "presence (server)", direction: "s2c", frame: {
    v: 1, type: "presence", id: SID("F"), room: "general", ts: T0 + 9000,
    payload: { userId: "alice", name: "Alice", status: "away" } } },
  { name: "history (client)", direction: "c2s", frame: {
    v: 1, type: "history", id: "01JAB3WAK1B2C3D4E5F6G7H8J9", room: "general", ts: 0, payload: { before: 42, limit: 2 } } },
  { name: "ack (message)", direction: "s2c", frame: {
    v: 1, type: "ack", id: SID("G"), room: "general", ts: T0,
    payload: { ref: M1, ok: true, seq: 42, dup: false, result: {} } } },
  { name: "ack (duplicate retry)", direction: "s2c", frame: {
    v: 1, type: "ack", id: SID("H"), room: "general", ts: T0 + 12000,
    payload: { ref: M1, ok: true, seq: 42, dup: true, result: {} } } },
  { name: "ack (history)", direction: "s2c", frame: {
    v: 1, type: "ack", id: SID("J"), room: "general", ts: T0 + 13000,
    payload: { ref: "01JAB3WAK1B2C3D4E5F6G7H8J9", ok: true, seq: null, dup: false,
      result: { messages: [{ v: 1, type: "message", id: M2, room: "general", ts: T0 - 60000,
        payload: { from: { userId: "bob", name: "Bob" }, text: "Morning!", replyTo: null, attachments: [], seq: 40, edited: false } }],
      hasMore: true, next: 40 } } } },
  { name: "error", direction: "s2c", frame: {
    v: 1, type: "error", id: SID("K"), room: "general", ts: T0 + 14000,
    payload: { ref: "01JAB3WAE1B2C3D4E5F6G7H8J9", code: "forbidden", message: "only the author can edit a message", retryable: false } } },
];

/** Frames that every conforming receiver must reject, with the error code the server answers. */
export const invalid: { name: string; text: string; code: string }[] = [
  { name: "not JSON", text: "{nope", code: "bad_request" },
  { name: "unknown version", text: JSON.stringify({ v: 2, type: "message", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: {} }), code: "unsupported_version" },
  { name: "unknown type", text: JSON.stringify({ v: 1, type: "shout", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: {} }), code: "bad_request" },
  { name: "empty text", text: JSON.stringify({ v: 1, type: "message", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: { text: "", replyTo: null, attachments: [] } }), code: "bad_request" },
  { name: "id too short", text: JSON.stringify({ v: 1, type: "leave", id: "abc", room: "general", ts: 0, payload: {} }), code: "bad_request" },
  { name: "room with capitals", text: JSON.stringify({ v: 1, type: "leave", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "General", ts: 0, payload: {} }), code: "bad_request" },
  { name: "http attachment", text: JSON.stringify({ v: 1, type: "message", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: { text: "x", replyTo: null, attachments: [{ url: "http://insecure.example.test/a.png", name: "a.png", mime: "image/png", size: 1 }] } }), code: "bad_request" },
  { name: "two graphemes in react", text: JSON.stringify({ v: 1, type: "react", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: { target: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", emoji: "\u{1F44D}\u{1F44D}", op: "add" } }), code: "bad_request" },
  { name: "null payload", text: JSON.stringify({ v: 1, type: "leave", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: null }), code: "bad_request" },
  { name: "history limit 500", text: JSON.stringify({ v: 1, type: "history", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: "general", ts: 0, payload: { before: null, limit: 500 } }), code: "bad_request" },
  { name: "ack sent by a client", text: JSON.stringify({ v: 1, type: "ack", id: "01JAB3W7Q8Z4N5R6T7V8X9Y0ZA", room: null, ts: 0, payload: {} }), code: "bad_request" },
];

import { ClientFrame, ServerFrame, parseClientFrame } from "./chatterbox-schema.ts";
import { examples, invalid } from "./frames.ts";

let failures = 0;
const check = (ok: boolean, label: string, detail = ""): void => {
  console.log(`${ok ? "PASS" : "FAIL"}  ${label}${detail ? `  ${detail}` : ""}`);
  if (!ok) failures++;
};

const types = new Set<string>();
for (const { name, direction, frame } of examples) {
  const schema = direction === "c2s" ? ClientFrame : ServerFrame;
  const result = schema.safeParse(frame);
  check(result.success, `${direction} ${name}`, result.success ? "" : result.error.issues[0].message);
  types.add(String(frame.type));
  // a frame must survive a JSON round trip unchanged
  check(JSON.stringify(JSON.parse(JSON.stringify(frame))) === JSON.stringify(frame), `${name} round trip`);
}
check(types.size === 12, "all twelve types covered", [...types].sort().join(","));

for (const { name, text, code } of invalid) {
  const r = parseClientFrame(text);
  check(!r.ok && r.code === code, `reject ${name}`, r.ok ? "accepted!" : `${r.code}: ${r.message}`);
}

// directions are enforced: an ack is never accepted from a client, a hello from a server needs the s_ id prefix
check(!ClientFrame.safeParse(examples.find((e) => e.name === "ack (message)")!.frame).success, "client schema rejects ack");
check(!ServerFrame.safeParse(examples.find((e) => e.name === "join")!.frame).success, "server schema rejects join");

console.log(failures === 0 ? "\nconformance: OK" : `\nconformance: ${failures} failure(s)`);
process.exit(failures === 0 ? 0 : 1);

import { z } from "zod";
import { Ajv2020 } from "ajv/dist/2020.js";
import addFormatsModule from "ajv-formats";
import { ClientFrame, ServerFrame } from "./chatterbox-schema.ts";
import { examples, invalid } from "./frames.ts";

// Zod 4 can emit JSON Schema (draft 2020-12), so one source of truth feeds both validators.
const clientSchema = z.toJSONSchema(ClientFrame, { io: "input" });
const serverSchema = z.toJSONSchema(ServerFrame, { io: "input" });

const addFormats = addFormatsModule as unknown as (a: Ajv2020) => void;
const ajv = new Ajv2020({ allErrors: true, strict: false });
addFormats(ajv);
const validateClient = ajv.compile(clientSchema);
const validateServer = ajv.compile(serverSchema);

let failures = 0;
for (const { name, direction, frame } of examples) {
  const ok = (direction === "c2s" ? validateClient : validateServer)(frame);
  console.log(`${ok ? "PASS" : "FAIL"}  ajv accepts ${direction} ${name}`);
  if (!ok) failures++;
}
for (const { name, text } of invalid) {
  let parsed: unknown;
  try { parsed = JSON.parse(text); } catch { console.log(`SKIP  ajv ${name} (not JSON)`); continue; }
  const jsonSchemaSays = validateClient(parsed);
  const zodSays = ClientFrame.safeParse(parsed).success;
  // Known gap: the Intl.Segmenter refinement cannot be expressed in JSON Schema
  const expectedGap = name === "two graphemes in react";
  const agree = jsonSchemaSays === zodSays || expectedGap;
  console.log(`${agree ? "PASS" : "FAIL"}  ajv ${jsonSchemaSays ? "accepts" : "rejects"} ${name}${expectedGap ? " (refinement only Zod can check)" : ""}`);
  if (!agree) failures++;
}
console.log(`\nGenerated JSON Schema: ${(clientSchema.oneOf ?? clientSchema.anyOf)?.length} client variants, ${(serverSchema.oneOf ?? serverSchema.anyOf)?.length} server variants`);
process.exit(failures === 0 ? 0 : 1);

import { fileURLToPath } from "node:url";
import { ServerFrame, SUBPROTOCOL, type ServerFrameT } from "./chatterbox-schema.ts";
import { clientId } from "./ids.ts";

type Listener = (frame: ServerFrameT) => void;
interface Pending { frame: Record<string, unknown>; resolve: (f: ServerFrameT) => void; timer?: ReturnType<typeof setTimeout> }

/** Minimal Chatterbox client: validates every inbound frame, correlates acks and retries with the same id. */
export class ChatterboxClient {
  ws: WebSocket | null = null;
  sessionId: string | null = null;
  lastSeq: Record<string, number> = {};
  readonly pending = new Map<string, Pending>(); // insertion order = original send order
  readonly sent = new Map<string, Record<string, unknown>>(); // every request frame, kept so tests can replay it
  readonly seen: ServerFrameT[] = [];
  private listeners = new Set<Listener>();
  private base: string;
  private userId: string;
  private ackTimeoutMs: number;
  constructor(base: string, userId: string, ackTimeoutMs = 10000) {
    this.base = base;
    this.userId = userId;
    this.ackTimeoutMs = ackTimeoutMs;
  }

  on(l: Listener): () => void { this.listeners.add(l); return () => this.listeners.delete(l); }
  waitFor(pred: (f: ServerFrameT) => boolean, ms = 3000): Promise<ServerFrameT> {
    return new Promise((resolve, reject) => {
      const t = setTimeout(() => { off(); reject(new Error("waitFor timed out")); }, ms);
      const off = this.on((f) => { if (pred(f)) { clearTimeout(t); off(); resolve(f); } });
    });
  }

  async connect(): Promise<ServerFrameT & { type: "hello" }> {
    const res = await fetch(`http://${this.base}/ticket?user=${this.userId}`, { method: "POST" });
    const { ticket } = (await res.json()) as { ticket: string };
    const ws = new WebSocket(`ws://${this.base}/`, SUBPROTOCOL); // browser-compatible global client, Node >= 22
    this.ws = ws;
    ws.onmessage = (ev) => this.onMessage(String(ev.data));
    await new Promise<void>((ok, bad) => { ws.onopen = () => ok(); ws.onerror = () => bad(new Error("connect failed")); });
    const resume = this.sessionId ? { sessionId: this.sessionId, rooms: this.lastSeq } : undefined;
    const hello = this.waitFor((f) => f.type === "hello");
    this.write({ v: 1, type: "hello", id: clientId(), room: null, ts: 0, payload: { token: ticket, client: "node/1.0", ...(resume && { resume }) } });
    const h = (await hello) as ServerFrameT & { type: "hello" };
    this.sessionId = h.payload.sessionId;
    for (const p of this.pending.values()) this.write(p.frame); // retry unacked envelopes, same ids, original order
    return h;
  }

  /** Send an envelope that expects an ack or an error and resolve with whichever arrives. */
  request(type: string, room: string | null, payload: Record<string, unknown>, id = clientId()): Promise<ServerFrameT> {
    const frame = { v: 1, type, id, room, ts: 0, payload };
    this.sent.set(id, frame);
    return new Promise((resolve) => {
      const p: Pending = { frame, resolve };
      this.pending.set(id, p);
      p.timer = setTimeout(() => { if (this.ws?.readyState === WebSocket.OPEN) this.write(frame); }, this.ackTimeoutMs);
      if (this.ws?.readyState === WebSocket.OPEN) this.write(frame);
    });
  }
  /** Fire-and-forget envelopes (typing, receipt). */
  notify(type: string, room: string, payload: Record<string, unknown>): void {
    this.write({ v: 1, type, id: clientId(), room, ts: 0, payload });
  }
  /** Re-send a frame that was already sent, byte for byte, as a lost-ack retry would. */
  resend(id: string): void { this.write(this.sent.get(id)!); }

  private write(frame: Record<string, unknown>): void { this.ws?.send(JSON.stringify(frame)); }

  private onMessage(text: string): void {
    const parsed = ServerFrame.safeParse(JSON.parse(text));
    if (!parsed.success) { console.error("dropping invalid server frame:", parsed.error.issues[0]); return; }
    const f = parsed.data;
    this.seen.push(f);
    if (f.type === "message" || f.type === "edit" || f.type === "react") {
      this.lastSeq[f.room] = Math.max(this.lastSeq[f.room] ?? 0, f.payload.seq);
    }
    if (f.type === "ack" || f.type === "error") {
      const ref = f.payload.ref;
      const p = ref && this.pending.get(ref);
      if (p && (f.type === "ack" || !f.payload.retryable)) {
        clearTimeout(p.timer);
        this.pending.delete(ref);
        p.resolve(f);
      }
    }
    this.listeners.forEach((l) => l(f));
  }

  close(): void { this.ws?.close(1000, "bye"); }
  drop(): void { this.ws?.close(1000, "simulated network loss"); }
}

// ---------------------------------------------------------------- demo scenario
if (process.argv[1] === fileURLToPath(import.meta.url)) {
  const base = process.env.CHATTERBOX ?? "127.0.0.1:18080";
  let failed = 0;
  const check = (ok: boolean, label: string): void => { console.log(`${ok ? "PASS" : "FAIL"}  ${label}`); if (!ok) failed++; };
  const ackOf = (f: ServerFrameT) => (f.type === "ack" ? f.payload : null);
  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

  const alice = new ChatterboxClient(base, "alice");
  const bob = new ChatterboxClient(base, "bob");
  const h1 = await alice.connect();
  await bob.connect();
  check(h1.payload.userId === "alice" && !h1.payload.resumed, "hello: alice authenticated with a one-time ticket");
  check(ackOf(await alice.request("join", "general", { since: null }))?.ok === true, "join general (alice)");
  const bobJoin = ackOf(await bob.request("join", "general", { since: null }));
  check((bobJoin?.result.members as unknown[]).length === 2, "join general (bob) lists two members");

  // 1. a normal message: ack with the assigned seq, broadcast to both members
  const id = clientId();
  const bobSees = bob.waitFor((f) => f.type === "message" && f.id === id);
  const first = ackOf(await alice.request("message", "general", { text: "Hello, Chatterbox", replyTo: null, attachments: [] }, id));
  check(first?.ok === true && first.dup === false && typeof first.seq === "number", `message acked with seq ${first?.seq}`);
  await bobSees;

  // 2. lost-ack retry: the SAME id is sent again, the server answers with the original ack and dup:true
  const retry = alice.waitFor((f) => f.type === "ack" && f.payload.ref === id && f.payload.dup);
  alice.resend(id);
  const dup = ackOf(await retry);
  await sleep(200); // give a (wrong) second broadcast time to arrive
  check(dup?.dup === true && dup.seq === first?.seq, "duplicate id: same seq, dup:true");
  check(bob.seen.filter((f) => f.type === "message" && f.id === id).length === 1, "duplicate id: not broadcast twice");

  // 3. network loss: alice drops, bob keeps talking, alice resumes and gets the missed envelope with its original seq
  alice.drop();
  await sleep(100);
  const missedId = clientId();
  ackOf(await bob.request("message", "general", { text: "You missed this", replyTo: null, attachments: [] }, missedId));
  const again = alice.waitFor((f) => f.type === "message" && f.id === missedId);
  const h2 = await alice.connect();
  check(h2.payload.resumed === true && h2.payload.sessionId === h1.payload.sessionId, "resume: same session, resumed:true");
  const replayed = await again;
  check(replayed.type === "message" && replayed.payload.seq === (first!.seq! + 1), "resume: missed message replayed with original seq");
  const dupAfterReconnect = ackOf(await alice.request("message", "general", { text: "Hello, Chatterbox", replyTo: null, attachments: [] }, id));
  check(dupAfterReconnect?.dup === true && dupAfterReconnect.seq === first?.seq, "retry after reconnect: still deduplicated");

  // 4. edit, react, typing, receipt, presence
  const edit = ackOf(await alice.request("edit", "general", { target: id, text: "Hello, Chatterbox!" }));
  check(edit?.ok === true && edit.seq! > first!.seq!, "edit acked with a newer seq");
  const forbidden = await bob.request("edit", "general", { target: id, text: "hijack" });
  check(forbidden.type === "error" && forbidden.payload.code === "forbidden", "edit by a non-author -> forbidden");
  const react = ackOf(await bob.request("react", "general", { target: id, emoji: "\u{1F44D}", op: "add" }));
  check(react?.ok === true, "react add acked");
  const conflict = await bob.request("react", "general", { target: id, emoji: "\u{1F44D}", op: "add" });
  check(conflict.type === "error" && conflict.payload.code === "conflict", "react add twice -> conflict");
  const typing = alice.waitFor((f) => f.type === "typing" && f.payload.userId === "bob");
  bob.notify("typing", "general", { state: "start" });
  await typing;
  check(true, "typing broadcast reaches the other member");
  const receipt = alice.waitFor((f) => f.type === "receipt");
  bob.notify("receipt", "general", { kind: "read", upTo: react!.seq! });
  await receipt;
  check(true, "receipt broadcast reaches the other member");
  const away = bob.waitFor((f) => f.type === "presence" && f.payload.status === "away");
  void alice.request("presence", null, { status: "away" });
  await away;
  check(true, "presence change broadcast to room members");

  // 5. history paging backwards by seq
  for (let i = 0; i < 4; i++) await alice.request("message", "general", { text: `filler ${i}`, replyTo: null, attachments: [] });
  const page1 = ackOf(await alice.request("history", "general", { before: null, limit: 3 }))!;
  const r1 = page1.result as { messages: { payload: { seq: number } }[]; hasMore: boolean; next: number | null };
  check(r1.messages.length === 3 && r1.hasMore && r1.next !== null, "history page 1: 3 messages, hasMore");
  const page2 = ackOf(await alice.request("history", "general", { before: r1.next, limit: 3 }))!;
  const r2 = page2.result as { messages: { payload: { seq: number } }[] };
  check(r2.messages.length >= 1 && r2.messages.at(-1)!.payload.seq < r1.next!, "history page 2 continues before next");

  // 6. error paths
  const notMember = await alice.request("message", "secret-room", { text: "hi", replyTo: null, attachments: [] });
  check(notMember.type === "error" && notMember.payload.code === "forbidden", "message in a room you have not joined -> forbidden");
  const dm = await alice.request("join", "dm-bob-carol", { since: null });
  check(dm.type === "error" && dm.payload.code === "forbidden", "joining someone else's direct-message room -> forbidden");
  const leave = ackOf(await alice.request("leave", "general", {}));
  check(leave?.ok === true, "leave general");

  alice.close(); bob.close();
  await sleep(100);
  console.log(failed === 0 ? "\nclient scenario: OK" : `\nclient scenario: ${failed} failure(s)`);
  process.exit(failed === 0 ? 0 : 1);
}

import { WebSocket } from "ws";
import { startServer } from "./server.ts";
import { clientId } from "./ids.ts";

let failed = 0;
const check = (ok: boolean, label: string): void => { console.log(`${ok ? "PASS" : "FAIL"}  ${label}`); if (!ok) failed++; };

const srv = await startServer({ port: 0, helloTimeoutMs: 300, heartbeatMs: 200, presenceGraceMs: 300 });
const base = `127.0.0.1:${srv.port}`;

/** Open a raw socket, collect frames and the close code. */
async function open(origin?: string, autoPong = true) {
  const ws = new WebSocket(`ws://${base}/`, "chatterbox.v1", { ...(origin && { origin }), autoPong });
  const frames: any[] = [];
  const closed = new Promise<number>((r) => ws.on("close", (code) => r(code)));
  ws.on("message", (d) => frames.push(JSON.parse(String(d))));
  await new Promise<void>((ok, bad) => { ws.on("open", () => ok()); ws.on("error", bad); });
  return { ws, frames, closed };
}
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const hello = async (user: string) => {
  const { ticket } = await (await fetch(`http://${base}/ticket?user=${user}`, { method: "POST" })).json() as { ticket: string };
  return JSON.stringify({ v: 1, type: "hello", id: clientId(), room: null, ts: 0, payload: { token: ticket, client: "edge/1" } });
};

// 1. Origin allow-list: a browser from another site is refused during the handshake
const bad = new WebSocket(`ws://${base}/`, "chatterbox.v1", { origin: "https://evil.example.test" });
const badResult = await new Promise<string>((r) => { bad.on("unexpected-response", (_q, res) => r(String(res.statusCode))); bad.on("open", () => r("open")); bad.on("error", () => r("error")); });
check(badResult === "403", "Origin not on the allow-list -> HTTP 403 handshake");
const good = await open("https://chat.example.test");
check(good.ws.protocol === "chatterbox.v1", "allowed Origin accepted, subprotocol chatterbox.v1 negotiated");
good.ws.close();

// 2. no hello within the deadline -> 4408
const silent = await open();
check((await silent.closed) === 4408, "no hello within helloTimeoutMs -> close 4408");

// 3. first frame is not hello -> unauthorized + 4401
const nohello = await open();
nohello.ws.send(JSON.stringify({ v: 1, type: "join", id: clientId(), room: "general", ts: 0, payload: { since: null } }));
check((await nohello.closed) === 4401 && nohello.frames[0].payload.code === "unauthorized", "frame before hello -> error unauthorized, close 4401");

// 4. unknown version -> error then 4426
const v2 = await open();
v2.ws.send(JSON.stringify({ v: 2, type: "hello", id: clientId(), room: null, ts: 0, payload: {} }));
check((await v2.closed) === 4426 && v2.frames[0].payload.code === "unsupported_version", "v:2 -> error unsupported_version, close 4426");

// 5. one-time ticket cannot be replayed
const t1 = await open();
const h = await hello("alice");
t1.ws.send(h);
await sleep(100);
const t2 = await open();
t2.ws.send(h);
check((await t2.closed) === 4401, "replayed ticket -> close 4401");

// 6. oversized frame -> too_large then 4413
const big = await open();
big.ws.send(await hello("bob"));
await sleep(100);
big.ws.send(JSON.stringify({ v: 1, type: "message", id: clientId(), room: "general", ts: 0, payload: { text: "x".repeat(20000), replyTo: null, attachments: [] } }));
check((await big.closed) === 4413 && big.frames.some((f) => f.payload.code === "too_large"), "frame over 16384 bytes -> too_large, close 4413");

// 7. malformed payload -> bad_request carrying the ref, connection stays open
const mal = await open();
mal.ws.send(await hello("carol"));
await sleep(100);
const badId = clientId();
mal.ws.send(JSON.stringify({ v: 1, type: "join", id: badId, room: "NOT VALID", ts: 0, payload: { since: null } }));
await sleep(100);
const err = mal.frames.find((f) => f.type === "error");
check(err?.payload.code === "bad_request" && err.payload.ref === badId && mal.ws.readyState === WebSocket.OPEN, "invalid room -> bad_request with ref, socket stays open");

// 8. rate limit: burst of 40 passes, the rest is rate_limited, persistent abuse closes with 4429
const rl = await open();
rl.ws.send(await hello("dave"));
await sleep(100);
for (let i = 0; i < 120; i++) rl.ws.send(JSON.stringify({ v: 1, type: "presence", id: clientId(), room: null, ts: 0, payload: { status: "online" } }));
const code = await rl.closed;
check(rl.frames.some((f) => f.payload?.code === "rate_limited" && f.payload.retryable === true) && code === 4429, "burst of 120 envelopes -> rate_limited (retryable), then close 4429");

// 9. silence for 2 x heartbeatMs: a peer that never answers pings is closed with 4408
const dead = await open(undefined, false); // autoPong:false -> never answers the server's pings
dead.ws.send(await hello("erin"));
check((await dead.closed) === 4408, "no pong and no frames for 2 x heartbeatMs -> close 4408");

// 10. presence goes offline after the grace period
const a = await open();
a.ws.send(await hello("fred"));
const b = await open();
b.ws.send(await hello("gina"));
await sleep(100);
for (const [w, room] of [[a.ws, "lobby"], [b.ws, "lobby"]] as const) w.send(JSON.stringify({ v: 1, type: "join", id: clientId(), room, ts: 0, payload: { since: null } }));
await sleep(100);
a.ws.close();
await sleep(600);
check(b.frames.some((f) => f.type === "presence" && f.payload.userId === "fred" && f.payload.status === "offline"), "closed connection -> presence offline after the grace period");
b.ws.close();

// 11. graceful shutdown tells clients to reconnect: 4503
const live = await open();
live.ws.send(await hello("hank"));
await sleep(100);
const shutdown = srv.close();
check((await live.closed) === 4503, "server restart -> close 4503");
await shutdown;

console.log(failed === 0 ? "\nedge cases: OK" : `\nedge cases: ${failed} failure(s)`);
process.exit(failed === 0 ? 0 : 1);

mkdir chatterbox-reference && cd chatterbox-reference
# save the files above, then:
npm install
npm run typecheck      # tsc --noEmit, no output means success
npm run conformance    # every example frame validates; every invalid frame is rejected
npm run ajv            # the generated JSON Schema agrees with Zod
npm run sizes          # prints the table of the previous section
node lamport.ts        # prints the Lamport ordering
npm run edge           # handshake, limits, close codes (starts its own server)

PORT=18080 npm run server &     # the reference server; POST /ticket?user=alice mints a demo ticket
CHATTERBOX=127.0.0.1:18080 npm run client

PASS  duplicate id: same seq, dup:true
PASS  duplicate id: not broadcast twice
PASS  resume: same session, resumed:true
PASS  resume: missed message replayed with original seq
PASS  retry after reconnect: still deduplicated
...
PASS  leave general

client scenario: OK