lambder 11.1.1 → 13.0.1

package/dist/core/Lambder.js

@@ -13,47 +13,66 @@ 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, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { checkedRefusal, 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, } from "../api/LambderApiEnvelope.js";
+import { apiNotFoundAnswer, envelopeAnswer, refusalAnswer, 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";
+import { buildApiGroup, buildLazyApiGroup, isRegistrableApiGroup, } from "../api/LambderApiDeclarations.js";
+import { splitApiName } from "../shared/wire/LambderApiNames.js";
 import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
 import { LambderCrashHandling } from "./LambderCrashHandling.js";
+import { currentInvocation, runInvocation } from "./LambderInvocationScope.js";
+import { roundedMilliseconds, writeCallSummaryLine } from "./LambderCallSummary.js";
+import { outcomeOfAnswerText } from "../shared/wire/LambderCallOutcome.js";
+import { LAMBDER_INVOKE_API_ID, LAMBDER_PARENT_REQUEST_HEADER } from "../shared/wire/LambderInvokeApiId.js";
 import { policyBuildersFor } from "./LambderPolicyBuilders.js";
 import { assertCreateOptions, mergeNamedMaps, } from "./LambderCreateOptions.js";
 /** The refusals of a name no API is registered under: no code, and none required. */
 const NO_DECLARED_REFUSALS = { codes: new Map(), codeRequired: false };
+/** Longest endpoint name a call summary carries: a page built before paths posts the name in its body, and a line is no place for a long one. */
+const MAX_SUMMARY_API_NAME_CHARS = 200;
+/** A request id as the parent header may carry one: what Lambda's own ids look like, and no longer than any of them. */
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9-]{1,128}$/;
+/**
+ * The request id of the invocation that invoked this one, from an invoke's
+ * event alone: over HTTP the header is whatever a client wrote, and an
+ * invoke's apiId is one no gateway lets a client set.
+ */
+const parentRequestIdOf = (event) => {
+    if (event.requestContext?.apiId !== LAMBDER_INVOKE_API_ID)
+        return null;
+    const value = Object.entries(event.headers ?? {}).find(([name]) => name.toLowerCase() === LAMBDER_PARENT_REQUEST_HEADER)?.[1];
+    return typeof value === "string" && REQUEST_ID_PATTERN.test(value) ? value : null;
+};
+/** The API call a request is, as its invocation records it; null for a request that is no API call. */
+const apiCallOf = (ctx, event) => ctx.api ? { api: ctx.api.apiName, parentRequestId: parentRequestIdOf(event) } : null;
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
  * whole configuration, including the typed policy layer, is given at
- * construction, and only registration (routes, apis, hooks, use) chains.
+ * construction. Endpoints are declared as values on the instance
+ * (defineApi, defineApiGroup) and registered in one registerApiGroups()
+ * call; routes, hooks and actions chain.
  *
- * @typeParam TSessionData - Type of session data stored in DynamoDB
- * @typeParam _TContract - @internal Accumulates API contract during chaining (do not pass manually)
- * @typeParam _TRateLimitPolicies - @internal Inferred from create()'s rateLimits.policies (do not pass manually)
- * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
- * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
- * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
- * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
- * @typeParam _TSessionsEnabled - @internal True when create() received the session option (do not pass manually). Defaults to true, unlike its siblings, so a plugin annotating its parameter as the bare Lambder<SessionData> can still register session APIs. create() knows the option and supplies the false; `new Lambder(...)` relies on the registration-time throw alone.
- * @typeParam _TRefusals - @internal The refusal vocabulary declareRefusals() gave the init (do not pass manually)
- * @typeParam _TRefusalCodesRequired - @internal True when declareRefusals() received requireCodes (do not pass manually)
+ * @typeParam TApp - @internal What create() configured, as LambderAppTypes: the session data, policies, guards, idempotency, the guard requirement, sessions and the refusal vocabulary (do not pass manually)
+ * @typeParam _TContract - @internal The contract of the groups registered so far (do not pass manually)
  *
  * @example
  * ```typescript
  * interface SessionData { userId: string; role: string; }
  *
- * const lambder = initLambder<SessionData>().create({ apiPath: '/api' })
- *   .addApi('getUser', { input: z.object({...}), output: z.object({...}) }, handler)
- *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
+ * const app = initLambder<SessionData>().create({ apiPath: '/api', session, guards });
+ * const userApis = app.defineApiGroup("users", {
+ *     get: app.defineApi({ input: z.object({...}), output: z.object({...}), guards: "signedIn" }, handler),
+ * });
+ * const lambder = app.registerApiGroups(userApis);
  * ```
  */
 export default class Lambder {
@@ -70,24 +89,35 @@ export default class Lambder {
      * Type property for extracting the API contract: every registered API's
      * input, output, mode and declared options, as a client calls it.
      *
-     * A small app's client imports it as it is. It is an intersection one
-     * member deep per endpoint, so reading it generically costs a large app's
-     * client most of its type check; writeApiContract (lambder/build) reads
-     * this property off the exported instance and writes the contract out as
-     * plain types for such a client to import instead.
+     * A small app's client imports it as it is. A large app's client reads
+     * the plain types writeApiContract (lambder/build) prints from this
+     * property instead, which cost it nothing to resolve.
      *
      * @example
      * ```typescript
-     * export const lambder = initLambder().create({ ... }).addApi(...).addApi(...);
+     * export const lambder = lambderApp.registerApiGroups(userApis, orderApis);
      * export type ApiContractType = typeof lambder.ApiContract;
      * ```
      */
     ApiContract;
+    /**
+     * Type property for what create() configured (LambderAppTypes): the
+     * session data, policies, guards and the rest, for code that takes any
+     * instance and needs one of them (lambderTestApp reads the session data
+     * type here). Like ApiContract, it has no value.
+     */
+    AppTypes;
     actionList = [];
     /** The API core: the pipeline every API call runs through, shared in shape with the mock runtime. */
     pipeline;
-    /** Every registered API by name: the duplicate-name check, and what apiSignatures() digests. */
+    /** Every registered API by name: what dispatch, apiSignatures() and apiOptionEntries() read. */
     apiDefinitions = new Map();
+    /** What answers each registered API: its output schema, compression setting and handler. */
+    apiHandlers = new Map();
+    /** Every group name registered, lazy or not: the duplicate-group check. */
+    apiGroupNames = new Set();
+    /** The lazy groups not loaded yet, each with its load in progress, if one is. */
+    lazyApiGroups = new Map();
     /** The guards given at creation, merged into one map, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
     guards;
     /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
@@ -109,7 +139,8 @@ export default class Lambder {
     eventActionList = [];
     corsConfig = null;
     finalizeOptions;
-    requireSessionApiGuards;
+    /** Whether every endpoint has to declare guards (create()'s requireApiGuards). */
+    requireApiGuards;
     /** Whether every refusal an API answers with has to name a code (declareRefusals's requireCodes). */
     requireRefusalCodes;
     /** Told what a request threw, beside whatever answers it; null outside a test. See LAMBDER_CRASH_WATCH. */
@@ -120,7 +151,9 @@ export default class Lambder {
     contextTools;
     trustedClientIpHeaders;
     trustedHostHeaders;
-    requirePublicApiGuards;
+    originProof;
+    /** Where each API call's summary goes (the callSummary option); null writes none. Replaceable through the backend swap alone. */
+    callSummaryWriter;
     constructor(given = {}) {
         // The guards and the rate-limit policies as one map each, whether
         // they were given as one or as a list; a name two maps declare
@@ -165,7 +198,9 @@ export default class Lambder {
                         sessionSalt: session.sessionSalt,
                         enableSlidingExpiration: session.enableSlidingExpiration,
                         slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
-                        dataRefresh: session.dataRefresh,
+                        // As given: the manager refuses dataRefresh without
+                        // the schema, which an untyped caller can still pass.
+                        ...{ dataRefresh: session.dataRefresh, dataSchema: session.dataSchema },
                         crypto: session.crypto,
                     }),
                     tokenCookieKey: session.tokenCookieKey,
@@ -179,19 +214,21 @@ export default class Lambder {
         });
         this.trustedClientIpHeaders = options.trustedClientIpHeaders ?? [];
         this.trustedHostHeaders = options.trustedHostHeaders ?? [];
-        this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
+        this.originProof = options.originProof ?? null;
+        this.callSummaryWriter = options.callSummary === false ? null : options.callSummary ?? writeCallSummaryLine;
+        this.requireApiGuards = options.requireApiGuards ?? false;
         this.requireRefusalCodes = options.requireRefusalCodes ?? false;
-        this.requirePublicApiGuards = options.requirePublicApiGuards ?? false;
         this.crashHandling = new LambderCrashHandling(options.crashes ?? {}, this.apiVersion);
         this.contextTools = {
             sessionControllerFor: (ctx) => this.getSessionController(ctx),
             chargeRateLimit: async (ctx, policy, key, refuse) => {
+                // A per-API budget counts per registered API. The posted name
+                // of a call no API matched (a hook or the fallback charging
+                // it) is the caller's choice, and a fresh name per request
+                // would be a fresh counter.
+                const apiName = ctx.api && await this.registeredDefinitionOf(ctx.api.apiName) ? ctx.api.apiName : null;
                 const { checkResult, refusal: refusalToThrow } = await this.pipeline.chargeRateLimit(policy, {
-                    // A per-API budget counts per registered API. The posted
-                    // name of a call no API matched (a hook or the fallback
-                    // charging it) is the caller's choice, and a fresh name
-                    // per request would be a fresh counter.
-                    apiName: ctx.api && this.apiDefinitions.has(ctx.api.apiName) ? ctx.api.apiName : null,
+                    apiName,
                     ip: ctx.ip,
                     session: ctx.session,
                     key,
@@ -287,45 +324,196 @@ export default class Lambder {
         });
         return this;
     }
-    // Typed API with Zod
-    addApi(name, schema, 
+    // =====================================================================
+    // Endpoints
+    // Declared as values, gathered into named groups, registered in one call.
+    // =====================================================================
+    /**
+     * Declares one endpoint, typed on this instance's types: its input and
+     * output schemas, its guards, rate limits, idempotency and refusals, and
+     * its handler. Nothing is registered until the declaration is put in a
+     * group (defineApiGroup) and the group is registered (registerApiGroups).
+     *
+     * The guards say who may call it, and so its mode: an endpoint whose
+     * guards include one that needs a session (`session: true`) is a session
+     * endpoint, its session read before the guards run and a call without
+     * one answered sessionExpired, and its handler's ctx.session is typed
+     * present. Any other endpoint is public.
+     *
+     * An arrow property rather than a method, so an app can hand it out
+     * detached: `export const { defineApi, defineApiGroup } = lambderApp;`.
+     */
+    defineApi = (options, 
     /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
-    handler) {
-        this.registerApi(name, "public", schema, handler);
-        return this;
+    handler) => ({ kind: "lambderApi", options: options, handler: handler });
+    /**
+     * Gathers endpoints into a named group: each is registered as
+     * `name.action` and called at `{apiPath}/{name}/{action}`, and every
+     * Lambder caller reaches it as `caller.name.action(input)`. A group's
+     * name and its actions are identifiers, and a group may not take a name
+     * a caller already answers for (see LAMBDER_RESERVED_GROUP_NAMES).
+     *
+     * A group declared across files takes each file's part:
+     * `defineApiGroup("orders", orderReadApis, orderWriteApis)`. An action
+     * two parts declare is refused, at compile time and at startup, rather
+     * than one silently replacing the other as an object spread would.
+     */
+    defineApiGroup = (name, ...parts) => buildApiGroup(name, parts);
+    /**
+     * A group loaded on the first call to one of its endpoints:
+     * `lazyApiGroup("orders", () => import("./orders.js").then((m) => m.orderApis))`.
+     * A cold start then parses none of it, nor anything only it imports,
+     * until a request calls it; the contract is the loaded group's, read off
+     * its type. The group loaded must carry the same name, which the type
+     * checks and loading checks again. `loadApiGroups()` loads every group,
+     * for a build step or a boot check that has to see them all.
+     */
+    lazyApiGroup = (name, load) => buildLazyApiGroup(name, load);
+    /**
+     * Registers groups of endpoints, as one contract: `typeof
+     * lambder.ApiContract` then maps every `group.action` to its entry, one
+     * flat object type the api-contract generator prints as it is. Register
+     * every group in one call where you can: the contract of one call is one
+     * mapped type, and a second call intersects it with the first.
+     *
+     * The call's groups take their place in the first-match chain here, as
+     * a route does: a route or action registered before them sees their calls
+     * first, one registered after them never does. The beforeRender hooks run
+     * before a lazy group loads, so a hook that answers a request spares it
+     * the import; one that throws a refusal or charges a per-API budget loads
+     * it (see registeredDefinitionOf).
+     *
+     * Refused at compile time: a group typed `any`, or a lazy one loading a
+     * group typed `any`, or a group whose endpoints are (its endpoints would
+     * be `any` to every client), and a group name given twice. Refused at
+     * registration, which is at startup for a group and at its first call for
+     * a lazy one: everything registration refuses of one endpoint (an unknown
+     * guard or policy, a missing guard where requireApiGuards is on, a
+     * refusal code outside the vocabulary).
+     */
+    registerApiGroups(...groups) {
+        const instance = this;
+        // Every group and every endpoint is checked before anything is
+        // claimed, so a registration refused anywhere leaves the instance as
+        // it was: no group name taken, no endpoint half registered, and a
+        // caller that catches the error and fixes the declaration is told the
+        // real problem on its next try.
+        const names = new Set();
+        const prepared = [];
+        for (const group of groups) {
+            if (!isRegistrableApiGroup(group)) {
+                throw new Error("Lambder: registerApiGroups takes groups built by defineApiGroup() or lazyApiGroup().");
+            }
+            if (instance.apiGroupNames.has(group.name) || names.has(group.name)) {
+                throw new Error(`Lambder: group "${group.name}" is registered twice. A group is one namespace, so its endpoints belong in one defineApiGroup().`);
+            }
+            names.add(group.name);
+            if (group.kind === "lambderApiGroup")
+                prepared.push(...instance.prepareApiGroup(group));
+        }
+        for (const group of groups) {
+            instance.apiGroupNames.add(group.name);
+            if (group.kind === "lambderLazyApiGroup")
+                instance.lazyApiGroups.set(group.name, { group, loading: null });
+        }
+        for (const api of prepared)
+            instance.commitApi(api);
+        instance.actionList.push({
+            match: (ctx) => {
+                const group = ctx.api ? splitApiName(ctx.api.apiName)?.group : undefined;
+                return group !== undefined && names.has(group) ? {} : false;
+            },
+            actionFn: (ctx, resolver) => instance.dispatchApiCall(ctx, resolver),
+        });
+        return instance;
     }
-    // Typed Session API with Zod
-    addSessionApi(name, schema, 
-    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
-    handler) {
-        this.registerApi(name, "session", schema, handler);
-        return this;
+    /**
+     * Loads every lazy group not loaded yet, registering its endpoints: what
+     * a build step digesting the signatures, a generator writing the options
+     * or a boot check has to do before it sees every endpoint. A group whose
+     * registration fails rejects here, which is the point of calling it.
+     */
+    async loadApiGroups() {
+        for (const name of [...this.lazyApiGroups.keys()])
+            await this.loadLazyApiGroup(name);
+    }
+    /**
+     * An API call to a registered group, its hooks run: its group loaded
+     * first when it is a lazy one no call has reached yet, then its endpoint
+     * run. An action the group does not have is answered as any unmatched API
+     * call is, fallback hooks first.
+     */
+    async dispatchApiCall(ctx, resolver) {
+        const apiName = ctx.api.apiName;
+        const definition = await this.registeredDefinitionOf(apiName);
+        const endpoint = this.apiHandlers.get(apiName);
+        if (!definition || !endpoint)
+            return await this.answerUnmatched(ctx, resolver);
+        return await this.runApi(ctx, definition, endpoint.output, endpoint.compress, endpoint.handler);
+    }
+    /**
+     * The definition of the endpoint a call names, its group loaded first
+     * when it is a lazy one no call has reached yet; undefined for a name no
+     * registered group declares. Everything that reads an endpoint's
+     * declarations for a call asks here (its dispatch, a refusal a hook
+     * throws on the way to it, a per-API budget a hook charges), so a lazy
+     * group answers each of them as an eager one does.
+     */
+    async registeredDefinitionOf(apiName) {
+        const group = splitApiName(apiName)?.group;
+        if (group !== undefined && this.lazyApiGroups.has(group))
+            await this.loadLazyApiGroup(group);
+        return this.apiDefinitions.get(apiName);
+    }
+    /** The endpoints of one group, each checked as `group.action`; nothing is registered until they are committed. */
+    prepareApiGroup(group) {
+        return Object.entries(group.apis).map(([action, declaration]) => this.prepareApi(`${group.name}.${action}`, declaration.options, declaration.handler));
     }
     /**
-     * What registering an API is, for addApi and addSessionApi alike: the
-     * checks that can refuse it, then its definition recorded (what
-     * apiSignatures() digests) and its action appended to the first-match
-     * chain. The two public methods differ only in the mode and in the types
-     * they give the handler.
+     * A lazy group, loaded once: its import, checked to be the group it was
+     * registered as, then registered. Concurrent first calls share one load;
+     * a failed load is forgotten, so the next call tries again rather than
+     * answering every later call with the first failure.
      */
-    registerApi(name, mode, schema, handler) {
-        if (this.apiDefinitions.has(name)) {
-            throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
+    async loadLazyApiGroup(name) {
+        const lazy = this.lazyApiGroups.get(name);
+        if (!lazy)
+            return;
+        if (!lazy.loading) {
+            const loading = (async () => {
+                const loaded = await lazy.group.load();
+                if (!isRegistrableApiGroup(loaded) || loaded.kind !== "lambderApiGroup") {
+                    throw new Error(`Lambder: the loader of lazy group "${name}" resolved to something that is not a group. Resolve to the value defineApiGroup() built.`);
+                }
+                if (loaded.name !== name) {
+                    throw new Error(`Lambder: lazy group "${name}" loaded the group "${loaded.name}". The loader must resolve to the group of the name it was registered under.`);
+                }
+                for (const api of this.prepareApiGroup(loaded))
+                    this.commitApi(api);
+                this.lazyApiGroups.delete(name);
+            })();
+            lazy.loading = loading;
+            loading.catch(() => { if (lazy.loading === loading)
+                lazy.loading = null; });
         }
-        // Everything that can refuse the registration runs before the name is
-        // claimed below: a refusal the app catches and fixes would otherwise
-        // leave the name taken, and the retry would report a duplicate
-        // instead of the problem it was fixing.
+        await lazy.loading;
+    }
+    /**
+     * What registering an endpoint takes: the checks that can refuse it and
+     * its mode read off its guards, into the definition apiSignatures()
+     * digests, beside its handler. Nothing is recorded here (commitApi does
+     * that), so a refusal anywhere in a registration leaves nothing behind.
+     */
+    prepareApi(name, schema, handler) {
+        const guardEntries = toGuardEntries(schema.guards);
+        const guardNeedsSession = (guard) => !!this.guards && Object.prototype.hasOwnProperty.call(this.guards, guard) && this.guards[guard]?.session === true;
+        const mode = guardEntries.some(({ name: guard }) => guardNeedsSession(guard)) ? "session" : "public";
         if (mode === "session" && !this.pipeline.hasSessions) {
-            throw new Error(`Lambder: session API "${name}" needs the session option at creation.`);
+            throw new Error(`Lambder: a guard of API "${name}" needs a session, and the instance was created without the session option.`);
         }
-        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
-        if (guardsRequired && schema.guards === undefined) {
-            const optOut = mode === "session"
-                ? "the named no-op guard that marks the session itself as the whole authorization"
-                : "the named no-op guard that records why anyone may call it";
-            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
-                `Declare the guard that authorizes it, or ${optOut}.`);
+        if (this.requireApiGuards && schema.guards === undefined) {
+            throw new Error(`Lambder: API "${name}" declares no guards, and requireApiGuards is on. ` +
+                `Declare the guard that authorizes it, or the named no-op guard that records why it needs nothing more.`);
         }
         // The option, like guards and rateLimit, is a declaration or absent:
         // an empty list would read as declaring codes while declaring none.
@@ -333,20 +521,22 @@ export default class Lambder {
         if (schema.refusals !== undefined && ownRefusals.length === 0) {
             throw new Error(`Lambder: API "${name}" declares an empty refusals option, which declares no code. Name the codes it refuses with, or omit the option entirely.`);
         }
-        const allowedCodes = resolveAllowedRefusals(name, this.refusalVocabulary, ownRefusals, toGuardEntries(schema.guards).map(({ name: guard }) => ({
+        const allowedCodes = resolveAllowedRefusals(name, this.refusalVocabulary, ownRefusals, guardEntries.map(({ name: guard }) => ({
             guard,
             codes: (this.guards && Object.prototype.hasOwnProperty.call(this.guards, guard) ? this.guards[guard]?.refusals : undefined) ?? [],
         })));
         const refusals = { codes: allowedCodes, codeRequired: this.requireRefusalCodes };
         const definition = { name, mode, guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output, refusals };
         this.pipeline.assertRegistration(definition);
-        this.apiDefinitions.set(name, definition);
-        if (schema.refusals !== undefined)
-            this.refusalOptions.set(name, schema.refusals);
-        this.actionList.push({
-            match: (ctx) => ctx.apiName === name ? {} : false,
-            actionFn: (ctx) => this.runApi(ctx, definition, schema.output, schema.compress ?? "auto", handler),
-        });
+        return { definition, refusalsOption: schema.refusals, output: schema.output, compress: schema.compress ?? "auto", handler };
+    }
+    /** Records a checked endpoint: its definition, its refusals option as written, and what answers it. */
+    commitApi(api) {
+        const { name } = api.definition;
+        this.apiDefinitions.set(name, api.definition);
+        if (api.refusalsOption !== undefined)
+            this.refusalOptions.set(name, api.refusalsOption);
+        this.apiHandlers.set(name, { output: api.output, compress: api.compress, handler: api.handler });
     }
     addHook(hookEvent, hookFn, priority = 0) {
         if (hookEvent === "created") {
@@ -378,16 +568,15 @@ export default class Lambder {
         });
         return this;
     }
-    // Plugin system
-    // The policy generics are `any` in the plugin signature on purpose: a
-    // module may annotate its parameter as the bare Lambder<SessionData> or
-    // as the app's narrowed alias, and both must chain. Registration-time
-    // assertions still check every referenced policy/guard name. Every
-    // policy generic must be listed: a missing one falls back to its default,
-    // making an instance with a non-default value unassignable to its own
-    // plugins.
+    /**
+     * Hands the instance to a function that registers on it (routes, hooks,
+     * actions) and continues the chain with what it returns. Endpoints are
+     * not registered this way: they are values, registered by
+     * registerApiGroups(), so a plugin adds nothing to the contract.
+     */
     use(plugin) {
-        return plugin(this);
+        plugin(this);
+        return this;
     }
     // =====================================================================
     // Accessors
@@ -418,6 +607,8 @@ export default class Lambder {
     [LAMBDER_BACKEND_SWAP](backends) {
         if (this.files && backends.fileSource)
             this.files[LAMBDER_BACKEND_SWAP](backends.fileSource);
+        if (backends.callSummary !== undefined)
+            this.callSummaryWriter = backends.callSummary;
         return { ...this.pipeline[LAMBDER_BACKEND_SWAP](backends), files: this.files !== null };
     }
     /**
@@ -451,6 +642,7 @@ export default class Lambder {
      * unless the generator writes it there.
      */
     async apiSignatureEntries() {
+        await this.loadApiGroups();
         const entries = await Promise.all([...this.apiDefinitions.values()].map(async (definition) => ({
             name: definition.name,
             key: await apiNameKeyOf(definition.name),
@@ -478,7 +670,8 @@ export default class Lambder {
      * same object. Every table is sorted by name, so the module diffs by
      * endpoint and never moves when registrations are reordered.
      */
-    apiOptionEntries() {
+    async apiOptionEntries() {
+        await this.loadApiGroups();
         const apis = {};
         for (const name of [...this.apiDefinitions.keys()].sort()) {
             const { mode, guards, rateLimit, idempotency } = this.apiDefinitions.get(name);
@@ -624,11 +817,22 @@ export default class Lambder {
         const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver, onContextReplaced);
         if (beforeRenderResult instanceof LambderResponse)
             return beforeRenderResult;
-        const currentCtx = beforeRenderResult;
+        return await this.answerUnmatched(beforeRenderResult, resolver);
+    }
+    /**
+     * What answers a request nothing matched, its beforeRender hooks run:
+     * the fallback hooks, then the API fallback for an API call, and
+     * otherwise the public files, the shell and the route fallback in turn.
+     */
+    async answerUnmatched(currentCtx, resolver) {
         for (const hook of this.hookList["fallback"]) {
             await hook.hookFn(currentCtx, resolver);
         }
-        const isAPI = currentCtx.api !== null || currentCtx.path === this.apiPath;
+        // 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.
+        const apiArea = this.apiPath.replace(/\/+$/, "");
+        const isAPI = currentCtx.api !== null || currentCtx.path === this.apiPath || (apiArea !== "" && currentCtx.path.startsWith(`${apiArea}/`));
         if (isAPI) {
             if (this.apiFallbackHandler)
                 return await this.apiFallbackHandler(currentCtx, resolver);
@@ -661,6 +865,10 @@ export default class Lambder {
         if (this.isCorsPreflight(ctx))
             return new LambderResponse({ statusCode: 204, body: null });
         if (ctx.api) {
+            // A page built before endpoints had paths: its call cannot be
+            // answered, and telling it its version expired is what reloads it.
+            if (ctx.api.retiredPath)
+                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
@@ -694,7 +902,19 @@ export default class Lambder {
             return beforeRenderResult;
         return await matched.action.actionFn(beforeRenderResult, resolver);
     }
+    /**
+     * One HTTP invocation, from the event to the finalized response, under
+     * an invocation record of its own (see LambderInvocationScope): what an
+     * API call's summary line is written from once the response is final.
+     */
     async render(event, lambdaContext) {
+        return await runInvocation(lambdaContext, async (invocation) => {
+            const response = await this.renderRequest(event, lambdaContext, invocation);
+            this.writeCallSummary(invocation, response.statusCode);
+            return response;
+        });
+    }
+    async renderRequest(event, lambdaContext, invocation) {
         let ctx = null;
         let started = false;
         // Settled as soon as the context exists and reused by every answer,
@@ -703,11 +923,8 @@ export default class Lambder {
         try {
             await this.ensureInitialized();
             started = true;
-            ctx = bindContextTools(createContext(event, lambdaContext, {
-                apiPath: this.apiPath,
-                trustedClientIpHeaders: this.trustedClientIpHeaders,
-                trustedHostHeaders: this.trustedHostHeaders,
-            }), this.contextTools);
+            ctx = bindContextTools(createContext(event, lambdaContext, this.contextOptions()), this.contextTools);
+            invocation.call = apiCallOf(ctx, event);
             if (this.corsConfig)
                 allowedOrigin = allowedCorsOriginOf(this.corsConfig, ctx);
             const resolver = this.getResolver(ctx);
@@ -756,12 +973,33 @@ export default class Lambder {
             // reach it.
             ctx.responseHeaders.applyTo(response, response === responseIntoHooks ? headersAppliedIntoHooks : 0);
             this.applyCors(allowedOrigin, response, this.isCorsPreflight(ctx));
+            invocation.outcome = response.callOutcome ?? { outcome: "other", code: null };
             return await finalizeResponse(ctx, response, this.finalizeOptions, ctx.eventFormat);
         }
         catch (err) {
+            // A crash before the context existed (a created hook that failed)
+            // still answers an API call, and its summary line is the one a
+            // dashboard counts the crash by. The context is read from the
+            // event and the instance's options alone, so it can be read here;
+            // an event it cannot be read from has no call to name.
+            if (!ctx) {
+                try {
+                    invocation.call = apiCallOf(createContext(event, lambdaContext, this.contextOptions()), event);
+                }
+                catch { /* no call to name */ }
+            }
             return await this.answerCrash(err, ctx, allowedOrigin, started, event, lambdaContext);
         }
     }
+    /** What createContext reads this instance's requests with. */
+    contextOptions() {
+        return {
+            apiPath: this.apiPath,
+            trustedClientIpHeaders: this.trustedClientIpHeaders,
+            trustedHostHeaders: this.trustedHostHeaders,
+            originProof: this.originProof,
+        };
+    }
     /**
      * A thrown value that is an answer rather than a crash, as the response;
      * anything else is rethrown to the crash path.
@@ -781,7 +1019,7 @@ export default class Lambder {
         if (thrown instanceof LambderResponse)
             return thrown;
         if (isLambderApiRefusal(thrown) && ctx.api)
-            return this.apiErrorResponse(thrown, ctx);
+            return await this.apiErrorResponse(thrown, ctx);
         if (thrown instanceof LambderSessionNotFoundError)
             return await this.sessionMissingResponse(ctx, resolver);
         throw thrown;
@@ -800,6 +1038,10 @@ export default class Lambder {
         // invocation would reject with a 502 no client can parse.
         const error = coerceToError(thrown, "an unstringifiable thrown value");
         this.crashWatcher?.(error);
+        // A crash, whatever the global error handler then answers with.
+        const invocation = currentInvocation();
+        if (invocation)
+            invocation.outcome = { outcome: "crash", code: null };
         const site = !started ? { kind: "startup", lambdaContext }
             : ctx?.api ? { kind: "api", ctx, lambdaContext }
                 : { kind: "route", ctx, lambdaContext };
@@ -836,6 +1078,37 @@ export default class Lambder {
         const crashResponse = this.withCallHeaders(ctx, allowedOrigin, await this.crashHandling.frameworkResponse(error, ctx, errorHandlerCrash));
         return emitResponse(eventFormat, crashResponse.statusCode, crashResponse.headers, typeof crashResponse.body === "string" ? crashResponse.body : "", false);
     }
+    /**
+     * The summary line of an API call, once its response is final: nothing
+     * for an invocation that served no API call. A writer that throws costs
+     * the call its line and nothing else.
+     */
+    writeCallSummary(invocation, status) {
+        const { call } = invocation;
+        if (!call || !this.callSummaryWriter)
+            return;
+        const summary = {
+            kind: "lambder.call",
+            // The path form is two identifiers; a page built before paths
+            // posts the name in its body, which is whatever it sent.
+            api: call.api.slice(0, MAX_SUMMARY_API_NAME_CHARS),
+            outcome: invocation.outcome?.outcome ?? "other",
+            code: invocation.outcome?.code ?? null,
+            status,
+            durationMs: roundedMilliseconds(performance.now() - invocation.startedAt),
+            handlerMs: invocation.handlerMs === null ? null : roundedMilliseconds(invocation.handlerMs),
+            replayed: invocation.replayed,
+            coldStart: invocation.coldStart,
+            requestId: invocation.requestId,
+            parentRequestId: call.parentRequestId,
+        };
+        try {
+            this.callSummaryWriter(summary);
+        }
+        catch (err) {
+            console.error(`Lambder: the callSummary writer threw, so the summary of "${summary.api}" was not written. ${coerceToError(err).message}`);
+        }
+    }
     /**
      * An answer to a crash, carrying what the call wrote and its CORS headers.
      * As on the success path, headers belong to the call: a call that wrote a
@@ -892,6 +1165,11 @@ export default class Lambder {
      * so Lambda's retries and dead-letter queues still see the failure.
      */
     async renderEvent(event, lambdaContext) {
+        // Under an invocation record, like an HTTP invocation, so the calls an
+        // action makes over invoke carry its request id.
+        return await runInvocation(lambdaContext, () => this.renderEventAction(event, lambdaContext));
+    }
+    async renderEventAction(event, lambdaContext) {
         let started = false;
         try {
             await this.ensureInitialized();
@@ -923,7 +1201,8 @@ export default class Lambder {
      */
     async inputValidationRefusal(ctx, zodError) {
         if (this.apiInputValidationErrorHandler) {
-            return answerFromResponse(await this.apiInputValidationErrorHandler(ctx, this.getResolver(ctx), zodError));
+            // A validation refusal, however the app words it.
+            return { ...answerFromResponse(await this.apiInputValidationErrorHandler(ctx, this.getResolver(ctx), zodError)), outcome: { outcome: "validation", code: null } };
         }
         // null asks the pipeline for the standard 422, so that answer is
         // written once, in the core, rather than here as well.
@@ -962,9 +1241,18 @@ export default class Lambder {
         const request = ctx.api;
         if (!request)
             throw new Error(`Lambder: API "${definition.name}" was matched by a request that is not an API call.`);
-        const { answer } = await this.pipeline.run(request, ctx, definition, async () => {
+        const invocation = currentInvocation();
+        const { answer, replayed } = await this.pipeline.run(request, ctx, definition, async () => {
             ctx.apiPayload = request.payload;
-            const returned = await handler(ctx);
+            const handlerStarted = performance.now();
+            let returned;
+            try {
+                returned = await handler(ctx);
+            }
+            finally {
+                if (invocation)
+                    invocation.handlerMs = performance.now() - handlerStarted;
+            }
             let parsed;
             try {
                 parsed = output.safeParse(returned);
@@ -979,19 +1267,23 @@ export default class Lambder {
             return envelopeAnswer(successEnvelope(this.apiVersion, parsed.data, ctx.logList));
         });
         // The API's compress option, on whatever answer the call ended with:
-        // a replayed one comes back from its store without the hint.
-        return responseFromAnswer({ ...answer, compress });
+        // a replayed one comes back from its store without the hints, and
+        // its outcome is read back from its text, which only a replay costs.
+        if (invocation)
+            invocation.replayed = replayed;
+        return responseFromAnswer({ ...answer, compress, outcome: answer.outcome ?? outcomeOfAnswerText(answer.statusCode, answer.body) });
     }
     /**
      * 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. A name no API is
+     * 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.
      */
-    apiErrorResponse(err, ctx) {
+    async apiErrorResponse(err, ctx) {
         const apiName = ctx.apiName ?? "";
-        const refusal = checkedRefusal(apiName, this.apiDefinitions.get(apiName)?.refusals ?? NO_DECLARED_REFUSALS, err);
+        const refusal = checkedRefusal(apiName, (await this.registeredDefinitionOf(apiName))?.refusals ?? NO_DECLARED_REFUSALS, err);
         return responseFromAnswer(refusalAnswer(refusal, this.apiVersion, ctx.logList));
     }
 }
@@ -1025,7 +1317,10 @@ export const initLambder = () => ({
      * Declares the app's refusal vocabulary: every code once, with the schema
      * of its data (`{ data: schema }`) or none (`{}`), the status every
      * refusal with it leaves with (`status`, 200 by default) and whether it
-     * sets the notAuthorized flag (`notAuthorized: true`). Returns the init
+     * sets the notAuthorized flag (`notAuthorized: true`). One map of codes,
+     * or a list of them, as guards and rate-limit policies are declared, so
+     * each part of an app declares its own codes; a code two maps declare is
+     * refused, at compile time and at the call. Returns the init
      * bound to it: its guard() types ctx.refuse to a guard's refusals and
      * refuses a guard naming a code outside the vocabulary, its refuse is
      * typed to the whole vocabulary, and its create() hands the vocabulary to
@@ -1034,9 +1329,11 @@ export const initLambder = () => ({
      * "no" a client reads names a code.
      */
     declareRefusals(refusals, options = {}) {
-        const vocabulary = readRefusalVocabulary(refusals);
-        if (!vocabulary)
-            throw new Error("Lambder: declareRefusals() takes the vocabulary, an object of codes.");
-        return lambderInitOf({ refusals, vocabulary, requireCodes: (options.requireCodes ?? false) });
+        const declared = declaredRefusalVocabulary(refusals, "Lambder");
+        return lambderInitOf({
+            refusals: declared.refusals,
+            vocabulary: declared.vocabulary,
+            requireCodes: (options.requireCodes ?? false),
+        });
     },
 });