@tabai/sdk 0.2.0

package/dist/proxy/proxy.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The proxy layer: one handler that forwards a request upstream, meters the
+ * delivery through the post-paid plugin, and runs hooks around both (R23.4).
+ *
+ * ## Order of operations, which is the whole contract
+ *
+ * ```text
+ * before hooks, in registration order
+ *   -> metering.execute( forward to upstream )
+ * after hooks, in reverse order
+ * ```
+ *
+ * The forward runs *inside* the metering plugin's `execute`, so the plugin sees
+ * the upstream's response exactly as it sees a local handler's: it records the
+ * delivery once the response exists, attaches the charge block, and replaces
+ * the response with a 402 on `LimitExceeded` alone. Nothing about the plugin's
+ * ordering guarantee changes because the handler is a network hop, and the
+ * "never withhold pending payment" rule (R23.3) is inherited rather than
+ * re-implemented here.
+ *
+ * ## Streaming
+ *
+ * The upstream response body is passed through as the stream it arrived as.
+ * Nothing here reads it, and the charge headers are attached by rebuilding the
+ * response around the same stream. A hook that needs the body must `clone()` the
+ * response and read the copy, and a hook that does so pays the buffering it
+ * asked for and nobody else does. The request body is likewise forwarded as a
+ * stream where the host `fetch` supports one.
+ *
+ * ## What is not forwarded
+ *
+ * Hop-by-hop request headers, `host`, and `content-length` are dropped before
+ * forwarding, because they describe the connection the proxy is on rather than
+ * the request. On the way back, `content-encoding`, `content-length`, and
+ * `transfer-encoding` are dropped, because the host `fetch` already decoded the
+ * body and the outbound server re-frames it; forwarding those headers would tell
+ * the caller to decode a body that is already plain.
+ *
+ * ## Failures are responses, never throws
+ *
+ * An unreachable upstream is a 502 carrying a `TabError` body. It is not a
+ * delivery, so the plugin's default `billable` predicate does not meter it. A
+ * critical hook's `err` is a response at its category's status. The handler
+ * this factory returns never rejects.
+ *
+ * Requirements: 23.4, 23.3
+ */
+import { type Result, type TabError } from "../_shared/index.js";
+import { type Logger } from "../logger.js";
+import { type MeteredCharge, type MeteringOutcome, type PostPaidPlugin } from "../server/post-paid.js";
+import type { ProxyHook, ProxyPhase } from "./hooks.js";
+import type { SettlementView } from "./hooks.js";
+/** Request headers that describe the hop rather than the request, per RFC 9110. */
+export declare const HOP_BY_HOP_HEADERS: readonly string[];
+/** Response headers the host `fetch` has already acted on and the outbound server re-frames. */
+export declare const REFRAMED_RESPONSE_HEADERS: readonly string[];
+/** The forward this proxy hands to its `fetch`. Structural, like `client-402.ts`. */
+export interface ProxyForwardInit {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    /** The request body stream, or undefined for a bodiless method. */
+    readonly body?: unknown;
+    /** Required by the host `fetch` to send a streamed request body. */
+    readonly duplex?: "half";
+    readonly signal?: AbortSignal;
+}
+/**
+ * The `fetch` the proxy forwards with. The host's global `fetch` is the default.
+ *
+ * The third argument is the request as it reached the proxy, the same object
+ * the metering plugin later hands to `priceOf`. A forward that learns the price
+ * on the way, the x402-fronting one does, keys what it learned by it. The host
+ * `fetch` and every existing two-argument `fetchImpl` ignore it.
+ */
+export type ProxyFetch = (url: string, init: ProxyForwardInit, request: Request) => Promise<Response>;
+/** One hook phase that returned an error or threw, in the order it happened. */
+export interface HookFailure {
+    readonly hook: string;
+    readonly phase: ProxyPhase;
+    readonly critical: boolean;
+    readonly error: TabError;
+}
+export interface ProxyResult {
+    /** The response that goes out. */
+    readonly response: Response;
+    /**
+     * `delivered`: the upstream's response, metered or not. `refused`: the metering
+     * plugin replaced it, which is `LimitExceeded` and the two Agent-side refusals
+     * only. `failed`: a critical hook or the forward itself failed.
+     */
+    readonly kind: "delivered" | "refused" | "failed";
+    /**
+     * Resolves once the delivery is recorded. Already resolved under the plugin's
+     * default `after-metering`; still pending under `before-metering`, where a
+     * host with a request lifetime hook passes it there.
+     */
+    readonly metering: Promise<MeteringOutcome> | undefined;
+    /** The recorded charge, when the outcome was known before the hooks ran. */
+    readonly charge: MeteredCharge | undefined;
+    /** The Settlement a hook attached (R23.5). */
+    readonly settlement: SettlementView | undefined;
+    /** Every hook failure, critical or not. */
+    readonly hookFailures: readonly HookFailure[];
+    /** The error that produced a `failed` result. */
+    readonly failure: TabError | undefined;
+    /** The shared scratch the hooks used, for a Service that wants to log it. */
+    readonly state: ReadonlyMap<string, unknown>;
+}
+export interface TabProxyOptions {
+    /** Absolute base URL of the service being fronted. The request path and query are appended. */
+    readonly upstream: string;
+    readonly hooks?: readonly ProxyHook[];
+    /** The post-paid plugin of `server/post-paid.ts`. Metering runs on every request. */
+    readonly metering: PostPaidPlugin;
+    readonly fetchImpl?: ProxyFetch;
+    readonly logger?: Logger;
+    /** Aborts the forward after this long. No timeout when omitted. */
+    readonly timeoutMs?: number;
+    /** Request headers dropped before forwarding, on top of the hop-by-hop set and `host`. */
+    readonly dropRequestHeaders?: readonly string[];
+    /**
+     * A leading path segment removed before the path is appended to `upstream`.
+     * A proxy mounted at `/hub/nansen` in front of `https://api.nansen.ai/api/v1`
+     * strips `/hub/nansen`, so `/hub/nansen/query` reaches `.../api/v1/query`.
+     */
+    readonly stripPrefix?: string;
+    /** Called with every result, so a Service logs which Settlement covered which request. */
+    readonly onResult?: (result: ProxyResult) => void;
+}
+/** A handler any web-standard host can mount, with the richer entry point beside it. */
+export interface TabProxy {
+    (request: Request): Promise<Response>;
+    /** The same run, returning everything the handler discards. */
+    proxy(request: Request): Promise<ProxyResult>;
+    readonly hooks: readonly ProxyHook[];
+    readonly upstream: string;
+}
+/**
+ * Builds the proxy.
+ *
+ * Construction is total, as everywhere in this package. An unusable `upstream`
+ * is reported by the first request as a 500 carrying a `VALIDATION` error, which
+ * is the first point at which anybody is listening.
+ */
+export declare function createTabProxy(options: TabProxyOptions): TabProxy;
+/**
+ * The request path and query, resolved against the upstream base.
+ *
+ * `stripPrefix`, when given, is removed from the front of the path first, and a
+ * path that does not start with it is refused rather than forwarded somewhere
+ * the mount did not intend.
+ */
+export declare function resolveUpstream(upstream: string, requestUrl: string, stripPrefix?: string): Result<string>;
+/** A `TabError` as the response it becomes: its category's status, the error as JSON. */
+export declare function errorResponse(error: TabError): Response;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy/proxy.ts"],"names":[],"mappings":"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"}

package/dist/proxy/proxy.js

@@ -0,0 +1,366 @@
+/**
+ * The proxy layer: one handler that forwards a request upstream, meters the
+ * delivery through the post-paid plugin, and runs hooks around both (R23.4).
+ *
+ * ## Order of operations, which is the whole contract
+ *
+ * ```text
+ * before hooks, in registration order
+ *   -> metering.execute( forward to upstream )
+ * after hooks, in reverse order
+ * ```
+ *
+ * The forward runs *inside* the metering plugin's `execute`, so the plugin sees
+ * the upstream's response exactly as it sees a local handler's: it records the
+ * delivery once the response exists, attaches the charge block, and replaces
+ * the response with a 402 on `LimitExceeded` alone. Nothing about the plugin's
+ * ordering guarantee changes because the handler is a network hop, and the
+ * "never withhold pending payment" rule (R23.3) is inherited rather than
+ * re-implemented here.
+ *
+ * ## Streaming
+ *
+ * The upstream response body is passed through as the stream it arrived as.
+ * Nothing here reads it, and the charge headers are attached by rebuilding the
+ * response around the same stream. A hook that needs the body must `clone()` the
+ * response and read the copy, and a hook that does so pays the buffering it
+ * asked for and nobody else does. The request body is likewise forwarded as a
+ * stream where the host `fetch` supports one.
+ *
+ * ## What is not forwarded
+ *
+ * Hop-by-hop request headers, `host`, and `content-length` are dropped before
+ * forwarding, because they describe the connection the proxy is on rather than
+ * the request. On the way back, `content-encoding`, `content-length`, and
+ * `transfer-encoding` are dropped, because the host `fetch` already decoded the
+ * body and the outbound server re-frames it; forwarding those headers would tell
+ * the caller to decode a body that is already plain.
+ *
+ * ## Failures are responses, never throws
+ *
+ * An unreachable upstream is a 502 carrying a `TabError` body. It is not a
+ * delivery, so the plugin's default `billable` predicate does not meter it. A
+ * critical hook's `err` is a response at its category's status. The handler
+ * this factory returns never rejects.
+ *
+ * Requirements: 23.4, 23.3
+ */
+import { causeOf, httpStatusOf, ok, wrap } from "../_shared/index.js";
+import { tabError } from "../errors.js";
+import { defaultLogger } from "../logger.js";
+import { jsonResponse, } from "../server/post-paid.js";
+/** Request headers that describe the hop rather than the request, per RFC 9110. */
+export const HOP_BY_HOP_HEADERS = [
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+];
+/** Response headers the host `fetch` has already acted on and the outbound server re-frames. */
+export const REFRAMED_RESPONSE_HEADERS = [
+    "content-encoding",
+    "content-length",
+    "transfer-encoding",
+    "connection",
+    "keep-alive",
+];
+/**
+ * Builds the proxy.
+ *
+ * Construction is total, as everywhere in this package. An unusable `upstream`
+ * is reported by the first request as a 500 carrying a `VALIDATION` error, which
+ * is the first point at which anybody is listening.
+ */
+export function createTabProxy(options) {
+    const logger = options.logger ?? defaultLogger;
+    const hooks = [...(options.hooks ?? [])];
+    const dropped = new Set([
+        ...HOP_BY_HOP_HEADERS,
+        "host",
+        "content-length",
+        ...(options.dropRequestHeaders ?? []).map((name) => name.toLowerCase()),
+    ]);
+    /**
+     * The forward. A failure becomes a response and is also recorded on `holder`,
+     * so the result can name the error without reading it back off the response.
+     */
+    const forward = async (request, holder) => {
+        const failed = (error) => {
+            holder.failure = error;
+            return errorResponse(error);
+        };
+        const target = resolveUpstream(options.upstream, request.url, options.stripPrefix);
+        if (!target.ok)
+            return failed(target.error);
+        const send = options.fetchImpl ?? hostFetch();
+        if (send === undefined) {
+            return failed(tabError("UPSTREAM", "FETCH_UNAVAILABLE", "this host has no global fetch; supply fetchImpl, or run on Node 20.10 or later"));
+        }
+        const headers = {};
+        request.headers.forEach((value, name) => {
+            if (!dropped.has(name.toLowerCase()))
+                headers[name] = value;
+        });
+        const bodiless = request.method === "GET" || request.method === "HEAD";
+        const body = bodiless ? undefined : request.body;
+        const signal = forwardSignal(request, options.timeoutMs);
+        const init = {
+            method: request.method,
+            headers,
+            ...(body === undefined || body === null ? {} : { body, duplex: "half" }),
+            ...(signal === undefined ? {} : { signal }),
+        };
+        const sent = await wrap(async () => send(target.value, init, request), (error) => tabError("UPSTREAM", "PROXY_UPSTREAM_UNREACHABLE", `the upstream at ${target.value} did not answer`, {
+            retryable: true,
+            details: { upstream: target.value, method: request.method },
+            cause: causeOf(error),
+        }));
+        if (!sent.ok)
+            return failed(sent.error);
+        if (!looksLikeResponse(sent.value)) {
+            return failed(tabError("UPSTREAM", "PROXY_UPSTREAM_INVALID", `the fetch given to this proxy returned something that is not a response for ${target.value}`));
+        }
+        return reframe(sent.value);
+    };
+    const proxy = async (request) => {
+        const state = new Map();
+        const failures = [];
+        const base = { request, state, logger };
+        let settlement;
+        // ---- before, in registration order
+        for (const hook of hooks) {
+            if (hook.before === undefined)
+                continue;
+            const context = { ...base, phase: "before" };
+            const outcome = await runPhase(hook, "before", context, logger);
+            if (outcome !== undefined) {
+                failures.push(outcome);
+                if (outcome.critical) {
+                    return finish({
+                        response: errorResponse(outcome.error),
+                        kind: "failed",
+                        metering: undefined,
+                        charge: undefined,
+                        settlement: context.settlement,
+                        hookFailures: failures,
+                        failure: outcome.error,
+                        state,
+                    });
+                }
+            }
+            settlement = context.settlement ?? settlement;
+        }
+        // ---- the forward, under metering
+        const holder = {};
+        const execution = await options.metering.execute(request, () => forward(request, holder));
+        let response;
+        let kind;
+        let forwardThrew;
+        let metering;
+        let outcome;
+        if (execution.kind === "handler-failed") {
+            // `forward` never throws, so this is a plugin invariant rather than a path,
+            // and it is answered the same way a throwing hook is: as an INTERNAL error.
+            forwardThrew = tabError("INTERNAL", "PROXY_FORWARD_THREW", "the forward threw where it should have returned a response", {
+                cause: causeOf(execution.thrown),
+            });
+            response = errorResponse(forwardThrew);
+            kind = "failed";
+        }
+        else if (execution.kind === "refused") {
+            response = execution.response;
+            kind = "refused";
+            outcome = execution.outcome;
+            metering = Promise.resolve(execution.outcome);
+        }
+        else {
+            response = execution.response;
+            kind = holder.failure === undefined ? "delivered" : "failed";
+            metering = execution.metering;
+            if (options.metering.release === "after-metering")
+                outcome = await execution.metering;
+        }
+        const charge = outcome?.kind === "charged" ? outcome.charge : undefined;
+        // ---- after, in reverse order
+        for (const hook of [...hooks].reverse()) {
+            if (hook.after === undefined)
+                continue;
+            const context = {
+                ...base,
+                phase: "after",
+                response,
+                ...(charge === undefined ? {} : { charge }),
+                ...(outcome === undefined ? {} : { metering: outcome }),
+                ...(settlement === undefined ? {} : { settlement }),
+            };
+            const failed = await runPhase(hook, "after", context, logger);
+            settlement = context.settlement ?? settlement;
+            if (failed !== undefined) {
+                failures.push(failed);
+                if (failed.critical) {
+                    discard(response, logger);
+                    return finish({
+                        response: errorResponse(failed.error),
+                        kind: "failed",
+                        metering,
+                        charge,
+                        settlement,
+                        hookFailures: failures,
+                        failure: failed.error,
+                        state,
+                    });
+                }
+            }
+        }
+        return finish({
+            response,
+            kind,
+            metering,
+            charge,
+            settlement,
+            hookFailures: failures,
+            failure: kind === "failed" ? (holder.failure ?? forwardThrew) : undefined,
+            state,
+        });
+    };
+    const finish = (result) => {
+        if (options.onResult !== undefined) {
+            try {
+                options.onResult(result);
+            }
+            catch (error) {
+                logger.warn("onResult threw and was ignored", causeOf(error));
+            }
+        }
+        return result;
+    };
+    const handler = async (request) => (await proxy(request)).response;
+    return Object.assign(handler, { proxy, hooks, upstream: options.upstream });
+}
+/**
+ * Runs one phase of one hook without letting it throw or reject into the proxy.
+ * Returns the failure, or undefined when the phase succeeded.
+ */
+async function runPhase(hook, phase, context, logger) {
+    const run = phase === "before" ? hook.before : hook.after;
+    if (run === undefined)
+        return undefined;
+    let result;
+    try {
+        result = await run.call(hook, context);
+    }
+    catch (error) {
+        result = { ok: false, error: tabError("INTERNAL", "HOOK_THREW", `hook ${hook.name} threw in its ${phase} phase`, { cause: causeOf(error) }) };
+    }
+    if (result.ok)
+        return undefined;
+    const critical = hook.critical === true;
+    logger[critical ? "error" : "warn"](critical ? `hook ${hook.name} failed its ${phase} phase and the request fails with it` : `hook ${hook.name} failed its ${phase} phase and was skipped`, { hook: hook.name, phase, code: result.error.code, message: result.error.message });
+    return { hook: hook.name, phase, critical, error: result.error };
+}
+/**
+ * The request path and query, resolved against the upstream base.
+ *
+ * `stripPrefix`, when given, is removed from the front of the path first, and a
+ * path that does not start with it is refused rather than forwarded somewhere
+ * the mount did not intend.
+ */
+export function resolveUpstream(upstream, requestUrl, stripPrefix) {
+    const base = safeUrl(upstream.endsWith("/") ? upstream : `${upstream}/`);
+    if (base === undefined || (base.protocol !== "http:" && base.protocol !== "https:")) {
+        return {
+            ok: false,
+            error: tabError("VALIDATION", "UPSTREAM_INVALID", `upstream \`${upstream}\` is not an absolute http or https URL`),
+        };
+    }
+    const incoming = safeUrl(requestUrl, base);
+    if (incoming === undefined) {
+        return {
+            ok: false,
+            error: tabError("VALIDATION", "REQUEST_URL_INVALID", `the request URL \`${requestUrl}\` does not parse`),
+        };
+    }
+    let pathname = incoming.pathname;
+    if (stripPrefix !== undefined && stripPrefix.length > 0) {
+        const prefix = `/${stripPrefix.replace(/^\/+|\/+$/g, "")}`;
+        if (pathname !== prefix && !pathname.startsWith(`${prefix}/`)) {
+            return {
+                ok: false,
+                error: tabError("VALIDATION", "REQUEST_PATH_OUTSIDE_MOUNT", `the request path \`${pathname}\` does not start with the mount \`${prefix}\``, {
+                    details: { path: pathname, prefix },
+                }),
+            };
+        }
+        pathname = pathname.slice(prefix.length);
+    }
+    const relative = `${pathname.replace(/^\/+/, "")}${incoming.search}`;
+    return ok(new URL(relative, base).toString());
+}
+function safeUrl(value, base) {
+    try {
+        return base === undefined ? new URL(value) : new URL(value, base);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A signal that fires on the caller's abort or on the timeout, whichever comes first. */
+function forwardSignal(request, timeoutMs) {
+    const timeout = timeoutMs === undefined ? undefined : AbortSignal.timeout(timeoutMs);
+    const caller = request.signal;
+    if (timeout === undefined)
+        return caller;
+    const any = AbortSignal.any;
+    return typeof any === "function" ? any([caller, timeout]) : timeout;
+}
+/**
+ * Rebuilds the upstream response around its own body stream, minus the headers
+ * the host `fetch` has already consumed. No byte of the body is read here.
+ */
+function reframe(upstream) {
+    const headers = new Headers();
+    upstream.headers.forEach((value, name) => {
+        if (!REFRAMED_RESPONSE_HEADERS.includes(name.toLowerCase()))
+            headers.append(name, value);
+    });
+    return new Response(upstream.body, {
+        status: upstream.status,
+        statusText: upstream.statusText,
+        headers,
+    });
+}
+/** A `TabError` as the response it becomes: its category's status, the error as JSON. */
+export function errorResponse(error) {
+    return jsonResponse(httpStatusOf(error), {}, { ok: false, error });
+}
+function looksLikeResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.status === "number" && typeof candidate.headers === "object" && candidate.headers !== null;
+}
+/** Releases a response that is not going out, so its connection does not wait for the collector. */
+function discard(response, logger) {
+    const body = response.body;
+    if (body === null || response.bodyUsed)
+        return;
+    try {
+        body.cancel().catch((error) => {
+            logger.debug("discarded response body could not be cancelled", causeOf(error));
+        });
+    }
+    catch (error) {
+        logger.debug("discarded response body could not be cancelled", causeOf(error));
+    }
+}
+/** The host's global `fetch`, behind a runtime check so its absence is an error and not a TypeError. */
+function hostFetch() {
+    const candidate = globalThis.fetch;
+    return typeof candidate === "function" ? candidate : undefined;
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/proxy/proxy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The proxy layer: one handler that forwards a request upstream, meters the\n * delivery through the post-paid plugin, and runs hooks around both (R23.4).\n *\n * ## Order of operations, which is the whole contract\n *\n * ```text\n * before hooks, in registration order\n *   -> metering.execute( forward to upstream )\n * after hooks, in reverse order\n * ```\n *\n * The forward runs *inside* the metering plugin's `execute`, so the plugin sees\n * the upstream's response exactly as it sees a local handler's: it records the\n * delivery once the response exists, attaches the charge block, and replaces\n * the response with a 402 on `LimitExceeded` alone. Nothing about the plugin's\n * ordering guarantee changes because the handler is a network hop, and the\n * \"never withhold pending payment\" rule (R23.3) is inherited rather than\n * re-implemented here.\n *\n * ## Streaming\n *\n * The upstream response body is passed through as the stream it arrived as.\n * Nothing here reads it, and the charge headers are attached by rebuilding the\n * response around the same stream. A hook that needs the body must `clone()` the\n * response and read the copy, and a hook that does so pays the buffering it\n * asked for and nobody else does. The request body is likewise forwarded as a\n * stream where the host `fetch` supports one.\n *\n * ## What is not forwarded\n *\n * Hop-by-hop request headers, `host`, and `content-length` are dropped before\n * forwarding, because they describe the connection the proxy is on rather than\n * the request. On the way back, `content-encoding`, `content-length`, and\n * `transfer-encoding` are dropped, because the host `fetch` already decoded the\n * body and the outbound server re-frames it; forwarding those headers would tell\n * the caller to decode a body that is already plain.\n *\n * ## Failures are responses, never throws\n *\n * An unreachable upstream is a 502 carrying a `TabError` body. It is not a\n * delivery, so the plugin's default `billable` predicate does not meter it. A\n * critical hook's `err` is a response at its category's status. The handler\n * this factory returns never rejects.\n *\n * Requirements: 23.4, 23.3\n */\n\nimport { causeOf, httpStatusOf, ok, wrap, type Result, type TabError } from \"../_shared/index.js\";\n\nimport { tabError } from \"../errors.js\";\nimport { defaultLogger, type Logger } from \"../logger.js\";\nimport {\n  jsonResponse,\n  type MeteredCharge,\n  type MeteringOutcome,\n  type PostPaidPlugin,\n} from \"../server/post-paid.js\";\nimport type { ProxyHook, ProxyHookContext, ProxyPhase } from \"./hooks.js\";\nimport type { SettlementView } from \"./hooks.js\";\n\n/** Request headers that describe the hop rather than the request, per RFC 9110. */\nexport const HOP_BY_HOP_HEADERS: readonly string[] = [\n  \"connection\",\n  \"keep-alive\",\n  \"proxy-authenticate\",\n  \"proxy-authorization\",\n  \"proxy-connection\",\n  \"te\",\n  \"trailer\",\n  \"transfer-encoding\",\n  \"upgrade\",\n];\n\n/** Response headers the host `fetch` has already acted on and the outbound server re-frames. */\nexport const REFRAMED_RESPONSE_HEADERS: readonly string[] = [\n  \"content-encoding\",\n  \"content-length\",\n  \"transfer-encoding\",\n  \"connection\",\n  \"keep-alive\",\n];\n\n/** The forward this proxy hands to its `fetch`. Structural, like `client-402.ts`. */\nexport interface ProxyForwardInit {\n  readonly method: string;\n  readonly headers: Readonly<Record<string, string>>;\n  /** The request body stream, or undefined for a bodiless method. */\n  readonly body?: unknown;\n  /** Required by the host `fetch` to send a streamed request body. */\n  readonly duplex?: \"half\";\n  readonly signal?: AbortSignal;\n}\n\n/**\n * The `fetch` the proxy forwards with. The host's global `fetch` is the default.\n *\n * The third argument is the request as it reached the proxy, the same object\n * the metering plugin later hands to `priceOf`. A forward that learns the price\n * on the way, the x402-fronting one does, keys what it learned by it. The host\n * `fetch` and every existing two-argument `fetchImpl` ignore it.\n */\nexport type ProxyFetch = (url: string, init: ProxyForwardInit, request: Request) => Promise<Response>;\n\n/** One hook phase that returned an error or threw, in the order it happened. */\nexport interface HookFailure {\n  readonly hook: string;\n  readonly phase: ProxyPhase;\n  readonly critical: boolean;\n  readonly error: TabError;\n}\n\nexport interface ProxyResult {\n  /** The response that goes out. */\n  readonly response: Response;\n  /**\n   * `delivered`: the upstream's response, metered or not. `refused`: the metering\n   * plugin replaced it, which is `LimitExceeded` and the two Agent-side refusals\n   * only. `failed`: a critical hook or the forward itself failed.\n   */\n  readonly kind: \"delivered\" | \"refused\" | \"failed\";\n  /**\n   * Resolves once the delivery is recorded. Already resolved under the plugin's\n   * default `after-metering`; still pending under `before-metering`, where a\n   * host with a request lifetime hook passes it there.\n   */\n  readonly metering: Promise<MeteringOutcome> | undefined;\n  /** The recorded charge, when the outcome was known before the hooks ran. */\n  readonly charge: MeteredCharge | undefined;\n  /** The Settlement a hook attached (R23.5). */\n  readonly settlement: SettlementView | undefined;\n  /** Every hook failure, critical or not. */\n  readonly hookFailures: readonly HookFailure[];\n  /** The error that produced a `failed` result. */\n  readonly failure: TabError | undefined;\n  /** The shared scratch the hooks used, for a Service that wants to log it. */\n  readonly state: ReadonlyMap<string, unknown>;\n}\n\nexport interface TabProxyOptions {\n  /** Absolute base URL of the service being fronted. The request path and query are appended. */\n  readonly upstream: string;\n  readonly hooks?: readonly ProxyHook[];\n  /** The post-paid plugin of `server/post-paid.ts`. Metering runs on every request. */\n  readonly metering: PostPaidPlugin;\n  readonly fetchImpl?: ProxyFetch;\n  readonly logger?: Logger;\n  /** Aborts the forward after this long. No timeout when omitted. */\n  readonly timeoutMs?: number;\n  /** Request headers dropped before forwarding, on top of the hop-by-hop set and `host`. */\n  readonly dropRequestHeaders?: readonly string[];\n  /**\n   * A leading path segment removed before the path is appended to `upstream`.\n   * A proxy mounted at `/hub/nansen` in front of `https://api.nansen.ai/api/v1`\n   * strips `/hub/nansen`, so `/hub/nansen/query` reaches `.../api/v1/query`.\n   */\n  readonly stripPrefix?: string;\n  /** Called with every result, so a Service logs which Settlement covered which request. */\n  readonly onResult?: (result: ProxyResult) => void;\n}\n\n/** A handler any web-standard host can mount, with the richer entry point beside it. */\nexport interface TabProxy {\n  (request: Request): Promise<Response>;\n  /** The same run, returning everything the handler discards. */\n  proxy(request: Request): Promise<ProxyResult>;\n  readonly hooks: readonly ProxyHook[];\n  readonly upstream: string;\n}\n\n/**\n * Builds the proxy.\n *\n * Construction is total, as everywhere in this package. An unusable `upstream`\n * is reported by the first request as a 500 carrying a `VALIDATION` error, which\n * is the first point at which anybody is listening.\n */\nexport function createTabProxy(options: TabProxyOptions): TabProxy {\n  const logger = options.logger ?? defaultLogger;\n  const hooks = [...(options.hooks ?? [])];\n  const dropped = new Set([\n    ...HOP_BY_HOP_HEADERS,\n    \"host\",\n    \"content-length\",\n    ...(options.dropRequestHeaders ?? []).map((name) => name.toLowerCase()),\n  ]);\n\n  /**\n   * The forward. A failure becomes a response and is also recorded on `holder`,\n   * so the result can name the error without reading it back off the response.\n   */\n  const forward = async (request: Request, holder: { failure?: TabError }): Promise<Response> => {\n    const failed = (error: TabError): Response => {\n      holder.failure = error;\n      return errorResponse(error);\n    };\n    const target = resolveUpstream(options.upstream, request.url, options.stripPrefix);\n    if (!target.ok) return failed(target.error);\n\n    const send = options.fetchImpl ?? hostFetch();\n    if (send === undefined) {\n      return failed(\n        tabError(\"UPSTREAM\", \"FETCH_UNAVAILABLE\", \"this host has no global fetch; supply fetchImpl, or run on Node 20.10 or later\"),\n      );\n    }\n\n    const headers: Record<string, string> = {};\n    request.headers.forEach((value, name) => {\n      if (!dropped.has(name.toLowerCase())) headers[name] = value;\n    });\n\n    const bodiless = request.method === \"GET\" || request.method === \"HEAD\";\n    const body = bodiless ? undefined : request.body;\n    const signal = forwardSignal(request, options.timeoutMs);\n    const init: ProxyForwardInit = {\n      method: request.method,\n      headers,\n      ...(body === undefined || body === null ? {} : { body, duplex: \"half\" as const }),\n      ...(signal === undefined ? {} : { signal }),\n    };\n\n    const sent = await wrap(\n      async () => send(target.value, init, request),\n      (error) =>\n        tabError(\"UPSTREAM\", \"PROXY_UPSTREAM_UNREACHABLE\", `the upstream at ${target.value} did not answer`, {\n          retryable: true,\n          details: { upstream: target.value, method: request.method },\n          cause: causeOf(error),\n        }),\n    );\n    if (!sent.ok) return failed(sent.error);\n    if (!looksLikeResponse(sent.value)) {\n      return failed(\n        tabError(\"UPSTREAM\", \"PROXY_UPSTREAM_INVALID\", `the fetch given to this proxy returned something that is not a response for ${target.value}`),\n      );\n    }\n    return reframe(sent.value);\n  };\n\n  const proxy = async (request: Request): Promise<ProxyResult> => {\n    const state = new Map<string, unknown>();\n    const failures: HookFailure[] = [];\n    const base = { request, state, logger } as const;\n    let settlement: SettlementView | undefined;\n\n    // ---- before, in registration order\n    for (const hook of hooks) {\n      if (hook.before === undefined) continue;\n      const context: ProxyHookContext = { ...base, phase: \"before\" };\n      const outcome = await runPhase(hook, \"before\", context, logger);\n      if (outcome !== undefined) {\n        failures.push(outcome);\n        if (outcome.critical) {\n          return finish({\n            response: errorResponse(outcome.error),\n            kind: \"failed\",\n            metering: undefined,\n            charge: undefined,\n            settlement: context.settlement,\n            hookFailures: failures,\n            failure: outcome.error,\n            state,\n          });\n        }\n      }\n      settlement = context.settlement ?? settlement;\n    }\n\n    // ---- the forward, under metering\n    const holder: { failure?: TabError } = {};\n    const execution = await options.metering.execute(request, () => forward(request, holder));\n\n    let response: Response;\n    let kind: ProxyResult[\"kind\"];\n    let forwardThrew: TabError | undefined;\n    let metering: Promise<MeteringOutcome> | undefined;\n    let outcome: MeteringOutcome | undefined;\n    if (execution.kind === \"handler-failed\") {\n      // `forward` never throws, so this is a plugin invariant rather than a path,\n      // and it is answered the same way a throwing hook is: as an INTERNAL error.\n      forwardThrew = tabError(\"INTERNAL\", \"PROXY_FORWARD_THREW\", \"the forward threw where it should have returned a response\", {\n        cause: causeOf(execution.thrown),\n      });\n      response = errorResponse(forwardThrew);\n      kind = \"failed\";\n    } else if (execution.kind === \"refused\") {\n      response = execution.response;\n      kind = \"refused\";\n      outcome = execution.outcome;\n      metering = Promise.resolve(execution.outcome);\n    } else {\n      response = execution.response;\n      kind = holder.failure === undefined ? \"delivered\" : \"failed\";\n      metering = execution.metering;\n      if (options.metering.release === \"after-metering\") outcome = await execution.metering;\n    }\n    const charge = outcome?.kind === \"charged\" ? outcome.charge : undefined;\n\n    // ---- after, in reverse order\n    for (const hook of [...hooks].reverse()) {\n      if (hook.after === undefined) continue;\n      const context: ProxyHookContext = {\n        ...base,\n        phase: \"after\",\n        response,\n        ...(charge === undefined ? {} : { charge }),\n        ...(outcome === undefined ? {} : { metering: outcome }),\n        ...(settlement === undefined ? {} : { settlement }),\n      };\n      const failed = await runPhase(hook, \"after\", context, logger);\n      settlement = context.settlement ?? settlement;\n      if (failed !== undefined) {\n        failures.push(failed);\n        if (failed.critical) {\n          discard(response, logger);\n          return finish({\n            response: errorResponse(failed.error),\n            kind: \"failed\",\n            metering,\n            charge,\n            settlement,\n            hookFailures: failures,\n            failure: failed.error,\n            state,\n          });\n        }\n      }\n    }\n\n    return finish({\n      response,\n      kind,\n      metering,\n      charge,\n      settlement,\n      hookFailures: failures,\n      failure: kind === \"failed\" ? (holder.failure ?? forwardThrew) : undefined,\n      state,\n    });\n  };\n\n  const finish = (result: ProxyResult): ProxyResult => {\n    if (options.onResult !== undefined) {\n      try {\n        options.onResult(result);\n      } catch (error) {\n        logger.warn(\"onResult threw and was ignored\", causeOf(error));\n      }\n    }\n    return result;\n  };\n\n  const handler = async (request: Request): Promise<Response> => (await proxy(request)).response;\n  return Object.assign(handler, { proxy, hooks, upstream: options.upstream });\n}\n\n/**\n * Runs one phase of one hook without letting it throw or reject into the proxy.\n * Returns the failure, or undefined when the phase succeeded.\n */\nasync function runPhase(\n  hook: ProxyHook,\n  phase: ProxyPhase,\n  context: ProxyHookContext,\n  logger: Logger,\n): Promise<HookFailure | undefined> {\n  const run = phase === \"before\" ? hook.before : hook.after;\n  if (run === undefined) return undefined;\n  let result: Result<void>;\n  try {\n    result = await run.call(hook, context);\n  } catch (error) {\n    result = { ok: false, error: tabError(\"INTERNAL\", \"HOOK_THREW\", `hook ${hook.name} threw in its ${phase} phase`, { cause: causeOf(error) }) };\n  }\n  if (result.ok) return undefined;\n  const critical = hook.critical === true;\n  logger[critical ? \"error\" : \"warn\"](\n    critical ? `hook ${hook.name} failed its ${phase} phase and the request fails with it` : `hook ${hook.name} failed its ${phase} phase and was skipped`,\n    { hook: hook.name, phase, code: result.error.code, message: result.error.message },\n  );\n  return { hook: hook.name, phase, critical, error: result.error };\n}\n\n/**\n * The request path and query, resolved against the upstream base.\n *\n * `stripPrefix`, when given, is removed from the front of the path first, and a\n * path that does not start with it is refused rather than forwarded somewhere\n * the mount did not intend.\n */\nexport function resolveUpstream(upstream: string, requestUrl: string, stripPrefix?: string): Result<string> {\n  const base = safeUrl(upstream.endsWith(\"/\") ? upstream : `${upstream}/`);\n  if (base === undefined || (base.protocol !== \"http:\" && base.protocol !== \"https:\")) {\n    return {\n      ok: false,\n      error: tabError(\"VALIDATION\", \"UPSTREAM_INVALID\", `upstream \\`${upstream}\\` is not an absolute http or https URL`),\n    };\n  }\n  const incoming = safeUrl(requestUrl, base);\n  if (incoming === undefined) {\n    return {\n      ok: false,\n      error: tabError(\"VALIDATION\", \"REQUEST_URL_INVALID\", `the request URL \\`${requestUrl}\\` does not parse`),\n    };\n  }\n  let pathname = incoming.pathname;\n  if (stripPrefix !== undefined && stripPrefix.length > 0) {\n    const prefix = `/${stripPrefix.replace(/^\\/+|\\/+$/g, \"\")}`;\n    if (pathname !== prefix && !pathname.startsWith(`${prefix}/`)) {\n      return {\n        ok: false,\n        error: tabError(\"VALIDATION\", \"REQUEST_PATH_OUTSIDE_MOUNT\", `the request path \\`${pathname}\\` does not start with the mount \\`${prefix}\\``, {\n          details: { path: pathname, prefix },\n        }),\n      };\n    }\n    pathname = pathname.slice(prefix.length);\n  }\n  const relative = `${pathname.replace(/^\\/+/, \"\")}${incoming.search}`;\n  return ok(new URL(relative, base).toString());\n}\n\nfunction safeUrl(value: string, base?: URL): URL | undefined {\n  try {\n    return base === undefined ? new URL(value) : new URL(value, base);\n  } catch {\n    return undefined;\n  }\n}\n\n/** A signal that fires on the caller's abort or on the timeout, whichever comes first. */\nfunction forwardSignal(request: Request, timeoutMs: number | undefined): AbortSignal | undefined {\n  const timeout = timeoutMs === undefined ? undefined : AbortSignal.timeout(timeoutMs);\n  const caller = request.signal;\n  if (timeout === undefined) return caller;\n  const any = (AbortSignal as { any?: (signals: AbortSignal[]) => AbortSignal }).any;\n  return typeof any === \"function\" ? any([caller, timeout]) : timeout;\n}\n\n/**\n * Rebuilds the upstream response around its own body stream, minus the headers\n * the host `fetch` has already consumed. No byte of the body is read here.\n */\nfunction reframe(upstream: Response): Response {\n  const headers = new Headers();\n  upstream.headers.forEach((value, name) => {\n    if (!REFRAMED_RESPONSE_HEADERS.includes(name.toLowerCase())) headers.append(name, value);\n  });\n  return new Response(upstream.body, {\n    status: upstream.status,\n    statusText: upstream.statusText,\n    headers,\n  });\n}\n\n/** A `TabError` as the response it becomes: its category's status, the error as JSON. */\nexport function errorResponse(error: TabError): Response {\n  return jsonResponse(httpStatusOf(error), {}, { ok: false, error });\n}\n\nfunction looksLikeResponse(value: unknown): value is Response {\n  if (typeof value !== \"object\" || value === null) return false;\n  const candidate = value as { status?: unknown; headers?: unknown };\n  return typeof candidate.status === \"number\" && typeof candidate.headers === \"object\" && candidate.headers !== null;\n}\n\n/** Releases a response that is not going out, so its connection does not wait for the collector. */\nfunction discard(response: Response, logger: Logger): void {\n  const body = response.body;\n  if (body === null || response.bodyUsed) return;\n  try {\n    body.cancel().catch((error: unknown) => {\n      logger.debug(\"discarded response body could not be cancelled\", causeOf(error));\n    });\n  } catch (error) {\n    logger.debug(\"discarded response body could not be cancelled\", causeOf(error));\n  }\n}\n\n/** The host's global `fetch`, behind a runtime check so its absence is an error and not a TypeError. */\nfunction hostFetch(): ProxyFetch | undefined {\n  const candidate = (globalThis as { fetch?: unknown }).fetch;\n  return typeof candidate === \"function\" ? (candidate as ProxyFetch) : undefined;\n}\n"]}