lambder 7.3.1 → 8.1.1

package/dist/invoke/LambderLambdaEvent.js

@@ -10,17 +10,23 @@
  */
 import { restoreBytes } from "../shared/wire/LambderCompressionCodec.js";
 import { bytesToBase64 } from "../shared/util/LambderBase64.js";
+import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID } from "../shared/wire/LambderInvokeApiId.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. */
+/**
+ * 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 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.
+ * The forwarded-address header a gateway writes, which an invoke never
+ * carries: its address travels as `clientIp` alone (see
+ * synthesizeLambdaHttpEvent).
  */
 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. */
@@ -33,22 +39,19 @@ const randomRequestId = () => {
 };
 export function 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.
+    // cannot be displaced by them.
     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];
+    // The invoke markers the event owns whatever the caller passed: they say
+    // what this event is. Forwarding a browser's headers wholesale is an
+    // ordinary gateway-lambda pattern, and without these deletes it would let
+    // a browser-shaped request claim to be an invoke, or an invoke name an
+    // invoking function that did not send it.
     delete headers[LAMBDER_INVOKE_HEADER];
     delete headers[LAMBDER_INVOKED_BY_HEADER];
+    if (options.invoke)
+        delete headers[FORWARDED_FOR_HEADER];
     headers.host = request.host;
     headers["accept-encoding"] = "br, gzip";
     if (options.invoke) {
@@ -58,7 +61,9 @@ export function synthesizeLambdaHttpEvent(request, options) {
             headers[LAMBDER_INVOKED_BY_HEADER] = invokedBy;
     }
     const isBinary = Buffer.isBuffer(request.body);
-    if (request.body !== undefined && !headers["content-type"]) {
+    if (request.contentType)
+        headers["content-type"] = request.contentType;
+    else if (request.body !== undefined && !headers["content-type"]) {
         headers["content-type"] = isBinary ? "application/octet-stream" : "application/json";
     }
     const body = request.body === undefined ? undefined : isBinary ? bytesToBase64(request.body) : request.body;
@@ -85,7 +90,7 @@ export function synthesizeLambdaHttpEvent(request, options) {
             // Cognito identity) describes a deployment this event has none of.
             requestContext: {
                 accountId: "",
-                apiId: "lambder-local",
+                apiId: options.invoke ? LAMBDER_INVOKE_API_ID : LAMBDER_LOCAL_API_ID,
                 domainName: request.host,
                 httpMethod: request.method,
                 identity: { sourceIp: request.clientIp ?? "", userAgent: "lambder-local" },
@@ -100,21 +105,34 @@ export function synthesizeLambdaHttpEvent(request, options) {
             isBase64Encoded: isBinary,
         };
     }
+    // An HTTP API's event, with its path decoded (an encoded slash into a
+    // separator, too) the way the gateway delivers it, whatever host the
+    // request names. The server reads a gateway's v2 event as encoded when
+    // its domain is a Function URL's, so it is told this event is decoded by
+    // the apiId, which is Lambder's own either way: a request naming a
+    // lambda-url host would otherwise have its path decoded a second time,
+    // and `/%2561dmin` would reach `/admin`. A path that does not decode goes
+    // as it is.
+    let decodedPath = request.path;
+    try {
+        decodedPath = decodeURIComponent(request.path);
+    }
+    catch { /* delivered as written */ }
     return {
         version: "2.0",
         routeKey: "$default",
-        rawPath: request.path,
+        rawPath: decodedPath,
         rawQueryString: new URLSearchParams(request.query ?? {}).toString(),
         headers,
         ...(request.cookies?.length ? { cookies: request.cookies } : {}),
         requestContext: {
             accountId: "",
-            apiId: options.invoke ? "lambder-invoke" : "lambder-local",
+            apiId: options.invoke ? LAMBDER_INVOKE_API_ID : LAMBDER_LOCAL_API_ID,
             domainName: request.host,
             domainPrefix: "",
             http: {
                 method: request.method,
-                path: request.path,
+                path: decodedPath,
                 protocol: "HTTP/1.1",
                 sourceIp: request.clientIp ?? "",
                 userAgent: options.invoke ? "lambder-invoke" : "lambder-local",
@@ -182,8 +200,8 @@ export const decodeLambdaHttpResult = async (result, maxBodyBytes) => {
     }
     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.
+        // proxy may set it, so it passes as a plain body; only other values
+        // fail the invoke.
         throw new Error(`the answer carries an unsupported Content-Encoding "${encoding}"`);
     }
     return {

package/dist/invoke/lambderHandlerTransport.d.ts

@@ -23,17 +23,16 @@ export type LambderHandlerTransportOptions = {
  * 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.
+ * since render() answers its own last-resort 500) produced no answer, so the
+ * call fails as `protocol` with the handler's own error as its cause. API
+ * Gateway would turn it into a bare 502, but synthesizing one here would
+ * throw the error away, and keeping it is the point of an in-process
+ * transport. An HTTP answer's only place for it would be the user-facing
+ * `message` field, 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.
+ * handler still runs to completion, because a function call in this process
+ * cannot be cancelled: a timeout buys the caller its answer, not the
+ * callee's attention.
  */
 export declare const lambderHandlerTransport: (handler: LambderHandler, options?: LambderHandlerTransportOptions) => LambderApiTransport;

package/dist/invoke/lambderHandlerTransport.js

@@ -15,18 +15,17 @@ const isAbortError = (err, signal) => signal !== undefined && signal.aborted &&
  * 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.
+ * since render() answers its own last-resort 500) produced no answer, so the
+ * call fails as `protocol` with the handler's own error as its cause. API
+ * Gateway would turn it into a bare 502, but synthesizing one here would
+ * throw the error away, and keeping it is the point of an in-process
+ * transport. An HTTP answer's only place for it would be the user-facing
+ * `message` field, 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.
+ * handler still runs to completion, because a function call in this process
+ * cannot be cancelled: a timeout buys the caller its answer, not the
+ * callee's attention.
  */
 export const lambderHandlerTransport = (handler, options = {}) => {
     const clientIp = options.clientIp ?? LOOPBACK_CLIENT_IP;
@@ -47,6 +46,7 @@ export const lambderHandlerTransport = (handler, options = {}) => {
             path: target.path,
             host,
             headers: request.headers,
+            contentType: "application/json",
             clientIp: request.clientIp ?? clientIp,
             cookies: request.cookies,
             body: JSON.stringify(buildTransportEnvelope({ ...request, siteHost: request.siteHost || host })),
@@ -58,18 +58,15 @@ export const lambderHandlerTransport = (handler, options = {}) => {
         catch (err) {
             if (isAbortError(err, request.signal))
                 throw err;
-            // The whole point of this transport is in-process integration
-            // testing, so the handler's own error is the useful part. A thrown
-            // handler answered nothing, and a transport failure is the one
-            // channel that carries a cause: swallowing it into a synthetic 502
-            // left the caller an outcome.error reading "Request failed: 502"
-            // and no way to reach what actually threw.
+            // A transport failure is the one channel that carries a cause. A
+            // synthetic 502 would leave the caller an outcome.error reading
+            // "Request failed: 502" and no way to reach what actually threw.
             throw new LambderTransportFailure("protocol", `the handler threw instead of answering: ${coerceToError(err).message}`, { cause: err });
         }
         // Decoding failures are the callee answering with something that is
         // not an HTTP result, or with more than the ceiling allows. Neither is
-        // a network failure, and reporting them as one sends whoever is
-        // debugging an integration test looking at their connection.
+        // a network failure, and reporting one as such would send whoever is
+        // debugging an integration test to look at their connection.
         let http;
         try {
             http = await decodeLambdaHttpResult(result, maxResponseBytes);

package/dist/mock/LambderMockApp.d.ts

@@ -13,13 +13,13 @@ import type { LambderMockAppOptions, LambderMockIdempotencyOptions, LambderMockT
 import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, LambderMockEntryInput, LambderMockFailure, LambderMockFailureReason, LambderMockHandler, LambderMockLatency, LambderMockListener, LambderMockPublicNames, LambderMockRateLimitPolicies, LambderMockRegistryCheck, LambderMockRestEntry, LambderMockSessionCallContext, LambderMockSessionNames, LambderMockSlice, LambderMockOverride } from "./LambderMockTypes.js";
 /**
  * The mock runtime: the API core (LambderApiPipeline, the same class the
- * Lambda server runs) over memory stores, with a registry of typed mock
- * handlers where the server has app handlers, and mock guards where it has
- * app guards. Everything the protocol does (envelope, refusals, sessions
- * and their cookies, guards, rate limits, idempotency, the signature gate)
- * happens in the core; this class only resolves a name to an entry, wraps
- * the handler's return into the envelope, and adds what a mock needs on
- * top: failure injection, latency, a subscription, a call log, reset.
+ * Lambda server runs) over memory stores, with typed mock handlers and mock
+ * guards where the server has app handlers and guards. Every protocol step
+ * (envelope, refusals, sessions and their cookies, guards, rate limits,
+ * idempotency, the signature gate) happens in the core; this class resolves
+ * a name to an entry, wraps the handler's return into the envelope, and adds
+ * what a mock needs: failure injection, latency, a subscription, a call log,
+ * reset.
  *
  * Create one with initLambderMock<Contract, SessionData>().create(...),
  * which fixes the contract and session types first so everything else is
@@ -34,12 +34,11 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     readonly tokenCookieKey: string;
     readonly csrfCookieKey: string;
     /**
-     * The client IP a transport request carrying none is read as. Public
-     * because an adapter has to read the same default the direct transport
-     * uses: the MSW adapter had a hardcoded "127.0.0.1" of its own, so an app
-     * that set defaultClientIp saw one address through the transport and
-     * another through the service worker, and a per-IP rate limit counted two
-     * clients where there was one.
+     * The client IP a transport request carrying none is read as. Public so
+     * every adapter reads the same default the direct transport uses: with a
+     * default of its own, an app that set defaultClientIp would show one
+     * address through the transport and another through the service worker,
+     * and a per-IP rate limit would count two clients where there is one.
      */
     readonly defaultClientIp: string;
     /** The host this runtime's cookies belong to (see the cookieHost option). */
@@ -47,9 +46,8 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     /**
      * The API core, every protocol step of it. Private: the mock's surface is
      * the app, and a consumer reaching past it would be configuring the
-     * server's pipeline through a development tool. The three adapters take
-     * what they need from the app's own methods (handleRequest,
-     * requestFromTransport), which is why none of them names this.
+     * server's pipeline through a development tool. The adapters use the
+     * app's own methods (handleRequest, requestFromTransport) instead.
      */
     private readonly pipeline;
     /** The cookie scope signIn plants under, so signOut can name the same one when it clears them. */
@@ -71,11 +69,10 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * the ones the server runs on a definition, and the mock's own "a session
      * endpoint needs the sessions option".
      *
-     * One place, so no registration path can skip either check. A session
-     * endpoint on a mock without sessions would otherwise register silently
-     * and answer the first call with a 500 from inside the pipeline, naming
-     * the SERVER's option name, for a mistake whose fix is one option at
-     * create().
+     * One place, so no registration path can skip either check. Without the
+     * second, a session endpoint on a mock without sessions would register
+     * silently and answer its first call with a 500 naming the SERVER's
+     * option, for a mistake fixed by one option at create().
      */
     private assertEntryRegistration;
     private buildEntry;
@@ -87,14 +84,13 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * A public endpoint deliberately left without a mock; a call answers the
      * notMocked refusal carrying the reason.
      *
-     * Public and session have separate builders for the same reason publicApi
-     * and sessionApi do: the refusal runs through the pipeline so that the
-     * steps BEFORE dispatch still happen, and the session read is one of them.
-     * Declaring every not-mocked endpoint public switched that step off, so a
-     * session endpoint with no session answered "not mocked" where the server
-     * answers sessionExpired, and the mode on its events and call log was
-     * wrong too. The mode cannot be recovered at runtime, because the contract
-     * is a type, so the builder is where it has to be said.
+     * Public and session get separate builders, as publicApi and sessionApi
+     * do, because the refusal runs through the pipeline so the steps BEFORE
+     * dispatch still happen, and the session read is one of them. Were every
+     * not-mocked endpoint public, a session endpoint with no session would
+     * answer "not mocked" where the server answers sessionExpired, and its
+     * events and call log would carry the wrong mode. The contract is a type,
+     * so the mode cannot be recovered at runtime: the builder has to say it.
      */
     notMocked<K extends LambderMockPublicNames<C>>(name: K, reason: string): LambderMockEntry<C, K>;
     /** A session endpoint deliberately left without a mock: the session is still read, and refused before the notMocked refusal. */
@@ -107,23 +103,21 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * mockApp.register(userMocks, billingMocks, mockApp.restNotMocked("not mocked yet"));
      * ```
      *
-     * What it buys is adoption over a contract the mocks do not cover yet:
-     * register() stays exhaustive by construction, and the endpoints nothing
-     * claims answer the notMocked refusal carrying this reason instead of
+     * It lets mocks be adopted over a contract they do not cover yet:
+     * register() stays exhaustive by construction, and endpoints nothing
+     * claims answer the notMocked refusal with this reason instead of
      * apiNotFound, so a screen that reaches one says "not mocked yet" rather
      * than "unknown error". Strays and duplicates in the explicit slices are
-     * refused exactly as they are without it, and an entry registered later
-     * (registerPartial, or a second register) takes the endpoint back from the
-     * rest.
+     * still refused, and an entry registered later (registerPartial, or a
+     * second register) takes its endpoint back from the rest.
      *
-     * The one thing it cannot do is the session read. A call it answers is
-     * processed as a public endpoint: the protocol's pre-pass still runs, so a
-     * stale client still hears versionExpired, but the mode of a name nothing
-     * registered is not knowable at runtime, the contract being a type. So a
-     * signed-out call to an unmocked session endpoint is answered "not mocked"
-     * where the server answers sessionExpired, and the endpoint whose
-     * signed-out path a test cares about is the one to declare with
-     * sessionNotMocked instead.
+     * What it cannot do is the session read. The mode of an unregistered name
+     * is not knowable at runtime (the contract is a type), so a call it
+     * answers is processed as public: the protocol's pre-pass still runs, so
+     * a stale client still hears versionExpired, but a signed-out call to an
+     * unmocked session endpoint answers "not mocked" where the server answers
+     * sessionExpired. Declare an endpoint whose signed-out path a test cares
+     * about with sessionNotMocked instead.
      */
     restNotMocked(reason: string): LambderMockRestEntry;
     private buildNotMockedEntry;
@@ -161,24 +155,20 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * Whether a call to this name would be answered from the registry, which
      * is what an adapter asks before passing one on.
      *
-     * True for every name once a rest entry is registered, because the rest
-     * entry is what answers the names nothing else claimed. That is what makes
-     * a rest entry and the MSW adapter's `onUnmocked: "passthrough"`
-     * alternatives rather than layers: with one registered, the runtime
-     * answers everything itself and nothing is handed on to the network.
+     * True for every name once a rest entry is registered, since it answers
+     * whatever nothing else claimed. That makes a rest entry and the MSW
+     * adapter's `onUnmocked: "passthrough"` alternatives rather than layers:
+     * with one registered, nothing is handed on to the network.
      */
     hasRegisteredEntry(apiName: string): boolean;
     private entryFor;
     /**
      * The entry that answers a name nothing registered, when register() was
      * given a rest entry: the notMocked refusal carrying its reason, run
-     * through the pipeline as a public endpoint.
-     *
-     * Public because the mode of an unregistered name cannot be recovered at
-     * runtime, the contract being a type. Everything that precedes dispatch
-     * still runs (the signature gate, the payload restore); the session read is
-     * the one step this answer cannot have, which is the fidelity limit
-     * restNotMocked documents.
+     * through the pipeline as a public endpoint, since the mode of an
+     * unregistered name cannot be recovered at runtime. Everything before
+     * dispatch still runs (the signature gate, the payload restore); the
+     * missing session read is the fidelity limit restNotMocked documents.
      */
     private restNotMockedEntry;
     /** The next call to the endpoint fails this way; several calls queue in order. */
@@ -194,30 +184,24 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * latency, the call log and its numbering, the cookies its own transports
      * hold, then onReset, so the app rewinds its own data too.
      *
-     * The cookies matter as much as the sessions do: emptying the session
-     * store while a jar still holds the token for one of them leaves the next
-     * call carrying a session that no longer exists, which reads as signed in
-     * until the answer says sessionExpired. So every jar transport() built
-     * for itself is emptied, and the cookies a "document" transport mirrored
-     * are expired again.
+     * The cookies matter as much as the sessions: a jar still holding the
+     * token of an emptied store's session reads as signed in until an answer
+     * says sessionExpired. So every jar transport() built for itself is
+     * emptied, and the cookies a "document" transport mirrored are expired.
      *
-     * The registry survives, being what the runtime was configured with
-     * rather than what it accumulated. Subscriptions survive too, because
-     * they are how a test watches the runtime rather than state it is
-     * testing; a listener muted for throwing is unmuted, so one bad call does
-     * not silence it for the rest of the run. A session store or a cookie jar
-     * the app supplied itself survives: the runtime did not create it and
-     * does not know what else holds it.
+     * The registry survives, being configuration rather than accumulated
+     * state. Subscriptions survive too, being how a test watches the runtime;
+     * a listener muted for throwing is unmuted, so one bad call does not
+     * silence it for the rest of the run. A session store or cookie jar the
+     * app supplied survives: the runtime did not create it and does not know
+     * what else holds it.
      */
     reset(): void;
     /**
      * The four session members refuse in the mock's own words, naming the
-     * option a mock is created with.
-     *
-     * The pipeline's guard says "Configure the session option at creation",
-     * which is the SERVER's option name: the mock's is `sessions`, and a
-     * reader who goes looking for `session` on create() does not find it.
-     * The registration path was fixed for exactly this one method over.
+     * option a mock is created with. The pipeline's guard names the SERVER's
+     * option (`session`), which a reader does not find on the mock's create()
+     * (`sessions`); assertEntryRegistration does the same for registration.
      */
     private assertSessionsConfigured;
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when sessions are off. */
@@ -301,9 +285,9 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     /**
      * Takes a jar an adapter built for itself as the runtime's own, so reset()
      * empties it with the rest. The MSW adapter's jar holds the session
-     * cookies of calls that never touch transport(), and a reset that leaves
-     * it full is the same stale-session bug: the store is empty and the next
-     * request still carries a token for one of its sessions.
+     * cookies of calls that never touch transport(); left full after a reset,
+     * the next request would carry a token for a session the emptied store no
+     * longer has.
      */
     adoptCookieJar(jar: LambderCookieJar): void;
     /** caller.setTransport(mockApp.transport(options)); returns the transport, its jar on it. */
@@ -341,12 +325,12 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
      * The mock app, with the guard map and the rate-limit policies inferred
      * from the options.
      *
-     * `const` on each of them is what pins a restatement to the contract, and
-     * it has one cost: inferring a generic from an object literal switches
-     * excess-property checking off for the whole literal, nested objects
-     * included, so a typo inside `rateLimits.policies` or `idempotency`
-     * compiled and was dropped in silence. `I` exists for the same reason `P`
-     * does, and LambderMockSurplusKeys puts the error back on the key.
+     * `const` on each of them pins a restatement to the contract, at a cost:
+     * inferring a generic from an object literal switches excess-property
+     * checking off for the whole literal, nested objects included, so a typo
+     * inside `rateLimits.policies` or `idempotency` would compile and be
+     * dropped. `I` exists for the same reason `P` does, and
+     * LambderMockSurplusKeys puts the error back on the key.
      */
     create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>>(options: LambderMockAppOptions<C, S, G, P, I>): LambderMockApp<C, S, G>;
 };