Public: anyone can read this; the crew can change it.
The live channel carries no secret and no waste: events name their table, and a phone that slept catches up #30
mason/parley:mason/23-the-live-channel-carries-no-secret-and-n → main 7 commits fork 2 threads · 2 unresolved
3 files
changed +163
−3
AGENTS.md +8 −1
| @@ -84,7 +84,14 @@ To add a concept: | ||
| 84 | 84 | - **A terminal command** — a key in `src/tty.ts` that calls the action and |
| 85 | 85 | reports on the status line. |
| 86 | 86 | - **Something live** — `emit(type, data)` in the action, and |
| 87 | `data-live="<types>"` on the region of the page that shows it. | |
| 87 | `data-live="<types>"` on the region of the page that shows it. An event's | |
| 88 | `data` is an identifier, never content — `{ table, act }`, never an | |
| 89 | accord, a charge, a claim or a name: the stream reaches every open page, | |
| 90 | a guest's included, so what a viewer may see stays a decision the action | |
| 91 | makes when they refetch. `emit` holds you to it, refusing a payload that | |
| 92 | is nested or a string longer than an id: it throws everywhere the app is | |
| 93 | being written (local, a preview, the tests) and logs and sends the | |
| 94 | address alone in production, where the write has already committed. | |
| 88 | 95 | |
| 89 | 96 | ## The bar |
| 90 | 97 |
src/live.ts +65 −1
| @@ -5,8 +5,19 @@ | ||
| 5 | 5 | * `?since=`) hears what it missed. `static/live.js` turns the stream into |
| 6 | 6 | * DOM events. The bus is this process's: the terminal is another process, |
| 7 | 7 | * and its writes show on the next load rather than live. |
| 8 | * | |
| 9 | * One rule holds it together, and this module enforces it: **an event's | |
| 10 | * `data` is an identifier, never content.** `{ table, act }`, never an | |
| 11 | * accord, a charge, a claim or a name-length essay. The stream reaches | |
| 12 | * every open page, a guest's included, and it has no viewer to redact for; | |
| 13 | * the client is told *something changed here* and the action decides what | |
| 14 | * that viewer may see when they refetch, so the redaction lives in one | |
| 15 | * place and cannot leak down the wire. | |
| 8 | 16 | */ |
| 9 | 17 | |
| 18 | import { env } from "./env.ts"; | |
| 19 | import { SECURITY } from "./http.ts"; | |
| 20 | ||
| 10 | 21 | export interface LiveEvent { |
| 11 | 22 | readonly id: number; |
| 12 | 23 | readonly type: string; |
| @@ -15,12 +26,58 @@ export interface LiveEvent { | ||
| 15 | 26 | |
| 16 | 27 | const KEEP = 100; |
| 17 | 28 | const HEARTBEAT_MS = 25_000; |
| 29 | /** An id on the bus is short: long enough for a uuid, too short for prose. */ | |
| 30 | export const ID_MAX = 64; | |
| 18 | 31 | const kept: LiveEvent[] = []; |
| 19 | 32 | const listeners = new Set<(event: LiveEvent) => void>(); |
| 20 | 33 | let last = 0; |
| 21 | 34 | |
| 35 | const shape = (value: unknown): string => | |
| 36 | value === null ? "null" : Array.isArray(value) ? "an array" : typeof value; | |
| 37 | ||
| 38 | /** | |
| 39 | * Why `data` is not an address, or `undefined` when it is one: an object | |
| 40 | * whose every value is a number, a boolean or a string of at most | |
| 41 | * {@link ID_MAX} characters. Nothing nested, nothing long — those are | |
| 42 | * content, and content does not travel on the bus. Exported so a test can | |
| 43 | * hold an emit to the rule and say why it broke it. | |
| 44 | */ | |
| 45 | export function notAnAddress(data: unknown): string | undefined { | |
| 46 | if (data === undefined || data === null) return undefined; | |
| 47 | if (typeof data !== "object" || Array.isArray(data)) | |
| 48 | return `data is ${shape(data)}; a live payload is an object of identifiers`; | |
| 49 | for (const [key, value] of Object.entries(data)) { | |
| 50 | if (typeof value === "number" || typeof value === "boolean") continue; | |
| 51 | if (typeof value === "string") { | |
| 52 | if (value.length <= ID_MAX) continue; | |
| 53 | return `data.${key} is a ${value.length}-character string; a live payload carries identifiers, not content (${ID_MAX} characters at most)`; | |
| 54 | } | |
| 55 | return `data.${key} is ${shape(value)}; a live payload carries only numbers, booleans and identifiers`; | |
| 56 | } | |
| 57 | return undefined; | |
| 58 | } | |
| 59 | ||
| 60 | /** | |
| 61 | * Announce that something changed. `data` names it and says nothing about | |
| 62 | * it; a payload that breaks the rule never travels as written. | |
| 63 | */ | |
| 22 | 64 | export function emit(type: string, data: unknown): LiveEvent { |
| 23 | const event: LiveEvent = { id: ++last, type, data }; | |
| 65 | const wrong = notAnAddress(data); | |
| 66 | let carried = data; | |
| 67 | if (wrong !== undefined) { | |
| 68 | // A payload that carries content is the expensive kind of bug: it is on | |
| 69 | // every open page before anyone reviews it. So it is loud where the app | |
| 70 | // is being written — a local run, a preview, the tests all throw — and | |
| 71 | // quiet in front of a player, where the write has already committed and | |
| 72 | // a 500 over the announcement of it would be a lie about what happened. | |
| 73 | // There the address alone goes down the wire: the client refetches by | |
| 74 | // type, and the action decides what it may see. | |
| 75 | const said = `emit(${JSON.stringify(type)}): ${wrong}`; | |
| 76 | if (env !== "production") throw new TypeError(said); | |
| 77 | console.error(`${said} — sent as an address alone`); | |
| 78 | carried = undefined; | |
| 79 | } | |
| 80 | const event: LiveEvent = { id: ++last, type, data: carried }; | |
| 24 | 81 | kept.push(event); |
| 25 | 82 | if (kept.length > KEEP) kept.shift(); |
| 26 | 83 | for (const listen of listeners) listen(event); |
| @@ -74,8 +131,15 @@ export function events(request: Request): Response { | ||
| 74 | 131 | return new Response(stream, { |
| 75 | 132 | headers: { |
| 76 | 133 | "content-type": "text/event-stream", |
| 134 | // The one answer that is a connection rather than a document: it says | |
| 135 | // its own `cache-control` at this call site, and `no-store` is the | |
| 136 | // whole of it — the stream is the same for everyone (it carries | |
| 137 | // addresses, never a viewer's state), so it needs no `Vary`, and | |
| 138 | // nothing may hold a copy of a connection anyway. The rest of the | |
| 139 | // floor applies here as to any other response. | |
| 77 | 140 | "cache-control": "no-store", |
| 78 | 141 | "x-accel-buffering": "no", |
| 142 | ...SECURITY, | |
| 79 | 143 | }, |
| 80 | 144 | }); |
| 81 | 145 | } |
src/server.test.ts +90 −1
| @@ -4,6 +4,13 @@ import { mkdtempSync } from "node:fs"; | ||
| 4 | 4 | import { tmpdir } from "node:os"; |
| 5 | 5 | import { join } from "node:path"; |
| 6 | 6 | import { text } from "./http.ts"; |
| 7 | import { | |
| 8 | emit, | |
| 9 | ID_MAX, | |
| 10 | type LiveEvent, | |
| 11 | notAnAddress, | |
| 12 | subscribe, | |
| 13 | } from "./live.ts"; | |
| 7 | 14 | import { layout } from "./pages/layout.ts"; |
| 8 | 15 | import { serve } from "./server.ts"; |
| 9 | 16 | import { sign } from "./who.ts"; |
| @@ -317,6 +324,79 @@ test("a change is on the event stream, and a late client hears what it missed", | ||
| 317 | 324 | expect(replay).toContain("table.opened"); |
| 318 | 325 | }); |
| 319 | 326 | |
| 327 | test("an event's data is an identifier, never content", () => { | |
| 328 | // What an address looks like: ids, counts, flags, and nothing said. | |
| 329 | expect(notAnAddress({ table: 7, act: 12 })).toBeUndefined(); | |
| 330 | expect(notAnAddress({ table: "7", started: true })).toBeUndefined(); | |
| 331 | expect(notAnAddress({ id: "x".repeat(ID_MAX) })).toBeUndefined(); | |
| 332 | expect(notAnAddress(undefined)).toBeUndefined(); | |
| 333 | expect(notAnAddress({})).toBeUndefined(); | |
| 334 | // What content looks like, and the message that says which rule it broke. | |
| 335 | expect(notAnAddress({ table: 7, accord: { clause: 2, swear: true } })).toMatch( | |
| 336 | /data\.accord is object/, | |
| 337 | ); | |
| 338 | expect(notAnAddress({ seats: [1, 2] })).toMatch(/data\.seats is an array/); | |
| 339 | expect(notAnAddress({ table: 7, claim: "x".repeat(ID_MAX + 1) })).toMatch( | |
| 340 | /data\.claim is a 65-character string/, | |
| 341 | ); | |
| 342 | expect(notAnAddress("the whole table")).toMatch(/data is string/); | |
| 343 | expect(notAnAddress([{ table: 7 }])).toMatch(/data is an array/); | |
| 344 | // And a breach is loud where the app is written: the tests are not | |
| 345 | // production, so emit throws rather than putting content on every page. | |
| 346 | expect(() => emit("test.breach", { charge: { clause: 1 } })).toThrow( | |
| 347 | /emit\("test\.breach"\)/, | |
| 348 | ); | |
| 349 | }); | |
| 350 | ||
| 351 | test("every emit the app makes today passes the rule", async () => { | |
| 352 | const heard: LiveEvent[] = []; | |
| 353 | const stop = subscribe((event) => heard.push(event)); | |
| 354 | const id = await openTable(alice, "The Addressed Table"); | |
| 355 | await api(`/api/tables/${id}/join`, { method: "POST" }, bob); | |
| 356 | await api(`/api/tables/${id}/leave`, { method: "POST" }, bob); | |
| 357 | stop(); | |
| 358 | // The emits that exist today, and the ids each one carries. A new type, | |
| 359 | // or a new key, fails here until someone has said it is an address — | |
| 360 | // which is the point: a bug fails a pull instead of a game. | |
| 361 | const addresses: Record<string, string[]> = { | |
| 362 | "table.opened": ["table", "title"], | |
| 363 | "seat.joined": ["player_name", "table"], | |
| 364 | "seat.left": ["player_name", "table"], | |
| 365 | }; | |
| 366 | expect(heard.map((event) => event.type)).toEqual([ | |
| 367 | "table.opened", | |
| 368 | "seat.joined", | |
| 369 | "seat.joined", | |
| 370 | "seat.left", | |
| 371 | ]); | |
| 372 | for (const event of heard) { | |
| 373 | expect(notAnAddress(event.data)).toBeUndefined(); | |
| 374 | expect(Object.keys(event.data as object).sort()).toEqual( | |
| 375 | addresses[event.type]!, | |
| 376 | ); | |
| 377 | } | |
| 378 | }); | |
| 379 | ||
| 380 | test("in front of a player a bad payload is dropped, not thrown", async () => { | |
| 381 | // The production half of the rule, where the write has already committed: | |
| 382 | // another process, because an environment is read once at start-up. | |
| 383 | const ran = Bun.spawnSync({ | |
| 384 | cmd: [ | |
| 385 | process.execPath, | |
| 386 | "-e", | |
| 387 | `const { emit } = await import(${JSON.stringify(join(import.meta.dir, "live.ts"))}); | |
| 388 | console.log(JSON.stringify(emit("table.opened", { table: 7, charter: { clause: 1 } })));`, | |
| 389 | ], | |
| 390 | env: { ...process.env, FORGE_APP_ENV: "production" }, | |
| 391 | }); | |
| 392 | expect(ran.exitCode).toBe(0); | |
| 393 | expect(JSON.parse(ran.stdout.toString())).toEqual({ | |
| 394 | id: 1, | |
| 395 | type: "table.opened", | |
| 396 | }); | |
| 397 | expect(ran.stderr.toString()).toContain("sent as an address alone"); | |
| 398 | }); | |
| 399 | ||
| 320 | 400 | test("the page region carries the live types it is refreshed by", async () => { |
| 321 | 401 | const page = await (await fetch(base + "/")).text(); |
| 322 | 402 | const region = /<section id="tables" data-live="([^"]*)"/.exec(page)?.[1]; |
| @@ -496,10 +576,19 @@ test("a call site can hand out a public cache on purpose", () => { | ||
| 496 | 576 | expect(shared.headers.get("x-content-type-options")).toBe("nosniff"); |
| 497 | 577 | }); |
| 498 | 578 | |
| 499 | test("the event stream keeps its own caching and still streams", async () => { | |
| 579 | test("the event stream stands on the floor, keeps its own caching, and streams", async () => { | |
| 500 | 580 | const stream = await fetch(base + "/events"); |
| 501 | 581 | expect(stream.headers.get("content-type")).toBe("text/event-stream"); |
| 502 | 582 | expect(stream.headers.get("cache-control")).toBe("no-store"); |
| 583 | // A connection is a response like any other: the floor is not optional | |
| 584 | // because the body never ends. | |
| 585 | expect(stream.headers.get("content-security-policy")).toContain( | |
| 586 | "default-src 'self'", | |
| 587 | ); | |
| 588 | expect(stream.headers.get("x-content-type-options")).toBe("nosniff"); | |
| 589 | expect(stream.headers.get("referrer-policy")).toBe( | |
| 590 | "strict-origin-when-cross-origin", | |
| 591 | ); | |
| 503 | 592 | const reader = stream.body!.getReader(); |
| 504 | 593 | const first = new TextDecoder().decode((await reader.read()).value); |
| 505 | 594 | expect(first).toContain("retry:"); |
new above
offline