lambder 14.0.1 → 15.0.1

package/dist/client/LambderUploadRunner.js

@@ -1,13 +1,22 @@
 import { checkUploadRule, } from "../shared/contracts/LambderUploadBucket.js";
 import { LambderBackoffTimer } from "../shared/util/LambderBackoffTimer.js";
 import { sha256Base64Of } from "../shared/util/LambderTextDigest.js";
-/** How an upload failed: `reason` for a screen to word, the underlying error as `cause`. */
+/**
+ * How an upload failed: `reason` for a screen to word, the underlying error
+ * as `cause`, and the failed outcome of the app's own call as `callFailure`
+ * when that call is what ended the upload, so a screen words a refusal by its
+ * code (`callFailure.refusal.code`) as it would on the call itself.
+ */
 export class LambderUploadError extends Error {
     reason;
+    /** The ticket or confirm call's failure outcome, when the upload ended on one. */
+    callFailure;
     constructor(reason, options = {}) {
         super(options.detail ? `${reason}: ${options.detail}` : reason, { cause: options.cause });
         this.name = "LambderUploadError";
         this.reason = reason;
+        if (options.callFailure)
+            this.callFailure = options.callFailure;
     }
 }
 /**
@@ -19,19 +28,38 @@ export class LambderUploadError extends Error {
 const TICKET_RENEWAL_LIMIT = 2;
 /** S3's refusals that are the connection's or the service's fault rather than the file's, which its own SDK retries too. */
 const TRANSIENT_STORAGE_CODES = new Set(["RequestTimeout", "SlowDown", "InternalError", "ServiceUnavailable"]);
+/**
+ * The ticket and confirm call failures that got no usable answer, so the same
+ * call may well pass on another try: no answer at all, the call's own
+ * timeout, a 5xx. Every other failure is the endpoint's answer (a refusal, a
+ * rejected input, an expired session), and the same call would get it again.
+ */
+const RETRIED_CALL_REASONS = new Set(["network", "timeout", "server"]);
+/** One line on what a failed call said, for the message of the upload error it ends in. */
+const describeCallFailure = (failure) => {
+    const said = failure.refusal !== undefined ? failure.refusal.content
+        : "error" in failure ? failure.error.message
+            : "";
+    return said ? `${failure.reason}: ${said}` : failure.reason;
+};
 export class LambderUploadRunner {
     options;
-    attempts;
+    /** How many times a step is tried again after its first try: the storageRetry option's attempts, less that first one. */
+    retries;
     /** The ladder one upload's waits climb; each upload() builds a timer of its own from it, so two uploads never share a count. */
     backoff;
     stallTimeoutMs;
     constructor(options) {
         this.options = options;
-        this.attempts = Math.max(1, options.storageRetry?.attempts ?? 4);
+        this.retries = Math.max(1, options.storageRetry?.attempts ?? 4) - 1;
         const baseDelayMs = options.storageRetry?.baseDelayMs ?? 1_000;
         const maxDelayMs = options.storageRetry?.maxDelayMs ?? 15_000;
         // A longest wait below the shortest is every wait at the shortest.
         this.backoff = { baseMs: baseDelayMs, maxMs: Math.max(baseDelayMs, maxDelayMs) };
+        // Each upload climbs a timer of its own; one built here checks the
+        // ladder where the runner is configured, so a storageRetry the timer
+        // refuses (a baseDelayMs of 0) fails now rather than on the first upload.
+        new LambderBackoffTimer(this.backoff);
         this.stallTimeoutMs = options.stallTimeoutMs ?? 60_000;
     }
     /** For a file input's `accept`, so the picker only offers what the rule takes. */
@@ -56,11 +84,11 @@ export class LambderUploadRunner {
         if (rejection)
             throw new LambderUploadError(rejection);
         const report = (phase, sentBytes = 0) => onProgress?.({ phase, sentBytes, totalBytes: file.size });
-        const stopIfCancelled = () => {
+        const stopIfAborted = () => {
             if (signal?.aborted)
-                throw new LambderUploadError("cancelled");
+                throw new LambderUploadError("aborted");
         };
-        stopIfCancelled();
+        stopIfAborted();
         report("hashing");
         const fileFacts = {
             fileName: file.name,
@@ -73,28 +101,64 @@ export class LambderUploadRunner {
                 throw new LambderUploadError("fileUnreadable", { cause });
             }))),
         };
-        stopIfCancelled();
-        const requestTicket = async () => {
-            report("requesting");
-            try {
-                return await this.options.requestTicket(fileFacts, { signal });
-            }
-            catch (cause) {
-                throw new LambderUploadError(signal?.aborted ? "cancelled" : "ticketRefused", { cause });
+        stopIfAborted();
+        // One timer for the whole upload, the app's calls and storage alike.
+        // A step that succeeds resets it, so each step has every attempt and
+        // its first wait is the shortest again. Every retry so far waited on
+        // the timer once, so its count is the retries the step has spent.
+        const backoff = new LambderBackoffTimer(this.backoff);
+        const waitToRetry = async (lastFailure) => {
+            if (backoff.retries >= this.retries)
+                throw new LambderUploadError("networkFailed", lastFailure);
+            // The wait rejects only for the signal: nothing else cancels it.
+            await backoff.wait(signal).catch((cause) => {
+                throw new LambderUploadError("aborted", { cause });
+            });
+        };
+        /**
+         * One of the app's calls through to its output. A failure with no
+         * usable answer is tried again on the timer, the same request each
+         * time (so a confirm asks about the ticket it was issued); any other
+         * failure ends the upload as `refused`, and one after the upload's
+         * signal aborted as the abort. A throw is the app's own code failing
+         * rather than the call, which no retry cures.
+         */
+        const callApp = async (call, refused) => {
+            for (;;) {
+                stopIfAborted();
+                let outcome;
+                try {
+                    outcome = await call();
+                }
+                catch (cause) {
+                    throw new LambderUploadError(signal?.aborted ? "aborted" : refused, { cause });
+                }
+                if (outcome.ok) {
+                    backoff.reset();
+                    return outcome.payload;
+                }
+                const ended = { callFailure: outcome, detail: describeCallFailure(outcome), ...("error" in outcome ? { cause: outcome.error } : {}) };
+                if (outcome.reason === "aborted" || signal?.aborted)
+                    throw new LambderUploadError("aborted", ended);
+                if (!RETRIED_CALL_REASONS.has(outcome.reason))
+                    throw new LambderUploadError(refused, ended);
+                await waitToRetry(ended);
             }
         };
+        const requestTicket = () => {
+            report("requesting");
+            return callApp(() => this.options.requestTicket(fileFacts, { signal }), "ticketRefused");
+        };
         let issued = await requestTicket();
-        const backoff = new LambderBackoffTimer(this.backoff);
-        let failedAttempts = 0;
         let ticketRenewals = 0;
         for (;;) {
-            stopIfCancelled();
+            stopIfAborted();
             report("uploading");
             const outcome = await this.send(issued.ticket, file, signal, (sentBytes) => report("uploading", sentBytes));
             if (outcome.kind === "stored")
                 break;
-            if (outcome.kind === "cancelled")
-                throw new LambderUploadError("cancelled");
+            if (outcome.kind === "aborted")
+                throw new LambderUploadError("aborted");
             if (outcome.kind === "rejected") {
                 // An expired ticket needs no wait and costs no attempt, only a
                 // new ticket; any other refusal is the file's, and final.
@@ -105,20 +169,11 @@ export class LambderUploadRunner {
             }
             // The ticket is kept through a network retry, so a flaky
             // connection does not leave the app a record per attempt.
-            if (++failedAttempts >= this.attempts)
-                throw new LambderUploadError("networkFailed");
-            // The wait rejects only for the signal: nothing else cancels it.
-            await backoff.wait(signal).catch((cause) => {
-                throw new LambderUploadError("cancelled", { cause });
-            });
+            await waitToRetry({});
         }
+        backoff.reset();
         report("confirming", file.size);
-        try {
-            return await this.options.confirmUpload(issued.reference, { signal });
-        }
-        catch (cause) {
-            throw new LambderUploadError(signal?.aborted ? "cancelled" : "confirmRefused", { cause });
-        }
+        return await callApp(() => this.options.confirmUpload(issued, { signal }), "confirmRefused");
     }
     /** Forgets a confirmed upload through the app's endpoint, when it declared one. */
     async discard(receipt) {
@@ -127,7 +182,7 @@ export class LambderUploadRunner {
     /** One upload of the file to storage, in the ticket's form. Never throws: every ending is an outcome. */
     send(ticket, file, signal, onSent) {
         if (signal?.aborted)
-            return Promise.resolve({ kind: "cancelled" });
+            return Promise.resolve({ kind: "aborted" });
         let request;
         if (ticket.method === "PUT") {
             request = { method: "PUT", url: ticket.uploadUrl, body: file, headers: ticket.headers };
@@ -176,7 +231,7 @@ const sendWithXhr = ({ method, url, body, headers }, fileBytes, stallTimeoutMs,
         settle(rejectedOutcome(request.status, request.responseText));
     };
     request.onerror = () => settle({ kind: "unreachable" });
-    request.onabort = () => settle(stalled ? { kind: "unreachable" } : { kind: "cancelled" });
+    request.onabort = () => settle(stalled ? { kind: "unreachable" } : { kind: "aborted" });
     signal?.addEventListener("abort", cancel, { once: true });
     watchForStall();
     try {
@@ -196,7 +251,7 @@ const sendWithFetch = async ({ method, url, body, headers }, fileBytes, signal,
         response = await fetch(url, { method, body, headers, signal });
     }
     catch {
-        return signal?.aborted ? { kind: "cancelled" } : { kind: "unreachable" };
+        return signal?.aborted ? { kind: "aborted" } : { kind: "unreachable" };
     }
     if (response.ok) {
         onSent(fileBytes);

package/dist/client.d.ts

@@ -19,17 +19,17 @@ export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_L
 export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignatureMap.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
-export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
+export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiFailure, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderLogListHandler, LambderCallerEndpoint, LambderCallerGroupCalls, LambderCallerMembers, } from "./client/LambderCaller.js";
 export { apiCallPath, splitApiName, LAMBDER_RESERVED_GROUP_NAMES, LAMBDER_RESERVED_ACTION_NAMES } from "./shared/wire/LambderApiNames.js";
 export type { LambderContractGroupsOf, LambderContractNamesInGroup, LambderContractActionOf } from "./shared/wire/LambderApiGroupCalls.js";
 export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 export type { LambderIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 export { LambderApiRefusal, isLambderApiRefusal, isLambderRefusalCode, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
-export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderPlainRefusalMessage, LambderUncheckedRefusalMessage, LambderRefusalCode, LambderRefuseOptions, LambderDeclaredRefuseOptions, LambderDeclaredRefuse, } from "./shared/wire/LambderApiRefusal.js";
+export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderPlainRefusalMessage, LambderRateLimitRefusalData, LambderUncheckedRefusalMessage, LambderRefusalCode, LambderRefuseOptions, LambderDeclaredRefuseOptions, LambderDeclaredRefuse, } from "./shared/wire/LambderApiRefusal.js";
 export { isObjectPayload } from "./shared/wire/LambderObjectPayload.js";
 export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiSuccessEnvelope, LambderApiRefusalEnvelope, LambderRefusalEnvelopeFields, LambderApiRefusalConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderContractRefusalsOf, LambderContractRefusalMessage, LambderContractRefusals, LambderContractAnyRefusalMessage, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
-export { apiGuardParam, apiGuardParamExportName } from "./shared/wire/LambderApiOptionEntries.js";
+export { apiGuardParam, apiGuardParamExportName, apisWithGuard } from "./shared/wire/LambderApiOptionEntries.js";
 export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, LambderApiGuardParam, } from "./shared/wire/LambderApiOptionEntries.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
@@ -37,13 +37,13 @@ export { compressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_
 export type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/wire/LambderRequestPayload.js";
 export { resolveCompressionOption } from "./shared/wire/LambderCompressionOption.js";
 export type { LambderCompressionOption, LambderCompressionSettingsBase } from "./shared/wire/LambderCompressionOption.js";
-export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
+export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue, type LambderJsonScriptOptions } from "./shared/LambderHtml.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
-export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nReadonlyInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nDictionaryEntry, LambderI18nPluralEntry, LambderI18nPluralCategory, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderHttpStatusCode, LambderRefusalStatusCode } from "./shared/wire/LambderHttpStatus.js";
 export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
 export type { LambderBackoffTimerOptions } from "./shared/util/LambderBackoffTimer.js";
-export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export { LambderSignedClaims, keyedDigest, randomSecret, randomCode } from "./shared/util/LambderSignedClaims.js";
 export type { LambderSignedClaimsOptions } from "./shared/util/LambderSignedClaims.js";
 export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";

package/dist/client.js

@@ -28,7 +28,7 @@ export { LambderApiRefusal, isLambderApiRefusal, isLambderRefusalCode, refuse, r
 export { isObjectPayload } from "./shared/wire/LambderObjectPayload.js";
 // The server's declared options as plain data (the generated options module's
 // entry types) and the readers a client derives its own facts from.
-export { apiGuardParam, apiGuardParamExportName } from "./shared/wire/LambderApiOptionEntries.js";
+export { apiGuardParam, apiGuardParamExportName, apisWithGuard } from "./shared/wire/LambderApiOptionEntries.js";
 // A crash described for a caller allowed to see it (the envelope's `crash` field; pure, no Node built-ins).
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 // Request payload compression (browser-safe: gzip via CompressionStream, no Node built-ins).
@@ -45,7 +45,7 @@ export { LambderBackoffTimer } from "./shared/util/LambderBackoffTimer.js";
 // Signed claims tokens, for the isomorphic code that verifies them where a
 // server's secret is at hand (an edge Worker, a shared backend package);
 // never in a page, which holds no secret to verify with.
-export { LambderSignedClaims, keyedDigest, randomSecret } from "./shared/util/LambderSignedClaims.js";
+export { LambderSignedClaims, keyedDigest, randomSecret, randomCode } from "./shared/util/LambderSignedClaims.js";
 export { constantTimeEquals } from "./shared/util/LambderTextDigest.js";
 // Direct uploads: the runner that takes a file from the browser straight to
 // storage, and the vocabulary it shares with the server's bucket.

package/dist/core/Lambder.d.ts

@@ -78,11 +78,12 @@ type LambderApiHandlerContext<TApp extends LambderAppTypes, TPayload, TGuardsOpt
  * ```
  */
 export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes, _TContract extends Record<string, any> = {}> {
-    apiPath: string;
+    /** Where API calls go: `{apiPath}/{group}/{action}`. */
+    readonly apiPath: string;
     /** Stamped on every API answer's envelope as apiVersion. Informational: a client's staleness is judged per endpoint by its signature, see apiSignatures(). */
-    apiVersion: null | string;
+    readonly apiVersion: null | string;
     /** The instance's file reader (source + caches), or null without the files option. */
-    files: LambderFiles | null;
+    readonly files: LambderFiles | null;
     /**
      * Type property for extracting the API contract: every registered API's
      * input, output, mode and declared options, as a client calls it.
@@ -125,7 +126,6 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     /** Every API's refusals option as written, for apiOptionEntries(); its definition holds the resolved set. */
     private readonly refusalOptions;
     private hookList;
-    private createdHooks;
     private initPromise;
     private globalErrorHandler;
     private routeFallbackHandler;
@@ -411,6 +411,17 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * endpoint and never moves when registrations are reordered.
      */
     apiOptionEntries(): Promise<LambderApiOptionEntries>;
+    /**
+     * Every registered API's input and output schemas by name, sorted by
+     * name: what writeApiSchemas (lambder/build) writes as JSON Schema to a
+     * module the mock validates its calls against. A build-time view, as
+     * apiSignatureEntries() is: it comes off the server instance, which a
+     * generator imports and a client never does.
+     */
+    apiSchemaEntries(): Promise<Record<string, {
+        input: z.ZodType;
+        output: z.ZodType;
+    }>>;
     getResponseBuilder(ctx?: LambderRenderContext): LambderResponseBuilder;
     private getResolver;
     getHandler(): LambderHandler;
@@ -510,8 +521,8 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * The answer to a request that needed a session and has none, whether it
      * never had one or it ended while the request held it: an API call gets
      * the protocol's sessionExpired envelope, as the pipeline gives a session
-     * API, and anything else the setSessionExpiredRouteHandler answer, a 401
-     * by default.
+     * API, and anything else the setSessionExpiredRouteHandler answer, a
+     * plain-text 401 by default, as the framework's own 404 and 500 are.
      */
     private sessionMissingResponse;
     /**
@@ -560,21 +571,30 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     private runApi;
     /**
      * A thrown LambderApiRefusal (from a hook, say) as the structured API
-     * envelope: the core's one mapping, after the same check the pipeline
-     * applies, against the endpoint the call names, its lazy group loaded if
-     * the refusal came before the call reached it. A name no API is
-     * registered under declares no code, so only an uncoded or a framework
-     * refusal goes out for it.
+     * envelope: the pipeline's own answer to a refusal (answerRefusal), so
+     * it is checked against the endpoint the call names, its lazy group
+     * loaded if the refusal came before the call reached it, and one saying
+     * the session is over ends it. A name no API is registered under
+     * declares no code, so only an uncoded or a framework refusal goes out
+     * for it.
      */
     private apiErrorResponse;
 }
+/** The options create() takes: the constructor's, less the two declareRefusals() supplies. */
+export type LambderInitCreateOptions<TSessionData> = Omit<LambderCreateOptions<TSessionData>, "refusals" | "requireRefusalCodes">;
 /**
- * The canonical way to create an instance: fix the session data type first,
- * then create with the full configuration in one declaration. The policy,
- * guard and idempotency types are inferred from the options, so the instance
- * is born fully typed, and the endpoints declared with its defineApi are
- * typed against it. There are no ordering rules, and nothing can be
- * half-configured.
+ * The entry point of an app, and the canonical way to create an instance:
+ * fix the session data type first, then create with the full configuration
+ * in one declaration. The policy, guard and idempotency types are inferred
+ * from the options, so the instance is born fully typed, and the endpoints
+ * declared with its defineApi are typed against it. There are no ordering
+ * rules, and nothing can be half-configured.
+ *
+ * Beside create() it hands out the builders that share the session data
+ * type (guard, rateLimitKey, refuse). `declareRefusals()` binds the app's
+ * refusal vocabulary too, so a guard's ctx.refuse and the init's own refuse
+ * are typed to it before any instance exists, and create() gives it to the
+ * instance for every API's refusals option to name codes from.
  *
  * ```typescript
  * // app.ts (imports no api modules, so modules can import from it)
@@ -603,15 +623,6 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
  * session type in the first call lets the second infer everything else.
  * `new Lambder(options)` serves untyped or session-data-free instances.
  */
-/** The options create() takes: the constructor's, less the two declareRefusals() supplies. */
-export type LambderInitCreateOptions<TSessionData> = Omit<LambderCreateOptions<TSessionData>, "refusals" | "requireRefusalCodes">;
-/**
- * The entry point of an app: binds the session data type, and hands out the
- * builders and create() that share it. `declareRefusals()` binds the app's
- * refusal vocabulary too, so a guard's ctx.refuse and the init's own refuse
- * are typed to it before any instance exists, and create() gives it to the
- * instance for every API's refusals option to name codes from.
- */
 export declare const initLambder: <TSessionData = any>() => {
     /**
      * Declares the app's refusal vocabulary: every code once, with the schema

package/dist/core/Lambder.js

@@ -13,12 +13,12 @@ import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
-import { checkedRefusal, declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
 import { refuse } from "../shared/wire/LambderApiRefusal.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignatureMap.js";
 import { assertPlainData } from "../shared/util/assertPlainData.js";
-import { apiNotFoundAnswer, envelopeAnswer, refusalAnswer, sessionExpiredAnswer, successEnvelope, versionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
+import { apiNotFoundAnswer, envelopeAnswer, sessionExpiredAnswer, successEnvelope, versionExpiredAnswer, } from "../api/LambderApiEnvelope.js";
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
 import { toGuardEntries } from "../api/LambderApiGuards.js";
@@ -80,6 +80,12 @@ export default class Lambder {
     // Construction
     // Everything an instance is, fixed before the first registration.
     // =====================================================================
+    // Fixed at construction, because what was built from them keeps its own
+    // copy: the pipeline and the crash handling stamp the apiVersion they
+    // were given, servePublicFiles serves through the reader it was given,
+    // and the callers of an instance post to the apiPath they were built
+    // with. A later write would leave the instance disagreeing with itself.
+    /** Where API calls go: `{apiPath}/{group}/{action}`. */
     apiPath;
     /** Stamped on every API answer's envelope as apiVersion. Informational: a client's staleness is judged per endpoint by its signature, see apiSignatures(). */
     apiVersion;
@@ -126,8 +132,7 @@ export default class Lambder {
     refusalVocabulary;
     /** Every API's refusals option as written, for apiOptionEntries(); its definition holds the resolved set. */
     refusalOptions = new Map();
-    hookList = { "beforeRender": [], "afterRender": [], "fallback": [] };
-    createdHooks = [];
+    hookList = { "created": [], "beforeRender": [], "afterRender": [], "fallback": [] };
     initPromise = null;
     globalErrorHandler = null;
     routeFallbackHandler = null;
@@ -211,6 +216,7 @@ export default class Lambder {
             rateLimits: options.rateLimits,
             guards: options.guards,
             idempotency: options.idempotency,
+            atRestSecret: session?.sessionSalt,
         });
         this.trustedClientIpHeaders = options.trustedClientIpHeaders ?? [];
         this.trustedHostHeaders = options.trustedHostHeaders ?? [];
@@ -539,14 +545,11 @@ export default class Lambder {
         this.apiHandlers.set(name, { output: api.output, compress: api.compress, handler: api.handler });
     }
     addHook(hookEvent, hookFn, priority = 0) {
-        if (hookEvent === "created") {
-            // Runs once, lazily, before the first request or event is handled.
-            this.createdHooks.push(hookFn);
-        }
-        else {
-            this.hookList[hookEvent].push({ priority, hookFn });
-            this.hookList[hookEvent].sort((a, b) => a.priority - b.priority);
-        }
+        // In priority order, lower first; the sort is stable, so hooks of one
+        // priority run in the order they were added. A created hook runs once,
+        // lazily, before the first request or event is handled.
+        this.hookList[hookEvent].push({ priority, hookFn });
+        this.hookList[hookEvent].sort((a, b) => a.priority - b.priority);
         return this;
     }
     addAction(filter, actionFn) {
@@ -723,6 +726,23 @@ export default class Lambder {
         }
         return { apis, rateLimitPolicies, guards };
     }
+    /**
+     * Every registered API's input and output schemas by name, sorted by
+     * name: what writeApiSchemas (lambder/build) writes as JSON Schema to a
+     * module the mock validates its calls against. A build-time view, as
+     * apiSignatureEntries() is: it comes off the server instance, which a
+     * generator imports and a client never does.
+     */
+    async apiSchemaEntries() {
+        await this.loadApiGroups();
+        const entries = {};
+        for (const name of [...this.apiDefinitions.keys()].sort()) {
+            // Both are always there on the server: registration takes them from the declaration, which requires them.
+            const { input, output } = this.apiDefinitions.get(name);
+            entries[name] = { input: input, output: output };
+        }
+        return entries;
+    }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
             files: this.files,
@@ -759,8 +779,8 @@ export default class Lambder {
     ensureInitialized() {
         if (!this.initPromise) {
             const pending = (async () => {
-                for (const hookFn of this.createdHooks) {
-                    await hookFn(this);
+                for (const hook of this.hookList["created"]) {
+                    await hook.hookFn(this);
                 }
             })();
             this.initPromise = pending;
@@ -828,11 +848,12 @@ export default class Lambder {
         for (const hook of this.hookList["fallback"]) {
             await hook.hookFn(currentCtx, resolver);
         }
-        // A request under apiPath is the API's to answer, whatever it asked
-        // for. A root apiPath shares every path with the site, so there only
-        // apiPath itself and the calls are.
+        // A request at or under apiPath is the API's to answer, whatever it
+        // asked for. A root apiPath shares every path with the site, the site
+        // root included, so there only the calls are.
         const apiArea = this.apiPath.replace(/\/+$/, "");
-        const isAPI = currentCtx.api !== null || currentCtx.path === this.apiPath || (apiArea !== "" && currentCtx.path.startsWith(`${apiArea}/`));
+        const isAPI = currentCtx.api !== null
+            || (apiArea !== "" && (currentCtx.path === this.apiPath || currentCtx.path.startsWith(`${apiArea}/`)));
         if (isAPI) {
             if (this.apiFallbackHandler)
                 return await this.apiFallbackHandler(currentCtx, resolver);
@@ -871,8 +892,9 @@ export default class Lambder {
                 return responseFromAnswer(versionExpiredAnswer(this.apiVersion));
             // 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.
+            // and so a stale client, or a body that is no envelope, 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);
@@ -1141,14 +1163,14 @@ export default class Lambder {
      * The answer to a request that needed a session and has none, whether it
      * never had one or it ended while the request held it: an API call gets
      * the protocol's sessionExpired envelope, as the pipeline gives a session
-     * API, and anything else the setSessionExpiredRouteHandler answer, a 401
-     * by default.
+     * API, and anything else the setSessionExpiredRouteHandler answer, a
+     * plain-text 401 by default, as the framework's own 404 and 500 are.
      */
     async sessionMissingResponse(ctx, resolver) {
         if (ctx.api)
             return responseFromAnswer(sessionExpiredAnswer(this.apiVersion, ctx.logList));
         if (!this.sessionExpiredRouteHandler)
-            return resolver.status(401, "Session required.");
+            return resolver.text("Session required.", { statusCode: 401 });
         try {
             return await this.sessionExpiredRouteHandler(ctx, resolver);
         }
@@ -1275,16 +1297,17 @@ export default class Lambder {
     }
     /**
      * A thrown LambderApiRefusal (from a hook, say) as the structured API
-     * envelope: the core's one mapping, after the same check the pipeline
-     * applies, against the endpoint the call names, its lazy group loaded if
-     * the refusal came before the call reached it. A name no API is
-     * registered under declares no code, so only an uncoded or a framework
-     * refusal goes out for it.
+     * envelope: the pipeline's own answer to a refusal (answerRefusal), so
+     * it is checked against the endpoint the call names, its lazy group
+     * loaded if the refusal came before the call reached it, and one saying
+     * the session is over ends it. A name no API is registered under
+     * declares no code, so only an uncoded or a framework refusal goes out
+     * for it.
      */
     async apiErrorResponse(err, ctx) {
         const apiName = ctx.apiName ?? "";
-        const refusal = checkedRefusal(apiName, (await this.registeredDefinitionOf(apiName))?.refusals ?? NO_DECLARED_REFUSALS, err);
-        return responseFromAnswer(refusalAnswer(refusal, this.apiVersion, ctx.logList));
+        const refusals = (await this.registeredDefinitionOf(apiName))?.refusals ?? NO_DECLARED_REFUSALS;
+        return responseFromAnswer(await this.pipeline.answerRefusal(apiName, refusals, err, ctx));
     }
 }
 /** The init bound to one vocabulary (or none): the policy builders, refuse and create() that share it. */
@@ -1305,11 +1328,45 @@ const lambderInitOf = (declared) => ({
     },
 });
 /**
- * The entry point of an app: binds the session data type, and hands out the
- * builders and create() that share it. `declareRefusals()` binds the app's
+ * The entry point of an app, and the canonical way to create an instance:
+ * fix the session data type first, then create with the full configuration
+ * in one declaration. The policy, guard and idempotency types are inferred
+ * from the options, so the instance is born fully typed, and the endpoints
+ * declared with its defineApi are typed against it. There are no ordering
+ * rules, and nothing can be half-configured.
+ *
+ * Beside create() it hands out the builders that share the session data
+ * type (guard, rateLimitKey, refuse). `declareRefusals()` binds the app's
  * refusal vocabulary too, so a guard's ctx.refuse and the init's own refuse
  * are typed to it before any instance exists, and create() gives it to the
  * instance for every API's refusals option to name codes from.
+ *
+ * ```typescript
+ * // app.ts (imports no api modules, so modules can import from it)
+ * export const lambderApp = initLambder<SessionData>().create({
+ *     apiPath: "/api",
+ *     session: { store: new LambderDdbSessionStore({ tableName: "app-session", region: "us-east-1" }), sessionSalt: "..." },
+ *     rateLimits: { limiter, policies },
+ *     guards,
+ *     idempotency: { store },
+ * });
+ * export const { defineApi, defineApiGroup, lazyApiGroup } = lambderApp;
+ *
+ * // orders.ts
+ * export const orderApis = defineApiGroup("orders", {
+ *     place: defineApi({ input, output, guards: "signedIn" }, async (ctx) => ...),
+ * });
+ *
+ * // index.ts: registration only
+ * const lambder = lambderApp.registerApiGroups(orderApis).addHook(...);
+ * export const handler = lambder.getHandler();
+ * ```
+ *
+ * Curried because TypeScript type arguments are all-or-nothing per call:
+ * passing the session data type to `new Lambder<S>(...)` would silently
+ * widen the inferred policy and guard types to their {} defaults. Fixing the
+ * session type in the first call lets the second infer everything else.
+ * `new Lambder(options)` serves untyped or session-data-free instances.
  */
 export const initLambder = () => ({
     ...lambderInitOf(null),

package/dist/core/LambderCallSummary.d.ts

@@ -27,7 +27,7 @@ export type LambderCallSummary = {
     coldStart: boolean;
     /** The invocation's request id, the one Lambda's own log lines for it carry. */
     requestId: string | null;
-    /** The request id of the invocation that called this one over a direct invoke (LambderInvokeCaller), which carries it; null otherwise. */
+    /** The request id of the invocation that called this one over a Lambda invoke (LambderInvokeCaller), which carries it; null otherwise. */
     parentRequestId: string | null;
 };
 /**