mppx 0.16.0 → 0.17.1

package/dist/proxy/Proxy.js

@@ -4,6 +4,7 @@ import * as Scope from '../server/internal/scope.js';
 import * as Mppx from '../server/Mppx.js';
 import * as Request from '../server/Request.js';
 import * as Headers from './internal/Headers.js';
+import * as Replay from './internal/Replay.js';
 import * as Route from './internal/Route.js';
 import * as Service from './Service.js';
 /**
@@ -34,6 +35,7 @@ import * as Service from './Service.js';
  */
 export function create(config) {
     const fetchImpl = config.fetch ?? globalThis.fetch;
+    const replay = config.replay ? Replay.resolve(config.replay) : undefined;
     const services = new Map(config.services.map((s) => {
         const proxy = createFetchProxy(s.baseUrl, { fetch: fetchImpl });
         return [s.id, { service: s, proxy }];
@@ -108,13 +110,59 @@ export function create(config) {
                 proxy,
                 onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
             });
+        // With replay, a paid request whose credential already paid for this exact
+        // request collects its recorded delivery instead of paying again.
+        let paidRequest = request;
+        let replayBody;
+        let replayKey;
+        // Routes with identity verifiers keep paying normally: a replay would skip them.
+        const credential = replay && !fallbackMatch && !requiresIdentity(handler)
+            ? Replay.credentialOf(request, credentialHeaders(handler))
+            : undefined;
+        if (replay && credential) {
+            const body = await Replay.readBody(request, replay.maxRequestBodySize);
+            if (!body)
+                return new Response('Payload Too Large', { status: 413 });
+            replayBody = body;
+            paidRequest = Replay.withBody(request, body);
+            replayKey = Replay.key({
+                body,
+                credential,
+                method: request.method,
+                target: url.origin + url.pathname + url.search,
+            });
+            const found = await Replay.lookup(replay, replayKey);
+            if (found.type === 'respond')
+                return found.response;
+            if (found.type === 'retry') {
+                const options = Service.getOptions(endpoint);
+                return Replay.deliver({
+                    applyReceipt: (response) => Replay.withReceiptHeader(response, found.receipt),
+                    attempts: found.attempts,
+                    replay,
+                    replayKey,
+                    requestHeaders: found.requestHeaders,
+                    run: (signal) => {
+                        // Send the headers of the request that was paid for, not the retry's.
+                        const upstream = Replay.withBody(paidRequest, body, signal, found.requestHeaders);
+                        return proxyUpstream({
+                            request: upstream,
+                            service,
+                            ctx: { ...ctx, request: upstream, ...options },
+                            proxy,
+                            onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+                        });
+                    },
+                });
+            }
+        }
         const scope = getConfiguredScope(handler) ??
             deriveRouteScope({
                 basePath: config.basePath,
                 routeKey: matched.key,
                 serviceId,
             });
-        const result = await handler(getConfiguredScope(handler) ? request : Scope.attach(request, scope));
+        const result = await handler(getConfiguredScope(handler) ? paidRequest : Scope.attach(paidRequest, scope));
         if (result.status === 402)
             return result.challenge;
         const managementResponse = (() => {
@@ -132,6 +180,26 @@ export function create(config) {
         if (fallbackMatch)
             return new Response('Method Not Allowed', { status: 405 });
         const options = Service.getOptions(endpoint);
+        if (replay && replayKey && replayBody) {
+            const body = replayBody;
+            return Replay.deliver({
+                applyReceipt: (response) => result.withReceipt(response),
+                attempts: 1,
+                replay,
+                replayKey,
+                requestHeaders: [...Headers.scrub(paidRequest.headers).entries()],
+                run: (signal) => {
+                    const upstream = Replay.withBody(paidRequest, body, signal);
+                    return proxyUpstream({
+                        request: upstream,
+                        service,
+                        ctx: { ...ctx, request: upstream, ...options },
+                        proxy,
+                        onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+                    });
+                },
+            });
+        }
         const upstreamRes = await proxyUpstream({
             request,
             service,
@@ -284,6 +352,26 @@ function buildDiscoveryRoutes(services) {
         };
     }));
 }
+/** Headers the handler reads Payment credentials from, lowercased (Authorization by default). */
+function credentialHeaders(handler) {
+    const internal = ('_internal' in handler ? handler._internal : undefined);
+    const headers = internal?.offers
+        ? internal.offers.flatMap((offer) => offer.credentialHeaders ?? [])
+        : (internal?.credentialHeaders ?? []);
+    const names = [...new Set(headers.map((header) => header.toLowerCase()))];
+    return names.length > 0 ? names : ['authorization'];
+}
+/** Whether a paid handler, or any offer of a composed one, requires identity verifiers. */
+function requiresIdentity(handler) {
+    if (!('_internal' in handler))
+        return false;
+    const internal = handler._internal;
+    if (!internal)
+        return false;
+    if (internal.offers)
+        return internal.offers.some((offer) => offer._identity);
+    return internal._identity === true;
+}
 function getConfiguredScope(handler) {
     if (!('_internal' in handler))
         return undefined;

package/dist/proxy/internal/Replay.d.ts

@@ -0,0 +1,105 @@
+import type * as Store from '../../Store.js';
+/** Options for replaying paid proxy deliveries. */
+export type Options = {
+    /**
+     * Upstream attempts per credential, including the first, before a retry gets `502`.
+     * A retry after a failed delivery (an upstream error, a 5xx or a body that broke
+     * off) sends the paid request upstream again without charging, so a
+     * non-idempotent upstream may run the operation twice; set `1` to only ever
+     * replay a recorded response. @default 3
+     */
+    maxAttempts?: number | undefined;
+    /** Largest response body, in bytes, kept for replay. Larger or streamed bodies are delivered but not kept. @default 1_048_576 */
+    maxBodySize?: number | undefined;
+    /** Largest request body, in bytes, a paid request may carry; larger ones get `413`. @default 1_048_576 */
+    maxRequestBodySize?: number | undefined;
+    /** `Retry-After` seconds returned while a delivery is still in flight. @default 5 */
+    retryAfter?: number | undefined;
+    /** Atomic store shared by every proxy instance that may receive a retry. */
+    store: Store.AtomicStore;
+    /**
+     * How long to wait for the upstream to start responding, and how long its outcome is kept after it is
+     * recorded, in milliseconds. Expired records are removed when they are next
+     * looked up, as with mppx's replay markers; give the backing store its own
+     * key expiry to reclaim records nobody retries. @default 900_000
+     */
+    ttl?: number | undefined;
+    /** Keeps background work alive after the response returns, such as Cloudflare's `ctx.waitUntil`. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined;
+};
+/** Replay options with defaults applied. */
+export type Resolved = {
+    maxAttempts: number;
+    maxBodySize: number;
+    maxRequestBodySize: number;
+    retryAfter: number;
+    store: Store.AtomicStore;
+    ttl: number;
+    waitUntil: ((promise: Promise<unknown>) => void) | undefined;
+};
+/** A delivery record, keyed by credential and request. */
+export type Record = {
+    attempts: number;
+    expires: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    status: 'pending';
+} | {
+    attempts: number;
+    expires: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    status: 'failed';
+} | {
+    expires: number;
+    status: 'delivered';
+} | {
+    body: string;
+    expires: number;
+    headers: [string, string][];
+    responseStatus: number;
+    status: 'complete';
+    statusText: string;
+};
+/** Applies defaults to replay options. */
+export declare function resolve(options: Options): Resolved;
+/** Returns the request's Payment credential header value, if it carries one. */
+export declare function credentialOf(request: Request, headerNames?: readonly string[]): string | undefined;
+/** Reads a request body, or returns null when it is larger than maxRequestBodySize. */
+export declare function readBody(request: Request, maxRequestBodySize: number): Promise<Uint8Array<ArrayBuffer> | null>;
+/** Derives the replay key from the credential and the exact request (origin, path, query, method, body) it paid for. */
+export declare function key(parameters: {
+    body: Uint8Array;
+    credential: string;
+    method: string;
+    target: string;
+}): string;
+/** Rebuilds a request around an already-read body, optionally with another abort signal. */
+export declare function withBody(request: Request, body: Uint8Array, signal?: AbortSignal, headers?: HeadersInit): Request;
+/** What a request with a known credential should do. */
+export type Lookup = {
+    type: 'none';
+} | {
+    response: Response;
+    type: 'respond';
+} | {
+    attempts: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    type: 'retry';
+};
+/** Looks up a delivery and, for a failed one, claims the next upstream attempt. */
+export declare function lookup(replay: Resolved, replayKey: string): Promise<Lookup>;
+/** Runs a paid upstream delivery detached from the client and records its outcome. */
+export declare function deliver(parameters: {
+    applyReceipt: (response: Response) => Response | Promise<Response>;
+    attempts: number;
+    replay: Resolved;
+    replayKey: string;
+    /** The upstream headers of the paid request; a retried delivery reuses them. */
+    requestHeaders: [string, string][];
+    run: (signal: AbortSignal) => Promise<Response>;
+}): Promise<Response>;
+/** Adds a stored receipt to a response built for a retried delivery. */
+export declare function withReceiptHeader(response: Response, receipt: string | null): Response;
+//# sourceMappingURL=Replay.d.ts.map

package/dist/proxy/internal/Replay.js

@@ -0,0 +1,257 @@
+import { Base64, Bytes, Hash } from 'ox';
+import * as Credential from '../../Credential.js';
+const keyPrefix = 'mppx:proxy:replay:';
+/** Applies defaults to replay options. */
+export function resolve(options) {
+    const ttl = options.ttl ?? 900_000;
+    // AbortSignal.timeout needs a positive integer that fits a 32-bit timer.
+    if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > 2_147_483_647)
+        throw new RangeError('replay.ttl must be a positive integer number of milliseconds up to 2147483647.');
+    return {
+        maxAttempts: options.maxAttempts ?? 3,
+        maxBodySize: options.maxBodySize ?? 1_048_576,
+        maxRequestBodySize: options.maxRequestBodySize ?? 1_048_576,
+        retryAfter: options.retryAfter ?? 5,
+        store: options.store,
+        ttl,
+        waitUntil: options.waitUntil,
+    };
+}
+/** Returns the request's Payment credential header value, if it carries one. */
+export function credentialOf(request, headerNames = ['authorization']) {
+    // Only the headers the route's payment handler verifies can name a replay.
+    for (const name of headerNames) {
+        const header = request.headers.get(name);
+        const payment = header ? Credential.extractPaymentScheme(header) : null;
+        if (payment)
+            return payment;
+    }
+    return undefined;
+}
+/** Reads a request body, or returns null when it is larger than maxRequestBodySize. */
+export async function readBody(request, maxRequestBodySize) {
+    const length = Number(request.headers.get('content-length'));
+    if (Number.isFinite(length) && length > maxRequestBodySize)
+        return null;
+    if (!request.body)
+        return new Uint8Array();
+    return keep(request.body, maxRequestBodySize);
+}
+/** Derives the replay key from the credential and the exact request (origin, path, query, method, body) it paid for. */
+export function key(parameters) {
+    const bodyHash = Hash.sha256(parameters.body, { as: 'Hex' });
+    const input = JSON.stringify([
+        parameters.credential,
+        parameters.method.toUpperCase(),
+        parameters.target,
+        bodyHash,
+    ]);
+    return keyPrefix + Hash.sha256(Bytes.fromString(input), { as: 'Hex' }).slice(2);
+}
+/** Rebuilds a request around an already-read body, optionally with another abort signal. */
+export function withBody(request, body, signal, headers) {
+    const method = request.method.toUpperCase();
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    return new globalThis.Request(request.url, {
+        // An empty body stays absent, as on the original request: payment
+        // transports tell management requests apart by a missing body.
+        body: hasBody && body.byteLength > 0 ? body : null,
+        headers: headers ?? request.headers,
+        method: request.method,
+        redirect: request.redirect,
+        signal: signal ?? request.signal,
+    });
+}
+/** Looks up a delivery and, for a failed one, claims the next upstream attempt. */
+export async function lookup(replay, replayKey) {
+    const now = Date.now();
+    // Read first: only a failed delivery needs an atomic claim, so unknown
+    // credentials never cause a store write.
+    const seen = (await replay.store.get(replayKey));
+    if (!seen)
+        return { type: 'none' };
+    if (seen.expires > now && seen.status !== 'failed')
+        return { response: respond(replay, seen), type: 'respond' };
+    const result = await replay.store.update(replayKey, (current) => {
+        const record = current;
+        if (!record)
+            return { op: 'noop', result: { type: 'none' } };
+        if (record.expires <= now)
+            return { op: 'delete', result: { type: 'none' } };
+        if (record.status !== 'failed' || record.attempts >= replay.maxAttempts)
+            return { op: 'noop', result: record };
+        const attempts = record.attempts + 1;
+        return {
+            op: 'set',
+            value: { ...record, attempts, status: 'pending' },
+            result: {
+                attempts,
+                receipt: record.receipt,
+                requestHeaders: record.requestHeaders,
+                type: 'retry',
+            },
+        };
+    });
+    if ('type' in result)
+        return result;
+    return { response: respond(replay, result), type: 'respond' };
+}
+/** Builds the response for a recorded delivery that is not retried. */
+function respond(replay, record) {
+    if (record.status === 'complete')
+        return fromRecord(record);
+    if (record.status === 'delivered')
+        return Response.json({ error: 'The paid response was delivered and is not stored for replay.' }, { status: 410 });
+    if (record.status === 'pending')
+        return new Response(null, {
+            headers: { 'Retry-After': String(replay.retryAfter) },
+            status: 202,
+        });
+    return withReceiptHeader(Response.json({ error: 'The paid upstream request failed.' }, { status: 502 }), record.receipt);
+}
+/** Runs a paid upstream delivery detached from the client and records its outcome. */
+export async function deliver(parameters) {
+    const { applyReceipt, attempts, replay, replayKey, requestHeaders } = parameters;
+    // Outcomes are kept for ttl from when they are recorded, not from the start.
+    const expires = () => Date.now() + replay.ttl;
+    await record(replay, replayKey, {
+        attempts,
+        expires: expires(),
+        receipt: null,
+        requestHeaders,
+        status: 'pending',
+    });
+    let response;
+    try {
+        // ttl bounds the wait for the upstream to respond, not how long its body
+        // streams: a paid stream keeps going once it has started.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException('Replay ttl elapsed.', 'TimeoutError')), replay.ttl);
+        let upstream;
+        try {
+            upstream = await parameters.run(controller.signal);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        response = await applyReceipt(upstream);
+    }
+    catch {
+        const failed = await applyReceipt(Response.json({ error: 'The paid upstream request failed.' }, { status: 502 }));
+        await recordFailure(replay, replayKey, attempts, requestHeaders, expires(), failed.headers.get('Payment-Receipt'));
+        return failed;
+    }
+    const receipt = response.headers.get('Payment-Receipt');
+    if (response.status >= 500) {
+        await recordFailure(replay, replayKey, attempts, requestHeaders, expires(), receipt);
+        return response;
+    }
+    if (!response.body) {
+        await record(replay, replayKey, toRecord(response, new Uint8Array(), expires()));
+        return response;
+    }
+    if (/^text\/event-stream/i.test(response.headers.get('content-type') ?? '')) {
+        await record(replay, replayKey, { expires: expires(), status: 'delivered' });
+        return response;
+    }
+    // Keep a copy while the client reads the other branch, so a client that
+    // disconnects mid-body can still collect the response on retry.
+    const [client, kept] = response.body.tee();
+    const stored = keep(kept, replay.maxBodySize)
+        .then((body) => replay.store.put(replayKey, body
+        ? toRecord(response, body, expires())
+        : { expires: expires(), status: 'delivered' }), 
+    // The upstream body broke off: let the payer retry the delivery.
+    () => recordFailure(replay, replayKey, attempts, requestHeaders, expires(), receipt))
+        // A failed background write leaves the record pending until it expires.
+        .catch(() => { });
+    replay.waitUntil?.(stored);
+    return new Response(client, {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+    });
+}
+/** Reads a body branch up to maxBodySize, or returns null when it is larger. */
+async function keep(stream, maxBodySize) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBodySize) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+/**
+ * Writes a replay record without letting a store failure break the paid
+ * delivery: the payer still gets the upstream response, only replay is lost.
+ */
+async function record(replay, replayKey, value) {
+    try {
+        await replay.store.put(replayKey, value);
+    }
+    catch { }
+}
+async function recordFailure(replay, replayKey, attempts, requestHeaders, expires, receipt) {
+    await record(replay, replayKey, {
+        attempts,
+        expires,
+        receipt,
+        requestHeaders,
+        status: 'failed',
+    });
+}
+/** Adds a stored receipt to a response built for a retried delivery. */
+export function withReceiptHeader(response, receipt) {
+    if (!receipt)
+        return response;
+    const headers = new Headers(response.headers);
+    headers.set('Payment-Receipt', receipt);
+    headers.set('Cache-Control', withPrivateCacheControl(headers.get('Cache-Control')));
+    return new Response(response.body, {
+        headers,
+        status: response.status,
+        statusText: response.statusText,
+    });
+}
+function withPrivateCacheControl(value) {
+    if (!value)
+        return 'private';
+    const directives = value.split(',').map((directive) => directive.trim().toLowerCase());
+    if (directives.includes('private'))
+        return value;
+    return `${value}, private`;
+}
+function toRecord(response, body, expires) {
+    return {
+        body: Base64.fromBytes(body),
+        expires,
+        headers: [...response.headers.entries()],
+        responseStatus: response.status,
+        status: 'complete',
+        statusText: response.statusText,
+    };
+}
+function fromRecord(record) {
+    const nullBody = [101, 204, 205, 304].includes(record.responseStatus);
+    return new Response(nullBody ? null : Base64.toBytes(record.body), {
+        headers: record.headers,
+        status: record.responseStatus,
+        statusText: record.statusText,
+    });
+}
+//# sourceMappingURL=Replay.js.map

package/dist/server/Mppx.d.ts

@@ -412,8 +412,10 @@ type ConfiguredHandler<transport extends Transport.AnyTransport = Transport.Http
         scope?: string | undefined;
         _canonicalRequest: Record<string, unknown>;
         _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
-        /** Whether the offer requires payment-stage identity. */
-        _paymentIdentity?: boolean | undefined;
+        /** The offer's payment-stage identity verifiers, if any. */
+        _paymentIdentity?: readonly Identity.Verifier[] | undefined;
+        /** Whether the route requires identity verifiers (request or payment stage). */
+        _identity?: boolean | undefined;
         _transport: Transport.AnyTransport;
     };
 };