@hadoku/service-kernel 0.0.0-stage → 0.1.4

package/dist/lifecycle/announce.js

@@ -0,0 +1,232 @@
+/*
+ * Prod posts its release's patch notes to a Discord server's #announcements at boot, through
+ * ArchiveBot's signed `/api/messages/send` (contract: docs/requests/ARCHIVEBOT_DISCORD_INTEGRATION_REPLY.md).
+ *
+ * The release is the newest `vX.Y.Z.md` release notes file in the tree. Every boot sends; the
+ * idempotency key `<service>-release-<version>` is deduped by ArchiveBot for 7 days, so a restart
+ * posts nothing new.
+ *
+ * A bug's reporter is named in its bullet as `@name` (their hadoku name; docs/RELEASE.md § "Attribution").
+ * Those names ride as `mentions`, and ArchiveBot turns each `@name` in the notes into the person's
+ * Discord mention, inline where the bullet credits them. No separate thank-you line.
+ *
+ * `secret` is the app's webhook secret (empty = skip, never an error); a failed post never blocks
+ * boot, and the next boot retries it.
+ *
+ * `ordering` decides which release files are newest: the kernel does not read a release-notes
+ * directory layout itself. The app supplies it (cardtable's adapter injects
+ * `scripts/release/build-version.ts`'s `newestReleaseFile`/`releaseFilesNewestFirst`, since the
+ * kernel cannot import `scripts/`).
+ *
+ * Imports only; nothing runs at import.
+ */
+import { createHmac } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** ArchiveBot's per-embed description cap. */
+const DESCRIPTION_MAX = 4096;
+/** The newest release notes in `dir`, by `ordering`, or null when there are none. */
+export async function latestRelease(dir, ordering) {
+    const newest = ordering.newest(await readdir(dir));
+    if (newest === null)
+        return null;
+    return parseNotes(newest.slice(0, -'.md'.length), await readFile(join(dir, newest), 'utf8'));
+}
+/**
+ * How many releases, newest first, a boot re-sends as edits. ArchiveBot keeps a post's record for 7
+ * days and refuses an edit it has no record of, so older notes cannot be changed this way anyway.
+ */
+export const EDITABLE_RELEASES = 3;
+/** The newest `count` release notes in `dir`, newest first, by `ordering`. */
+export async function recentReleases(dir, ordering, count = EDITABLE_RELEASES) {
+    const names = ordering.newestFirst(await readdir(dir)).slice(0, count);
+    return Promise.all(names.map(async (name) => parseNotes(name.slice(0, -'.md'.length), await readFile(join(dir, name), 'utf8'))));
+}
+/** The `# ` heading is the title; everything after it is the body. */
+export function parseNotes(version, text) {
+    const lines = text.split('\n');
+    const at = lines.findIndex((line) => line.startsWith('# '));
+    if (at === -1)
+        return { version, title: version, body: text.trim() };
+    return { version, title: lines[at].slice(2).trim(), body: lines.slice(at + 1).join('\n').trim() };
+}
+/**
+ * The body cut into descriptions of at most 4096 characters: whole `## ` sections packed in order,
+ * and a section that alone is too long cut at line breaks. Never truncated.
+ */
+export function splitBody(body, max = DESCRIPTION_MAX) {
+    const sections = body.split(/\n(?=## )/);
+    const pieces = sections.flatMap((section) => (section.length <= max ? [section] : splitLines(section, max)));
+    const out = [];
+    for (const piece of pieces) {
+        const last = out.length - 1;
+        if (last >= 0 && out[last].length + 1 + piece.length <= max)
+            out[last] = `${out[last]}\n${piece}`;
+        else
+            out.push(piece);
+    }
+    return out.map((d) => d.trim()).filter((d) => d !== '');
+}
+function splitLines(section, max) {
+    const out = [];
+    let current = '';
+    for (const line of section.split('\n')) {
+        // A single line past the cap is cut where it stands; nothing in a notes file comes close.
+        for (let rest = line;; rest = rest.slice(max)) {
+            const chunk = rest.slice(0, max);
+            if (current === '')
+                current = chunk;
+            else if (current.length + 1 + chunk.length <= max)
+                current = `${current}\n${chunk}`;
+            else {
+                out.push(current);
+                current = chunk;
+            }
+            if (rest.length <= max)
+                break;
+        }
+    }
+    if (current !== '')
+        out.push(current);
+    return out;
+}
+/** A line that starts its own block in Markdown: a heading, a list item, a quote, a fence. */
+const BLOCK_START = /^\s*(#|[-*+] |\d+\. |>|```)/;
+/**
+ * The body as Discord should get it. Discord breaks the line at every newline it is sent, and a
+ * notes file is wrapped at about a hundred columns, so a line that continues the one above is
+ * joined to it. Discord also spaces a heading by itself, so a blank line beside one would double
+ * the gap: those go. Other blank lines, block starts and anything inside a code fence stay.
+ */
+export function forDiscord(body) {
+    const out = [];
+    let fenced = false;
+    for (const line of body.split('\n')) {
+        const fence = line.trimStart().startsWith('```');
+        const last = out.length - 1;
+        if (!fenced && !fence && line.trim() !== '' && last >= 0 && out[last].trim() !== '' && !BLOCK_START.test(line) && !out[last].trimStart().startsWith('#')) {
+            out[last] = `${out[last].trimEnd()} ${line.trim()}`;
+        }
+        else {
+            out.push(line);
+        }
+        if (fence)
+            fenced = !fenced;
+    }
+    const heading = (line) => line !== undefined && line.trimStart().startsWith('#');
+    return out.filter((line, i) => line.trim() !== '' || !(heading(out[i - 1]) || heading(out[i + 1]))).join('\n');
+}
+/**
+ * Who a release thanks: every `@name` in its notes, the hadoku name of whoever reported a bug the
+ * release fixes (docs/RELEASE.md § "Attribution"), each once, in the order the notes first name them.
+ * A sentence's closing full stop is not part of a name.
+ */
+export function mentionsIn(body) {
+    const names = new Map();
+    for (const match of body.matchAll(/(?<![\w@/])@([A-Za-z0-9_.-]+)/g)) {
+        const name = match[1].replace(/[.-]+$/, '');
+        if (name !== '' && !names.has(name.toLowerCase()))
+            names.set(name.toLowerCase(), name);
+    }
+    return [...names.values()];
+}
+export function releaseEmbeds(notes, appUrl) {
+    return splitBody(forDiscord(notes.body)).map((description, i) => ({
+        ...(i === 0 ? { title: notes.title } : {}),
+        description,
+        url: appUrl,
+        color: 0x2f855a,
+    }));
+}
+/** The signed ArchiveBot request for one release's notes: its idempotency key is the release's own. */
+function notesPayload(service, notes, appUrl, now) {
+    const mentions = mentionsIn(notes.body);
+    return JSON.stringify({
+        idempotencyKey: `${service}-release-${notes.version}`,
+        timestamp: now.getTime(),
+        source: service,
+        ...(mentions.length === 0 ? {} : { mentions }),
+        embeds: releaseEmbeds(notes, appUrl),
+    });
+}
+async function postSigned(options, path, body) {
+    const signature = createHmac('sha256', options.secret).update(body).digest('hex');
+    return (options.fetch ?? fetch)(`${options.archivebotUrl}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Hadoku-Signature': `sha256=${signature}` },
+        body,
+        signal: AbortSignal.timeout(10_000),
+    });
+}
+/**
+ * Post the current release's notes, then re-send the newest few as edits, so a corrected notes file
+ * (a credit added to a bullet, a typo) changes its post at the next boot. ArchiveBot edits only a post
+ * whose shown text differs and never posts from an edit. Resolves on every outcome; the outcome is
+ * logged, never thrown.
+ */
+export async function announceRelease(options) {
+    const { log, service, ordering } = options;
+    if (options.secret === '') {
+        log({ event: 'release-announce', outcome: 'skipped', reason: `no ${options.secretEnvName}` });
+        return;
+    }
+    const now = () => (options.now ?? (() => new Date()))();
+    try {
+        const notes = await latestRelease(options.releasesDir, ordering);
+        if (notes === null) {
+            log({ event: 'release-announce', outcome: 'skipped', reason: `no release notes in ${options.releasesDir}` });
+            return;
+        }
+        const res = await postSigned(options, '/api/messages/send', notesPayload(service, notes, options.appUrl, now()));
+        const reply = await res.text();
+        if (!res.ok) {
+            log({ event: 'release-announce', outcome: 'failed', version: notes.version, status: res.status, reply: reply.slice(0, 500) });
+            return;
+        }
+        const answer = JSON.parse(reply);
+        log({
+            event: 'release-announce',
+            outcome: answer.deduped === true ? 'already-posted' : 'posted',
+            version: notes.version,
+            // A name ArchiveBot could not match to anyone is posted as plain text: say so, so it can be fixed.
+            ...(answer.unresolved !== undefined && answer.unresolved.length > 0 ? { unresolved: answer.unresolved } : {}),
+        });
+    }
+    catch (err) {
+        log({ event: 'release-announce', outcome: 'failed', error: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    let recent;
+    try {
+        recent = await recentReleases(options.releasesDir, ordering);
+    }
+    catch (err) {
+        log({ event: 'release-edit', outcome: 'failed', error: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    for (const notes of recent) {
+        try {
+            const res = await postSigned(options, '/api/messages/edit', notesPayload(service, notes, options.appUrl, now()));
+            const reply = await res.text();
+            // 404: ArchiveBot holds no post for it (older than its 7-day record): nothing to change.
+            if (res.status === 404)
+                continue;
+            if (!res.ok) {
+                log({ event: 'release-edit', outcome: 'failed', version: notes.version, status: res.status, reply: reply.slice(0, 500) });
+                continue;
+            }
+            const answer = JSON.parse(reply);
+            if (answer.edited !== true)
+                continue;
+            log({
+                event: 'release-edit',
+                outcome: 'edited',
+                version: notes.version,
+                ...(answer.unresolved !== undefined && answer.unresolved.length > 0 ? { unresolved: answer.unresolved } : {}),
+            });
+        }
+        catch (err) {
+            log({ event: 'release-edit', outcome: 'failed', version: notes.version, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+}

package/dist/lifecycle/bootClock.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The boot's own stopwatch: one `boot-phase` line per step between process start and listen, each
+ * with its own `ms` and the `at` since the process began (`performance.now()`'s origin), logged as
+ * the step ends. A boot that never listens has printed every phase it finished, so the last line
+ * names the step after it as the one it is stuck in.
+ */
+export declare function bootClock(log: (entry: Record<string, unknown>) => void): (phase: string) => void;

package/dist/lifecycle/bootClock.js

@@ -0,0 +1,14 @@
+/**
+ * The boot's own stopwatch: one `boot-phase` line per step between process start and listen, each
+ * with its own `ms` and the `at` since the process began (`performance.now()`'s origin), logged as
+ * the step ends. A boot that never listens has printed every phase it finished, so the last line
+ * names the step after it as the one it is stuck in.
+ */
+export function bootClock(log) {
+    let last = 0;
+    return (phase) => {
+        const now = performance.now();
+        log({ evt: 'boot-phase', phase, ms: Math.round(now - last), at: Math.round(now) });
+        last = now;
+    };
+}

package/dist/lifecycle/busy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * "Would restarting this server destroy work right now?"
+ *
+ * hadoku_site's deploy asks this before it stops an app. mgmt-api owns the
+ * contract (`services/mgmt-api/src/deploy/wait-for-idle.ts`, and the "Deferred
+ * deploys" section of its AGENTS.md); this is one app's answer. A deploy that
+ * finds it busy is PARKED and runs when the answer turns idle, instead of
+ * SIGKILLing a live run.
+ *
+ * What counts as "busy work" is entirely the app's: this file knows no run
+ * kind, only the report's shape and the plumbing around it. The app supplies
+ * a `report` function that returns a {@link BusyReport}; everything below is
+ * generic across what that report counts.
+ *
+ * ## Who may ask — and why this is not a tier
+ *
+ * `/health` is the one route that legitimately sits above the tier floor. This
+ * sits above it too, because the caller is the deploy runner on this host, which
+ * holds no session key. It stays inside a member-gate app's rule by answering
+ * ONLY a genuinely local caller and returning a bare 404 — not 403, which would
+ * confirm the route exists — to everyone else.
+ *
+ * "Local" cannot be decided by source address alone: cloudflared connects from
+ * loopback for EVERY request, edge-routed or direct-to-the-tunnel-hostname, so
+ * `remoteAddress` is 127.0.0.1 for the whole internet. What does tell them apart is
+ * that anything which came through Cloudflare carries headers Cloudflare itself
+ * adds (`cf-ray`, `cf-connecting-ip`, …) and a caller cannot strip headers added
+ * after it sent the request. So: loopback socket AND none of those headers.
+ *
+ * ## No names
+ *
+ * A run's `label` is opaque text, never a display name, so an admin deploy log
+ * never carries one — that discipline is the app's `report` function's.
+ *
+ * ## Fail SAFE on our own error
+ *
+ * mgmt-api treats an unanswerable endpoint as "not busy" and deploys immediately,
+ * which is right for a dead service and wrong for a live one whose count failed to
+ * compute. If `report` throws, this answers BUSY with one `unknown` run: the
+ * deferral is bounded and an operator can force past it, whereas a wrongly-idle
+ * answer could end a live run.
+ */
+import type { Request, RequestHandler } from 'express';
+export interface BusyRun {
+    id: string;
+    /** The app's own label for what kind of run this is. */
+    kind: string;
+    label: string;
+}
+export interface BusyReport {
+    busy: boolean;
+    count: number;
+    runs: BusyRun[];
+}
+export declare function isLocalProbe(req: Pick<Request, 'socket' | 'headers'>): boolean;
+/** `report` computes the app's own `BusyReport`; this adds the local-only gate and fail-safe. */
+export declare function busyHandler(report: () => BusyReport): RequestHandler;

package/dist/lifecycle/busy.js

@@ -0,0 +1,47 @@
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+/**
+ * Headers that mean "this request came through Cloudflare or the edge". Cloudflare
+ * adds the first group to every proxied request, tunnel-hostname traffic included;
+ * edge-router stamps the last. A local caller sends none of them.
+ */
+const PROXIED_HEADERS = [
+    'cf-ray',
+    'cf-connecting-ip',
+    'cf-visitor',
+    'cf-ipcountry',
+    'x-forwarded-for',
+    'x-forwarded-host',
+    'x-forwarded-proto',
+    'x-real-ip',
+    'forwarded',
+    'x-edge-auth',
+];
+export function isLocalProbe(req) {
+    const addr = req.socket?.remoteAddress;
+    if (addr === undefined || !LOOPBACK.has(addr))
+        return false;
+    return !PROXIED_HEADERS.some((h) => req.headers[h] !== undefined);
+}
+/** `report` computes the app's own `BusyReport`; this adds the local-only gate and fail-safe. */
+export function busyHandler(report) {
+    return (req, res) => {
+        if (!isLocalProbe(req)) {
+            // Bare 404: not 403, which would confirm there is something here.
+            res.status(404).end();
+            return;
+        }
+        let out;
+        try {
+            out = report();
+        }
+        catch {
+            out = {
+                busy: true,
+                count: 1,
+                runs: [{ id: 'unknown', kind: 'unknown', label: 'could not determine what is running' }],
+            };
+        }
+        res.setHeader('cache-control', 'no-store');
+        res.json(out);
+    };
+}

package/dist/lifecycle/flush-sockets.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Let what was just emitted reach the wire before the sockets are closed.
+ *
+ * `io.close()` closes every engine.io connection with `close(true)`, which
+ * DISCARDS its write buffer. A packet stays in that buffer when the
+ * connection's transport is not writable at the moment of the emit: a
+ * websocket still waiting on its previous send's callback, or a polling client
+ * between two GETs. A restart notice emitted just before the close would then
+ * be thrown away and the screen read "Reconnecting…" after all.
+ *
+ * engine.io hands a buffer to the transport synchronously when it can
+ * (`Socket.sendPacket` → `flush`, which emits `flush`), so a connection that
+ * did not flush during `send` still holds the packet, and gives it up on its
+ * next `drain`. Only those are waited for: a transport that is merely busy
+ * after flushing (a websocket awaiting its callback, a poll just answered)
+ * already has the packet, and its close comes after it.
+ */
+/** The part of an engine.io `Socket` (a socket.io socket's `conn`) this needs. */
+export interface Flushable {
+    once(event: 'drain' | 'close', listener: () => void): unknown;
+    on(event: 'flush', listener: () => void): unknown;
+    off(event: 'flush', listener: () => void): unknown;
+}
+/**
+ * Run `send`, then resolve once every connection that could not write it at
+ * once has written it (or closed), or after `ms`.
+ */
+export declare function sendThenFlush(conns: Iterable<Flushable>, send: () => void, ms: number): Promise<void>;
+/** The part of a node `http.Server` {@link closeConnections} needs. */
+export interface Closable {
+    closeIdleConnections(): void;
+    closeAllConnections(): void;
+}
+/**
+ * Let a closing server's connections go: the idle ones at once, and every one after `graceMs`, so
+ * a request already in flight is answered. `server.close` (which `io.close` calls) only stops new
+ * connections and waits for the open ones, and a keep-alive connection through cloudflared that a
+ * page keeps busy never goes idle: one restart was still answering requests a second in, and pm2
+ * SIGKILLed it at its `kill_timeout` before `shutdown-done`.
+ */
+export declare function closeConnections(server: Closable, graceMs: number): void;

package/dist/lifecycle/flush-sockets.js

@@ -0,0 +1,61 @@
+/**
+ * Let what was just emitted reach the wire before the sockets are closed.
+ *
+ * `io.close()` closes every engine.io connection with `close(true)`, which
+ * DISCARDS its write buffer. A packet stays in that buffer when the
+ * connection's transport is not writable at the moment of the emit: a
+ * websocket still waiting on its previous send's callback, or a polling client
+ * between two GETs. A restart notice emitted just before the close would then
+ * be thrown away and the screen read "Reconnecting…" after all.
+ *
+ * engine.io hands a buffer to the transport synchronously when it can
+ * (`Socket.sendPacket` → `flush`, which emits `flush`), so a connection that
+ * did not flush during `send` still holds the packet, and gives it up on its
+ * next `drain`. Only those are waited for: a transport that is merely busy
+ * after flushing (a websocket awaiting its callback, a poll just answered)
+ * already has the packet, and its close comes after it.
+ */
+/**
+ * Run `send`, then resolve once every connection that could not write it at
+ * once has written it (or closed), or after `ms`.
+ */
+export function sendThenFlush(conns, send, ms) {
+    const watched = [...conns].map((conn) => {
+        const seen = { conn, flushed: false, mark: () => (seen.flushed = true) };
+        conn.on('flush', seen.mark);
+        return seen;
+    });
+    try {
+        send();
+    }
+    finally {
+        for (const w of watched)
+            w.conn.off('flush', w.mark);
+    }
+    const waits = watched
+        .filter((w) => !w.flushed)
+        .map(({ conn }) => new Promise((done) => {
+        conn.once('drain', done);
+        conn.once('close', done);
+    }));
+    if (waits.length === 0)
+        return Promise.resolve();
+    return new Promise((done) => {
+        const bound = setTimeout(done, ms);
+        void Promise.all(waits).then(() => {
+            clearTimeout(bound);
+            done();
+        });
+    });
+}
+/**
+ * Let a closing server's connections go: the idle ones at once, and every one after `graceMs`, so
+ * a request already in flight is answered. `server.close` (which `io.close` calls) only stops new
+ * connections and waits for the open ones, and a keep-alive connection through cloudflared that a
+ * page keeps busy never goes idle: one restart was still answering requests a second in, and pm2
+ * SIGKILLed it at its `kill_timeout` before `shutdown-done`.
+ */
+export function closeConnections(server, graceMs) {
+    server.closeIdleConnections();
+    setTimeout(() => server.closeAllConnections(), graceMs).unref();
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,4 @@
+export { busyHandler, isLocalProbe, type BusyReport, type BusyRun } from './busy.js';
+export { bootClock } from './bootClock.js';
+export { closeConnections, sendThenFlush, type Closable, type Flushable } from './flush-sockets.js';
+export { announceRelease, EDITABLE_RELEASES, forDiscord, latestRelease, mentionsIn, parseNotes, recentReleases, releaseEmbeds, splitBody, type AnnounceOptions, type Embed, type ReleaseNotes, type ReleaseOrdering, } from './announce.js';

package/dist/lifecycle/index.js

@@ -0,0 +1,4 @@
+export { busyHandler, isLocalProbe } from "./busy.js";
+export { bootClock } from "./bootClock.js";
+export { closeConnections, sendThenFlush } from "./flush-sockets.js";
+export { announceRelease, EDITABLE_RELEASES, forDiscord, latestRelease, mentionsIn, parseNotes, recentReleases, releaseEmbeds, splitBody, } from "./announce.js";

package/dist/limits/index.d.ts

@@ -0,0 +1 @@
+export { bodyErrors, costlyActLimit, makeCallerId, parseBody, perCallerLimit, readBody, type BodySchema, } from './limits.js';

package/dist/limits/index.js

@@ -0,0 +1 @@
+export { bodyErrors, costlyActLimit, makeCallerId, parseBody, perCallerLimit, readBody, } from "./limits.js";

package/dist/limits/limits.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What every HTTP route reads off a request before its own work: who is asking, and what the
+ * body says. Knows no game's identity scheme — a caller's id comes from an injected deriver
+ * (`makeCallerId`), never a direct import, so a second game can bring its own.
+ */
+import type { ParticipantId } from '@wolffm/rooms-protocol';
+import { type RateLimitConfig } from '@wolffm/rooms-server';
+import type { ErrorRequestHandler, Request, Response } from 'express';
+import { callerContext } from '../telemetry/telemetry.js';
+/**
+ * A request's caller id, from an injected deriver over the request's headers (the app's own
+ * identity scheme — platform, but a parameter here rather than an import). A request the
+ * deriver can't place gets a fresh ephemeral fallback, which matches no seat and no member —
+ * the right answer for someone the edge could not name.
+ */
+export declare function makeCallerId(deriveId: (headers: Request['headers'], fallback: string) => ParticipantId): (req: Request) => ParticipantId;
+/**
+ * A per-caller token bucket for a costly step: each pass reports `costly-act` and each refusal
+ * `rate-limited`, both named by `act`, so telemetry shows who is spending the expensive steps and
+ * who hit the ceiling (the telemetry sink throttles the posts). `headers` are the caller's own,
+ * for the report. `null` is no limit — an e2e stack that disables rate limits for one test identity
+ * so it can make every room and start every match of a run.
+ */
+export declare function costlyActLimit(cfg: RateLimitConfig | null, opts: {
+    act: string;
+    now?: () => number;
+    onRefused?: () => void;
+}): (caller: ParticipantId, headers: Parameters<typeof callerContext>[0]) => boolean;
+/**
+ * {@link costlyActLimit} for a route: false once the 429 (with `Retry-After`) is sent. A route
+ * asks AFTER reading its body, so only a request that would do the work spends a token.
+ * `callerId` is the request's caller id — see {@link makeCallerId}.
+ */
+export declare function perCallerLimit(cfg: RateLimitConfig | null, refusal: string, opts: {
+    act: string;
+    callerId: (req: Request) => ParticipantId;
+    now?: () => number;
+    onRefused?: () => void;
+}): (req: Request, res: Response) => boolean;
+/** A request-body schema, as this module reads one — a minimal structural shape, never `@hadoku/shared` itself. */
+export interface BodySchema<T> {
+    safeParse(body: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: readonly {
+                code: string;
+                path: readonly PropertyKey[];
+                message: string;
+            }[];
+        };
+    };
+}
+/**
+ * A request body by its schema, or null once the 400 is sent. The
+ * answer is the schema's first refusal, a field nobody named before anything
+ * else, in the `{ error }` body every route answers with.
+ */
+export declare function parseBody<T>(schema: BodySchema<T>, req: Request, res: Response): T | null;
+/** A body by its schema, or the refusal `parseBody` would answer with. */
+export declare function readBody<T>(schema: BodySchema<T>, body: unknown): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The error handler mounted after a router: chiefly `express.json()`'s parse
+ * failure, raised on the api router before the router runs. Answered without
+ * the parser's message, which quotes the body, and reported by name only.
+ * Without `onError`, any other error goes on to the next handler.
+ */
+export declare function bodyErrors(onError?: (name: string) => void): ErrorRequestHandler;

package/dist/limits/limits.js

@@ -0,0 +1,103 @@
+/**
+ * What every HTTP route reads off a request before its own work: who is asking, and what the
+ * body says. Knows no game's identity scheme — a caller's id comes from an injected deriver
+ * (`makeCallerId`), never a direct import, so a second game can bring its own.
+ */
+import { randomUUID } from 'node:crypto';
+import { MultiRateLimiter } from '@wolffm/rooms-server';
+import { callerContext, report } from "../telemetry/telemetry.js";
+/**
+ * A request's caller id, from an injected deriver over the request's headers (the app's own
+ * identity scheme — platform, but a parameter here rather than an import). A request the
+ * deriver can't place gets a fresh ephemeral fallback, which matches no seat and no member —
+ * the right answer for someone the edge could not name.
+ */
+export function makeCallerId(deriveId) {
+    return (req) => deriveId(req.headers, `http-${randomUUID()}`);
+}
+/**
+ * A per-caller token bucket for a costly step: each pass reports `costly-act` and each refusal
+ * `rate-limited`, both named by `act`, so telemetry shows who is spending the expensive steps and
+ * who hit the ceiling (the telemetry sink throttles the posts). `headers` are the caller's own,
+ * for the report. `null` is no limit — an e2e stack that disables rate limits for one test identity
+ * so it can make every room and start every match of a run.
+ */
+export function costlyActLimit(cfg, opts) {
+    if (cfg === null)
+        return () => true;
+    const limiter = new MultiRateLimiter(cfg);
+    const now = opts.now ?? Date.now;
+    return (caller, headers) => {
+        if (limiter.allow(caller, 1, now())) {
+            report('costly-act', { act: opts.act, ...callerContext(headers) });
+            return true;
+        }
+        report('rate-limited', { act: opts.act, ...callerContext(headers) });
+        opts.onRefused?.();
+        return false;
+    };
+}
+/**
+ * {@link costlyActLimit} for a route: false once the 429 (with `Retry-After`) is sent. A route
+ * asks AFTER reading its body, so only a request that would do the work spends a token.
+ * `callerId` is the request's caller id — see {@link makeCallerId}.
+ */
+export function perCallerLimit(cfg, refusal, opts) {
+    if (cfg === null)
+        return () => true;
+    const allow = costlyActLimit(cfg, opts);
+    const retryAfter = String(Math.ceil(cfg.refillIntervalMs / 1000));
+    return (req, res) => {
+        if (allow(opts.callerId(req), req.headers))
+            return true;
+        res.setHeader('Retry-After', retryAfter);
+        res.status(429).json({ error: refusal });
+        return false;
+    };
+}
+/**
+ * A request body by its schema, or null once the 400 is sent. The
+ * answer is the schema's first refusal, a field nobody named before anything
+ * else, in the `{ error }` body every route answers with.
+ */
+export function parseBody(schema, req, res) {
+    const parsed = readBody(schema, req.body);
+    if (parsed.ok)
+        return parsed.value;
+    res.status(400).json({ error: parsed.error });
+    return null;
+}
+/** A body by its schema, or the refusal `parseBody` would answer with. */
+export function readBody(schema, body) {
+    const parsed = schema.safeParse(body);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    const { issues } = parsed.error;
+    const issue = issues.find((i) => i.code === 'unrecognized_keys' && i.path.length === 0) ?? issues[0];
+    return { ok: false, error: issue?.message ?? 'the request body could not be read' };
+}
+/**
+ * The error handler mounted after a router: chiefly `express.json()`'s parse
+ * failure, raised on the api router before the router runs. Answered without
+ * the parser's message, which quotes the body, and reported by name only.
+ * Without `onError`, any other error goes on to the next handler.
+ */
+export function bodyErrors(onError) {
+    return (err, _req, res, next) => {
+        if (res.headersSent)
+            return next(err);
+        const e = err;
+        if (e.type === 'entity.parse.failed') {
+            res.status(400).json({ error: 'body is not valid JSON' });
+            return;
+        }
+        if (typeof e.status === 'number' && e.status >= 400 && e.status < 500) {
+            res.status(400).json({ error: 'the request body could not be read' });
+            return;
+        }
+        if (onError === undefined)
+            return next(err);
+        onError(typeof e.name === 'string' ? e.name : 'unknown');
+        res.status(500).json({ error: 'internal error' });
+    };
+}

package/dist/log/index.d.ts

@@ -0,0 +1 @@
+export { jsonLogger, type JsonLog } from './log.js';

package/dist/log/index.js

@@ -0,0 +1 @@
+export { jsonLogger } from "./log.js";