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

Closed opened this
Closed without merging

mason/parley:mason/23-the-live-channel-carries-no-secret-and-n → main 7 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
3 files changed +163 −3
AGENTS.md +8 −1
@@ -84,7 +84,14 @@ To add a concept:
8484 - **A terminal command** — a key in `src/tty.ts` that calls the action and
8585 reports on the status line.
8686 - **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.
8895
8996 ## The bar
9097
src/live.ts +65 −1
@@ -5,8 +5,19 @@
55 * `?since=`) hears what it missed. `static/live.js` turns the stream into
66 * DOM events. The bus is this process's: the terminal is another process,
77 * 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.
816 */
917
18 import { env } from "./env.ts";
19 import { SECURITY } from "./http.ts";
20
1021 export interface LiveEvent {
1122 readonly id: number;
1223 readonly type: string;
@@ -15,12 +26,58 @@ export interface LiveEvent {
1526
1627 const KEEP = 100;
1728 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;
1831 const kept: LiveEvent[] = [];
1932 const listeners = new Set<(event: LiveEvent) => void>();
2033 let last = 0;
2134
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 */
2264 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 };
2481 kept.push(event);
2582 if (kept.length > KEEP) kept.shift();
2683 for (const listen of listeners) listen(event);
@@ -74,8 +131,15 @@ export function events(request: Request): Response {
74131 return new Response(stream, {
75132 headers: {
76133 "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.
77140 "cache-control": "no-store",
78141 "x-accel-buffering": "no",
142 ...SECURITY,
79143 },
80144 });
81145 }
src/server.test.ts +90 −1
@@ -4,6 +4,13 @@ import { mkdtempSync } from "node:fs";
44 import { tmpdir } from "node:os";
55 import { join } from "node:path";
66 import { text } from "./http.ts";
7 import {
8 emit,
9 ID_MAX,
10 type LiveEvent,
11 notAnAddress,
12 subscribe,
13 } from "./live.ts";
714 import { layout } from "./pages/layout.ts";
815 import { serve } from "./server.ts";
916 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",
317324 expect(replay).toContain("table.opened");
318325 });
319326
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
320400 test("the page region carries the live types it is refreshed by", async () => {
321401 const page = await (await fetch(base + "/")).text();
322402 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", () => {
496576 expect(shared.headers.get("x-content-type-options")).toBe("nosniff");
497577 });
498578
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 () => {
500580 const stream = await fetch(base + "/events");
501581 expect(stream.headers.get("content-type")).toBe("text/event-stream");
502582 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 );
503592 const reader = stream.body!.getReader();
504593 const first = new TextDecoder().decode((await reader.read()).value);
505594 expect(first).toContain("retry:");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs