@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/http/reply.d.ts

@@ -0,0 +1,130 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ResourceHttpPath, ResourceHttpReply } from '../../shared/resourceHttp.js';
+export declare const policyResponses: WeakMap<ServerResponse<IncomingMessage>, {
+    reply?: () => void;
+}>;
+export declare function sendResource<Path extends ResourceHttpPath>(res: ServerResponse, _route: Path, status: number, body: ResourceHttpReply<NoInfer<Path>>): void;
+/**
+ * A write that waited out another transaction's lock (writeLanes.ts,
+ * `--lock-timeout`): its statement failed and its transaction rolled back,
+ * so nothing landed, and the same request will very likely go through in a
+ * moment. 503 with Retry-After, which is what an HTTP client retries; the
+ * body is a write refusal's, with its own code. `extra` is the route's own
+ * fields (`deleted: false`).
+ */
+export declare function sendRowLocked(res: ServerResponse, extra?: Record<string, unknown>): void;
+/**
+ * A request the pool refused (poolMetrics.ts, PoolBusy): every connection was
+ * in use and the queue behind them was too long or had waited too long.
+ * Nothing was leased, so nothing ran: 503 with Retry-After, which is what an
+ * HTTP client retries, and for a write `outcome: 'not_applied'`, since it
+ * never began and the same request may be sent again. `extra` is the route's
+ * own fields (`deleted: false`); `write` is for a route that writes; `refusal` is the PoolBusy, which says how long to wait.
+ */
+export declare function sendBusy(res: ServerResponse, extra?: Record<string, unknown>, write?: boolean, refusal?: unknown): void;
+/**
+ * Where a failure's trace can be read, while something serves traces (the App
+ * framework's dev observer, observe/mount.ts, sets it when it runs): a refusal
+ * then says where, beside its own words. None otherwise, which is every
+ * production start and every database browser start.
+ */
+declare let traceLink: ((traceId: string | undefined, req: IncomingMessage) => string | undefined) | undefined;
+/** Set (or, with none, clear) where a failure's trace is read. */
+export declare function linkTraces(link: typeof traceLink): void;
+export declare function send(res: ServerResponse, status: number, body: unknown): void;
+/**
+ * A GET whose answer changes only when the catalog, the App or the principal
+ * does — the schema, the App, its pages, the runtime — sent with a strong
+ * ETag so a browser that has it asks again with If-None-Match and is told
+ * 304 instead of being sent the same bytes: 349 KB of schema on a wide
+ * catalog, on every load.
+ *
+ * The answer is still computed, authorized and compared on every request —
+ * `no-cache` means the browser may keep it but never use it unasked — so a
+ * revoked grant or a reload is seen at once. The tag is a digest of the body
+ * together with `principal`, so one person's copy never validates for
+ * another even where the bytes agree, and `private` with `Vary: Cookie`
+ * keeps it out of any shared cache. A reply the request already marked
+ * `no-store` — every row-policy and tenant reply (handler.ts) — keeps that:
+ * it gets no tag and is not stored at all.
+ */
+export declare function sendRevalidated(res: ServerResponse, body: unknown, principal: string): void;
+/**
+ * Brotli at quality 4 or gzip at level 6, whichever the request weights
+ * higher: 7–70 times fewer bytes than the JSON they carry, for a few
+ * milliseconds. Brotli wins a tie, being the smaller. `q=0` excludes an
+ * encoding, `*` weights the ones not named, and an `identity` the request
+ * names above both means it would rather have the bytes plain. Static assets
+ * are precompressed at build time (clientHttp.ts); a reply is compressed as
+ * it is sent.
+ */
+export declare function acceptedEncoding(res: ServerResponse): 'br' | 'gzip' | undefined;
+/** Files obey the same settlement boundary as JSON. Even their headers wait:
+ * a failed policy context must not publish file metadata or a partial body. */
+export declare function sendBytes(res: ServerResponse, status: number, bytes: Uint8Array, headers: Record<string, string | number>, head?: boolean): void;
+/**
+ * Bytes that arrive as a stream (a file passed on from its bucket), sent as
+ * they come. A reply a policy holds until its transaction ends cannot start
+ * early, so there the stream is read whole first and sent like any other.
+ */
+export declare function sendStream(res: ServerResponse, status: number, body: ReadableStream<Uint8Array>, headers: Record<string, string | number>, head?: boolean): Promise<void>;
+/**
+ * A written record as its reply shows it: a file's bytes as the `<n bytes>` label every read gives a blob (adapters/
+ * postgresValues.ts), never the bytes. An upload's reply otherwise echoed the file back as a JSON Buffer, three times
+ * its size. Anything that is not a record passes as it is.
+ */
+export declare function bytesLabelled<T>(record: T): T;
+/** A file upload, the one body allowed past that: base64 of the largest file an App may accept, and room for the rest. */
+export declare const FILE_UPLOAD_PATH = "/api/file/upload";
+export declare const FILE_UPLOAD_BODY: number;
+/**
+ * A tenant App's read of one file (tenant/tenantHttp.ts): the bytes come back
+ * as base64 in JSON, on the lease, like every other tenant read — a tenant
+ * page never addresses a file by URL, so no tenant's file is ever a link.
+ */
+export declare const FILE_READ_PATH = "/api/file/read";
+/**
+ * The most bytes a tenant App's upload carries, whatever the resource's own
+ * cap: a tenant request is captured whole before it is judged (evidence.ts
+ * `captureTenantData`, 16 MiB of text), and base64 of this fits in it.
+ */
+export declare const TENANT_FILE_MOST: number;
+export declare const TENANT_FILE_UPLOAD_BODY: number;
+/** Only diagnostics emitted by the request service are public. Provider errors
+ * are stripped of ResourceReadError inside that service; failures elsewhere in
+ * auth/policy startup never pass through this conversion. */
+export declare function httpRead<R>(work: () => Promise<R>): Promise<R>;
+/**
+ * An error that already knows what status it deserves.
+ *
+ * Without this everything that was not a `PathError` fell out of `createApp`'s
+ * catch as a 500, so a body the caller sent malformed — or one they sent too
+ * much of — was reported to them as an outage on this end. The status is the
+ * only part of a failure most clients branch on; getting it wrong sends
+ * people to look at the wrong machine.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * A refusal that answers to both names.
+ *
+ * The view endpoints report their failures as `errors: [{message}]`, because
+ * a half-built view can be wrong in several places at once; every other
+ * endpoint reports `error`. A client that branches on the status and then
+ * reads `.error` showed a blank message on exactly the endpoints where the
+ * message mattered most. Both are sent — the list stays the shape the view
+ * editor reads, and `error` is the first of them.
+ */
+export declare function refuse(res: ServerResponse, status: number, messages: string[]): void;
+/**
+ * A request body, at most `limit` bytes; undefined when it is longer. The rest of a longer body is still read, to be
+ * dropped: a reader that stopped at the limit left it on a keep-alive connection, where the server read the next
+ * request out of its leftovers, and that request hung or was reset (a live load test). So the 413 goes out on a
+ * connection that is clean. Not unboundedly: past OVERSIZE_DRAIN_MOST beyond the limit the connection is closed
+ * instead, which is what a client sending that much to a bounded route gets.
+ */
+export declare function readBounded(req: IncomingMessage, limit: number): Promise<Buffer | undefined>;
+export declare function readJson(req: IncomingMessage, limit?: number): Promise<Record<string, unknown>>;
+export {};

package/dist/server/http/reply.js

@@ -0,0 +1,394 @@
+/**
+ * How a reply leaves: JSON with a status, a bounded body read, and the error
+ * that already knows its status. Nothing here knows what a request means.
+ */
+import { currentSpan } from '../../adapters/telemetry/trace.js';
+import { FILE_MAX_BYTES_CEILING } from '../../shared/fileBounds.js';
+import { createHash } from 'node:crypto';
+import { brotliCompress, brotliCompressSync, constants as zlib, gzip, gzipSync } from 'node:zlib';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ResourceReadError } from '../resourceReadOperations.js';
+import { ROW_LOCKED_MESSAGE, ROW_LOCKED_RETRY_AFTER_SECONDS } from '../../adapters/writeLanes.js';
+import { POOL_BUSY_MESSAGE, poolBusyRetryAfterSeconds } from '../../adapters/poolMetrics.js';
+// Policy callbacks may catch an operation failure, but the context still owns
+// its outcome. Do not publish a partial success before that context settles.
+export const policyResponses = new WeakMap();
+export function sendResource(res, _route, status, body) {
+    send(res, status, body);
+}
+/**
+ * A write that waited out another transaction's lock (writeLanes.ts,
+ * `--lock-timeout`): its statement failed and its transaction rolled back,
+ * so nothing landed, and the same request will very likely go through in a
+ * moment. 503 with Retry-After, which is what an HTTP client retries; the
+ * body is a write refusal's, with its own code. `extra` is the route's own
+ * fields (`deleted: false`).
+ */
+export function sendRowLocked(res, extra = {}) {
+    currentSpan()?.event('lock timeout', { 'mistri.write.refusal': 'row_locked' });
+    if (!res.headersSent)
+        res.setHeader('retry-after', String(ROW_LOCKED_RETRY_AFTER_SECONDS));
+    send(res, 503, {
+        ...extra,
+        error: ROW_LOCKED_MESSAGE,
+        code: 'row_locked',
+        errors: [{ code: 'row_locked', message: ROW_LOCKED_MESSAGE }],
+        outcome: 'not_applied',
+    });
+}
+/**
+ * A request the pool refused (poolMetrics.ts, PoolBusy): every connection was
+ * in use and the queue behind them was too long or had waited too long.
+ * Nothing was leased, so nothing ran: 503 with Retry-After, which is what an
+ * HTTP client retries, and for a write `outcome: 'not_applied'`, since it
+ * never began and the same request may be sent again. `extra` is the route's
+ * own fields (`deleted: false`); `write` is for a route that writes; `refusal` is the PoolBusy, which says how long to wait.
+ */
+export function sendBusy(res, extra = {}, write = false, refusal) {
+    currentSpan()?.event('pool busy', { 'mistri.refusal': 'server_busy' });
+    if (!res.headersSent)
+        res.setHeader('retry-after', String(poolBusyRetryAfterSeconds(refusal)));
+    send(res, 503, {
+        ...extra,
+        error: POOL_BUSY_MESSAGE,
+        code: 'server_busy',
+        ...(write ? { errors: [{ code: 'server_busy', message: POOL_BUSY_MESSAGE }], outcome: 'not_applied' } : {}),
+    });
+}
+/**
+ * Where a failure's trace can be read, while something serves traces (the App
+ * framework's dev observer, observe/mount.ts, sets it when it runs): a refusal
+ * then says where, beside its own words. None otherwise, which is every
+ * production start and every database browser start.
+ */
+let traceLink;
+/** Set (or, with none, clear) where a failure's trace is read. */
+export function linkTraces(link) {
+    traceLink = link;
+}
+export function send(res, status, body) {
+    const deferred = policyResponses.get(res);
+    if (deferred) {
+        deferred.reply = () => send(res, status, body);
+        return;
+    }
+    if (res.destroyed || res.writableEnded)
+        return;
+    /* While the dev observer runs, a failure says where its trace is: the
+       "Open in observer" link beside the refusal (observe/mount.ts). */
+    const observe = traceLink && status >= 400 && body && typeof body === 'object' && !Array.isArray(body)
+        ? traceLink(currentSpan()?.traceId, res.req)
+        : undefined;
+    writeJson(res, status, Buffer.from(JSON.stringify(observe ? { ...body, observe } : body)));
+}
+/**
+ * A GET whose answer changes only when the catalog, the App or the principal
+ * does — the schema, the App, its pages, the runtime — sent with a strong
+ * ETag so a browser that has it asks again with If-None-Match and is told
+ * 304 instead of being sent the same bytes: 349 KB of schema on a wide
+ * catalog, on every load.
+ *
+ * The answer is still computed, authorized and compared on every request —
+ * `no-cache` means the browser may keep it but never use it unasked — so a
+ * revoked grant or a reload is seen at once. The tag is a digest of the body
+ * together with `principal`, so one person's copy never validates for
+ * another even where the bytes agree, and `private` with `Vary: Cookie`
+ * keeps it out of any shared cache. A reply the request already marked
+ * `no-store` — every row-policy and tenant reply (handler.ts) — keeps that:
+ * it gets no tag and is not stored at all.
+ */
+export function sendRevalidated(res, body, principal) {
+    const deferred = policyResponses.get(res);
+    if (deferred) {
+        deferred.reply = () => sendRevalidated(res, body, principal);
+        return;
+    }
+    if (res.destroyed || res.writableEnded)
+        return;
+    const json = Buffer.from(JSON.stringify(body));
+    if (String(res.getHeader('cache-control') ?? '').includes('no-store')) {
+        writeJson(res, 200, json);
+        return;
+    }
+    const tag = `"${createHash('sha256').update(principal).update('\0').update(json).digest('base64url').slice(0, 32)}"`;
+    const headers = { 'cache-control': 'private, no-cache', etag: tag };
+    addVary(res, 'Cookie');
+    const asked = res.req?.headers['if-none-match'];
+    if (typeof asked === 'string' && asked.split(',').some((one) => one.trim().replace(/^W\//, '') === tag)) {
+        addVary(res, 'Accept-Encoding');
+        res.writeHead(304, headers);
+        res.end();
+        return;
+    }
+    writeJson(res, 200, json, headers, tag);
+}
+/** JSON this size or larger is compressed when the request accepts it. Below
+ * it the header costs more than the saving. */
+const COMPRESS_FROM = 1024;
+/** Past this a body is compressed off the event loop: brotli at quality 4 is
+ * about 4 ms for a wide schema's 349 KB, and a 100,000-row read is far more;
+ * 32 KB is roughly a millisecond, the most a request should hold the loop for. */
+const COMPRESS_INLINE_BELOW = 32 * 1024;
+/** Compressed metadata, by tag and encoding: a revisit that is not a 304 (a
+ * new tab, a cleared cache) is sent the bytes compressed the first time. */
+const compressed = new Map();
+const COMPRESSED_KEPT = 64;
+/**
+ * Brotli at quality 4 or gzip at level 6, whichever the request weights
+ * higher: 7–70 times fewer bytes than the JSON they carry, for a few
+ * milliseconds. Brotli wins a tie, being the smaller. `q=0` excludes an
+ * encoding, `*` weights the ones not named, and an `identity` the request
+ * names above both means it would rather have the bytes plain. Static assets
+ * are precompressed at build time (clientHttp.ts); a reply is compressed as
+ * it is sent.
+ */
+export function acceptedEncoding(res) {
+    const weights = new Map();
+    for (const part of String(res.req?.headers['accept-encoding'] ?? '')
+        .toLowerCase()
+        .split(',')) {
+        const [token, ...params] = part.trim().split(';');
+        const name = token.trim();
+        if (!name)
+            continue;
+        const q = params.map((p) => p.trim()).find((p) => p.startsWith('q='));
+        const weight = q ? Number(q.slice(2)) : 1;
+        weights.set(name, Number.isFinite(weight) ? Math.min(weight, 1) : 0);
+    }
+    const weightOf = (name) => weights.get(name) ?? weights.get('*') ?? 0;
+    const br = weightOf('br');
+    const gzip = weightOf('gzip');
+    const best = br >= gzip ? 'br' : 'gzip';
+    const quality = Math.max(br, gzip);
+    if (quality <= 0 || (weights.get('identity') ?? 0) > quality)
+        return undefined;
+    return best;
+}
+function addVary(res, name) {
+    const current = String(res.getHeader('vary') ?? '');
+    const names = current
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (!names.some((part) => part.toLowerCase() === name.toLowerCase()))
+        res.setHeader('vary', [...names, name].join(', '));
+}
+function writeJson(res, status, json, extra = {}, tag) {
+    const headers = {
+        'content-type': 'application/json; charset=utf-8',
+        'x-content-type-options': 'nosniff',
+        ...extra,
+    };
+    const encoding = json.length >= COMPRESS_FROM ? acceptedEncoding(res) : undefined;
+    if (json.length >= COMPRESS_FROM)
+        addVary(res, 'Accept-Encoding');
+    const finish = (bytes, applied) => {
+        if (res.destroyed || res.writableEnded)
+            return;
+        res.writeHead(status, { ...headers, ...(applied ? { 'content-encoding': applied } : {}), 'content-length': bytes.length });
+        res.end(bytes);
+    };
+    if (!encoding)
+        return finish(json);
+    const key = tag && `${tag}:${encoding}`;
+    const kept = key ? compressed.get(key) : undefined;
+    if (kept)
+        return finish(kept, encoding);
+    const keep = (bytes) => {
+        if (!key)
+            return;
+        if (compressed.size >= COMPRESSED_KEPT)
+            compressed.delete(compressed.keys().next().value);
+        compressed.set(key, bytes);
+    };
+    const options = encoding === 'br'
+        ? {
+            params: {
+                [zlib.BROTLI_PARAM_QUALITY]: 4,
+                [zlib.BROTLI_PARAM_SIZE_HINT]: json.length,
+                [zlib.BROTLI_PARAM_MODE]: zlib.BROTLI_MODE_TEXT,
+            },
+        }
+        : { level: 6 };
+    if (json.length < COMPRESS_INLINE_BELOW) {
+        const bytes = encoding === 'br' ? brotliCompressSync(json, options) : gzipSync(json, options);
+        keep(bytes);
+        return finish(bytes, encoding);
+    }
+    const done = (error, bytes) => {
+        if (error)
+            return finish(json);
+        keep(bytes);
+        finish(bytes, encoding);
+    };
+    if (encoding === 'br')
+        brotliCompress(json, options, done);
+    else
+        gzip(json, options, done);
+}
+/** Files obey the same settlement boundary as JSON. Even their headers wait:
+ * a failed policy context must not publish file metadata or a partial body. */
+export function sendBytes(res, status, bytes, headers, head = false) {
+    const deferred = policyResponses.get(res);
+    if (deferred) {
+        const body = Buffer.from(bytes);
+        const capturedHeaders = { ...headers };
+        deferred.reply = () => sendBytes(res, status, body, capturedHeaders, head);
+        return;
+    }
+    if (res.destroyed || res.writableEnded)
+        return;
+    res.writeHead(status, headers);
+    res.end(head ? undefined : bytes);
+}
+/**
+ * Bytes that arrive as a stream (a file passed on from its bucket), sent as
+ * they come. A reply a policy holds until its transaction ends cannot start
+ * early, so there the stream is read whole first and sent like any other.
+ */
+export async function sendStream(res, status, body, headers, head = false) {
+    if (head || res.destroyed || res.writableEnded) {
+        await body.cancel().catch(() => { });
+        sendBytes(res, status, new Uint8Array(0), headers, true);
+        return;
+    }
+    if (policyResponses.get(res)) {
+        sendBytes(res, status, new Uint8Array(await new Response(body).arrayBuffer()), headers);
+        return;
+    }
+    res.writeHead(status, headers);
+    await pipeline(Readable.fromWeb(body), res).catch(() => res.destroy());
+}
+/**
+ * A written record as its reply shows it: a file's bytes as the `<n bytes>` label every read gives a blob (adapters/
+ * postgresValues.ts), never the bytes. An upload's reply otherwise echoed the file back as a JSON Buffer, three times
+ * its size. Anything that is not a record passes as it is.
+ */
+export function bytesLabelled(record) {
+    if (!record || typeof record !== 'object' || Array.isArray(record) || record instanceof Uint8Array)
+        return record;
+    const entries = Object.entries(record);
+    if (!entries.some(([, value]) => value instanceof Uint8Array))
+        return record;
+    return Object.fromEntries(entries.map(([column, value]) => [column, value instanceof Uint8Array ? `<${value.byteLength} bytes>` : value]));
+}
+/** Bounded, because an unbounded request body is a denial of service. */
+const MAX_BODY = 1024 * 256;
+/** A file upload, the one body allowed past that: base64 of the largest file an App may accept, and room for the rest. */
+export const FILE_UPLOAD_PATH = '/api/file/upload';
+export const FILE_UPLOAD_BODY = Math.ceil(FILE_MAX_BYTES_CEILING / 3) * 4 + 64 * 1024;
+/**
+ * A tenant App's read of one file (tenant/tenantHttp.ts): the bytes come back
+ * as base64 in JSON, on the lease, like every other tenant read — a tenant
+ * page never addresses a file by URL, so no tenant's file is ever a link.
+ */
+export const FILE_READ_PATH = '/api/file/read';
+/**
+ * The most bytes a tenant App's upload carries, whatever the resource's own
+ * cap: a tenant request is captured whole before it is judged (evidence.ts
+ * `captureTenantData`, 16 MiB of text), and base64 of this fits in it.
+ */
+export const TENANT_FILE_MOST = 10 * 1024 * 1024;
+export const TENANT_FILE_UPLOAD_BODY = Math.ceil(TENANT_FILE_MOST / 3) * 4 + 64 * 1024;
+/** Only diagnostics emitted by the request service are public. Provider errors
+ * are stripped of ResourceReadError inside that service; failures elsewhere in
+ * auth/policy startup never pass through this conversion. */
+export async function httpRead(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof ResourceReadError)
+            throw new HttpError(error.status, error.message);
+        throw error;
+    }
+}
+/**
+ * An error that already knows what status it deserves.
+ *
+ * Without this everything that was not a `PathError` fell out of `createApp`'s
+ * catch as a 500, so a body the caller sent malformed — or one they sent too
+ * much of — was reported to them as an outage on this end. The status is the
+ * only part of a failure most clients branch on; getting it wrong sends
+ * people to look at the wrong machine.
+ */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+/**
+ * A refusal that answers to both names.
+ *
+ * The view endpoints report their failures as `errors: [{message}]`, because
+ * a half-built view can be wrong in several places at once; every other
+ * endpoint reports `error`. A client that branches on the status and then
+ * reads `.error` showed a blank message on exactly the endpoints where the
+ * message mattered most. Both are sent — the list stays the shape the view
+ * editor reads, and `error` is the first of them.
+ */
+export function refuse(res, status, messages) {
+    send(res, status, {
+        error: messages[0],
+        errors: messages.map((message) => ({ message })),
+    });
+}
+/** How much of a body past its limit is still read off the wire, to be dropped (readBounded). */
+const OVERSIZE_DRAIN_MOST = 16 * 1024 * 1024;
+/**
+ * A request body, at most `limit` bytes; undefined when it is longer. The rest of a longer body is still read, to be
+ * dropped: a reader that stopped at the limit left it on a keep-alive connection, where the server read the next
+ * request out of its leftovers, and that request hung or was reset (a live load test). So the 413 goes out on a
+ * connection that is clean. Not unboundedly: past OVERSIZE_DRAIN_MOST beyond the limit the connection is closed
+ * instead, which is what a client sending that much to a bounded route gets.
+ */
+export async function readBounded(req, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const part of req) {
+        const chunk = Buffer.isBuffer(part) ? part : Buffer.from(part);
+        size += chunk.length;
+        if (size <= limit)
+            chunks.push(chunk);
+        else if (size > limit + OVERSIZE_DRAIN_MOST) {
+            req.socket?.destroy();
+            return undefined;
+        }
+        else
+            chunks.length = 0;
+    }
+    return size > limit ? undefined : Buffer.concat(chunks);
+}
+export async function readJson(req, limit = MAX_BODY) {
+    const read = await readBounded(req, limit);
+    if (!read)
+        throw new HttpError(413, 'Request body too large.');
+    if (!read.length)
+        return {};
+    try {
+        /* JSON.parse itself preserves literal keys safely. Some downstream maps
+           still use keyed assignment on ordinary objects, though, so admitting
+           these names would not preserve their values end to end. Refuse the
+           whole request rather than silently deleting an intended write. Literal
+           column support needs those consumers hardened before this can relax. */
+        const body = JSON.parse(read.toString('utf8'), (key, value) => {
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+                throw new HttpError(400, `Request body property "${key}" is not supported.`);
+            }
+            return value;
+        });
+        if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+            throw new HttpError(400, 'Request body must be a JSON object.');
+        }
+        return body;
+    }
+    catch (error) {
+        if (error instanceof HttpError)
+            throw error;
+        throw new HttpError(400, 'Request body was not valid JSON.');
+    }
+}

package/dist/server/http/requestOrigin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The origin a request was made to, as the browser that made it wrote it:
+ * what a sitemap's `<loc>` and a link preview's `og:url` must be, since both
+ * are read away from the page and need an absolute address. The Host header
+ * has already been held to the server's allowed hosts by the gate
+ * (trust.ts); the scheme is https when the request arrived over https
+ * (trust.ts `arrivedOverHttps`), and http otherwise.
+ */
+import type { IncomingMessage } from 'node:http';
+import { type Bound } from './trust.js';
+export declare function requestOrigin(req: Pick<IncomingMessage, 'headers' | 'socket'>, bound: Pick<Bound, 'trustedProxies'>): string | undefined;

package/dist/server/http/requestOrigin.js

@@ -0,0 +1,8 @@
+import { arrivedOverHttps } from './trust.js';
+export function requestOrigin(req, bound) {
+    const host = String(req.headers.host ?? '').trim();
+    // A host, an optional port: anything else is not an origin to write into a page.
+    if (!/^(?:[a-z0-9.-]+|\[[0-9a-f:.]+\])(?::\d{1,5})?$/i.test(host))
+        return undefined;
+    return `${arrivedOverHttps(req, bound.trustedProxies) ? 'https' : 'http'}://${host.toLowerCase()}`;
+}

package/dist/server/http/router.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How a dispatcher is put together: the door (door.ts) and then tables of
+ * routes, each tried in order until one answers. A route is a predicate
+ * that answers as it decides, so a table reads as the order requests are
+ * matched in, and moving a route moves its precedence with it — which is
+ * why the tables are lists rather than a map keyed by path.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** What every route is handed, whatever product's dispatcher it sits in: the request, and what that product adds. */
+export type RequestContext<Ext = object> = {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly url: URL;
+    readonly path: string;
+} & Ext;
+/** One route: true when it answered the request. */
+export type Route<C extends RequestContext> = (ctx: C) => boolean | Promise<boolean>;
+/** Try `routes` in order; true when one answered. */
+export declare function route<C extends RequestContext>(ctx: C, routes: readonly Route<C>[]): Promise<boolean>;
+/**
+ * Every dispatcher: a module that takes a request from a socket (or a host's
+ * server) and holds it to the door before any route reads it, in the door's
+ * order — the Host, the proxy's identity, the product's session, then a
+ * write's Origin and body. test/door.test.ts stands each up and sends it the
+ * same refusals; a new one is named here, and given a row there.
+ */
+export declare const DISPATCHERS: readonly [{
+    readonly module: 'packages/tablewalk/src/server/http/browserHandler.ts';
+    readonly serves: 'the database browser';
+}, {
+    readonly module: 'packages/mistri/src/server/http/handler.ts';
+    readonly serves: 'the Apps of a deployment that serves them';
+}, {
+    readonly module: 'packages/mistri/src/server/embed/handler.ts';
+    readonly serves: 'an App mounted inside somebody else’s server';
+}, {
+    readonly module: 'packages/mistri/src/server/http/suite.ts';
+    readonly serves: 'several deployments under one origin, each behind its own dispatcher';
+}, {
+    readonly module: 'packages/mistri/src/server/tenant/tenantAuthenticatedHttp.ts';
+    readonly serves: 'a tenant App’s browser host and its native sign-in';
+}, {
+    readonly module: 'packages/mistri/src/server/tenant/tenantHttp.ts';
+    readonly serves: 'a tenant App’s data, inside its browser host';
+}];

package/dist/server/http/router.js

@@ -0,0 +1,22 @@
+/** Try `routes` in order; true when one answered. */
+export async function route(ctx, routes) {
+    for (const each of routes)
+        if (await each(ctx))
+            return true;
+    return false;
+}
+/**
+ * Every dispatcher: a module that takes a request from a socket (or a host's
+ * server) and holds it to the door before any route reads it, in the door's
+ * order — the Host, the proxy's identity, the product's session, then a
+ * write's Origin and body. test/door.test.ts stands each up and sends it the
+ * same refusals; a new one is named here, and given a row there.
+ */
+export const DISPATCHERS = [
+    { module: 'packages/tablewalk/src/server/http/browserHandler.ts', serves: 'the database browser' },
+    { module: 'packages/mistri/src/server/http/handler.ts', serves: 'the Apps of a deployment that serves them' },
+    { module: 'packages/mistri/src/server/embed/handler.ts', serves: 'an App mounted inside somebody else’s server' },
+    { module: 'packages/mistri/src/server/http/suite.ts', serves: 'several deployments under one origin, each behind its own dispatcher' },
+    { module: 'packages/mistri/src/server/tenant/tenantAuthenticatedHttp.ts', serves: 'a tenant App’s browser host and its native sign-in' },
+    { module: 'packages/mistri/src/server/tenant/tenantHttp.ts', serves: 'a tenant App’s data, inside its browser host' },
+];