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

package/dist/server/http/rateLimit.js

@@ -0,0 +1,351 @@
+import { CacheUnavailable, scopedCache } from '../../adapters/cache/cacheStore.js';
+import { forwardedClient, ipv6Groups } from './trust.js';
+const MAX_CLIENTS = 10_000;
+function assertWindows(windows) {
+    if (!windows.length || windows.some((w) => !Number.isSafeInteger(w.limit) || w.limit < 1 || !Number.isFinite(w.ms) || w.ms <= 0)) {
+        throw new Error('A rate limiter needs at least one window of a positive limit over a positive span.');
+    }
+}
+/** One budget over a set of windows: where each window started and what it has counted. */
+class Budget {
+    starts;
+    counts;
+    seen;
+    constructor(windows, now) {
+        this.starts = windows.map(() => now);
+        this.counts = windows.map(() => 0);
+        this.seen = now;
+    }
+    /** Roll over the windows that have elapsed; the seconds until the longest exceeded one reopens, or 0. */
+    wait(windows, now) {
+        let wait = 0;
+        windows.forEach((window, i) => {
+            if (now - this.starts[i] >= window.ms) {
+                this.starts[i] = now;
+                this.counts[i] = 0;
+            }
+            if (this.counts[i] >= window.limit)
+                wait = Math.max(wait, Math.ceil((this.starts[i] + window.ms - now) / 1000), 1);
+        });
+        return wait;
+    }
+    /** Count one request; what is left in the tightest window. */
+    count(windows) {
+        let remaining = Infinity;
+        windows.forEach((window, i) => {
+            this.counts[i]++;
+            remaining = Math.min(remaining, window.limit - this.counts[i]);
+        });
+        return remaining;
+    }
+}
+/**
+ * The key a client's budget is kept under. IPv4 as it is; an IPv4-mapped
+ * IPv6 address (`::ffff:192.0.2.1`, how a dual-stack socket reports an IPv4
+ * peer) as that IPv4 address; any other IPv6 address as its /64, the
+ * smallest network one subscriber is routinely given — one host can
+ * otherwise draw a fresh budget from each of its 2^64 addresses. Anything
+ * that is not an address (`unknown`) is its own key.
+ */
+export function limitKey(address) {
+    if (!address.includes(':'))
+        return address;
+    const groups = ipv6Groups(address);
+    if (!groups)
+        return address;
+    if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff) {
+        return `${groups[6] >> 8}.${groups[6] & 255}.${groups[7] >> 8}.${groups[7] & 255}`;
+    }
+    return `${groups
+        .slice(0, 4)
+        .map((group) => group.toString(16))
+        .join(':')}::/64`;
+}
+export class FixedWindowLimiter {
+    windows;
+    now;
+    /* Least recently seen first. Named `hits` still: the review's probe reads its size. */
+    hits = new Map();
+    longest;
+    maxClients;
+    whenFull;
+    totalWindows;
+    total;
+    constructor(windows, now = Date.now, options = {}) {
+        this.windows = windows;
+        this.now = now;
+        assertWindows(windows);
+        if (options.total)
+            assertWindows(options.total);
+        const maxClients = options.maxClients ?? MAX_CLIENTS;
+        if (!Number.isSafeInteger(maxClients) || maxClients < 1)
+            throw new Error('A rate limiter tracks at least one client.');
+        this.longest = Math.max(...windows.map((window) => window.ms));
+        this.maxClients = maxClients;
+        this.whenFull = options.whenFull ?? 'refuse';
+        this.totalWindows = options.total;
+    }
+    /** Count one request for the client, or say how long it waits. */
+    take(address, part = 'both') {
+        const now = this.now();
+        this.expire(now);
+        if (part === 'all')
+            return this.takeShared(now) ?? { ok: true, remaining: Infinity };
+        const key = limitKey(address);
+        const entry = this.hits.get(key);
+        if (entry) {
+            // Seen again, refused or not: a client still knocking keeps what it spent.
+            this.hits.delete(key);
+            this.hits.set(key, entry);
+            entry.seen = now;
+            const wait = entry.wait(this.windows, now);
+            if (wait > 0)
+                return { ok: false, retryAfterSeconds: wait, scope: 'client' };
+        }
+        const shared = part === 'both' && this.totalWindows ? (this.total ??= new Budget(this.totalWindows, now)) : undefined;
+        const sharedWait = shared ? shared.wait(this.totalWindows, now) : 0;
+        if (sharedWait > 0)
+            return { ok: false, retryAfterSeconds: sharedWait, scope: 'all' };
+        let budget = entry;
+        if (!budget) {
+            if (this.hits.size >= this.maxClients) {
+                const [stalest, oldest] = this.hits.entries().next().value;
+                /* Every slot holds a budget still in force. Evicting one forgets
+                   what that client spent, so a client rotating addresses past the
+                   cap would come back to a fresh budget — the one thing a limiter
+                   exists to withhold. `refuse` keeps every budget and turns the
+                   newcomer away until the stalest slot expires on its own (at most
+                   the longest window): the fail-safe direction, and the submit
+                   limiter's. It refuses no one a flood would not already have
+                   refused, since reaching the cap there needs more admitted
+                   submissions than the shared ceiling allows in a window. `evict`
+                   is for reads, where a forgotten budget costs a page of
+                   presentation and a refusal would let a flood of addresses blank
+                   the form for everyone arriving after it. */
+                if (this.whenFull === 'refuse') {
+                    return { ok: false, retryAfterSeconds: Math.max(1, Math.ceil((oldest.seen + this.longest - now) / 1000)), scope: 'all' };
+                }
+                this.hits.delete(stalest);
+            }
+            budget = new Budget(this.windows, now);
+            this.hits.set(key, budget);
+        }
+        const remaining = budget.count(this.windows);
+        shared?.count(this.totalWindows);
+        return { ok: true, remaining };
+    }
+    /* The shared ceiling alone: a refusal, or undefined once counted (or where there is none). */
+    takeShared(now) {
+        if (!this.totalWindows)
+            return undefined;
+        const shared = (this.total ??= new Budget(this.totalWindows, now));
+        const wait = shared.wait(this.totalWindows, now);
+        if (wait > 0)
+            return { ok: false, retryAfterSeconds: wait, scope: 'all' };
+        shared.count(this.totalWindows);
+        return undefined;
+    }
+    /** How many clients are tracked; tests read it. */
+    get size() {
+        return this.hits.size;
+    }
+    /** Forget every client and the shared count; tests and a policy reload use it. */
+    reset() {
+        this.hits.clear();
+        this.total = undefined;
+    }
+    /* A budget last seen a longest-window ago has nothing left in force:
+       each take rolls over what elapsed, so every window then began after
+       `seen - longest`. The Map is in seen order, so the sweep stops at the
+       first entry still live. */
+    expire(now) {
+        for (const [key, entry] of this.hits) {
+            if (entry.seen + this.longest > now)
+                break;
+            this.hits.delete(key);
+        }
+    }
+}
+/**
+ * The same windows, counted in the deployment's cache so every instance
+ * spends one budget. Each window is a key per client (and one for everyone)
+ * counted by the cache's atomic windowed count, which starts the window on
+ * the first request; a refused request is counted too, which only keeps an
+ * exceeded window exceeded until it ends on its own. There is no cap on
+ * tracked clients to keep: every key expires with its window.
+ *
+ * When the cache cannot count, the process's own limiter decides — the
+ * budget degrades to one instance's, never to none.
+ */
+export class SharedWindowLimiter {
+    name;
+    windows;
+    cache;
+    fallback;
+    totalWindows;
+    constructor(name, windows, cache, fallback, totalWindows) {
+        this.name = name;
+        this.windows = windows;
+        this.cache = cache;
+        this.fallback = fallback;
+        this.totalWindows = totalWindows;
+        assertWindows(windows);
+        if (totalWindows)
+            assertWindows(totalWindows);
+    }
+    async take(address, part = 'both') {
+        try {
+            let remaining = Infinity;
+            if (part !== 'all') {
+                const client = await this.count(this.windows, `${this.name}:${limitKey(address)}`);
+                if (client.wait > 0)
+                    return { ok: false, retryAfterSeconds: client.wait, scope: 'client' };
+                remaining = client.remaining;
+            }
+            if (part !== 'client' && this.totalWindows) {
+                const all = await this.count(this.totalWindows, `${this.name}:*`);
+                if (all.wait > 0)
+                    return { ok: false, retryAfterSeconds: all.wait, scope: 'all' };
+            }
+            return { ok: true, remaining };
+        }
+        catch (error) {
+            if (!(error instanceof CacheUnavailable))
+                throw error;
+            return this.fallback.take(address, part);
+        }
+    }
+    reset() {
+        this.fallback.reset();
+    }
+    async count(windows, key) {
+        let wait = 0;
+        let remaining = Infinity;
+        for (const [i, window] of windows.entries()) {
+            const { count, ttlMs } = await this.cache.incr(`${key}:${i}`, window.ms);
+            if (count > window.limit)
+                wait = Math.max(wait, Math.max(1, Math.ceil(ttlMs / 1000)));
+            else
+                remaining = Math.min(remaining, window.limit - count);
+        }
+        return { wait, remaining };
+    }
+}
+/** The client a limit counts against; a forwarded header only from a trusted peer (loopback, or `--trust-proxy`). */
+export function clientAddress(req, trusted = []) {
+    return forwardedClient(req, trusted);
+}
+/* The public forms' defaults, across every public form of the App: five
+   submissions a minute and thirty an hour per client, three hundred an hour
+   across every client, sixty reads a minute per client. One instance per
+   process, shared by every request; `resetPublicFormLimits` is for tests
+   that run several servers in one. */
+export const PUBLIC_FORM_SUBMIT_WINDOWS = Object.freeze([
+    { limit: 5, ms: 60_000 },
+    { limit: 30, ms: 3_600_000 },
+]);
+export const PUBLIC_FORM_SUBMIT_TOTAL = Object.freeze([{ limit: 300, ms: 3_600_000 }]);
+export const PUBLIC_FORM_READ_WINDOWS = Object.freeze([{ limit: 60, ms: 60_000 }]);
+/* An account-creating invitation's claim is shaped like a submission — the
+   same per-client windows and ceiling, the same refusal — but counted in a
+   budget of its own: a busy public form must not use up the claims a dealer's
+   new staff can make, nor the other way about. */
+export const INVITATION_CLAIM_WINDOWS = PUBLIC_FORM_SUBMIT_WINDOWS;
+export const INVITATION_CLAIM_TOTAL = PUBLIC_FORM_SUBMIT_TOTAL;
+/* A form saved on every step opens a draft in the App's real tables on its
+   first step, so the drafts one client may open are capped apart from its
+   submissions: ten an hour — an applicant who starts over a few times is never
+   near it, and a script cannot fill the root table with abandoned drafts. A
+   status check is a guess at a receipt and its confirmations, so it is
+   counted tighter still, per client here and per receipt in its own lockout
+   (forms/statusCheck.ts). */
+const SAVED_FORM_START_WINDOWS = Object.freeze([{ limit: 10, ms: 3_600_000 }]);
+const SAVED_FORM_START_TOTAL = Object.freeze([{ limit: 500, ms: 3_600_000 }]);
+const STATUS_CHECK_WINDOWS = Object.freeze([
+    { limit: 5, ms: 60_000 },
+    { limit: 20, ms: 3_600_000 },
+]);
+const STATUS_CHECK_TOTAL = Object.freeze([{ limit: 600, ms: 3_600_000 }]);
+/* Adding an application to an account — spending the browser's claim, or
+   linking after a status check — is counted on its own too: a person links
+   the one application they made, so a handful a minute is already generous. */
+const LINK_WINDOWS = Object.freeze([
+    { limit: 5, ms: 60_000 },
+    { limit: 20, ms: 3_600_000 },
+]);
+const LINK_TOTAL = Object.freeze([{ limit: 300, ms: 3_600_000 }]);
+/* A request that makes the server send an email — a code to prove an
+   address — is counted apart and tightest: a person asks for one or two. */
+const CODE_WINDOWS = Object.freeze([
+    { limit: 3, ms: 60_000 },
+    { limit: 10, ms: 3_600_000 },
+]);
+const CODE_TOTAL = Object.freeze([{ limit: 300, ms: 3_600_000 }]);
+/* A step's check: a form's own pages asking the server's word as someone goes on, so a page's worth a minute from one
+   client, and never counted against what that client may submit. */
+const CHECK_WINDOWS = Object.freeze([{ limit: 60, ms: 60_000 }]);
+const CHECK_TOTAL = Object.freeze([{ limit: 6_000, ms: 60_000 }]);
+const check = new FixedWindowLimiter(CHECK_WINDOWS, Date.now, { total: CHECK_TOTAL, whenFull: 'evict' });
+const submit = new FixedWindowLimiter(PUBLIC_FORM_SUBMIT_WINDOWS, Date.now, { total: PUBLIC_FORM_SUBMIT_TOTAL, whenFull: 'refuse' });
+const read = new FixedWindowLimiter(PUBLIC_FORM_READ_WINDOWS, Date.now, { whenFull: 'evict' });
+const claim = new FixedWindowLimiter(INVITATION_CLAIM_WINDOWS, Date.now, { total: INVITATION_CLAIM_TOTAL, whenFull: 'refuse' });
+const start = new FixedWindowLimiter(SAVED_FORM_START_WINDOWS, Date.now, { total: SAVED_FORM_START_TOTAL, whenFull: 'refuse' });
+const status = new FixedWindowLimiter(STATUS_CHECK_WINDOWS, Date.now, { total: STATUS_CHECK_TOTAL, whenFull: 'refuse' });
+const link = new FixedWindowLimiter(LINK_WINDOWS, Date.now, { total: LINK_TOTAL, whenFull: 'refuse' });
+const code = new FixedWindowLimiter(CODE_WINDOWS, Date.now, { total: CODE_TOTAL, whenFull: 'refuse' });
+let shared;
+export function publicFormLimiter(kind) {
+    if (shared)
+        return shared[kind];
+    if (kind === 'check')
+        return check;
+    return kind === 'submit'
+        ? submit
+        : kind === 'read'
+            ? read
+            : kind === 'start'
+                ? start
+                : kind === 'link'
+                    ? link
+                    : kind === 'code'
+                        ? code
+                        : status;
+}
+/** The invitation claims' own budget (tenantInvitationHttp.ts), never the forms'. */
+export function invitationClaimLimiter() {
+    return shared ? shared.claim : claim;
+}
+/**
+ * Count the public forms' windows in the deployment's cache, under the
+ * deployment's namespace (`tw:<app>:form:`), or — with no cache, or the
+ * process's own — in this process, as before.
+ */
+export function configurePublicFormLimits(cache, namespace) {
+    if (!cache || cache.kind === 'memory') {
+        shared = undefined;
+        return;
+    }
+    const scoped = scopedCache(cache, `tw:${namespace}:form:`);
+    shared = {
+        submit: new SharedWindowLimiter('submit', PUBLIC_FORM_SUBMIT_WINDOWS, scoped, submit, PUBLIC_FORM_SUBMIT_TOTAL),
+        read: new SharedWindowLimiter('read', PUBLIC_FORM_READ_WINDOWS, scoped, read),
+        // Its own key prefix, so the claims' windows are counted apart from the forms'.
+        claim: new SharedWindowLimiter('claim', INVITATION_CLAIM_WINDOWS, scoped, claim, INVITATION_CLAIM_TOTAL),
+        start: new SharedWindowLimiter('start', SAVED_FORM_START_WINDOWS, scoped, start, SAVED_FORM_START_TOTAL),
+        status: new SharedWindowLimiter('status', STATUS_CHECK_WINDOWS, scoped, status, STATUS_CHECK_TOTAL),
+        link: new SharedWindowLimiter('link', LINK_WINDOWS, scoped, link, LINK_TOTAL),
+        code: new SharedWindowLimiter('code', CODE_WINDOWS, scoped, code, CODE_TOTAL),
+        check: new SharedWindowLimiter('check', CHECK_WINDOWS, scoped, check, CHECK_TOTAL),
+    };
+}
+/** Forgets the forms' budgets and the claims'; tests and a policy reload use it. */
+export function resetPublicFormLimits() {
+    submit.reset();
+    read.reset();
+    claim.reset();
+    start.reset();
+    status.reset();
+    link.reset();
+    code.reset();
+    check.reset();
+}

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

@@ -0,0 +1,9 @@
+import { type RequestContext, type ResolvedSource } from './context.js';
+/** What a product serves among the reads. */
+export interface ReadHooks {
+    /** What the client draws around the data: the App, its pages, the stored layouts and filters. True when answered. */
+    projection(ctx: RequestContext, source: ResolvedSource): Promise<boolean>;
+    /** One file's bytes, from a resource whose rows are files. False where the resource holds none. */
+    file?(ctx: RequestContext, source: ResolvedSource): Promise<boolean>;
+}
+export declare function readRoutes(ctx: RequestContext, source: ResolvedSource, hooks: ReadHooks): Promise<boolean>;

package/dist/server/http/readRoutes.js

@@ -0,0 +1,131 @@
+/**
+ * The GET reads that need a resolved database: the schema and the
+ * connection-scoped halves of the config file — views, saved SQL, a table's
+ * DDL. What a product draws around the data (`ReadHooks.projection`: an
+ * App's payload and pages, or the database browser's) sits between them in
+ * the same chain, and a resource whose rows are files is the App's
+ * (`ReadHooks.file`, appFileRead.ts).
+ */
+import { validateView } from '../../shared/view.js';
+import { textToView, viewToTextWithSchema } from '../../shared/viewtext.js';
+import { queriesFor } from '../../shared/sqlsaved.js';
+import { findTable, renderDDL } from '../../shared/schema.js';
+import { send, sendRevalidated } from './reply.js';
+import { principalOf } from './context.js';
+/** The `Sec-Fetch-Dest` values that load what they fetch as code. */
+const SCRIPT_DESTINATIONS = new Set(['script', 'style', 'worker', 'sharedworker', 'serviceworker', 'audioworklet', 'paintworklet', 'xslt']);
+export async function readRoutes(ctx, source, hooks) {
+    const { res, url, path, registry, configViews, configQueries } = ctx;
+    const { adapter, schema, access, connectionId, publicScope, publicDefinition } = source;
+    /**
+     * Views defined in the config file, for the connection in hand.
+     *
+     * Saved views live in the browser, per connection — they are one person's
+     * working set, and writing them into a file the server owns would make a
+     * page silently edit something on disk. Config views are the shared half:
+     * checked into a repo, the same for everyone, and read-only from here.
+     *
+     * A view whose base table does not exist on this connection is returned
+     * *with its reason* rather than dropped. Dropping it shows a shorter list
+     * and no explanation, which is the failure this whole tool argues against.
+     */
+    if (path === '/api/views') {
+        const name = registry.list().find((c) => c.id === connectionId)?.name;
+        const mine = configViews.filter((v) => !v.connection || v.connection === connectionId || v.connection === name);
+        send(res, 200, {
+            ...publicScope,
+            views: access ? [] : mine.map((v) => publicDefinition(materialise(schema, v))),
+        });
+        return true;
+    }
+    if (path === '/api/schema') {
+        sendRevalidated(res, schema, principalOf(ctx.identity));
+        return true;
+    }
+    /**
+     * One file's bytes, from a resource whose rows are files (`file` on the
+     * resource). The read is the ordinary query, so the App's table and field
+     * grants apply to it, asked for the bytes instead of their label. A
+     * download, unless `inline=1` asks for a picture and the bytes are one: a
+     * stored type is only the uploader's claim, so it never decides either.
+     * `variant=thumb` asks for the resource's smaller copy (`file.thumbnail`),
+     * which a card draws at a third of the width; a resource or a row without
+     * one answers with the file itself.
+     */
+    if (path === '/api/file') {
+        /* An upload is never code to run. A page that loads one as a script or a
+           stylesheet (`<script src="/api/file?…">`) asks with its destination,
+           and is refused before anything is read: with nosniff and a download's
+           type the browser would refuse it too, but only if it honours both. */
+        if (SCRIPT_DESTINATIONS.has(String(ctx.req.headers['sec-fetch-dest'] ?? '').toLowerCase())) {
+            send(res, 403, { error: 'A file is not served as a script or a stylesheet.' });
+            return true;
+        }
+        if (!(await hooks.file?.(ctx, source)))
+            send(res, 404, { error: 'This resource does not hold files.' });
+        return true;
+    }
+    if (await hooks.projection(ctx, source))
+        return true;
+    /**
+     * SQL statements the config file names, for the connection in hand.
+     *
+     * The committable half of saved SQL. The other half lives in the browser,
+     * and the client merges them — a statement someone checked in and one you
+     * saved this morning are the same kind of thing to whoever is looking for
+     * one, and only differ in whether you may delete it.
+     */
+    if (path === '/api/queries') {
+        const name = registry.list().find((c) => c.id === connectionId)?.name;
+        send(res, 200, {
+            connection: connectionId,
+            queries: queriesFor(configQueries, connectionId, name),
+        });
+        return true;
+    }
+    /**
+     * A table's definition. `exact` tells the client whether it is looking at
+     * the database's own stored DDL or a reconstruction from the catalog, so
+     * the page can label it rather than implying an authority it lacks.
+     */
+    if (path === '/api/ddl') {
+        const tableId = url.searchParams.get('table') ?? '';
+        if (!findTable(schema, tableId)) {
+            send(res, 404, { error: `Unknown table "${tableId}"` });
+            return true;
+        }
+        const stored = adapter.ddl ? await adapter.ddl(tableId) : undefined;
+        send(res, 200, {
+            table: tableId,
+            sql: stored ?? renderDDL(schema, tableId),
+            exact: Boolean(stored),
+        });
+        return true;
+    }
+    return false;
+}
+/**
+ * Expand a config view against a live schema, and say what is wrong with it.
+ *
+ * A view written as text cannot be expanded when the config file is read —
+ * there is no connection open yet, and the text names tables. So it is
+ * carried through and resolved here, where a schema exists. Both halves are
+ * returned: the structure, so the composer can edit it by clicking, and the
+ * text, so it can be read and edited as a statement.
+ *
+ * A view that does not resolve comes back *with its reason*, never dropped.
+ * Dropping it gives someone a shorter list and no explanation, which is the
+ * failure this whole tool argues against.
+ */
+function materialise(schema, view) {
+    if (!view.text) {
+        const error = validateView(schema, view);
+        return { ...view, error, text: error ? undefined : viewToTextWithSchema(schema, view) };
+    }
+    const parsed = textToView(schema, view.text, { id: view.id, name: view.name });
+    if (!parsed.view || parsed.errors.length) {
+        return { ...view, error: parsed.errors[0]?.message ?? `"${view.name}" could not be read.` };
+    }
+    const expanded = { ...parsed.view, source: view.source, connection: view.connection, text: view.text };
+    return { ...expanded, error: validateView(schema, expanded) };
+}

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

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ReadContext } from '../../adapters/replicas.js';
+/** Whether the POST `path` with `body` may read from a replica. */
+export declare function toleratesLag(path: string, body: Readonly<Record<string, unknown>>): boolean;
+/** The cookie a write sets so the same browser's next reads go to the primary, in the running product's name. */
+export declare const freshCookie: () => string;
+/**
+ * The read-your-write context for one request (replicas.ts `readsAs`).
+ *
+ * A browser carries the marker: a write sets `<product>_fresh=<write time>` (`mistri_fresh`, or `tablewalk_fresh` in the browser)
+ * for FRESH_READ_MS on the App's base path, and a request that brings one
+ * back within that time reads the primary. It needs no shared state, so it
+ * holds whichever pod the next request reaches, and each visitor — signed
+ * in or not — has their own. It is HttpOnly and SameSite=Lax like the
+ * other cookies here, and never Secure-only: it holds a time, not a
+ * secret, and a forged or stolen one buys nothing but primary reads for
+ * ten seconds. A caller sending a bearer token has no cookie jar, so its
+ * writes are remembered in this process under a digest of the token.
+ */
+export declare function readFreshness(request: Pick<IncomingMessage, 'headers'>, response: Pick<ServerResponse, 'headersSent' | 'getHeader' | 'setHeader'>, base: string, now?: () => number): ReadContext;

package/dist/server/http/readRouting.js

@@ -0,0 +1,80 @@
+/**
+ * Which body routes may read from a replica (packages/engine/src/adapters/replicas.ts).
+ *
+ * Lag-tolerant: a list's page and its counts (`/api/query`, `/api/run`,
+ * `/api/view/run`, `/api/count`, `/api/counts`), a dashboard's breakdowns
+ * (`/api/breakdown`, `/api/breakdowns`) and an export (`/api/export`) —
+ * the Workbench grid and an App's lists, search and charts all arrive as
+ * these. A row a moment old is what anyone reading a list already accepts:
+ * it was a moment old by the time it was drawn.
+ *
+ * Everything else reads the primary, and so does a read of one row
+ * (`limit: 1`): that is a record's own read — the record page, the
+ * Workbench record, a section's probe — and a record is where a person
+ * looks for what they just saved. A composed record page is pinned whole
+ * (handler.ts), related lists and all. Commands, writes, the catalog,
+ * the stores, raw SQL and the MCP tools never ask for a replica.
+ */
+import { createHash } from 'node:crypto';
+import { FRESH_READ_MS } from '../../adapters/replicas.js';
+import { product } from '../product.js';
+const LAG_TOLERANT = new Set([
+    '/api/query',
+    '/api/run',
+    '/api/view/run',
+    '/api/count',
+    '/api/counts',
+    '/api/breakdown',
+    '/api/breakdowns',
+    '/api/export',
+]);
+/** Whether the POST `path` with `body` may read from a replica. */
+export function toleratesLag(path, body) {
+    if (!LAG_TOLERANT.has(path))
+        return false;
+    const view = body.view && typeof body.view === 'object' ? body.view : undefined;
+    return body.limit !== 1 && view?.limit !== 1;
+}
+/** The cookie a write sets so the same browser's next reads go to the primary, in the running product's name. */
+export const freshCookie = () => `${product()}_fresh`;
+/**
+ * The read-your-write context for one request (replicas.ts `readsAs`).
+ *
+ * A browser carries the marker: a write sets `<product>_fresh=<write time>` (`mistri_fresh`, or `tablewalk_fresh` in the browser)
+ * for FRESH_READ_MS on the App's base path, and a request that brings one
+ * back within that time reads the primary. It needs no shared state, so it
+ * holds whichever pod the next request reaches, and each visitor — signed
+ * in or not — has their own. It is HttpOnly and SameSite=Lax like the
+ * other cookies here, and never Secure-only: it holds a time, not a
+ * secret, and a forged or stolen one buys nothing but primary reads for
+ * ten seconds. A caller sending a bearer token has no cookie jar, so its
+ * writes are remembered in this process under a digest of the token.
+ */
+export function readFreshness(request, response, base, now = Date.now) {
+    const bearer = /^Bearer\s+(\S+)/i.exec(request.headers.authorization ?? '')?.[1];
+    if (bearer)
+        return { fresh: false, key: `bearer:${createHash('sha256').update(bearer).digest('base64url').slice(0, 22)}` };
+    const at = now();
+    const fresh = cookieValues(request.headers.cookie, freshCookie()).some((value) => {
+        const wrote = /^\d{1,16}$/.test(value) ? Number(value) : NaN;
+        // A time ahead of this clock by more than a little is not one this server wrote.
+        return wrote <= at + 1_000 && at - wrote < FRESH_READ_MS;
+    });
+    return {
+        fresh,
+        onWrite: () => {
+            if (response.headersSent)
+                return;
+            const cookie = `${freshCookie()}=${now()}; Path=${base || '/'}; Max-Age=${FRESH_READ_MS / 1000}; HttpOnly; SameSite=Lax`;
+            const prior = response.getHeader('set-cookie');
+            response.setHeader('set-cookie', prior === undefined ? cookie : [...(Array.isArray(prior) ? prior : [String(prior)]), cookie]);
+        },
+    };
+}
+function cookieValues(header, name) {
+    return (header ?? '')
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith(`${name}=`))
+        .map((part) => part.slice(name.length + 1));
+}

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

@@ -0,0 +1,67 @@
+/**
+ * A record page in one request (shared/recordReads.ts says why).
+ *
+ * `POST /api/pages/compose` takes what `/api/pages/plan` takes — the page,
+ * by name or as itself, and the record's key — with the reader's page size
+ * for related lists (`rows`) and the tab it opens on (`tab`). It plans the
+ * page, then asks every read the sections it draws will send: the record's
+ * row once for every section that reads it, each related list's first page
+ * and totals, each figure, each timeline and custom read, each `when`, the
+ * record's history and which of its commands are available. Each is asked
+ * of the route the section's own request reaches, on this request's source —
+ * one admission, one session, one row-policy context, the same grants, row
+ * scope and hidden columns — through `post`, which is the dispatcher's own,
+ * into a reply held in memory. What a signed-out visitor or a row policy may
+ * not ask on its own is not asked here either.
+ *
+ * The answer is the plan, as `/api/pages/plan` answers it, and beside it
+ * each read that succeeded with the request it answers. A read that failed
+ * is left out: the section asks it itself, and is refused in its own words.
+ */
+import type { ServerResponse } from 'node:http';
+import { type PageDef } from '../../shared/page.js';
+import type { RequestContext, ResolvedSource } from './context.js';
+export declare const COMPOSE_PATH = "/api/pages/compose";
+/** The resources of the App a page is drawn in, as far as composing its reads needs them. */
+export type ComposeResources = Record<string, {
+    recordLabel?: string | false;
+    defined?: Record<string, {
+        per?: string;
+    }>;
+    actions?: Array<{
+        when?: string;
+        command?: {
+            id: string;
+            version: number;
+            target: string;
+        };
+    }>;
+}>;
+/** One availability check of a record's command, as `/api/commands/availability` takes it. */
+interface CommandCheck {
+    readonly command: string;
+    readonly commandVersion: number;
+    readonly keys: Record<string, unknown>[];
+}
+/** What a product decides of a composed page. The database browser asks every part, has no App, and runs no commands. */
+export interface ComposeHooks {
+    /** Whether this request's reader may ask `path` on its own: the gate's and the row policy's rule for that route. */
+    mayAsk(ctx: RequestContext, path: string): boolean;
+    /** The App's resources as this reader is served them, or none. */
+    resources(ctx: RequestContext, source: ResolvedSource): ComposeResources;
+    /** A table's suggested page (`suggested:<table>`). */
+    suggested(source: ResolvedSource, table: string): PageDef | null;
+    /** Which of the record's commands are available to this reader: the availability route's answer, or none. */
+    availability?(ctx: RequestContext, checks: CommandCheck[]): Promise<{
+        status: number;
+        body: unknown;
+    } | undefined>;
+}
+export declare function composeRecordPage({ ctx, source, body, post, hooks, }: {
+    ctx: RequestContext;
+    source: ResolvedSource;
+    body: Record<string, unknown>;
+    post: (reply: ServerResponse, path: string, body: Record<string, unknown>) => Promise<void>;
+    hooks: ComposeHooks;
+}): Promise<void>;
+export {};