lambder 11.1.1 → 13.0.1

package/dist/shared/wire/LambderApiGroupCalls.js

@@ -0,0 +1,68 @@
+import { isActionName, isGroupName } from "./LambderApiNames.js";
+/**
+ * The caller, answering for each group a contract could name besides its
+ * own members. A member the caller has (a method, a field) is always the
+ * caller's; a name that could be a group (see isGroupName: an identifier no
+ * caller member has) is one; anything else a runtime or a framework asks of
+ * an object (then, toJSON, a symbol, `__v_isRef`) is what the caller itself
+ * answers, so a caller is never mistaken for a promise, a ref or a
+ * serializable record.
+ *
+ * A caller keeps its state in #private fields, which no property name
+ * reaches, so a group may take any name its public members leave free. Such
+ * a field is readable only on the caller itself, never through this proxy,
+ * so a member is read and a method run on the caller; a method that returns
+ * the caller (setTransport) hands back the proxy, groups and all.
+ *
+ * A group answers the same way one level down: an ordinary object's own
+ * members (toString, valueOf, hasOwnProperty) are an ordinary object's, so
+ * converting a group to a string or asking it what it holds calls no
+ * endpoint; any other name that could be an action (see isActionName) is
+ * one. A group is read-only, like the type that describes it.
+ */
+export const withApiGroupCalls = (caller, call, outcome) => {
+    const methods = new WeakMap();
+    const methodOnCaller = (method) => {
+        let bound = methods.get(method);
+        if (!bound) {
+            bound = (...args) => {
+                const result = Reflect.apply(method, caller, args);
+                return result === caller ? withGroups : result;
+            };
+            methods.set(method, bound);
+        }
+        return bound;
+    };
+    const groups = new Map();
+    const groupOf = (group) => {
+        let calls = groups.get(group);
+        if (!calls) {
+            const actions = new Map();
+            calls = new Proxy(Object.freeze({}), {
+                get: (target, action) => {
+                    if (typeof action !== "string" || action in target || !isActionName(action))
+                        return Reflect.get(target, action);
+                    let endpoint = actions.get(action);
+                    if (!endpoint) {
+                        const apiName = `${group}.${action}`;
+                        endpoint = Object.freeze(Object.assign((...args) => call(apiName, args), { outcome: (...args) => outcome(apiName, args) }));
+                        actions.set(action, endpoint);
+                    }
+                    return endpoint;
+                },
+            });
+            groups.set(group, calls);
+        }
+        return calls;
+    };
+    const withGroups = new Proxy(caller, {
+        get: (target, property) => {
+            if (typeof property === "string" && !(property in target) && isGroupName(property))
+                return groupOf(property);
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" && property !== "constructor" ? methodOnCaller(value) : value;
+        },
+        set: (target, property, value) => Reflect.set(target, property, value, target),
+    });
+    return withGroups;
+};

package/dist/shared/wire/LambderApiNames.d.ts

@@ -0,0 +1,55 @@
+/**
+ * How an endpoint is named and where it is called. An endpoint belongs to a
+ * group, and its name is the two joined by a dot: `orders.place`. Both are
+ * identifiers, so the name is also a path: a call posts to
+ * `{apiPath}/{group}/{action}`, which a gateway, a CDN and a log can meter,
+ * limit and read per endpoint without opening the body.
+ *
+ * The group is also a property of every Lambder caller
+ * (`caller.orders.place(input)`), so a group may not be named like anything a
+ * caller already has.
+ */
+/** A group's or an action's name: a letter, then letters, digits or underscores. */
+export declare const LAMBDER_API_NAME_SEGMENT: RegExp;
+/**
+ * Every public member of the three callers a group becomes a property of
+ * (LambderCaller, LambderInvokeCaller, LambderTestVisitor), since a caller
+ * looks a group up only after its own members. Their state is #private,
+ * which no property name reaches, so only these can stand in a group's way.
+ * A test holds this to the callers' public members, in their types and at
+ * runtime, both ways.
+ */
+export declare const LAMBDER_CALLER_MEMBER_NAMES: readonly ["api", "apiOutcome", "caller", "clientIp", "fetchTrackerList", "host", "isLoading", "jar", "request", "setSessionCookieKey", "setTransport", "signIn"];
+/**
+ * Names no group may take: the callers' members, and what a JavaScript
+ * runtime, a promise check, a serializer or a framework asks of any object.
+ */
+export declare const LAMBDER_RESERVED_GROUP_NAMES: readonly ["api", "apiOutcome", "caller", "clientIp", "fetchTrackerList", "host", "isLoading", "jar", "request", "setSessionCookieKey", "setTransport", "signIn", "constructor", "then", "catch", "finally", "toJSON", "toString", "valueOf", "toLocaleString", "prototype", "inspect", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable"];
+/** A name no group may take; see LAMBDER_RESERVED_GROUP_NAMES. */
+export type LambderReservedGroupName = typeof LAMBDER_RESERVED_GROUP_NAMES[number];
+/**
+ * Names no action may take: what a runtime, a promise check or a serializer
+ * asks of a group or of the function a caller hands out for an action, and
+ * the members every object has (toString, valueOf, hasOwnProperty), which a
+ * group keeps as its own.
+ */
+export declare const LAMBDER_RESERVED_ACTION_NAMES: readonly ["then", "catch", "finally", "toJSON", "constructor", "prototype", "outcome", "bind", "call", "apply", "length", "name", "arguments", "caller", "toString", "toLocaleString", "valueOf", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable"];
+/** A name no action may take; see LAMBDER_RESERVED_ACTION_NAMES. */
+export type LambderReservedActionName = typeof LAMBDER_RESERVED_ACTION_NAMES[number];
+/** Whether a name can be a group: an identifier segment, and not one a caller already answers for. */
+export declare const isGroupName: (name: string) => boolean;
+/** Whether a name can be an action of a group: an identifier segment, and not one a function already answers for. */
+export declare const isActionName: (name: string) => boolean;
+/** An endpoint's name split into its group and action, or null for a name that is not two segments. */
+export declare const splitApiName: (apiName: string) => {
+    group: string;
+    action: string;
+} | null;
+/** Where a call to the endpoint goes: `{apiPath}/{group}/{action}`. An apiPath may be absolute (another origin) or end with a slash. */
+export declare const apiCallPath: (apiPath: string, apiName: string) => string;
+/**
+ * The endpoint a request path calls, or null when the path is not a call
+ * under apiPath: exactly `{apiPath}/{group}/{action}`, with no query, no
+ * trailing slash and no further segment.
+ */
+export declare const apiNameOfCallPath: (apiPath: string, path: string) => string | null;

package/dist/shared/wire/LambderApiNames.js

@@ -0,0 +1,81 @@
+/**
+ * How an endpoint is named and where it is called. An endpoint belongs to a
+ * group, and its name is the two joined by a dot: `orders.place`. Both are
+ * identifiers, so the name is also a path: a call posts to
+ * `{apiPath}/{group}/{action}`, which a gateway, a CDN and a log can meter,
+ * limit and read per endpoint without opening the body.
+ *
+ * The group is also a property of every Lambder caller
+ * (`caller.orders.place(input)`), so a group may not be named like anything a
+ * caller already has.
+ */
+/** A group's or an action's name: a letter, then letters, digits or underscores. */
+export const LAMBDER_API_NAME_SEGMENT = /^[A-Za-z][A-Za-z0-9_]*$/;
+/**
+ * Every public member of the three callers a group becomes a property of
+ * (LambderCaller, LambderInvokeCaller, LambderTestVisitor), since a caller
+ * looks a group up only after its own members. Their state is #private,
+ * which no property name reaches, so only these can stand in a group's way.
+ * A test holds this to the callers' public members, in their types and at
+ * runtime, both ways.
+ */
+export const LAMBDER_CALLER_MEMBER_NAMES = [
+    "api", "apiOutcome", "caller", "clientIp", "fetchTrackerList", "host", "isLoading", "jar", "request",
+    "setSessionCookieKey", "setTransport", "signIn",
+];
+/**
+ * Names no group may take: the callers' members, and what a JavaScript
+ * runtime, a promise check, a serializer or a framework asks of any object.
+ */
+export const LAMBDER_RESERVED_GROUP_NAMES = [
+    ...LAMBDER_CALLER_MEMBER_NAMES,
+    "constructor", "then", "catch", "finally", "toJSON", "toString", "valueOf", "toLocaleString", "prototype", "inspect",
+    "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable",
+];
+/**
+ * Names no action may take: what a runtime, a promise check or a serializer
+ * asks of a group or of the function a caller hands out for an action, and
+ * the members every object has (toString, valueOf, hasOwnProperty), which a
+ * group keeps as its own.
+ */
+export const LAMBDER_RESERVED_ACTION_NAMES = [
+    "then", "catch", "finally", "toJSON", "constructor", "prototype", "outcome", "bind", "call", "apply", "length", "name",
+    "arguments", "caller", "toString", "toLocaleString", "valueOf", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable",
+];
+const RESERVED_GROUP_NAMES = new Set(LAMBDER_RESERVED_GROUP_NAMES);
+const RESERVED_ACTION_NAMES = new Set(LAMBDER_RESERVED_ACTION_NAMES);
+/** Whether a name can be a group: an identifier segment, and not one a caller already answers for. */
+export const isGroupName = (name) => LAMBDER_API_NAME_SEGMENT.test(name) && !RESERVED_GROUP_NAMES.has(name);
+/** Whether a name can be an action of a group: an identifier segment, and not one a function already answers for. */
+export const isActionName = (name) => LAMBDER_API_NAME_SEGMENT.test(name) && !RESERVED_ACTION_NAMES.has(name);
+/** An endpoint's name split into its group and action, or null for a name that is not two segments. */
+export const splitApiName = (apiName) => {
+    const dot = apiName.indexOf(".");
+    if (dot === -1)
+        return null;
+    const group = apiName.slice(0, dot);
+    const action = apiName.slice(dot + 1);
+    return LAMBDER_API_NAME_SEGMENT.test(group) && LAMBDER_API_NAME_SEGMENT.test(action) ? { group, action } : null;
+};
+/** Where a call to the endpoint goes: `{apiPath}/{group}/{action}`. An apiPath may be absolute (another origin) or end with a slash. */
+export const apiCallPath = (apiPath, apiName) => {
+    const parts = splitApiName(apiName);
+    if (!parts)
+        throw new Error(`Lambder: "${apiName}" is not an endpoint name. An endpoint is named group.action, both identifiers.`);
+    return `${apiPath.replace(/\/+$/, "")}/${parts.group}/${parts.action}`;
+};
+/**
+ * The endpoint a request path calls, or null when the path is not a call
+ * under apiPath: exactly `{apiPath}/{group}/{action}`, with no query, no
+ * trailing slash and no further segment.
+ */
+export const apiNameOfCallPath = (apiPath, path) => {
+    const base = apiPath.replace(/\/+$/, "");
+    if (!path.startsWith(`${base}/`))
+        return null;
+    const segments = path.slice(base.length + 1).split("/");
+    if (segments.length !== 2)
+        return null;
+    const [group, action] = segments;
+    return LAMBDER_API_NAME_SEGMENT.test(group) && LAMBDER_API_NAME_SEGMENT.test(action) ? `${group}.${action}` : null;
+};

package/dist/shared/wire/LambderCallOutcome.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What an API call ended in, as the server names it in the call's summary
+ * line: the reasons a caller reads the same answer by (resolveApiOutcome),
+ * with the server's side of a 5xx, a crash, and `other` for an answer that
+ * was not written as an API answer (a hook answering an API call with a page
+ * of its own).
+ */
+export type LambderCallOutcome = "success" | "refusal" | "notAuthorized" | "sessionExpired" | "versionExpired" | "validation" | "crash" | "other";
+/** An answer's outcome and refusal code, as the code that wrote the answer knows them. */
+export type LambderCallOutcomeHint = {
+    outcome: LambderCallOutcome;
+    /** The refusal's code, a framework code (`lambder/rate-limited`) or an app's; null when the answer carries none. */
+    code: string | null;
+};
+/**
+ * An envelope's outcome, read in the order a caller honours it: a 5xx is a
+ * crash whatever the envelope says, then the three flags, then a refusal,
+ * and anything else is the handler's answer.
+ */
+export declare const outcomeOfEnvelope: (written: object, statusCode: number) => LambderCallOutcomeHint;
+/**
+ * The outcome of an answer written as text, for an answer that arrived with
+ * no hint (a replayed one, which its store keeps as text): a 422 is a
+ * validation refusal, an envelope is read as outcomeOfEnvelope reads it, and
+ * anything else is known by its status alone.
+ */
+export declare const outcomeOfAnswerText: (statusCode: number, body: string) => LambderCallOutcomeHint;

package/dist/shared/wire/LambderCallOutcome.js

@@ -0,0 +1,47 @@
+const codeOf = (refusal) => {
+    if (refusal === null || typeof refusal !== "object")
+        return null;
+    const code = refusal.code;
+    return typeof code === "string" ? code : null;
+};
+/**
+ * An envelope's outcome, read in the order a caller honours it: a 5xx is a
+ * crash whatever the envelope says, then the three flags, then a refusal,
+ * and anything else is the handler's answer.
+ */
+export const outcomeOfEnvelope = (written, statusCode) => {
+    const envelope = written;
+    if (statusCode >= 500)
+        return { outcome: "crash", code: null };
+    if (envelope.versionExpired)
+        return { outcome: "versionExpired", code: null };
+    if (envelope.sessionExpired)
+        return { outcome: "sessionExpired", code: null };
+    if (envelope.notAuthorized)
+        return { outcome: "notAuthorized", code: codeOf(envelope.refusal) };
+    if (envelope.refusal !== undefined)
+        return { outcome: "refusal", code: codeOf(envelope.refusal) };
+    return { outcome: "success", code: null };
+};
+/**
+ * The outcome of an answer written as text, for an answer that arrived with
+ * no hint (a replayed one, which its store keeps as text): a 422 is a
+ * validation refusal, an envelope is read as outcomeOfEnvelope reads it, and
+ * anything else is known by its status alone.
+ */
+export const outcomeOfAnswerText = (statusCode, body) => {
+    if (statusCode >= 500)
+        return { outcome: "crash", code: null };
+    if (statusCode === 422)
+        return { outcome: "validation", code: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return { outcome: "other", code: null };
+    }
+    if (parsed === null || typeof parsed !== "object" || !("payload" in parsed))
+        return { outcome: "other", code: null };
+    return outcomeOfEnvelope(parsed, statusCode);
+};

package/dist/shared/wire/LambderInvokeApiId.d.ts

@@ -25,3 +25,13 @@ export declare const LAMBDER_INVOKE_API_ID = "lambder-invoke";
  * it.
  */
 export declare const LAMBDER_LOCAL_API_ID = "lambder-local";
+/**
+ * The request id of the invocation that made an invoke, when it runs under a
+ * Lambder handler: the invoke event builder writes it, and the callee's call
+ * summary records it as its parentRequestId, so a query over both functions'
+ * logs joins a call to the calls it made. The server reads it only from an
+ * invoke (LAMBDER_INVOKE_API_ID), whose event no gateway lets a client write.
+ * Declared here, beside the ids, because the builder writes it and the
+ * server reads it.
+ */
+export declare const LAMBDER_PARENT_REQUEST_HEADER = "x-lambder-parent-request-id";

package/dist/shared/wire/LambderInvokeApiId.js

@@ -25,3 +25,13 @@ export const LAMBDER_INVOKE_API_ID = "lambder-invoke";
  * it.
  */
 export const LAMBDER_LOCAL_API_ID = "lambder-local";
+/**
+ * The request id of the invocation that made an invoke, when it runs under a
+ * Lambder handler: the invoke event builder writes it, and the callee's call
+ * summary records it as its parentRequestId, so a query over both functions'
+ * logs joins a call to the calls it made. The server reads it only from an
+ * invoke (LAMBDER_INVOKE_API_ID), whose event no gateway lets a client write.
+ * Declared here, beside the ids, because the builder writes it and the
+ * server reads it.
+ */
+export const LAMBDER_PARENT_REQUEST_HEADER = "x-lambder-parent-request-id";

package/dist/shared/wire/LambderUploadSchemas.js

@@ -5,9 +5,10 @@ import { z } from "zod";
  * posts to the ticket endpoint, and the ticket it answers.
  *
  * ```ts
- * .addSessionApi("documents.requestUpload", {
+ * requestUpload: defineApi({
  *     input: z.object({ folderId: z.uuid(), fileFacts: LambderUploadFileFactsSchema }),
  *     output: z.object({ ticket: LambderUploadTicketSchema, documentId: z.uuid() }),
+ *     guards: "signedIn",
  * }, ...)
  * ```
  *

package/dist/stores/LambderDdbRateLimiter.d.ts

@@ -20,12 +20,21 @@ export interface LambderDdbRateLimiterOptions {
  * Fixed-window rate limiter backed by DynamoDB.
  *
  * Each window is one item counted with a conditional `ADD`, so the increment
- * and the limit check are one atomic request. Windows are evaluated smallest
- * first and evaluation stops at the first exceeded one, which keeps blocked
- * requests cheap and spares the larger counters. Attempts count, not
- * successes: a counter checked before the refusing one keeps its increment,
- * since a compensating decrement would give up the conditional-ADD
- * atomicity. Items carry an `expiresAt` attribute for DynamoDB TTL.
+ * and the limit check are one atomic request, and every window's request is
+ * sent at once: a policy capping three windows costs one round trip on the
+ * request's critical path, not three. Attempts count, not successes: a window
+ * under its limit counts an attempt another window refuses, since a
+ * compensating decrement would give up the conditional-ADD atomicity. The
+ * refusal names the smallest window that refused. Items carry an `expiresAt`
+ * attribute for DynamoDB TTL.
+ *
+ * A window the table refused an attempt in stays at its limit until it
+ * resets, since a count only rises within its window. So the process
+ * remembers it until then, and refuses the key's next attempts from memory
+ * without touching the table: a flood costs each process one round of
+ * writes per window it fills, and the counters of its other windows stop
+ * rising once it is refused. Another process asks the table once and then
+ * remembers too.
  *
  * The tracker key is caller data (an address, a session key, whatever a
  * policy handler returned), so a key whose partition key would pass
@@ -47,9 +56,9 @@ export interface LambderDdbRateLimiterOptions {
  * means the partition holding this counter is flooded. A partition holds a
  * range of keys, though, not one: a flood on one address, or a session or
  * cache spike on a shared table, throttles every counter on the same
- * partition. The key's own counts tell the flood from its neighbours: the
- * throttled window's and every capped window's after it, the ones this
- * attempt has not been counted against yet, each read with a consistent
+ * partition. The key's own counts tell the flood from its neighbours: those
+ * of the windows whose write was throttled, the ones this attempt has not
+ * been counted against, each read with a consistent
  * GetItem, in parallel (reads have their own throughput, which the throttled
  * writes leave alone). A key at or over the limit of any of them is the
  * flood: it is refused, since passed on as a failure `failOpen` would wave
@@ -87,8 +96,8 @@ export declare class LambderDdbRateLimiter implements LambderRateLimiter {
     private readonly ready;
     private readonly ttlWindowMultiplier;
     private readonly now;
-    /** The windows seen during key-range throttles, by (partition key, window, window start); see the class doc. */
-    private readonly throttledWindows;
+    /** The windows found at their limit, and those whose read a throttle refused, by (partition key, window, window start); see the class doc. */
+    private readonly rememberedWindows;
     constructor(options: LambderDdbRateLimiterOptions);
     /** The clock the windows are computed against, for the engine's Retry-After. */
     clockMilliseconds(): number;
@@ -107,11 +116,10 @@ export declare class LambderDdbRateLimiter implements LambderRateLimiter {
      */
     private incrementWindow;
     /**
-     * The answer to a key-range throttle on the first of `uncounted`: that
-     * window and every capped one after it, the windows this attempt has not
-     * been counted against. The windows before it counted this attempt and
-     * allowed it, so reading them could only turn the attempt that filled
-     * one into a refusal.
+     * The answer to a key-range throttle on `uncounted`, the windows whose
+     * write the throttle refused and which have not counted this attempt.
+     * The others counted it and allowed it, so reading them could only turn
+     * the attempt that filled one into a refusal.
      *
      * Each count is read strongly consistent: the count that decides is the
      * one the throttled writes were racing to raise, and a replica lagging

package/dist/stores/LambderDdbRateLimiter.js

@@ -6,12 +6,14 @@ import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 /** How long a key refused during a throttle is told to wait: long enough to let the partition recover, short enough for a legitimate caller. */
 const THROTTLED_RETRY_SECONDS = 5;
 /**
- * Most (tracker key, window) pairs the limiter remembers from throttles at
- * once. Only a key seen during a key-range throttle is remembered, for
- * THROTTLED_RETRY_SECONDS, so this is reached only by a flood spread over
- * that many keys at once, where the ones closest to expiring go first.
+ * Most (tracker key, window) pairs the limiter remembers at once. Only a
+ * window found at its limit is remembered (until it resets, or for
+ * THROTTLED_RETRY_SECONDS when a throttle's read found it there), so this is
+ * reached only by refusals spread over that many keys at once, where the
+ * ones closest to expiring go first; a key forgotten early is asked of the
+ * table again, which answers the same.
  */
-const THROTTLED_WINDOW_MEMORY_ENTRIES = 10_000;
+const REMEMBERED_WINDOW_ENTRIES = 10_000;
 /** The table key of one window's counter. */
 const counterKeyOf = (partitionKey, window) => ({
     pk: { S: partitionKey },
@@ -23,12 +25,21 @@ const rememberedWindowKeyOf = (partitionKey, window) => joinKeyFields(partitionK
  * Fixed-window rate limiter backed by DynamoDB.
  *
  * Each window is one item counted with a conditional `ADD`, so the increment
- * and the limit check are one atomic request. Windows are evaluated smallest
- * first and evaluation stops at the first exceeded one, which keeps blocked
- * requests cheap and spares the larger counters. Attempts count, not
- * successes: a counter checked before the refusing one keeps its increment,
- * since a compensating decrement would give up the conditional-ADD
- * atomicity. Items carry an `expiresAt` attribute for DynamoDB TTL.
+ * and the limit check are one atomic request, and every window's request is
+ * sent at once: a policy capping three windows costs one round trip on the
+ * request's critical path, not three. Attempts count, not successes: a window
+ * under its limit counts an attempt another window refuses, since a
+ * compensating decrement would give up the conditional-ADD atomicity. The
+ * refusal names the smallest window that refused. Items carry an `expiresAt`
+ * attribute for DynamoDB TTL.
+ *
+ * A window the table refused an attempt in stays at its limit until it
+ * resets, since a count only rises within its window. So the process
+ * remembers it until then, and refuses the key's next attempts from memory
+ * without touching the table: a flood costs each process one round of
+ * writes per window it fills, and the counters of its other windows stop
+ * rising once it is refused. Another process asks the table once and then
+ * remembers too.
  *
  * The tracker key is caller data (an address, a session key, whatever a
  * policy handler returned), so a key whose partition key would pass
@@ -50,9 +61,9 @@ const rememberedWindowKeyOf = (partitionKey, window) => joinKeyFields(partitionK
  * means the partition holding this counter is flooded. A partition holds a
  * range of keys, though, not one: a flood on one address, or a session or
  * cache spike on a shared table, throttles every counter on the same
- * partition. The key's own counts tell the flood from its neighbours: the
- * throttled window's and every capped window's after it, the ones this
- * attempt has not been counted against yet, each read with a consistent
+ * partition. The key's own counts tell the flood from its neighbours: those
+ * of the windows whose write was throttled, the ones this attempt has not
+ * been counted against, each read with a consistent
  * GetItem, in parallel (reads have their own throughput, which the throttled
  * writes leave alone). A key at or over the limit of any of them is the
  * flood: it is refused, since passed on as a failure `failOpen` would wave
@@ -90,8 +101,8 @@ export class LambderDdbRateLimiter {
     ready;
     ttlWindowMultiplier;
     now;
-    /** The windows seen during key-range throttles, by (partition key, window, window start); see the class doc. */
-    throttledWindows;
+    /** The windows found at their limit, and those whose read a throttle refused, by (partition key, window, window start); see the class doc. */
+    rememberedWindows;
     constructor(options) {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
@@ -99,7 +110,7 @@ export class LambderDdbRateLimiter {
         this.keyPrefix = options.keyPrefix ?? "RL";
         this.ttlWindowMultiplier = assertNumberAtLeast(options.ttlWindowMultiplier ?? 2, 1, "ttlWindowMultiplier");
         this.now = options.now ?? (() => Date.now());
-        this.throttledWindows = new LambderExpiringMap({ now: this.now, maxEntries: THROTTLED_WINDOW_MEMORY_ENTRIES });
+        this.rememberedWindows = new LambderExpiringMap({ now: this.now, maxEntries: REMEMBERED_WINDOW_ENTRIES });
         this.ready = createDynamoClientLoader({ user: "LambderDdbRateLimiter", region: options.region, client: options.client });
     }
     /** The clock the windows are computed against, for the engine's Retry-After. */
@@ -121,28 +132,37 @@ export class LambderDdbRateLimiter {
         const windows = RATE_LIMIT_WINDOWS
             .filter(({ key }) => policy[key])
             .map(({ key, seconds }) => ({ key, seconds, limit: policy[key], start: Math.floor(nowSeconds / seconds) * seconds }));
-        // A window this process read at its limit during a throttle refuses
-        // without touching the table (see the class doc).
-        const rememberedAtLimit = windows.find((window) => {
-            const remembered = this.throttledWindows.get(rememberedWindowKeyOf(partitionKey, window));
-            return remembered !== undefined && "count" in remembered && remembered.count >= window.limit;
-        });
-        if (rememberedAtLimit)
-            return { window: rememberedAtLimit.key, limit: rememberedAtLimit.limit, resetAt: nowSeconds + THROTTLED_RETRY_SECONDS };
-        for (const [index, window] of windows.entries()) {
-            try {
-                if (await this.incrementWindow(partitionKey, window, nowSeconds))
-                    return { window: window.key, limit: window.limit, resetAt: window.start + window.seconds };
-            }
-            catch (error) {
-                // A key-range throttle may be the limiter's own answer (see
-                // the class doc); anything else is the table failing, which
-                // only the caller can decide what to do about.
-                if (!isKeyRangeThrottle(error))
-                    throw error;
-                return await this.answerKeyRangeThrottle(partitionKey, windows.slice(index), nowSeconds, error);
+        // A window this process has found at its limit refuses without
+        // touching the table (see the class doc).
+        for (const window of windows) {
+            const remembered = this.rememberedWindows.get(rememberedWindowKeyOf(partitionKey, window));
+            if (remembered !== undefined && "count" in remembered && remembered.count >= window.limit) {
+                return { window: window.key, limit: window.limit, resetAt: remembered.resetAt ?? nowSeconds + THROTTLED_RETRY_SECONDS };
             }
         }
+        const attempts = await Promise.allSettled(windows.map((window) => this.incrementWindow(partitionKey, window, nowSeconds)));
+        // A refusal is the answer whatever the other windows did: a window at
+        // its limit refuses the attempt whether the others counted it, failed
+        // or were throttled.
+        const refusedAt = attempts.findIndex((attempt) => attempt.status === "fulfilled" && attempt.value);
+        if (refusedAt !== -1) {
+            const refusing = windows[refusedAt];
+            const resetAt = refusing.start + refusing.seconds;
+            this.rememberedWindows.set(rememberedWindowKeyOf(partitionKey, refusing), { count: refusing.limit, resetAt }, resetAt);
+            return { window: refusing.key, limit: refusing.limit, resetAt };
+        }
+        // A failure that is not the key's range being throttled is the table
+        // failing, which only the caller can decide what to do about.
+        const failure = attempts.find((attempt) => attempt.status === "rejected" && !isKeyRangeThrottle(attempt.reason));
+        if (failure)
+            throw failure.reason;
+        // A key-range throttle may be the limiter's own answer (see the class
+        // doc), read from the windows the throttle kept the attempt from.
+        const throttled = windows.filter((_, index) => attempts[index].status === "rejected");
+        if (throttled.length) {
+            const throttle = attempts.find((attempt) => attempt.status === "rejected").reason;
+            return await this.answerKeyRangeThrottle(partitionKey, throttled, nowSeconds, throttle);
+        }
         return false;
     }
     /** The item's partition key, refused when the tracker key makes it one DynamoDB will not take. */
@@ -185,11 +205,10 @@ export class LambderDdbRateLimiter {
         }
     }
     /**
-     * The answer to a key-range throttle on the first of `uncounted`: that
-     * window and every capped one after it, the windows this attempt has not
-     * been counted against. The windows before it counted this attempt and
-     * allowed it, so reading them could only turn the attempt that filled
-     * one into a refusal.
+     * The answer to a key-range throttle on `uncounted`, the windows whose
+     * write the throttle refused and which have not counted this attempt.
+     * The others counted it and allowed it, so reading them could only turn
+     * the attempt that filled one into a refusal.
      *
      * Each count is read strongly consistent: the count that decides is the
      * one the throttled writes were racing to raise, and a replica lagging
@@ -201,7 +220,7 @@ export class LambderDdbRateLimiter {
      */
     async answerKeyRangeThrottle(partitionKey, uncounted, nowSeconds, throttle) {
         const throttledWindowKey = rememberedWindowKeyOf(partitionKey, uncounted[0]);
-        const remembered = this.throttledWindows.get(throttledWindowKey);
+        const remembered = this.rememberedWindows.get(throttledWindowKey);
         if (remembered !== undefined && "unreadable" in remembered)
             throw remembered.unreadable;
         const { client, sdk } = await this.ready();
@@ -214,14 +233,14 @@ export class LambderDdbRateLimiter {
         for (const [index, read] of reads.entries()) {
             const window = uncounted[index];
             if (read.status === "fulfilled" && read.value >= window.limit) {
-                this.throttledWindows.set(rememberedWindowKeyOf(partitionKey, window), { count: read.value }, rememberUntil);
+                this.rememberedWindows.set(rememberedWindowKeyOf(partitionKey, window), { count: read.value }, rememberUntil);
                 refusing ??= window;
             }
         }
         if (refusing)
             return { window: refusing.key, limit: refusing.limit, resetAt: rememberUntil };
         if (reads.some((read) => read.status === "rejected" && isKeyRangeThrottle(read.reason))) {
-            this.throttledWindows.set(throttledWindowKey, { unreadable: throttle }, rememberUntil);
+            this.rememberedWindows.set(throttledWindowKey, { unreadable: throttle }, rememberUntil);
         }
         throw throttle;
     }

package/dist/stores/LambderMemoryRateLimiter.d.ts

@@ -1,10 +1,15 @@
 import { type LambderRateLimiter, type LambderRateLimitPolicy, type LambderRateLimitResult, type LambderRateLimitWindow } from "../shared/contracts/LambderRateLimiter.js";
 /**
  * Fixed-window rate limiter held in memory: the same windows, the same
- * attempts-count semantics and the same evaluation order as
- * LambderDdbRateLimiter, with a Map in place of the table. For tests and
- * for the mock runtime; a single-process server could use it too, with the
- * caveat that its counters are per process and vanish with it.
+ * attempts-count semantics and the same refusals as LambderDdbRateLimiter,
+ * with a Map in place of the table. For tests and for the mock runtime; a
+ * single-process server could use it too, with the caveat that its counters
+ * are per process and vanish with it.
+ *
+ * Every counter is in hand, so an attempt a window refuses is counted in no
+ * window: what the DynamoDB limiter reaches once it remembers the refusing
+ * window, which the first refused attempt in each of its processes still
+ * counts in the others.
  *
  * `now` is injectable so a test can move time forward and watch a window
  * reset without waiting for it.