lambder 11.1.1 → 13.0.1

package/dist/stores/LambderMemoryRateLimiter.js

@@ -3,10 +3,15 @@ import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
 import { joinKeyFields } from "../shared/util/joinKeyFields.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.
@@ -31,24 +36,24 @@ export class LambderMemoryRateLimiter {
     }
     async isRateLimited(trackerKey, policy) {
         const nowSeconds = Math.floor(this.now() / 1000);
-        for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
-            const limit = policy[key];
-            if (!limit)
-                continue;
+        const windows = RATE_LIMIT_WINDOWS.filter(({ key }) => policy[key]).map(({ key, seconds }) => {
             const windowStart = Math.floor(nowSeconds / seconds) * seconds;
             // The table keeps the tracker key and the window in separate
             // attributes; one string has to keep them as distinct, hence the
             // escaping join.
             const counterKey = joinKeyFields(trackerKey, key, String(windowStart));
-            const counter = this.counters.get(counterKey) ?? { count: 0 };
-            // The DynamoDB limiter's conditional ADD: allowed while the count
-            // before this attempt is under the limit, and the refused attempt
-            // leaves the counter where it was.
-            if (counter.count >= limit)
-                return { window: key, limit, resetAt: windowStart + seconds };
+            return { key, limit: policy[key], resetAt: windowStart + seconds, counterKey, counter: this.counters.get(counterKey) ?? { count: 0 } };
+        });
+        // The DynamoDB limiter's conditional ADD: allowed while the count
+        // before this attempt is under the limit, and the smallest window at
+        // its limit names the refusal.
+        const refusing = windows.find(({ counter, limit }) => counter.count >= limit);
+        if (refusing)
+            return { window: refusing.key, limit: refusing.limit, resetAt: refusing.resetAt };
+        for (const { counterKey, counter, resetAt } of windows) {
             counter.count += 1;
             // The counter dies with its window, which is also the table's TTL.
-            this.counters.set(counterKey, counter, windowStart + seconds);
+            this.counters.set(counterKey, counter, resetAt);
         }
         return false;
     }

package/dist/testing/LambderTestApp.d.ts

@@ -7,7 +7,9 @@ import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
 import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import type { LambderCallSummary } from "../core/LambderCallSummary.js";
 import { LambderTestVisitor, type LambderTestVisitorArgs, type LambderTestVisitorOptions } from "./LambderTestVisitor.js";
 /**
  * What a test app may be told. Nothing is required: `lambderTestApp(lambder)`
@@ -51,7 +53,10 @@ export type LambderTestAppOptions = {
  * (`lambderTestApp<SessionData, ApiContractType>(lambder)`), so the tests type
  * their calls against plain members rather than the chained intersection.
  */
-export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any, any, any> & {
+export type LambderTestedInstance<TSessionData, TContract> = Pick<Lambder<any, any>, "apiPath" | "getHandler" | "getSessionController" | "getSessionManager" | typeof LAMBDER_BACKEND_SWAP | typeof LAMBDER_CRASH_WATCH> & {
+    readonly AppTypes: {
+        session: TSessionData;
+    };
     readonly ApiContract: TContract;
 };
 /**
@@ -96,6 +101,8 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
     private visitorCount;
     private resetCount;
     private readonly crashList;
+    /** Every call summary the app wrote since the last reset; see callSummaries. */
+    private readonly callSummaryList;
     /**
      * The call a crash happened under. The app's 500 says nothing about the
      * crash, so the error travels beside the answer, and with concurrent
@@ -113,6 +120,12 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
      * error an `event()` rejects with, which the test already holds.
      */
     get crashes(): readonly Error[];
+    /**
+     * The summary of every API call the app answered since the last reset,
+     * in order (see LambderCallSummary): what its callSummary option would
+     * have been handed, collected here instead of written to stdout.
+     */
+    get callSummaries(): readonly LambderCallSummary[];
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
     get sessionManager(): LambderSessionManager<TSessionData>;
     /**
@@ -155,10 +168,10 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
     event(event: unknown, context?: Partial<Context>): Promise<unknown>;
     /**
      * Rewinds what accumulated: sessions, rate-limit counters and replay
-     * records in the stores this test app made, the crashes it recorded, and
-     * the cookies of every visitor it created (each empties its jar the next
-     * time it is used). For a beforeEach. The app's own data (its database)
-     * is the app's to rewind.
+     * records in the stores this test app made, the crashes and call
+     * summaries it recorded, and the cookies of every visitor it created
+     * (each empties its jar the next time it is used). For a beforeEach. The
+     * app's own data (its database) is the app's to rewind.
      */
     reset(): void;
 }

package/dist/testing/LambderTestApp.js

@@ -49,6 +49,8 @@ export class LambderTestApp {
     visitorCount = 0;
     resetCount = 0;
     crashList = [];
+    /** Every call summary the app wrote since the last reset; see callSummaries. */
+    callSummaryList = [];
     /**
      * The call a crash happened under. The app's 500 says nothing about the
      * crash, so the error travels beside the answer, and with concurrent
@@ -66,7 +68,12 @@ export class LambderTestApp {
         const sessionStore = options.session?.store ?? own(new LambderMemorySessionStore());
         const rateLimiter = options.rateLimits?.limiter ?? own(new LambderMemoryRateLimiter());
         const idempotencyStore = options.idempotency?.store ?? own(new LambderMemoryIdempotencyStore());
-        const swap = lambder[LAMBDER_BACKEND_SWAP]({ sessionStore, rateLimiter, idempotencyStore, fileSource: options.files });
+        // The summaries are collected rather than written, so a suite's
+        // output stays its own and a test can read what a call recorded.
+        const swap = lambder[LAMBDER_BACKEND_SWAP]({
+            sessionStore, rateLimiter, idempotencyStore, fileSource: options.files,
+            callSummary: (summary) => { this.callSummaryList.push(summary); },
+        });
         if (options.files && !swap.files) {
             throw new Error("lambderTestApp: the files option was given, but the app was created without one, so nothing reads files to put a source under.");
         }
@@ -116,6 +123,14 @@ export class LambderTestApp {
     get crashes() {
         return this.crashList;
     }
+    /**
+     * The summary of every API call the app answered since the last reset,
+     * in order (see LambderCallSummary): what its callSummary option would
+     * have been handed, collected here instead of written to stdout.
+     */
+    get callSummaries() {
+        return this.callSummaryList;
+    }
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
     get sessionManager() {
         return this.lambder.getSessionManager();
@@ -178,15 +193,16 @@ export class LambderTestApp {
     }
     /**
      * Rewinds what accumulated: sessions, rate-limit counters and replay
-     * records in the stores this test app made, the crashes it recorded, and
-     * the cookies of every visitor it created (each empties its jar the next
-     * time it is used). For a beforeEach. The app's own data (its database)
-     * is the app's to rewind.
+     * records in the stores this test app made, the crashes and call
+     * summaries it recorded, and the cookies of every visitor it created
+     * (each empties its jar the next time it is used). For a beforeEach. The
+     * app's own data (its database) is the app's to rewind.
      */
     reset() {
         for (const store of this.ownStores)
             store.reset();
         this.crashList.length = 0;
+        this.callSummaryList.length = 0;
         this.resetCount += 1;
     }
 }

package/dist/testing/LambderTestVisitor.d.ts

@@ -1,4 +1,4 @@
-import LambderCaller from "../client/LambderCaller.js";
+import LambderCaller, { type LambderCallerGroupCalls, type LambderCallerMembers } from "../client/LambderCaller.js";
 import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 import type { LambderHandler } from "../core/LambderCreateOptions.js";
 import { type LambderLambdaHttpResult } from "../invoke/LambderLambdaEvent.js";
@@ -84,7 +84,8 @@ export type LambderTestVisitorArgs<TOptions, TProvidedGuards extends string> = [
  *
  * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
  */
-export declare class LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> {
+declare class LambderTestVisitorCore<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> {
+    #private;
     readonly host: string;
     readonly clientIp: string;
     /**
@@ -95,7 +96,7 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
      */
     readonly caller: LambderCaller<TContract, TProvidedGuards>;
     /** The payload on success, `undefined` on a failure: LambderCaller.api, through this visitor. */
-    readonly api: LambderCaller<TContract, TProvidedGuards>["api"];
+    readonly api: LambderCallerMembers<TContract, TProvidedGuards>["api"];
     /**
      * The full outcome, never throwing: LambderCaller.apiOutcome, through
      * this visitor. Pair it with assertApiSuccess / assertApiFailure.
@@ -105,11 +106,7 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
      * 500"; here that error's `cause` is what the app actually threw, stack
      * included, so a failing test points at the line in the handler.
      */
-    readonly apiOutcome: LambderCaller<TContract, TProvidedGuards>["apiOutcome"];
-    private readonly wiring;
-    private readonly headers;
-    private readonly cookieJar;
-    private seenResetCount;
+    readonly apiOutcome: LambderCallerMembers<TContract, TProvidedGuards>["apiOutcome"];
     constructor(wiring: LambderTestVisitorWiring<TSessionData>, options: LambderTestVisitorOptions<TContract, TProvidedGuards> & {
         host: string;
         clientIp: string;
@@ -151,3 +148,14 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
         ttlSeconds?: number;
     }): Promise<LambderCreatedSession<TSessionData>>;
 }
+/**
+ * One simulated browser in front of a real Lambder app, with the app's
+ * endpoints by group as a caller has them: `visitor.orders.place(input)`,
+ * `visitor.orders.place.outcome(input)`.
+ */
+export type LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> = LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards> & LambderCallerGroupCalls<TContract, TProvidedGuards>;
+export declare const LambderTestVisitor: {
+    new <TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never>(...args: ConstructorParameters<typeof LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards>>): LambderTestVisitor<TContract, TSessionData, TProvidedGuards>;
+    readonly prototype: LambderTestVisitorCore<any, any, any>;
+};
+export {};

package/dist/testing/LambderTestVisitor.js

@@ -1,4 +1,5 @@
 import LambderCaller from "../client/LambderCaller.js";
+import { withApiGroupCalls } from "../shared/wire/LambderApiGroupCalls.js";
 import { lambderHandlerTransport } from "../invoke/lambderHandlerTransport.js";
 import { decodeLambdaHttpResult, localLambdaContext, synthesizeLambdaHttpEvent, } from "../invoke/LambderLambdaEvent.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
@@ -15,7 +16,7 @@ import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderReques
  *
  * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
  */
-export class LambderTestVisitor {
+class LambderTestVisitorCore {
     host;
     clientIp;
     /**
@@ -37,19 +38,19 @@ export class LambderTestVisitor {
      * included, so a failing test points at the line in the handler.
      */
     apiOutcome;
-    wiring;
-    headers;
-    cookieJar;
-    seenResetCount;
+    #wiring;
+    #headers;
+    #cookieJar;
+    #seenResetCount;
     constructor(wiring, options) {
-        this.wiring = wiring;
+        this.#wiring = wiring;
         this.host = options.host;
         this.clientIp = options.clientIp;
-        this.headers = options.headers ?? {};
-        this.cookieJar = new LambderCookieJar({ host: this.host });
-        this.seenResetCount = wiring.resetCount();
+        this.#headers = options.headers ?? {};
+        this.#cookieJar = new LambderCookieJar({ host: this.host });
+        this.#seenResetCount = wiring.resetCount();
         const handlerTransport = lambderHandlerTransport(wiring.handler, { host: this.host, clientIp: this.clientIp, eventFormat: wiring.eventFormat });
-        const withVisitorHeaders = (request) => handlerTransport({ ...request, headers: { ...this.headers, ...request.headers } });
+        const withVisitorHeaders = (request) => handlerTransport({ ...request, headers: { ...this.#headers, ...request.headers } });
         this.caller = new LambderCaller({
             apiPath: wiring.apiPath,
             apiVersion: options.apiVersion,
@@ -69,13 +70,19 @@ export class LambderTestVisitor {
         if (wiring.sessionCookieNames) {
             this.caller.setSessionCookieKey(wiring.sessionCookieNames.tokenCookieKey, wiring.sessionCookieNames.csrfCookieKey);
         }
-        this.api = this.caller.api.bind(this.caller);
-        this.apiOutcome = (async (...callArgs) => {
-            const { result: outcome, crash } = await wiring.watchCrash(() => this.caller.apiOutcome(...callArgs));
+        const caller = this.caller;
+        const apiOutcome = async (apiName, ...callArgs) => {
+            const { result: outcome, crash } = await wiring.watchCrash(() => caller.apiOutcome(apiName, ...callArgs));
             if (crash && !outcome.ok && "error" in outcome && outcome.error.cause === undefined)
                 outcome.error.cause = crash;
             return outcome;
-        });
+        };
+        this.api = ((apiName, ...callArgs) => caller.api(apiName, ...callArgs));
+        this.apiOutcome = apiOutcome;
+        // Each group of the contract, as on a caller, through this visitor's
+        // own two calls: visitor.orders.place.outcome(input) carries the crash
+        // cause as visitor.apiOutcome does.
+        return withApiGroupCalls(this, (apiName, args) => caller.api(apiName, ...args), (apiName, args) => apiOutcome(apiName, ...args));
     }
     /**
      * This visitor's cookies, to inspect or clear; every call and request
@@ -84,12 +91,12 @@ export class LambderTestVisitor {
      * emptied store would read as signed in until an answer said otherwise.
      */
     get jar() {
-        const resetCount = this.wiring.resetCount();
-        if (resetCount !== this.seenResetCount) {
-            this.cookieJar.clear();
-            this.seenResetCount = resetCount;
+        const resetCount = this.#wiring.resetCount();
+        if (resetCount !== this.#seenResetCount) {
+            this.#cookieJar.clear();
+            this.#seenResetCount = resetCount;
         }
-        return this.cookieJar;
+        return this.#cookieJar;
     }
     /**
      * One HTTP request to the app that is not an API call, answered by
@@ -117,12 +124,12 @@ export class LambderTestVisitor {
             path: pathname,
             query,
             host: this.host,
-            headers: { ...this.headers, ...init.headers },
+            headers: { ...this.#headers, ...init.headers },
             clientIp: this.clientIp,
             cookies: this.jar.cookiePairs(cookieScope),
             body: init.body,
-        }, { invoke: false, eventFormat: this.wiring.eventFormat });
-        const result = await decodeLambdaHttpResult(await this.wiring.handler(event, localLambdaContext("lambder-test")), DEFAULT_MAX_RESTORED_PAYLOAD_BYTES);
+        }, { invoke: false, eventFormat: this.#wiring.eventFormat });
+        const result = await decodeLambdaHttpResult(await this.#wiring.handler(event, localLambdaContext("lambder-test")), DEFAULT_MAX_RESTORED_PAYLOAD_BYTES);
         if (result.cookies.length)
             this.jar.storeSetCookies(result.cookies, cookieScope);
         return result;
@@ -140,11 +147,11 @@ export class LambderTestVisitor {
      * answer sessionExpired with nothing to say why.
      */
     async signIn(sessionKey, data, options = {}) {
-        if (!this.wiring.sessionCookieNames)
+        if (!this.#wiring.sessionCookieNames)
             throw new Error("LambderTestVisitor: signIn() needs an app with sessions. Pass the session option to create().");
-        const { created, setCookies } = await this.wiring.issueSession(this.host, sessionKey, data, options.ttlSeconds);
+        const { created, setCookies } = await this.#wiring.issueSession(this.host, sessionKey, data, options.ttlSeconds);
         this.jar.storeSetCookies(setCookies, { host: this.host });
-        if (this.jar.get(this.wiring.sessionCookieNames.tokenCookieKey, { host: this.host, includeHttpOnly: true }) === undefined) {
+        if (this.jar.get(this.#wiring.sessionCookieNames.tokenCookieKey, { host: this.host, includeHttpOnly: true }) === undefined) {
             throw new Error(`LambderTestVisitor: the session cookie did not stick for host "${this.host}", the way a browser on that host would drop it. ` +
                 "The app most likely scopes its session cookie to a domain this host is not under: " +
                 "give the test app or this visitor a `host` the cookie domain covers.");
@@ -152,3 +159,4 @@ export class LambderTestVisitor {
         return created;
     }
 }
+export const LambderTestVisitor = LambderTestVisitorCore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "11.1.1",
+  "version": "13.0.1",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [