lambder 7.3.1 → 8.0.2

package/dist/core/LambderContext.d.ts

@@ -2,12 +2,14 @@ import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, APIGatewayProxyEvent
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import type LambderSessionController from "../session/LambderSessionController.js";
+import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult } from "../api/LambderApiRateLimits.js";
 export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
 /**
  * Which API Gateway payload format an event arrived in, and the format its
- * response leaves in. Declared here, beside the detection it comes from:
- * LambderResponse holds the emitters that read it, and having the type there
- * as well made the two core modules import each other.
+ * response leaves in. Declared here, beside the detection it comes from,
+ * rather than beside LambderResponse's emitters that read it: there, the two
+ * core modules would import each other.
  */
 export type LambderHttpEventFormat = "v1" | "v2";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
@@ -16,11 +18,32 @@ export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxy
  * Everything a route or API handler knows about the request. Extends the
  * API core's call context (session, guardData, responseHeaders, logList),
  * which is the part the pipeline and the session controller work on; the
- * rest is the HTTP request as the Lambda event delivered it.
+ * rest is the HTTP request as the Lambda event delivered it, plus the tools
+ * the instance rendering it binds on (sessionController, rateLimit, isRateLimited).
+ *
+ * TRateLimitPolicies is the app's policies map on a handler registered with
+ * addApi, addSessionApi, addRoute or addSessionRoute, so a policy name is
+ * checked where it is charged; anywhere else (a hook, a guard) the names are
+ * any string.
  */
-export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}, TSessionData = any> = {
+export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}, TSessionData = any, TRateLimitPolicies = Record<string, LambderApiRateLimitPolicyConfig>> = {
+    /**
+     * The Host the gateway received, or the first header named in
+     * `trustedHostHeaders` that carries a well-formed host. On a direct
+     * invoke, the invoking caller's `host`, whatever headers it forwarded.
+     */
     host: string;
+    /**
+     * The request path, decoded exactly once whichever gateway delivered it
+     * (a REST API and a Function URL deliver it encoded, an HTTP API
+     * decoded, in either payload format), with two escapes kept: a slash inside a segment stays `%2F`,
+     * so it cannot become a separator, and a percent sign stays `%25`, so no
+     * decoded text passes for an escape. What routes match and files are
+     * looked up by (see LambderRequestPath).
+     */
     path: string;
+    /** The path as the gateway delivered it, stage stripped: encoded or not, depending on the gateway. */
+    rawPath: string;
     pathParams: TPathParams;
     method: string;
     get: Record<string, string | undefined>;
@@ -36,13 +59,12 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
      */
     cookieList: Record<string, string[]>;
     /**
-     * The session, once something read or created one: the pipeline sets it on
-     * a session API, and getSessionController(ctx).createSession writes it
-     * here too. Null everywhere else, which is why a route or public API reads
-     * it as `ctx.session?.data`. Typing it as the literal `null` said the
-     * opposite of what the code does: after createSession the field was still
-     * `never`, and addSessionRoute needed a double cast to hand the handler
-     * the same object it already held.
+     * The session, once something read or created one: the pipeline sets it
+     * on a session API, and ctx.sessionController.createSession writes it here too.
+     * Null everywhere else, which is why a route or public API reads it as
+     * `ctx.session?.data`. Not typed as the literal `null`, since
+     * createSession fills it and addSessionRoute hands the handler this same
+     * object.
      */
     session: LambderSessionRecord<TSessionData> | null;
     /**
@@ -68,7 +90,8 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     /**
      * The address the gateway observed, or the leftmost entry of the first
      * header named in `trustedClientIpHeaders` that carries one; nothing is
-     * trusted by default. One spelling per address (port and brackets
+     * trusted by default, and no header on a direct invoke, whose address is
+     * the invoking caller's `clientIp`. One spelling per address (port and brackets
      * stripped, lowercased, length-bounded), so a `per: "ip"` limit keys one
      * counter per client.
      */
@@ -83,9 +106,53 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     responseHeaders: LambderAnswerHeaders;
     /** Entries for the API envelope's logList channel (res.logToApiResponse). */
     logList: unknown[];
+    /**
+     * Sessions for this request: read the one it carries
+     * (fetchSessionIfExists), create, rotate, refresh and end them. An API
+     * call presents its posted CSRF token and a route its cookies alone, the
+     * same controller `lambder.getSessionController(ctx)` hands out. Throws
+     * when the instance was created without the session option.
+     */
+    sessionController: LambderSessionController<TSessionData>;
+    /**
+     * Counts one attempt against a named rate-limit policy and refuses the
+     * request when it is over: a 429 envelope on an API call, a plain 429 on
+     * a route, with Retry-After and the policy's errorMessage either way. A
+     * policy without `per` takes the key as the second argument; a `per:
+     * "ip"` or `per: "session"` one reads it off the request. The instance's
+     * limiter, failOpen and key bounding apply, as for a declared limit.
+     */
+    rateLimit: LambderContextRateLimit<TRateLimitPolicies>;
+    /** The same count as rateLimit, answered instead of thrown: false, or the window that refused and its retryAfterSeconds. */
+    isRateLimited: LambderContextRateLimitCheck<TRateLimitPolicies>;
 };
-export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}> = Omit<LambderRenderContext<TApiPayload, TPathParams, TGuardData, SessionData>, 'session'> & {
+export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}, TRateLimitPolicies = Record<string, LambderApiRateLimitPolicyConfig>> = Omit<LambderRenderContext<TApiPayload, TPathParams, TGuardData, SessionData, TRateLimitPolicies>, 'session'> & {
     session: LambderSessionRecord<SessionData>;
 };
+/** The members of a render context that belong to the instance rendering the request rather than to its event. */
+type LambderContextToolName = "sessionController" | "rateLimit" | "isRateLimited";
+/** What an instance binds onto each context it renders: see bindContextTools. */
+export type LambderContextTools = {
+    sessionControllerFor: (ctx: LambderRenderContext) => LambderSessionController<any>;
+    /** Charges a policy for ctx; `refuse` throws the refusal when it is over instead of answering the check result. */
+    chargeRateLimit: (ctx: LambderRenderContext, policy: string, key: string | undefined, refuse: boolean) => Promise<LambderRateLimitCheckResult>;
+};
+/**
+ * Puts one instance's tools onto a context, bound to that very object, so
+ * what they read (the session, the ip, which API the call is) is the
+ * context's own. Bound through bindCallTools, as the mock's are, and bound
+ * again by the instance on whatever context a beforeRender hook hands back.
+ */
+export declare const bindContextTools: (ctx: Omit<LambderRenderContext, LambderContextToolName> | LambderRenderContext, tools: LambderContextTools) => LambderRenderContext;
+/** What createContext reads a request with: the instance's own settings for where an API call goes and which forwarded headers it trusts. */
+export type LambderContextOptions = {
+    /** See `apiPath` at create(). Default: "/api", as there. */
+    apiPath?: string;
+    /** See `trustedClientIpHeaders` at create(). Default: none. */
+    trustedClientIpHeaders?: readonly string[];
+    /** See `trustedHostHeaders` at create(). Default: none. */
+    trustedHostHeaders?: readonly string[];
+};
 /** The render context for one request: everything a route handler, an API handler, a hook or a guard reads about it, built once from the Lambda event. */
-export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, apiPath: string, trustedClientIpHeaders?: readonly string[]) => LambderRenderContext;
+export declare const createContext: (event: LambderHttpEvent, lambdaContext: Context, { apiPath, trustedClientIpHeaders, trustedHostHeaders }?: LambderContextOptions) => LambderRenderContext;
+export {};

package/dist/core/LambderContext.js

@@ -1,17 +1,76 @@
-import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
+import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { resolveClientIp } from "../shared/util/LambderClientIp.js";
 import { base64ToText } from "../shared/util/LambderBase64.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
+import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID } from "../shared/wire/LambderInvokeApiId.js";
+import { bindCallTools } from "../api/LambderApiCallContext.js";
+import { decodeRequestPath } from "./LambderRequestPath.js";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export const isV2HttpEvent = (event) => !!event && typeof event === "object"
     && event.version === "2.0"
     && !!event.requestContext?.http;
+/**
+ * Puts one instance's tools onto a context, bound to that very object, so
+ * what they read (the session, the ip, which API the call is) is the
+ * context's own. Bound through bindCallTools, as the mock's are, and bound
+ * again by the instance on whatever context a beforeRender hook hands back.
+ */
+export const bindContextTools = (ctx, tools) => {
+    const bound = ctx;
+    bindCallTools(bound, {
+        getters: { sessionController: () => tools.sessionControllerFor(bound) },
+        methods: {
+            rateLimit: async (policy, key) => { await tools.chargeRateLimit(bound, policy, key, true); },
+            isRateLimited: (policy, key) => tools.chargeRateLimit(bound, policy, key, false),
+        },
+    });
+    return bound;
+};
+/**
+ * The tools of a context no instance renders: one createContext() built from
+ * an event on its own. Touching one says what is missing instead of failing
+ * on an undefined member.
+ */
+const unboundTool = (member) => () => {
+    throw new Error(`Lambder: ctx.${member} is bound by the Lambder instance rendering the request, and this context was built by createContext() alone. Use lambder.getSessionController(ctx) for its session controller.`);
+};
+const UNBOUND_CONTEXT_TOOLS = {
+    sessionControllerFor: unboundTool("sessionController"),
+    chargeRateLimit: unboundTool("rateLimit"),
+};
+/**
+ * A Function URL's own domain, `<url-id>.lambda-url.<region>.on.aws`, which
+ * its events always carry: the URL answers no other Host, so CloudFront in
+ * front of one sends it this one too. Every other gateway's v2 event is an
+ * HTTP API's, custom domains included.
+ *
+ * Asked of a gateway's event only. An event Lambder synthesized (an invoke,
+ * lambder/testing, the handler transport) carries one of Lambder's own
+ * apiIds and its path decoded, and names whatever host its caller chose,
+ * this domain included.
+ */
+const FUNCTION_URL_DOMAIN = /\.lambda-url\.[a-z0-9-]+\.on\.aws$/i;
+/** A value a Host header may carry: a name or an address, and a port. Anything else from a forwarded header is not taken as the host. */
+const HOST_VALUE_PATTERN = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\])(?::\d{1,5})?$/;
+/**
+ * The path without a named stage's prefix. An HTTP API keeps the stage in
+ * the path it delivers, in either payload format (`/prod/orders` on stage
+ * `prod`), where a REST API strips it first; `$default` is never in it.
+ */
+const withoutStagePrefix = (path, stage) => stage && stage !== "$default" && (path === `/${stage}` || path.startsWith(`/${stage}/`))
+    ? path.slice(stage.length + 1) || "/"
+    : path;
 /** The render context for one request: everything a route handler, an API handler, a hook or a guard reads about it, built once from the Lambda event. */
-export const createContext = (event, lambdaContext, apiPath, trustedClientIpHeaders = []) => {
+export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH, trustedClientIpHeaders = [], trustedHostHeaders = [] } = {}) => {
     // Normalize the two API Gateway payload formats into one shape.
     const eventFormat = isV2HttpEvent(event) ? "v2" : "v1";
     let host;
-    let path;
+    let rawPath;
+    // An HTTP API delivers the path decoded, in either payload format, and so
+    // does Lambder's own 2.0 event builder; a REST API and a Function URL
+    // deliver it as the viewer sent it.
+    let pathAlreadyDecoded = false;
     let method;
     let get;
     let cookiePairs;
@@ -19,12 +78,10 @@ export const createContext = (event, lambdaContext, apiPath, trustedClientIpHead
     const headers = event.headers ?? {};
     if (isV2HttpEvent(event)) {
         host = headers.host || event.requestContext.domainName || "";
-        path = event.rawPath;
-        // Named stages (non-$default) are included in rawPath; v1 strips them.
-        const stage = event.requestContext.stage;
-        if (stage && stage !== "$default" && (path === `/${stage}` || path.startsWith(`/${stage}/`))) {
-            path = path.slice(stage.length + 1) || "/";
-        }
+        const apiId = event.requestContext.apiId;
+        pathAlreadyDecoded = apiId === LAMBDER_INVOKE_API_ID || apiId === LAMBDER_LOCAL_API_ID
+            || !FUNCTION_URL_DOMAIN.test(event.requestContext.domainName ?? "");
+        rawPath = withoutStagePrefix(event.rawPath, event.requestContext.stage);
         method = event.requestContext.http.method;
         get = {};
         for (const [key, value] of new URLSearchParams(event.rawQueryString ?? "").entries()) {
@@ -36,26 +93,54 @@ export const createContext = (event, lambdaContext, apiPath, trustedClientIpHead
     }
     else {
         host = headers.Host || headers.host || "";
-        path = event.path;
+        rawPath = event.path;
+        // An HTTP API sending payload format 1.0 marks it `version: "1.0"`;
+        // a REST API's event carries no version. Read as a REST API's, the
+        // decoded path would be decoded a second time: `/%2561dmin`, handed
+        // over as `/%61dmin`, would reach `/admin` past whatever authorizer
+        // guarded that route at the gateway.
+        if (event.version === "1.0") {
+            pathAlreadyDecoded = true;
+            rawPath = withoutStagePrefix(event.path, event.requestContext?.stage);
+        }
         method = event.httpMethod;
         get = event.queryStringParameters || {};
         // A REST API keeps only the LAST value of a repeated header in
         // `headers` and every value in `multiValueHeaders`, and HTTP/2 lets a
         // client split its cookies across several Cookie headers. The session
-        // layer weighs every copy of a cookie name, so dropping one is
-        // dropping a candidate session; v2's `event.cookies` already carries
-        // them all.
+        // layer weighs every copy of a cookie name, so dropping one drops a
+        // candidate session (v2's `event.cookies` carries them all).
         const cookieHeaders = event.multiValueHeaders?.Cookie ?? event.multiValueHeaders?.cookie;
         cookiePairs = (cookieHeaders?.length ? cookieHeaders.join("; ") : (headers.Cookie || headers.cookie || "")).split(";");
         sourceIp = event.requestContext?.identity?.sourceIp || "";
     }
+    const path = decodeRequestPath(rawPath, pathAlreadyDecoded);
     const cookieList = cookieValuesByName(cookiePairs);
     const cookie = Object.create(null);
     for (const [name, values] of Object.entries(cookieList))
         cookie[name] = values[0];
     const lowercasedHeaders = lowercaseHeaderNames(headers);
     const header = (name) => lowercasedHeaders[name.toLowerCase()];
-    const ip = resolveClientIp(lowercasedHeaders, sourceIp, trustedClientIpHeaders);
+    // A trusted forwarding header is trusted because a proxy in front of this
+    // function writes it. A direct invoke has no such proxy: its headers are
+    // whatever the invoking code passed on, and a gateway lambda forwarding a
+    // browser's request passes on the browser's own. So on an invoke the
+    // address and the host are the ones the invoker named (clientIp and host,
+    // delivered as sourceIp and Host), and no header is read for either.
+    const invokedDirectly = event.requestContext?.apiId === LAMBDER_INVOKE_API_ID;
+    // The first trusted header carrying a well-formed host, leftmost entry,
+    // else the host the gateway saw. Behind CloudFront a Function URL sees
+    // its own lambda-url domain, since CloudFront sends an origin its own
+    // Host, so cookie domains and host routing need the viewer's host from a
+    // header the distribution writes.
+    for (const name of invokedDirectly ? [] : trustedHostHeaders) {
+        const forwarded = (lowercasedHeaders[name.toLowerCase()] ?? "").split(",")[0].trim();
+        if (HOST_VALUE_PATTERN.test(forwarded)) {
+            host = forwarded;
+            break;
+        }
+    }
+    const ip = resolveClientIp(lowercasedHeaders, sourceIp, invokedDirectly ? [] : trustedClientIpHeaders);
     // Decode body: keep the raw string, then parse as JSON with urlencoded fallback.
     const rawBody = event.isBase64Encoded
         ? (event.body ? base64ToText(event.body) : "")
@@ -71,13 +156,15 @@ export const createContext = (event, lambdaContext, apiPath, trustedClientIpHead
             post[key] = value;
         }
     }
-    // A POST to the API path whose body names an API is an API call; the
-    // core reads the envelope, and everything downstream reads ctx.api.
-    const api = method === "POST" && !!apiPath && path === apiPath
+    // A JSON POST to the API path whose body names an API is an API call;
+    // the core reads the envelope, and everything downstream reads ctx.api.
+    // JSON only (isApiCallContentType): any site can submit a plain HTML form
+    // to this path, and enctype="text/plain" lays out a JSON body exactly.
+    const api = method === "POST" && !!apiPath && path === apiPath && isApiCallContentType(lowercasedHeaders)
         ? readApiEnvelope(post, { headers: lowercasedHeaders, cookies: cookieList, ip, host })
         : null;
-    return {
-        host, path, pathParams: {}, method,
+    return bindContextTools({
+        host, path, rawPath, pathParams: {}, method,
         get, post, cookie, cookieList, event,
         session: null,
         api,
@@ -89,5 +176,5 @@ export const createContext = (event, lambdaContext, apiPath, trustedClientIpHead
         eventFormat,
         responseHeaders: new LambderAnswerHeaders(),
         logList: [],
-    };
+    }, UNBOUND_CONTEXT_TOOLS);
 };

package/dist/core/LambderCors.d.ts

@@ -1,8 +1,14 @@
 import type { LambderRenderContext } from "./LambderContext.js";
 import type { LambderResponse } from "./LambderResponse.js";
 export type LambderCorsConfig = {
-    /** "*" (default), an allowlist, or a per-request predicate. With credentials, the origin is echoed (never "*"). */
+    /** "*" (default), an allowlist, or a per-request predicate, asked once per request; one that throws counts as refused. An allowed origin is echoed back. */
     origins?: "*" | string[] | ((origin: string, ctx: LambderRenderContext) => boolean);
+    /**
+     * Let an allowed origin make credentialed calls (cookies). Needs an
+     * allowlist or a predicate in `origins`: credentials for any origin would
+     * let every website read a signed-in user's answers, so create() refuses
+     * the pair.
+     */
     credentials?: boolean;
     methods?: string[];
     allowHeaders?: string[];
@@ -14,5 +20,17 @@ export type LambderCorsConfig = {
     exposeHeaders?: string[];
     maxAge?: number;
 };
-/** Mutate the response with the CORS headers the config allows for this request. */
-export declare const applyCorsHeaders: (config: LambderCorsConfig | null, ctx: LambderRenderContext, response: LambderResponse, isPreflight: boolean) => void;
+/**
+ * The Access-Control-Allow-Origin this request earns: "*", the echoed origin,
+ * or null for a refused or absent one.
+ *
+ * Settled once per request, before anything can crash, and handed to every
+ * answer the request ends in: the crash path then applies a verdict already
+ * reached and runs no app code of its own. A predicate that throws counts as
+ * refused and is logged. `new URL(origin)` throws on the `Origin: null` a
+ * sandboxed frame or a cross-origin redirect sends, and a CORS header is no
+ * reason to fail the request it decorates.
+ */
+export declare const allowedCorsOriginOf: (config: LambderCorsConfig, ctx: LambderRenderContext) => string | null;
+/** Mutate the response with the CORS headers the config allows, for the origin verdict allowedCorsOriginOf settled for this request. */
+export declare const applyCorsHeaders: (config: LambderCorsConfig | null, allowedOrigin: string | null, response: LambderResponse, isPreflight: boolean) => void;

package/dist/core/LambderCors.js

@@ -1,24 +1,43 @@
-/** Mutate the response with the CORS headers the config allows for this request. */
-export const applyCorsHeaders = (config, ctx, response, isPreflight) => {
-    if (!config)
-        return;
-    const origin = ctx.header("origin") ?? "";
+/**
+ * The Access-Control-Allow-Origin this request earns: "*", the echoed origin,
+ * or null for a refused or absent one.
+ *
+ * Settled once per request, before anything can crash, and handed to every
+ * answer the request ends in: the crash path then applies a verdict already
+ * reached and runs no app code of its own. A predicate that throws counts as
+ * refused and is logged. `new URL(origin)` throws on the `Origin: null` a
+ * sandboxed frame or a cross-origin redirect sends, and a CORS header is no
+ * reason to fail the request it decorates.
+ */
+export const allowedCorsOriginOf = (config, ctx) => {
     const origins = config.origins ?? "*";
-    let allowOrigin = null;
-    if (origins === "*") {
-        allowOrigin = config.credentials ? (origin || null) : "*";
+    if (origins === "*")
+        return "*";
+    const origin = ctx.header("origin");
+    if (!origin)
+        return null;
+    if (Array.isArray(origins))
+        return origins.includes(origin) ? origin : null;
+    try {
+        return origins(origin, ctx) ? origin : null;
     }
-    else if (Array.isArray(origins)) {
-        allowOrigin = origin && origins.includes(origin) ? origin : null;
-    }
-    else {
-        allowOrigin = origin && origins(origin, ctx) ? origin : null;
+    catch (predicateErr) {
+        console.error("Lambder: cors.origins threw; the origin was refused.", predicateErr);
+        return null;
     }
-    if (!allowOrigin)
+};
+/** Mutate the response with the CORS headers the config allows, for the origin verdict allowedCorsOriginOf settled for this request. */
+export const applyCorsHeaders = (config, allowedOrigin, response, isPreflight) => {
+    if (!config)
         return;
-    response.setHeader("Access-Control-Allow-Origin", allowOrigin);
-    if (allowOrigin !== "*")
+    // Under an allowlist or a predicate the answer depends on Origin even when
+    // this one was refused: a cache must not serve the answer to a refused or
+    // absent Origin to an allowed one, which would read it as a CORS failure.
+    if ((config.origins ?? "*") !== "*")
         response.addHeader("Vary", "Origin");
+    if (!allowedOrigin)
+        return;
+    response.setHeader("Access-Control-Allow-Origin", allowedOrigin);
     if (config.credentials)
         response.setHeader("Access-Control-Allow-Credentials", "true");
     if (isPreflight) {

package/dist/core/LambderCrashHandling.d.ts

@@ -0,0 +1,40 @@
+import type { LambderRenderContext } from "./LambderContext.js";
+import type { LambderCrashOptions, LambderCrashSite } from "./LambderCreateOptions.js";
+import { LambderResponse } from "./LambderResponse.js";
+/**
+ * The `crashes` option applied: what the instance does with a crash beyond
+ * handing it to the app's global error handler.
+ *
+ * Kept apart from the request path, like CORS and file serving: a crash is
+ * reported wherever it happened (an API call, a route, an event, a `created`
+ * hook) and answered by the framework only when nothing the app wrote
+ * answered it, so neither is a step of rendering a request.
+ */
+export declare class LambderCrashHandling {
+    private readonly options;
+    private readonly apiVersion;
+    private readonly reportTimeoutMs;
+    constructor(options: LambderCrashOptions, apiVersion: string | null);
+    /**
+     * Hands a crash to the app's reporter and waits for it, for up to
+     * reportTimeoutMs. Never throws: a reporter that fails is logged beside
+     * the crash it was given, one that has not finished by then is logged
+     * with it as unfinished, and either way the request goes on to be
+     * answered. The report itself cannot be cancelled and runs on; only the
+     * wait ends.
+     */
+    report(error: Error, site: LambderCrashSite): Promise<void>;
+    /**
+     * The framework's own 500, for a crash nothing the app wrote answered:
+     * API calls get the core's crash envelope so clients can parse a
+     * structured failure, everything else plain text. It carries the crash in
+     * full only for a caller `crashes.reveal` trusts.
+     *
+     * Without a reporter it also logs the crash (and a global error handler
+     * that threw on it): the invocation answered, so Lambda counts no error,
+     * and this log line is the only trace the crash leaves.
+     */
+    frameworkResponse(error: Error, ctx: LambderRenderContext | null, errorHandlerCrash: Error | null): Promise<LambderResponse>;
+    /** Whether this request's caller may read the crash; a reveal rule that throws answers no. */
+    private mayReveal;
+}

package/dist/core/LambderCrashHandling.js

@@ -0,0 +1,97 @@
+import { crashAnswer } from "../api/LambderApiEnvelope.js";
+import { describeCrash } from "../shared/wire/LambderCrashDetail.js";
+import { stopWaitingWhenAborted } from "../shared/util/LambderCallAbort.js";
+import { LambderResponse, responseFromAnswer } from "./LambderResponse.js";
+/**
+ * How long a crash's answer waits for the reporter by default: long enough
+ * for a network write to a log or an error tracker, short enough that a
+ * stalled one leaves most of a function's timeout to answer in.
+ */
+const DEFAULT_CRASH_REPORT_TIMEOUT_MS = 3_000;
+/**
+ * The `crashes` option applied: what the instance does with a crash beyond
+ * handing it to the app's global error handler.
+ *
+ * Kept apart from the request path, like CORS and file serving: a crash is
+ * reported wherever it happened (an API call, a route, an event, a `created`
+ * hook) and answered by the framework only when nothing the app wrote
+ * answered it, so neither is a step of rendering a request.
+ */
+export class LambderCrashHandling {
+    options;
+    apiVersion;
+    reportTimeoutMs;
+    constructor(options, apiVersion) {
+        this.options = options;
+        this.apiVersion = apiVersion;
+        this.reportTimeoutMs = options.reportTimeoutMs ?? DEFAULT_CRASH_REPORT_TIMEOUT_MS;
+    }
+    /**
+     * Hands a crash to the app's reporter and waits for it, for up to
+     * reportTimeoutMs. Never throws: a reporter that fails is logged beside
+     * the crash it was given, one that has not finished by then is logged
+     * with it as unfinished, and either way the request goes on to be
+     * answered. The report itself cannot be cancelled and runs on; only the
+     * wait ends.
+     */
+    async report(error, site) {
+        const report = this.options.report;
+        if (!report)
+            return;
+        const deadline = AbortSignal.timeout(this.reportTimeoutMs);
+        try {
+            // Started inside the promise chain, so a reporter that throws
+            // before its first await lands in the catch below like one that
+            // rejects.
+            await stopWaitingWhenAborted(Promise.resolve().then(() => report(error, site)), deadline);
+        }
+        catch (reportErr) {
+            if (deadline.aborted && reportErr === deadline.reason) {
+                console.error(`Lambder: crashes.report did not finish within ${this.reportTimeoutMs} ms and is no longer waited for. The crash:`, error);
+            }
+            else {
+                console.error("Lambder: crashes.report threw while reporting a crash. The crash:", error, "What the reporter threw:", reportErr);
+            }
+        }
+    }
+    /**
+     * The framework's own 500, for a crash nothing the app wrote answered:
+     * API calls get the core's crash envelope so clients can parse a
+     * structured failure, everything else plain text. It carries the crash in
+     * full only for a caller `crashes.reveal` trusts.
+     *
+     * Without a reporter it also logs the crash (and a global error handler
+     * that threw on it): the invocation answered, so Lambda counts no error,
+     * and this log line is the only trace the crash leaves.
+     */
+    async frameworkResponse(error, ctx, errorHandlerCrash) {
+        if (!this.options.report) {
+            console.error(`Lambder: ${ctx ? `${ctx.method} ${ctx.path}` : "a request"} crashed and was answered with the framework's 500.`, error);
+            if (errorHandlerCrash)
+                console.error(errorHandlerCrash);
+        }
+        const revealed = ctx && await this.mayReveal(ctx) ? describeCrash(error, ctx) : null;
+        if (ctx?.api) {
+            return responseFromAnswer(crashAnswer(this.apiVersion, revealed ? { crash: revealed, logList: ctx.logList } : undefined));
+        }
+        return new LambderResponse({
+            statusCode: 500,
+            body: revealed
+                ? ["Internal Server Error.", "", revealed.stack ?? `${revealed.name}: ${revealed.message}`,
+                    ...(revealed.causeList ?? []).map((cause) => `Caused by: ${cause.stack ?? `${cause.name}: ${cause.message}`}`)].join("\n")
+                : "Internal Server Error.",
+        });
+    }
+    /** Whether this request's caller may read the crash; a reveal rule that throws answers no. */
+    async mayReveal(ctx) {
+        if (!this.options.reveal)
+            return false;
+        try {
+            return (await this.options.reveal(ctx)) === true;
+        }
+        catch (revealErr) {
+            console.error("Lambder: crashes.reveal threw; the crash was not revealed.", revealErr);
+            return false;
+        }
+    }
+}