lambder 7.2.4 → 7.3.1

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.
+     *
+     * One thing is added to what the caller hands back. When the app crashed
+     * answering the call, the outcome is the `server` failure any client
+     * would get, whose error says "Request failed: 500" and nothing else;
+     * 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,
+            isCorsEnabled: false,
+            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.
+            transport: (request) => lambderCookieJarTransport(withVisitorHeaders, { jar: this.jar, host: this.host })(request),
+        });
+        // The caller names the CSRF cookie the jar transport fills its token
+        // from, so an app that renamed its session cookies 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. Emptied by the test app's reset(), which a
+     * visitor notices here, the next time anything asks for its cookies: 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" }`) writes one
+     * this visitor's host is not under, a browser on that host would drop it,
+     * and so does the jar; left silent, every session call after it answers
+     * 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,26 @@
+/**
+ * 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 { 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,23 @@
+/**
+ * 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 { 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.4",
+  "version": "7.3.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": [
@@ -49,6 +49,10 @@
       "types": "./dist/mock.d.ts",
       "default": "./dist/mock.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -58,10 +62,14 @@
       ],
       "mock": [
         "./dist/mock.d.ts"
+      ],
+      "testing": [
+        "./dist/testing.d.ts"
       ]
     }
   },
   "browser": {
+    "async_hooks": false,
     "fs": false,
     "path": false,
     "zlib": false,