lambder 14.1.1 → 15.0.1

package/dist/core/LambderContext.d.ts

@@ -5,6 +5,7 @@ import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
 import { type LambderResponseTools } from "../api/LambderApiCallContext.js";
 import type LambderSessionController from "../session/LambderSessionController.js";
 import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult } from "../api/LambderApiRateLimits.js";
+import type { LambderAppTypes } from "../api/LambderApiDeclarations.js";
 export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
 /**
  * Which API Gateway payload format an event arrived in, and the format its
@@ -15,6 +16,21 @@ export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
 export type LambderHttpEventFormat = "v1" | "v2";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxyEventV2;
+/**
+ * How a request reached the function, as `ctx.arrivedVia` says it:
+ * - "proxy": over HTTP, carrying a valid `originProof`, so it came through
+ *   the proxy in front of the app;
+ * - "direct": over HTTP without a valid proof, sent to the gateway's own
+ *   address (an `execute-api` or `lambda-url` domain) rather than through the
+ *   proxy, so the proxy's headers on it are whatever its sender wrote and
+ *   have been taken off;
+ * - "invoke": a Lambda invoke, told by the event's `requestContext.apiId`,
+ *   which a gateway writes itself and no HTTP client can set, so only a
+ *   caller IAM let invoke the function sends one;
+ * - "unverified": over HTTP on an instance with no `originProof`, where
+ *   nothing tells a proxied request from a direct one.
+ */
+export type LambderRequestArrival = "proxy" | "direct" | "invoke" | "unverified";
 /**
  * Everything a route or API handler knows about the request. Extends the
  * API core's call context (session, guardData, responseHeaders, logList),
@@ -24,15 +40,17 @@ export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxy
  * and the response tools (setResponseHeader, addResponseHeader, setCookie,
  * clearCookie) that write onto whatever answer the request ends with.
  *
- * TRateLimitPolicies is the app's policies map on a handler registered with
- * defineApi, addRoute or addSessionRoute, so a policy name is
- * checked where it is charged; anywhere else (a hook, a guard) the names are
- * any string.
+ * TRateLimitPolicies is the app's policies map on an API handler (defineApi)
+ * and on a route registered by a path string (addRoute, addSessionRoute), so
+ * a policy name is checked where it is charged; anywhere else (a route
+ * matched by a RegExp, a predicate or a matcher object, a hook, a guard) the
+ * names are any string. LambderRenderContextOf names the typed form for a
+ * helper that takes one instance's context.
  */
 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
+     * `trustedHostHeaders` that carries a well-formed host. On a Lambda
      * invoke, the invoking caller's `host`, whatever headers it forwarded.
      */
     host: string;
@@ -93,7 +111,7 @@ 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, and no header on a direct invoke, whose address is
+     * trusted by default, and no header on a Lambda 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.
@@ -105,6 +123,12 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     lambdaContext: Context;
     /** Which API Gateway payload format the event arrived in, and the response leaves in. */
     eventFormat: LambderHttpEventFormat;
+    /**
+     * How the request reached the function (see LambderRequestArrival):
+     * through the proxy with a valid `originProof`, without it, by a
+     * Lambda invoke, or, with no `originProof` configured, unverified.
+     */
+    readonly arrivedVia: LambderRequestArrival;
     /** Response headers written during the request (the response tools below, session cookies), applied onto the response at the end. */
     responseHeaders: LambderAnswerHeaders;
     /** Entries for the API envelope's logList channel: a handler pushes what it wants the caller's debug log to show. */
@@ -132,6 +156,25 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
 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>;
 };
+/** What the context helpers below read off an instance: the AppTypes property every instance carries. */
+type LambderInstanceTypes = {
+    readonly AppTypes: LambderAppTypes;
+};
+/**
+ * One instance's render context, read off `typeof lambderApp`: its session
+ * data and its rate-limit policy names, any payload, path parameters and
+ * guard data. What a helper in another file takes to be handed a context of
+ * that instance, without writing LambderRenderContext's parameters out: an
+ * API handler's, a route's, a hook's and a guard's context are each
+ * assignable to it.
+ */
+export type LambderRenderContextOf<TInstance extends LambderInstanceTypes> = LambderRenderContext<any, Record<string, string>, {}, TInstance["AppTypes"]["session"], TInstance["AppTypes"]["policies"]>;
+/**
+ * LambderRenderContextOf with the session present: what a helper takes to be
+ * handed the context of a session route, a session endpoint's handler or a
+ * guard that needs a session, each assignable to it.
+ */
+export type LambderSessionRenderContextOf<TInstance extends LambderInstanceTypes> = LambderSessionRenderContext<any, TInstance["AppTypes"]["session"], Record<string, string>, {}, TInstance["AppTypes"]["policies"]>;
 /** The members of a render context that are bound onto it rather than read from its event. */
 type LambderContextToolName = "sessionController" | "rateLimit" | "isRateLimited" | keyof LambderResponseTools;
 /** What an instance binds onto each context it renders: see bindContextTools. */
@@ -157,6 +200,15 @@ export type LambderOriginProof = {
     header: string;
     /** The values it may carry: the current secret, and during a rotation the one before it. */
     secrets: readonly string[];
+    /**
+     * Headers the proxy writes that the app reads, beside the trusted client
+     * address and host headers, such as "cf-ipcountry" or
+     * "cloudfront-viewer-country". A request without the proof carries
+     * whatever its sender wrote under these names, so they are taken off
+     * `ctx.headers` and `ctx.header()` there, as the trusted headers are.
+     * Default: none.
+     */
+    proxyHeaders?: readonly string[];
 };
 /** 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 = {
@@ -166,7 +218,7 @@ export type LambderContextOptions = {
     trustedClientIpHeaders?: readonly string[];
     /** See `trustedHostHeaders` at create(). Default: none. */
     trustedHostHeaders?: readonly string[];
-    /** See `originProof` at create(). Default: none, so the trusted headers are read on every request. */
+    /** See `originProof` at create(). Default: none, so the trusted headers are read on every request and `arrivedVia` is "unverified" on all but an invoke. */
     originProof?: LambderOriginProof | null;
 };
 /** 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. */

package/dist/core/LambderContext.js

@@ -131,25 +131,31 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
     // The origin proof is read, then taken off the headers the app reads
     // (ctx.headers, ctx.header()), so no handler, hook or log of them meets
     // the secret; the raw event keeps it. A request that does not carry it
-    // came to the origin some other way than through the proxy, and the
-    // proxy's headers on it are whatever its sender wrote.
+    // came to the origin some other way than through the proxy, and every
+    // header the proxy writes is, on it, whatever its sender wrote: those
+    // are taken off too, so a handler reading one (a country, a viewer's
+    // address) reads what the proxy said or nothing.
     let proven = true;
     if (originProof) {
-        const proofHeader = originProof.header.toLowerCase();
-        const presented = lowercasedHeaders[proofHeader] ?? "";
+        const presented = lowercasedHeaders[originProof.header.toLowerCase()] ?? "";
         proven = originProof.secrets.some((secret) => constantTimeEquals(presented, secret));
-        delete lowercasedHeaders[proofHeader];
-        headers = Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== proofHeader));
+        const senderWritten = proven ? [] : [...trustedClientIpHeaders, ...trustedHostHeaders, ...(originProof.proxyHeaders ?? [])];
+        const removed = new Set([originProof.header, ...senderWritten].map((name) => name.toLowerCase()));
+        for (const name of removed)
+            delete lowercasedHeaders[name];
+        headers = Object.fromEntries(Object.entries(headers).filter(([name]) => !removed.has(name.toLowerCase())));
     }
     const header = (name) => lowercasedHeaders[name.toLowerCase()];
     // 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
+    // function writes it. A Lambda 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.
+    // delivered as sourceIp and Host), and no header is read for either. An
+    // invoke is told by the apiId, which a gateway writes itself.
     const invokedDirectly = event.requestContext?.apiId === LAMBDER_INVOKE_API_ID;
     const readsForwarding = proven && !invokedDirectly;
+    const arrivedVia = invokedDirectly ? "invoke" : !originProof ? "unverified" : proven ? "proxy" : "direct";
     // 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
@@ -163,21 +169,30 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
         }
     }
     const ip = resolveClientIp(lowercasedHeaders, sourceIp, readsForwarding ? trustedClientIpHeaders : []);
-    // Decode body: keep the raw string, then parse as JSON with urlencoded fallback.
+    // Decode body: keep the raw string, then read it as a JSON object, or as
+    // urlencoded fields when it is not JSON. ctx.post is an object whatever
+    // the body was: a JSON number, string, boolean, null or array is not
+    // fields, and every reader (a handler, a hook, the API path writing the
+    // restored payload onto it) indexes into it. Such a body stays readable
+    // as ctx.rawBody. What it means for an API call is readApiEnvelope's to
+    // say, from the parse itself.
     const rawBody = event.isBase64Encoded
         ? (event.body ? base64ToText(event.body) : "")
         : (event.body || "");
+    let posted;
+    let bodyNotJson = false;
     let post = {};
     try {
-        post = JSON.parse(rawBody || "{}") || {};
+        posted = JSON.parse(rawBody || "{}");
     }
-    catch (e) {
-        const params = new URLSearchParams(rawBody);
-        post = {};
-        for (const [key, value] of params.entries()) {
+    catch {
+        bodyNotJson = true;
+        for (const [key, value] of new URLSearchParams(rawBody).entries()) {
             post[key] = value;
         }
     }
+    if (posted !== null && typeof posted === "object" && !Array.isArray(posted))
+        post = posted;
     // A JSON POST to `{apiPath}/{group}/{action}` is a call to that endpoint;
     // the core reads the envelope, and everything downstream reads ctx.api.
     // JSON only (isApiCallContentType): any site can submit a plain HTML form
@@ -188,7 +203,7 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
     const isJsonPost = method === "POST" && !!apiPath && isApiCallContentType(lowercasedHeaders);
     const calledName = isJsonPost ? apiNameOfCallPath(apiPath, path) : null;
     const requestInfo = { headers: lowercasedHeaders, cookies: cookieList, ip, host };
-    const api = calledName !== null ? readApiEnvelope(post, requestInfo, calledName)
+    const api = calledName !== null ? readApiEnvelope(posted, requestInfo, calledName, bodyNotJson ? { bodyNotJson: true } : {})
         : isJsonPost && path === apiPath && typeof post.apiName === "string" && post.apiName !== ""
             ? readApiEnvelope(post, requestInfo, post.apiName, { retiredPath: true })
             : null;
@@ -203,6 +218,7 @@ export const createContext = (event, lambdaContext, { apiPath = DEFAULT_API_PATH
         headers, rawBody, ip, header,
         lambdaContext,
         eventFormat,
+        arrivedVia,
         responseHeaders: new LambderAnswerHeaders(),
         logList: [],
     }, UNBOUND_CONTEXT_TOOLS);

package/dist/core/LambderCrashHandling.d.ts

@@ -22,6 +22,11 @@ export declare class LambderCrashHandling {
      * 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.
+     *
+     * An error already reported where it arose (an invoke failure its
+     * caller's onFailure took, which api() then threw) is not handed over
+     * again: it is still a crash, answered as one, but reporting it here
+     * would record the one failure twice.
      */
     report(error: Error, site: LambderCrashSite): Promise<void>;
     /**

package/dist/core/LambderCrashHandling.js

@@ -1,6 +1,7 @@
 import { crashAnswer } from "../api/LambderApiEnvelope.js";
 import { describeCrash } from "../shared/wire/LambderCrashDetail.js";
 import { stopWaitingWhenAborted } from "../shared/util/LambderCallAbort.js";
+import { isErrorReported } from "../shared/util/LambderErrorReportMark.js";
 import { LambderResponse, responseFromAnswer } from "./LambderResponse.js";
 /**
  * How long a crash's answer waits for the reporter by default: long enough
@@ -33,10 +34,15 @@ export class LambderCrashHandling {
      * 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.
+     *
+     * An error already reported where it arose (an invoke failure its
+     * caller's onFailure took, which api() then threw) is not handed over
+     * again: it is still a crash, answered as one, but reporting it here
+     * would record the one failure twice.
      */
     async report(error, site) {
         const report = this.options.report;
-        if (!report)
+        if (!report || isErrorReported(error))
             return;
         const deadline = AbortSignal.timeout(this.reportTimeoutMs);
         try {
@@ -74,8 +80,12 @@ export class LambderCrashHandling {
         if (ctx?.api) {
             return responseFromAnswer(crashAnswer(this.apiVersion, revealed ? { crash: revealed, logList: ctx.logList } : undefined));
         }
+        // Typed as the text it is, as the framework's own 404 is: with no
+        // Content-Type a browser sniffs the body, and a crash message that
+        // reads like markup would render as a page.
         return new LambderResponse({
             statusCode: 500,
+            headers: { "Content-Type": "text/plain; charset=utf-8" },
             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")

package/dist/core/LambderCreateOptions.d.ts

@@ -128,7 +128,14 @@ export type LambderSessionOptions<TSessionData = any> = {
      * the store, so ctx.session.data would be typed by the table.
      */
     store: LambderSessionStore<any>;
-    /** The HMAC key that turns a sessionKey into the store's partition key, so a table read does not reveal whose sessions it holds. Treat as a secret. */
+    /**
+     * The HMAC key that turns a sessionKey into the store's partition key, so
+     * a table read does not reveal whose sessions it holds. A subkey derived
+     * from it (HKDF) also keys the at-rest digests of the caller's fields in
+     * every rate-limit key and idempotency scope. Changing it signs every
+     * session out and starts every rate-limit counter and idempotency record
+     * afresh. Treat as a secret.
+     */
     sessionSalt: string;
     enableSlidingExpiration?: boolean;
     /** Min seconds between sliding-expiration writes. Default: max(60, 5% of TTL). */
@@ -203,8 +210,8 @@ export type LambderCreateOptions<TSessionData = any> = {
      * a change the signatures cannot see (a security fix, a field whose
      * meaning changed under the same shape). Dotted numbers ("1.2.10"),
      * compared segment by segment; a call naming no version is not judged. A
-     * floor above `apiVersion` is taken as `apiVersion`, with a warning, so a
-     * mistaken floor cannot refuse this build's own clients. Default: none.
+     * floor above `apiVersion` throws at creation, since it would refuse this
+     * build's own clients. Default: none.
      */
     minApiVersion?: string;
     /**
@@ -248,7 +255,7 @@ export type LambderCreateOptions<TSessionData = any> = {
      * `per: "ip"` rate limits key off ctx.ip, and an address the caller picks
      * per request is not a limit. API Gateway APPENDS to x-forwarded-for, so
      * behind API Gateway alone the leftmost entry is the client's own claim
-     * and the header should be left out. A direct invoke reads none of these:
+     * and the header should be left out. A Lambda invoke reads none of these:
      * its ctx.ip is the invoker's `clientIp`.
      */
     trustedClientIpHeaders?: readonly string[];
@@ -260,24 +267,28 @@ export type LambderCreateOptions<TSessionData = any> = {
      *
      * The same rule as trustedClientIpHeaders: ctx.host decides cookie
      * domains and host-matched routes, and a host a client picks is a tenant
-     * a client picks. A direct invoke reads none of these: its ctx.host is the
+     * a client picks. A Lambda invoke reads none of these: its ctx.host is the
      * invoker's `host`.
      */
     trustedHostHeaders?: readonly string[];
     /**
      * Proof that a request came through the proxy the trusted headers are
-     * trusted for: `{ header, secrets }`, a header the proxy sets on every
-     * request it forwards (a Cloudflare transform rule, a CloudFront origin
-     * custom header) and the secret it carries, with the previous one beside
-     * it during a rotation. The trusted client address and host headers are
-     * read only from a request that carries it. One sent to the origin
-     * directly (an API Gateway's own execute-api URL, a Function URL) has
-     * its address and host from the gateway, whatever headers it wrote, so
-     * a `per: "ip"` limit counts it by the address it really came from. The
-     * header is taken off `ctx.headers` and `ctx.header()`, so no handler or
-     * hook meets the secret. Default: none, so the trusted headers are read
-     * on every request, which is right only for an origin nothing but the
-     * proxy can reach.
+     * trusted for: `{ header, secrets, proxyHeaders? }`, a header the proxy
+     * sets on every request it forwards (a Cloudflare transform rule, a
+     * CloudFront origin custom header) and the secret it carries, with the
+     * previous one beside it during a rotation. The trusted client address
+     * and host headers are read only from a request that carries it. One
+     * sent to the origin directly (an API Gateway's own execute-api URL, a
+     * Function URL) has its address and host from the gateway, whatever
+     * headers it wrote, so a `per: "ip"` limit counts it by the address it
+     * really came from, and the trusted headers and `proxyHeaders` (the
+     * other headers only the proxy writes) are taken off `ctx.headers` and
+     * `ctx.header()` on it. `ctx.arrivedVia` says which it was: "proxy" or
+     * "direct", or "invoke" for a Lambda invoke. The proof header itself is
+     * always taken off, so no handler or hook meets the secret. Default:
+     * none, so the trusted headers are read on every request, which is right
+     * only for an origin nothing but the proxy can reach, and
+     * `ctx.arrivedVia` is "unverified" on all but an invoke.
      */
     originProof?: LambderOriginProof;
     /**

package/dist/core/LambderCreateOptions.js

@@ -54,10 +54,16 @@ export const assertCreateOptions = (options) => {
 };
 /** Shortest secret an origin proof takes: one a sender could guess is no proof. 32 characters of hex or base64 is 128 bits or more. */
 export const MIN_ORIGIN_PROOF_SECRET_LENGTH = 32;
-/** An origin proof that proves something: a header name, secrets long enough not to guess, and trusted headers for it to guard. */
+/** A header name as a proxy writes one. */
+const HEADER_NAME_PATTERN = /^[A-Za-z0-9-]+$/;
+/**
+ * An origin proof that proves something: a header name, secrets long enough
+ * not to guess, and proxy headers that are header names. It needs no
+ * trusted header to guard: ctx.arrivedVia is worth having on its own.
+ */
 const assertOriginProof = (options) => {
     const proof = options.originProof;
-    if (typeof proof?.header !== "string" || !/^[A-Za-z0-9-]+$/.test(proof.header)) {
+    if (typeof proof?.header !== "string" || !HEADER_NAME_PATTERN.test(proof.header)) {
         throw new Error("Lambder: originProof.header must be a header name, such as \"x-origin-proof\".");
     }
     if (!Array.isArray(proof.secrets) || proof.secrets.length === 0) {
@@ -68,11 +74,12 @@ const assertOriginProof = (options) => {
             throw new Error(`Lambder: every originProof secret must be a string of at least ${MIN_ORIGIN_PROOF_SECRET_LENGTH} characters; a shorter one could be guessed, and a guessed proof proves nothing.`);
         }
     }
-    const trusted = [...(options.trustedClientIpHeaders ?? []), ...(options.trustedHostHeaders ?? [])];
-    if (trusted.length === 0) {
-        throw new Error("Lambder: originProof guards the trustedClientIpHeaders and trustedHostHeaders, and this instance trusts none, so it would prove nothing.");
+    const proxyHeaders = proof.proxyHeaders ?? [];
+    if (!Array.isArray(proxyHeaders) || proxyHeaders.some((name) => typeof name !== "string" || !HEADER_NAME_PATTERN.test(name))) {
+        throw new Error("Lambder: originProof.proxyHeaders must list header names the proxy writes, such as [\"cf-ipcountry\"].");
     }
-    if (trusted.some((name) => name.toLowerCase() === proof.header.toLowerCase())) {
-        throw new Error(`Lambder: originProof.header "${proof.header}" is also a trusted header; the proof is its own header, which the app never reads.`);
+    const proxyWritten = [...(options.trustedClientIpHeaders ?? []), ...(options.trustedHostHeaders ?? []), ...proxyHeaders];
+    if (proxyWritten.some((name) => name.toLowerCase() === proof.header.toLowerCase())) {
+        throw new Error(`Lambder: originProof.header "${proof.header}" is also a trusted or proxy header; the proof is its own header, which the app never reads.`);
     }
 };

package/dist/core/LambderResolver.d.ts

@@ -1,5 +1,6 @@
-import LambderResponseBuilder from "./LambderResponseBuilder.js";
+import LambderResponseBuilder, { type LambderTemplateFileOptions } from "./LambderResponseBuilder.js";
 import type { LambderResponse } from "./LambderResponse.js";
+import type { LambderTemplateData } from "./LambderTemplatingEngine.js";
 type SyncDie<T extends (...args: any[]) => LambderResponse> = (...args: Parameters<T>) => never;
 type AsyncDie<T extends (...args: any[]) => Promise<LambderResponse>> = (...args: Parameters<T>) => Promise<never>;
 /** The `res.die.*` surface: every builder method, throwing what it built. Internal to the resolver, which is the only thing that has one. */
@@ -16,7 +17,7 @@ interface DieResolverMethods {
     fileBase64: SyncDie<LambderResponseBuilder["fileBase64"]>;
     apiRefusal: SyncDie<LambderResponseBuilder["apiRefusal"]>;
     file: AsyncDie<LambderResponseBuilder["file"]>;
-    templateFile: AsyncDie<LambderResponseBuilder["templateFile"]>;
+    templateFile: <TNames extends string = string>(filePath: string, data?: LambderTemplateData<TNames>, options?: LambderTemplateFileOptions) => Promise<never>;
 }
 /**
  * Response builder passed to route handlers and hooks.

package/dist/core/LambderResponseBuilder.d.ts

@@ -16,6 +16,11 @@ export type LambderResponseOptions = {
     /** "auto" (default): ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
 };
+/** res.templateFile's options: a response's, and how the file is compiled. */
+export type LambderTemplateFileOptions = LambderResponseOptions & {
+    /** Expose the <title> content as slot "title" and the point before </head> as slot "head" (see LambderTemplatingEngineOptions). */
+    htmlVirtualSlots?: boolean;
+};
 export type LambderRawResponseInit = {
     statusCode: LambderHttpStatusCode;
     headers?: LambderHeadersInput;
@@ -44,11 +49,16 @@ export default class LambderResponseBuilder {
     private requireFiles;
     raw(init: LambderRawResponseInit): LambderResponse;
     json(data: Record<string, any>, options?: LambderResponseOptions): LambderResponse;
+    /** A plain-text body, sent as text: the place for a message, whatever status it goes out with (`{ statusCode }`). */
     text(data: string, options?: LambderResponseOptions): LambderResponse;
-    xml(data: string | LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
-    html(data: string | LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
-    status(statusCode: LambderHttpStatusCode, body?: string, options?: LambderResponseOptions): LambderResponse;
-    status404(data: string, options?: LambderResponseOptions): LambderResponse;
+    /** An XML document (a sitemap, a feed, SVG) built with xml`...` or marked safe with raw(). */
+    xml(data: LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
+    /** An HTML page built with html`...` or marked safe with raw(). */
+    html(data: LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
+    /** An HTML response with any status code, its body built like res.html's; no body sends an empty one. */
+    status(statusCode: LambderHttpStatusCode, body?: LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
+    /** An HTML 404, its body built like res.html's. */
+    status404(data: LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
     /**
      * A redirect to `url`, which may be a path or a whole URL. A path stays on
      * this origin: a leading run of slashes and backslashes collapses to one
@@ -72,12 +82,13 @@ export default class LambderResponseBuilder {
      * LambderTemplatingEngine (comment-based slots/conditionals) and return
      * it as an HTML response. The compiled template is cached on the
      * instance across warm invocations; a missing file throws (it is a
-     * server-side configuration error, not a client 404). Set
-     * htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
+     * server-side configuration error, not a client 404), and so does a data
+     * key the file has no slot or condition for, naming the file. TNames, when
+     * given, is the file's slot and condition names, so a misspelled key is a
+     * compile error. Set htmlVirtualSlots to expose "title"/"head" slots on
+     * marker-less files.
      */
-    templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
-        htmlVirtualSlots?: boolean;
-    }): Promise<LambderResponse>;
+    templateFile<TNames extends string = string>(filePath: string, data?: LambderTemplateData<TNames>, options?: LambderTemplateFileOptions): Promise<LambderResponse>;
     /**
      * An API call answered from outside its handler: what a hook, a fallback,
      * the input validation handler or the global error handler answers with.

package/dist/core/LambderResponseBuilder.js

@@ -1,6 +1,21 @@
 import { outcomeOfEnvelope } from "../shared/wire/LambderCallOutcome.js";
 import { LambderResponse } from "./LambderResponse.js";
+import { LambderSafeHtml } from "../shared/LambderHtml.js";
 import { plainRefusalEnvelope } from "../api/LambderApiEnvelope.js";
+/**
+ * The body of a response a browser renders as markup: safe markup only. A
+ * plain string is refused rather than sent, since nothing can tell markup an
+ * author wrote from text a request supplied (`"No match at " + ctx.path`),
+ * and the latter, sent as a page, runs as script. The tag escapes what it
+ * interpolates, raw() is the one visible place where trusted markup passes as
+ * it is, and text goes out as text.
+ */
+const markupBody = (method, tag, body) => {
+    if (body instanceof LambderSafeHtml)
+        return body.value;
+    throw new TypeError(`Lambder: ${method} takes safe ${tag === "html" ? "HTML" : "XML"}, and was given ${body === null ? "null" : typeof body}. Build the body with ${tag}\`...\`, which ` +
+        `escapes what it interpolates, mark markup you trust with raw(), or send plain text with res.text(body, { statusCode }).`);
+};
 /**
  * Builds the responses of routes, hooks and error handlers. An API handler
  * never holds one: it returns its output or refuses, and writes headers and
@@ -52,23 +67,28 @@ export default class LambderResponseBuilder {
     json(data, options) {
         return this.buildResponse(200, "application/json; charset=utf-8", JSON.stringify(data), options);
     }
+    /** A plain-text body, sent as text: the place for a message, whatever status it goes out with (`{ statusCode }`). */
     text(data, options) {
         return this.buildResponse(200, "text/plain; charset=utf-8", data, options);
     }
+    /** An XML document (a sitemap, a feed, SVG) built with xml`...` or marked safe with raw(). */
     xml(data, options) {
-        return this.buildResponse(200, "application/xml; charset=utf-8", String(data), options);
+        return this.buildResponse(200, "application/xml; charset=utf-8", markupBody("res.xml", "xml", data), options);
     }
     ;
+    /** An HTML page built with html`...` or marked safe with raw(). */
     html(data, options) {
-        return this.buildResponse(200, "text/html; charset=utf-8", String(data), options);
+        return this.buildResponse(200, "text/html; charset=utf-8", markupBody("res.html", "html", data), options);
     }
     ;
+    /** An HTML response with any status code, its body built like res.html's; no body sends an empty one. */
     status(statusCode, body, options) {
-        return this.buildResponse(statusCode, "text/html; charset=utf-8", body ?? "", options);
+        return this.buildResponse(statusCode, "text/html; charset=utf-8", body === undefined ? "" : markupBody("res.status", "html", body), options);
     }
     ;
+    /** An HTML 404, its body built like res.html's. */
     status404(data, options) {
-        return this.buildResponse(404, "text/html; charset=utf-8", data, options);
+        return this.buildResponse(404, "text/html; charset=utf-8", markupBody("res.status404", "html", data), options);
     }
     ;
     /**
@@ -118,7 +138,7 @@ export default class LambderResponseBuilder {
     async file(filePath, options) {
         const file = await this.requireFiles("res.file").read(filePath);
         if (!file)
-            return this.status404("File not found", { etag: false });
+            return this.text("File not found", { statusCode: 404, etag: false });
         return this.buildResponse(200, file.mimeType, file.body, options);
     }
     ;
@@ -127,12 +147,23 @@ export default class LambderResponseBuilder {
      * LambderTemplatingEngine (comment-based slots/conditionals) and return
      * it as an HTML response. The compiled template is cached on the
      * instance across warm invocations; a missing file throws (it is a
-     * server-side configuration error, not a client 404). Set
-     * htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
+     * server-side configuration error, not a client 404), and so does a data
+     * key the file has no slot or condition for, naming the file. TNames, when
+     * given, is the file's slot and condition names, so a misspelled key is a
+     * compile error. Set htmlVirtualSlots to expose "title"/"head" slots on
+     * marker-less files.
      */
     async templateFile(filePath, data, options) {
         const template = await this.requireFiles("res.templateFile").template(filePath, { htmlVirtualSlots: options?.htmlVirtualSlots });
-        return this.buildResponse(200, "text/html; charset=utf-8", template.render(data), options);
+        let body;
+        try {
+            body = template.render(data);
+        }
+        catch (error) {
+            // The engine knows its source, not the file it came from.
+            throw new Error(`Lambder: res.templateFile(${JSON.stringify(filePath)}): ${error.message}`, { cause: error });
+        }
+        return this.buildResponse(200, "text/html; charset=utf-8", body, options);
     }
     ;
     /**

package/dist/core/LambderTemplatingEngine.d.ts

@@ -1,5 +1,12 @@
 import { type LambderHtmlValue } from "../shared/LambderHtml.js";
-export type LambderTemplateData = Record<string, LambderHtmlValue>;
+/**
+ * What a template renders with: a value per slot or condition name. TNames,
+ * when given, is the template's names, so a key outside them is a compile
+ * error; left out, any name is accepted here and checked at render.
+ */
+export type LambderTemplateData<TNames extends string = string> = {
+    [Name in TNames]?: LambderHtmlValue;
+};
 export type LambderTemplatingEngineOptions = {
     /**
      * For full HTML documents without declared markers: expose the <title>
@@ -8,18 +15,29 @@ export type LambderTemplatingEngineOptions = {
      */
     htmlVirtualSlots?: boolean;
 };
-export declare class LambderTemplatingEngine {
+/**
+ * A comment-only HTML template, compiled once. TNames is the caller's
+ * statement of its slot and condition names, which types render()'s data;
+ * left out, any name compiles, and render() checks every key either way.
+ */
+export declare class LambderTemplatingEngine<TNames extends string = string> {
     private nodes;
-    /** Slot names discovered at compile time (dynamic typing surface). */
+    /** Every slot and condition name: what a data key has to be one of. */
+    private names;
+    /** Slot names discovered at compile time. */
     readonly slotNames: readonly string[];
     /** Condition names discovered at compile time. */
     readonly conditionNames: readonly string[];
     /** Parse `source`; throws on unclosed or mismatched blocks. */
     constructor(source: string, options?: LambderTemplatingEngineOptions);
     /** Read and parse a template file (compile once, render many times). */
-    static fromFile(filePath: string, options?: LambderTemplatingEngineOptions): Promise<LambderTemplatingEngine>;
+    static fromFile<TNames extends string = string>(filePath: string, options?: LambderTemplatingEngineOptions): Promise<LambderTemplatingEngine<TNames>>;
     /** True when the template declares `name` as a slot or condition. */
     has(name: string): boolean;
-    /** Render with escaped-by-default data; unknown keys ignored, omitted slots keep defaults. */
-    render(data?: LambderTemplateData): string;
+    /**
+     * Render with escaped-by-default data; omitted slots keep their defaults.
+     * Throws for a key the template has no slot or condition for, naming it
+     * and the template's names.
+     */
+    render(data?: LambderTemplateData<TNames>): string;
 }