@variance-authority/tribunal 0.1.0

package/dist/node/database.d.ts

@@ -0,0 +1,33 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { D1Like } from '../bindings.js';
+export interface SqliteDatabase extends D1Like {
+    /** Ends the process's hold on the file. `':memory:'` disappears with it. */
+    close(): void;
+}
+export interface TribunalDatabase extends SqliteDatabase {
+    /** Where it actually landed, absolute — printed at startup so it can be found again. */
+    readonly path: string;
+    /** The version the file is at once {@link openDatabase} has returned. */
+    readonly version: number;
+}
+/**
+ * Open the file, bring it to {@link SCHEMA_VERSION}, and hand back a `D1Like`.
+ *
+ * Fresh file, deployed file and half-upgraded file are three cases and this is
+ * the only place that distinguishes them; every caller downstream gets a
+ * database at the current version or an exception with a sentence in it.
+ */
+export declare function openDatabase(path: string): Promise<TribunalDatabase>;
+/** The version a file is at, or `null` for a database with no schema yet. */
+export declare function schemaVersionOf(db: D1Like): Promise<number | null>;
+/**
+ * The wrapper itself: `node:sqlite` in, {@link D1Like} out.
+ *
+ * The one behavioural difference from a `DatabaseSync` used directly is that
+ * `first` answers `null` where `get` answers `undefined`. That is not cosmetic:
+ * `null` is D1's "no row", the whole store distinguishes it from a failure, and a
+ * wrapper that returned `undefined` would let a `=== null` check silently stop
+ * being true.
+ */
+export declare function wrapSqlite(database: DatabaseSync): SqliteDatabase;
+//# sourceMappingURL=database.d.ts.map

package/dist/node/database.js

@@ -0,0 +1,157 @@
+import { createRequire } from 'node:module';
+import { INITIAL_VERSION, MIGRATIONS, SCHEMA_VERSION, applySchema } from '../schema.js';
+/**
+ * D1, as a file on a disk somebody owns.
+ *
+ * D1 *is* SQLite, so this is an adapter rather than a port: the same `SCHEMA`,
+ * the same indexes, the same append-only triggers and the same `ON CONFLICT`
+ * clauses execute here, through `node:sqlite`, that a Worker executes through the
+ * platform. Nothing above this file knows which one it got — `review.ts`,
+ * `store.ts` and `history.ts` take a {@link D1Like} and have never named a
+ * runtime.
+ *
+ * The double in [`testing.ts`](../testing.ts) is this same wrapper over
+ * `':memory:'`. That is deliberate and it is the point: the adapter an operator
+ * deploys is the adapter the suite runs, so a test that passes is a test of the
+ * shipped thing rather than of a paraphrase of it.
+ *
+ * ## What this does that the Worker cannot
+ *
+ * **It migrates on open.** A Worker must not — `applySchema` is documented as the
+ * operator's to call, because a handler that migrates on first use migrates
+ * concurrently under load and D1 has no advisory lock to serialize it with. A
+ * single process opening a single file at startup has neither problem: it holds
+ * the file, it is not yet serving, and `BEGIN IMMEDIATE` is a real lock. So the
+ * one piece of ceremony a Cloudflare deployment cannot avoid is one this
+ * deployment does not have.
+ *
+ * **It refuses a database from the future.** A file at a `schema_version` this
+ * build has never heard of was written by a newer build, and the columns it would
+ * read are the ones it does not know are there. Opening it read-write is how a
+ * downgrade quietly writes rows the newer build then misreads.
+ */
+const { DatabaseSync: Database } = createRequire(import.meta.url)('node:sqlite');
+/**
+ * Open the file, bring it to {@link SCHEMA_VERSION}, and hand back a `D1Like`.
+ *
+ * Fresh file, deployed file and half-upgraded file are three cases and this is
+ * the only place that distinguishes them; every caller downstream gets a
+ * database at the current version or an exception with a sentence in it.
+ */
+export async function openDatabase(path) {
+    const database = new Database(path);
+    // WAL, because a reviewer reading a build while CI posts one is the ordinary
+    // case and rollback-journal SQLite blocks readers behind that writer.
+    // `busy_timeout` is the other half: two writers now wait rather than one
+    // failing instantly with SQLITE_BUSY.
+    database.exec('PRAGMA journal_mode = WAL');
+    database.exec('PRAGMA busy_timeout = 5000');
+    database.exec('PRAGMA foreign_keys = ON');
+    const db = wrapSqlite(database);
+    const version = await migrate(db);
+    return Object.assign(db, { path, version });
+}
+/** The version a file is at, or `null` for a database with no schema yet. */
+export async function schemaVersionOf(db) {
+    const table = await db
+        .prepare(`SELECT name FROM sqlite_schema WHERE type = 'table' AND name = 'schema_version'`)
+        .first();
+    if (table === null)
+        return null;
+    const row = await db.prepare('SELECT version FROM schema_version').first();
+    if (row === null || typeof row.version !== 'number') {
+        throw new Error('this database has a `schema_version` table with no version in it. That is not a state ' +
+            'any migration here can produce, so the file was edited by something else; point ' +
+            '`--database` at a new path rather than letting a repair guess what the rest of the rows mean');
+    }
+    return row.version;
+}
+async function migrate(db) {
+    const version = await schemaVersionOf(db);
+    if (version === null) {
+        await applySchema(db);
+        return SCHEMA_VERSION;
+    }
+    if (version === SCHEMA_VERSION)
+        return version;
+    if (version > SCHEMA_VERSION) {
+        db.close();
+        throw new Error(`this database is at schema version ${version} and this build knows ${SCHEMA_VERSION}. It ` +
+            'was written by a newer @variance-authority/tribunal, and the columns that build added ' +
+            'are the ones this one does not know to write. Upgrade the service rather than ' +
+            'downgrading the record');
+    }
+    if (version < INITIAL_VERSION) {
+        db.close();
+        throw new Error(`this database is at schema version ${version}, which predates the first published shape ` +
+            `(${INITIAL_VERSION}). There is no step from it, because there was never a released ` +
+            'build that wrote it');
+    }
+    // Each step ends by writing the version it lands on, and each runs in its own
+    // batch — so an interrupted upgrade leaves the file at a version whose shape it
+    // actually has, and the next open resumes from there rather than replaying a
+    // step that already landed.
+    for (const step of MIGRATIONS.slice(version - INITIAL_VERSION)) {
+        await db.batch(step.map((statement) => db.prepare(statement)));
+    }
+    return SCHEMA_VERSION;
+}
+/**
+ * The wrapper itself: `node:sqlite` in, {@link D1Like} out.
+ *
+ * The one behavioural difference from a `DatabaseSync` used directly is that
+ * `first` answers `null` where `get` answers `undefined`. That is not cosmetic:
+ * `null` is D1's "no row", the whole store distinguishes it from a failure, and a
+ * wrapper that returned `undefined` would let a `=== null` check silently stop
+ * being true.
+ */
+export function wrapSqlite(database) {
+    const statement = (sql, values) => ({
+        bind: (...bound) => statement(sql, bound),
+        async first() {
+            const row = database.prepare(sql).get(...inputs(values));
+            return row === undefined ? null : row;
+        },
+        async all() {
+            return { results: database.prepare(sql).all(...inputs(values)) };
+        },
+        async run() {
+            return database.prepare(sql).run(...inputs(values));
+        },
+    });
+    return {
+        prepare: (sql) => statement(sql, []),
+        /**
+         * All of them, or none of them.
+         *
+         * D1 documents `batch` as running inside an implicit transaction that rolls
+         * back on any failure, and the history backend's atomicity requirement rests
+         * entirely on that. Here it is a real `BEGIN IMMEDIATE`, so a caller that
+         * expects a half-written run to leave nothing behind is getting the property
+         * rather than the platform's description of it.
+         */
+        async batch(statements) {
+            database.exec('BEGIN IMMEDIATE');
+            try {
+                const results = [];
+                for (const prepared of statements)
+                    results.push(await prepared.run());
+                database.exec('COMMIT');
+                return results;
+            }
+            catch (error) {
+                database.exec('ROLLBACK');
+                throw error;
+            }
+        },
+        close: () => database.close(),
+    };
+}
+/**
+ * `node:sqlite` accepts `null`, numbers, strings and `Uint8Array`; D1 speaks
+ * `ArrayBuffer`. One conversion, in the one place the two vocabularies meet.
+ */
+function inputs(values) {
+    return values.map((value) => (value instanceof ArrayBuffer ? new Uint8Array(value) : value));
+}
+//# sourceMappingURL=database.js.map

package/dist/node/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/node/database.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRequire } from 'node:module';\nimport type { DatabaseSync, SQLInputValue } from 'node:sqlite';\nimport type { D1Like, D1PreparedLike, D1Value } from '../bindings.js';\nimport { INITIAL_VERSION, MIGRATIONS, SCHEMA_VERSION, applySchema } from '../schema.js';\n\n/**\n * D1, as a file on a disk somebody owns.\n *\n * D1 *is* SQLite, so this is an adapter rather than a port: the same `SCHEMA`,\n * the same indexes, the same append-only triggers and the same `ON CONFLICT`\n * clauses execute here, through `node:sqlite`, that a Worker executes through the\n * platform. Nothing above this file knows which one it got — `review.ts`,\n * `store.ts` and `history.ts` take a {@link D1Like} and have never named a\n * runtime.\n *\n * The double in [`testing.ts`](../testing.ts) is this same wrapper over\n * `':memory:'`. That is deliberate and it is the point: the adapter an operator\n * deploys is the adapter the suite runs, so a test that passes is a test of the\n * shipped thing rather than of a paraphrase of it.\n *\n * ## What this does that the Worker cannot\n *\n * **It migrates on open.** A Worker must not — `applySchema` is documented as the\n * operator's to call, because a handler that migrates on first use migrates\n * concurrently under load and D1 has no advisory lock to serialize it with. A\n * single process opening a single file at startup has neither problem: it holds\n * the file, it is not yet serving, and `BEGIN IMMEDIATE` is a real lock. So the\n * one piece of ceremony a Cloudflare deployment cannot avoid is one this\n * deployment does not have.\n *\n * **It refuses a database from the future.** A file at a `schema_version` this\n * build has never heard of was written by a newer build, and the columns it would\n * read are the ones it does not know are there. Opening it read-write is how a\n * downgrade quietly writes rows the newer build then misreads.\n */\n\nconst { DatabaseSync: Database } = createRequire(import.meta.url)('node:sqlite') as {\n  DatabaseSync: new (path: string) => DatabaseSync;\n};\n\nexport interface SqliteDatabase extends D1Like {\n  /** Ends the process's hold on the file. `':memory:'` disappears with it. */\n  close(): void;\n}\n\nexport interface TribunalDatabase extends SqliteDatabase {\n  /** Where it actually landed, absolute — printed at startup so it can be found again. */\n  readonly path: string;\n  /** The version the file is at once {@link openDatabase} has returned. */\n  readonly version: number;\n}\n\n/**\n * Open the file, bring it to {@link SCHEMA_VERSION}, and hand back a `D1Like`.\n *\n * Fresh file, deployed file and half-upgraded file are three cases and this is\n * the only place that distinguishes them; every caller downstream gets a\n * database at the current version or an exception with a sentence in it.\n */\nexport async function openDatabase(path: string): Promise<TribunalDatabase> {\n  const database = new Database(path);\n\n  // WAL, because a reviewer reading a build while CI posts one is the ordinary\n  // case and rollback-journal SQLite blocks readers behind that writer.\n  // `busy_timeout` is the other half: two writers now wait rather than one\n  // failing instantly with SQLITE_BUSY.\n  database.exec('PRAGMA journal_mode = WAL');\n  database.exec('PRAGMA busy_timeout = 5000');\n  database.exec('PRAGMA foreign_keys = ON');\n\n  const db = wrapSqlite(database);\n  const version = await migrate(db);\n  return Object.assign(db, { path, version });\n}\n\n/** The version a file is at, or `null` for a database with no schema yet. */\nexport async function schemaVersionOf(db: D1Like): Promise<number | null> {\n  const table = await db\n    .prepare(`SELECT name FROM sqlite_schema WHERE type = 'table' AND name = 'schema_version'`)\n    .first<{ readonly name: string }>();\n  if (table === null) return null;\n\n  const row = await db.prepare('SELECT version FROM schema_version').first<{ readonly version: number }>();\n  if (row === null || typeof row.version !== 'number') {\n    throw new Error(\n      'this database has a `schema_version` table with no version in it. That is not a state ' +\n        'any migration here can produce, so the file was edited by something else; point ' +\n        '`--database` at a new path rather than letting a repair guess what the rest of the rows mean',\n    );\n  }\n  return row.version;\n}\n\nasync function migrate(db: SqliteDatabase): Promise<number> {\n  const version = await schemaVersionOf(db);\n\n  if (version === null) {\n    await applySchema(db);\n    return SCHEMA_VERSION;\n  }\n\n  if (version === SCHEMA_VERSION) return version;\n\n  if (version > SCHEMA_VERSION) {\n    db.close();\n    throw new Error(\n      `this database is at schema version ${version} and this build knows ${SCHEMA_VERSION}. It ` +\n        'was written by a newer @variance-authority/tribunal, and the columns that build added ' +\n        'are the ones this one does not know to write. Upgrade the service rather than ' +\n        'downgrading the record',\n    );\n  }\n\n  if (version < INITIAL_VERSION) {\n    db.close();\n    throw new Error(\n      `this database is at schema version ${version}, which predates the first published shape ` +\n        `(${INITIAL_VERSION}). There is no step from it, because there was never a released ` +\n        'build that wrote it',\n    );\n  }\n\n  // Each step ends by writing the version it lands on, and each runs in its own\n  // batch — so an interrupted upgrade leaves the file at a version whose shape it\n  // actually has, and the next open resumes from there rather than replaying a\n  // step that already landed.\n  for (const step of MIGRATIONS.slice(version - INITIAL_VERSION)) {\n    await db.batch(step.map((statement) => db.prepare(statement)));\n  }\n  return SCHEMA_VERSION;\n}\n\n/**\n * The wrapper itself: `node:sqlite` in, {@link D1Like} out.\n *\n * The one behavioural difference from a `DatabaseSync` used directly is that\n * `first` answers `null` where `get` answers `undefined`. That is not cosmetic:\n * `null` is D1's \"no row\", the whole store distinguishes it from a failure, and a\n * wrapper that returned `undefined` would let a `=== null` check silently stop\n * being true.\n */\nexport function wrapSqlite(database: DatabaseSync): SqliteDatabase {\n  const statement = (sql: string, values: readonly D1Value[]): D1PreparedLike => ({\n    bind: (...bound: readonly D1Value[]) => statement(sql, bound),\n    async first<Row>(): Promise<Row | null> {\n      const row = database.prepare(sql).get(...inputs(values));\n      return row === undefined ? null : (row as Row);\n    },\n    async all<Row>(): Promise<{ readonly results: readonly Row[] }> {\n      return { results: database.prepare(sql).all(...inputs(values)) as Row[] };\n    },\n    async run(): Promise<unknown> {\n      return database.prepare(sql).run(...inputs(values));\n    },\n  });\n\n  return {\n    prepare: (sql: string) => statement(sql, []),\n\n    /**\n     * All of them, or none of them.\n     *\n     * D1 documents `batch` as running inside an implicit transaction that rolls\n     * back on any failure, and the history backend's atomicity requirement rests\n     * entirely on that. Here it is a real `BEGIN IMMEDIATE`, so a caller that\n     * expects a half-written run to leave nothing behind is getting the property\n     * rather than the platform's description of it.\n     */\n    async batch(statements: readonly D1PreparedLike[]): Promise<unknown> {\n      database.exec('BEGIN IMMEDIATE');\n      try {\n        const results: unknown[] = [];\n        for (const prepared of statements) results.push(await prepared.run());\n        database.exec('COMMIT');\n        return results;\n      } catch (error) {\n        database.exec('ROLLBACK');\n        throw error;\n      }\n    },\n\n    close: () => database.close(),\n  };\n}\n\n/**\n * `node:sqlite` accepts `null`, numbers, strings and `Uint8Array`; D1 speaks\n * `ArrayBuffer`. One conversion, in the one place the two vocabularies meet.\n */\nfunction inputs(values: readonly D1Value[]): SQLInputValue[] {\n  return values.map((value) => (value instanceof ArrayBuffer ? new Uint8Array(value) : value));\n}\n"]}

package/dist/node/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The service, on a machine somebody owns — a file, a directory and a port.
+ *
+ * The same review service `./worker` serves on Cloudflare. D1 is SQLite through
+ * `node:sqlite`, R2 is a directory through `node:fs`, and the router between them
+ * is byte-for-byte the code a Worker runs, because every module above the
+ * bindings takes a `D1Like` and an `R2Like` and has never named a runtime.
+ *
+ * Requires Node 22 for `node:sqlite`, which is why it is its own entrypoint: a
+ * Worker importing `@variance-authority/tribunal/worker` must not pull a Node
+ * built-in into its bundle to do it.
+ *
+ * ```ts
+ * import { createDirectoryBucket, openDatabase, serveTribunal } from '@variance-authority/tribunal/node';
+ * import { createTribunal } from '@variance-authority/tribunal/worker';
+ *
+ * const db = await openDatabase('variance-tribunal.db');
+ * const tribunal = createTribunal({
+ *   db,
+ *   bucket: createDirectoryBucket('variance-tribunal-objects'),
+ *   project: 'todomvc',
+ *   ingestToken: process.env.INGEST_TOKEN!,
+ *   reviewToken: process.env.REVIEW_TOKEN!,
+ * });
+ *
+ * await serveTribunal({
+ *   tribunal,
+ *   host: '127.0.0.1',
+ *   port: 7789,
+ *   authorize: () => 'review',
+ *   tokens: { ingest: process.env.INGEST_TOKEN!, review: process.env.REVIEW_TOKEN! },
+ * });
+ * ```
+ *
+ * Or run `variance-authority-tribunal` and configure it with an environment —
+ * [`bin.ts`](./bin.ts) is that program, and the policy it applies is written out
+ * there rather than assumed here.
+ */
+export { createDirectoryBucket, type DirectoryBucket } from './bucket.js';
+export { openDatabase, schemaVersionOf, wrapSqlite, type SqliteDatabase, type TribunalDatabase, } from './database.js';
+export { MAX_BODY_BYTES, createRequestListener, serveTribunal, type TribunalService, type TribunalServiceOptions, } from './serve.js';
+export { reviewPage, uiAsset, type ReviewPageOptions } from './ui-assets.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.js

@@ -0,0 +1,43 @@
+/**
+ * The service, on a machine somebody owns — a file, a directory and a port.
+ *
+ * The same review service `./worker` serves on Cloudflare. D1 is SQLite through
+ * `node:sqlite`, R2 is a directory through `node:fs`, and the router between them
+ * is byte-for-byte the code a Worker runs, because every module above the
+ * bindings takes a `D1Like` and an `R2Like` and has never named a runtime.
+ *
+ * Requires Node 22 for `node:sqlite`, which is why it is its own entrypoint: a
+ * Worker importing `@variance-authority/tribunal/worker` must not pull a Node
+ * built-in into its bundle to do it.
+ *
+ * ```ts
+ * import { createDirectoryBucket, openDatabase, serveTribunal } from '@variance-authority/tribunal/node';
+ * import { createTribunal } from '@variance-authority/tribunal/worker';
+ *
+ * const db = await openDatabase('variance-tribunal.db');
+ * const tribunal = createTribunal({
+ *   db,
+ *   bucket: createDirectoryBucket('variance-tribunal-objects'),
+ *   project: 'todomvc',
+ *   ingestToken: process.env.INGEST_TOKEN!,
+ *   reviewToken: process.env.REVIEW_TOKEN!,
+ * });
+ *
+ * await serveTribunal({
+ *   tribunal,
+ *   host: '127.0.0.1',
+ *   port: 7789,
+ *   authorize: () => 'review',
+ *   tokens: { ingest: process.env.INGEST_TOKEN!, review: process.env.REVIEW_TOKEN! },
+ * });
+ * ```
+ *
+ * Or run `variance-authority-tribunal` and configure it with an environment —
+ * [`bin.ts`](./bin.ts) is that program, and the policy it applies is written out
+ * there rather than assumed here.
+ */
+export { createDirectoryBucket } from './bucket.js';
+export { openDatabase, schemaVersionOf, wrapSqlite, } from './database.js';
+export { MAX_BODY_BYTES, createRequestListener, serveTribunal, } from './serve.js';
+export { reviewPage, uiAsset } from './ui-assets.js';
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,qBAAqB,EAAwB,MAAM,aAAa,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,eAAe,EACf,UAAU,GAGX,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,aAAa,GAGd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,OAAO,EAA0B,MAAM,gBAAgB,CAAC","sourcesContent":["/**\n * The service, on a machine somebody owns — a file, a directory and a port.\n *\n * The same review service `./worker` serves on Cloudflare. D1 is SQLite through\n * `node:sqlite`, R2 is a directory through `node:fs`, and the router between them\n * is byte-for-byte the code a Worker runs, because every module above the\n * bindings takes a `D1Like` and an `R2Like` and has never named a runtime.\n *\n * Requires Node 22 for `node:sqlite`, which is why it is its own entrypoint: a\n * Worker importing `@variance-authority/tribunal/worker` must not pull a Node\n * built-in into its bundle to do it.\n *\n * ```ts\n * import { createDirectoryBucket, openDatabase, serveTribunal } from '@variance-authority/tribunal/node';\n * import { createTribunal } from '@variance-authority/tribunal/worker';\n *\n * const db = await openDatabase('variance-tribunal.db');\n * const tribunal = createTribunal({\n *   db,\n *   bucket: createDirectoryBucket('variance-tribunal-objects'),\n *   project: 'todomvc',\n *   ingestToken: process.env.INGEST_TOKEN!,\n *   reviewToken: process.env.REVIEW_TOKEN!,\n * });\n *\n * await serveTribunal({\n *   tribunal,\n *   host: '127.0.0.1',\n *   port: 7789,\n *   authorize: () => 'review',\n *   tokens: { ingest: process.env.INGEST_TOKEN!, review: process.env.REVIEW_TOKEN! },\n * });\n * ```\n *\n * Or run `variance-authority-tribunal` and configure it with an environment —\n * [`bin.ts`](./bin.ts) is that program, and the policy it applies is written out\n * there rather than assumed here.\n */\n\nexport { createDirectoryBucket, type DirectoryBucket } from './bucket.js';\nexport {\n  openDatabase,\n  schemaVersionOf,\n  wrapSqlite,\n  type SqliteDatabase,\n  type TribunalDatabase,\n} from './database.js';\nexport {\n  MAX_BODY_BYTES,\n  createRequestListener,\n  serveTribunal,\n  type TribunalService,\n  type TribunalServiceOptions,\n} from './serve.js';\nexport { reviewPage, uiAsset, type ReviewPageOptions } from './ui-assets.js';\n"]}

package/dist/node/serve.d.ts

@@ -0,0 +1,81 @@
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { Tribunal } from '../worker.js';
+/**
+ * The socket: `node:http` in, {@link Tribunal.fetch} out.
+ *
+ * A Worker handler is `(Request) => Promise<Response>` and a Node server is
+ * `(IncomingMessage, ServerResponse) => void`, and the whole of this file is the
+ * conversion between those two plus the two decisions the conversion forces.
+ * Nothing here knows what a build is; every route, every refusal and every status
+ * code is the same code a Cloudflare deployment runs.
+ *
+ * Shaped after [`server/http.ts`](../../../server/src/http.ts): `node:http`, no
+ * framework, and no logic of its own beyond transport.
+ *
+ * ## The two decisions
+ *
+ * **A body has a ceiling.** A Worker gets one from the platform; a Node process
+ * gets one from whoever wrote the reader. An unbounded `POST /review/builds`
+ * carrying three hundred base64 PNGs is a heap the operator did not budget for,
+ * and the failure mode is the process dying rather than the request being
+ * refused. So there is a limit, it is a number, and exceeding it is a 413 with a
+ * sentence rather than an OOM.
+ *
+ * **Who may review is not this file's to assume.** The review token promotes
+ * baselines, so a browser must never hold it — the argument is in
+ * [`next.ts`](../next.ts) and it does not change because the host did. So
+ * `authorize` is required here too, and the mount reuses `createTribunalRoutes`
+ * rather than re-deriving the token-attaching rule: one implementation of "which
+ * capability is this caller allowed" means the Node service and the Next.js app
+ * cannot drift into two answers.
+ */
+/**
+ * Largest request body accepted, in bytes.
+ *
+ * 256 MiB: a build posts every image it kept, base64-encoded, in one JSON
+ * document, and a wide Storybook at two device scales gets big. It is a ceiling
+ * on damage rather than a target — an operator whose builds approach it should
+ * be keeping fewer images, not raising this.
+ */
+export declare const MAX_BODY_BYTES: number;
+export interface TribunalServiceOptions {
+    readonly tribunal: Tribunal;
+    /**
+     * Which capability a request is allowed. No default — see the note above.
+     *
+     * The shipped policy is in [`bin.ts`](./bin.ts), where an operator can read it.
+     */
+    authorize(request: Request): Promise<'ingest' | 'review' | null> | 'ingest' | 'review' | null;
+    /** The tokens the tribunal was constructed with, for the mount to attach. */
+    readonly tokens: {
+        readonly ingest: string;
+        readonly review: string;
+    };
+    /**
+     * Serve the review surface at `/`, not just the JSON API.
+     *
+     * Default `true`. Off is for a deployment that only ingests — a service behind
+     * CI with no reviewer on it — where a page nobody opens is a page nobody has to
+     * authorize.
+     */
+    readonly ui?: boolean;
+    /** Shown in the surface as who is deciding. The record carries it on every approval. */
+    readonly reviewer?: string;
+}
+export interface TribunalService {
+    readonly server: Server;
+    /** Where it is actually listening, with the port the OS chose if `0` was asked for. */
+    readonly url: string;
+    close(): Promise<void>;
+}
+/** Listen, and resolve once the socket is accepting. */
+export declare function serveTribunal(options: TribunalServiceOptions & {
+    readonly host: string;
+    readonly port: number;
+}): Promise<TribunalService>;
+/**
+ * The handler, without the socket — so a test can drive it and a host that
+ * already owns its listener can mount it.
+ */
+export declare function createRequestListener(options: TribunalServiceOptions): (request: IncomingMessage, response: ServerResponse) => void;
+//# sourceMappingURL=serve.d.ts.map

package/dist/node/serve.js

@@ -0,0 +1,193 @@
+import { createServer } from 'node:http';
+import { createTribunalRoutes } from '../next.js';
+import { isPagePath } from '../ui/route.js';
+import { reviewPage, uiAsset } from './ui-assets.js';
+/**
+ * The socket: `node:http` in, {@link Tribunal.fetch} out.
+ *
+ * A Worker handler is `(Request) => Promise<Response>` and a Node server is
+ * `(IncomingMessage, ServerResponse) => void`, and the whole of this file is the
+ * conversion between those two plus the two decisions the conversion forces.
+ * Nothing here knows what a build is; every route, every refusal and every status
+ * code is the same code a Cloudflare deployment runs.
+ *
+ * Shaped after [`server/http.ts`](../../../server/src/http.ts): `node:http`, no
+ * framework, and no logic of its own beyond transport.
+ *
+ * ## The two decisions
+ *
+ * **A body has a ceiling.** A Worker gets one from the platform; a Node process
+ * gets one from whoever wrote the reader. An unbounded `POST /review/builds`
+ * carrying three hundred base64 PNGs is a heap the operator did not budget for,
+ * and the failure mode is the process dying rather than the request being
+ * refused. So there is a limit, it is a number, and exceeding it is a 413 with a
+ * sentence rather than an OOM.
+ *
+ * **Who may review is not this file's to assume.** The review token promotes
+ * baselines, so a browser must never hold it — the argument is in
+ * [`next.ts`](../next.ts) and it does not change because the host did. So
+ * `authorize` is required here too, and the mount reuses `createTribunalRoutes`
+ * rather than re-deriving the token-attaching rule: one implementation of "which
+ * capability is this caller allowed" means the Node service and the Next.js app
+ * cannot drift into two answers.
+ */
+/**
+ * Largest request body accepted, in bytes.
+ *
+ * 256 MiB: a build posts every image it kept, base64-encoded, in one JSON
+ * document, and a wide Storybook at two device scales gets big. It is a ceiling
+ * on damage rather than a target — an operator whose builds approach it should
+ * be keeping fewer images, not raising this.
+ */
+export const MAX_BODY_BYTES = 256 * 1024 * 1024;
+/** Listen, and resolve once the socket is accepting. */
+export async function serveTribunal(options) {
+    const server = createServer(createRequestListener(options));
+    await new Promise((accept, refuse) => {
+        server.once('error', refuse);
+        server.listen(options.port, options.host, () => {
+            server.removeListener('error', refuse);
+            accept();
+        });
+    });
+    const address = server.address();
+    const host = address.family === 'IPv6' ? `[${address.address}]` : address.address;
+    return {
+        server,
+        url: `http://${host}:${address.port}`,
+        close: () => new Promise((accept, refuse) => {
+            server.close((error) => (error === undefined ? accept() : refuse(error)));
+        }),
+    };
+}
+/**
+ * The handler, without the socket — so a test can drive it and a host that
+ * already owns its listener can mount it.
+ */
+export function createRequestListener(options) {
+    const mounted = createTribunalRoutes(options.tribunal, {
+        authorize: options.authorize,
+        tokens: options.tokens,
+    });
+    const serveUi = options.ui ?? true;
+    return (incoming, outgoing) => {
+        void (async () => {
+            try {
+                const request = await requestOf(incoming);
+                const asset = serveUi ? await pageOrAsset(request, options.reviewer) : null;
+                const response = asset ?? (await mounted[method(request)](request));
+                await write(outgoing, response);
+            }
+            catch (error) {
+                await write(outgoing, refusal(error));
+            }
+        })();
+    };
+}
+/**
+ * The surface and its bundle, ahead of the API.
+ *
+ * Which paths are pages is not decided here. [`ui/route.ts`](../ui/route.ts)
+ * holds the table, the browser reads it to turn a path into a view, and this
+ * reads the same table to decide who gets the document — because the alternative
+ * is two lists, and they drift in the worst direction: a link the client renders
+ * happily and the server answers with a 404.
+ *
+ * Still no prefix match. Every pattern is anchored and none of them shares a
+ * first segment with an API route; `serve.test.ts` holds the two apart rather
+ * than trusting the reading, since this file must not be the reason a request
+ * never reached the router.
+ */
+async function pageOrAsset(request, reviewer) {
+    const path = new URL(request.url).pathname;
+    if (request.method !== 'GET' && request.method !== 'HEAD')
+        return null;
+    if (isPagePath(path)) {
+        return new Response(reviewPage({ endpoint: '', ...(reviewer === undefined ? {} : { reviewer }) }), {
+            headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
+        });
+    }
+    if (path === '/ui/review.js') {
+        const bundle = await uiAsset();
+        if (bundle === null)
+            return null;
+        return new Response(bundle, {
+            headers: {
+                'content-type': 'text/javascript; charset=utf-8',
+                // Immutable because the file changes only when the package does, and a
+                // reviewer who upgrades gets a new process on a new URL-less asset —
+                // so this is a lie the moment the bundle is rebuilt in place. It is
+                // therefore `no-cache`: revalidate, do not re-download.
+                'cache-control': 'no-cache',
+            },
+        });
+    }
+    return null;
+}
+function method(request) {
+    if (request.method === 'POST')
+        return 'POST';
+    if (request.method === 'HEAD')
+        return 'HEAD';
+    return 'GET';
+}
+/** `IncomingMessage` → `Request`, with the body read to a ceiling. */
+async function requestOf(incoming) {
+    const url = new URL(incoming.url ?? '/', `http://${incoming.headers.host ?? 'localhost'}`);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(incoming.headers)) {
+        if (value === undefined)
+            continue;
+        for (const one of Array.isArray(value) ? value : [value])
+            headers.append(name, one);
+    }
+    const method = incoming.method ?? 'GET';
+    if (method === 'GET' || method === 'HEAD') {
+        return new Request(url, { method, headers });
+    }
+    return new Request(url, { method, headers, body: await body(incoming) });
+}
+async function body(incoming) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of incoming) {
+        size += chunk.byteLength;
+        if (size > MAX_BODY_BYTES) {
+            incoming.destroy();
+            throw new PayloadTooLarge(`this request body is over ${MAX_BODY_BYTES} bytes, which is the ceiling this service ` +
+                'accepts. A build carrying every image it kept is the way this happens; keep fewer ' +
+                'images, or split the build across two posts');
+        }
+        chunks.push(chunk);
+    }
+    const joined = Buffer.concat(chunks);
+    return joined.buffer.slice(joined.byteOffset, joined.byteOffset + joined.byteLength);
+}
+/** `Response` → `ServerResponse`. */
+async function write(outgoing, response) {
+    for (const [name, value] of response.headers)
+        outgoing.setHeader(name, value);
+    outgoing.statusCode = response.status;
+    if (response.body === null) {
+        outgoing.end();
+        return;
+    }
+    outgoing.end(Buffer.from(await response.arrayBuffer()));
+}
+class PayloadTooLarge extends Error {
+}
+/**
+ * An exception is a 500 with a sentence, and a refused body is a 413.
+ *
+ * Nothing in `Tribunal.fetch` throws — it answers with a status — so anything
+ * arriving here is transport or a construction failure, and the operator reading
+ * it is the person who can fix it. The message is theirs; the stack is not.
+ */
+function refusal(error) {
+    const message = error instanceof Error ? error.message : 'this service could not answer';
+    return new Response(JSON.stringify({ error: message }), {
+        status: error instanceof PayloadTooLarge ? 413 : 500,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+    });
+}
+//# sourceMappingURL=serve.js.map

package/dist/node/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/node/serve.ts"],"names":[],"mappings":"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","sourcesContent":["import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\nimport type { AddressInfo } from 'node:net';\nimport { createTribunalRoutes } from '../next.js';\nimport type { Tribunal } from '../worker.js';\nimport { isPagePath } from '../ui/route.js';\nimport { reviewPage, uiAsset } from './ui-assets.js';\n\n/**\n * The socket: `node:http` in, {@link Tribunal.fetch} out.\n *\n * A Worker handler is `(Request) => Promise<Response>` and a Node server is\n * `(IncomingMessage, ServerResponse) => void`, and the whole of this file is the\n * conversion between those two plus the two decisions the conversion forces.\n * Nothing here knows what a build is; every route, every refusal and every status\n * code is the same code a Cloudflare deployment runs.\n *\n * Shaped after [`server/http.ts`](../../../server/src/http.ts): `node:http`, no\n * framework, and no logic of its own beyond transport.\n *\n * ## The two decisions\n *\n * **A body has a ceiling.** A Worker gets one from the platform; a Node process\n * gets one from whoever wrote the reader. An unbounded `POST /review/builds`\n * carrying three hundred base64 PNGs is a heap the operator did not budget for,\n * and the failure mode is the process dying rather than the request being\n * refused. So there is a limit, it is a number, and exceeding it is a 413 with a\n * sentence rather than an OOM.\n *\n * **Who may review is not this file's to assume.** The review token promotes\n * baselines, so a browser must never hold it — the argument is in\n * [`next.ts`](../next.ts) and it does not change because the host did. So\n * `authorize` is required here too, and the mount reuses `createTribunalRoutes`\n * rather than re-deriving the token-attaching rule: one implementation of \"which\n * capability is this caller allowed\" means the Node service and the Next.js app\n * cannot drift into two answers.\n */\n\n/**\n * Largest request body accepted, in bytes.\n *\n * 256 MiB: a build posts every image it kept, base64-encoded, in one JSON\n * document, and a wide Storybook at two device scales gets big. It is a ceiling\n * on damage rather than a target — an operator whose builds approach it should\n * be keeping fewer images, not raising this.\n */\nexport const MAX_BODY_BYTES = 256 * 1024 * 1024;\n\nexport interface TribunalServiceOptions {\n  readonly tribunal: Tribunal;\n  /**\n   * Which capability a request is allowed. No default — see the note above.\n   *\n   * The shipped policy is in [`bin.ts`](./bin.ts), where an operator can read it.\n   */\n  authorize(request: Request): Promise<'ingest' | 'review' | null> | 'ingest' | 'review' | null;\n  /** The tokens the tribunal was constructed with, for the mount to attach. */\n  readonly tokens: { readonly ingest: string; readonly review: string };\n  /**\n   * Serve the review surface at `/`, not just the JSON API.\n   *\n   * Default `true`. Off is for a deployment that only ingests — a service behind\n   * CI with no reviewer on it — where a page nobody opens is a page nobody has to\n   * authorize.\n   */\n  readonly ui?: boolean;\n  /** Shown in the surface as who is deciding. The record carries it on every approval. */\n  readonly reviewer?: string;\n}\n\nexport interface TribunalService {\n  readonly server: Server;\n  /** Where it is actually listening, with the port the OS chose if `0` was asked for. */\n  readonly url: string;\n  close(): Promise<void>;\n}\n\n/** Listen, and resolve once the socket is accepting. */\nexport async function serveTribunal(\n  options: TribunalServiceOptions & { readonly host: string; readonly port: number },\n): Promise<TribunalService> {\n  const server = createServer(createRequestListener(options));\n\n  await new Promise<void>((accept, refuse) => {\n    server.once('error', refuse);\n    server.listen(options.port, options.host, () => {\n      server.removeListener('error', refuse);\n      accept();\n    });\n  });\n\n  const address = server.address() as AddressInfo;\n  const host = address.family === 'IPv6' ? `[${address.address}]` : address.address;\n\n  return {\n    server,\n    url: `http://${host}:${address.port}`,\n    close: () =>\n      new Promise<void>((accept, refuse) => {\n        server.close((error) => (error === undefined ? accept() : refuse(error)));\n      }),\n  };\n}\n\n/**\n * The handler, without the socket — so a test can drive it and a host that\n * already owns its listener can mount it.\n */\nexport function createRequestListener(\n  options: TribunalServiceOptions,\n): (request: IncomingMessage, response: ServerResponse) => void {\n  const mounted = createTribunalRoutes(options.tribunal, {\n    authorize: options.authorize,\n    tokens: options.tokens,\n  });\n  const serveUi = options.ui ?? true;\n\n  return (incoming: IncomingMessage, outgoing: ServerResponse): void => {\n    void (async () => {\n      try {\n        const request = await requestOf(incoming);\n\n        const asset = serveUi ? await pageOrAsset(request, options.reviewer) : null;\n        const response = asset ?? (await mounted[method(request)](request));\n\n        await write(outgoing, response);\n      } catch (error) {\n        await write(outgoing, refusal(error));\n      }\n    })();\n  };\n}\n\n/**\n * The surface and its bundle, ahead of the API.\n *\n * Which paths are pages is not decided here. [`ui/route.ts`](../ui/route.ts)\n * holds the table, the browser reads it to turn a path into a view, and this\n * reads the same table to decide who gets the document — because the alternative\n * is two lists, and they drift in the worst direction: a link the client renders\n * happily and the server answers with a 404.\n *\n * Still no prefix match. Every pattern is anchored and none of them shares a\n * first segment with an API route; `serve.test.ts` holds the two apart rather\n * than trusting the reading, since this file must not be the reason a request\n * never reached the router.\n */\nasync function pageOrAsset(request: Request, reviewer?: string): Promise<Response | null> {\n  const path = new URL(request.url).pathname;\n  if (request.method !== 'GET' && request.method !== 'HEAD') return null;\n\n  if (isPagePath(path)) {\n    return new Response(reviewPage({ endpoint: '', ...(reviewer === undefined ? {} : { reviewer }) }), {\n      headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },\n    });\n  }\n\n  if (path === '/ui/review.js') {\n    const bundle = await uiAsset();\n    if (bundle === null) return null;\n    return new Response(bundle, {\n      headers: {\n        'content-type': 'text/javascript; charset=utf-8',\n        // Immutable because the file changes only when the package does, and a\n        // reviewer who upgrades gets a new process on a new URL-less asset —\n        // so this is a lie the moment the bundle is rebuilt in place. It is\n        // therefore `no-cache`: revalidate, do not re-download.\n        'cache-control': 'no-cache',\n      },\n    });\n  }\n\n  return null;\n}\n\nfunction method(request: Request): 'GET' | 'POST' | 'HEAD' {\n  if (request.method === 'POST') return 'POST';\n  if (request.method === 'HEAD') return 'HEAD';\n  return 'GET';\n}\n\n/** `IncomingMessage` → `Request`, with the body read to a ceiling. */\nasync function requestOf(incoming: IncomingMessage): Promise<Request> {\n  const url = new URL(incoming.url ?? '/', `http://${incoming.headers.host ?? 'localhost'}`);\n\n  const headers = new Headers();\n  for (const [name, value] of Object.entries(incoming.headers)) {\n    if (value === undefined) continue;\n    for (const one of Array.isArray(value) ? value : [value]) headers.append(name, one);\n  }\n\n  const method = incoming.method ?? 'GET';\n  if (method === 'GET' || method === 'HEAD') {\n    return new Request(url, { method, headers });\n  }\n\n  return new Request(url, { method, headers, body: await body(incoming) });\n}\n\nasync function body(incoming: IncomingMessage): Promise<ArrayBuffer> {\n  const chunks: Buffer[] = [];\n  let size = 0;\n\n  for await (const chunk of incoming) {\n    size += (chunk as Buffer).byteLength;\n    if (size > MAX_BODY_BYTES) {\n      incoming.destroy();\n      throw new PayloadTooLarge(\n        `this request body is over ${MAX_BODY_BYTES} bytes, which is the ceiling this service ` +\n          'accepts. A build carrying every image it kept is the way this happens; keep fewer ' +\n          'images, or split the build across two posts',\n      );\n    }\n    chunks.push(chunk as Buffer);\n  }\n\n  const joined = Buffer.concat(chunks);\n  return joined.buffer.slice(joined.byteOffset, joined.byteOffset + joined.byteLength) as ArrayBuffer;\n}\n\n/** `Response` → `ServerResponse`. */\nasync function write(outgoing: ServerResponse, response: Response): Promise<void> {\n  for (const [name, value] of response.headers) outgoing.setHeader(name, value);\n  outgoing.statusCode = response.status;\n\n  if (response.body === null) {\n    outgoing.end();\n    return;\n  }\n  outgoing.end(Buffer.from(await response.arrayBuffer()));\n}\n\nclass PayloadTooLarge extends Error {}\n\n/**\n * An exception is a 500 with a sentence, and a refused body is a 413.\n *\n * Nothing in `Tribunal.fetch` throws — it answers with a status — so anything\n * arriving here is transport or a construction failure, and the operator reading\n * it is the person who can fix it. The message is theirs; the stack is not.\n */\nfunction refusal(error: unknown): Response {\n  const message = error instanceof Error ? error.message : 'this service could not answer';\n  return new Response(JSON.stringify({ error: message }), {\n    status: error instanceof PayloadTooLarge ? 413 : 500,\n    headers: { 'content-type': 'application/json; charset=utf-8' },\n  });\n}\n"]}