lambder 6.0.2 → 7.0.2

package/dist/invoke/LambderInvokeOutcome.d.ts

@@ -0,0 +1,165 @@
+/**
+ * What an invoke call reports: the failure reasons, the outcome union, the
+ * error api() throws, and the pure functions that read a failure (what a
+ * rejected delivery means, what Lambda's error payload says, the one-line
+ * detail an error message ends with).
+ *
+ * Split out of LambderInvokeCaller for the reason shared/wire/LambderApiOutcome.ts
+ * is split out of the browser caller: this is the vocabulary a CALLER of the
+ * caller reads, and a site that only annotates an outcome or narrows an error
+ * should not have to read a 700-line class to find it. The functions here
+ * touch none of the caller's state, so every "what went wrong on an invoke"
+ * answer is in one file.
+ */
+import type { LambderApiEnvelopeBody } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiFailureReason, LambderValidationError } from "../shared/wire/LambderApiOutcome.js";
+import type { LambderCrashDetail } from "../shared/wire/LambderCrashDetail.js";
+export type LambderInvokeFailureReason = LambderApiFailureReason | 'crash' | 'protocol' | 'payloadTooLarge';
+/** Lambda's own error payload for a FunctionError invocation. */
+export type LambderInvokeFunctionError = {
+    errorType?: string;
+    errorMessage?: string;
+    trace?: string[];
+};
+/** What every invoke failure carries, whatever went wrong. */
+type LambderInvokeFailureFields = {
+    ok: false;
+    /** HTTP status, when the callee answered. */
+    status?: number;
+    /** Envelope errorMessage, when the callee provided one. */
+    errorMessage?: any;
+    /** Seconds to wait before retrying, from the answer's Retry-After header. */
+    retryAfterSeconds?: number;
+    /** Always present: the error api() throws for this failure, with the callee's error as its cause when one is known. */
+    error: LambderInvokeError;
+    /** The answer's logList; empty when no envelope came back. */
+    logList: unknown[];
+    /** The answer's Set-Cookie values; empty when no answer came back. */
+    cookies: string[];
+};
+/** HTTP 422: the callee rejected the input against the API's schema. Always carries the issues. */
+export type LambderInvokeValidationFailure = LambderInvokeFailureFields & {
+    reason: 'validation';
+    zodError: LambderValidationError;
+};
+/** Lambda reported a FunctionError: the callee failed outside the framework (an init failure, a timeout, out of memory). Always carries the runtime's error payload. */
+export type LambderInvokeCrashFailure = LambderInvokeFailureFields & {
+    reason: 'crash';
+    functionError: LambderInvokeFunctionError;
+};
+/** Refused before sending: the serialized event is over the invoke cap. Always carries its size. */
+export type LambderInvokePayloadTooLargeFailure = LambderInvokeFailureFields & {
+    reason: 'payloadTooLarge';
+    /** The event's byte size, so a caller can say by how much it is over. */
+    bytes: number;
+};
+/** The callee answered, and the envelope itself says the call is refused. Always carries that envelope. */
+export type LambderInvokeEnvelopeFailure = LambderInvokeFailureFields & {
+    reason: 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage';
+    response: LambderApiEnvelopeBody<any>;
+    /** The callee's crash detail, when its global error handler sent one (the envelope's `crash` field). */
+    crash?: LambderCrashDetail;
+};
+/**
+ * Nothing usable came back: the invoke never arrived or was given up on, the
+ * Lambda service answered instead of the callee, the callee answered 5xx, or
+ * something around the call threw. A 5xx carries `response` when the callee
+ * answered with Lambder's own envelope, which is how a crash detail and a
+ * logList arrive with it.
+ */
+export type LambderInvokeDeliveryFailure = LambderInvokeFailureFields & {
+    reason: 'network' | 'timeout' | 'server' | 'protocol' | 'unknown';
+    response?: LambderApiEnvelopeBody<any>;
+    /** The callee's crash detail, when its global error handler sent one (the envelope's `crash` field). */
+    crash?: LambderCrashDetail;
+};
+/**
+ * A failed invoke, discriminated by `reason` rather than written as one arm of
+ * optional fields, so narrowing to a reason narrows to what that reason
+ * actually carries: `zodError` after `validation`, `functionError` after
+ * `crash`, `bytes` after `payloadTooLarge`, `response` after an envelope
+ * reason, so a reader never writes an optional chain or a `!` for a field the
+ * reason already guarantees. The browser caller's LambderApiOutcome is
+ * discriminated the same way.
+ *
+ * `error`, `logList` and `cookies` are on every arm, and `status`,
+ * `errorMessage` and `retryAfterSeconds` are there whenever an answer came
+ * back to read them from.
+ */
+export type LambderInvokeFailure = LambderInvokeValidationFailure | LambderInvokeCrashFailure | LambderInvokePayloadTooLargeFailure | LambderInvokeEnvelopeFailure | LambderInvokeDeliveryFailure;
+export type LambderInvokeOutcome<T> = {
+    ok: true;
+    payload: T;
+    response: LambderApiEnvelopeBody<T>;
+    logList: unknown[];
+    /**
+     * The answer's Set-Cookie values. A caller carrying a user's session
+     * is the browser for that call, and nothing else is: a callee that
+     * rotated or cleared the session cookies says so here, and a caller
+     * that ignores them keeps sending the old token. See
+     * reissueSession() on the callee for the tokens themselves.
+     */
+    cookies: string[];
+} | LambderInvokeFailure;
+export type LambderInvokeErrorInit = {
+    message: string;
+    reason: LambderInvokeFailureReason;
+    apiName: string;
+    functionName: string;
+    status?: number;
+    errorMessage?: any;
+    crash?: LambderCrashDetail;
+    functionError?: LambderInvokeFunctionError;
+    logList: unknown[];
+    zodError?: LambderValidationError;
+    retryAfterSeconds?: number;
+    bytes?: number;
+    cause?: unknown;
+};
+/**
+ * What api() throws. Its message names the function, the API and the reason,
+ * so an error reporter that fingerprints on the message groups one broken
+ * API into one row; its cause is the callee's own error rebuilt from the
+ * crash detail (or Lambda's FunctionError, or the SDK's rejection), so a
+ * reporter that walks causes stores the callee's stack.
+ */
+export declare class LambderInvokeError extends Error {
+    /** Brand for detection across duplicate lambder installs, like LambderApiRefusal. */
+    readonly isLambderInvokeError = true;
+    readonly reason: LambderInvokeFailureReason;
+    readonly apiName: string;
+    readonly functionName: string;
+    readonly status?: number;
+    readonly errorMessage?: any;
+    readonly crash?: LambderCrashDetail;
+    readonly functionError?: LambderInvokeFunctionError;
+    readonly logList: unknown[];
+    readonly zodError?: LambderValidationError;
+    readonly retryAfterSeconds?: number;
+    readonly bytes?: number;
+    /** The full failure outcome; it carries this error and this error carries it. */
+    outcome: LambderInvokeFailure;
+    constructor(init: LambderInvokeErrorInit);
+}
+/** Brand-based type guard (see LambderInvokeError.isLambderInvokeError). */
+export declare const isLambderInvokeError: (err: unknown) => err is LambderInvokeError;
+/**
+ * What a rejected delivery means, as far as the rejection itself says.
+ *
+ * A transport that named its own reason is believed. Otherwise: the Lambda
+ * SDK throws its service exceptions (AccessDeniedException,
+ * ResourceNotFoundException, RequestEntityTooLargeException and the rest)
+ * with a $fault mark and a name ending in "Exception", while a connectivity
+ * failure arrives as a plain Error or TypeError carrying neither. The first
+ * kind is the Lambda service answering the invoke, which is a permission,
+ * wiring or size fault to go and fix; calling it `network` sent whoever read
+ * it to look at their connection instead.
+ */
+export declare const classifyDeliveryFailure: (error: Error) => "network" | "protocol";
+/** Lambda's error payload as an Error, with the callee's own name and trace. */
+export declare const errorFromFunctionError: (functionError: LambderInvokeFunctionError) => Error;
+/** Lambda's error payload as it actually arrives: an object with the three fields, or whatever else the runtime sent. */
+export declare const parseFunctionError: (result: unknown) => LambderInvokeFunctionError;
+/** The one-line detail a failure's message ends with. */
+export declare const describeFailure: (init: Omit<LambderInvokeErrorInit, "message" | "apiName" | "functionName" | "logList">) => string;
+export {};

package/dist/invoke/LambderInvokeOutcome.js

@@ -0,0 +1,129 @@
+/**
+ * What an invoke call reports: the failure reasons, the outcome union, the
+ * error api() throws, and the pure functions that read a failure (what a
+ * rejected delivery means, what Lambda's error payload says, the one-line
+ * detail an error message ends with).
+ *
+ * Split out of LambderInvokeCaller for the reason shared/wire/LambderApiOutcome.ts
+ * is split out of the browser caller: this is the vocabulary a CALLER of the
+ * caller reads, and a site that only annotates an outcome or narrows an error
+ * should not have to read a 700-line class to find it. The functions here
+ * touch none of the caller's state, so every "what went wrong on an invoke"
+ * answer is in one file.
+ */
+import { isLambderTransportFailure } from "../shared/transport/LambderApiTransport.js";
+/**
+ * What api() throws. Its message names the function, the API and the reason,
+ * so an error reporter that fingerprints on the message groups one broken
+ * API into one row; its cause is the callee's own error rebuilt from the
+ * crash detail (or Lambda's FunctionError, or the SDK's rejection), so a
+ * reporter that walks causes stores the callee's stack.
+ */
+export class LambderInvokeError extends Error {
+    /** Brand for detection across duplicate lambder installs, like LambderApiRefusal. */
+    isLambderInvokeError = true;
+    reason;
+    apiName;
+    functionName;
+    status;
+    errorMessage;
+    crash;
+    functionError;
+    logList;
+    zodError;
+    retryAfterSeconds;
+    bytes;
+    /** The full failure outcome; it carries this error and this error carries it. */
+    outcome;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = "LambderInvokeError";
+        this.reason = init.reason;
+        this.apiName = init.apiName;
+        this.functionName = init.functionName;
+        this.status = init.status;
+        this.errorMessage = init.errorMessage;
+        this.crash = init.crash;
+        this.functionError = init.functionError;
+        this.logList = init.logList;
+        this.zodError = init.zodError;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+        this.bytes = init.bytes;
+    }
+}
+/** Brand-based type guard (see LambderInvokeError.isLambderInvokeError). */
+export const isLambderInvokeError = (err) => err instanceof Error && err.isLambderInvokeError === true;
+// ---------------------------------------------------------------------------
+// Reading a failure: pure functions over what came back, used by the caller.
+// ---------------------------------------------------------------------------
+/**
+ * What a rejected delivery means, as far as the rejection itself says.
+ *
+ * A transport that named its own reason is believed. Otherwise: the Lambda
+ * SDK throws its service exceptions (AccessDeniedException,
+ * ResourceNotFoundException, RequestEntityTooLargeException and the rest)
+ * with a $fault mark and a name ending in "Exception", while a connectivity
+ * failure arrives as a plain Error or TypeError carrying neither. The first
+ * kind is the Lambda service answering the invoke, which is a permission,
+ * wiring or size fault to go and fix; calling it `network` sent whoever read
+ * it to look at their connection instead.
+ */
+export const classifyDeliveryFailure = (error) => {
+    if (isLambderTransportFailure(error))
+        return error.reason;
+    const fault = error.$fault;
+    if (fault === "client" || fault === "server")
+        return 'protocol';
+    return error.name.endsWith("Exception") ? 'protocol' : 'network';
+};
+/** Lambda's error payload as an Error, with the callee's own name and trace. */
+export const errorFromFunctionError = (functionError) => {
+    const error = new Error(functionError.errorMessage ?? "the function failed");
+    error.name = functionError.errorType ?? "FunctionError";
+    if (functionError.trace?.length)
+        error.stack = functionError.trace.join("\n");
+    return error;
+};
+/** Lambda's error payload as it actually arrives: an object with the three fields, or whatever else the runtime sent. */
+export const parseFunctionError = (result) => {
+    if (result && typeof result === "object") {
+        const { errorType, errorMessage, trace } = result;
+        return {
+            ...(typeof errorType === "string" ? { errorType } : {}),
+            ...(typeof errorMessage === "string" ? { errorMessage } : {}),
+            ...(Array.isArray(trace) ? { trace: trace.map(String) } : {}),
+        };
+    }
+    return { errorMessage: typeof result === "string" ? result : undefined };
+};
+/** The one-line detail a failure's message ends with. */
+export const describeFailure = (init) => {
+    if (init.crash)
+        return init.crash.message;
+    if (init.functionError)
+        return `${init.functionError.errorType ?? "FunctionError"}: ${init.functionError.errorMessage ?? "the function failed"}`;
+    if (init.errorMessage !== undefined) {
+        const content = init.errorMessage?.content;
+        if (typeof content === "string")
+            return content;
+        if (typeof init.errorMessage === "string")
+            return init.errorMessage;
+        try {
+            return JSON.stringify(init.errorMessage);
+        }
+        catch {
+            return String(init.errorMessage);
+        }
+    }
+    if (init.reason === 'validation')
+        return "the callee rejected the input";
+    if (init.reason === 'versionExpired')
+        return "the callee answered versionExpired";
+    if (init.reason === 'sessionExpired')
+        return "the callee answered sessionExpired";
+    if (init.reason === 'notAuthorized')
+        return "the callee answered notAuthorized";
+    if (init.cause instanceof Error)
+        return init.cause.message;
+    return init.status !== undefined ? `HTTP ${init.status}` : "no answer";
+};

package/dist/invoke/LambderLambdaEvent.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The two conversions between a request and what Lambda speaks: a request
+ * as the API Gateway payload-format-2.0 event it would have delivered, and
+ * a function's answer as the decoded HTTP result it stands for. Shared by
+ * LambderInvokeCaller (a real invoke through the Lambda SDK) and
+ * lambderHandlerTransport (a Lambder handler called in-process, for tests),
+ * along with the smaller conversions that belong to a synthesized request:
+ * its body envelope, and a carried session as the cookie pair it travels as.
+ * Server-only: Buffer and the codec's zlib restore.
+ */
+import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
+import type { LambderCompressedBrotliPayload, LambderCompressedGzipPayload } from "../shared/wire/LambderRequestPayload.js";
+/** Marks a synthesized request as an invoke, for guards and hooks that want to tell. Not an authorization. */
+export declare const LAMBDER_INVOKE_HEADER = "x-lambder-invoke";
+/** The invoking function's name, when the caller runs in Lambda; for the callee's logs. */
+export declare const LAMBDER_INVOKED_BY_HEADER = "x-lambder-invoked-by";
+/** The value of the marker header; a future incompatible event shape would bump it. */
+export declare const LAMBDER_INVOKE_PROTOCOL = "1";
+/** A session carried on a user's behalf: the two values a browser holds. */
+export type LambderInvokeSession = {
+    token: string;
+    csrf: string;
+};
+/** The session's cookie pair for a synthesized event: the token rides as a cookie, the CSRF value in the envelope's `token` field. */
+export declare const sessionCookies: (session: LambderInvokeSession | undefined, tokenCookieKey: string) => string[] | undefined;
+export type LambderSynthesizedRequest = {
+    method: string;
+    path: string;
+    query?: Record<string, string>;
+    host: string;
+    headers?: Record<string, string>;
+    clientIp?: string;
+    cookies?: string[];
+    body?: string | Buffer;
+};
+/**
+ * The payload-format-2.0 event API Gateway would deliver for this request.
+ * `invoke: true` adds the invoke marker headers a server-to-server call
+ * carries; a browser-shaped request (the handler transport) leaves them off.
+ *
+ * The client address is `clientIp` and reaches the callee as
+ * requestContext.http.sourceIp only. Writing it as x-forwarded-for as well
+ * would put the same fact on a channel a callee may be configured to trust
+ * (trustedClientIpHeaders), and the header is the one the caller's own
+ * `headers` could otherwise have set.
+ */
+export declare const synthesizeLambdaHttpEvent: (request: LambderSynthesizedRequest, options: {
+    invoke: boolean;
+}) => APIGatewayProxyEventV2;
+/**
+ * The body envelope LambderCaller sends, minus the fields only a browser has
+ * a value for, as JSON. A plain payload arrives already serialized (the
+ * compression decision needed its JSON) and is spliced in rather than
+ * parsed and stringified a second time; a compressed one rides as its two
+ * fields.
+ */
+export declare const buildEnvelopeJson: (fields: {
+    apiName: string;
+    version?: string;
+    csrf?: string;
+    siteHost: string;
+    /** The payload's own JSON, when it goes plainly. */
+    payloadJson?: string;
+    /** The compressed pair, when it goes compressed. */
+    compressed?: LambderCompressedBrotliPayload | LambderCompressedGzipPayload | null;
+    guardInputs?: Record<string, unknown>;
+    idempotencyKey?: string;
+}) => string;
+/** The decoded HTTP answer of a Lambda result: status, lowercased headers, cookies and the body bytes (decompressed when the callee compressed them). */
+export type LambderLambdaHttpResult = {
+    statusCode: number;
+    headers: Record<string, string>;
+    cookies: string[];
+    body: Buffer;
+    text: () => string;
+    json: () => unknown;
+};
+/** The function's answer as an HTTP result; throws when it is not one, or its compressed body cannot be restored under `maxBodyBytes`. */
+export declare const decodeLambdaHttpResult: (result: unknown, maxBodyBytes: number) => Promise<LambderLambdaHttpResult>;
+/** A Lambda context for an in-process call, the fields a handler might read filled plausibly. */
+export declare const localLambdaContext: (functionName: string, overrides?: Partial<Context>) => Context;

package/dist/invoke/LambderLambdaEvent.js

@@ -0,0 +1,187 @@
+/**
+ * The two conversions between a request and what Lambda speaks: a request
+ * as the API Gateway payload-format-2.0 event it would have delivered, and
+ * a function's answer as the decoded HTTP result it stands for. Shared by
+ * LambderInvokeCaller (a real invoke through the Lambda SDK) and
+ * lambderHandlerTransport (a Lambder handler called in-process, for tests),
+ * along with the smaller conversions that belong to a synthesized request:
+ * its body envelope, and a carried session as the cookie pair it travels as.
+ * Server-only: Buffer and the codec's zlib restore.
+ */
+import { restoreBytes } from "../shared/wire/LambderCompressionCodec.js";
+import { bytesToBase64 } from "../shared/util/LambderBase64.js";
+import { buildEnvelopeFields } from "../shared/transport/LambderApiTransport.js";
+/** Marks a synthesized request as an invoke, for guards and hooks that want to tell. Not an authorization. */
+export const LAMBDER_INVOKE_HEADER = "x-lambder-invoke";
+/** The invoking function's name, when the caller runs in Lambda; for the callee's logs. */
+export const LAMBDER_INVOKED_BY_HEADER = "x-lambder-invoked-by";
+/** The value of the marker header; a future incompatible event shape would bump it. */
+export const LAMBDER_INVOKE_PROTOCOL = "1";
+/**
+ * The forwarded-address header a gateway writes. This event never writes it:
+ * the address it asserts travels in requestContext.http.sourceIp, which is
+ * what resolveClientIp reads and the only channel a callee trusts by default.
+ */
+const FORWARDED_FOR_HEADER = "x-forwarded-for";
+/** The session's cookie pair for a synthesized event: the token rides as a cookie, the CSRF value in the envelope's `token` field. */
+export const sessionCookies = (session, tokenCookieKey) => session ? [`${tokenCookieKey}=${session.token}`] : undefined;
+const randomRequestId = () => {
+    const webCrypto = globalThis.crypto;
+    if (webCrypto?.randomUUID)
+        return webCrypto.randomUUID();
+    return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+};
+/**
+ * The payload-format-2.0 event API Gateway would deliver for this request.
+ * `invoke: true` adds the invoke marker headers a server-to-server call
+ * carries; a browser-shaped request (the handler transport) leaves them off.
+ *
+ * The client address is `clientIp` and reaches the callee as
+ * requestContext.http.sourceIp only. Writing it as x-forwarded-for as well
+ * would put the same fact on a channel a callee may be configured to trust
+ * (trustedClientIpHeaders), and the header is the one the caller's own
+ * `headers` could otherwise have set.
+ */
+export const synthesizeLambdaHttpEvent = (request, options) => {
+    // The caller's own headers go on first, so the ones this function owns
+    // cannot be displaced by them. Forwarding an incoming browser request's
+    // headers into `headers` is an ordinary gateway-lambda pattern, and with
+    // the spread last it let that end user overwrite the invoke markers and
+    // the forwarded address this event is asserting.
+    const headers = {};
+    for (const [key, value] of Object.entries(request.headers ?? {}))
+        headers[key.toLowerCase()] = value;
+    // These three the event owns unconditionally, whatever the caller passed:
+    // a forwarded address the caller did not assert through `clientIp` is not
+    // this event's to make, and the invoke markers say what this event is. A
+    // gateway lambda that forwards a browser's headers wholesale would
+    // otherwise hand a callee that trusts x-forwarded-for an end-user-chosen
+    // ctx.ip, and let a browser-shaped request claim to be an invoke.
+    delete headers[FORWARDED_FOR_HEADER];
+    delete headers[LAMBDER_INVOKE_HEADER];
+    delete headers[LAMBDER_INVOKED_BY_HEADER];
+    headers.host = request.host;
+    headers["accept-encoding"] = "br, gzip";
+    if (options.invoke) {
+        headers[LAMBDER_INVOKE_HEADER] = LAMBDER_INVOKE_PROTOCOL;
+        const invokedBy = typeof process !== "undefined" ? process.env?.AWS_LAMBDA_FUNCTION_NAME : undefined;
+        if (invokedBy)
+            headers[LAMBDER_INVOKED_BY_HEADER] = invokedBy;
+    }
+    const isBinary = Buffer.isBuffer(request.body);
+    if (request.body !== undefined && !headers["content-type"]) {
+        headers["content-type"] = isBinary ? "application/octet-stream" : "application/json";
+    }
+    const now = Date.now();
+    return {
+        version: "2.0",
+        routeKey: "$default",
+        rawPath: request.path,
+        rawQueryString: new URLSearchParams(request.query ?? {}).toString(),
+        headers,
+        ...(request.cookies?.length ? { cookies: request.cookies } : {}),
+        requestContext: {
+            accountId: "",
+            apiId: options.invoke ? "lambder-invoke" : "lambder-local",
+            domainName: request.host,
+            domainPrefix: "",
+            http: {
+                method: request.method,
+                path: request.path,
+                protocol: "HTTP/1.1",
+                sourceIp: request.clientIp ?? "",
+                userAgent: options.invoke ? "lambder-invoke" : "lambder-local",
+            },
+            requestId: randomRequestId(),
+            routeKey: "$default",
+            stage: "$default",
+            time: new Date(now).toISOString(),
+            timeEpoch: now,
+        },
+        ...(request.body !== undefined
+            ? { body: isBinary ? bytesToBase64(request.body) : request.body }
+            : {}),
+        isBase64Encoded: isBinary,
+    };
+};
+/**
+ * The body envelope LambderCaller sends, minus the fields only a browser has
+ * a value for, as JSON. A plain payload arrives already serialized (the
+ * compression decision needed its JSON) and is spliced in rather than
+ * parsed and stringified a second time; a compressed one rides as its two
+ * fields.
+ */
+export const buildEnvelopeJson = (fields) => {
+    // The field set is buildEnvelopeFields', so a field added to the envelope
+    // reaches this sender too; only the payload is this one's own business.
+    const withoutPayload = JSON.stringify(buildEnvelopeFields({
+        apiName: fields.apiName,
+        version: fields.version,
+        token: fields.csrf ?? "",
+        siteHost: fields.siteHost,
+        compressed: fields.compressed,
+        guardInputs: fields.guardInputs,
+        idempotencyKey: fields.idempotencyKey,
+    }));
+    if (fields.payloadJson === undefined)
+        return withoutPayload;
+    return `${withoutPayload.slice(0, -1)},"payload":${fields.payloadJson}}`;
+};
+/** The function's answer as an HTTP result; throws when it is not one, or its compressed body cannot be restored under `maxBodyBytes`. */
+export const decodeLambdaHttpResult = async (result, maxBodyBytes) => {
+    if (!result || typeof result !== "object" || typeof result.statusCode !== "number") {
+        throw new Error("the function did not answer with an HTTP response object; is it a Lambder app?");
+    }
+    const raw = result;
+    const headers = {};
+    const cookies = [...(raw.cookies ?? [])];
+    for (const [key, value] of Object.entries(raw.headers ?? {}))
+        headers[key.toLowerCase()] = value;
+    for (const [key, values] of Object.entries(raw.multiValueHeaders ?? {})) {
+        // A v1 answer carries Set-Cookie as a multi-value header; keep the
+        // values apart, as the v2 cookies array does, since they contain commas.
+        if (key.toLowerCase() === "set-cookie")
+            cookies.push(...values);
+        headers[key.toLowerCase()] = values.join(", ");
+    }
+    let body = raw.body ? Buffer.from(raw.body, raw.isBase64Encoded ? "base64" : "utf8") : Buffer.alloc(0);
+    const encoding = headers["content-encoding"]?.trim().toLowerCase();
+    if (encoding === "br" || encoding === "gzip") {
+        // restoreBytes, not restoreText: a route may answer compressed
+        // binary (a wasm module, anything it forced compression on), and
+        // decoding that as UTF-8 first would replace every byte that is
+        // not valid UTF-8 and hand back a silently different body.
+        const restored = await restoreBytes(body, encoding, { maxBytes: maxBodyBytes });
+        body = Buffer.isBuffer(restored) ? restored : Buffer.from(restored);
+    }
+    else if (encoding && encoding !== "identity") {
+        // "identity" is a legal value meaning no encoding, and a hook or a
+        // proxy may set it; treating it as unsupported turned every such
+        // invoke into a protocol failure.
+        throw new Error(`the answer carries an unsupported Content-Encoding "${encoding}"`);
+    }
+    return {
+        statusCode: raw.statusCode,
+        headers,
+        cookies,
+        body,
+        text: () => body.toString("utf8"),
+        json: () => JSON.parse(body.toString("utf8")),
+    };
+};
+/** A Lambda context for an in-process call, the fields a handler might read filled plausibly. */
+export const localLambdaContext = (functionName, overrides = {}) => ({
+    callbackWaitsForEmptyEventLoop: false,
+    functionName,
+    functionVersion: "$LATEST",
+    invokedFunctionArn: `arn:aws:lambda:local:000000000000:function:${functionName}`,
+    memoryLimitInMB: "128",
+    awsRequestId: randomRequestId(),
+    logGroupName: `/aws/lambda/${functionName}`,
+    logStreamName: "local",
+    getRemainingTimeInMillis: () => 30_000,
+    done: () => { },
+    fail: () => { },
+    succeed: () => { },
+    ...overrides,
+});

package/dist/invoke/lambderHandlerTransport.d.ts

@@ -0,0 +1,36 @@
+import type { Context } from "aws-lambda";
+import type { LambderApiTransport } from "../shared/transport/LambderApiTransport.js";
+import type { LambderHandler } from "../core/LambderCreateOptions.js";
+export type LambderHandlerTransportOptions = {
+    /** The Host the handler sees (ctx.host), and the siteHost the envelope carries when the caller has none. Default: the apiPath's own host when it is absolute, otherwise "localhost". */
+    host?: string;
+    /** The client IP the handler sees (ctx.ip). Default: "127.0.0.1". */
+    clientIp?: string;
+    /** Ceiling on what a compressed answer may restore to. Default: 20,000,000. */
+    maxResponseBytes?: number;
+    /** Fields of the Lambda context the handler receives. */
+    context?: Partial<Context>;
+};
+/**
+ * A transport that calls a Lambder handler in this process, the way a
+ * browser's request would reach it: a browser-shaped API Gateway event (no
+ * invoke marker), the real handler, and its answer decoded back, compressed
+ * bodies included. With the memory stores, that is an integration test of a
+ * real app through the typed caller with no HTTP and no AWS. Wrap it in
+ * lambderCookieJarTransport to hold a session across calls.
+ *
+ * A handler that throws (which a Lambder app never does on the HTTP path,
+ * since render() answers its own last-resort 500) produced no answer at all,
+ * so the call fails as `protocol` carrying the handler's own error as its
+ * cause. API Gateway would have turned it into a bare 502, and synthesizing
+ * one here would throw the error away; keeping it is the point of an
+ * in-process transport, and there is nowhere in an HTTP answer to put one
+ * except the user-facing `message` field, which is the wrong channel for an
+ * internal fault.
+ *
+ * `request.signal` ends the wait, as the transport contract requires. The
+ * handler keeps running to completion either way, because a function call in
+ * this process cannot be cancelled: what a timeout buys here is the caller's
+ * answer, not the callee's attention.
+ */
+export declare const lambderHandlerTransport: (handler: LambderHandler, options?: LambderHandlerTransportOptions) => LambderApiTransport;