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

package/dist/server/http/captured.js

@@ -0,0 +1,73 @@
+/**
+ * A reply held in memory: what a route sends when it answers a request made
+ * inside another (recordCompose.ts). The route is the same code an HTTP
+ * request reaches — the same grants, row scope and hidden columns — and
+ * writes through `send` as ever; only the bytes stop here instead of on a
+ * socket. Just enough of ServerResponse for the reply helpers (reply.ts) and
+ * the routes that set a header on the way.
+ */
+import { EventEmitter } from 'node:events';
+export class CapturedReply extends EventEmitter {
+    statusCode = 200;
+    headersSent = false;
+    writableEnded = false;
+    destroyed = false;
+    /** No request: nothing is compressed, and the whole reply is one JSON body. */
+    req = undefined;
+    headers = new Map();
+    chunks = [];
+    setHeader(name, value) {
+        this.headers.set(name.toLowerCase(), value);
+        return this;
+    }
+    getHeader(name) {
+        return this.headers.get(name.toLowerCase());
+    }
+    hasHeader(name) {
+        return this.headers.has(name.toLowerCase());
+    }
+    removeHeader(name) {
+        this.headers.delete(name.toLowerCase());
+    }
+    writeHead(status, headers) {
+        this.statusCode = status;
+        for (const [name, value] of Object.entries(headers ?? {}))
+            if (value !== undefined)
+                this.setHeader(name, value);
+        this.headersSent = true;
+        return this;
+    }
+    write(chunk) {
+        this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        return true;
+    }
+    end(chunk) {
+        if (chunk !== undefined)
+            this.write(chunk);
+        this.headersSent = true;
+        this.writableEnded = true;
+        this.emit('finish');
+        return this;
+    }
+    destroy() {
+        this.destroyed = true;
+        this.emit('close');
+        return this;
+    }
+    /** As the route answered: its status and its JSON, or undefined when it sent nothing. */
+    answer() {
+        if (!this.writableEnded)
+            return undefined;
+        const text = Buffer.concat(this.chunks).toString('utf8');
+        try {
+            return { status: this.statusCode, body: text ? JSON.parse(text) : null };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Typed as the response the routes take. */
+    asResponse() {
+        return this;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function clockNow(): Date;

package/dist/server/http/clock.js

@@ -0,0 +1,14 @@
+/**
+ * The wall clock, unless a test has pinned it: MISTRI_CLOCK holds an
+ * instant the browser suite fixes so that "last 90 days" over a database
+ * seeded for a known day reads the same on every run, and a stamp an action
+ * writes ('now') is the same instant on every run. Never set in use.
+ */
+import { productEnv } from '../product.js';
+export function clockNow() {
+    const pinned = productEnv('CLOCK');
+    if (!pinned)
+        return new Date();
+    const at = new Date(pinned);
+    return Number.isNaN(at.getTime()) ? new Date() : at;
+}

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

@@ -0,0 +1,4 @@
+import type { RequestContext, ResolvedSource } from './context.js';
+/** The query-string key a request names its source with. */
+export declare function sourceSelector(ctx: Pick<RequestContext, 'appConfigured'>): 'app' | 'conn';
+export declare function resolveConnectionSource(ctx: RequestContext, id: string | null | undefined): Promise<ResolvedSource>;

package/dist/server/http/connectionSource.js

@@ -0,0 +1,48 @@
+/**
+ * The source a database browser request reads: the connection it names, or
+ * the active one, opened and leased for the request's life. An App's source
+ * — its resources, its reader's grants, its row policy — is the App
+ * framework's (source.ts), which comes here only for a request no App
+ * curates.
+ */
+import { HttpError } from './reply.js';
+/** The query-string key a request names its source with. */
+export function sourceSelector(ctx) {
+    return ctx.appConfigured ? 'app' : 'conn';
+}
+export async function resolveConnectionSource(ctx, id) {
+    const { res, registry } = ctx;
+    /* Named but unknown is a 404, not a fallback. Falling back ran the
+       request against whatever happened to be active — the right answer to
+       the wrong question, and with raw SQL on the same path, the wrong
+       database. */
+    if (id && !registry.has(id))
+        throw new HttpError(404, `No connection called "${id}".`);
+    const target = id ?? registry.active;
+    if (!target)
+        throw new HttpError(409, 'No connection is open.');
+    const opened = await registry.open(target);
+    const release = registry.lease(target);
+    if (res.destroyed)
+        release();
+    else
+        res.once('close', release);
+    /* Every answer says which database gave it.
+  
+       Set here rather than added to a dozen `send` calls: this is the one
+       place that knows, and a header covers the replies that are arrays and
+       the ones that are errors as well as the ones that are objects.
+  
+       It exists to make the guarantee checkable. "The reply came from the
+       connection the request named" is the whole of the multi-tab fix, and
+       without this it is a claim rather than something a test or a reader can
+       verify. */
+    res.setHeader('x-mistri-connection', target);
+    return {
+        adapter: opened.adapter,
+        schema: opened.schema,
+        connectionId: target,
+        publicScope: { connection: target },
+        publicDefinition: (definition) => definition,
+    };
+}

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

@@ -0,0 +1,189 @@
+/**
+ * What one request carries through the route modules: the parameters
+ * `handle` was called with, the copies it takes, and what the auth gate
+ * established. Built once per request in handler.ts after the gate; every
+ * route module reads it and none writes to it, with the one exception
+ * documented on `configPages`.
+ */
+import type { AddressMount } from '../../shared/mount.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Adapter } from '../../adapters/adapter.js';
+import type { Registry } from '../connections.js';
+import type { ViewDef } from '../../shared/view.js';
+import type { SavedQuery } from '../../shared/sqlsaved.js';
+import type { PageDef } from '../../shared/page.js';
+import type { ConfigLayout } from '../../shared/recordview.js';
+import type { DatabaseSchema } from '../../shared/schema.js';
+import type { QueryPerson } from '../../shared/query.js';
+import type { ColumnGrant } from '../columnGrants.js';
+import type { RequestDiagnostics } from '../operations/diagnostics.js';
+import type { Bound } from './trust.js';
+/**
+ * The App framework's types for what a request carries on its behalf: the
+ * Apps it serves, an App's resources and its reader's grants, its commands,
+ * its row policy, its job host. The engine's routes pass them along and ask
+ * no more of them than the readings below; the App framework registers its
+ * own types by declaring this interface's members (http/appContext.ts), as
+ * a library registers its types with a router. Unregistered — the engine on
+ * its own, or the database browser — each is the engine's reading.
+ *
+ * @public read by declaration merging, which no import shows
+ */
+export interface Register {
+}
+type Registered<Key extends string, Engine> = Register extends {
+    readonly [K in Key]: infer T;
+} ? T : Engine;
+/** An App a request may be on (app/apps.ts AppHost): the engine's routes only count them and pass them on. */
+type HostedApp = Registered<'host', object>;
+/** An App's resources (app/appRuntimeResources.ts): the engine asks only which connection a table is in, and its adapter. */
+type SourceResources = Registered<'resources', {
+    connectionFor(table: string): string;
+    forConnection(connection: string): Adapter;
+}>;
+/** A reader's grants on an App's resources (app/appAccess.ts): the columns, and the fixed actions that admit an update. */
+type SourceAccess = Registered<'access', ColumnGrant & {
+    readonly actions?: ReadonlyMap<string, unknown>;
+}>;
+/** Who is asking: the proxy header's answer, then the session's when there is one. */
+/** Who is asking. `name` is the verified session's own name, for a greeting only. */
+export interface Identity {
+    id?: string;
+    who?: string;
+    role?: string;
+    name?: string;
+    refusal?: string;
+    emailVerified?: true;
+    /** Open sign-up, email not yet proven: the address names nobody (auth.ts Identity). */
+    emailUnproven?: true;
+}
+/** Who a revalidated reply is for (reply.ts sendRevalidated): the verified
+ * account, its roles and the name a proxy or session gave it. */
+export declare function principalOf(identity: Identity): string;
+/**
+ * A request's target as the browser sent it, base path and all, where the
+ * server took the base off (server.ts `routeAddress`): Better Auth routes and
+ * mints its links from the whole address.
+ */
+export declare const arrivedUrls: WeakMap<IncomingMessage, string>;
+/** What the gate reads: settled before it runs, in handler.ts. */
+export interface GateInput {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly path: string;
+    readonly bound: Bound;
+    readonly appHosts?: HostedApp[];
+    /** Where the Apps are served and under what path (shared/mount.ts); `path` is already its inside form. */
+    readonly mount: AddressMount;
+    readonly commandRequest: boolean;
+    /** Answer a business-command request with the failure shape its client reads. */
+    readonly commandRefusal: (code: Registered<'refusal', string>) => void;
+}
+/** What the gate establishes when it lets a request through. */
+export interface GateResult {
+    readonly identity: Identity;
+    /** The one App host that signs people in, when there is one. */
+    readonly signedIn?: HostedApp;
+    readonly hostingError?: string;
+}
+export interface RequestContext extends GateInput, GateResult {
+    readonly url: URL;
+    readonly registry: Registry;
+    readonly configViews: ViewDef[];
+    /** The file this session read its connections from, and writes them back to. */
+    readonly configPath?: string;
+    readonly configQueries: SavedQuery[];
+    /**
+     * Mutable, on purpose: `resolveSource` narrows it to the pages an
+     * access-controlled App's field grants allow, and handlePost then reads the
+     * narrowed list. That was a reassigned local before the split; it is the
+     * one field a route writes.
+     */
+    configPages: PageDef[];
+    readonly configLayouts: ConfigLayout[];
+    readonly commands?: Registered<'commands', unknown>;
+    readonly policy?: Registered<'policy', unknown>;
+    /** True, or what to tell a caller, while the row policy is not serving (cli/serve.ts). */
+    readonly policyUnavailable: boolean | string;
+    readonly diagnostics?: RequestDiagnostics;
+    /** The `--jobs` host, when the deployment runs one. */
+    readonly jobs?: Registered<'jobs', unknown>;
+    /** Whether the browser on this listener is the operator — see `clientTrusted`. */
+    readonly trusted: boolean;
+    readonly appConfigured: boolean;
+    /** The row-policy context this dispatch runs under, when the deployment has one. */
+    readonly policyContext?: Registered<'policyContext', unknown>;
+}
+/** A request past the gate, before the row policy's context (handler.ts `door`). */
+export type GatedContext = Omit<RequestContext, 'policyContext'>;
+/**
+ * One browser connection or App entry point, resolved for the request in
+ * hand. `publicScope` and `publicDefinition` are the reply-shaping half: an
+ * App answer names the app, a connection answer names the connection, and a
+ * definition's connection — a view's `connection`, a page's `connection` — never
+ * leaves an App server.
+ */
+export interface ResolvedSource {
+    readonly adapter: Adapter;
+    readonly schema: DatabaseSchema;
+    readonly resources?: SourceResources;
+    readonly access?: SourceAccess;
+    readonly wholeRowWrites?: ReadonlySet<string>;
+    readonly selectedHost?: HostedApp;
+    readonly connectionId: string;
+    readonly publicScope: {
+        appId: string;
+    } | {
+        connection: string;
+    };
+    readonly publicDefinition: <T extends {
+        connection?: string;
+    }>(definition: T) => T;
+    /** Who `me` is for this request, through the reader it is given (server/app/appMe.ts). */
+    readonly person?: (reader: Adapter) => Promise<QueryPerson>;
+    /** This reader's zone, where `ui.timezone` reads one (readerZone.ts); read through `appZone`. */
+    readonly zone?: string;
+    /** This reader's locale, resolved once (readerLocale.ts `requestLocale`): their words and figures. */
+    readonly locale?: string;
+    /** Their tenant's own words over the App's (recordMessages.ts), stamped by tenant and content: `localizedApp`'s key. */
+    readonly messages?: {
+        readonly stamp: string;
+        readonly words: Registered<'messages', unknown>;
+    };
+}
+/**
+ * What a POST route reads: the body, already parsed once, and the source
+ * the body named. Built where the body is read (handler.ts `postRoute`), once per reply.
+ */
+export interface PostContext {
+    readonly res: ServerResponse;
+    readonly path: string;
+    readonly body: Record<string, unknown>;
+    readonly adapter: Adapter;
+    readonly schema: DatabaseSchema;
+    readonly registry: Registry;
+    readonly connection: string;
+    readonly configPages: PageDef[];
+    readonly appHosts?: HostedApp[];
+    /** Who is asking, when a proxy header or a session says; stamped on every journaled write. */
+    readonly who?: string;
+    /** Their role, when a session says; the write scope may be the role's. */
+    readonly role?: string;
+    readonly resources?: SourceResources;
+    readonly access?: SourceAccess;
+    readonly principal?: string;
+    /** Whose notices this request reads: the signed-in account's email, where it names someone (signedInAs). */
+    readonly recipient?: string;
+    readonly wholeRowWrites?: ReadonlySet<string>;
+    readonly rowPolicy: boolean;
+    readonly appConfigured: boolean;
+    /** "Now" for date phrases, in the app's zone — see `appNowFor`. */
+    readonly appNow: () => Date;
+    /** This reader's zone, where `ui.timezone` reads one (readerZone.ts). */
+    readonly zone?: string;
+    /** The App the request names, where it names one. */
+    readonly appHost?: HostedApp;
+    /** Who `me` is in an App's conditions, read through this request's reader (server/app/appMe.ts). */
+    readonly me?: () => Promise<QueryPerson>;
+}
+export {};

package/dist/server/http/context.js

@@ -0,0 +1,11 @@
+/** Who a revalidated reply is for (reply.ts sendRevalidated): the verified
+ * account, its roles and the name a proxy or session gave it. */
+export function principalOf(identity) {
+    return JSON.stringify([identity.id ?? null, identity.role ?? null, identity.who ?? null]);
+}
+/**
+ * A request's target as the browser sent it, base path and all, where the
+ * server took the base off (server.ts `routeAddress`): Better Auth routes and
+ * mints its links from the whole address.
+ */
+export const arrivedUrls = new WeakMap();

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

@@ -0,0 +1,15 @@
+/**
+ * What a crawler asks a server first — `/robots.txt`, then `/sitemap.xml` —
+ * and the shape of the answer: plain text a crawler may keep for an hour, or
+ * a refusal it may not keep. A server with no public App answers it here
+ * (`closedToCrawlers`): nothing on it is for a search engine. An App's public
+ * pages are listed by its sitemap (sitemap.ts), in the same shape.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const SITEMAP_PATH = "/sitemap.xml";
+export declare const ROBOTS_PATH = "/robots.txt";
+export declare function sendText(req: IncomingMessage, res: ServerResponse, status: number, type: string, body: string): true;
+/** True when `path` is a crawler's question: answered as a GET or HEAD only. */
+export declare function crawlerAsks(req: IncomingMessage, res: ServerResponse, path: string): boolean;
+/** The answer of a server with nothing public: crawl nothing, list nothing. False for any other address. */
+export declare function closedToCrawlers(req: IncomingMessage, res: ServerResponse, path: string): boolean;

package/dist/server/http/crawlerText.js

@@ -0,0 +1,32 @@
+export const SITEMAP_PATH = '/sitemap.xml';
+export const ROBOTS_PATH = '/robots.txt';
+export function sendText(req, res, status, type, body) {
+    res.writeHead(status, {
+        'content-type': `${type}; charset=utf-8`,
+        // A crawler asks again within the hour; a new car is in the next answer.
+        'cache-control': status === 200 ? 'public, max-age=3600' : 'no-store',
+        'x-content-type-options': 'nosniff',
+    });
+    res.end(req.method === 'HEAD' ? undefined : body);
+    return true;
+}
+/** True when `path` is a crawler's question: answered as a GET or HEAD only. */
+export function crawlerAsks(req, res, path) {
+    if (path !== ROBOTS_PATH && path !== SITEMAP_PATH)
+        return false;
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { allow: 'GET, HEAD', 'cache-control': 'no-store' }).end();
+        return true;
+    }
+    return false;
+}
+/** The answer of a server with nothing public: crawl nothing, list nothing. False for any other address. */
+export function closedToCrawlers(req, res, path) {
+    if (path !== ROBOTS_PATH && path !== SITEMAP_PATH)
+        return false;
+    if (crawlerAsks(req, res, path))
+        return true;
+    if (path === ROBOTS_PATH)
+        return sendText(req, res, 200, 'text/plain', 'User-agent: *\nDisallow: /\n');
+    return sendText(req, res, 404, 'text/plain', 'Nothing here is public.\n');
+}

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

@@ -0,0 +1,88 @@
+/**
+ * The data routes both products serve on a resolved source: a POST reads its
+ * body once, resolves the source it names and goes to `handlePost` — the
+ * page routes, an export, the resource reads (resourceReadHttp.ts), a
+ * composed record page, the record writes (recordWrites.ts) — and a GET
+ * goes to the reads (readRoutes.ts).
+ *
+ * What a product decides of them is `DataHooks`, given by its dispatcher:
+ * the database browser's (browserHandler.ts) and the App framework's
+ * (handler.ts). The hooks are where a product's rules enter, and the only
+ * place:
+ *
+ *   - `gates.read`: a reader asking past what they may read (an App's
+ *     signed-out visitor is asked to sign in); `gates.write`, the write gate
+ *     every record write passes (the connection's `writable` flag and the
+ *     reader's grant, in the product's words); `after.write`, what follows a
+ *     committed write (an App's search document);
+ *   - `source`: how the source is resolved (an App's resources and its
+ *     reader's grants, or the connection);
+ *   - the rest — the routes before and after, an export's grants, a page's
+ *     anatomy, a composed page's App — each named on the hook.
+ */
+import type { ServerResponse } from 'node:http';
+import type { Adapter } from '../../adapters/adapter.js';
+import { type AppReads } from '../resourceReadHttp.js';
+import type { PostContext, RequestContext, ResolvedSource } from './context.js';
+import { type ExportHooks } from './exportRoute.js';
+import { type PageHooks } from './pageRoutes.js';
+import { type ReadHooks } from './readRoutes.js';
+import { type ComposeHooks } from './recordCompose.js';
+import { type RecordHooks } from './recordWrites.js';
+/** What a POST is given beside its body and source, by the product. */
+type PostExtras = Partial<Pick<PostContext, 'appNow' | 'zone' | 'appHost' | 'recipient' | 'me'>>;
+export interface DataHooks {
+    /** The source a request names (`null`: none), resolved and leased for the request's life. */
+    source(ctx: RequestContext, id: string | null | undefined): Promise<ResolvedSource>;
+    readonly gates: {
+        /**
+         * A reader asking past what they may read — a table their catalog does
+         * not hold, or (with `body`) a POST read naming one. True when it was
+         * answered; otherwise a GET is refused as a table that does not exist,
+         * and a POST goes on to be refused by the route that reads it.
+         */
+        read?(ctx: RequestContext, source: ResolvedSource, asked: {
+            path: string;
+            body?: Record<string, unknown>;
+        }): boolean;
+        readonly write: RecordHooks['gates']['write'];
+    };
+    readonly after?: RecordHooks['after'];
+    readonly rules?: RecordHooks['rules'];
+    /** The adapter a POST's reads go through (an App's search-aware reader), into `reply`. */
+    reads?(ctx: RequestContext, source: ResolvedSource, adapter: Adapter, reply: ServerResponse): Adapter;
+    /** What a POST is told beside its body: "now" in the App's zone, who `me` is, whose notices it reads. */
+    extras?(ctx: RequestContext, source: ResolvedSource, reads: Adapter): PostExtras;
+    /** A POST the App's pages answer before any route (a free-form page's loaders, its manifest). True when answered. */
+    page?(ctx: RequestContext, source: ResolvedSource, body: Record<string, unknown>): Promise<boolean>;
+    /** The POST routes before the data routes. True when answered. */
+    routes(post: PostContext): Promise<boolean>;
+    /** The POST routes after them. True when answered. */
+    later(post: PostContext): Promise<boolean>;
+    /**
+     * What an App's reads are (app/appReads.ts): its unions, its replies
+     * without the compiler's output, its failures in its own words, its `me`.
+     * Given by the App framework's dispatcher; a request on an App is refused
+     * rather than read as the database browser's without it.
+     */
+    readonly appReads?: AppReads;
+    /** The ISO weekday the reads' weeks start on, where the product says. */
+    weekStart?(post: PostContext): number;
+    readonly exports: ExportHooks;
+    readonly pages: PageHooks;
+    readonly compose: ComposeHooks;
+    readonly read: ReadHooks;
+}
+/**
+ * A POST to the API: the body is read once, the connection or App it names
+ * is resolved from it, and the routes that take a body (`handlePost`) are
+ * given both, as a PostContext built here.
+ *
+ * Split out because the connection is resolved from the body, which means the
+ * body has to be read before dispatch — and a stream can only be read once.
+ * Handlers get it already parsed rather than each reaching for the request.
+ */
+export declare function postData(ctx: RequestContext, hooks: DataHooks): Promise<void>;
+/** A read of the API, on the source its query names. */
+export declare function getData(ctx: RequestContext, hooks: DataHooks): Promise<void>;
+export {};

package/dist/server/http/dataRoutes.js

@@ -0,0 +1,137 @@
+import { lagTolerantReads, primaryReads } from '../../adapters/replicas.js';
+import { AppAccessDenied } from '../columnGrants.js';
+import { dispatchResourceReadHttp } from '../resourceReadHttp.js';
+import { UNEXPORTED_MOST } from '../../shared/reads.js';
+import { clockNow } from './clock.js';
+import { sourceSelector } from './connectionSource.js';
+import { exportRoute } from './exportRoute.js';
+import { pageRoutes } from './pageRoutes.js';
+import { readRoutes } from './readRoutes.js';
+import { toleratesLag } from './readRouting.js';
+import { COMPOSE_PATH, composeRecordPage } from './recordCompose.js';
+import { recordWriteRoutes } from './recordWrites.js';
+import { FILE_UPLOAD_BODY, FILE_UPLOAD_PATH, httpRead, readJson, send } from './reply.js';
+/**
+ * A POST to the API: the body is read once, the connection or App it names
+ * is resolved from it, and the routes that take a body (`handlePost`) are
+ * given both, as a PostContext built here.
+ *
+ * Split out because the connection is resolved from the body, which means the
+ * body has to be read before dispatch — and a stream can only be read once.
+ * Handlers get it already parsed rather than each reaching for the request.
+ */
+export async function postData(ctx, hooks) {
+    const { res, url, path, identity, appHosts, registry } = ctx;
+    const selector = sourceSelector(ctx);
+    // POST bodies can name a connection too, and the body is read once and
+    // reused by the handler below.
+    const body = await readJson(ctx.req, path === FILE_UPLOAD_PATH ? FILE_UPLOAD_BODY : undefined);
+    if (ctx.appConfigured && Object.hasOwn(body, 'conn'))
+        return send(res, 400, { error: 'Application requests identify an app, not a connection.' });
+    if (body[selector] !== undefined && typeof body[selector] !== 'string')
+        return send(res, 400, { error: 'Invalid request identity.' });
+    const inBody = typeof body[selector] === 'string' ? body[selector] : undefined;
+    const inQuery = url.searchParams.get(selector);
+    /* Both, and disagreeing, is refused rather than resolved by precedence.
+     Either answer runs somebody's statement against a database they did not
+     mean, and the request has already told us it is confused about which. */
+    if (inBody && inQuery && inBody !== inQuery) {
+        return send(res, 400, {
+            error: ctx.appConfigured
+                ? 'This request names two different applications.'
+                : `This request names two connections: "${inQuery}" in the URL and "${inBody}" in the body.`,
+        });
+    }
+    const source = await hooks.source(ctx, inBody ?? inQuery);
+    if (res.destroyed)
+        return;
+    const { adapter, schema, resources, access, wholeRowWrites, connectionId } = source;
+    if (hooks.gates.read?.(ctx, source, { path, body }))
+        return;
+    const appConfigured = Boolean(appHosts?.length);
+    /* One POST on this source, into the reply it is given: this request's
+     own, or a composed read's part (recordCompose.ts), which is the same
+     route with the same grants, row scope and hidden columns. */
+    const post = async (reply, asked, given) => {
+        if (access && typeof given.table === 'string' && !access.readable.has(given.table))
+            throw new AppAccessDenied();
+        const reads = hooks.reads?.(ctx, source, adapter, reply) ?? adapter;
+        return handlePost({
+            res: reply,
+            path: asked,
+            body: given,
+            adapter: reads,
+            schema,
+            registry,
+            connection: connectionId,
+            configPages: ctx.configPages,
+            appHosts,
+            who: identity.who,
+            role: identity.role,
+            resources,
+            access,
+            principal: identity.id,
+            wholeRowWrites,
+            rowPolicy: Boolean(ctx.policyContext),
+            appConfigured,
+            appNow: clockNow,
+            ...hooks.extras?.(ctx, source, reads),
+        }, hooks);
+    };
+    /* A record page, pinned to the primary whole: its related lists are
+       asked through the list routes, and a record is where a person looks
+       for what they just saved (readRouting.ts). */
+    if (path === COMPOSE_PATH)
+        return primaryReads(() => composeRecordPage({ ctx, source, body, post, hooks: hooks.compose }));
+    if (await hooks.page?.(ctx, source, body))
+        return;
+    return post(res, path, body);
+}
+/** Everything that takes a body, on its source. */
+async function handlePost(post, hooks) {
+    const { res, path, body, adapter: reads, schema, appConfigured, appNow, me } = post;
+    if (await hooks.routes(post))
+        return;
+    if (await pageRoutes(post, hooks.pages))
+        return;
+    /* A list, a count, a breakdown or an export may be answered by a replica
+       (readRouting.ts); every other route reads the primary. */
+    const reading = (work) => (toleratesLag(path, body) ? lagTolerantReads(work) : work());
+    if (await reading(() => exportRoute(post, hooks.exports)))
+        return;
+    const exportable = hooks.exports.may(post);
+    const weekStart = hooks.weekStart?.(post);
+    /* Read as the browser's, an App's reply would carry its SQL and its compiled columns. */
+    if (appConfigured && !hooks.appReads)
+        throw new Error('An App is read through its own reads (DataHooks.appReads).');
+    const readReply = await httpRead(() => reading(() => dispatchResourceReadHttp(path, body, reads, schema, {
+        app: appConfigured ? hooks.appReads : undefined,
+        now: appNow,
+        ...(me ? { me } : {}),
+        ...(weekStart === undefined ? {} : { weekStart }),
+        // A table this person may not export is read a screen's worth at a time, never a file's.
+        rowsMost: (table) => (exportable(table) ? undefined : UNEXPORTED_MOST),
+    })));
+    if (readReply)
+        return send(res, readReply.status, readReply.body);
+    if (await recordWriteRoutes(post, hooks))
+        return;
+    if (await hooks.later(post))
+        return;
+    return send(res, 404, { error: `No such endpoint: ${path}` });
+}
+/** A read of the API, on the source its query names. */
+export async function getData(ctx, hooks) {
+    const source = await hooks.source(ctx, ctx.url.searchParams.get(sourceSelector(ctx)));
+    if (ctx.res.destroyed)
+        return;
+    const table = ctx.url.searchParams.get('table');
+    if (source.access && table !== null && !source.access.readable.has(table)) {
+        if (hooks.gates.read?.(ctx, source, { path: ctx.path }))
+            return;
+        throw new AppAccessDenied();
+    }
+    if (await readRoutes(ctx, source, hooks.read))
+        return;
+    send(ctx.res, 404, { error: `No such endpoint: ${ctx.path}` });
+}