lambder 7.3.1 → 8.1.1

package/dist/stores/LambderMemoryIdempotencyStore.js

@@ -10,14 +10,12 @@ import { LambderExpiringMap, LambderExpiringMapFullError } from "../shared/util/
  * path can be exercised; unbounded by default. `now` is injectable so a test
  * can expire a claim without waiting.
  *
- * `maxEntries` is the map's ceiling, 100,000 by default, and it is the one
- * way this store differs from a table: a process cannot hold records without
- * bound, so past the ceiling the SETTLED records are dropped, soonest expiry
- * first, and a retry whose record was dropped executes again instead of
- * replaying. Pending claims are never dropped for room, because losing one
- * lets two concurrent retries execute at once, which is the thing idempotency
- * exists to prevent; a claim that cannot be made room for is reported as
- * "pending" instead, so the duplicate is refused rather than run.
+ * `maxEntries` (100,000 by default) is the one way this store differs from a
+ * table: past the ceiling, SETTLED records are dropped, soonest expiry first,
+ * and a retry whose record was dropped executes again instead of replaying.
+ * Pending claims are never dropped, since losing one lets two concurrent
+ * retries both execute; a claim that finds no room is reported as "pending"
+ * instead, so the duplicate is refused rather than run.
  */
 export class LambderMemoryIdempotencyStore {
     records;
@@ -34,7 +32,7 @@ export class LambderMemoryIdempotencyStore {
     nowSeconds() { return Math.floor(this.now() / 1000); }
     /** A settled record as the engine reads it: a copy, so a caller writing onto what it got back cannot rewrite the record. */
     static answerOf(record) {
-        return { statusCode: record.statusCode, headers: structuredClone(record.headers), body: record.body };
+        return { statusCode: record.statusCode, headers: structuredClone(record.headers), body: record.body, fingerprint: record.fingerprint };
     }
     async peek(scopeKey) {
         const record = this.records.get(scopeKey);
@@ -42,43 +40,45 @@ export class LambderMemoryIdempotencyStore {
             return null;
         return LambderMemoryIdempotencyStore.answerOf(record);
     }
-    async begin(scopeKey, { pendingTtlSeconds }) {
+    async begin(scopeKey, { pendingTtlSeconds, fingerprint }) {
         const existing = this.records.get(scopeKey);
         if (existing) {
             if (existing.state === "done")
                 return { state: "done", ...LambderMemoryIdempotencyStore.answerOf(existing) };
-            return { state: "pending" };
+            return { state: "pending", fingerprint: existing.fingerprint };
         }
         this.ownerCounter += 1;
         const ownerToken = `owner-${this.ownerCounter}`;
         try {
-            // Not evictable: the claim is the only thing standing between two
-            // concurrent retries and two executions, and it is also the entry
-            // the soonest-expiry rule would otherwise take first, since a
-            // claim lives for minutes and the record it becomes for a day.
-            this.records.set(scopeKey, { state: "pending", ownerToken }, this.nowSeconds() + pendingTtlSeconds, { evictable: false });
+            // Not evictable: the claim is all that stands between two
+            // concurrent retries and two executions, and the soonest-expiry
+            // rule would take it first (a claim lives minutes, a record a day).
+            this.records.set(scopeKey, { state: "pending", ownerToken, fingerprint }, this.nowSeconds() + pendingTtlSeconds, { evictable: false });
         }
         catch (error) {
             if (!(error instanceof LambderExpiringMapFullError))
                 throw error;
-            // Every record held is a live claim, so there is no room and
-            // nothing safe to take. "pending" is the interface's shape for
-            // "the claim is not yours": the caller refuses the duplicate,
-            // which is the answer that cannot execute anything twice, and a
-            // retry once the flood drains claims normally.
+            // Every record held is a live claim, so nothing is safe to take.
+            // "pending" means "the claim is not yours": the caller refuses the
+            // duplicate, which cannot execute anything twice, and a retry
+            // after the flood drains claims normally. It carries the caller's
+            // own fingerprint, so the engine answers the in-flight 409 and the
+            // client retries under the same key; any other fingerprint would
+            // be the key-reused 409, which moves a client's key scope on as
+            // though the operation were settled.
             if (!this.claimCeilingReported) {
                 this.claimCeilingReported = true;
                 console.error("LambderMemoryIdempotencyStore: every record held is a live claim, so new requests are refused as duplicates until one settles. Raise maxEntries or move to LambderDdbIdempotencyStore.");
             }
-            return { state: "pending" };
+            return { state: "pending", fingerprint };
         }
         this.claimCeilingReported = false;
         return { state: "new", ownerToken };
     }
-    async complete(scopeKey, ownerToken, { statusCode, headers, body, ttlSeconds }) {
-        // Size first, ownership second, the order LambderDdbIdempotencyStore works
-        // in: it settles with one conditional write, so the only thing it can
-        // decide before going to the table is whether the body fits.
+    async complete(scopeKey, ownerToken, { statusCode, headers, body, fingerprint, ttlSeconds }) {
+        // Size first, ownership second, as LambderDdbIdempotencyStore must:
+        // it settles with one conditional write, so whether the body fits is
+        // all it can decide before going to the table.
         if (new TextEncoder().encode(body).length > this.maxBodyBytes)
             return "too-large";
         const existing = this.records.get(scopeKey);
@@ -87,18 +87,19 @@ export class LambderMemoryIdempotencyStore {
         // Settled records ARE evictable: the claim's job is done, and a record
         // the ceiling drops costs a retry its replay, not its exclusivity.
         // The key is already held, so this write cannot cross the ceiling.
-        this.records.set(scopeKey, { state: "done", ownerToken, statusCode, headers: structuredClone(headers), body }, this.nowSeconds() + ttlSeconds);
+        this.records.set(scopeKey, { state: "done", ownerToken, statusCode, headers: structuredClone(headers), body, fingerprint }, this.nowSeconds() + ttlSeconds);
         return "stored";
     }
+    /** Releases a pending claim for its owner; a settled record stays, as LambderIdempotencyStore requires. */
     async abandon(scopeKey, ownerToken) {
         const existing = this.records.get(scopeKey);
-        if (existing && existing.ownerToken === ownerToken)
+        if (existing?.state === "pending" && existing.ownerToken === ownerToken)
             this.records.delete(scopeKey);
     }
     /**
      * The record under a scope, for assertions; null when absent or expired.
-     * A copy, like every other read here, so an assertion that pokes at what
-     * it got back cannot edit the stored record.
+     * A copy, like every read here, so an assertion cannot edit the stored
+     * record.
      */
     recordOf(scopeKey) {
         const record = this.records.get(scopeKey);

package/dist/stores/LambderMemoryRateLimiter.d.ts

@@ -9,15 +9,13 @@ import { type LambderRateLimiter, type LambderRateLimitPolicy, type LambderRateL
  * `now` is injectable so a test can move time forward and watch a window
  * reset without waiting for it.
  *
- * `maxEntries` is the ceiling on counters held at once, 100,000 by default,
- * and it is the one way this limiter differs from the table: a process cannot
- * hold counters without bound, so past the ceiling the counters closest to
- * their window's end are dropped and a key whose counter was dropped starts
- * that window again from zero. It takes one distinct key per counter to get
- * there (a limit keyed per IP under a flood from many of them), and the
- * counters with the most life left, which are the long-window ones, are the
- * last to go. A deployment where that matters wants LambderDdbRateLimiter,
- * whose counters are not held in the process at all.
+ * `maxEntries` (100,000 counters by default) is the one way this limiter
+ * differs from the table: past the ceiling, the counters closest to their
+ * window's end are dropped, and a key whose counter was dropped starts that
+ * window again from zero. Reaching it takes one distinct key per counter (a
+ * per-IP limit under a flood from many IPs), and the long-window counters,
+ * with the most life left, go last. Where that matters, use
+ * LambderDdbRateLimiter, whose counters live outside the process.
  */
 export declare class LambderMemoryRateLimiter implements LambderRateLimiter {
     private readonly counters;
@@ -26,6 +24,7 @@ export declare class LambderMemoryRateLimiter implements LambderRateLimiter {
         now?: () => number;
         maxEntries?: number;
     });
+    clockMilliseconds(): number;
     isRateLimited(trackerKey: string, policy: LambderRateLimitPolicy): Promise<LambderRateLimitResult>;
     /** The attempts counted so far for a key in the current window of `window`; for assertions. */
     countOf(trackerKey: string, window: LambderRateLimitWindow): number;

package/dist/stores/LambderMemoryRateLimiter.js

@@ -1,6 +1,6 @@
 import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
-import { joinKeyFields } from "../shared/util/LambderKeyFields.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
@@ -11,15 +11,13 @@ import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
  * `now` is injectable so a test can move time forward and watch a window
  * reset without waiting for it.
  *
- * `maxEntries` is the ceiling on counters held at once, 100,000 by default,
- * and it is the one way this limiter differs from the table: a process cannot
- * hold counters without bound, so past the ceiling the counters closest to
- * their window's end are dropped and a key whose counter was dropped starts
- * that window again from zero. It takes one distinct key per counter to get
- * there (a limit keyed per IP under a flood from many of them), and the
- * counters with the most life left, which are the long-window ones, are the
- * last to go. A deployment where that matters wants LambderDdbRateLimiter,
- * whose counters are not held in the process at all.
+ * `maxEntries` (100,000 counters by default) is the one way this limiter
+ * differs from the table: past the ceiling, the counters closest to their
+ * window's end are dropped, and a key whose counter was dropped starts that
+ * window again from zero. Reaching it takes one distinct key per counter (a
+ * per-IP limit under a flood from many IPs), and the long-window counters,
+ * with the most life left, go last. Where that matters, use
+ * LambderDdbRateLimiter, whose counters live outside the process.
  */
 export class LambderMemoryRateLimiter {
     counters;
@@ -28,6 +26,9 @@ export class LambderMemoryRateLimiter {
         this.now = options.now ?? (() => Date.now());
         this.counters = new LambderExpiringMap({ now: this.now, maxEntries: options.maxEntries });
     }
+    clockMilliseconds() {
+        return this.now();
+    }
     async isRateLimited(trackerKey, policy) {
         const nowSeconds = Math.floor(this.now() / 1000);
         for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
@@ -35,9 +36,9 @@ export class LambderMemoryRateLimiter {
             if (!limit)
                 continue;
             const windowStart = Math.floor(nowSeconds / seconds) * seconds;
-            // The table gives the tracker key and the window separate
-            // attributes; one string here has to keep them as distinct, so the
-            // fields are joined through the escaping join rather than glued.
+            // 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

package/dist/stores/LambderMemorySessionStore.d.ts

@@ -1,4 +1,4 @@
-import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderSessionChanges, LambderSessionRecord, LambderSessionStore, LambderSessionUpdateResult } from "../shared/contracts/LambderSessionStore.js";
 /**
  * Session records held in memory: a Map in place of the DynamoDB table. For
  * tests and for the mock runtime, where the session model (tokens, expiry,
@@ -7,9 +7,11 @@ import type { LambderSessionRecord, LambderSessionStore } from "../shared/contra
  *
  * Records are copied on the way in and out through JSON, the way a real store
  * serializes them, so a caller mutating a fetched record changes nothing until
- * it is put back, and data DynamoDB would reject is rejected here too. A
- * record also leaves at its own expiresAt, the way the table's TTL removes
- * it, so a long-lived process does not hold every session it ever issued.
+ * it is written back, and data DynamoDB would reject is rejected here too.
+ * Creates and updates carry the table's conditions: a create refuses an
+ * existing record, and an update never brings back a deleted one. A record
+ * also leaves at its own expiresAt, as the table's TTL removes it, so a
+ * long-lived process does not hold every session it ever issued.
  */
 export declare class LambderMemorySessionStore<SessionData = unknown> implements LambderSessionStore<SessionData> {
     /** Nothing here outlives the process. */
@@ -28,17 +30,18 @@ export declare class LambderMemorySessionStore<SessionData = unknown> implements
     private static keyOf;
     /**
      * A record the way a real store hands it back: through JSON, so an
-     * undefined field is gone and a cyclic value throws here exactly as it
-     * throws on the way into DynamoDB. structuredClone did neither, which made
-     * the memory store the more forgiving of the two and let a test pass over
-     * data the production store would reject.
+     * undefined field is gone and a cyclic value throws here exactly as on the
+     * way into DynamoDB. structuredClone would do neither, and a test could
+     * then pass over data the production store rejects.
      */
     private static storedCopy;
     get(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
-    put(record: LambderSessionRecord<SessionData>): Promise<void>;
-    delete(sessionKeyHash: string, secretHash: string): Promise<void>;
+    create(record: LambderSessionRecord<SessionData>): Promise<void>;
+    update(sessionKeyHash: string, secretHash: string, changes: LambderSessionChanges<SessionData>, condition?: {
+        dataVersion: number;
+    }): Promise<LambderSessionUpdateResult>;
+    delete(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
     listSecretHashes(sessionKeyHash: string): Promise<string[]>;
-    markDataExpired(sessionKeyHash: string, secretHash: string, at: number): Promise<void>;
     /** Every live record held, for assertions. */
     list(): LambderSessionRecord<SessionData>[];
     /** Number of live records held. */

package/dist/stores/LambderMemorySessionStore.js

@@ -1,5 +1,5 @@
 import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
-import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
 /**
  * Session records held in memory: a Map in place of the DynamoDB table. For
  * tests and for the mock runtime, where the session model (tokens, expiry,
@@ -8,9 +8,11 @@ import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
  *
  * Records are copied on the way in and out through JSON, the way a real store
  * serializes them, so a caller mutating a fetched record changes nothing until
- * it is put back, and data DynamoDB would reject is rejected here too. A
- * record also leaves at its own expiresAt, the way the table's TTL removes
- * it, so a long-lived process does not hold every session it ever issued.
+ * it is written back, and data DynamoDB would reject is rejected here too.
+ * Creates and updates carry the table's conditions: a create refuses an
+ * existing record, and an update never brings back a deleted one. A record
+ * also leaves at its own expiresAt, as the table's TTL removes it, so a
+ * long-lived process does not hold every session it ever issued.
  */
 export class LambderMemorySessionStore {
     /** Nothing here outlives the process. */
@@ -26,17 +28,16 @@ export class LambderMemorySessionStore {
         this.records = new LambderExpiringMap(options);
     }
     static keyOf(sessionKeyHash, secretHash) {
-        // Escaped rather than joined plainly: both halves are hex today, but a
-        // custom LambderSessionCrypto writes whatever it likes into them, and
-        // two records sharing one key would be one session silently.
+        // Escaped rather than joined plainly: the default crypto writes hex,
+        // but a custom LambderSessionCrypto may write anything, and two
+        // records sharing one key would silently be one session.
         return joinKeyFields(sessionKeyHash, secretHash);
     }
     /**
      * A record the way a real store hands it back: through JSON, so an
-     * undefined field is gone and a cyclic value throws here exactly as it
-     * throws on the way into DynamoDB. structuredClone did neither, which made
-     * the memory store the more forgiving of the two and let a test pass over
-     * data the production store would reject.
+     * undefined field is gone and a cyclic value throws here exactly as on the
+     * way into DynamoDB. structuredClone would do neither, and a test could
+     * then pass over data the production store rejects.
      */
     static storedCopy(record) {
         return JSON.parse(JSON.stringify(record));
@@ -45,22 +46,40 @@ export class LambderMemorySessionStore {
         const record = this.records.get(LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash));
         return record ? LambderMemorySessionStore.storedCopy(record) : null;
     }
-    async put(record) {
-        this.records.set(LambderMemorySessionStore.keyOf(record.sessionKeyHash, record.secretHash), LambderMemorySessionStore.storedCopy(record), record.expiresAt);
+    async create(record) {
+        const key = LambderMemorySessionStore.keyOf(record.sessionKeyHash, record.secretHash);
+        if (this.records.get(key))
+            throw new Error("LambderMemorySessionStore: a session already exists under these hashes.");
+        this.records.set(key, LambderMemorySessionStore.storedCopy(record), record.expiresAt);
+    }
+    async update(sessionKeyHash, secretHash, changes, condition) {
+        const key = LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash);
+        const record = this.records.get(key);
+        if (!record)
+            return "missing";
+        if (condition && record.dataVersion !== condition.dataVersion)
+            return "stale";
+        // A write of the data or its deadline moves the version, whatever
+        // value it writes, as the DynamoDB store's ADD does.
+        const writesData = "data" in changes || changes.dataExpiresAt !== undefined;
+        // Through the same JSON copy a create takes, so an update carries
+        // exactly what the table would hold, and the record's own expiry
+        // moves with it, the way the table's TTL attribute does.
+        const updated = LambderMemorySessionStore.storedCopy({ ...record, ...changes, dataVersion: record.dataVersion + (writesData ? 1 : 0) });
+        this.records.set(key, updated, updated.expiresAt);
+        return "updated";
     }
     async delete(sessionKeyHash, secretHash) {
-        this.records.delete(LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash));
+        const key = LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash);
+        const record = this.records.get(key);
+        this.records.delete(key);
+        return record ? LambderMemorySessionStore.storedCopy(record) : null;
     }
     async listSecretHashes(sessionKeyHash) {
         return this.records.values()
             .filter((record) => record.sessionKeyHash === sessionKeyHash)
             .map((record) => record.secretHash);
     }
-    async markDataExpired(sessionKeyHash, secretHash, at) {
-        const record = this.records.get(LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash));
-        if (record)
-            record.dataExpiresAt = at;
-    }
     /** Every live record held, for assertions. */
     list() {
         return this.records.values().map((record) => LambderMemorySessionStore.storedCopy(record));

package/dist/stores/LambderMemoryUploadBucket.d.ts

@@ -0,0 +1,99 @@
+import { type LambderUploadBucket, type LambderUploadContentDisposition, type LambderUploadFileFacts, type LambderUploadObjectOptions, type LambderUploadRule, type LambderUploadTicket, type LambderUploadVerdict } from "../shared/contracts/LambderUploadBucket.js";
+export type LambderMemoryUploadBucketOptions = {
+    /**
+     * The URL tickets and download links point under, which a mock's MSW
+     * handler (lambderMockUploadMswHandler) or a test's fetch stub answers
+     * for. Default: a URL of its own per bucket, on a host that cannot
+     * resolve (`https://upload-bucket-<id>.invalid/`), so a request nothing
+     * intercepts fails rather than reaching the network.
+     */
+    baseUrl?: string;
+    /** How long a ticket stays usable, unless a ticket says otherwise. Default: 600 seconds, as LambderS3UploadBucket. */
+    ticketLifetimeSeconds?: number;
+    /** How long a download link reads the object, unless a link says otherwise. Default: 300 seconds, as LambderS3UploadBucket. */
+    downloadLifetimeSeconds?: number;
+    /** The clock tickets and links expire by, injectable so a test can move past an expiry without waiting. Default: Date.now. */
+    now?: () => number;
+};
+/** What the memory bucket holds under a key, for a test to assert on: the object's facts and what it carries. */
+export type LambderMemoryUploadObject = {
+    byteSize: number;
+    mimeType: string;
+    sha256Base64: string;
+} & LambderUploadObjectOptions;
+/**
+ * An upload bucket in memory (see LambderUploadBucket), for tests and the
+ * mock runtime.
+ *
+ * It holds a post to the rules S3 holds a presigned POST to: every field the
+ * ticket carries, each with the ticket's value, and no other, all ahead of
+ * the file (as S3 does, anything after the file is ignored); a ticket it
+ * issued and not yet expired; a body of exactly the size described; and bytes
+ * whose SHA-256 is the one described. It refuses otherwise with the status
+ * and the XML error S3 answers with (AccessDenied for a policy, and "Policy
+ * expired" for a late one, EntityTooSmall, EntityTooLarge, BadDigest), so any
+ * client, a LambderUploadRunner or another, takes the same path against it as
+ * against S3: an expired ticket is asked for again, a wrong file is refused.
+ * A download link reads the object until it expires.
+ *
+ * Storage requests reach it through handleStorageRequest(), which answers a
+ * fetch Request with a Response: lambderMockUploadMswHandler plugs that into
+ * MSW, and a test can route a stubbed fetch to it directly. Everything it
+ * uses is a web API (fetch's Request and Response, FormData, WebCrypto), so it
+ * runs in a browser, a service worker and Node alike.
+ */
+export declare class LambderMemoryUploadBucket implements LambderUploadBucket {
+    /** Where tickets and download links point, always ending in a slash. */
+    readonly baseUrl: string;
+    private readonly ticketLifetimeSeconds;
+    private readonly downloadLifetimeSeconds;
+    private readonly now;
+    private readonly objects;
+    private readonly tickets;
+    private readonly links;
+    constructor({ baseUrl, ticketLifetimeSeconds, downloadLifetimeSeconds, now }?: LambderMemoryUploadBucketOptions);
+    issueUploadTicket({ objectKey, fileFacts, uploadRule, lifetimeSeconds, object }: {
+        objectKey: string;
+        fileFacts: LambderUploadFileFacts;
+        uploadRule: LambderUploadRule;
+        lifetimeSeconds?: number;
+        object?: LambderUploadObjectOptions;
+    }): Promise<LambderUploadTicket>;
+    verifyUploadedObject({ objectKey, fileFacts }: {
+        objectKey: string;
+        fileFacts: Pick<LambderUploadFileFacts, "byteSize" | "sha256Base64">;
+    }): Promise<LambderUploadVerdict>;
+    issueDownloadUrl({ objectKey, lifetimeSeconds, contentDisposition }: {
+        objectKey: string;
+        lifetimeSeconds?: number;
+        contentDisposition?: LambderUploadContentDisposition;
+    }): Promise<string>;
+    readObject(objectKey: string): Promise<Uint8Array>;
+    writeObject({ objectKey, body, mimeType, sha256Base64, object }: {
+        objectKey: string;
+        body: Uint8Array;
+        mimeType: string;
+        sha256Base64?: string;
+        object?: LambderUploadObjectOptions;
+    }): Promise<void>;
+    copyObject({ fromObjectKey, toObjectKey }: {
+        fromObjectKey: string;
+        toObjectKey: string;
+    }): Promise<void>;
+    deleteObject(objectKey: string): Promise<void>;
+    /** The keys that hold an object, sorted, for a test to assert on. */
+    listObjectKeys(): string[];
+    /** What is held under a key (its facts, tags, metadata and headers), for a test to assert on; null when nothing is. */
+    inspectObject(objectKey: string): LambderMemoryUploadObject | null;
+    /** Forgets every object, ticket and link. */
+    reset(): void;
+    /**
+     * Answers a request to storage the way S3 answers it: a post under a
+     * ticket stores its file, a GET or HEAD through a download link reads an
+     * object. A request outside baseUrl answers null, for the caller to hand
+     * on.
+     */
+    handleStorageRequest(request: Request): Promise<Response | null>;
+    private acceptUpload;
+    private serveDownload;
+}