lambder 7.2.5 → 8.0.2

package/dist/api/LambderApiPipeline.d.ts

@@ -5,20 +5,22 @@ import type { LambderApiCallContext } from "./LambderApiCallContext.js";
 import type { LambderApiCallTrace } from "./LambderApiCallContext.js";
 import type { LambderApiDefinition } from "./LambderApiDefinition.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
-import type { LambderApiGuard } from "./LambderApiGuards.js";
-import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
-import type { LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
-import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
+import { type LambderApiGuard } from "./LambderApiGuards.js";
+import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitChargeResult, type LambderRateLimitChargeSubject } from "./LambderApiRateLimits.js";
+import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
+import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import type LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController, { type LambderSessionCookieOptions, type LambderSessionRequestInfo } from "../session/LambderSessionController.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
 /**
  * The app's own answer for a rejected input (setApiInputValidationErrorHandler
- * on the server). Returning null asks for the standard 422 body, which is
- * what an adapter whose app set no handler answers: the rule lives in the
- * pipeline alone, so "no handler, standard 422" is written once. The API's
- * schema and every preflight slice (guard inputs, rate-limit keys) answer
- * through here, so one failure has one shape.
+ * on the server). Returning null asks for the standard 422 body, which only
+ * the pipeline writes, so every adapter without a handler answers alike. The
+ * API's schema and every preflight slice (guard inputs, rate-limit keys)
+ * answer through here, so one failure has one shape.
  */
 export type LambderApiInputRefusal<TCtx> = (zodError: z.ZodError, ctx: TCtx, request: LambderApiRequest) => MaybePromise<LambderApiAnswer | null>;
 /** The session subsystem as the pipeline runs it: the manager plus the cookie names and scope the controller writes. */
@@ -57,6 +59,26 @@ export type LambderApiPipelineOptions<TCtx extends LambderApiCallContext<TSessio
     }>>;
     idempotency?: LambderApiIdempotencyConfig;
 };
+/** The stores `lambder/testing` puts under a built pipeline. One the pipeline has no subsystem for is left aside. */
+export type LambderPipelineBackends = {
+    sessionStore?: LambderSessionStore<any>;
+    rateLimiter?: LambderRateLimiter;
+    idempotencyStore?: LambderIdempotencyStore;
+};
+/**
+ * What a backend swap found: whether the rate-limit and idempotency
+ * subsystems exist to take a store, and, when sessions are configured, the
+ * cookie names a caller over this pipeline has to be told (they are the
+ * app's own choice and nothing else hands them out).
+ */
+export type LambderPipelineBackendSwap = {
+    sessions: {
+        tokenCookieKey: string;
+        csrfCookieKey: string;
+    } | null;
+    rateLimits: boolean;
+    idempotency: boolean;
+};
 /** What one run produced, beside the answer: what an adapter may want to report. */
 export type LambderApiRunResult = LambderApiCallTrace & {
     answer: LambderApiAnswer;
@@ -69,16 +91,22 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * version floor → signature gate → restore payload → rate limits that need no session
- * → session (session mode) → idempotency replay → the remaining rate limits
- * → guards → input validation → exec, inside the idempotency claim
- * → drain response headers → answer
+ * version floor → signature gate → restore payload → rate limits keyed per ip
+ * → session (session mode) → idempotency replay → rate limits keyed per session
+ * (and custom keys charged beforeGuards) → guards → input validation → guards
+ * placed after it → rate limits keyed by a custom key → exec, inside the
+ * idempotency claim → drain response headers → answer
  * ```
  *
+ * Each policy subsystem (rate limits, guards, idempotency) is its own
+ * engine, held here and called at its step, so the order above can be read
+ * directly off execute().
+ *
  * Steps whose subsystem is not configured are skipped. A LambderApiRefusal
  * thrown by any step, guard or handler is rendered here, in one place: a
  * validation error through onInvalidInput, any other refusal as the refusal
- * envelope. Anything else propagates, because only the adapter knows what a
+ * envelope, and a session ended while the handler held it
+ * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
  * crash means (a global error handler, a mock event).
  *
  * `run` never sees a name it has no definition for; resolving a name to a
@@ -89,7 +117,9 @@ export type LambderApiExec<TCtx> = (ctx: TCtx) => Promise<LambderApiAnswer>;
 export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSessionData>, TSessionData = any> {
     readonly apiVersion: string | null;
     readonly minApiVersion: string | null;
-    private readonly policies;
+    private readonly rateLimits;
+    private readonly guards;
+    private readonly idempotency;
     private readonly maxRequestPayloadBytes;
     private readonly onInvalidInput;
     private readonly sessions;
@@ -105,8 +135,20 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * (its cookies and posted CSRF token) or a route's (cookies and no CSRF).
      */
     sessionController(ctx: TCtx, request: LambderSessionRequestInfo): LambderSessionController<TSessionData>;
+    /**
+     * The backend swap: each store given goes under the subsystem that holds
+     * one, and everything the app configured around it (the session model,
+     * the named policies, the replay TTLs) stays in force.
+     */
+    [LAMBDER_BACKEND_SWAP](backends: LambderPipelineBackends): LambderPipelineBackendSwap;
     /** The session request info of an API request: its cookies, and the CSRF token it posted. */
     static sessionInfoOf(request: LambderApiRequest): LambderSessionRequestInfo;
+    /**
+     * One named rate-limit policy charged by code: what an adapter's
+     * `ctx.rateLimit` and `ctx.isRateLimited` run. The adapter supplies who is
+     * being counted, since only it knows whether the request is an API call.
+     */
+    chargeRateLimit(name: string, subject: LambderRateLimitChargeSubject): Promise<LambderRateLimitChargeResult>;
     /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */
     assertRegistration(definition: LambderApiDefinition): void;
     /**
@@ -117,32 +159,28 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * client built against a contract that had it) has already been answered
      * versionExpired by the time anything asks for an unknown name.
      */
-    answerUnknownApi(request: LambderApiRequest, ctx?: TCtx): LambderApiAnswer;
+    answerUnknownApi(ctx?: TCtx): LambderApiAnswer;
     /**
      * The steps that come before anything may read the request: the version
      * floor, the signature gate, then the compressed-payload restore that
      * every later reader (a rate-limit key slice, a guard, the input schema)
-     * depends on having happened.
-     *
-     * The floor answers versionExpired to a request naming a version below
-     * minApiVersion whatever its signature says: the lever for a change the
-     * digest cannot see (a security fix, a field whose meaning changed under
-     * the same shape). A request naming no version is not judged by it, as
-     * one carrying no signature is not gated.
+     * relies on.
      *
-     * The gate compares the signature the request carries with the map's
-     * entry for the endpoint it names. A match runs; anything else, another
-     * entry or none, is a client built against another shape of this
-     * endpoint or against an endpoint that no longer exists, and is answered
-     * versionExpired. A request carrying no signature is never gated.
+     * The floor refuses a request naming a version below minApiVersion,
+     * whatever its signature says: the lever for a change the digest cannot
+     * see (a security fix, a field whose meaning changed under the same
+     * shape). The gate refuses a signature that is not the map's entry for
+     * the endpoint named (another entry, or none): a client built against
+     * another shape of this endpoint, or against one that no longer exists.
+     * Both answer versionExpired. A request naming no version skips the
+     * floor, and one carrying no signature skips the gate.
      *
-     * Public and named because the server runs them earlier than run() does,
-     * on the way in, so that its hooks see a plain payload and a stale client
-     * is answered before any of them, whether or not the name it asked for
-     * exists. run() calls it too, so an adapter that has no such step still
-     * gets the whole protocol. Calling it twice is safe by construction: the
-     * gates are comparisons and the restore has already removed the wire
-     * fields it reads.
+     * Public because the server runs it earlier, on the way in, so its hooks
+     * see a plain payload and a stale client is answered before any of them,
+     * whether or not the name it asked for exists. run() calls it too, so an
+     * adapter without that step still gets the whole protocol. Calling it
+     * twice is safe: the gates are comparisons, and the restore has already
+     * removed the wire fields it reads.
      *
      * Returns the answer that ends the call, or null when the request is
      * ready to dispatch.
@@ -153,10 +191,10 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      *
      * An adapter that wants to report what the call did even when it crashed
      * passes its own trace object: the pipeline writes into that one, so a
-     * handler that threw still leaves the guards it ran behind for the
-     * adapter's catch. Without it the trace was created here and lost with
-     * the throw, and the mock's call log showed no guards on exactly the
-     * calls a developer opens the log for.
+     * handler that threw still leaves the guards it ran for the adapter's
+     * catch. A trace created here would be lost with the throw, and the
+     * mock's call log would show no guards on exactly the calls a developer
+     * opens it for.
      */
     run(request: LambderApiRequest, ctx: TCtx, definition: LambderApiDefinition, exec: LambderApiExec<TCtx>, trace?: LambderApiCallTrace): Promise<LambderApiRunResult>;
     private execute;

package/dist/api/LambderApiPipeline.js

@@ -6,25 +6,36 @@ import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 import { compareDottedVersions, isDottedVersion } from "../shared/wire/LambderVersionOrder.js";
-import { LambderApiPolicyEngine } from "./LambderApiPolicyEngine.js";
-import LambderSessionController, { assertSessionCookiePrefixes, } from "../session/LambderSessionController.js";
+import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
+import { LambderApiRateLimitsEngine, } from "./LambderApiRateLimits.js";
+import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
+import LambderSessionController, { assertSessionCookiePrefixes, LambderSessionNotFoundError, } from "../session/LambderSessionController.js";
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
+/** An API that asks for idempotency: declared, and not the explicit `false` opt-out. */
+const usesIdempotency = (definition) => definition.idempotency !== undefined && definition.idempotency !== false;
 /**
  * The API pipeline: one API call from a parsed request to a plain answer,
  * in the order the protocol defines. The Lambda server and the mock runtime
  * are adapters over this class; neither reimplements a step of it.
  *
  * ```
- * version floor → signature gate → restore payload → rate limits that need no session
- * → session (session mode) → idempotency replay → the remaining rate limits
- * → guards → input validation → exec, inside the idempotency claim
- * → drain response headers → answer
+ * version floor → signature gate → restore payload → rate limits keyed per ip
+ * → session (session mode) → idempotency replay → rate limits keyed per session
+ * (and custom keys charged beforeGuards) → guards → input validation → guards
+ * placed after it → rate limits keyed by a custom key → exec, inside the
+ * idempotency claim → drain response headers → answer
  * ```
  *
+ * Each policy subsystem (rate limits, guards, idempotency) is its own
+ * engine, held here and called at its step, so the order above can be read
+ * directly off execute().
+ *
  * Steps whose subsystem is not configured are skipped. A LambderApiRefusal
  * thrown by any step, guard or handler is rendered here, in one place: a
  * validation error through onInvalidInput, any other refusal as the refusal
- * envelope. Anything else propagates, because only the adapter knows what a
+ * envelope, and a session ended while the handler held it
+ * (LambderSessionNotFoundError) as sessionExpired. Anything else propagates, because only the adapter knows what a
  * crash means (a global error handler, a mock event).
  *
  * `run` never sees a name it has no definition for; resolving a name to a
@@ -35,7 +46,9 @@ import { DEFAULT_SESSION_CSRF_COOKIE_KEY, DEFAULT_SESSION_TOKEN_COOKIE_KEY } fro
 export class LambderApiPipeline {
     apiVersion;
     minApiVersion;
-    policies = new LambderApiPolicyEngine();
+    rateLimits = new LambderApiRateLimitsEngine();
+    guards = new LambderApiGuardsEngine();
+    idempotency;
     maxRequestPayloadBytes;
     onInvalidInput;
     sessions;
@@ -54,16 +67,16 @@ export class LambderApiPipeline {
             if (!isDottedVersion(this.minApiVersion)) {
                 throw new Error(`Lambder: minApiVersion must be a dotted version such as "1.2.10", got ${JSON.stringify(this.minApiVersion)}.`);
             }
-            // A floor above the version this server stamps on its answers
-            // would refuse the very clients this build serves, and the first
-            // symptom would be every tab reloading. The lower of the two is
-            // the most a floor can mean here, so that is what it becomes, and
-            // the mistake is said once at creation.
+            // A floor above the version this server stamps would refuse this
+            // build's own clients, and the first symptom would be every tab
+            // reloading. The floor is clamped to apiVersion and the mistake
+            // reported once, at creation.
             if (this.apiVersion !== null && compareDottedVersions(this.minApiVersion, this.apiVersion) > 0) {
                 console.warn(`Lambder: minApiVersion ${this.minApiVersion} is above apiVersion ${this.apiVersion}; the floor is taken as ${this.apiVersion}.`);
                 this.minApiVersion = this.apiVersion;
             }
         }
+        this.idempotency = new LambderApiIdempotencyEngine(this.apiVersion);
         this.apiSignatures = options.apiSignatures ?? null;
         this.maxRequestPayloadBytes = assertPositiveInteger(options.maxRequestPayloadBytes ?? DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, "maxRequestPayloadBytes");
         this.onInvalidInput = options.onInvalidInput ?? null;
@@ -78,11 +91,11 @@ export class LambderApiPipeline {
         if (this.sessions)
             assertSessionCookiePrefixes(this.sessions);
         if (options.rateLimits)
-            this.policies.configureRateLimits(options.rateLimits);
+            this.rateLimits.configure(options.rateLimits);
         if (options.guards)
-            this.policies.configureGuards(options.guards);
+            this.guards.configure(options.guards);
         if (options.idempotency)
-            this.policies.configureIdempotency(options.idempotency);
+            this.idempotency.configure(options.idempotency);
     }
     /** True when a session manager was configured. */
     get hasSessions() { return this.sessions !== null; }
@@ -109,13 +122,53 @@ export class LambderApiPipeline {
             request,
         });
     }
+    /**
+     * The backend swap: each store given goes under the subsystem that holds
+     * one, and everything the app configured around it (the session model,
+     * the named policies, the replay TTLs) stays in force.
+     */
+    [LAMBDER_BACKEND_SWAP](backends) {
+        if (this.sessions && backends.sessionStore)
+            this.sessions.manager[LAMBDER_BACKEND_SWAP](backends.sessionStore);
+        return {
+            sessions: this.sessions ? { tokenCookieKey: this.sessions.tokenCookieKey, csrfCookieKey: this.sessions.csrfCookieKey } : null,
+            rateLimits: backends.rateLimiter ? this.rateLimits[LAMBDER_BACKEND_SWAP](backends.rateLimiter) : false,
+            idempotency: backends.idempotencyStore ? this.idempotency[LAMBDER_BACKEND_SWAP](backends.idempotencyStore) : false,
+        };
+    }
     /** The session request info of an API request: its cookies, and the CSRF token it posted. */
     static sessionInfoOf(request) {
         return { host: request.host, cookies: request.cookies, csrfToken: request.token };
     }
+    /**
+     * One named rate-limit policy charged by code: what an adapter's
+     * `ctx.rateLimit` and `ctx.isRateLimited` run. The adapter supplies who is
+     * being counted, since only it knows whether the request is an API call.
+     */
+    async chargeRateLimit(name, subject) {
+        return await this.rateLimits.chargePolicy(name, subject);
+    }
     /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */
     assertRegistration(definition) {
-        this.policies.assertRegistration(definition);
+        const { name, mode } = definition;
+        // Each subsystem reports its own absence: one combined message would
+        // name all three when only one of them is missing.
+        if (definition.rateLimit !== undefined && !this.rateLimits.isConfigured) {
+            throw new Error(`Lambder: API "${name}" declares rateLimit but no rateLimits option was configured at creation.`);
+        }
+        if (definition.guards !== undefined && !this.guards.isConfigured) {
+            throw new Error(`Lambder: API "${name}" declares guards but no guards option was configured at creation.`);
+        }
+        this.rateLimits.assertRegistration(name, mode, definition.rateLimit);
+        this.guards.assertRegistration(name, mode, definition.guards);
+        // `idempotency: false` is an explicit opt-out, not a use: it asks for
+        // nothing and so needs no store behind it.
+        if (usesIdempotency(definition)) {
+            if (!this.idempotency.isConfigured) {
+                throw new Error(`Lambder: API "${name}" declares idempotency but no idempotency store was configured at creation.`);
+            }
+            this.idempotency.assertRegistration(name, definition.idempotency);
+        }
     }
     /**
      * The answer for a request naming no registered API: the apiNotFound
@@ -125,7 +178,7 @@ export class LambderApiPipeline {
      * client built against a contract that had it) has already been answered
      * versionExpired by the time anything asks for an unknown name.
      */
-    answerUnknownApi(request, ctx) {
+    answerUnknownApi(ctx) {
         const answer = apiNotFoundAnswer(this.apiVersion, ctx?.logList);
         ctx?.responseHeaders.applyInto(answer.headers);
         return answer;
@@ -134,27 +187,23 @@ export class LambderApiPipeline {
      * The steps that come before anything may read the request: the version
      * floor, the signature gate, then the compressed-payload restore that
      * every later reader (a rate-limit key slice, a guard, the input schema)
-     * depends on having happened.
+     * relies on.
      *
-     * The floor answers versionExpired to a request naming a version below
-     * minApiVersion whatever its signature says: the lever for a change the
-     * digest cannot see (a security fix, a field whose meaning changed under
-     * the same shape). A request naming no version is not judged by it, as
-     * one carrying no signature is not gated.
+     * The floor refuses a request naming a version below minApiVersion,
+     * whatever its signature says: the lever for a change the digest cannot
+     * see (a security fix, a field whose meaning changed under the same
+     * shape). The gate refuses a signature that is not the map's entry for
+     * the endpoint named (another entry, or none): a client built against
+     * another shape of this endpoint, or against one that no longer exists.
+     * Both answer versionExpired. A request naming no version skips the
+     * floor, and one carrying no signature skips the gate.
      *
-     * The gate compares the signature the request carries with the map's
-     * entry for the endpoint it names. A match runs; anything else, another
-     * entry or none, is a client built against another shape of this
-     * endpoint or against an endpoint that no longer exists, and is answered
-     * versionExpired. A request carrying no signature is never gated.
-     *
-     * Public and named because the server runs them earlier than run() does,
-     * on the way in, so that its hooks see a plain payload and a stale client
-     * is answered before any of them, whether or not the name it asked for
-     * exists. run() calls it too, so an adapter that has no such step still
-     * gets the whole protocol. Calling it twice is safe by construction: the
-     * gates are comparisons and the restore has already removed the wire
-     * fields it reads.
+     * Public because the server runs it earlier, on the way in, so its hooks
+     * see a plain payload and a stale client is answered before any of them,
+     * whether or not the name it asked for exists. run() calls it too, so an
+     * adapter without that step still gets the whole protocol. Calling it
+     * twice is safe: the gates are comparisons, and the restore has already
+     * removed the wire fields it reads.
      *
      * Returns the answer that ends the call, or null when the request is
      * ready to dispatch.
@@ -178,10 +227,10 @@ export class LambderApiPipeline {
      *
      * An adapter that wants to report what the call did even when it crashed
      * passes its own trace object: the pipeline writes into that one, so a
-     * handler that threw still leaves the guards it ran behind for the
-     * adapter's catch. Without it the trace was created here and lost with
-     * the throw, and the mock's call log showed no guards on exactly the
-     * calls a developer opens the log for.
+     * handler that threw still leaves the guards it ran for the adapter's
+     * catch. A trace created here would be lost with the throw, and the
+     * mock's call log would show no guards on exactly the calls a developer
+     * opens it for.
      */
     async run(request, ctx, definition, exec, trace = { guardsRun: [], replayed: false }) {
         let answer;
@@ -195,6 +244,14 @@ export class LambderApiPipeline {
             else if (isLambderApiRefusal(err)) {
                 answer = refusalAnswer(err, this.apiVersion, ctx.logList);
             }
+            else if (err instanceof LambderSessionNotFoundError) {
+                // No usable session: it ended while the handler held it (a
+                // logout or a password change landed mid-request), or a read
+                // the handler made found none or several
+                // (LambderSessionAmbiguousError is one of these). The same
+                // answer a session read that found none gives.
+                answer = sessionExpiredAnswer(this.apiVersion, ctx.logList);
+            }
             else {
                 throw err;
             }
@@ -213,11 +270,11 @@ export class LambderApiPipeline {
         // The limits whose key is known from the request alone, before the
         // session store is asked anything: a request carrying bogus session
         // cookies costs up to four store reads, and answering it
-        // sessionExpired without the limiter having run let one address spend
+        // sessionExpired before the limiter runs would let one address spend
         // the session store's read budget freely. A replay costs the same
-        // reads, so an ip-limited replay counts against that budget too: the
-        // limit protects the stores, not the handler.
-        await this.policies.runSessionlessRateLimits(request, ctx, definition);
+        // reads, so an ip-limited replay counts too: the limit protects the
+        // stores, not the handler.
+        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "beforeSession");
         if (definition.mode === "session") {
             if (!this.sessions)
                 throw new Error(`Lambder: API "${definition.name}" is a session API, but no session store was configured at creation.`);
@@ -228,33 +285,49 @@ export class LambderApiPipeline {
         // Replay fast path: a completed idempotent request answers its stored
         // answer without burning the remaining rate-limit quota or re-running
         // guards. After the session read, because the replay scope is keyed
-        // per session.
-        const replay = await this.policies.findReplay(request, ctx, definition, trace);
+        // per user, by the session's sessionKey.
+        const keyedCall = usesIdempotency(definition) ? await this.idempotency.resolveKeyedCall(definition.name, request, ctx) : null;
+        const replay = keyedCall ? await this.idempotency.findReplay(definition.name, keyedCall, trace) : null;
         if (replay)
             return replay;
-        await this.policies.runPreflight(request, ctx, definition, trace);
-        if (definition.input) {
-            const parsed = definition.input.safeParse(request.payload);
-            if (!parsed.success)
-                throw new LambderApiValidationRefusal(parsed.error);
+        // What refuses a request without spending anything on it comes first:
+        // the limits keyed per session, the guards, the input. What spends
+        // something comes last: a guard placed after validation (a
+        // single-use captcha a mistyped field would otherwise waste), and the
+        // limits keyed by a caller-chosen value (an email in the payload),
+        // which charged earlier would let a caller who never passes the
+        // captcha spend a victim's budget. Refusals throw; the trace records
+        // each guard as it runs.
+        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "beforeGuards");
+        await this.guards.run(request, ctx, definition.guards, trace, "beforeInputValidation");
+        // Asynchronously, so an input schema with an async refinement
+        // validates instead of making zod throw on every call. The parse is
+        // handed to the handler only after the late guards and the custom
+        // keys, which read their slices from the payload as it was sent.
+        const parsed = definition.input ? await definition.input.safeParseAsync(request.payload) : null;
+        if (parsed && !parsed.success)
+            throw new LambderApiValidationRefusal(parsed.error);
+        await this.guards.run(request, ctx, definition.guards, trace, "afterInputValidation");
+        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "afterGuards");
+        if (parsed)
             request.payload = parsed.data;
-        }
         // The handler's own answer, and only that: what it wrote into
-        // responseHeaders during the call is on it before the idempotency
-        // engine judges and stores it, while a header written EARLIER in the
-        // call is not. That line matters, because the engine refuses to store
-        // an answer carrying a Set-Cookie: charge it with the stale-session
-        // cookie the session read evicted and an otherwise idempotent
-        // operation would silently stop being idempotent and re-execute on
-        // every retry. The call's earlier headers still reach the client;
-        // run() applies them to the answer on the way out.
+        // responseHeaders during the call goes on before the idempotency
+        // engine judges and stores it, while a header written earlier in the
+        // call does not. The engine refuses to store an answer carrying a
+        // Set-Cookie, so the stale-session cookie the session read evicted
+        // would silently make an idempotent operation re-execute on every
+        // retry. The earlier headers still reach the client: run() applies
+        // them on the way out.
         const runHandler = async () => {
             const handlerFirstHeader = ctx.responseHeaders.size;
             const produced = await exec(ctx);
             ctx.responseHeaders.applyInto(produced.headers, handlerFirstHeader);
             return produced;
         };
-        return await this.policies.withIdempotency(request, ctx, definition, trace, runHandler);
+        return keyedCall && usesIdempotency(definition)
+            ? await this.idempotency.withIdempotency(definition.name, keyedCall, definition.idempotency, trace, runHandler)
+            : await runHandler();
     }
     async refuseInput(err, ctx, request) {
         const custom = this.onInvalidInput ? await this.onInvalidInput(err.zodError, ctx, request) : null;