lambder 7.3.1 → 8.0.2

package/dist/testing/LambderTestVisitor.d.ts

@@ -100,10 +100,9 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
      * 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
+     * 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"];
@@ -117,10 +116,9 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
     });
     /**
      * 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.
+     * 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;
     /**
@@ -144,10 +142,10 @@ export declare class LambderTestVisitor<TContract extends LambderApiContractShap
      * 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.
+     * 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;

package/dist/testing/LambderTestVisitor.js

@@ -31,10 +31,9 @@ export class LambderTestVisitor {
      * 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
+     * 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;
@@ -53,17 +52,19 @@ export class LambderTestVisitor {
         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 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 that renamed its session cookies has to be matched
+        // 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);
@@ -78,10 +79,9 @@ export class LambderTestVisitor {
     }
     /**
      * 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.
+     * 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();
@@ -134,10 +134,10 @@ export class LambderTestVisitor {
      * 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.
+     * 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)

package/dist/testing.d.ts

@@ -18,6 +18,7 @@ export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAsserti
 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/dist/testing.js

@@ -18,6 +18,7 @@ export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcome
 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.3.1",
+  "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": [
@@ -53,6 +53,10 @@
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
     },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -65,15 +69,20 @@
       ],
       "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",
@@ -101,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,47 +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";
-import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
-import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
-import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
-/**
- * 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;
-    /** The backend swap, handed on to the two subsystems that hold a store. Each answers whether it had a place for one. */
-    [LAMBDER_BACKEND_SWAP](backends: {
-        rateLimiter?: LambderRateLimiter;
-        idempotencyStore?: LambderIdempotencyStore;
-    }): {
-        rateLimits: boolean;
-        idempotency: boolean;
-    };
-    /** 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>;
-}

package/dist/api/LambderApiPolicyEngine.js

@@ -1,85 +0,0 @@
-import { LambderApiGuardsEngine } from "./LambderApiGuards.js";
-import { LambderApiRateLimitsEngine } from "./LambderApiRateLimits.js";
-import { LambderApiIdempotencyEngine } from "./LambderApiIdempotency.js";
-import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
-/** An API that asks for idempotency: declared, and not the explicit `false` opt-out. */
-const usesIdempotency = (definition) => definition.idempotency !== undefined && definition.idempotency !== false;
-/**
- * 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 class LambderApiPolicyEngine {
-    rateLimits = new LambderApiRateLimitsEngine();
-    guards = new LambderApiGuardsEngine();
-    idempotency = new LambderApiIdempotencyEngine();
-    /** True once any of the three subsystems was configured. */
-    get isConfigured() {
-        return this.rateLimits.isConfigured || this.guards.isConfigured || this.idempotency.isConfigured;
-    }
-    configureRateLimits(config) {
-        this.rateLimits.configure(config);
-    }
-    configureGuards(guards) {
-        this.guards.configure(guards);
-    }
-    configureIdempotency(config) {
-        this.idempotency.configure(config);
-    }
-    /** The backend swap, handed on to the two subsystems that hold a store. Each answers whether it had a place for one. */
-    [LAMBDER_BACKEND_SWAP](backends) {
-        return {
-            rateLimits: backends.rateLimiter ? this.rateLimits[LAMBDER_BACKEND_SWAP](backends.rateLimiter) : false,
-            idempotency: backends.idempotencyStore ? this.idempotency[LAMBDER_BACKEND_SWAP](backends.idempotencyStore) : false,
-        };
-    }
-    /** Startup validation of one API's declarative options. */
-    assertRegistration(definition) {
-        const { name, mode } = definition;
-        // Each subsystem reports its own absence. One combined message would
-        // tell an API that declares guards on an instance with no guards map
-        // that none of the three was configured, which reads as a question
-        // about all three when only one of them is missing.
-        if (definition.rateLimit !== undefined && !this.rateLimits.isConfigured) {
-            throw new Error(`Lambder: API "${name}" declares rateLimit but no rateLimits option was configured at creation.`);
-        }
-        if (definition.guards !== undefined && !this.guards.isConfigured) {
-            throw new Error(`Lambder: API "${name}" declares guards but no guards option was configured at creation.`);
-        }
-        this.rateLimits.assertRegistration(name, mode, definition.rateLimit);
-        this.guards.assertRegistration(name, mode, definition.guards);
-        // `idempotency: false` is an explicit opt-out, not a use: it asks for
-        // nothing and so needs no store behind it.
-        if (usesIdempotency(definition)) {
-            if (!this.idempotency.isConfigured) {
-                throw new Error(`Lambder: API "${name}" declares idempotency but no idempotency store was configured at creation.`);
-            }
-            this.idempotency.assertRegistration(name, definition.idempotency);
-        }
-    }
-    /** The rate-limit policies that can be checked before the session is read: see LambderApiRateLimitsEngine.run. */
-    async runSessionlessRateLimits(request, ctx, definition) {
-        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "beforeSession");
-    }
-    /** The remaining rate limits, then guards, in declared order. Refusals throw; the trace records each guard as it runs. */
-    async runPreflight(request, ctx, definition, trace) {
-        await this.rateLimits.run(definition.name, request, ctx, definition.rateLimit, "afterSession");
-        await this.guards.run(request, ctx, definition.guards, trace);
-    }
-    /** Idempotency replay fast path, run before the preflight: see LambderApiIdempotencyEngine.findReplay. */
-    async findReplay(request, ctx, definition, trace) {
-        if (!definition.idempotency)
-            return null;
-        return await this.idempotency.findReplay(definition.name, request, ctx, trace);
-    }
-    /** Idempotency claim/replay wrapper around handler execution: see LambderApiIdempotencyEngine.withIdempotency. */
-    async withIdempotency(request, ctx, definition, trace, exec) {
-        if (!definition.idempotency)
-            return await exec();
-        return await this.idempotency.withIdempotency(definition.name, request, ctx, definition.idempotency, trace, exec);
-    }
-}

package/dist/shared/util/LambderKeyFields.d.ts

@@ -1,32 +0,0 @@
-/**
- * Joining the fields of a tracker or scope key.
- *
- * Both the rate limiter and the idempotency engine build a key by joining a
- * few fields with a separator, and at least one field in each is caller data:
- * a rate-limit key returned by a policy handler, an idempotency key posted
- * with the request. A plain join lets two different field lists produce one
- * string, so two callers land on one counter or one caller reads another's
- * stored answer.
- *
- * Escaping the caller's use of the separator rather than rejecting or
- * reserving it: the caller chose the character for its own reasons, and a
- * limit that refuses a legal key is a bug of its own.
- *
- * The join is one-way. Nothing here reads a key back apart, because nothing
- * needs to: a key is looked up, counted against or compared, never taken to
- * pieces. The escaping is there so that distinct field lists cannot collide,
- * not so that the fields can be recovered.
- *
- * LambderDdbCache's sort-key encoding looks similar and is deliberately the
- * other thing: a reversible escape, because a cached entry's sort key is
- * handed back to the caller by listSortKeys and therefore has to decode to
- * exactly what was written. Two schemes, two jobs; neither should be reached
- * for in the other's place.
- *
- * Written once because the two engines had drifted, one escaping and one not.
- */
-/**
- * The fields joined into one key, each escaped, so no two distinct field
- * lists can produce the same string.
- */
-export declare const joinKeyFields: (...fields: string[]) => string;

package/dist/shared/util/LambderKeyFields.js

@@ -1,34 +0,0 @@
-/**
- * Joining the fields of a tracker or scope key.
- *
- * Both the rate limiter and the idempotency engine build a key by joining a
- * few fields with a separator, and at least one field in each is caller data:
- * a rate-limit key returned by a policy handler, an idempotency key posted
- * with the request. A plain join lets two different field lists produce one
- * string, so two callers land on one counter or one caller reads another's
- * stored answer.
- *
- * Escaping the caller's use of the separator rather than rejecting or
- * reserving it: the caller chose the character for its own reasons, and a
- * limit that refuses a legal key is a bug of its own.
- *
- * The join is one-way. Nothing here reads a key back apart, because nothing
- * needs to: a key is looked up, counted against or compared, never taken to
- * pieces. The escaping is there so that distinct field lists cannot collide,
- * not so that the fields can be recovered.
- *
- * LambderDdbCache's sort-key encoding looks similar and is deliberately the
- * other thing: a reversible escape, because a cached entry's sort key is
- * handed back to the caller by listSortKeys and therefore has to decode to
- * exactly what was written. Two schemes, two jobs; neither should be reached
- * for in the other's place.
- *
- * Written once because the two engines had drifted, one escaping and one not.
- */
-/** One field, with the separator and its own escape character escaped. */
-const escapeKeyField = (value) => value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
-/**
- * The fields joined into one key, each escaped, so no two distinct field
- * lists can produce the same string.
- */
-export const joinKeyFields = (...fields) => fields.map(escapeKeyField).join("|");