@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/observability/curl-logger.js

@@ -0,0 +1,175 @@
+/**
+ * `curlLogger(options)`: log each request as a `curl` command, redacted, once its answer is known.
+ * The line goes to the app's logger (`ctx.log.info`, so it carries the request's bindings and obeys
+ * `app.logger(false)` and the level) unless `log` takes it. It is the one opt-in exception to "no
+ * request detail in a log line" (H17): header values a credential, cookie or session would be in are
+ * masked (`isSensitiveHeader`, the request log's own definition), token-like query parameters too,
+ * and the body appears only with `body`, bounded and of a text type.
+ *
+ * The body is read from a `clone()` taken before the handler runs, so the handler still reads it
+ * whole. `skip` runs before any formatting. A failing hook or sink is logged as "curlLogger failed"
+ * and never turns the answer into a 500; nothing it starts can reject unobserved.
+ */
+import { HoneyError } from "../errors/error.js";
+import { namedMiddleware } from "../middleware/middleware.js";
+import { isSensitiveHeader } from "../telemetry/fields.js";
+import { shellQuote } from "./request-to-curl.js";
+const DEFAULT_BODY_TYPES = /* @__PURE__ */ Object.freeze([
+    "application/json",
+    "application/x-www-form-urlencoded",
+    "application/xml",
+    "text/",
+]);
+const DEFAULT_MAX_BODY_BYTES = 16_384;
+const REDACTED = "[REDACTED]";
+const SENSITIVE_PARAM = /(?:^|[_.-])(?:access_?token|refresh_?token|id_?token|token|secret|client_?secret|password|passwd|pwd|api_?key|apikey|key|sig|signature|auth|code|session|jwt)$/i;
+/** The request log's own sensitive headers, masked. */
+export function defaultRedactHeader(name, value) {
+    return isSensitiveHeader(name) ? REDACTED : value;
+}
+/** Token-, key-, secret- and password-like query parameters, masked. */
+export function defaultRedactQueryParam(name, value) {
+    return SENSITIVE_PARAM.test(name) ? REDACTED : value;
+}
+function essenceOf(contentType) {
+    const semi = contentType.indexOf(";");
+    return (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase();
+}
+function typeAllowed(contentType, allowed) {
+    if (contentType === null)
+        return false;
+    const essence = essenceOf(contentType);
+    /* the top-level type alone, for a family entry such as `text/` */
+    const family = essence.slice(0, essence.indexOf("/") + 1);
+    return allowed.some((type) => (type.endsWith("/") ? family : essence) === type.toLowerCase());
+}
+function redactUrl(raw, redact) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        /* the answer, not a failure: a URL that does not parse (a malformed Host on Node) is logged without its query */
+        return raw.split("?")[0];
+    }
+    if (url.search === "")
+        return url.href;
+    const params = new URLSearchParams();
+    for (const [name, value] of url.searchParams) {
+        const kept = redact(name, value);
+        if (kept !== null)
+            params.append(name, kept);
+    }
+    url.search = params.toString();
+    return url.href;
+}
+const omitted = (omittedReason) => ({ body: null, omittedReason });
+/** Read at most `maxBytes` of `stream`; never rejects. */
+async function drain(stream, maxBytes) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                reader.cancel().catch(() => {
+                    /* the log copy only: the request's own body is untouched, and the body is omitted below */
+                });
+                return omitted("too-large");
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        /* the answer, not a failure: a body that cannot be read is logged as omitted */
+        return omitted("read-error");
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { body: new TextDecoder().decode(bytes), omittedReason: null };
+}
+/** Start reading the body to log now, from a clone taken before any handler reads the request. */
+function startBodyRead(request, option) {
+    if (option !== true && (typeof option !== "object" || option === null))
+        return Promise.resolve(omitted("disabled"));
+    const { allowContentTypes = DEFAULT_BODY_TYPES, maxBytes = DEFAULT_MAX_BODY_BYTES } = option === true ? {} : option;
+    if (request.body === null)
+        return Promise.resolve(omitted("missing"));
+    if (!typeAllowed(request.headers.get("content-type"), allowContentTypes))
+        return Promise.resolve(omitted("content-type"));
+    const declared = Number.parseInt(request.headers.get("content-length") ?? "", 10);
+    if (declared > maxBytes)
+        return Promise.resolve(omitted("too-large"));
+    return drain(request.clone().body, maxBytes);
+}
+function formatCurl(request, body, redact) {
+    const parts = ["curl", "-X", shellQuote(request.method)];
+    for (const [name, value] of request.headers) {
+        const shown = redact.redactHeader(name, value);
+        if (shown !== null)
+            parts.push("-H", shellQuote(`${name}: ${shown}`));
+    }
+    if (body.body !== null)
+        parts.push("--data-raw", shellQuote(body.body));
+    parts.push(shellQuote(redactUrl(request.url, redact.redactQueryParam)));
+    return parts.join(" ");
+}
+function redactorsOf(options) {
+    return {
+        redactHeader: options.redactHeader ?? defaultRedactHeader,
+        redactQueryParam: options.redactQueryParam ?? defaultRedactQueryParam,
+    };
+}
+/** The command and the body's fate for one request, outside the middleware. */
+export async function buildCurlLogData(request, options = {}) {
+    const body = await startBodyRead(request, options.body);
+    return {
+        bodyIncluded: body.body !== null,
+        bodyOmittedReason: body.omittedReason,
+        curl: formatCurl(request, body, redactorsOf(options)),
+    };
+}
+export function curlLogger(options = {}) {
+    const redact = redactorsOf(options);
+    return namedMiddleware("curlLogger", async (ctx, next) => {
+        const started = performance.now();
+        const request = ctx.req;
+        /* the only work before next(): the clone must be taken before a handler reads the body */
+        const body = startBodyRead(request, options.body);
+        const response = await next();
+        const seen = {
+            duration: performance.now() - started,
+            method: request.method,
+            path: ctx.path,
+            requestId: ctx.requestId ?? null,
+            status: response.status,
+        };
+        try {
+            if (options.skip?.(seen))
+                return response;
+            const read = await body;
+            const data = {
+                ...seen,
+                bodyIncluded: read.body !== null,
+                bodyOmittedReason: read.omittedReason,
+                curl: formatCurl(request, read, redact),
+            };
+            if (options.log)
+                options.log(data);
+            else
+                ctx.log.info({ ...data }, "request curl");
+        }
+        catch (failure) {
+            ctx.log.error({ err: HoneyError.serialize(failure) }, "curlLogger failed");
+        }
+        return response;
+    });
+}

package/dist/observability/request-to-curl.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `requestToCurl(request)`: the request as a `curl` command that reproduces it, for a developer to
+ * paste. Faithful by default: no header is redacted, since a redacted command cannot reproduce the
+ * request; `excludeHeader` leaves out what the caller names, and `curlLogger` is the redacting path
+ * for logs. The request is cloned, so its body stays readable.
+ */
+export type RequestToCurlOptions = {
+    /** Leave a header out of the command. */
+    excludeHeader?: (name: string, value: string) => boolean;
+};
+/**
+ * One shell word. Plain values use single quotes; a value with a control character (CR, LF, ESC…)
+ * uses ANSI-C `$'…'` quoting with `\xHH` escapes, so a pasted command cannot carry a raw newline
+ * and a log line cannot be split.
+ */
+export declare function shellQuote(value: string): string;
+export declare function requestToCurl(request: Request, options?: RequestToCurlOptions): Promise<string>;

package/dist/observability/request-to-curl.js

@@ -0,0 +1,47 @@
+/**
+ * `requestToCurl(request)`: the request as a `curl` command that reproduces it, for a developer to
+ * paste. Faithful by default: no header is redacted, since a redacted command cannot reproduce the
+ * request; `excludeHeader` leaves out what the caller names, and `curlLogger` is the redacting path
+ * for logs. The request is cloned, so its body stays readable.
+ */
+function hasControl(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * One shell word. Plain values use single quotes; a value with a control character (CR, LF, ESC…)
+ * uses ANSI-C `$'…'` quoting with `\xHH` escapes, so a pasted command cannot carry a raw newline
+ * and a log line cannot be split.
+ */
+export function shellQuote(value) {
+    if (!hasControl(value))
+        return `'${value.replaceAll("'", "'\\''")}'`;
+    let out = "$'";
+    for (const ch of value) {
+        const code = ch.codePointAt(0);
+        if (ch === "\\" || ch === "'")
+            out += `\\${ch}`;
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\x${code.toString(16).padStart(2, "0")}`;
+        else
+            out += ch;
+    }
+    return `${out}'`;
+}
+export async function requestToCurl(request, options = {}) {
+    const copy = request.clone();
+    const parts = ["curl", "-X", shellQuote(copy.method)];
+    for (const [name, value] of copy.headers) {
+        if (options.excludeHeader?.(name, value) !== true)
+            parts.push("-H", shellQuote(`${name}: ${value}`));
+    }
+    const body = await copy.text();
+    if (body.length > 0)
+        parts.push("--data-raw", shellQuote(body));
+    parts.push(shellQuote(copy.url));
+    return parts.join(" ");
+}

package/dist/openapi/collect.d.ts

@@ -1,20 +1,58 @@
-import type { RouteHandler, WSRouteHandler } from "../tree.ts";
-import type { InputSchemaEntry, StandardSchemaLike } from "../types.ts";
-export type CollectedRoute = {
-    handler: RouteHandler;
-    method: string;
-    path: string;
+/**
+ * The routes an app serves, as records a document is built from: one per concrete path, read
+ * from the finalized table so meta and error keys are what dispatch resolves. WebSocket routes
+ * come apart: they are no operations.
+ */
+import { type ErrorMetaEntry } from "../errors/errors.ts";
+import type { InputSchemas } from "../input/input.ts";
+import { type HoneyGraph } from "../routing/register.ts";
+import { GRAPH } from "../routing/app.ts";
+import type { OutputSchemas } from "../routing/output-types.ts";
+/** One path a WebSocket route serves. */
+export type CollectedWsRoute = {
+    /** `WS /pattern` */
+    readonly id: string;
+    /** the upgrade's non-body sources, as declared */
+    readonly input: InputSchemas | null;
+    readonly meta: Readonly<Record<string, unknown>>;
+    /** parameter names, an unnamed wildcard as `wildcard` */
+    readonly params: readonly string[];
+    /** the OpenAPI path template: `/chat/{room}` */
+    readonly path: string;
+    /** the honey pattern: `/chat/:room` */
+    readonly pattern: string;
 };
-export type CollectedWSRoute = {
-    handler: WSRouteHandler;
-    path: string;
+/** An error key as the document describes it: its status and, for a schema error, its schema. */
+export type CollectedError = {
+    readonly schema: ErrorMetaEntry["schema"];
+    /** the HTTP status; `0` when nothing says */
+    readonly status: number;
+    /** the status key; `"unknown"` when nothing says */
+    readonly statusKey: string;
 };
-/** Path parameter names of a route pattern, as OpenAPI names them (wildcards included). */
-export declare function extractParams(path: string): string[];
-export declare function toOpenApiPath(path: string): string;
-/** Every served HTTP route of an app, one entry per concrete path. */
-export declare function collectRoutes(app: unknown, includeSkipped?: boolean): CollectedRoute[];
-/** Every websocket route of an app, one entry per concrete path. */
-export declare function collectWsRoutes(app: unknown): CollectedWSRoute[];
-export declare function unwrapEntry(entry: InputSchemaEntry): StandardSchemaLike;
-//# sourceMappingURL=collect.d.ts.map
+/** One path an HTTP route serves. */
+export type CollectedRoute = CollectedWsRoute & {
+    /** the keys the route may answer with, sorted; none for a route that declares none */
+    readonly errorKeys: readonly string[];
+    /** each of `errorKeys` with its status: from ERROR_META, never by calling a factory */
+    readonly errorMeta: Readonly<Record<string, CollectedError>>;
+    /** the error factories the route's keys come from: what `ctx.errors` holds */
+    readonly errors: Readonly<Record<string, (...args: never[]) => unknown>> | null;
+    /** `meta.internal`: generated artifacts leave the route out */
+    readonly internal: boolean;
+    /** the registration the route came from: shared by the records one `.on()` call writes */
+    readonly registration: object;
+    /** `GET`, `POST`… or `ALL` */
+    readonly method: string;
+    /** each middleware the route runs, in order, by name; an unnamed one is `anonymous` (F13) */
+    readonly middleware: readonly string[];
+    readonly output: OutputSchemas | null;
+};
+export type CollectedRoutes = {
+    readonly http: CollectedRoute[];
+    readonly ws: CollectedWsRoute[];
+};
+/** Every route `app` serves: in registration order, or a loaded tree's order. */
+export declare function collectRoutes(app: {
+    readonly [GRAPH]: HoneyGraph;
+}): CollectedRoutes;

package/dist/openapi/collect.js

@@ -1,30 +1,116 @@
-import { parsePattern, toOpenApiTemplate, UNNAMED_WILDCARD } from "../pattern.js";
-/** Path parameter names of a route pattern, as OpenAPI names them (wildcards included). */
-export function extractParams(path) {
-    const out = [];
-    for (const seg of parsePattern(path)) {
-        if (seg.k === "param")
-            out.push(seg.n);
-        else if (seg.k === "wildcard")
-            out.push(seg.n === UNNAMED_WILDCARD ? "wildcard" : seg.n);
+/**
+ * The routes an app serves, as records a document is built from: one per concrete path, read
+ * from the finalized table so meta and error keys are what dispatch resolves. WebSocket routes
+ * come apart: they are no operations.
+ */
+import { ERROR_META } from "../errors/errors.js";
+import { statusKeyToCode } from "../response/status.js";
+import { compareCodeUnits } from "../schema/canonicalize.js";
+import { chainErrorFactories } from "../routing/register.js";
+import { GRAPH } from "../routing/app.js";
+import { finalTable } from "../routing/dispatch.js";
+import { expandOptional, parsePattern, patternParams, splitRouteId, toOpenApiTemplate, UNNAMED_WILDCARD, } from "../routing/pattern.js";
+import { assertOutputKeys } from "./output-keys.js";
+/** The error status a key names by itself: a status key, or one as its suffix. */
+function inferred(key) {
+    /* longest first, so `billing_event_not_found` reads as not_found and never found */
+    const byLength = Object.keys(statusKeyToCode).sort((a, b) => b.length - a.length);
+    const statusKey = byLength.find((k) => key === k || key.endsWith(`_${k}`));
+    if (statusKey === undefined || statusKeyToCode[statusKey] < 400)
+        return null;
+    return { schema: null, status: statusKeyToCode[statusKey], statusKey };
+}
+/** What `source` holds for `key`: its factory's ERROR_META entry, or the status key a tree recorded. */
+function lookup(source, key) {
+    if (source === null || source === undefined)
+        return undefined;
+    const meta = source[ERROR_META];
+    if (meta !== undefined)
+        return Object.hasOwn(meta, key) ? meta[key] : undefined;
+    const statusKey = Object.hasOwn(source, key) ? source[key] : undefined;
+    return typeof statusKey === "string" ? { schema: null, statusKey: statusKey } : undefined;
+}
+/**
+ * Each key's status from the first source that knows it (the factory the route named, the ones its
+ * middleware brought, the app it was registered on, a generated tree's record, the app serving it),
+ * else from its name, else unknown.
+ */
+function errorMetaOf(keys, sources) {
+    const out = {};
+    for (const key of keys) {
+        const entry = sources.map((source) => lookup(source, key)).find((found) => found !== undefined);
+        out[key] =
+            entry === undefined
+                ? (inferred(key) ?? { schema: null, status: 0, statusKey: "unknown" })
+                : { schema: entry.schema, status: statusKeyToCode[entry.statusKey], statusKey: entry.statusKey };
     }
     return out;
 }
-export function toOpenApiPath(path) {
-    return toOpenApiTemplate(parsePattern(path));
-}
-/** Every served HTTP route of an app, one entry per concrete path. */
-export function collectRoutes(app, includeSkipped) {
-    return app._collectRoutes(includeSkipped);
+/** What a route resolves to: from its plan, or for a loaded leaf nothing serves, from its tree entry. */
+function resolved(plan, entry) {
+    if (plan !== undefined) {
+        const declared = plan.policy.declared === null ? [] : [...plan.policy.declared];
+        return { errorKeys: declared.sort(compareCodeUnits), errors: plan.route.errors, meta: plan.route.meta };
+    }
+    const meta = entry?.mt ?? {};
+    return { errorKeys: [...(entry?.ek ?? [])].sort(compareCodeUnits), errors: null, meta };
 }
-/** Every websocket route of an app, one entry per concrete path. */
-export function collectWsRoutes(app) {
-    return app._collectWsRoutes();
+/**
+ * A route's pattern and declarations: its record's, else its loaded tree entry's. Its output holds no key the types
+ * refuse (assertOutputKeys): every document, manifest and generated type reads routes from here.
+ */
+function declarations(g, id) {
+    const record = g.records.get(id);
+    const entry = g.loaded?.[id];
+    const output = record?.out ?? entry?.out ?? null;
+    if (output !== null)
+        assertOutputKeys(output, id);
+    return {
+        input: record?.iv ?? entry?.iv ?? null,
+        output,
+        segments: record?.sg ?? parsePattern(splitRouteId(id).pattern),
+    };
 }
-export function unwrapEntry(entry) {
-    if ("_tag" in entry) {
-        return entry.schema;
+/** Every route `app` serves: in registration order, or a loaded tree's order. */
+export function collectRoutes(app) {
+    const g = app[GRAPH];
+    const { plans } = finalTable(g);
+    const http = [];
+    const ws = [];
+    for (const id of g.loaded === null ? g.records.keys() : Object.keys(g.loaded)) {
+        const { input, output, segments } = declarations(g, id);
+        const { errorKeys, errors, meta } = resolved(plans.get(id), g.loaded?.[id]);
+        const record = g.records.get(id);
+        const chain = plans.get(id)?.mw ?? [];
+        const errorMeta = errorMetaOf(errorKeys, [
+            record?.ef,
+            ...chainErrorFactories(chain),
+            record?.own.errorFactory,
+            g.loaded?.[id]?.es,
+            g.settings.errorFactory,
+        ]);
+        const { method, pattern } = splitRouteId(id);
+        for (const variant of expandOptional(segments)) {
+            const params = patternParams(variant).map((name) => (name === UNNAMED_WILDCARD ? "wildcard" : name));
+            const base = { id, input, meta, params, path: toOpenApiTemplate(variant), pattern };
+            if (method === "WS")
+                ws.push(base);
+            else {
+                /* every route is a record or a loaded leaf */
+                const registration = (record?.fn ?? g.loaded?.[id]);
+                http.push({
+                    ...base,
+                    errorKeys,
+                    errorMeta,
+                    errors,
+                    internal: meta.internal === true,
+                    method,
+                    middleware: chain.map((mw) => mw.name || "anonymous"),
+                    output,
+                    registration,
+                });
+            }
+        }
     }
-    return entry;
+    return { http, ws };
 }
-//# sourceMappingURL=collect.js.map

package/dist/openapi/components.d.ts

@@ -0,0 +1,9 @@
+import type { JsonSchema } from "../schema/to-json-schema.ts";
+export type Components = {
+    /** `schema` with its local references lifted; the same object when it has none. */
+    hoist(schema: JsonSchema, hint: string): JsonSchema;
+    /** Every lifted component, in the order it was lifted. */
+    schemas(): Record<string, JsonSchema>;
+};
+/** One document's components; `taken` names component names the caller already holds. */
+export declare function createComponents(taken?: (name: string) => boolean): Components;

package/dist/openapi/components.js

@@ -0,0 +1,90 @@
+/**
+ * A converter's local references, lifted into the document's components. Converters write
+ * `$ref: "#"` for recursion and `#/$defs/<name>` (or `#/definitions/<name>`) for shared nodes,
+ * relative to the schema's own root; in a document `#` is the document, so each is lifted into
+ * `components.schemas` and every reference rewritten to point there.
+ */
+import { sanitizeComponentName } from "../schema/naming.js";
+/** Keys whose values are data, not schemas: a `$ref` inside them is a value, not a reference. */
+const DATA_KEYS = ["const", "default", "enum", "example", "examples"];
+/* where a converter keeps shared nodes, and how a reference into each is spelled */
+const DEF_KEYS = [
+    ["$defs", "#/$defs/"],
+    ["definitions", "#/definitions/"],
+];
+const COMPONENTS = "#/components/schemas/";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Whether `node` holds `$ref: target` anywhere a schema can sit. */
+function refersTo(node, target) {
+    if (Array.isArray(node))
+        return node.some((item) => refersTo(item, target));
+    if (!isRecord(node))
+        return false;
+    return Object.entries(node).some(([key, value]) => key === "$ref" && typeof value === "string"
+        ? value === target
+        : !DATA_KEYS.includes(key) && refersTo(value, target));
+}
+/** `node` with each `$ref` that `rewrite` maps replaced; data keywords copied as they are. */
+function rewriteRefs(node, rewrite) {
+    if (Array.isArray(node))
+        return node.map((item) => rewriteRefs(item, rewrite));
+    if (!isRecord(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "$ref" && typeof value === "string")
+            out[key] = rewrite(value) ?? value;
+        else
+            out[key] = DATA_KEYS.includes(key) ? value : rewriteRefs(value, rewrite);
+    }
+    return out;
+}
+/** A JSON Pointer token, unescaped: `~1` is `/`, `~0` is `~`. */
+const decodePointer = (token) => token.replaceAll("~1", "/").replaceAll("~0", "~");
+/** One document's components; `taken` names component names the caller already holds. */
+export function createComponents(taken = () => false) {
+    const lifted = Object.create(null);
+    const reserve = (base) => {
+        const clean = sanitizeComponentName(base) || "Schema";
+        let name = clean;
+        for (let n = 2; taken(name) || Object.hasOwn(lifted, name); n++)
+            name = `${clean}${n}`;
+        lifted[name] = {};
+        return name;
+    };
+    const hoist = (schema, hint) => {
+        const defs = DEF_KEYS.flatMap(([key, prefix]) => Object.entries(isRecord(schema[key]) ? schema[key] : {}).map(([name, def]) => ({
+            def,
+            name,
+            prefix,
+        })));
+        const selfRef = refersTo(schema, "#");
+        if (defs.length === 0 && !selfRef)
+            return schema;
+        const rootName = selfRef ? reserve(hint) : null;
+        /* each def's component name, by the reference that reaches it */
+        const names = new Map();
+        for (const { name, prefix } of defs) {
+            names.set(`${prefix}${name}`, reserve(name.startsWith("__schema") ? `${hint}${name.slice(8)}` : name));
+        }
+        const rewrite = (ref) => {
+            /* a `#` reference is what reserved the root's name */
+            if (ref === "#")
+                return `${COMPONENTS}${rootName}`;
+            const prefix = DEF_KEYS.find(([, p]) => ref.startsWith(p))?.[1];
+            const name = prefix === undefined ? undefined : names.get(`${prefix}${decodePointer(ref.slice(prefix.length))}`);
+            return name === undefined ? null : `${COMPONENTS}${name}`;
+        };
+        for (const { def, name, prefix } of defs)
+            lifted[names.get(`${prefix}${name}`)] = rewriteRefs(def, rewrite);
+        const { $defs: _defs, definitions: _definitions, ...rest } = schema;
+        const root = rewriteRefs(rest, rewrite);
+        if (rootName === null)
+            return root;
+        lifted[rootName] = root;
+        return { $ref: `${COMPONENTS}${rootName}` };
+    };
+    return { hoist, schemas: () => ({ ...lifted }) };
+}

package/dist/openapi/docs-page.d.ts

@@ -1,9 +1,11 @@
-import type { TypedResponse } from "../response.ts";
 /**
- * Pinned docs UI assets with Subresource Integrity. The page runs on the API's own origin, so
- * an unpinned CDN script could read anything the origin can; a pinned version with an
- * integrity hash can only ever be these bytes.
+ * The docs page shell: pinned UI assets with Subresource Integrity, JSON safe to inline in a
+ * script, and a handler that answers each request with a fresh script nonce under a CSP that
+ * runs only that inline script and the pinned CDN. The page runs on the API's own origin, so an
+ * unpinned script could read anything the origin can; a pinned one with an integrity hash can only
+ * ever be these bytes.
  */
+import type { TypedResponse } from "../response/response.ts";
 export declare const SWAGGER_UI: {
     readonly css: {
         readonly integrity: "sha384-Ov4/wv3j2bmct8cDc5X4ngJZohVPzEmc6uDPH8WeljUxO5vtoykvMEfbu9Vh6RaW";
@@ -20,23 +22,23 @@ export declare const SCALAR: {
         readonly url: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.73.1/dist/browser/standalone.js";
     };
 };
-/**
- * JSON for an inline `<script>`: `<` cannot end the element, and U+2028/U+2029 cannot end a
- * string literal in older engines.
- */
-export declare function inlineJson(value: unknown): string;
-export declare function escapeAttribute(value: string): string;
-type DocsCtx = {
-    res: {
-        html(sk: "ok", body: string, opts?: {
+/** What a docs page reads of its context: the HTML answer. */
+export type DocsContext = {
+    readonly res: {
+        html(statusKey: "ok", body: string, options?: {
             headers?: Record<string, string>;
         }): TypedResponse;
     };
 };
+/** A docs page config: the document URL, and the rest of the UI's own options. */
+export type DocsConfig = {
+    readonly url: string;
+    readonly [key: string]: unknown;
+};
 /**
- * A docs page handler: a fresh script nonce per response, a CSP that allows only that inline
- * script and the pinned CDN, and `nosniff`.
+ * JSON for an inline `<script>`: `<`, `>` and `&` cannot end the element or start an entity, and
+ * U+2028/U+2029 cannot end a string literal in older engines.
  */
-export declare function docsPage(render: (nonce: string) => string): (ctx: DocsCtx) => TypedResponse;
-export {};
-//# sourceMappingURL=docs-page.d.ts.map
+export declare function inlineJson(value: unknown): string;
+/** A docs page handler: `render` writes the page around a nonce minted for each answer. */
+export declare function docsPage(render: (nonce: string) => string): (ctx: DocsContext) => TypedResponse;