lambder 6.0.2 → 7.0.1

package/dist/core/Lambder.js

@@ -1,17 +1,20 @@
 import LambderResolver from "./LambderResolver.js";
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
-import { LambderResponse, finalizeResponse, DEFAULT_FINALIZE_OPTIONS, DEFAULT_RESPONSE_COMPRESSION_SETTINGS, } from "./LambderResponse.js";
+import { LambderResponse, finalizeResponse, answerFromResponse, responseFromAnswer, emitResponse, DEFAULT_FINALIZE_OPTIONS, DEFAULT_RESPONSE_COMPRESSION_SETTINGS, } from "./LambderResponse.js";
 import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
-import { resolveCompressionOption } from "../shared/LambderCompressionOption.js";
-import LambderSessionController from "../session/LambderSessionController.js";
+import { resolveCompressionOption } from "../shared/wire/LambderCompressionOption.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
+import { LambderIndexHtmlHandler } from "./LambderIndexHtml.js";
 import { LambderFiles } from "./LambderFiles.js";
-import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
-import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
-import { createContext, isV2HttpEvent, restoreCompressedApiPayload } from "./LambderContext.js";
-import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/LambderRequestPayload.js";
+import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
+import { apiNotFoundAnswer, crashAnswer, refusalAnswer, } from "../api/LambderApiEnvelope.js";
+import { createContext, isV2HttpEvent } from "./LambderContext.js";
+import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
+import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
+import { assertCreateOptions, } from "./LambderCreateOptions.js";
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -25,6 +28,7 @@ import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/LambderRequestPayl
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
  * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
+ * @typeParam _TSessionsEnabled - @internal True when create() received the session option (do not pass manually). It defaults to TRUE, unlike its siblings: a plugin module annotates its parameter as the bare Lambder<SessionData>, and that annotation has to keep registering session APIs. create() is where the option is actually known, so create() is where the false comes from; `new Lambder(...)` keeps only the registration-time throw.
  *
  * @example
  * ```typescript
@@ -36,6 +40,10 @@ import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/LambderRequestPayl
  * ```
  */
 export default class Lambder {
+    // =====================================================================
+    // Construction
+    // Everything an instance is, fixed before the first registration.
+    // =====================================================================
     apiPath;
     apiVersion;
     /** The instance's file reader (source + caches), or null without the files option. */
@@ -52,7 +60,8 @@ export default class Lambder {
      */
     ApiContract;
     actionList = [];
-    apiPolicyEngine = null;
+    /** The API core: the pipeline every API call runs through, shared in shape with the mock runtime. */
+    pipeline;
     registeredApiNames = new Set();
     hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
     createdHooks = [];
@@ -63,18 +72,15 @@ export default class Lambder {
     apiInputValidationErrorHandler = null;
     sessionExpiredRouteHandler = null;
     publicFilesHandler = null;
-    indexHtmlConfig = null;
+    indexHtmlHandler = null;
     eventActionList = [];
     corsConfig = null;
     finalizeOptions;
-    maxRequestPayloadBytes;
     requireSessionApiGuards;
+    trustedClientIpHeaders;
     requirePublicApiGuards;
-    lambderSessionManager;
-    sessionCookieOptions = {};
-    sessionTokenCookieKey = "LMDRSESSIONTKID";
-    sessionCsrfCookieKey = "LMDRSESSIONCSTK";
     constructor(options = {}) {
+        assertCreateOptions(options);
         this.files = options.files ? new LambderFiles(options.files) : null;
         this.apiPath = options.apiPath ?? "/api";
         this.apiVersion = options.apiVersion ?? null;
@@ -85,45 +91,43 @@ export default class Lambder {
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
-        this.maxRequestPayloadBytes = options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES;
-        if (!Number.isSafeInteger(this.maxRequestPayloadBytes) || this.maxRequestPayloadBytes <= 0) {
-            throw new Error("maxRequestPayloadBytes must be a positive integer");
-        }
         if (options.cors !== undefined && options.cors !== false) {
             this.corsConfig = options.cors === true ? {} : options.cors;
         }
-        if (options.session) {
-            const session = options.session;
-            this.lambderSessionManager = new LambderSessionManager({
-                tableName: session.tableName,
-                tableRegion: session.tableRegion,
-                partitionKey: session.partitionKey ?? "pk",
-                sortKey: session.sortKey ?? "sk",
-                sessionSalt: session.sessionSalt,
-                enableSlidingExpiration: session.enableSlidingExpiration,
-                slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
-                dataRefresh: session.dataRefresh,
-                compression: session.compression,
-            });
-            this.sessionCookieOptions = session.cookie ?? {};
-            if (session.tokenCookieKey)
-                this.sessionTokenCookieKey = session.tokenCookieKey;
-            if (session.csrfCookieKey)
-                this.sessionCsrfCookieKey = session.csrfCookieKey;
-        }
-        if (options.rateLimits)
-            this.getOrCreatePolicyEngine().setRateLimits(options.rateLimits);
-        if (options.guards)
-            this.getOrCreatePolicyEngine().addGuards(options.guards);
-        if (options.idempotency)
-            this.getOrCreatePolicyEngine().setIdempotency(options.idempotency);
+        const session = options.session;
+        this.pipeline = new LambderApiPipeline({
+            apiVersion: this.apiVersion,
+            maxRequestPayloadBytes: options.maxRequestPayloadBytes,
+            // The app's own validation handler is read at call time, since
+            // setApiInputValidationErrorHandler runs after creation.
+            onInvalidInput: (zodError, ctx) => this.inputValidationRefusal(ctx, zodError),
+            sessions: session
+                ? {
+                    manager: new LambderSessionManager({
+                        store: session.store,
+                        sessionSalt: session.sessionSalt,
+                        enableSlidingExpiration: session.enableSlidingExpiration,
+                        slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
+                        dataRefresh: session.dataRefresh,
+                        crypto: session.crypto,
+                    }),
+                    tokenCookieKey: session.tokenCookieKey,
+                    csrfCookieKey: session.csrfCookieKey,
+                    cookieOptions: session.cookie,
+                }
+                : undefined,
+            rateLimits: options.rateLimits,
+            guards: options.guards,
+            idempotency: options.idempotency,
+        });
+        this.trustedClientIpHeaders = options.trustedClientIpHeaders ?? [];
         this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
         this.requirePublicApiGuards = options.requirePublicApiGuards ?? false;
-        const requireFlag = this.requireSessionApiGuards ? "requireSessionApiGuards" : "requirePublicApiGuards";
-        if ((this.requireSessionApiGuards || this.requirePublicApiGuards) && !options.guards) {
-            throw new Error(`Lambder: ${requireFlag} needs a guards map at creation for APIs to declare from.`);
-        }
     }
+    // =====================================================================
+    // Registration
+    // What an app declares on the instance; all of it chains.
+    // =====================================================================
     setRouteFallbackHandler(routeFallbackHandler) {
         this.routeFallbackHandler = routeFallbackHandler;
         return this;
@@ -148,15 +152,16 @@ export default class Lambder {
     /**
      * Terminal public-file layer. Runs only when no route matched, so it can
      * never shadow routes registered after it. Serves files from the `files`
-     * source configured at creation, traversal-safe, mime-typed,
+     * source configured at creation, under the reader's path rule, mime-typed,
      * memory-cached, with the immutable-cache heuristic for content-hashed
-     * assets; when the source has no such file the request falls through to
-     * setRouteFallbackHandler, where the app decides what remains (e.g.
-     * render an app shell with res.templateFile).
+     * assets. Only configured methods reach it, default GET/HEAD, as for
+     * serveIndexHtml; a gated-out method and a path the source has no file
+     * for both fall through to setRouteFallbackHandler, where the app decides
+     * what remains (e.g. render an app shell with res.templateFile).
      */
     servePublicFiles(options = {}) {
         if (!this.files)
-            throw new Error("servePublicFiles requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))");
+            throw new Error("Lambder: servePublicFiles requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))");
         this.publicFilesHandler = new LambderPublicFilesHandler(this.files, options);
         return this;
     }
@@ -170,78 +175,9 @@ export default class Lambder {
      * res.templateFile (markers optional) with no-cache.
      */
     serveIndexHtml(handler, options = {}) {
-        this.indexHtmlConfig = { handler: handler ?? null, options };
+        this.indexHtmlHandler = new LambderIndexHtmlHandler(handler ?? null, options);
         return this;
     }
-    /** Apply the serveIndexHtml gates; null means fall through. */
-    async tryServeIndexHtml(ctx, resolver) {
-        if (!this.indexHtmlConfig)
-            return null;
-        const { handler, options } = this.indexHtmlConfig;
-        const methods = (options.methods ?? ["GET", "HEAD"]).map((m) => m.toUpperCase());
-        if (!methods.includes(ctx.method.toUpperCase()))
-            return null;
-        if ((options.skipFilePaths ?? false) && (ctx.path.split("/").pop() ?? "").includes("."))
-            return null;
-        if (options.redirectTrailingSlash && ctx.path.length > 1 && ctx.path.endsWith("/")) {
-            const target = ctx.path.replace(/\/+$/, "") || "/";
-            return resolver.redirect(target + buildQueryString(ctx), 301);
-        }
-        const response = handler
-            ? await handler(ctx, resolver)
-            : await resolver.templateFile(typeof options.indexFile === "function" ? options.indexFile(ctx) : (options.indexFile ?? "index.html"), {}, { cacheControl: "no-cache" });
-        if (options.compress !== undefined) {
-            response.compress = typeof options.compress === "function" ? options.compress(ctx) : options.compress;
-        }
-        return response;
-    }
-    getOrCreatePolicyEngine() {
-        // Late-bound: the handler may be set after creation, so the engine
-        // asks at request time rather than capturing it here.
-        if (!this.apiPolicyEngine)
-            this.apiPolicyEngine = new LambderApiPolicyEngine((ctx, resolver, zodError) => this.inputValidationRefusal(ctx, resolver, zodError));
-        return this.apiPolicyEngine;
-    }
-    /**
-     * The response for a rejected input: the app's
-     * setApiInputValidationErrorHandler when set, otherwise the standard 422
-     * body. The API's own schema and every preflight slice (guard inputs,
-     * rate-limit keys) answer through here, so one failure has one shape.
-     */
-    async inputValidationRefusal(ctx, resolver, zodError) {
-        if (this.apiInputValidationErrorHandler)
-            return await this.apiInputValidationErrorHandler(ctx, resolver, zodError);
-        // Spelled out rather than serialized as-is: zod 4 keeps `issues` as a
-        // non-enumerable property, so JSON.stringify(zodError) would carry the
-        // issues only inside the message string, and a client's validation
-        // handler would receive a ZodError with nothing to branch on.
-        return resolver.json({
-            error: "Input validation failed",
-            zodError: { name: zodError.name, message: zodError.message, issues: zodError.issues },
-        }, { statusCode: 422 });
-    }
-    /** Registration-time checks shared by addApi/addSessionApi. */
-    assertApiRegistration(name, mode, options) {
-        if (this.registeredApiNames.has(name)) {
-            throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
-        }
-        this.registeredApiNames.add(name);
-        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
-        if (guardsRequired && options.guards === undefined) {
-            const optOut = mode === "session"
-                ? "the named no-op guard that marks the session itself as the whole authorization"
-                : "the named no-op guard that records why anyone may call it";
-            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
-                `Declare the guard that authorizes it, or ${optOut}.`);
-        }
-        const usesPolicies = options.rateLimit !== undefined || options.guards !== undefined || options.idempotency !== undefined;
-        if (!usesPolicies)
-            return;
-        if (!this.apiPolicyEngine) {
-            throw new Error(`Lambder: API "${name}" declares rateLimit/guards/idempotency, but none of rateLimits/guards/idempotency was configured at creation.`);
-        }
-        this.apiPolicyEngine.assertRegistration(name, mode, options);
-    }
     addRoute(condition, actionFn) {
         this.actionList.push({
             match: compileRouteMatcher(condition),
@@ -254,96 +190,33 @@ export default class Lambder {
             match: compileRouteMatcher(condition),
             actionFn: async (ctx, resolver) => {
                 await this.requireSession(ctx, resolver);
+                // requireSession answered already if there was no session, so
+                // the only narrowing left is null to non-null.
                 return await actionFn(ctx, resolver);
             },
         });
         return this;
     }
-    // Plugin system
-    // The policy generics are `any` in the plugin signature on purpose: a
-    // module may annotate its parameter as the bare Lambder<SessionData> or
-    // as the app's narrowed alias, and both must chain. Registration-time
-    // assertions still verify every referenced policy/guard name at runtime.
-    // Every policy generic must be listed here: one short of the class's
-    // parameter list and the missing one silently falls back to its default,
-    // which makes an instance carrying the non-default value unassignable to
-    // its own plugins (requireSessionApiGuards did exactly that in 4.7.1).
-    use(plugin) {
-        return plugin(this);
-    }
     // Typed API with Zod
     addApi(name, schema, handler) {
         this.assertApiRegistration(name, "public", schema);
+        const definition = { name, mode: "public", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input };
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
-            actionFn: async (ctx, resolver) => {
-                // Replay fast path first: a completed idempotent request must
-                // answer its stored response without burning rate-limit quota
-                // or re-running guards (no handler executes either way).
-                if (this.apiPolicyEngine && schema.idempotency) {
-                    const replay = await this.apiPolicyEngine.findReplay(name, ctx);
-                    if (replay)
-                        return replay;
-                }
-                if (this.apiPolicyEngine)
-                    await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
-                const inputResult = schema.input.safeParse(ctx.apiPayload);
-                if (!inputResult.success)
-                    return await this.inputValidationRefusal(ctx, resolver, inputResult.error);
-                ctx.apiPayload = inputResult.data;
-                const run = async () => await handler(ctx, resolver);
-                if (this.apiPolicyEngine && schema.idempotency)
-                    return await this.apiPolicyEngine.withIdempotency(name, ctx, schema.idempotency, run);
-                return await run();
-            },
+            actionFn: (ctx, resolver) => this.runApi(ctx, resolver, definition, handler),
         });
         return this;
     }
     // Typed Session API with Zod
     addSessionApi(name, schema, handler) {
         this.assertApiRegistration(name, "session", schema);
+        const definition = { name, mode: "session", guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input };
         this.actionList.push({
             match: (ctx) => ctx.apiName === name ? {} : false,
-            actionFn: async (ctx, resolver) => {
-                await this.requireSession(ctx, resolver);
-                // Replay fast path (after the session fetch: the replay scope
-                // is keyed per session): see addApi.
-                if (this.apiPolicyEngine && schema.idempotency) {
-                    const replay = await this.apiPolicyEngine.findReplay(name, ctx);
-                    if (replay)
-                        return replay;
-                }
-                if (this.apiPolicyEngine)
-                    await this.apiPolicyEngine.runPreflight(name, ctx, resolver, schema);
-                const inputResult = schema.input.safeParse(ctx.apiPayload);
-                if (!inputResult.success)
-                    return await this.inputValidationRefusal(ctx, resolver, inputResult.error);
-                ctx.apiPayload = inputResult.data;
-                const run = async () => await handler(ctx, resolver);
-                if (this.apiPolicyEngine && schema.idempotency)
-                    return await this.apiPolicyEngine.withIdempotency(name, ctx, schema.idempotency, run);
-                return await run();
-            }
+            actionFn: (ctx, resolver) => this.runApi(ctx, resolver, definition, handler),
         });
         return this;
     }
-    /**
-     * Fetch the session or short-circuit the request: API calls get the
-     * protocol's { sessionExpired: true } response (handled by LambderCaller),
-     * routes get the sessionExpiredRouteHandler response (default 401).
-     */
-    async requireSession(ctx, resolver) {
-        const session = await this.getSessionController(ctx).fetchSessionIfExists();
-        if (!session) {
-            if (ctx._otherInternal.isApiCall) {
-                throw resolver.api(null, { sessionExpired: true });
-            }
-            if (this.sessionExpiredRouteHandler) {
-                throw await this.sessionExpiredRouteHandler(ctx, resolver);
-            }
-            throw resolver.status(401, "Session required.");
-        }
-    }
     addHook(hookEvent, hookFn, priority = 0) {
         if (hookEvent === "created") {
             // Runs once, lazily, at the first render() call.
@@ -355,16 +228,53 @@ export default class Lambder {
         }
         return this;
     }
-    getSessionController(ctx) {
-        if (!this.lambderSessionManager)
-            throw new Error("Session is not enabled. Configure the session option at creation.");
-        return new LambderSessionController({
-            lambderSessionManager: this.lambderSessionManager,
-            sessionTokenCookieKey: this.sessionTokenCookieKey,
-            sessionCsrfCookieKey: this.sessionCsrfCookieKey,
-            cookieOptions: this.sessionCookieOptions,
-            ctx,
+    addAction(filter, actionFn) {
+        // HTTP side: joins the route/API chain in registration order.
+        this.actionList.push({
+            match: (ctx) => filter(ctx.event, ctx) ? {} : false,
+            actionFn: async (ctx, resolver) => {
+                const result = await actionFn(ctx.event, { ctx, res: resolver, lambdaContext: ctx.lambdaContext });
+                if (!(result instanceof LambderResponse)) {
+                    throw new Error("Lambder: an addAction matched an HTTP request but did not return a response. Build one with tools.res.");
+                }
+                return result;
+            },
+        });
+        // Non-HTTP side.
+        this.eventActionList.push({
+            match: (event) => filter(event, null),
+            actionFn: (event, lambdaContext) => actionFn(event, { ctx: null, res: null, lambdaContext }),
         });
+        return this;
+    }
+    // Plugin system
+    // The policy generics are `any` in the plugin signature on purpose: a
+    // module may annotate its parameter as the bare Lambder<SessionData> or
+    // as the app's narrowed alias, and both must chain. Registration-time
+    // assertions still verify every referenced policy/guard name at runtime.
+    // Every policy generic must be listed here: one short of the class's
+    // parameter list and the missing one silently falls back to its default,
+    // which makes an instance carrying the non-default value unassignable to
+    // its own plugins.
+    use(plugin) {
+        return plugin(this);
+    }
+    // =====================================================================
+    // Accessors
+    // What a handler or an app asks the instance for.
+    // =====================================================================
+    /**
+     * Sessions for this request: what handlers create, rotate, refresh and
+     * end sessions with. An API call presents its posted CSRF token; a route
+     * presents cookies alone.
+     */
+    getSessionController(ctx) {
+        const context = ctx;
+        return this.pipeline.sessionController(context, context.api ? LambderApiPipeline.sessionInfoOf(context.api) : { host: context.host, cookies: context.cookieList, csrfToken: null });
+    }
+    /** The session manager, for code that works on sessions outside a request (maintenance, tests). */
+    getSessionManager() {
+        return this.pipeline.sessionManager;
     }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
@@ -382,25 +292,11 @@ export default class Lambder {
         });
     }
     ;
-    /** Map a thrown LambderApiError onto the structured API envelope. */
-    apiErrorResponse(err, resolver) {
-        return resolver.api(null, {
-            ...(err.errorMessage !== undefined ? { errorMessage: err.errorMessage } : {}),
-            ...(err.notAuthorized ? { notAuthorized: true } : {}),
-            ...(err.sessionExpired ? { sessionExpired: true } : {}),
-        }, {
-            ...(err.statusCode !== undefined ? { statusCode: err.statusCode } : {}),
-            ...(err.headers ? { headers: err.headers } : {}),
-        });
-    }
     getHandler() {
         return ((event, context) => Lambder.isHttpEvent(event)
             ? this.render(event, context)
             : this.renderEvent(event, context));
     }
-    // ---------------------------------------------------------------------
-    // Actions (raw-event or context filtering; the only handler for non-HTTP)
-    // ---------------------------------------------------------------------
     /** True when the Lambda event is an API Gateway HTTP event (REST API v1 or HTTP API / Function URL v2). */
     static isHttpEvent(event) {
         if (!event || typeof event !== "object")
@@ -409,99 +305,113 @@ export default class Lambder {
             return true;
         return isV2HttpEvent(event);
     }
-    addAction(filter, actionFn) {
-        // HTTP side: joins the route/API chain in registration order.
-        this.actionList.push({
-            match: (ctx) => filter(ctx.event, ctx) ? {} : false,
-            actionFn: async (ctx, resolver) => {
-                const result = await actionFn(ctx.event, { ctx, res: resolver, lambdaContext: ctx.lambdaContext });
-                if (!(result instanceof LambderResponse)) {
-                    throw new Error("Lambder: an addAction matched an HTTP request but did not return a response. Build one with tools.res.");
-                }
-                return result;
-            },
-        });
-        // Non-HTTP side.
-        this.eventActionList.push({
-            match: (event) => filter(event, null),
-            actionFn: (event, lambdaContext) => actionFn(event, { ctx: null, res: null, lambdaContext }),
-        });
-        return this;
-    }
-    /** Dispatch a non-HTTP Lambda event to the registered actions. */
-    async renderEvent(event, lambdaContext) {
-        await this.ensureInitialized();
-        for (const action of this.eventActionList) {
-            if (action.match(event)) {
-                return await action.actionFn(event, lambdaContext);
-            }
-        }
-        const summary = event && typeof event === "object"
-            ? ` (source: ${String(event.source ?? "?")}, detail-type: ${String(event["detail-type"] ?? "?")})`
-            : "";
-        throw new Error(`Lambder: no action matched non-HTTP event${summary}. Register one with addAction(); a trailing addAction(() => true, ...) acts as a fallback.`);
-    }
-    // ---------------------------------------------------------------------
-    // Render pipeline
-    // ---------------------------------------------------------------------
+    // =====================================================================
+    // The request path
+    // One HTTP invocation, from the event to the finalized response.
+    // =====================================================================
     ensureInitialized() {
         if (!this.initPromise) {
-            this.initPromise = (async () => {
+            const pending = (async () => {
                 for (const hookFn of this.createdHooks) {
                     await hookFn(this);
                 }
             })();
+            this.initPromise = pending;
+            // A `created` hook usually reaches something that can be briefly
+            // unavailable (a first DynamoDB read, a secret fetch). Keeping the
+            // rejected promise meant the warm container answered every later
+            // invocation with the first failure and never recovered, so the
+            // failure is forgotten and the next invocation runs the hooks
+            // again. Whoever is awaiting this one still gets the rejection.
+            pending.catch(() => { if (this.initPromise === pending)
+                this.initPromise = null; });
         }
         return this.initPromise;
     }
     applyCors(ctx, response, isPreflight) {
         applyCorsHeaders(this.corsConfig, ctx, response, isPreflight);
     }
+    /**
+     * The beforeRender hooks, in priority order: the replaced context to
+     * continue with, or the response one of them answered with.
+     *
+     * Its own method because BOTH request paths run it. Left inline after the
+     * match, it ran for routes and APIs and for nothing else, so a
+     * servePublicFiles or serveIndexHtml answer, which is every asset and
+     * every app-shell page, skipped the one hook that can inspect a request,
+     * replace its context or short-circuit it: a security header written in a
+     * hook reached the API answers and not the HTML it was written for, and a
+     * maintenance-mode hook served the whole frontend anyway.
+     */
+    async runBeforeRenderHooks(ctx, resolver) {
+        let currentCtx = ctx;
+        for (const hook of this.hookList["beforeRender"]) {
+            const hookResult = await hook.hookFn(currentCtx, resolver);
+            if (hookResult instanceof Error)
+                throw hookResult;
+            if (hookResult instanceof LambderResponse)
+                return hookResult;
+            currentCtx = hookResult;
+        }
+        return currentCtx;
+    }
     async handleNoMatchedAction(ctx, resolver) {
+        // Before the fallback hooks, and with the same power it has on a
+        // matched route: the fallback hooks are typed void and cannot answer.
+        const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver);
+        if (beforeRenderResult instanceof LambderResponse)
+            return beforeRenderResult;
+        const currentCtx = beforeRenderResult;
         for (const hook of this.hookList["fallback"]) {
-            await hook.hookFn(ctx, resolver);
+            await hook.hookFn(currentCtx, resolver);
         }
-        const isAPI = ctx._otherInternal.isApiCall || ctx.path === this.apiPath;
+        const isAPI = currentCtx.api !== null || currentCtx.path === this.apiPath;
         if (isAPI) {
             if (this.apiFallbackHandler)
-                return await this.apiFallbackHandler(ctx, resolver);
-            return resolver.api(null, { errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.apiNotFound, content: "API not found." } });
+                return await this.apiFallbackHandler(currentCtx, resolver);
+            return responseFromAnswer(currentCtx.api ? this.pipeline.answerUnknownApi(currentCtx.api, currentCtx) : apiNotFoundAnswer(this.apiVersion, currentCtx.logList));
         }
         if (this.publicFilesHandler) {
-            const fileResponse = await this.publicFilesHandler.handle(ctx);
+            const fileResponse = await this.publicFilesHandler.handle(currentCtx);
             if (fileResponse)
                 return fileResponse;
         }
-        const indexResponse = await this.tryServeIndexHtml(ctx, resolver);
+        const indexResponse = this.indexHtmlHandler ? await this.indexHtmlHandler.handle(currentCtx, resolver) : null;
         if (indexResponse)
             return indexResponse;
         if (this.routeFallbackHandler)
-            return await this.routeFallbackHandler(ctx, resolver);
+            return await this.routeFallbackHandler(currentCtx, resolver);
         return resolver.text("Not found.", { statusCode: 404 });
     }
+    /**
+     * True for the OPTIONS request the CORS layer answers by itself. Asked
+     * twice: once to build the 204, once at the end of render() to decide
+     * which form of the headers goes on. Asking once and letting the tail
+     * apply the ordinary headers on top of the 204's would put both forms on
+     * a preflight, answering `Vary: Origin, Origin` and an
+     * Access-Control-Expose-Headers that means nothing before a request.
+     */
+    isCorsPreflight(ctx) {
+        return ctx.method === "OPTIONS" && !!this.corsConfig;
+    }
     async resolveRequest(ctx, resolver) {
-        if (ctx.method === "OPTIONS" && this.corsConfig) {
-            const preflight = new LambderResponse({ statusCode: 204, body: null });
-            this.applyCors(ctx, preflight, true);
-            return preflight;
-        }
-        // Version check if provided by both the client and the server
-        if (this.apiVersion && ctx._otherInternal.requestVersion && ctx._otherInternal.requestVersion !== this.apiVersion) {
-            return resolver.versionExpired();
-        }
-        // A gzipped payload is restored before anything reads it: rate-limit
-        // key slices, guards and input validation all see a plain payload.
-        if (ctx._otherInternal.isApiCall) {
-            const restored = await restoreCompressedApiPayload(ctx, this.maxRequestPayloadBytes);
-            if (!restored.ok) {
-                return resolver.api(null, {
-                    errorMessage: {
-                        type: "error",
-                        code: LAMBDER_REFUSAL_CODES.invalidRequestPayload,
-                        content: restored.message,
-                    },
-                }, { statusCode: 400 });
-            }
+        if (this.isCorsPreflight(ctx))
+            return new LambderResponse({ statusCode: 204, body: null });
+        if (ctx.api) {
+            // The protocol's own pre-pass, run here rather than left to the
+            // pipeline so that hooks and route matching see a plain payload,
+            // and so a stale client is answered before any of them, whether or
+            // not the name it asked for exists.
+            const prepared = await this.pipeline.prepare(ctx.api);
+            if (prepared)
+                return responseFromAnswer(prepared);
+            // ctx.post is the raw body view; it shows the restored payload and
+            // none of the wire fields, so nothing reading it sees the format.
+            ctx.apiPayload = ctx.api.payload;
+            ctx.post.payload = ctx.api.payload;
+            delete ctx.post[COMPRESSED_PAYLOAD_GZ_FIELD];
+            delete ctx.post[COMPRESSED_PAYLOAD_BR_FIELD];
+            delete ctx.post[COMPRESSED_PAYLOAD_BYTES_FIELD];
         }
         let matched = null;
         for (const action of this.actionList) {
@@ -513,23 +423,19 @@ export default class Lambder {
         }
         if (!matched)
             return await this.handleNoMatchedAction(ctx, resolver);
+        // Set before the hooks run, so a beforeRender hook on a matched route
+        // sees the route's own path params.
         ctx.pathParams = matched.params;
-        let currentCtx = ctx;
-        for (const hook of this.hookList["beforeRender"]) {
-            const hookResult = await hook.hookFn(currentCtx, resolver);
-            if (hookResult instanceof Error)
-                throw hookResult;
-            if (hookResult instanceof LambderResponse)
-                return hookResult;
-            currentCtx = hookResult;
-        }
-        return await matched.action.actionFn(currentCtx, resolver);
+        const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver);
+        if (beforeRenderResult instanceof LambderResponse)
+            return beforeRenderResult;
+        return await matched.action.actionFn(beforeRenderResult, resolver);
     }
     async render(event, lambdaContext) {
         let ctx = null;
         try {
             await this.ensureInitialized();
-            ctx = createContext(event, lambdaContext, this.apiPath);
+            ctx = createContext(event, lambdaContext, this.apiPath, this.trustedClientIpHeaders);
             const resolver = this.getResolver(ctx);
             let response;
             try {
@@ -540,15 +446,23 @@ export default class Lambder {
                 if (err instanceof LambderResponse) {
                     response = err;
                 }
-                // A thrown LambderApiError on an API call IS a structured refusal
+                // A thrown LambderApiRefusal on an API call IS a structured refusal
                 // (brand-checked, not instanceof, to survive duplicate installs).
-                else if (isLambderApiError(err) && ctx._otherInternal.isApiCall) {
-                    response = this.apiErrorResponse(err, resolver);
+                else if (isLambderApiRefusal(err) && ctx.api) {
+                    response = this.apiErrorResponse(err, ctx);
                 }
                 else {
                     throw err;
                 }
             }
+            // What the call wrote goes on BEFORE the hooks run, so an
+            // afterRender hook can override or delete a header the handler
+            // wrote: replaying the operations afterwards put the handler's
+            // value straight back, and a hook could not win an argument it
+            // was the last to speak in.
+            const responseIntoHooks = response;
+            const headersAppliedIntoHooks = ctx.responseHeaders.size;
+            ctx.responseHeaders.applyTo(response);
             try {
                 for (const hook of this.hookList["afterRender"]) {
                     const hookResponse = await hook.hookFn(ctx, resolver, response);
@@ -561,54 +475,196 @@ export default class Lambder {
                 if (err instanceof LambderResponse) {
                     response = err;
                 }
-                else if (isLambderApiError(err) && ctx._otherInternal.isApiCall) {
-                    response = this.apiErrorResponse(err, resolver);
+                else if (isLambderApiRefusal(err) && ctx.api) {
+                    response = this.apiErrorResponse(err, ctx);
                 }
                 else {
                     throw err;
                 }
             }
-            // Apply setHeader, addHeader values.
-            for (const header of ctx._otherInternal.setHeaderFnAccumulator) {
-                response.setHeader(header.key, header.value);
-            }
-            for (const header of ctx._otherInternal.addHeaderFnAccumulator) {
-                response.addHeader(header.key, header.value);
-            }
-            this.applyCors(ctx, response, false);
-            return await finalizeResponse(ctx, response, this.finalizeOptions, ctx._otherInternal.eventFormat);
+            // Only what the hooks themselves wrote (res.setHeader inside a
+            // hook) is left to apply, which is what leaves their overrides
+            // standing. A hook that answered with a DIFFERENT response takes
+            // the whole set instead: headers belong to the call rather than to
+            // the response that first carried them, so the session cookie the
+            // call wrote has to travel across to it.
+            ctx.responseHeaders.applyTo(response, response === responseIntoHooks ? headersAppliedIntoHooks : 0);
+            this.applyCors(ctx, response, this.isCorsPreflight(ctx));
+            return await finalizeResponse(ctx, response, this.finalizeOptions, ctx.eventFormat);
         }
         catch (err) {
-            const wrappedError = err instanceof Error ? err : new Error("Error: " + String(err));
+            // Describing the thrown value can itself throw: an object with a
+            // null prototype, a Proxy, or a throwing toString/Symbol.toPrimitive.
+            // Coercing it unguarded in the FIRST statement of the last-resort
+            // catch made the catch throw, so the error handler never ran, no
+            // envelope was produced, and the invocation rejected with a 502 no
+            // client could parse. coerceToError is the shared version of that
+            // care, the one every site in the framework now uses.
+            const wrappedError = coerceToError(err, "an unstringifiable thrown value");
             // ctx may be null (createContext failed): derive the format from the raw event.
-            const eventFormat = ctx?._otherInternal.eventFormat ?? (isV2HttpEvent(event) ? "v2" : "v1");
+            const eventFormat = ctx?.eventFormat ?? (isV2HttpEvent(event) ? "v2" : "v1");
             try {
                 if (this.globalErrorHandler) {
                     const responseBuilder = this.getResponseBuilder(ctx ?? undefined);
-                    const errorResponse = await this.globalErrorHandler(wrappedError, ctx, responseBuilder, ctx?._otherInternal.logToApiResponseAccumulator);
+                    const errorResponse = await this.globalErrorHandler(wrappedError, ctx, responseBuilder);
+                    // The same rule the success path follows: headers belong
+                    // to the call, not to the response that first carried
+                    // them. A call that wrote a session cookie and then threw
+                    // still owes the browser that cookie, and a cross-origin
+                    // caller cannot read the error at all without the CORS
+                    // headers.
+                    ctx?.responseHeaders.applyTo(errorResponse);
+                    if (ctx)
+                        this.applyCors(ctx, errorResponse, false);
                     return await finalizeResponse(ctx, errorResponse, this.finalizeOptions, eventFormat);
                 }
             }
             catch (handlerErr) {
                 if (handlerErr instanceof LambderResponse) {
+                    ctx?.responseHeaders.applyTo(handlerErr);
+                    if (ctx)
+                        this.applyCors(ctx, handlerErr, false);
                     try {
                         return await finalizeResponse(ctx, handlerErr, this.finalizeOptions, eventFormat);
                     }
                     catch { /* fall through */ }
                 }
             }
-            // Last-resort 500. API calls get the JSON envelope so clients can
-            // parse a structured failure; everything else keeps plain text.
-            if (ctx?._otherInternal.isApiCall) {
-                const apiBody = JSON.stringify({ apiVersion: this.apiVersion, payload: null, errorMessage: "Internal server error." });
-                return eventFormat === "v2"
-                    ? { statusCode: 500, headers: { "Content-Type": "application/json; charset=utf-8" }, body: apiBody, isBase64Encoded: false }
-                    : { statusCode: 500, multiValueHeaders: { "Content-Type": ["application/json; charset=utf-8"] }, body: apiBody, isBase64Encoded: false };
+            // Last-resort 500. API calls get the core's crash envelope so
+            // clients can parse a structured failure; everything else keeps
+            // plain text. Emitted directly rather than finalized, because
+            // finalization may be what failed. The headers still go on: they
+            // belong to the call and not to the response that first carried
+            // them, so a call that wrote a session cookie and then threw still
+            // owes the browser that cookie, and a cross-origin caller cannot
+            // read this error at all without the CORS headers. Applying them
+            // is plain object work, none of the compression, base64 or size
+            // handling that finalization does.
+            const crashResponse = ctx?.api
+                ? responseFromAnswer(crashAnswer(this.apiVersion))
+                : new LambderResponse({ statusCode: 500, body: "Internal Server Error." });
+            ctx?.responseHeaders.applyTo(crashResponse);
+            if (ctx)
+                this.applyCors(ctx, crashResponse, false);
+            return emitResponse(eventFormat, crashResponse.statusCode, crashResponse.headers, typeof crashResponse.body === "string" ? crashResponse.body : "", false);
+        }
+    }
+    /**
+     * Fetch the session for a session route or short-circuit it with the
+     * sessionExpiredRouteHandler response (default 401). Session APIs never
+     * come through here: the pipeline answers them with the protocol's
+     * { sessionExpired: true } envelope itself.
+     */
+    async requireSession(ctx, resolver) {
+        const session = await this.getSessionController(ctx).fetchSessionIfExists();
+        if (!session) {
+            if (this.sessionExpiredRouteHandler) {
+                throw await this.sessionExpiredRouteHandler(ctx, resolver);
+            }
+            throw resolver.status(401, "Session required.");
+        }
+    }
+    /** Dispatch a non-HTTP Lambda event to the registered actions. */
+    async renderEvent(event, lambdaContext) {
+        await this.ensureInitialized();
+        for (const action of this.eventActionList) {
+            if (action.match(event)) {
+                return await action.actionFn(event, lambdaContext);
             }
-            return eventFormat === "v2"
-                ? { statusCode: 500, headers: {}, body: "Internal Server Error.", isBase64Encoded: false }
-                : { statusCode: 500, multiValueHeaders: {}, body: "Internal Server Error.", isBase64Encoded: false };
         }
+        const summary = event && typeof event === "object"
+            ? ` (source: ${String(event.source ?? "?")}, detail-type: ${String(event["detail-type"] ?? "?")})`
+            : "";
+        throw new Error(`Lambder: no action matched non-HTTP event${summary}. Register one with addAction(); a trailing addAction(() => true, ...) acts as a fallback.`);
+    }
+    // =====================================================================
+    // The API path
+    // The steps only an API call takes, around the shared core.
+    // =====================================================================
+    /** Registration-time checks shared by addApi/addSessionApi. */
+    assertApiRegistration(name, mode, options) {
+        if (this.registeredApiNames.has(name)) {
+            throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
+        }
+        // Everything that can refuse this registration runs before the name is
+        // claimed. Claiming it first meant a caught registration error burned
+        // the name, and the retry reported a duplicate instead of the problem
+        // the app was fixing; the session check was still on the far side of
+        // that line, one method down in addSessionApi.
+        if (mode === "session" && !this.pipeline.hasSessions) {
+            throw new Error(`Lambder: session API "${name}" needs the session option at creation.`);
+        }
+        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
+        if (guardsRequired && options.guards === undefined) {
+            const optOut = mode === "session"
+                ? "the named no-op guard that marks the session itself as the whole authorization"
+                : "the named no-op guard that records why anyone may call it";
+            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
+                `Declare the guard that authorizes it, or ${optOut}.`);
+        }
+        this.pipeline.assertRegistration({ name, mode, guards: options.guards, rateLimit: options.rateLimit, idempotency: options.idempotency });
+        this.registeredApiNames.add(name);
+    }
+    /**
+     * The answer for a rejected input: the app's
+     * setApiInputValidationErrorHandler when set, otherwise the standard 422
+     * body. The API's own schema and every preflight slice (guard inputs,
+     * rate-limit keys) answer through here, so one failure has one shape.
+     */
+    async inputValidationRefusal(ctx, zodError) {
+        if (this.apiInputValidationErrorHandler) {
+            return answerFromResponse(await this.apiInputValidationErrorHandler(ctx, this.getResolver(ctx), zodError));
+        }
+        // null asks the pipeline for the standard 422, so that answer is
+        // written once, in the core, rather than here as well.
+        return null;
+    }
+    /**
+     * One API call through the core: the pipeline runs the protocol steps and
+     * calls back for the handler, whose LambderResponse (returned, or thrown
+     * via res.die.*) becomes the answer the pipeline stores and hands back.
+     * The context is the pipeline's context, so a session it fetched is on
+     * ctx.session and the validated payload is on ctx.apiPayload when the
+     * handler runs.
+     */
+    async runApi(ctx, resolver, definition, handler) {
+        const request = ctx.api;
+        if (!request)
+            throw new Error(`Lambder: API "${definition.name}" was matched by a request that is not an API call.`);
+        // What the handler produced, in both forms: the answer went to the
+        // pipeline, and the response is kept so it can carry on unchanged.
+        const handled = { output: null };
+        const { answer } = await this.pipeline.run(request, ctx, definition, async () => {
+            ctx.apiPayload = request.payload;
+            let response;
+            try {
+                response = await handler(ctx, resolver);
+            }
+            catch (err) {
+                // A thrown LambderResponse IS the response (res.die.*): an
+                // answer like a returned one, stored and replayed alike.
+                if (err instanceof LambderResponse)
+                    response = err;
+                else
+                    throw err;
+            }
+            handled.output = { response, answer: answerFromResponse(response) };
+            return handled.output.answer;
+        });
+        // The handler's own response carries on when the pipeline answered
+        // with it, rather than a rebuild of its answer. An answer holds a
+        // Buffer body base64-encoded, because that is the plain shape the
+        // idempotency store persists, and rebuilding a response from that
+        // would hand finalization a base64 string it must pass through
+        // uncompressed. Identity is what settles it: the pipeline may have
+        // answered with a stored replay or a refusal instead.
+        if (handled.output?.answer === answer)
+            return handled.output.response;
+        return responseFromAnswer(answer);
+    }
+    /** A thrown LambderApiRefusal (from a hook, say) as the structured API envelope: the core's one mapping. */
+    apiErrorResponse(err, ctx) {
+        return responseFromAnswer(refusalAnswer(err, this.apiVersion, ctx.logList));
     }
 }
 /**
@@ -623,7 +679,7 @@ export default class Lambder {
  * // app.ts (imports no api modules, so modules can import the type back)
  * export const lambderApp = initLambder<SessionData>().create({
  *     apiPath: "/api",
- *     session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: "..." },
+ *     session: { store: new LambderDdbSessionStore({ tableName: "app-session", region: "us-east-1" }), sessionSalt: "..." },
  *     rateLimits: { limiter, policies },
  *     guards,
  *     idempotency: { store },
@@ -651,26 +707,3 @@ export const initLambder = () => ({
         return new Lambder(options);
     },
 });
-/** Rebuild the query string from the API Gateway event for redirects. */
-const buildQueryString = (ctx) => {
-    if (isV2HttpEvent(ctx.event)) {
-        return ctx.event.rawQueryString ? `?${ctx.event.rawQueryString}` : "";
-    }
-    const multi = ctx.event.multiValueQueryStringParameters;
-    const single = ctx.event.queryStringParameters;
-    const params = new URLSearchParams();
-    if (multi) {
-        for (const [key, values] of Object.entries(multi)) {
-            for (const value of values ?? [])
-                params.append(key, value);
-        }
-    }
-    else if (single) {
-        for (const [key, value] of Object.entries(single)) {
-            if (value !== undefined)
-                params.append(key, value);
-        }
-    }
-    const queryString = params.toString();
-    return queryString ? `?${queryString}` : "";
-};