lambder 7.2.5 → 8.0.2

package/dist/testing/LambderTestApp.js

@@ -0,0 +1,204 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { createContext } from "../core/LambderContext.js";
+import { localLambdaContext, synthesizeLambdaHttpEvent } from "../invoke/LambderLambdaEvent.js";
+import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
+import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
+import { LambderMemoryIdempotencyStore } from "../stores/LambderMemoryIdempotencyStore.js";
+import { LambderMemoryRateLimiter } from "../stores/LambderMemoryRateLimiter.js";
+import { LambderMemorySessionStore } from "../stores/LambderMemorySessionStore.js";
+import { LambderTestVisitor } from "./LambderTestVisitor.js";
+/**
+ * A real Lambder app under test: the instance an app already has, with memory
+ * stores put under it in place, and as many simulated browsers in front of it
+ * as a test needs. No HTTP, no AWS, and nothing in the app restructured.
+ *
+ * The app's own declarations all run as written: guards, named rate-limit
+ * policies, idempotency settings, session salt, cookie options and
+ * dataRefresh, hooks and error handlers. Only where things rest is replaced:
+ * once this is created, the stores the app was configured with are out of the
+ * instance's reach, so a test cannot touch a production table by mistake.
+ * What the app reaches on its own (its database, a mailer) is the app's to
+ * replace.
+ *
+ * The sibling of LambderMockApp, which serves a contract from mock handlers:
+ * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
+ * real handlers.
+ *
+ * Time is not this class's: fake `Date` with the test runner
+ * (`vi.useFakeTimers({ toFake: ["Date"] })`), which moves the framework, the
+ * memory stores and the app's own handlers together.
+ *
+ * One test app per instance: a second one puts its own stores under the same
+ * instance and takes over its crash watch, so the first stops seeing either.
+ */
+export class LambderTestApp {
+    /** The instance's handler: what `event()` and every visitor call. */
+    handler;
+    /** The host visitors browse unless they name their own. */
+    host;
+    /** The session store now under the instance, for assertions; null when the app has no sessions. A LambderMemorySessionStore unless one was given. */
+    sessionStore;
+    /** The rate limiter now under the instance; null when the app declares no rate limits. */
+    rateLimiter;
+    /** The idempotency store now under the instance; null when the app has no idempotency. */
+    idempotencyStore;
+    lambder;
+    wiring;
+    /** The memory stores this test app made itself, which reset() empties. One the test supplied is the test's: nothing here knows what else holds it. */
+    ownStores = [];
+    visitorCount = 0;
+    resetCount = 0;
+    crashList = [];
+    /**
+     * 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
+     * calls (a duplicate sent while the original is in flight is an ordinary
+     * idempotency test) only the async context says which call it belongs to.
+     */
+    crashScope = new AsyncLocalStorage();
+    constructor(lambder, options = {}) {
+        // Only a Lambder instance from this same package copy answers to the
+        // key; saying so here beats a bare "is not a function".
+        if (typeof lambder?.[LAMBDER_BACKEND_SWAP] !== "function") {
+            throw new Error("lambderTestApp: expected a Lambder instance (what initLambder().create() returns), from the same installed copy of lambder as lambder/testing.");
+        }
+        const own = (store) => { this.ownStores.push(store); return store; };
+        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 });
+        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.");
+        }
+        lambder[LAMBDER_CRASH_WATCH]((error) => {
+            this.crashList.push(error);
+            const scope = this.crashScope.getStore();
+            if (scope)
+                scope.crash = error;
+        });
+        this.lambder = lambder;
+        this.handler = lambder.getHandler();
+        this.host = options.host ?? "localhost";
+        this.sessionStore = swap.sessions ? sessionStore : null;
+        this.rateLimiter = swap.rateLimits ? rateLimiter : null;
+        this.idempotencyStore = swap.idempotency ? idempotencyStore : null;
+        this.wiring = {
+            handler: this.handler,
+            apiPath: lambder.apiPath,
+            eventFormat: options.eventFormat ?? "v2",
+            sessionCookieNames: swap.sessions,
+            resetCount: () => this.resetCount,
+            watchCrash: async (run) => {
+                const scope = { crash: null };
+                return { result: await this.crashScope.run(scope, run), crash: scope.crash };
+            },
+            issueSession: async (host, sessionKey, data, ttlSeconds) => {
+                // Through a session controller on a request context, as a
+                // login handler does, so the cookies are what the app's own
+                // cookie options produce for that host.
+                const event = synthesizeLambdaHttpEvent({ method: "GET", path: "/", host }, { invoke: false });
+                const ctx = createContext(event, localLambdaContext("lambder-test"), { apiPath: lambder.apiPath });
+                const created = await lambder.getSessionController(ctx).issueSession(sessionKey, data, ttlSeconds);
+                const headers = {};
+                ctx.responseHeaders.applyInto(headers);
+                return { created, setCookies: getAnswerHeader(headers, "Set-Cookie") ?? [] };
+            },
+        };
+    }
+    /**
+     * Every error the app threw while answering a request since the last
+     * reset, in order: what reached its global error handler, or the
+     * framework's last-resort 500. The answers say nothing about what was
+     * thrown, so a test reads it here; `expect(app.crashes).toEqual([])`
+     * says nothing crashed. A refusal is not a crash, and neither is an
+     * error an `event()` rejects with, which the test already holds.
+     */
+    get crashes() {
+        return this.crashList;
+    }
+    /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
+    get sessionManager() {
+        return this.lambder.getSessionManager();
+    }
+    /**
+     * A new simulated browser: its own cookie jar, and its own address unless
+     * one is given. A stranger until it signs in, through the app's own login
+     * API or through `signIn`.
+     */
+    visitor(...[options]) {
+        this.visitorCount += 1;
+        return new LambderTestVisitor(this.wiring, {
+            ...options,
+            host: options?.host ?? this.host,
+            // One private address per visitor, counted up and never handed out
+            // twice, so no two visitors share a per-ip counter by accident.
+            clientIp: options?.clientIp ?? `10.${(this.visitorCount >> 16) & 255}.${(this.visitorCount >> 8) & 255}.${this.visitorCount & 255}`,
+        });
+    }
+    /**
+     * A new visitor, already signed in: `visitor()` followed by its
+     * `signIn()`. The session is minted by the app's own session model, so
+     * no login endpoint has to exist or be called.
+     *
+     * ```typescript
+     * const admin = await app.signIn("user:ada", { userId: "ada", role: "admin" });
+     * expect(await admin.api("org.rename", { name })).toEqual({ ok: true });
+     * ```
+     */
+    async signIn(sessionKey, data, ...[options]) {
+        const { ttlSeconds, ...visitorOptions } = (options ?? {});
+        const visitor = this.visitor(...[visitorOptions]);
+        await visitor.signIn(sessionKey, data, { ttlSeconds });
+        return visitor;
+    }
+    /**
+     * Ends every session of the subject, the way "log out everywhere" does.
+     * A visitor signed in as that subject keeps its cookies, as a browser
+     * would, so its next call is what a real one's would be: answered
+     * sessionExpired, with the stale cookies evicted.
+     */
+    async signOut(sessionKey) {
+        await this.sessionManager.deleteSessionAllByKey(sessionKey);
+    }
+    /** Marks the subject's session data stale, so the next read renews it through the app's dataRefresh. */
+    async expireSessionData(sessionKey) {
+        await this.sessionManager.expireSessionDataAllByKey(sessionKey);
+    }
+    /**
+     * Hands the handler an event that is not an HTTP request (a schedule, an
+     * SNS or SQS delivery), which is how an addAction handler runs, with a
+     * Lambda context filled in. Resolves to whatever the action returned.
+     *
+     * ```typescript
+     * await app.event({ source: "aws.events", "detail-type": "Scheduled Event" });
+     * ```
+     */
+    async event(event, context = {}) {
+        return await this.handler(event, localLambdaContext("lambder-test", context));
+    }
+    /**
+     * 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.
+     */
+    reset() {
+        for (const store of this.ownStores)
+            store.reset();
+        this.crashList.length = 0;
+        this.resetCount += 1;
+    }
+}
+/**
+ * Puts a built Lambder instance under test. See LambderTestApp.
+ *
+ * ```typescript
+ * import { lambderTestApp } from "lambder/testing";
+ * import { lambder } from "../src/index.js";
+ *
+ * const app = lambderTestApp(lambder);
+ * beforeEach(() => app.reset());
+ * ```
+ */
+export const lambderTestApp = (lambder, options = {}) => new LambderTestApp(lambder, options);

package/dist/testing/LambderTestVisitor.d.ts

@@ -0,0 +1,153 @@
+import LambderCaller 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";
+import type { LambderCreatedSession } from "../session/LambderSessionManager.js";
+import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
+import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { LambderGuardInputsProviderOption } from "../shared/wire/LambderCallOptions.js";
+/**
+ * How one visitor differs from the next. Everything is optional: a visitor
+ * nobody described is a stranger on the app's host, at an address of its own.
+ */
+export type LambderTestVisitorOptions<TContract, TProvidedGuards extends string = never> = {
+    /** The host this visitor browses (ctx.host), and the host its cookies are scoped to. Default: the test app's. */
+    host?: string;
+    /**
+     * The address the gateway observed (ctx.ip). Default: one no other
+     * visitor of this test app has, so a `per: "ip"` rate limit counts each
+     * visitor apart, as it does for two people in production. Give two
+     * visitors the same one to test what a shared address does.
+     */
+    clientIp?: string;
+    /** Headers every request of this visitor carries, under those a single call or request adds: what a CDN in front of the app writes (a country header), or a user agent. */
+    headers?: Record<string, string>;
+    /** Sent with every API call as `version`. Default: none, and a call naming no version is not judged by minApiVersion. */
+    apiVersion?: string;
+    /** Sent per API call as `signature`. Default: none, and a call carrying no signature is never gated; pass a map to test the gate itself. */
+    apiSignatures?: LambderApiSignatureMap;
+} & LambderGuardInputsProviderOption<TContract, TProvidedGuards>;
+/** What `request()` sends beside the method and the path. */
+export type LambderTestRequestInit = {
+    /** Query parameters, merged over any the path itself carries. */
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Sent as is: a string is JSON unless a content-type header says otherwise, a Buffer is binary. */
+    body?: string | Buffer;
+};
+/**
+ * What a test app hands each of its visitors: the handler they call, and the
+ * one thing a visitor cannot do alone, which is start a session without a
+ * login endpoint. The session model is the instance's, so the test app mints
+ * and the visitor keeps the cookies.
+ */
+export type LambderTestVisitorWiring<TSessionData> = {
+    handler: LambderHandler;
+    apiPath: string;
+    /** The gateway shape every event is synthesized in; the test app's, since a deployment sits behind one gateway. */
+    eventFormat: LambderHttpEventFormat;
+    /** The app's session cookie names, or null when it has no sessions. */
+    sessionCookieNames: {
+        tokenCookieKey: string;
+        csrfCookieKey: string;
+    } | null;
+    issueSession: (host: string, sessionKey: string, data: TSessionData, ttlSeconds?: number) => Promise<{
+        created: LambderCreatedSession<TSessionData>;
+        setCookies: string[];
+    }>;
+    /** How many times the test app was reset. A visitor compares it with the count it last saw, so the test app keeps no list of the visitors it made. */
+    resetCount: () => number;
+    /** Runs one call, and hands back beside its result the error the app threw while answering it, if it crashed. */
+    watchCrash: <TResult>(run: () => Promise<TResult>) => Promise<{
+        result: TResult;
+        crash: Error | null;
+    }>;
+};
+/**
+ * The options argument of `visitor()` and `signIn()`: optional, until the
+ * call names provided guards. Then the provider that supplies them is
+ * required, as it is on LambderCaller, since naming guards without one would
+ * send nothing for them.
+ */
+export type LambderTestVisitorArgs<TOptions, TProvidedGuards extends string> = [
+    TProvidedGuards
+] extends [never] ? [options?: TOptions] : [options: TOptions];
+/**
+ * One simulated browser in front of a real Lambder app: a cookie jar, an
+ * address and a host of its own, and two ways in. `api` / `apiOutcome` are a
+ * typed LambderCaller's, over the real handler in this process, so a call
+ * runs the whole pipeline (rate limits, session, replay, guards, validation)
+ * the way a browser's would. `request` is everything else a browser sends:
+ * pages, redirects, session routes, file requests. Both carry the same jar,
+ * so a session started through one is the session the other presents.
+ *
+ * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
+ */
+export declare class LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> {
+    readonly host: string;
+    readonly clientIp: string;
+    /**
+     * The typed caller `api` and `apiOutcome` run on, for code under test
+     * that takes a LambderCaller itself (a frontend store, a shared client
+     * module): handed this one, it talks to the real server in this process.
+     * An answer's logList is not printed; it is on the outcome.
+     */
+    readonly caller: LambderCaller<TContract, TProvidedGuards>;
+    /** The payload on success, `undefined` on a failure: LambderCaller.api, through this visitor. */
+    readonly api: LambderCaller<TContract, TProvidedGuards>["api"];
+    /**
+     * The full outcome, never throwing: LambderCaller.apiOutcome, through
+     * this visitor. Pair it with assertApiSuccess / assertApiFailure.
+     *
+     * When the app crashed answering the call, the outcome is the `server`
+     * failure any client would get, whose error says only "Request failed:
+     * 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;
+    constructor(wiring: LambderTestVisitorWiring<TSessionData>, options: LambderTestVisitorOptions<TContract, TProvidedGuards> & {
+        host: string;
+        clientIp: string;
+    });
+    /**
+     * This visitor's cookies, to inspect or clear; every call and request
+     * reads and fills them. The test app's reset() empties them, noticed here
+     * the next time anything asks: a jar still holding the token of an
+     * emptied store would read as signed in until an answer said otherwise.
+     */
+    get jar(): LambderCookieJar;
+    /**
+     * One HTTP request to the app that is not an API call, answered by
+     * whatever answers it in production: a route, a session route, the public
+     * files, the index page, a fallback. The answer comes back decoded
+     * (decompressed, headers lowercased), redirects are not followed, and
+     * its Set-Cookie headers land in this visitor's jar.
+     *
+     * ```typescript
+     * const page = await visitor.request("GET", "/orders?page=2");
+     * expect(page.statusCode).toBe(200);
+     * expect(page.text()).toContain("Your orders");
+     * ```
+     */
+    request(method: string, path: string, init?: LambderTestRequestInit): Promise<LambderLambdaHttpResult>;
+    /**
+     * Starts a session for this visitor without a login endpoint: minted by
+     * the app's own session model, under its own cookie options, and planted
+     * in this visitor's jar, so its next call is signed in. Returns the raw
+     * tokens too, as LambderMockApp.signIn does.
+     *
+     * Throws when the cookies do not stick. An app that scopes its session
+     * cookie to a domain (`cookie: { domain: ".example.com" }`) this visitor's
+     * host is not under writes a cookie a browser on that host would drop, and
+     * the jar drops it too; left silent, every later session call would
+     * answer sessionExpired with nothing to say why.
+     */
+    signIn(sessionKey: string, data: TSessionData, options?: {
+        ttlSeconds?: number;
+    }): Promise<LambderCreatedSession<TSessionData>>;
+}

package/dist/testing/LambderTestVisitor.js

@@ -0,0 +1,154 @@
+import LambderCaller from "../client/LambderCaller.js";
+import { lambderHandlerTransport } from "../invoke/lambderHandlerTransport.js";
+import { decodeLambdaHttpResult, localLambdaContext, synthesizeLambdaHttpEvent, } from "../invoke/LambderLambdaEvent.js";
+import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
+import { lambderCookieJarTransport } from "../shared/transport/lambderCookieJarTransport.js";
+import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
+/**
+ * One simulated browser in front of a real Lambder app: a cookie jar, an
+ * address and a host of its own, and two ways in. `api` / `apiOutcome` are a
+ * typed LambderCaller's, over the real handler in this process, so a call
+ * runs the whole pipeline (rate limits, session, replay, guards, validation)
+ * the way a browser's would. `request` is everything else a browser sends:
+ * pages, redirects, session routes, file requests. Both carry the same jar,
+ * so a session started through one is the session the other presents.
+ *
+ * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
+ */
+export class LambderTestVisitor {
+    host;
+    clientIp;
+    /**
+     * The typed caller `api` and `apiOutcome` run on, for code under test
+     * that takes a LambderCaller itself (a frontend store, a shared client
+     * module): handed this one, it talks to the real server in this process.
+     * An answer's logList is not printed; it is on the outcome.
+     */
+    caller;
+    /** The payload on success, `undefined` on a failure: LambderCaller.api, through this visitor. */
+    api;
+    /**
+     * The full outcome, never throwing: LambderCaller.apiOutcome, through
+     * this visitor. Pair it with assertApiSuccess / assertApiFailure.
+     *
+     * When the app crashed answering the call, the outcome is the `server`
+     * failure any client would get, whose error says only "Request failed:
+     * 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.
+     */
+    apiOutcome;
+    wiring;
+    headers;
+    cookieJar;
+    seenResetCount;
+    constructor(wiring, options) {
+        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();
+        const handlerTransport = lambderHandlerTransport(wiring.handler, { host: this.host, clientIp: this.clientIp, eventFormat: wiring.eventFormat });
+        const withVisitorHeaders = (request) => handlerTransport({ ...request, headers: { ...this.headers, ...request.headers } });
+        this.caller = new LambderCaller({
+            apiPath: wiring.apiPath,
+            apiVersion: options.apiVersion,
+            apiSignatures: options.apiSignatures,
+            guardInputsProvider: options.guardInputsProvider,
+            logListHandler: () => { },
+            // The jar is read per call rather than captured, so a call made
+            // after the test app was reset carries none of the old cookies.
+            // The visitor's session lives in that jar, so a CSRF token the
+            // caller read from a page's document.cookie (a test with a DOM)
+            // is dropped and the jar's own is posted.
+            transport: (request) => lambderCookieJarTransport(withVisitorHeaders, { jar: this.jar, host: this.host })({ ...request, token: "" }),
+        });
+        // The caller names the CSRF cookie the jar transport fills its token
+        // from, so an app with custom session cookie names has to be matched
+        // here or every session call would post an empty token.
+        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));
+            if (crash && !outcome.ok && "error" in outcome && outcome.error.cause === undefined)
+                outcome.error.cause = crash;
+            return outcome;
+        });
+    }
+    /**
+     * This visitor's cookies, to inspect or clear; every call and request
+     * reads and fills them. The test app's reset() empties them, noticed here
+     * the next time anything asks: a jar still holding the token of an
+     * 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;
+        }
+        return this.cookieJar;
+    }
+    /**
+     * One HTTP request to the app that is not an API call, answered by
+     * whatever answers it in production: a route, a session route, the public
+     * files, the index page, a fallback. The answer comes back decoded
+     * (decompressed, headers lowercased), redirects are not followed, and
+     * its Set-Cookie headers land in this visitor's jar.
+     *
+     * ```typescript
+     * const page = await visitor.request("GET", "/orders?page=2");
+     * expect(page.statusCode).toBe(200);
+     * expect(page.text()).toContain("Your orders");
+     * ```
+     */
+    async request(method, path, init = {}) {
+        const queryStart = path.indexOf("?");
+        const pathname = queryStart === -1 ? path : path.slice(0, queryStart);
+        const query = {
+            ...(queryStart === -1 ? {} : Object.fromEntries(new URLSearchParams(path.slice(queryStart + 1)))),
+            ...init.query,
+        };
+        const cookieScope = { host: this.host, path: pathname };
+        const event = synthesizeLambdaHttpEvent({
+            method,
+            path: pathname,
+            query,
+            host: this.host,
+            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);
+        if (result.cookies.length)
+            this.jar.storeSetCookies(result.cookies, cookieScope);
+        return result;
+    }
+    /**
+     * Starts a session for this visitor without a login endpoint: minted by
+     * the app's own session model, under its own cookie options, and planted
+     * in this visitor's jar, so its next call is signed in. Returns the raw
+     * tokens too, as LambderMockApp.signIn does.
+     *
+     * Throws when the cookies do not stick. An app that scopes its session
+     * cookie to a domain (`cookie: { domain: ".example.com" }`) this visitor's
+     * host is not under writes a cookie a browser on that host would drop, and
+     * the jar drops it too; left silent, every later session call would
+     * answer sessionExpired with nothing to say why.
+     */
+    async signIn(sessionKey, data, options = {}) {
+        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);
+        this.jar.storeSetCookies(setCookies, { host: this.host });
+        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.");
+        }
+        return created;
+    }
+}

package/dist/testing.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Testing entry point (`import ... from "lambder/testing"`).
+ *
+ * A real Lambder app under test, in this process: the instance an app
+ * already has, memory stores put under it in place, and simulated browsers
+ * in front of it, each with a typed caller and a cookie jar of its own.
+ * Server-only, like the root entry, and never part of a deployment by
+ * construction: nothing else imports it.
+ *
+ * The sibling of `lambder/mock`, which serves a contract from mock handlers
+ * for frontend work. This one runs the real handlers.
+ */
+export { lambderTestApp } from "./testing/LambderTestApp.js";
+export type { LambderTestApp, LambderTestAppOptions, LambderTestedInstance } from "./testing/LambderTestApp.js";
+export type { LambderTestVisitor, LambderTestVisitorOptions, LambderTestRequestInit } from "./testing/LambderTestVisitor.js";
+export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
+export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
+export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
+export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
+export { LambderLocalFileSource } from "./stores/LambderLocalFileSource.js";
+export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";
+export { LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export type { LambderLambdaHttpResult } from "./invoke/LambderLambdaEvent.js";
+export type { LambderCreatedSession } from "./session/LambderSessionManager.js";
+export type { LambderApiOutcome, LambderApiFailureReason } from "./shared/wire/LambderApiOutcome.js";

package/dist/testing.js

@@ -0,0 +1,24 @@
+/**
+ * Testing entry point (`import ... from "lambder/testing"`).
+ *
+ * A real Lambder app under test, in this process: the instance an app
+ * already has, memory stores put under it in place, and simulated browsers
+ * in front of it, each with a typed caller and a cookie jar of its own.
+ * Server-only, like the root entry, and never part of a deployment by
+ * construction: nothing else imports it.
+ *
+ * The sibling of `lambder/mock`, which serves a contract from mock handlers
+ * for frontend work. This one runs the real handlers.
+ */
+export { lambderTestApp } from "./testing/LambderTestApp.js";
+export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+// What a test reaches for beside the test app: the stores to inspect or to
+// hand it, a file source over fixtures, the refusal codes to assert on, and
+// the types of what a visitor and its session hand back.
+export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
+export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
+export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
+export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
+export { LambderLocalFileSource } from "./stores/LambderLocalFileSource.js";
+export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";
+export { LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "7.2.5",
+  "version": "8.0.2",
   "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": [
@@ -49,6 +49,14 @@
       "types": "./dist/mock.d.ts",
       "default": "./dist/mock.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -58,14 +66,23 @@
       ],
       "mock": [
         "./dist/mock.d.ts"
+      ],
+      "testing": [
+        "./dist/testing.d.ts"
+      ],
+      "build": [
+        "./dist/build.d.ts"
       ]
     }
   },
   "browser": {
+    "async_hooks": false,
+    "child_process": false,
     "fs": false,
     "path": false,
     "zlib": false,
-    "crypto": false
+    "crypto": false,
+    "url": false
   },
   "files": [
     "dist",
@@ -93,7 +110,7 @@
     "tough-cookie": "^6.0.2"
   },
   "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.574.0",
+    "@aws-sdk/client-dynamodb": "^3.868.0",
     "@aws-sdk/client-lambda": "^3.574.0",
     "@aws-sdk/client-s3": "^3.574.0",
     "@aws-sdk/lib-dynamodb": "^3.574.0",

package/dist/api/LambderApiPolicyEngine.d.ts

@@ -1,36 +0,0 @@
-import type { LambderApiRequest } from "./LambderApiRequest.js";
-import type { LambderApiCallContext, LambderApiCallTrace } from "./LambderApiCallContext.js";
-import type { LambderApiAnswer } from "./LambderApiAnswer.js";
-import type { LambderApiDefinition } from "./LambderApiDefinition.js";
-import { type LambderApiGuard } from "./LambderApiGuards.js";
-import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig } from "./LambderApiRateLimits.js";
-import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
-/**
- * Runtime side of the declarative API options: composes the three policy
- * subsystems (rate limits in ./LambderApiRateLimits.ts, guards in
- * ./LambderApiGuards.ts, idempotency in ./LambderApiIdempotency.ts), asserts
- * registrations against them at startup, and executes them around handlers
- * at request time. Owned by LambderApiPipeline; apps interact through the
- * create() options (rateLimits, guards, idempotency) and the per-API
- * options.
- */
-export declare class LambderApiPolicyEngine {
-    private rateLimits;
-    private guards;
-    private idempotency;
-    /** True once any of the three subsystems was configured. */
-    get isConfigured(): boolean;
-    configureRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
-    configureGuards(guards: Record<string, LambderApiGuard<any, any, any>>): void;
-    configureIdempotency(config: LambderApiIdempotencyConfig): void;
-    /** Startup validation of one API's declarative options. */
-    assertRegistration(definition: LambderApiDefinition): void;
-    /** The rate-limit policies that can be checked before the session is read: see LambderApiRateLimitsEngine.run. */
-    runSessionlessRateLimits(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition): Promise<void>;
-    /** The remaining rate limits, then guards, in declared order. Refusals throw; the trace records each guard as it runs. */
-    runPreflight(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition, trace: LambderApiCallTrace): Promise<void>;
-    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
-    findReplay(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition, trace: LambderApiCallTrace): Promise<LambderApiAnswer | null>;
-    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
-    withIdempotency(request: LambderApiRequest, ctx: LambderApiCallContext, definition: LambderApiDefinition, trace: LambderApiCallTrace, exec: () => Promise<LambderApiAnswer>): Promise<LambderApiAnswer>;
-}