@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/openapi/tags.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The document's tags: every tag an operation names, once, in the order operations first name
+ * them, each merged with what the caller declares for it (description, externalDocs,
+ * x-displayName). Tags are explicit: nothing is derived from paths. A declared tag no operation
+ * names is not listed, and said; a tag declared twice is refused.
+ */
+import type { EmittedOperation } from "./paths.ts";
+export type OpenApiExternalDocs = {
+    readonly description?: string;
+    readonly url: string;
+};
+export type OpenApiTag = {
+    readonly description?: string;
+    readonly externalDocs?: OpenApiExternalDocs;
+    readonly name: string;
+    readonly "x-displayName"?: string;
+};
+export type TagReport = (code: "INVALID_TAG" | "UNUSED_TAG", level: "error" | "warn", message: string) => void;
+/** The tags `operations` name, first-seen, with the declared metadata of each. */
+export declare function tagsOf(operations: readonly EmittedOperation[], declared: readonly OpenApiTag[] | undefined, report: TagReport): OpenApiTag[];

package/dist/openapi/tags.js

@@ -0,0 +1,20 @@
+/** The tags `operations` name, first-seen, with the declared metadata of each. */
+export function tagsOf(operations, declared, report) {
+    const byName = new Map();
+    for (const tag of declared ?? []) {
+        if (byName.has(tag.name))
+            report("INVALID_TAG", "error", `tag "${tag.name}" is declared twice`);
+        else
+            byName.set(tag.name, tag);
+    }
+    const named = new Set();
+    for (const { operation } of operations) {
+        for (const name of Array.isArray(operation.tags) ? operation.tags : [])
+            named.add(name);
+    }
+    for (const name of byName.keys()) {
+        if (!named.has(name))
+            report("UNUSED_TAG", "warn", `tag "${name}" is declared but no operation names it`);
+    }
+    return [...named].map((name) => structuredClone(byName.get(name) ?? { name }));
+}

package/dist/openapi/webhooks.d.ts

@@ -0,0 +1,19 @@
+import type { Operation } from "./paths.ts";
+import type { Convert } from "./responses.ts";
+export type WebhookSignature = {
+    readonly algorithm: "hmac-sha256";
+    readonly encoding: "base64" | "hex";
+    readonly header: string;
+    /** what precedes the digest in the header, as `sha256=` */
+    readonly prefix?: string;
+};
+export type OpenApiWebhook = {
+    readonly body: unknown;
+    readonly description?: string;
+    /** `"post"` by default */
+    readonly method?: string;
+    readonly signature?: WebhookSignature;
+    readonly summary?: string;
+};
+/** The 3.1 `webhooks` of `webhooks`, by name in code-unit order; each refusal reported through `error`. */
+export declare function webhooksOf(webhooks: Readonly<Record<string, OpenApiWebhook>> | undefined, convert: Convert, error: (message: string) => void): Record<string, Record<string, Operation>>;

package/dist/openapi/webhooks.js

@@ -0,0 +1,70 @@
+/**
+ * The document's webhooks (OpenAPI 3.1): each request the API sends a subscriber, by name, as the
+ * operation the subscriber serves. Its body converts on the output side, as the API writes it. A
+ * signed webhook states how as `x-honey-signature`, which the SDKs' verify helpers read; a
+ * declaration that cannot be signed or sent as written is refused.
+ */
+import { compareCodeUnits } from "../schema/canonicalize.js";
+const METHODS = ["delete", "get", "patch", "post", "put"];
+/* C0, DEL and C1 */
+const CONTROL = /\p{Cc}/u;
+/* a summary or description is CommonMark text: tabs and line breaks are its own */
+const STRAY = /(?![\t\n\r])\p{Cc}/u;
+/* RFC 9110 token: a header name */
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** Each reason `signature` cannot be checked as written. */
+function signatureErrors(signature) {
+    const errors = [];
+    if (signature.algorithm !== "hmac-sha256")
+        errors.push(`signature algorithm "${signature.algorithm}" is not hmac-sha256`);
+    if (signature.encoding !== "hex" && signature.encoding !== "base64")
+        errors.push(`signature encoding "${signature.encoding}" is not hex or base64`);
+    if (!TOKEN.test(signature.header))
+        errors.push(`signature header ${JSON.stringify(signature.header)} is not a header name`);
+    if (signature.prefix !== undefined && CONTROL.test(signature.prefix))
+        errors.push("the signature prefix holds a control character");
+    return errors;
+}
+/** Each reason `webhook` cannot be sent as written. */
+function webhookErrors(webhook, method) {
+    const errors = METHODS.includes(method) ? [] : [`method "${webhook.method}" is not one of ${METHODS.join(", ")}`];
+    for (const [field, text] of [
+        ["summary", webhook.summary],
+        ["description", webhook.description],
+    ]) {
+        if (text !== undefined && STRAY.test(text))
+            errors.push(`the ${field} holds a control character`);
+    }
+    return webhook.signature === undefined ? errors : [...errors, ...signatureErrors(webhook.signature)];
+}
+/** The 3.1 `webhooks` of `webhooks`, by name in code-unit order; each refusal reported through `error`. */
+export function webhooksOf(webhooks, convert, error) {
+    const out = {};
+    for (const name of Object.keys(webhooks ?? {}).sort(compareCodeUnits)) {
+        const webhook = webhooks[name];
+        const method = (webhook.method ?? "post").toLowerCase();
+        if (name === "")
+            error("a webhook needs a name");
+        else if (CONTROL.test(name))
+            error(`webhook ${JSON.stringify(name)}: the name holds a control character`);
+        for (const reason of webhookErrors(webhook, method))
+            error(`webhook ${JSON.stringify(name)}: ${reason}`);
+        const operation = {};
+        if (webhook.summary !== undefined)
+            operation.summary = webhook.summary;
+        if (webhook.description !== undefined)
+            operation.description = webhook.description;
+        const schema = convert(webhook.body, "output", `${name}Webhook`);
+        operation.requestBody = { content: { "application/json": { schema } }, required: true };
+        operation.responses = { "200": { description: "Received" } };
+        if (webhook.signature !== undefined)
+            operation["x-honey-signature"] = signatureOf(webhook.signature);
+        out[name] = { [method]: operation };
+    }
+    return out;
+}
+/** The signature as the SDKs read it: its own fields only, in one order. */
+function signatureOf(signature) {
+    const { algorithm, encoding, header, prefix } = signature;
+    return prefix === undefined ? { algorithm, encoding, header } : { algorithm, encoding, header, prefix };
+}

package/dist/openapi/yaml.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A JSON-compatible YAML 1.2 emitter: the same document as `JSON.stringify`, in another encoding.
+ * The value is first normalized through JSON (an undefined key is skipped, a Date is its ISO
+ * string, NaN is null); then every string that is not plainly safe is written double-quoted, which
+ * also reads the same under YAML 1.1 readers. Vendor-free: what a served `.yaml` is written with.
+ */
+/** `value` as YAML, ending in a newline; `undefined` is `null`, as JSON has no nothing. */
+export declare function toYaml(value: unknown): string;

package/dist/openapi/yaml.js

@@ -0,0 +1,74 @@
+/**
+ * A JSON-compatible YAML 1.2 emitter: the same document as `JSON.stringify`, in another encoding.
+ * The value is first normalized through JSON (an undefined key is skipped, a Date is its ISO
+ * string, NaN is null); then every string that is not plainly safe is written double-quoted, which
+ * also reads the same under YAML 1.1 readers. Vendor-free: what a served `.yaml` is written with.
+ */
+const INDENT = "  ";
+/*
+ * A plain scalar is used only for a conservative shape: it starts with a letter, `_`, `/` or `$`
+ * and holds only word characters, `.`, `/`, `$`, `-`, `+`, `{}`, `()` and single inner spaces.
+ * That excludes every indicator, `: `, ` #`, a leading digit (numbers, 1.1 octal and sexagesimal)
+ * and `.inf`/`.nan`.
+ */
+const PLAIN = /^[A-Za-z_/$](?:[\w./${}()+-]| (?! ))*$/;
+/* words YAML 1.1 or 1.2 reads as null or a boolean */
+const RESERVED = /^(?:y|n|yes|no|on|off|true|false|null|~)$/i;
+/* JSON string syntax is a YAML double-quoted scalar, but YAML forbids raw DEL, C1 bar NEL, the BOM and non-characters */
+const UNPRINTABLE = /[\u007f-\u0084\u0086-\u009f￾￿]/g;
+/** `value` as YAML, ending in a newline; `undefined` is `null`, as JSON has no nothing. */
+export function toYaml(value) {
+    const json = JSON.stringify(value);
+    return `${emit(json === undefined ? null : JSON.parse(json), 0)}\n`;
+}
+function emit(value, indent) {
+    if (value === null || typeof value !== "object")
+        return scalar(value);
+    if (Array.isArray(value))
+        return emitArray(value, indent);
+    return emitObject(value, indent);
+}
+/** A JSON scalar: null, a boolean, a number or a string. */
+function scalar(value) {
+    return typeof value === "string" ? emitString(value) : String(value);
+}
+function emitString(value) {
+    return PLAIN.test(value) && !value.endsWith(" ") && !RESERVED.test(value) ? value : quote(value);
+}
+function quote(value) {
+    return JSON.stringify(value).replace(UNPRINTABLE, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function isNonEmptyCollection(value) {
+    return value !== null && typeof value === "object" && Object.keys(value).length > 0;
+}
+function emitArray(value, indent) {
+    if (value.length === 0)
+        return "[]";
+    const pad = INDENT.repeat(indent);
+    const childPad = INDENT.repeat(indent + 1);
+    return value
+        .map((item) => {
+        if (!isNonEmptyCollection(item))
+            return `${pad}- ${emit(item, 0)}`;
+        /* the item's first line, indented one level, moves up onto the dash */
+        const lines = emit(item, indent + 1).split("\n");
+        lines[0] = `${pad}- ${lines[0].slice(childPad.length)}`;
+        return lines.join("\n");
+    })
+        .join("\n");
+}
+function emitObject(value, indent) {
+    const keys = Object.keys(value);
+    if (keys.length === 0)
+        return "{}";
+    const pad = INDENT.repeat(indent);
+    return keys
+        .map((key) => {
+        const child = value[key];
+        const name = emitString(key);
+        return isNonEmptyCollection(child)
+            ? `${pad}${name}:\n${emit(child, indent + 1)}`
+            : `${pad}${name}: ${emit(child, 0)}`;
+    })
+        .join("\n");
+}

package/dist/proxy/headers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The headers a proxy sends upstream and answers with. Hop-by-hop headers (RFC 9110 §7.6.1)
+ * describe one connection and never cross a proxy, in either direction, and neither does any
+ * header `Connection` names. Upstream, the client's `Host` and `Expect` stay behind, and the
+ * forwarding headers describe the client as the platform reported it (H23): `X-Forwarded-For` is
+ * `ctx.ip`, `-Proto` and `-Host` the request URL's; whatever forwarding headers the client wrote
+ * are dropped, never passed on. `CF-Connecting-IP` passes untouched: on Workers the edge set it,
+ * so a service-bound Worker downstream sees the same client.
+ */
+/** The headers an edit needs: native `Headers` and the plain map's `HoneyOutHeaders` both are. */
+type Editable = {
+    delete(name: string): void;
+    get(name: string): string | null;
+};
+/** Drop every hop-by-hop header and every header `Connection` names; an upgrade may keep `Upgrade`. */
+export declare function dropHopByHop(headers: Editable, keepUpgrade: boolean): void;
+export type Upstream = {
+    /** `ctx.ip`; `undefined` when no forwarding headers are added. */
+    readonly client: string | null | undefined;
+    readonly websocket: boolean;
+};
+/** The request headers destination is handed: a copy, cleaned, with the forwarding headers set. */
+export declare function upstreamHeaders(request: Request, upstream: Upstream): Headers;
+/**
+ * The response headers the client gets, edited in place. `fetch()` hands back a decoded body with
+ * the `Content-Encoding` that described the encoded one; when `decoded`, that header and the
+ * encoded length go, so the headers describe the bytes the client receives.
+ */
+export declare function clientHeaders(headers: Editable, decoded: boolean): void;
+export {};

package/dist/proxy/headers.js

@@ -0,0 +1,86 @@
+/**
+ * The headers a proxy sends upstream and answers with. Hop-by-hop headers (RFC 9110 §7.6.1)
+ * describe one connection and never cross a proxy, in either direction, and neither does any
+ * header `Connection` names. Upstream, the client's `Host` and `Expect` stay behind, and the
+ * forwarding headers describe the client as the platform reported it (H23): `X-Forwarded-For` is
+ * `ctx.ip`, `-Proto` and `-Host` the request URL's; whatever forwarding headers the client wrote
+ * are dropped, never passed on. `CF-Connecting-IP` passes untouched: on Workers the edge set it,
+ * so a service-bound Worker downstream sees the same client.
+ */
+/** `proxy-connection` is the pre-standard spelling clients still send. */
+const HOP_BY_HOP = [
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+];
+/** What a client may write about itself, and a proxy must never pass on as fact. */
+const FORWARDING = [
+    "forwarded",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-port",
+    "x-forwarded-proto",
+    "x-real-ip",
+];
+/** Drop every hop-by-hop header and every header `Connection` names; an upgrade may keep `Upgrade`. */
+export function dropHopByHop(headers, keepUpgrade) {
+    const named = headers.get("connection");
+    if (named !== null) {
+        for (const token of named.split(",")) {
+            const name = token.trim().toLowerCase();
+            if (name !== "" && !(keepUpgrade && name === "upgrade"))
+                headers.delete(name);
+        }
+    }
+    for (const name of HOP_BY_HOP)
+        if (!(keepUpgrade && name === "upgrade"))
+            headers.delete(name);
+}
+/** The scheme and host of a request URL, read without parsing it: a Request's URL always has a path. */
+function originParts(url) {
+    const scheme = url.indexOf("://");
+    return { host: url.slice(scheme + 3, url.indexOf("/", scheme + 3)), proto: url.slice(0, scheme) };
+}
+/** The request headers destination is handed: a copy, cleaned, with the forwarding headers set. */
+export function upstreamHeaders(request, upstream) {
+    const headers = new Headers(request.headers);
+    dropHopByHop(headers, upstream.websocket);
+    if (upstream.websocket) {
+        headers.set("upgrade", "websocket");
+        headers.set("connection", "upgrade");
+    }
+    headers.delete("host");
+    /* the proxy reads the body itself */
+    headers.delete("expect");
+    for (const name of FORWARDING)
+        headers.delete(name);
+    if (upstream.client !== undefined) {
+        const { host, proto } = originParts(request.url);
+        if (upstream.client !== null)
+            headers.set("x-forwarded-for", upstream.client);
+        headers.set("x-forwarded-proto", proto);
+        headers.set("x-forwarded-host", host);
+    }
+    return headers;
+}
+/**
+ * The response headers the client gets, edited in place. `fetch()` hands back a decoded body with
+ * the `Content-Encoding` that described the encoded one; when `decoded`, that header and the
+ * encoded length go, so the headers describe the bytes the client receives.
+ */
+export function clientHeaders(headers, decoded) {
+    dropHopByHop(headers, false);
+    if (!decoded)
+        return;
+    const encoding = headers.get("content-encoding");
+    if (encoding !== null && encoding.trim().toLowerCase() !== "identity") {
+        headers.delete("content-encoding");
+        headers.delete("content-length");
+    }
+}

package/dist/proxy/proxy.d.ts

@@ -0,0 +1,39 @@
+import type { TypedResponse } from "../response/response.ts";
+export type ProxyConfig<TCtx> = {
+    /**
+     * Where the request goes: `fetch`, a Workers service binding, a Durable Object stub, anything
+     * that answers a Response. `url` is the normalized path and query (after `rewriteUrl`), `init`
+     * the method, headers, body, signal and `redirect: "manual"` the framework prepared. A network
+     * failure the runtime reports is a 502; any other throw, a bug here included, a 500.
+     */
+    destination: (ctx: TCtx, url: string, init: RequestInit) => Promise<Response> | Response;
+    /**
+     * Whether the answer's body is already decoded, as `fetch()` always returns it. When true (the
+     * default) an encoded answer loses `Content-Encoding` and `Content-Length`, so the headers
+     * describe the bytes the client gets. False when destination returns bytes still encoded.
+     */
+    decoded?: boolean;
+    /** Add `X-Forwarded-For`, `-Proto` and `-Host`. Default true; the client's own are dropped either way. */
+    forwardedHeaders?: boolean;
+    /**
+     * Most milliseconds the upstream may stay silent while the body streams. Omitted or not
+     * positive: no limit (an SSE stream may idle). A stall aborts the upstream and errors the body.
+     * Off for a WebSocket upgrade.
+     */
+    idleTimeout?: number | ((ctx: TCtx) => number);
+    /**
+     * Runs on the answer before the client gets it, its headers mutable. Return a Response to
+     * replace it. Not called for a 101 upgrade, which is the runtime's.
+     */
+    onResponse?: (ctx: TCtx, response: Response) => Promise<Response | void> | Response | void;
+    /** Run last on the forwarded headers, so it may set any of them: a record of entries, or an edit. */
+    requestHeaders?: Record<string, string> | ((ctx: TCtx, headers: Headers) => void);
+    /** Rewrite the normalized path and query before destination sees it. */
+    rewriteUrl?: (url: string, ctx: TCtx) => string;
+    /**
+     * Most milliseconds to wait for the answer's headers; later is a 504. Default 60 000; not
+     * positive is no limit. The body is `idleTimeout`'s. Off for a WebSocket upgrade.
+     */
+    timeout?: number | ((ctx: TCtx) => number);
+};
+export declare function proxy<TCtx>(config: ProxyConfig<TCtx>): (ctx: TCtx) => Promise<TypedResponse>;

package/dist/proxy/proxy.js

@@ -0,0 +1,103 @@
+/**
+ * `proxy(config)`: a route handler that forwards the request to an upstream and streams its answer
+ * back, mounted like any other: `app.all("/api/*rest").handler(proxy({ destination }))`. Plain code
+ * reached through `@lovrozagar/honey/proxy`, no slot and no builder method (H23): core never imports
+ * it. The answer is the passthrough brand, since the upstream decides its status and type.
+ *
+ * Both ways, hop-by-hop headers are dropped and the forwarding headers describe the client as the
+ * platform reported it (headers.ts); the URL is the normalized path, the deadlines and failure
+ * mapping are upstream.ts's. Every method but GET and HEAD forwards its body. The call follows
+ * `ctx.signal`: a disconnect, `timeout()` or shutdown cancels it and its body. Redirects go back to
+ * the client, never followed. On the Node bridge the answer is a HoneyResponse, so the header
+ * middleware in front of the route stay on the plain map.
+ */
+import { TRACE } from "../context/context.js";
+import { createHoneyResponse, isNodeOutbound } from "../response/builder.js";
+import { headersToRecord, HoneyOutHeaders } from "../response/out-headers.js";
+import { searchOfUrl } from "../routing/request-path.js";
+import { clientHeaders, upstreamHeaders } from "./headers.js";
+import { forwardBody, msOf, timeoutError, withIdleTimeout, within } from "./upstream.js";
+/** Default time allowed until the upstream's response headers arrive. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+function isNullBody(status) {
+    return status === 101 || status === 103 || status === 204 || status === 205 || status === 304;
+}
+/** The client's copy of the upstream answer, its headers cleaned and mutable for onResponse. */
+function answerFor(response, body, decoded, nodeOut) {
+    const init = { status: response.status, statusText: response.statusText };
+    const stream = isNullBody(response.status) ? null : body;
+    if (nodeOut) {
+        const headers = new HoneyOutHeaders(headersToRecord(response.headers));
+        clientHeaders(headers, decoded);
+        return createHoneyResponse({ ...init, headers: headers.toRecord(), stream });
+    }
+    const headers = new Headers(response.headers);
+    clientHeaders(headers, decoded);
+    return new Response(stream, { ...init, headers });
+}
+function applyRequestHeaders(edit, ctx, headers) {
+    if (typeof edit === "function")
+        return edit(ctx, headers);
+    for (const [name, value] of Object.entries(edit ?? {}))
+        headers.set(name, value);
+}
+/** An untraced request's call: made as it is, its headers as they came. */
+const untraced = (call) => call();
+/**
+ * How the call is made: on a traced request inside its `http.proxy` span, the upstream getting the
+ * request's trace, never the caller's (a trusted caller's tracestate goes on with it).
+ */
+function traced(ctx, method, headers) {
+    const outbound = ctx[TRACE]?.outbound("http.proxy", method);
+    if (outbound === undefined)
+        return untraced;
+    if (outbound.traceparent === null)
+        headers.delete("traceparent");
+    else
+        headers.set("traceparent", outbound.traceparent);
+    if (outbound.tracestate === undefined)
+        headers.delete("tracestate");
+    else
+        headers.set("tracestate", outbound.tracestate);
+    return (call) => outbound.send(call);
+}
+export function proxy(config) {
+    const decoded = config.decoded !== false;
+    const forwarded = config.forwardedHeaders !== false;
+    return async (ctx) => {
+        const { ip, path, req, signal } = ctx;
+        const websocket = req.headers.get("upgrade")?.trim().toLowerCase() === "websocket";
+        const pathQuery = path + searchOfUrl(req.url);
+        const url = config.rewriteUrl ? config.rewriteUrl(pathQuery, ctx) : pathQuery;
+        const headers = upstreamHeaders(req, { client: forwarded ? ip : undefined, websocket });
+        /* requestHeaders below still has the last word */
+        const send = traced(ctx, req.method, headers);
+        const body = await forwardBody(req);
+        /* no body, or bytes whose length fetch() computes itself */
+        if (!(body instanceof ReadableStream))
+            headers.delete("content-length");
+        applyRequestHeaders(config.requestHeaders, ctx, headers);
+        const upstream = new AbortController();
+        const init = {
+            body: body ?? undefined,
+            headers,
+            method: req.method,
+            redirect: "manual",
+            signal: AbortSignal.any([signal, upstream.signal]),
+        };
+        /* a streamed request body needs it on Node; Workers imply it */
+        if (body instanceof ReadableStream)
+            init.duplex = "half";
+        const headerMs = websocket ? undefined : msOf(config.timeout, ctx, DEFAULT_TIMEOUT_MS);
+        const response = await within({ client: signal, headerMs, upstream }, () => send(() => config.destination(ctx, url, init)));
+        if (response.status === 101)
+            return response;
+        const idleMs = websocket ? undefined : msOf(config.idleTimeout, ctx);
+        const stream = response.body !== null && idleMs !== undefined
+            ? withIdleTimeout(response.body, idleMs, () => upstream.abort(timeoutError()))
+            : response.body;
+        const answer = answerFor(response, stream, decoded, isNodeOutbound(req));
+        const replaced = config.onResponse ? await config.onResponse(ctx, answer) : undefined;
+        return (replaced ?? answer);
+    };
+}

package/dist/proxy/upstream.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The body destination is handed. Bytes when small and sized: a streamed body the destination
+ * never reads can hold a service binding open until it times out, and a body teed by `clone()`
+ * has no known length. Bytes have neither problem.
+ */
+export declare function forwardBody(request: Request): Promise<ArrayBuffer | ReadableStream<Uint8Array> | null>;
+/**
+ * Whether `error` means the upstream failed (502), as opposed to a bug in user code (500). Fetch
+ * reports a network failure as a `TypeError`, as it does a typo, and runtimes tell them apart
+ * differently: undici says "fetch failed", Bun puts a `code` on the error (`ConnectionRefused`,
+ * `ENOTFOUND`), Workers say the network connection was lost. An invalid URL is the caller's bug.
+ */
+export declare function isUpstreamFailure(error: unknown): boolean;
+export declare function timeoutError(): DOMException;
+/** A deadline option as milliseconds, or `undefined` for none (omitted or not positive). */
+export declare function msOf<TCtx>(option: number | ((ctx: TCtx) => number) | undefined, ctx: TCtx, fallback?: number): number | undefined;
+/** One call and its deadline: the upstream controller to abort, the client's signal to tell a disconnect apart. */
+export type Call = {
+    readonly client: AbortSignal;
+    readonly headerMs: number | undefined;
+    readonly upstream: AbortController;
+};
+/** Await `answer` within the header deadline; map what it throws to what the client is told. */
+export declare function within(call: Call, answer: () => Promise<Response> | Response): Promise<Response>;
+/**
+ * `body`, erroring and calling `onIdle` (which aborts the upstream) when the upstream sends nothing
+ * for `ms`. The clock runs only while a read waits: a client reading slowly is backpressure, not an
+ * idle upstream.
+ */
+export declare function withIdleTimeout(body: ReadableStream<Uint8Array>, ms: number, onIdle: () => void): ReadableStream<Uint8Array>;

package/dist/proxy/upstream.js

@@ -0,0 +1,116 @@
+/**
+ * The call to the upstream: the body it is sent, the deadlines it is held to, and what its failures
+ * mean to the client. A network failure the runtime reports is a 502 `bad_gateway`, a missed
+ * deadline a 504 `gateway_timeout`; any other throw, a bug in `destination` included, stays what
+ * it is (a 500). The URL is the router's normalized `ctx.path` plus the raw query: one leading
+ * slash, `//` and `\` collapsed, encoded separators refused with a 400 before any handler runs, so
+ * neither `base + url` nor `new URL(url, base)` can leave the upstream's origin (SSRF).
+ */
+import { HoneyError } from "../errors/error.js";
+/* bodies up to this size with a declared length are forwarded as bytes; larger or unsized ones stream */
+const MAX_BUFFERED_BODY_BYTES = 1024 * 1024;
+/** Network-level codes runtimes put on errors when the upstream cannot be reached or drops. */
+const NETWORK_CODES = /^(?:E[A-Z0-9_]+|Connection\w*|UND_ERR\w*|UNABLE_\w+|CERT_\w+|DEPTH_ZERO\w*)$/;
+const FETCH_FAILED = /^fetch failed/i;
+const CONNECTION_LOST = /network connection (?:was )?lost/i;
+/**
+ * The body destination is handed. Bytes when small and sized: a streamed body the destination
+ * never reads can hold a service binding open until it times out, and a body teed by `clone()`
+ * has no known length. Bytes have neither problem.
+ */
+export async function forwardBody(request) {
+    const method = request.method;
+    /* fetch refuses a GET or HEAD body */
+    if (request.body === null || method === "GET" || method === "HEAD")
+        return null;
+    const declared = Number.parseInt(request.headers.get("content-length") ?? "", 10);
+    if (Number.isFinite(declared) && declared <= MAX_BUFFERED_BODY_BYTES)
+        return request.arrayBuffer();
+    return request.body;
+}
+/**
+ * Whether `error` means the upstream failed (502), as opposed to a bug in user code (500). Fetch
+ * reports a network failure as a `TypeError`, as it does a typo, and runtimes tell them apart
+ * differently: undici says "fetch failed", Bun puts a `code` on the error (`ConnectionRefused`,
+ * `ENOTFOUND`), Workers say the network connection was lost. An invalid URL is the caller's bug.
+ */
+export function isUpstreamFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    if (typeof code === "string")
+        return !code.startsWith("ERR_INVALID") && NETWORK_CODES.test(code);
+    return error instanceof TypeError && (FETCH_FAILED.test(error.message) || CONNECTION_LOST.test(error.message));
+}
+export function timeoutError() {
+    return new DOMException("upstream timed out", "TimeoutError");
+}
+/** A deadline option as milliseconds, or `undefined` for none (omitted or not positive). */
+export function msOf(option, ctx, fallback) {
+    const ms = typeof option === "function" ? option(ctx) : (option ?? fallback);
+    return ms !== undefined && ms > 0 ? ms : undefined;
+}
+/** Await `answer` within the header deadline; map what it throws to what the client is told. */
+export async function within(call, answer) {
+    let timedOut = false;
+    const timer = call.headerMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            timedOut = true;
+            call.upstream.abort(timeoutError());
+        }, call.headerMs);
+    try {
+        return await answer();
+    }
+    catch (error) {
+        /* ours, or the destination's own AbortSignal.timeout() */
+        if (timedOut || (error instanceof DOMException && error.name === "TimeoutError")) {
+            throw new HoneyError({ cause: error, errorKey: "gateway_timeout", status: "gateway_timeout" });
+        }
+        if (!call.client.aborted && isUpstreamFailure(error)) {
+            throw new HoneyError({ cause: error, errorKey: "bad_gateway", status: "bad_gateway" });
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * `body`, erroring and calling `onIdle` (which aborts the upstream) when the upstream sends nothing
+ * for `ms`. The clock runs only while a read waits: a client reading slowly is backpressure, not an
+ * idle upstream.
+ */
+export function withIdleTimeout(body, ms, onIdle) {
+    const reader = body.getReader();
+    return new ReadableStream({
+        cancel: (reason) => reader.cancel(reason),
+        async pull(controller) {
+            let timer;
+            const idle = new Promise((resolve) => {
+                timer = setTimeout(() => resolve("idle"), ms);
+            });
+            try {
+                const result = await Promise.race([reader.read(), idle]);
+                if (result === "idle") {
+                    onIdle();
+                    const error = timeoutError();
+                    reader.cancel(error).catch(() => {
+                        /* the upstream may not react to the abort (a binding, a stub): the body errors below either way */
+                    });
+                    controller.error(error);
+                }
+                else if (result.done)
+                    controller.close();
+                else
+                    controller.enqueue(result.value);
+            }
+            catch (error) {
+                controller.error(error);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    });
+}