lambder 7.3.1 → 8.1.1

package/dist/invoke/LambderInvokeCaller.js

@@ -2,17 +2,17 @@
  * Calling a Lambder app from another lambda, or from any server code that
  * holds AWS credentials and lambda:InvokeFunction on it.
  *
- * API Gateway delivers an HTTP request to a Lambder app as a JSON event and
- * takes a JSON response object back; a direct InvokeCommand carries JSON in
- * both directions too. So this caller builds the payload-format-2.0 event
- * API Gateway would have built, invokes the function with it, and reads the
- * response object Lambder returns. The callee is an unmodified Lambder app,
- * and everything it offers over HTTP (zod validation, the inferred contract,
- * refusals, guards, idempotency keys, Brotli answers, logList, the crash
- * detail its global error handler chooses to send) applies unchanged. The
- * callee tells an invoke from a browser only by the x-lambder-invoke header,
- * which is a marker for guards and hooks, never an authorization: the IAM
- * grant is that.
+ * Builds the payload-format-2.0 event API Gateway would have built, invokes
+ * the function with it directly, and reads the response object Lambder
+ * returns. The callee is an unmodified Lambder app, so everything it offers
+ * over HTTP (zod validation, the inferred contract, refusals, guards,
+ * idempotency keys, Brotli answers, logList, the crash detail its error
+ * handler chooses to send) applies unchanged. The callee tells an invoke
+ * apart by the event's requestContext.apiId, which no gateway lets a client
+ * write, and reads no forwarding header on one, so `clientIp` and `host` are
+ * the only address and host it sees. The x-lambder-invoke header is a marker
+ * for guards and hooks, never an authorization: the IAM grant is the
+ * authorization.
  *
  * Server-only (zlib, the Lambda SDK), so it is exported from the root entry
  * and never from lambder/client. The SDK is an optional peer dependency
@@ -25,11 +25,13 @@ import { DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionC
 import { readApiSignature } from "../shared/wire/LambderApiSignature.js";
 import { resolveApiOutcome } from "../shared/wire/LambderApiOutcome.js";
 import { mergeGuardInputs, } from "../shared/wire/LambderCallOptions.js";
+import { beginIdempotentAttempt, IDEMPOTENT_ATTEMPT_NOT_SENT } from "../shared/wire/LambderIdempotencyKeyScope.js";
 import { createCallAbort, stopWaitingWhenAborted } from "../shared/util/LambderCallAbort.js";
 import { coerceToError, errorFromCrashDetail } from "../shared/wire/LambderCrashDetail.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 import { resolveCompressionOption } from "../shared/wire/LambderCompressionOption.js";
 import { DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, compressPayloadBrotli, resolveRequestCompressionMinBytes, } from "../shared/wire/LambderRequestPayload.js";
+import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
 import { buildEnvelopeJson, decodeLambdaHttpResult, localLambdaContext, sessionCookies, synthesizeLambdaHttpEvent, } from "./LambderLambdaEvent.js";
 /**
  * Lambda caps a synchronous invoke's request and its response at about 6MB;
@@ -65,7 +67,7 @@ export default class LambderInvokeCaller {
         this.functionName = functionName;
         this.client = client;
         this.clientConfig = clientConfig;
-        this.apiPath = apiPath ?? "/api";
+        this.apiPath = apiPath ?? DEFAULT_API_PATH;
         this.apiVersion = apiVersion;
         this.apiSignatures = apiSignatures;
         this.host = host ?? functionName;
@@ -88,9 +90,10 @@ export default class LambderInvokeCaller {
         const tokenCookieKey = init.sessionTokenCookieKey ?? DEFAULT_SESSION_TOKEN_COOKIE_KEY;
         return synthesizeLambdaHttpEvent({
             method: "POST",
-            path: init.apiPath ?? "/api",
+            path: init.apiPath ?? DEFAULT_API_PATH,
             host,
             headers: init.headers,
+            contentType: "application/json",
             clientIp: init.clientIp,
             cookies: sessionCookies(init.session, tokenCookieKey),
             body: buildEnvelopeJson({
@@ -110,10 +113,9 @@ export default class LambderInvokeCaller {
      * Lambda would: a thrown error becomes a FunctionError payload. For
      * tests that want the real handlers behind the real envelope.
      *
-     * It honours the signal the way lambderHandlerTransport does, by ending
-     * the wait: a function call in this process cannot be cancelled, so the
-     * handler runs to completion regardless and what a timeout buys is the
-     * caller's answer. Ignoring it made timeoutMs a no-op here.
+     * It honours the signal by ending the wait, as lambderHandlerTransport
+     * does: an in-process call cannot be cancelled, so the handler runs to
+     * completion regardless, but timeoutMs still frees the caller.
      */
     static localTransport(handler, context = {}) {
         return async (event, { functionName, signal }) => {
@@ -148,9 +150,9 @@ export default class LambderInvokeCaller {
     }
     async invokeThroughSdk(eventJson, signal) {
         const { LambdaClient, InvokeCommand } = await this.loadSdk();
-        // One call is one delivery attempt, which is what LambderApiTransport
-        // promises: the SDK's own default of 3 would re-invoke a callee that
-        // already ran when only the response was lost.
+        // One call is one delivery attempt, as LambderApiTransport promises:
+        // the SDK's default of 3 would re-invoke a callee that already ran
+        // when only the response was lost.
         if (!this.client)
             this.client = new LambdaClient({ maxAttempts: 1, ...this.clientConfig });
         const output = await this.client.send(new InvokeCommand({
@@ -172,10 +174,10 @@ export default class LambderInvokeCaller {
     }
     /** Delivers one event, serialized exactly once; an event over the invoke cap, a rejected transport, or one that answered after the call was given up on, is a failure. */
     async deliverEvent(event, eventJson, options) {
-        // Measured here rather than on the API path alone, because every
-        // caller of this one sends the same bytes. A path that skips the cap
-        // gets the SDK's RequestEntityTooLargeException back instead, which
-        // classifies as `protocol` and names neither the size nor the cap.
+        // Measured here so every path that delivers an event is capped: an
+        // oversized event would otherwise come back as the SDK's
+        // RequestEntityTooLargeException, which classifies as `protocol` and
+        // names neither the size nor the cap.
         const bytes = Buffer.byteLength(eventJson, "utf8");
         if (bytes > LAMBDER_INVOKE_MAX_EVENT_BYTES) {
             return { failed: {
@@ -188,16 +190,15 @@ export default class LambderInvokeCaller {
         const abort = createCallAbort({ timeoutMs: options.timeoutMs ?? this.timeoutMs, signal: options.signal });
         try {
             // A call the site has already given up on does not reach the
-            // transport: honouring the signal is the transport's obligation
-            // and not every transport does.
+            // transport: honouring the signal is the transport's obligation,
+            // and not every transport meets it.
             const refused = abort.abortFailure("beforeSending");
             if (refused)
                 return { failed: { reason: refused.reason, cause: refused.error, detail: refused.error.message } };
             const sent = await this.transport(event, { functionName: this.functionName, eventJson, signal: abort.signal });
             // An answer that arrives after the abort is not a success: a
-            // transport that ignores the signal resolves late, and believing
-            // it would report ok on a 20ms timeoutMs at 300ms, handing the
-            // call site data it had already abandoned.
+            // transport that ignores the signal resolves late, and trusting it
+            // would hand the call site data it had already abandoned.
             const late = abort.abortFailure("afterAnswering");
             if (late)
                 return { failed: { reason: late.reason, cause: late.error, detail: late.error.message } };
@@ -205,8 +206,8 @@ export default class LambderInvokeCaller {
         }
         catch (err) {
             const cause = coerceToError(err, "the invoke failed");
-            // The caller's own timeout wins, since only it knows about that;
-            // otherwise the rejection says what it was.
+            // The caller's own timeout wins, since only the caller knows about
+            // it; otherwise the rejection says what it was.
             return { failed: { reason: abort.timedOut() ? 'timeout' : classifyDeliveryFailure(cause), cause } };
         }
         finally {
@@ -236,9 +237,8 @@ export default class LambderInvokeCaller {
             cause,
         });
         // FailureInit's arms mirror the outcome's, so each reason's evidence
-        // was already demanded at the site that chose the reason; the
-        // assembly is one object either way, and this is where it is named as
-        // the arm it is rather than written out five times.
+        // was already demanded where the reason was chosen; the failure is
+        // assembled once here and cast to its arm.
         const failure = {
             ok: false,
             reason: init.reason,
@@ -282,15 +282,25 @@ export default class LambderInvokeCaller {
         for (const entry of logList)
             console.log(`[lambder invoke] ${this.functionName} ${apiName}`, entry);
     }
-    /** One call, one outcome. Never throws; api() is what throws. */
+    /**
+     * One call, one outcome. Never throws; api() is what throws. A key scope
+     * is told how the attempt ended, as it is on LambderCaller.
+     */
     async dispatch(apiName, payload, options = {}) {
-        // Everything that happens before the event leaves: the guardInputs
-        // provider, the payload's JSON and its compression. All of it can
-        // throw on the caller's own inputs (a provider that rejects, a
-        // payload holding a cycle or a BigInt), and none of it may escape:
-        // apiOutcome() promises an outcome, api() promises a
-        // LambderInvokeError, and onFailure is the one place failures are
-        // reported. So a throw here is an 'unknown' failure like any other.
+        const idempotentAttempt = beginIdempotentAttempt(options.idempotencyKey);
+        const outcome = await this.dispatchAttempt(apiName, payload, options, idempotentAttempt);
+        // Only the first settle counts: an attempt that never left settled
+        // itself as not sent.
+        idempotentAttempt.settle(outcome);
+        return outcome;
+    }
+    async dispatchAttempt(apiName, payload, options, idempotentAttempt) {
+        const idempotencyKey = idempotentAttempt.key;
+        // Everything before the event leaves can throw on the caller's own
+        // inputs (a provider that rejects, a payload holding a cycle or a
+        // BigInt). None of it may escape: apiOutcome() promises an outcome,
+        // api() a LambderInvokeError, and onFailure must see every failure,
+        // so it becomes an 'unknown' failure.
         let event;
         let eventJson;
         try {
@@ -303,10 +313,10 @@ export default class LambderInvokeCaller {
                 ? await this.guardInputsProvider(apiName)
                 : undefined;
             const guardInputs = mergeGuardInputs(provided, options.guardInputs);
-            // The payload is serialized once: the compression decision needs
-            // its JSON, and when it goes plainly that same JSON is spliced
-            // into the envelope. Compressed when enabled and the JSON reaches
-            // the threshold; `compressRequest` overrides both ways.
+            // Serialized once: the compression decision needs the JSON, and a
+            // plain payload splices that same JSON into the envelope.
+            // Compressed when enabled and the JSON reaches the threshold;
+            // `compressRequest` overrides both ways.
             const payloadJson = payload !== undefined ? JSON.stringify(payload) : undefined;
             const compressionMinBytes = resolveRequestCompressionMinBytes(options.compressRequest, this.requestCompression);
             const compressed = compressionMinBytes !== null && payloadJson !== undefined
@@ -317,6 +327,7 @@ export default class LambderInvokeCaller {
                 path: this.apiPath,
                 host: this.host,
                 headers: options.headers,
+                contentType: "application/json",
                 clientIp: options.clientIp,
                 cookies: sessionCookies(options.session, this.sessionTokenCookieKey),
                 body: buildEnvelopeJson({
@@ -328,13 +339,16 @@ export default class LambderInvokeCaller {
                     payloadJson: compressed ? undefined : payloadJson,
                     compressed,
                     guardInputs,
-                    idempotencyKey: options.idempotencyKey,
+                    idempotencyKey,
                 }),
             }, { invoke: true });
             // Serialized once here; the size guard and the SDK transport both use it.
             eventJson = JSON.stringify(event);
         }
         catch (err) {
+            // Nothing was sent, so the key was not used: the same as the
+            // browser caller's failure before sending.
+            idempotentAttempt.settle(IDEMPOTENT_ATTEMPT_NOT_SENT);
             return await this.failureOutcome(apiName, { reason: 'unknown', cause: coerceToError(err, "the call could not be built") });
         }
         const delivery = await this.deliverEvent(event, eventJson, options);
@@ -357,17 +371,17 @@ export default class LambderInvokeCaller {
             json: async () => http.json(),
             text: async () => http.text(),
         });
-        // Every answer's logs, from the one field the mapping puts them on:
-        // an envelope's, a 500 body's, and a rejected input's, which the
-        // callee writes onto the validation body as it does onto a success.
+        // Every answer's logs arrive on outcome.logList, whether they came
+        // from an envelope, a 500 body or a validation body.
         const logList = outcome.logList ?? [];
         await this.surfaceLogs(apiName, logList);
         // The answer's Set-Cookie values, so a session the callee rotated or
         // cleared is visible to whoever is carrying it.
         const cookies = http.cookies;
-        // The declared output, by the callee's own typing: res.api(null) compiles
-        // only for an output that allows null or beside a reason (an errorMessage
-        // is a failure below; a message-only null is the callee's contract to keep).
+        // The declared output, by the callee's own typing: res.api(null)
+        // compiles only for an output that allows null or beside a reason (an
+        // errorMessage is a failure below; a message-only null is the
+        // callee's contract to keep).
         if (outcome.ok)
             return { ok: true, payload: (outcome.payload ?? null), response: outcome.response, logList, cookies };
         const shared = { status: outcome.status, retryAfterSeconds: outcome.retryAfterSeconds, logList, cookies };
@@ -395,24 +409,21 @@ export default class LambderInvokeCaller {
         }
         return await this.failureOutcome(apiName, {
             ...shared,
-            reason: outcome.reason,
-            errorMessage: outcome.errorMessage,
+            ...(outcome.reason === 'errorMessage' ? { reason: outcome.reason, errorMessage: outcome.errorMessage } : { reason: outcome.reason }),
             response: outcome.response,
             crash: outcome.response.crash,
         });
     }
     /**
      * Full-fidelity call: resolves to a discriminated LambderInvokeOutcome
-     * instead of throwing. Never throws; for sites that degrade gracefully.
-     *
-     * The output is computed from the contract in the return type rather than
-     * taken as a type parameter, so a call site cannot replace it by
-     * annotating what it assigns to.
+     * instead of throwing, for sites that degrade gracefully. The output type
+     * comes from the contract rather than a type parameter, so a call site
+     * cannot replace it by annotating what it assigns to.
      */
     async apiOutcome(apiName, ...rest) {
         // The tuple is a conditional type on an unresolved TApiName, so its
-        // elements read as unknown from inside; the contract shaped them on
-        // the way in, which is where the guarantee belongs.
+        // elements read as unknown here; the contract already checked them at
+        // the call site.
         const [payload, options] = rest;
         return await this.dispatch(apiName, payload, options);
     }
@@ -420,10 +431,9 @@ export default class LambderInvokeCaller {
      * The declared output, or a thrown LambderInvokeError carrying the
      * outcome. A failed dependency is a failed request: the throw reaches the
      * app's global error handler with the callee's error as its cause. The
-     * result is the callee's output type as it declared it: the resolver
-     * only lets a handler answer null when the output allows it or beside a
-     * reason (LambderApiAnswer), so a nullable output is the one place null
-     * arrives.
+     * resolver lets a handler answer null only when the output allows it or
+     * beside a reason (LambderApiAnswer), so null arrives only for a
+     * nullable output.
      */
     async api(apiName, ...rest) {
         const [payload, options] = rest;

package/dist/invoke/LambderInvokeOutcome.d.ts

@@ -4,16 +4,16 @@
  * 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
+ * Kept apart from LambderInvokeCaller, as shared/wire/LambderApiOutcome.ts is
+ * kept apart from 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.
+ * should not have to read the whole class to find it. None of these functions
+ * touch the caller's state.
  */
 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";
+import type { LambderAppRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
 export type LambderInvokeFailureReason = LambderApiFailureReason | 'crash' | 'protocol' | 'payloadTooLarge';
 /** Lambda's own error payload for a FunctionError invocation. */
 export type LambderInvokeFunctionError = {
@@ -26,8 +26,8 @@ type LambderInvokeFailureFields = {
     ok: false;
     /** HTTP status, when the callee answered. */
     status?: number;
-    /** Envelope errorMessage, when the callee provided one. */
-    errorMessage?: any;
+    /** Envelope errorMessage, when the callee provided one: always the message object, a plain string having been read as one (refusalMessageOf). */
+    errorMessage?: LambderAppRefusalMessage;
     /** 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. */
@@ -53,13 +53,17 @@ export type LambderInvokePayloadTooLargeFailure = LambderInvokeFailureFields & {
     /** 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. */
+/** The callee answered, and the envelope itself says the call is refused. Always carries that envelope, and an `errorMessage` refusal always carries its message. */
 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;
-};
+} & ({
+    reason: 'versionExpired' | 'sessionExpired' | 'notAuthorized';
+} | {
+    reason: 'errorMessage';
+    errorMessage: LambderAppRefusalMessage;
+});
 /**
  * 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
@@ -74,13 +78,11 @@ export type LambderInvokeDeliveryFailure = LambderInvokeFailureFields & {
     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
+ * A failed invoke, discriminated by `reason` so narrowing to a reason narrows
+ * to what it 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.
+ * reason, with no optional chain or `!` for a guaranteed field. 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
@@ -94,10 +96,10 @@ export type LambderInvokeOutcome<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.
+     * is the browser for that call: 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;
@@ -107,7 +109,7 @@ export type LambderInvokeErrorInit = {
     apiName: string;
     functionName: string;
     status?: number;
-    errorMessage?: any;
+    errorMessage?: LambderAppRefusalMessage;
     crash?: LambderCrashDetail;
     functionError?: LambderInvokeFunctionError;
     logList: unknown[];
@@ -130,7 +132,7 @@ export declare class LambderInvokeError extends Error {
     readonly apiName: string;
     readonly functionName: string;
     readonly status?: number;
-    readonly errorMessage?: any;
+    readonly errorMessage?: LambderAppRefusalMessage;
     readonly crash?: LambderCrashDetail;
     readonly functionError?: LambderInvokeFunctionError;
     readonly logList: unknown[];
@@ -150,10 +152,9 @@ export declare const isLambderInvokeError: (err: unknown) => err is LambderInvok
  * 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.
+ * failure is a plain Error or TypeError with neither. A service exception is
+ * a permission, wiring or size fault to fix; calling it `network` would send
+ * the reader to check 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. */

package/dist/invoke/LambderInvokeOutcome.js

@@ -4,12 +4,11 @@
  * 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
+ * Kept apart from LambderInvokeCaller, as shared/wire/LambderApiOutcome.ts is
+ * kept apart from 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.
+ * should not have to read the whole class to find it. None of these functions
+ * touch the caller's state.
  */
 import { isLambderTransportFailure } from "../shared/transport/LambderApiTransport.js";
 /**
@@ -63,10 +62,9 @@ export const isLambderInvokeError = (err) => err instanceof Error && err.isLambd
  * 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.
+ * failure is a plain Error or TypeError with neither. A service exception is
+ * a permission, wiring or size fault to fix; calling it `network` would send
+ * the reader to check their connection instead.
  */
 export const classifyDeliveryFailure = (error) => {
     if (isLambderTransportFailure(error))
@@ -102,19 +100,8 @@ export const describeFailure = (init) => {
         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.errorMessage !== undefined)
+        return init.errorMessage.content;
     if (init.reason === 'validation')
         return "the callee rejected the input";
     if (init.reason === 'versionExpired')

package/dist/invoke/LambderLambdaEvent.d.ts

@@ -11,7 +11,12 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, Context } from "aws-lambda";
 import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 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. */
+/**
+ * Marks a synthesized request as an invoke, for guards and hooks that want to
+ * tell. Not an authorization: over HTTP it is a header any client can send.
+ * The server itself tells an invoke by its requestContext.apiId, which no
+ * gateway lets a client write (see LAMBDER_INVOKE_API_ID).
+ */
 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";
@@ -33,21 +38,36 @@ export type LambderSynthesizedRequest = {
     clientIp?: string;
     cookies?: string[];
     body?: string | Buffer;
+    /**
+     * The body's type, owned by the event over any Content-Type in `headers`:
+     * an API call's envelope is JSON whatever headers a caller forwards, and
+     * a server takes a POST to its API path as an API call only when it says
+     * so. Left out, a caller's own Content-Type stands, and a body without
+     * one is typed by its kind.
+     */
+    contentType?: string;
 };
 /**
  * The event API Gateway would deliver for this request: payload format 2.0
- * (an HTTP API, a Function URL) unless `eventFormat: "v1"` asks for the REST
- * API's. An invoke is always 2.0; the other format is for an in-process call
- * that wants the handler to meet the shape its own deployment delivers.
+ * (an HTTP API's, whose path arrives decoded) unless `eventFormat: "v1"` asks
+ * for the REST API's, whose path arrives as written. An invoke is always 2.0;
+ * the other format is for an in-process call that wants the handler to meet
+ * the shape its own deployment delivers.
  * `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 the gateway's
- * observed source address only (requestContext.http.sourceIp, or
- * requestContext.identity.sourceIp on a REST API event). 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.
+ * observed source address (requestContext.http.sourceIp, or
+ * requestContext.identity.sourceIp on a REST API event). On an invoke it is
+ * the only channel, and x-forwarded-for is dropped from the caller's
+ * `headers`: a server of this version reads no trusted forwarding header on
+ * an event carrying LAMBDER_INVOKE_API_ID, but a callee on Lambder 7.x reads
+ * the one it trusts on any event, so a gateway lambda forwarding a browser's
+ * headers would hand it a ctx.ip the browser chose. x-forwarded-for is the
+ * header a gateway writes and the one such a callee trusts in the common
+ * case. A browser-shaped request keeps every header it was given: it stands
+ * for what a gateway delivered, and a test that writes a forwarding header
+ * on one is exercising the app's own trustedClientIpHeaders.
  */
 export declare function synthesizeLambdaHttpEvent(request: LambderSynthesizedRequest, options: {
     invoke: boolean;