@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/context/peer.js

@@ -0,0 +1,190 @@
+/**
+ * `ctx.ip`: the peer the platform reports, in one canonical spelling (H23). There is no proxy
+ * trust: the address is the connection's other end as the runtime sees it.
+ *
+ * - Cloudflare Workers: `CF-Connecting-IP`, which the edge sets and a client cannot override. It
+ *   is read only when running on Workers; anywhere else it is client-sent text.
+ * - Bun: `server.requestIP(req)`, from the server Bun passes as fetch's env (or `env.server`).
+ * - Node: the socket's `remoteAddress`, which the Node adapter's request reports under
+ *   `PEER_ADDRESS`.
+ *
+ * Behind a self-hosted reverse proxy that is the proxy's address.
+ */
+/** A request that knows its peer reports it under this key, allocation-free (the Node adapter's request). */
+export const PEER_ADDRESS = /* @__PURE__ */ Symbol.for("honey.peerAddress");
+/** Workers is the one runtime whose edge reports the peer in a header a client cannot send. */
+function onWorkers() {
+    return globalThis.navigator?.userAgent === "Cloudflare-Workers";
+}
+/** The peer address as the runtime reports it, unparsed, or `null` when nothing reports one. */
+export function peerAddressOf(req, env) {
+    const own = req[PEER_ADDRESS];
+    if (typeof own === "string")
+        return own === "" ? null : own;
+    if (env !== null && typeof env === "object") {
+        const e = env;
+        const server = typeof e.requestIP === "function" ? e : e.server;
+        if (typeof server?.requestIP === "function") {
+            try {
+                return server.requestIP(req)?.address ?? null;
+            }
+            catch {
+                /* a request Bun did not see (a test or a shim): there is no peer, which is the answer */
+                return null;
+            }
+        }
+    }
+    return onWorkers() ? req.headers.get("cf-connecting-ip") : null;
+}
+/** The request's canonical peer, read on first ask and kept on its state. */
+export function ipOf(source) {
+    if (source.ip === undefined) {
+        const peer = peerAddressOf(source.req, source.env);
+        source.ip = peer === null ? null : canonicalIp(peer);
+    }
+    return source.ip;
+}
+const V4_MAPPED_PREFIX = 0xffffn << 32n;
+const V4_MAPPED_MASK = ~0xffffffffn & ((1n << 128n) - 1n);
+const DIGITS = /^\d+$/;
+const HEX_GROUP = /^[0-9A-Fa-f]{1,4}$/;
+const PORT = /^\d{1,5}$/;
+const BRACKET_TAIL = /^:\d{1,5}$/;
+/** Dotted IPv4, strict: four decimal octets, no leading zero; `null` otherwise. */
+export function parseIpv4(s) {
+    const parts = s.split(".");
+    if (parts.length !== 4)
+        return null;
+    let n = 0;
+    for (const part of parts) {
+        /* digits only and no leading zero: `010` is octal to some parsers and decimal to others */
+        if (part.length === 0 || part.length > 3 || !DIGITS.test(part))
+            return null;
+        if (part.length > 1 && part.charCodeAt(0) === 48)
+            return null;
+        const octet = Number(part);
+        if (octet > 255)
+            return null;
+        n = n * 256 + octet;
+    }
+    return n;
+}
+/** The `:`-separated groups of one side of `::`, as numbers; `null` when one is not 1–4 hex digits. */
+function groupsOf(side) {
+    if (side === "")
+        return [];
+    const groups = [];
+    for (const group of side.split(":")) {
+        if (!HEX_GROUP.test(group))
+            return null;
+        groups.push(Number.parseInt(group, 16));
+    }
+    return groups;
+}
+/** IPv6 text (an embedded IPv4 tail allowed) as its 128-bit value; no brackets, zone or port; `null` otherwise. */
+export function parseIpv6(s) {
+    let head = s;
+    const tail = [];
+    const lastColon = s.lastIndexOf(":");
+    if (s.includes(".", lastColon)) {
+        /* an embedded IPv4 address fills the last two groups */
+        const v4 = parseIpv4(s.slice(lastColon + 1));
+        if (v4 === null)
+            return null;
+        tail.push(Math.floor(v4 / 65536), v4 % 65536);
+        head = s.slice(0, lastColon + 1);
+        /* "a:1.2.3.4" leaves "a:", whose trailing colon is a separator; "a::1.2.3.4" leaves "a::" */
+        if (!head.endsWith("::"))
+            head = head.slice(0, -1);
+    }
+    const halves = head.split("::");
+    if (halves.length > 2)
+        return null;
+    const left = groupsOf(halves[0]);
+    if (left === null)
+        return null;
+    let groups = [...left, ...tail];
+    if (halves.length === 2) {
+        const right = groupsOf(halves[1]);
+        if (right === null)
+            return null;
+        const fill = 8 - left.length - right.length - tail.length;
+        /* `::` stands for at least one zero group */
+        if (fill < 1)
+            return null;
+        groups = [...left, ...Array.from({ length: fill }, () => 0), ...right, ...tail];
+    }
+    if (groups.length !== 8)
+        return null;
+    let n = 0n;
+    for (const group of groups)
+        n = (n << 16n) | BigInt(group);
+    return n;
+}
+/** Strip what a runtime or header wraps an address in: brackets with a port, an IPv4 port, an IPv6 zone. */
+function unwrap(input) {
+    let s = input.trim();
+    if (s.startsWith("[")) {
+        const close = s.indexOf("]");
+        if (close === -1)
+            return null;
+        const after = s.slice(close + 1);
+        if (after !== "" && !BRACKET_TAIL.test(after))
+            return null;
+        s = s.slice(1, close);
+    }
+    else {
+        const colon = s.indexOf(":");
+        /* one colon and a dot can only be IPv4 with a port */
+        if (colon !== -1 && colon === s.lastIndexOf(":") && s.includes(".")) {
+            if (!PORT.test(s.slice(colon + 1)))
+                return null;
+            s = s.slice(0, colon);
+        }
+    }
+    const zone = s.indexOf("%");
+    if (zone === -1)
+        return s;
+    return s.includes(":") ? s.slice(0, zone) : null;
+}
+function formatV4(n) {
+    return `${Math.floor(n / 16777216)}.${Math.floor(n / 65536) % 256}.${Math.floor(n / 256) % 256}.${n % 256}`;
+}
+/** RFC 5952: lowercase hex, the longest run of two or more zero groups compressed to `::`. */
+function formatV6(n) {
+    const groups = [];
+    for (let i = 7; i >= 0; i--)
+        groups.push(Number((n >> BigInt(i * 16)) & 0xffffn));
+    let start = -1;
+    let length = 1;
+    for (let i = 0; i < 8;) {
+        let j = i;
+        while (j < 8 && groups[j] === 0)
+            j++;
+        if (j - i > length)
+            [start, length] = [i, j - i];
+        i = j === i ? i + 1 : j;
+    }
+    const text = groups.map((group) => group.toString(16));
+    if (start === -1)
+        return text.join(":");
+    return `${text.slice(0, start).join(":")}::${text.slice(start + length).join(":")}`;
+}
+/**
+ * One spelling per address, so the same client reads the same on every runtime: dotted IPv4 (an
+ * IPv4-mapped IPv6 address and an IPv4 address with a port included) or RFC 5952 IPv6. `null`
+ * for anything that is not exactly one address.
+ */
+export function canonicalIp(input) {
+    const s = unwrap(input);
+    if (s === null)
+        return null;
+    if (!s.includes(":")) {
+        const v4 = parseIpv4(s);
+        return v4 === null ? null : formatV4(v4);
+    }
+    const n = parseIpv6(s);
+    if (n === null)
+        return null;
+    return (n & V4_MAPPED_MASK) === V4_MAPPED_PREFIX ? formatV4(Number(n & 0xffffffffn)) : formatV6(n);
+}

package/dist/errors/error.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `HoneyError`: the one error shape honey answers with. It names its error key and status by the
+ * snake_case vocabulary, carries per-field errors, and keeps what the operator log needs (cause,
+ * vars) apart from what the client sees.
+ */
+import { type StatusKey } from "../response/status.ts";
+/** One problem with one input field: what the client reads under `fields`. */
+export type FieldError = {
+    error_key: string;
+    message: string;
+    path: string;
+};
+/** The error keys the framework throws on its own behalf. */
+export declare const EK: Readonly<{
+    readonly bad_gateway: "bad_gateway";
+    readonly bad_request: "bad_request";
+    readonly content_too_large: "content_too_large";
+    readonly forbidden: "forbidden";
+    readonly gateway_timeout: "gateway_timeout";
+    readonly internal_server_error: "internal_server_error";
+    /** a request body the declared parser cannot read (bad JSON, broken multipart): 400 */
+    readonly malformed_body: "malformed_body";
+    readonly method_not_allowed: "method_not_allowed";
+    readonly not_found: "not_found";
+    readonly output_content_type_mismatch: "output_content_type_mismatch";
+    readonly output_validation_failed: "output_validation_failed";
+    readonly request_timeout: "request_timeout";
+    readonly too_many_requests: "too_many_requests";
+    readonly unsupported_media_type: "unsupported_media_type";
+    readonly validation_failed: "validation_failed";
+}>;
+/**
+ * A key the framework owns (validation, negotiation, routing, the shipped middleware): it always
+ * passes a route's declared-error check, since users never declare it via `.errors()`. A plain
+ * `internal_server_error` is not one: an undeclared throw of it still goes through the boundary.
+ */
+export declare function isFrameworkErrorKey(key: string): boolean;
+export type HoneyErrorOptions = {
+    cause?: unknown;
+    data?: unknown;
+    errorKey: string;
+    fields?: Record<string, FieldError[]>;
+    headers?: Record<string, string>;
+    status: StatusKey;
+    vars?: Record<string, number | string>;
+};
+/** Whether `error` was built with a status key that names no status. */
+export declare function hasUnknownStatus(error: HoneyError): boolean;
+export declare class HoneyError extends Error {
+    readonly data?: unknown;
+    readonly errorKey: string;
+    readonly fields: Readonly<Record<string, FieldError[]>>;
+    readonly headers?: Record<string, string>;
+    readonly status: number;
+    readonly statusKey: StatusKey;
+    readonly vars?: Record<string, number | string>;
+    constructor(options: HoneyErrorOptions);
+    /** A thrown value as a plain object for the operator log: message, name, stack, the error's keys and its cause chain. */
+    static serialize(error: unknown): Record<string, unknown>;
+}

package/dist/errors/error.js

@@ -0,0 +1,84 @@
+/**
+ * `HoneyError`: the one error shape honey answers with. It names its error key and status by the
+ * snake_case vocabulary, carries per-field errors, and keeps what the operator log needs (cause,
+ * vars) apart from what the client sees.
+ */
+import { statusKeyToCode } from "../response/status.js";
+const EMPTY_FIELDS = /* @__PURE__ */ Object.freeze(
+/* @__PURE__ */ Object.create(null));
+/** The error keys the framework throws on its own behalf. */
+export const EK = /* @__PURE__ */ Object.freeze({
+    bad_gateway: "bad_gateway",
+    bad_request: "bad_request",
+    content_too_large: "content_too_large",
+    forbidden: "forbidden",
+    gateway_timeout: "gateway_timeout",
+    internal_server_error: "internal_server_error",
+    /** a request body the declared parser cannot read (bad JSON, broken multipart): 400 */
+    malformed_body: "malformed_body",
+    method_not_allowed: "method_not_allowed",
+    not_found: "not_found",
+    output_content_type_mismatch: "output_content_type_mismatch",
+    output_validation_failed: "output_validation_failed",
+    request_timeout: "request_timeout",
+    too_many_requests: "too_many_requests",
+    unsupported_media_type: "unsupported_media_type",
+    validation_failed: "validation_failed",
+});
+/**
+ * A key the framework owns (validation, negotiation, routing, the shipped middleware): it always
+ * passes a route's declared-error check, since users never declare it via `.errors()`. A plain
+ * `internal_server_error` is not one: an undeclared throw of it still goes through the boundary.
+ */
+export function isFrameworkErrorKey(key) {
+    return key !== EK.internal_server_error && Object.hasOwn(EK, key);
+}
+/** Marks an error built with a status key that names no status: not representable to a client (H18.17). */
+const UNKNOWN_STATUS = /* @__PURE__ */ Symbol("honey.unknownStatus");
+/** Whether `error` was built with a status key that names no status. */
+export function hasUnknownStatus(error) {
+    return Object.hasOwn(error, UNKNOWN_STATUS);
+}
+export class HoneyError extends Error {
+    data;
+    errorKey;
+    fields;
+    headers;
+    status;
+    statusKey;
+    vars;
+    constructor(options) {
+        /* no cause given: no own `cause` property, as with a plain Error */
+        super(options.errorKey, options.cause === undefined ? undefined : { cause: options.cause });
+        this.data = options.data;
+        this.errorKey = options.errorKey;
+        this.headers = options.headers;
+        /* an unknown status key must not turn an error into a 200: it is a 500 */
+        const known = Object.hasOwn(statusKeyToCode, options.status);
+        this.statusKey = known ? options.status : "internal_server_error";
+        this.status = known ? statusKeyToCode[options.status] : 500;
+        if (!known)
+            Object.defineProperty(this, UNKNOWN_STATUS, { value: true });
+        this.fields = options.fields ?? EMPTY_FIELDS;
+        this.vars = options.vars;
+    }
+    /** A thrown value as a plain object for the operator log: message, name, stack, the error's keys and its cause chain. */
+    static serialize(error) {
+        if (!(error instanceof Error))
+            return { message: String(error) };
+        const out = { message: error.message, name: error.name, stack: error.stack };
+        if (error instanceof HoneyError) {
+            out.errorKey = error.errorKey;
+            out.status = error.status;
+            out.statusKey = error.statusKey;
+            if (Object.keys(error.fields).length > 0)
+                out.fields = error.fields;
+            if (error.vars !== undefined)
+                out.vars = error.vars;
+        }
+        /* v0 parity: a falsy cause (null, 0, "") is not logged */
+        if (error.cause)
+            out.cause = HoneyError.serialize(error.cause);
+        return out;
+    }
+}

package/dist/errors/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `defineErrors`: an app's error vocabulary. Each key becomes a factory that builds a `HoneyError`
+ * with that key and its status; a key with a schema takes a typed payload instead. `ERROR_META`
+ * keeps each key's status and schema for the projector and codegen.
+ */
+import type { StatusKey } from "../response/status.ts";
+import type { InferOutput, StandardSchemaLike } from "../validation/standard-schema.ts";
+import { type FieldError, HoneyError } from "./error.ts";
+type ErrorFactoryOpts = {
+    cause?: unknown;
+    fields?: Record<string, FieldError[]>;
+    headers?: Record<string, string>;
+    vars?: Record<string, number | string>;
+};
+type SchemaErrorOpts = {
+    cause?: unknown;
+    headers?: Record<string, string>;
+};
+type ErrorDefWithSchema = {
+    schema: StandardSchemaLike;
+    status: StatusKey;
+};
+type ErrorDef = ErrorDefWithSchema | StatusKey;
+export type ErrorMetaEntry = {
+    schema: StandardSchemaLike | null;
+    statusKey: StatusKey;
+};
+/** Per-key meta: keeps the schema and status-key literals for the typed error union. */
+type ErrorMetaForDef<D extends ErrorDef> = D extends ErrorDefWithSchema ? {
+    schema: D["schema"];
+    statusKey: D["status"];
+} : {
+    schema: null;
+    statusKey: D;
+};
+export declare const ERROR_META: unique symbol;
+export type ErrorFactories<TMap extends Record<string, ErrorDef>> = {
+    [K in keyof TMap]: TMap[K] extends ErrorDefWithSchema ? (data: InferOutput<TMap[K]["schema"]>, opts?: SchemaErrorOpts) => HoneyError : (opts?: ErrorFactoryOpts) => HoneyError;
+} & {
+    readonly [ERROR_META]: {
+        [K in keyof TMap]: ErrorMetaForDef<TMap[K]>;
+    };
+};
+export declare function defineErrors<const TMap extends Record<string, ErrorDef>>(map: TMap): ErrorFactories<TMap>;
+export {};

package/dist/errors/errors.js

@@ -0,0 +1,31 @@
+import { HoneyError } from "./error.js";
+export const ERROR_META = /* @__PURE__ */ Symbol.for("honey.error.meta");
+function standardFactory(errorKey, status) {
+    return (opts) => new HoneyError({
+        cause: opts?.cause,
+        errorKey,
+        fields: opts?.fields,
+        headers: opts?.headers,
+        status,
+        vars: opts?.vars,
+    });
+}
+function schemaFactory(errorKey, status) {
+    return (data, opts) => new HoneyError({ cause: opts?.cause, data, errorKey, headers: opts?.headers, status });
+}
+export function defineErrors(map) {
+    const result = Object.create(null);
+    const meta = Object.create(null);
+    for (const [key, def] of Object.entries(map)) {
+        if (typeof def === "string") {
+            meta[key] = { schema: null, statusKey: def };
+            result[key] = standardFactory(key, def);
+        }
+        else {
+            meta[key] = { schema: def.schema, statusKey: def.status };
+            result[key] = schemaFactory(key, def.status);
+        }
+    }
+    Object.defineProperty(result, ERROR_META, { configurable: false, enumerable: false, value: meta, writable: false });
+    return result;
+}

package/dist/errors/on-error.d.ts

@@ -0,0 +1,10 @@
+import type { MaybePromise } from "../middleware/middleware.ts";
+import type { FetchState } from "../routing/dispatch.ts";
+import type { AppSettings, ErrorCtx } from "../routing/settings.ts";
+import { type FormatterReport } from "./projector.ts";
+/** A crashed error formatter, logged with the request it answered (when there is one). */
+export declare function formatterReport(s: AppSettings<unknown>, state: FetchState | null): FormatterReport;
+/** What `onError`, `onNotFound` and `onMethodNotAllowed` receive. */
+export declare function errorCtx(s: AppSettings<unknown>, state: FetchState): ErrorCtx<unknown>;
+/** The error boundary of every `next()`: what was thrown becomes the Response that replaces it. Never rejects. */
+export declare function boundary(s: AppSettings<unknown>): (thrown: unknown, ctx: object) => MaybePromise<Response>;

package/dist/errors/on-error.js

@@ -0,0 +1,204 @@
+/**
+ * The error boundary of every `next()` and the app's `onError`: what a handler or middleware threw
+ * becomes the Response that replaces it. `onError` is awaited and response-shaping: it returns a
+ * HoneyError to replace the error, a Response to answer, or nothing to fall through to the native
+ * projection. The boundary never rejects.
+ *
+ * An unknown error the app did not handle gets a digest: the client's 500 carries only it, the
+ * operator's log line carries it with the error's name, message and stack (H17).
+ */
+import { REQUEST, setCtxError } from "../context/context.js";
+import { isHoneyResponse, isNodeOutbound } from "../response/builder.js";
+import { invokeUser } from "../realtime/invoke-user.js";
+import { pathOf, requestBindings } from "../telemetry/fields.js";
+import { HoneyError, hasUnknownStatus } from "./error.js";
+import { asHoneyError, createErrorResponse, DIGEST, projectThrown, safeErrorResponse, } from "./projector.js";
+function stateOf(ctx) {
+    return ctx[REQUEST];
+}
+/** A crashed error formatter, logged with the request it answered (when there is one). */
+export function formatterReport(s, state) {
+    return (failure) => {
+        const where = state === null ? {} : requestBindings(state.req.method, state.path, state.plan.route.id);
+        s.logger.error({ ...where, err: HoneyError.serialize(failure) }, "error formatter failed");
+    };
+}
+/** What `onError`, `onNotFound` and `onMethodNotAllowed` receive. */
+export function errorCtx(s, state) {
+    return {
+        env: state.env,
+        jsonFromError: (err) => createErrorResponse(err, s.errorFormatter, s.customErrorFormatter, {
+            format: s.errorFormat,
+            nodeOut: isNodeOutbound(state.req),
+            report: formatterReport(s, state),
+        }),
+        req: state.req,
+    };
+}
+/** How an error answers for `ctx`: its format, its request id as the instance, its bridge. */
+function answerFor(s, ctx) {
+    const state = stateOf(ctx);
+    return {
+        format: s.errorFormat,
+        instance: ctx.requestId ?? null,
+        nodeOut: isNodeOutbound(state.req),
+        report: formatterReport(s, state),
+    };
+}
+/** The response for `error`, recording it on `ctx.error`. */
+function respond(s, ctx, error) {
+    setCtxError(ctx, error);
+    return createErrorResponse(error, s.errorFormatter, s.customErrorFormatter, answerFor(s, ctx));
+}
+/**
+ * `error` in the request's locale: a translated copy, the thrown error never changed. A failing
+ * `resolveLocale` or `translate` is a warn, and the error answers untranslated. Never rejects.
+ */
+async function translated(s, i18n, ctx, error) {
+    try {
+        const c = ctx;
+        const state = stateOf(ctx);
+        const locale = await i18n.resolveLocale({
+            cookies: c.cookies,
+            env: state.env,
+            headers: c.headers,
+            params: c.params,
+            req: state.req,
+            search: c.search,
+        });
+        return i18n.translate(error, locale);
+    }
+    catch (failure) {
+        s.logger.warn({ ...bindings(ctx), err: HoneyError.serialize(failure) }, "error i18n failed");
+        return error;
+    }
+}
+/** Answer with `error`, translated first when the app has errorI18n (only then asynchronously). */
+function answer(s, ctx, error) {
+    const i18n = s.errorI18n;
+    if (i18n === null)
+        return respond(s, ctx, error);
+    return translated(s, i18n, ctx, error).then((localized) => respond(s, ctx, localized));
+}
+/** What an operator line says about the request: method, path without its query, route id. */
+function bindings(ctx) {
+    const state = stateOf(ctx);
+    return requestBindings(state.req.method, state.path, state.plan.route.id, {
+        requestId: ctx.requestId,
+        trace: state.trace?.ids(),
+    });
+}
+/** Sixteen hex characters, random per occurrence: it names the line, it says nothing about the error. */
+function newDigest() {
+    const bytes = crypto.getRandomValues(new Uint8Array(8));
+    let hex = "";
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, "0");
+    return hex;
+}
+/**
+ * Answer an error nothing handled. An unknown throw that became a 5xx gets a digest, and the
+ * operator's line; a HoneyError the app threw itself answers as it is.
+ */
+function unhandled(s, { ctx, error, thrown }) {
+    if (error !== thrown && error.status >= 500) {
+        const digest = newDigest();
+        Object.defineProperty(error, DIGEST, { value: digest });
+        s.logger.error({ ...bindings(ctx), digest, err: HoneyError.serialize(thrown) }, "unhandled error");
+    }
+    return answer(s, ctx, error);
+}
+/** A failing onError: logged once, then the native projection answers. */
+function onErrorFailed(s, t, failure) {
+    s.logger.error({ ...bindings(t.ctx), err: HoneyError.serialize(failure) }, "onError failed");
+    return unhandled(s, t);
+}
+/** Apply what `onError` returned: a HoneyError replaces the error, a Response answers, nothing falls through. */
+function settleOnError(s, t, result) {
+    if (result instanceof HoneyError)
+        return answer(s, t.ctx, hasUnknownStatus(result) ? projectThrown(result, stateOf(t.ctx).plan.policy) : result);
+    /* jsonFromError answers a HoneyResponse on the Node path: a Response all the same */
+    if (result instanceof Response || isHoneyResponse(result)) {
+        setCtxError(t.ctx, t.error);
+        return result;
+    }
+    return unhandled(s, t);
+}
+function convertWith(s, thrown, ctx) {
+    const t = { ctx, error: projectThrown(thrown, stateOf(ctx).plan.policy), thrown };
+    const onError = s.onError;
+    if (onError === null)
+        return unhandled(s, t);
+    let result;
+    try {
+        result = onError(thrown, errorCtx(s, stateOf(ctx)));
+    }
+    catch (failure) {
+        return onErrorFailed(s, t, failure);
+    }
+    if (!(result instanceof Promise))
+        return settleOnError(s, t, result);
+    return result.then((value) => settleOnError(s, t, value), (failure) => onErrorFailed(s, t, failure));
+}
+/**
+ * A thrown error whose answer is decided: its `http.error` span, and `telemetry.onError` in the
+ * request's background, contained (a failure is a warn). Never throws.
+ */
+function reportThrow(s, telemetry, ctx, thrown) {
+    const c = ctx;
+    const state = stateOf(ctx);
+    /* the boundary has answered: ctx.error holds what it answered as */
+    const honeyError = c.error;
+    const digest = honeyError[DIGEST];
+    /* telemetry on: every request it serves has a trace */
+    const trace = state.trace;
+    trace.error(honeyError, thrown, digest);
+    const onError = telemetry.onError;
+    if (onError === null)
+        return;
+    const report = {
+        durationMs: Math.round((performance.now() - trace.started) * 1000) / 1000,
+        error: thrown,
+        honeyError,
+        method: state.req.method,
+        path: pathOf(state.req.url),
+        routeId: state.plan.route.id,
+        ...(digest !== undefined && { digest }),
+        ...trace.ids(),
+    };
+    const warn = (error) => s.logger.warn({ err: HoneyError.serialize(error) }, "telemetry onError failed");
+    c.background(Promise.resolve().then(() => invokeUser(() => onError(report), { onError: warn, phase: "telemetry" })));
+}
+/** The error boundary of every `next()`: what was thrown becomes the Response that replaces it. Never rejects. */
+export function boundary(s) {
+    /* answering the error failed itself: what failed is logged, and the last-resort answer goes out */
+    const reportAndAnswer = (thrown, ctx, failure) => {
+        s.logger.error({ ...bindings(ctx), err: HoneyError.serialize(failure) }, "error response failed");
+        setCtxError(ctx, asHoneyError(thrown));
+        return safeErrorResponse(thrown, s.errorFormatter, s.customErrorFormatter, answerFor(s, ctx));
+    };
+    const answered = (thrown, ctx) => {
+        try {
+            const res = convertWith(s, thrown, ctx);
+            return res instanceof Promise ? res.catch((failure) => reportAndAnswer(thrown, ctx, failure)) : res;
+        }
+        catch (failure) {
+            return reportAndAnswer(thrown, ctx, failure);
+        }
+    };
+    /* telemetry hears the error once its answer is decided, and never changes it */
+    return (thrown, ctx) => {
+        const res = answered(thrown, ctx);
+        const telemetry = s.telemetry;
+        if (telemetry === null)
+            return res;
+        if (!(res instanceof Promise)) {
+            reportThrow(s, telemetry, ctx, thrown);
+            return res;
+        }
+        return res.then((settled) => {
+            reportThrow(s, telemetry, ctx, thrown);
+            return settled;
+        });
+    };
+}

package/dist/errors/problem-json.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Problem Details (RFC 9457, A7), the opt-in error format: `app.errorFormat("problem+json")`. A
+ * standard error answers as `application/problem+json`: its key as the `type` URI, the status's
+ * reason phrase as `title`, the message as `detail`, the request id as `instance` when
+ * `requestId()` set one, and its fields under the extension member `errors`, where no field can
+ * stand in for a member. Vars and the cause stay server-side, as in the native envelope. A schema
+ * error keeps its declared body.
+ */
+import type { HoneyError } from "./error.ts";
+/** How errors answer: honey's envelope (the default) or RFC 9457 Problem Details. */
+export type ErrorFormat = "honey" | "problem+json";
+export declare const PROBLEM_JSON = "application/problem+json";
+/** The Problem Details document for a standard error; `instance` is the request id, or `null`. */
+export declare function problemDetails(error: HoneyError, instance: string | null): Record<string, unknown>;