lambder 7.2.5 → 8.0.2

package/dist/stores/LambderDdbSessionStore.js

@@ -1,6 +1,8 @@
 import { createDynamoDocumentClientLoader, isConditionalCheckFailure } from "./LambderDdbSdk.js";
 import { compressText, restoreText } from "../shared/wire/LambderCompressionCodec.js";
 import { resolveCompressionOption, } from "../shared/wire/LambderCompressionOption.js";
+/** The fields besides data an update may write, as the manager names them. */
+const UPDATABLE_FIELDS = ["dataExpiresAt", "lastAccessedAt", "expiresAt"];
 /**
  * Session compression defaults: every record compressed (see
  * LambderCompressionOption for the option's shape and toggle semantics).
@@ -19,6 +21,10 @@ const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
  * Table shape: a string hash key (the salted sessionKey hash, every session
  * of one subject shares it) and a string range key (the bearer secret's
  * hash), plus a TTL on `expiresAt` to let DynamoDB sweep expired sessions.
+ *
+ * Every write is conditional: a create on the item not existing, an update
+ * on it existing, so no write already in flight can bring back a session a
+ * logout deleted.
  */
 export class LambderDdbSessionStore {
     /** DynamoDB keeps records after this process is gone. */
@@ -45,33 +51,38 @@ export class LambderDdbSessionStore {
     keyOf(sessionKeyHash, secretHash) {
         return { [this.partitionKey]: sessionKeyHash, [this.sortKey]: secretHash };
     }
+    /**
+     * session.data as the attributes that hold it: `dataBr` and `dataBytes`
+     * when compressed, a plain `data` otherwise. Either way it goes through
+     * its JSON first, so a plain record holds exactly what a compressed one
+     * restores to: an `undefined` inside the data is dropped rather than
+     * handed to the document client, which refuses one and would fail the
+     * write (a login answering 500) only when compression is off.
+     */
+    async dataAttributes(data) {
+        const json = JSON.stringify(data);
+        const raw = Buffer.from(json, "utf8");
+        if (this.compression && raw.byteLength >= this.compression.minBytes) {
+            return { dataBr: await compressText(raw, "br", this.compression.quality), dataBytes: raw.byteLength };
+        }
+        return { data: JSON.parse(json) };
+    }
     /** The item for a record: the two hashes under the table's key names, the data plain or compressed. */
     async toItem(record) {
         const { sessionKeyHash, secretHash, data, ...rest } = record;
-        const item = { ...this.keyOf(sessionKeyHash, secretHash), ...rest };
-        const raw = this.compression && Buffer.from(JSON.stringify(data), "utf8");
-        if (this.compression && raw && raw.byteLength >= this.compression.minBytes) {
-            item.dataBr = await compressText(raw, "br", this.compression.quality);
-            item.dataBytes = raw.byteLength;
-        }
-        else {
-            item.data = data;
-        }
-        return item;
+        return { ...this.keyOf(sessionKeyHash, secretHash), ...rest, ...await this.dataAttributes(data) };
     }
     /**
      * The record for an item. A compressed record decodes back into `data`;
-     * one whose data cannot be decoded is a malformed record and reads as no
-     * session, the same as a record missing its csrfTokenHash.
+     * one whose data cannot be decoded is malformed and reads as no session,
+     * like a record missing its csrfTokenHash.
      *
-     * Read failures and malformed records have to stay apart, and this is the
-     * seam where they separate. A read failure is infrastructure and must
-     * surface as a 500, because signing somebody out over a transient
-     * DynamoDB error is a worse answer than an error page. A record that will
-     * not decode is not transient: it will not decode on the next request
-     * either, so a 500 there is a session the visitor can neither use nor
-     * clear, on every request, until the TTL retires it. Ending it lets them
-     * log in again.
+     * This is where read failures and malformed records separate. A read
+     * failure is infrastructure and must surface as a 500: signing somebody
+     * out over a transient DynamoDB error is worse than an error page. A
+     * record that will not decode will not decode on the next request either,
+     * so a 500 there would be a session the visitor can neither use nor clear
+     * until the TTL retires it. Ending it lets them log in again.
      */
     async fromItem(item) {
         const { [this.partitionKey]: sessionKeyHash, [this.sortKey]: secretHash, dataBr, dataBytes, data, ...rest } = item;
@@ -89,15 +100,19 @@ export class LambderDdbSessionStore {
         // everything past this line trusts them: the manager compares the two
         // hashes in constant time (a non-string would throw there rather than
         // answer false) and reads expiresAt as a number to decide whether the
-        // session is over. An item missing them is not this store's record,
-        // whether it was written by hand, by an older schema, or by another
-        // app sharing the table, and it reads as no session for the same
-        // reason an undecodable one does: it will not become valid later.
+        // session is over. An item missing them is not this store's record
+        // (written by an earlier major, by hand, or by another app sharing the
+        // table), and it reads as no session for the same reason an
+        // undecodable one does: it will not become valid later. Not logged: a
+        // visitor whose cookie names such an item sends it on every request
+        // until the cookie expires, and the item itself goes with its TTL.
+        // dataVersion is load-bearing the same way: every conditioned write
+        // names the one read, and a record without it would fail that write
+        // rather than answer "stale".
         if (typeof sessionKeyHash !== "string" || typeof secretHash !== "string"
             || typeof rest.csrfTokenHash !== "string" || typeof rest.sessionKey !== "string"
             || typeof rest.createdAt !== "number" || typeof rest.expiresAt !== "number"
-            || typeof rest.ttlInSeconds !== "number") {
-            console.warn(`LambderDdbSessionStore: an item in "${this.tableName}" is missing the fields a session record has, so it reads as no session.`);
+            || typeof rest.ttlInSeconds !== "number" || typeof rest.dataVersion !== "number") {
             return null;
         }
         // The one cast: session.data is whatever the app put there, and JSON
@@ -112,14 +127,86 @@ export class LambderDdbSessionStore {
             return null;
         return await this.fromItem(response.Item);
     }
-    async put(record) {
+    async create(record) {
         const item = await this.toItem(record);
         const { client, sdk } = await this.ready();
-        await client.send(new sdk.PutCommand({ TableName: this.tableName, Item: item }));
+        await client.send(new sdk.PutCommand({
+            TableName: this.tableName,
+            Item: item,
+            ConditionExpression: "attribute_not_exists(#sk)",
+            ExpressionAttributeNames: { "#sk": this.sortKey },
+        }));
+    }
+    async update(sessionKeyHash, secretHash, changes, condition) {
+        const names = { "#sk": this.sortKey };
+        const values = {};
+        const set = [];
+        const remove = [];
+        const add = [];
+        if ("data" in changes) {
+            // The data is held in one of two forms, so writing one removes the other.
+            const attributes = await this.dataAttributes(changes.data);
+            for (const attribute of ["data", "dataBr", "dataBytes"]) {
+                names[`#${attribute}`] = attribute;
+                if (attribute in attributes) {
+                    values[`:${attribute}`] = attributes[attribute];
+                    set.push(`#${attribute} = :${attribute}`);
+                }
+                else {
+                    remove.push(`#${attribute}`);
+                }
+            }
+        }
+        for (const field of UPDATABLE_FIELDS) {
+            if (changes[field] === undefined)
+                continue;
+            names[`#${field}`] = field;
+            values[`:${field}`] = changes[field];
+            set.push(`#${field} = :${field}`);
+        }
+        // A write of the data or its deadline moves the version in the same
+        // write, whatever value it writes (see LambderSessionStore.update).
+        if ("data" in changes || changes.dataExpiresAt !== undefined) {
+            names["#dataVersion"] = "dataVersion";
+            values[":dataVersionStep"] = 1;
+            add.push("#dataVersion :dataVersionStep");
+        }
+        let conditionExpression = "attribute_exists(#sk)";
+        if (condition) {
+            names["#dataVersion"] = "dataVersion";
+            values[":readDataVersion"] = condition.dataVersion;
+            conditionExpression += " AND #dataVersion = :readDataVersion";
+        }
+        try {
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.UpdateCommand({
+                TableName: this.tableName,
+                Key: this.keyOf(sessionKeyHash, secretHash),
+                UpdateExpression: [
+                    set.length ? `SET ${set.join(", ")}` : "",
+                    add.length ? `ADD ${add.join(", ")}` : "",
+                    remove.length ? `REMOVE ${remove.join(", ")}` : "",
+                ].filter(Boolean).join(" "),
+                ConditionExpression: conditionExpression,
+                ExpressionAttributeNames: names,
+                ...(Object.keys(values).length ? { ExpressionAttributeValues: values } : {}),
+                // Which half of the condition failed is told by the item the
+                // refusal hands back, in the same call: none means the record
+                // is gone, one means its dataVersion moved.
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
+            }));
+            return "updated";
+        }
+        catch (err) {
+            if (!isConditionalCheckFailure(err))
+                throw err;
+            return err.Item ? "stale" : "missing";
+        }
     }
     async delete(sessionKeyHash, secretHash) {
         const { client, sdk } = await this.ready();
-        await client.send(new sdk.DeleteCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash) }));
+        const response = await client.send(new sdk.DeleteCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash), ReturnValues: "ALL_OLD" }));
+        return response.Attributes ? await this.fromItem(response.Attributes) : null;
     }
     async listSecretHashes(sessionKeyHash) {
         const params = {
@@ -128,6 +215,9 @@ export class LambderDdbSessionStore {
             ProjectionExpression: "#sk",
             ExpressionAttributeNames: { "#pk": this.partitionKey, "#sk": this.sortKey },
             ExpressionAttributeValues: { ":pv": sessionKeyHash },
+            // Consistent: "log out everywhere" has to find a session created
+            // a moment before it, and an eventually consistent read may not.
+            ConsistentRead: true,
         };
         const hashes = [];
         for (;;) {
@@ -140,22 +230,4 @@ export class LambderDdbSessionStore {
             params.ExclusiveStartKey = LastEvaluatedKey;
         }
     }
-    async markDataExpired(sessionKeyHash, secretHash, at) {
-        try {
-            const { client, sdk } = await this.ready();
-            await client.send(new sdk.UpdateCommand({
-                TableName: this.tableName,
-                Key: this.keyOf(sessionKeyHash, secretHash),
-                UpdateExpression: "SET #dataExpiresAt = :at",
-                ConditionExpression: "attribute_exists(#sk)",
-                ExpressionAttributeNames: { "#dataExpiresAt": "dataExpiresAt", "#sk": this.sortKey },
-                ExpressionAttributeValues: { ":at": at },
-            }));
-        }
-        catch (err) {
-            // Deleted between the query and the update: nothing left to expire.
-            if (!isConditionalCheckFailure(err))
-                throw err;
-        }
-    }
 }

package/dist/stores/LambderHttpFileSource.d.ts

@@ -9,6 +9,14 @@ export type LambderHttpFileSourceOptions = {
     headers?: Record<string, string>;
     /** How long one read may take before it fails. Default: 10000. */
     timeoutMs?: number;
+    /**
+     * The statuses that mean "no such file", read as null so the request
+     * falls through. Default: [403, 404, 410]. A private S3 bucket behind
+     * CloudFront answers a missing key 403, since its reader may not list the
+     * bucket; an origin whose 403 only ever means a refused credential passes
+     * [404, 410] so that failure surfaces as an error.
+     */
+    notFoundStatuses?: readonly number[];
 };
 /**
  * Files over HTTP(S) from any origin that serves them by path: a CDN, a
@@ -16,16 +24,17 @@ export type LambderHttpFileSourceOptions = {
  * endpoint) or another server. Reads with the runtime's fetch, so it needs
  * no SDK, and no credentials for a public origin; reads come out of the
  * origin's edge cache. Each path segment is percent-encoded, so a relative
- * path names the same object it would as an S3 key. A 404 or 410 reads as
- * null and the request falls through; any other failed status, a network
- * error or a timeout propagates as an error. The response's Content-Type is
- * used unless it is a generic octet-stream, in which case the extension
- * decides, as for local files.
+ * path names the same object it would as an S3 key. A missing file (see
+ * `notFoundStatuses`) reads as null and the request falls through; any other
+ * failed status, a network error or a timeout throws. The response's
+ * Content-Type is used unless it is a generic octet-stream, in which case
+ * the extension decides.
  */
 export declare class LambderHttpFileSource implements LambderFileSource {
     private readonly baseUrl;
     private readonly headers;
     private readonly timeoutMs;
-    constructor({ baseUrl, headers, timeoutMs }: LambderHttpFileSourceOptions);
+    private readonly notFoundStatuses;
+    constructor({ baseUrl, headers, timeoutMs, notFoundStatuses }: LambderHttpFileSourceOptions);
     read(relativePath: string): Promise<LambderFile | null>;
 }

package/dist/stores/LambderHttpFileSource.js

@@ -1,22 +1,24 @@
 import { remoteStoreFile } from "../shared/contracts/LambderFileSource.js";
 const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_NOT_FOUND_STATUSES = [403, 404, 410];
 /**
  * Files over HTTP(S) from any origin that serves them by path: a CDN, a
  * public bucket's own domain (a Cloudflare R2 custom domain, an S3 website
  * endpoint) or another server. Reads with the runtime's fetch, so it needs
  * no SDK, and no credentials for a public origin; reads come out of the
  * origin's edge cache. Each path segment is percent-encoded, so a relative
- * path names the same object it would as an S3 key. A 404 or 410 reads as
- * null and the request falls through; any other failed status, a network
- * error or a timeout propagates as an error. The response's Content-Type is
- * used unless it is a generic octet-stream, in which case the extension
- * decides, as for local files.
+ * path names the same object it would as an S3 key. A missing file (see
+ * `notFoundStatuses`) reads as null and the request falls through; any other
+ * failed status, a network error or a timeout throws. The response's
+ * Content-Type is used unless it is a generic octet-stream, in which case
+ * the extension decides.
  */
 export class LambderHttpFileSource {
     baseUrl;
     headers;
     timeoutMs;
-    constructor({ baseUrl, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+    notFoundStatuses;
+    constructor({ baseUrl, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS, notFoundStatuses = DEFAULT_NOT_FOUND_STATUSES }) {
         let url;
         try {
             url = new URL(baseUrl);
@@ -31,22 +33,22 @@ export class LambderHttpFileSource {
         this.baseUrl = url;
         this.headers = headers;
         this.timeoutMs = timeoutMs;
+        this.notFoundStatuses = notFoundStatuses;
     }
     async read(relativePath) {
         const url = new URL(relativePath.split("/").map(encodeURIComponent).join("/"), this.baseUrl);
-        // The reader's path rule already refuses everything that could make
-        // this reference leave the configured folder (a leading slash makes it
+        // The reader's path rule already refuses anything that could make this
+        // reference leave the configured folder (a leading slash makes it
         // root-relative, two make it protocol-relative and pick the host).
-        // Checked again here rather than trusted, because the value being
-        // resolved is the request path and what leaving costs is a
-        // credentialed fetch of an attacker-named origin, served back from
-        // this app's own domain.
+        // Re-checked rather than trusted: the value is the request path, and
+        // escaping would mean a credentialed fetch of an attacker-named
+        // origin, served back from this app's own domain.
         if (!url.href.startsWith(this.baseUrl.href))
             return null;
         const response = await fetch(url, { headers: this.headers, signal: AbortSignal.timeout(this.timeoutMs) });
         if (!response.ok) {
             await response.body?.cancel();
-            if (response.status === 404 || response.status === 410)
+            if (this.notFoundStatuses.includes(response.status))
                 return null;
             throw new Error(`LambderHttpFileSource: ${response.status} ${response.statusText} reading ${url}`);
         }

package/dist/stores/LambderMemoryCache.d.ts

@@ -0,0 +1,49 @@
+import type { LambderCache, LambderCacheKey, LambderCacheListOptions, LambderCacheSetOptions } from "../shared/contracts/LambderCache.js";
+export interface LambderMemoryCacheOptions {
+    /** Default: one year, as LambderDdbCache's. */
+    defaultTtlSeconds?: number;
+    /** Largest value accepted, in UTF-8 bytes of its JSON. Default: 32 MiB, as LambderDdbCache's. */
+    maxValueBytes?: number;
+    /** Ceiling on entries held at once; past it the ones closest to expiring go first. Default: 100,000. */
+    maxEntries?: number;
+    /** The clock entries expire against, so a test can cross a TTL without waiting. */
+    now?: () => number;
+}
+/**
+ * LambderDdbCache's twin, held in memory: the same LambderCache interface and
+ * the same rules, so code written against the interface can be tested
+ * without a table. It refuses the keys and values the DynamoDB cache
+ * refuses, stores a value's JSON text and hands back a fresh parse of it,
+ * expires entries on the same TTL, and lists sort keys in the same order.
+ *
+ * getOrSet runs through the LambderCacheFiller both caches hold: concurrent
+ * calls for one key share a load, every call (the filling one included)
+ * answers the stored JSON parsed, a loader's undefined comes back uncached,
+ * and a set, delete or deletePartition of the key while the loader runs
+ * keeps the fill from storing over it, so a test that passes here passes
+ * against the table.
+ *
+ * It has none of the table's machinery: no compression, no chunks, no fill
+ * lease across containers. It is one process's cache, bounded by
+ * `maxEntries`, and a single-process server could use it as that.
+ */
+export declare class LambderMemoryCache implements LambderCache {
+    private readonly entries;
+    /** getOrSet's single-flight and fail-open, shared with LambderDdbCache (see LambderCacheFiller). */
+    private readonly filler;
+    private readonly defaultTtlSeconds;
+    private readonly maxValueBytes;
+    private readonly now;
+    constructor(options?: LambderMemoryCacheOptions);
+    get<T>(key: LambderCacheKey): Promise<T | undefined>;
+    has(key: LambderCacheKey): Promise<boolean>;
+    set<T>(key: LambderCacheKey, value: T, options?: LambderCacheSetOptions): Promise<void>;
+    delete(key: LambderCacheKey): Promise<boolean>;
+    deletePartition(partition: string): Promise<number>;
+    listSortKeys(partition: string, options?: LambderCacheListOptions): Promise<string[]>;
+    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheSetOptions): Promise<T>;
+    /** Forgets every entry; a fill in flight meanwhile stores nothing. */
+    reset(): void;
+    /** Stores the value and hands back what was stored, the parse of its JSON. */
+    private setByAddress;
+}

package/dist/stores/LambderMemoryCache.js

@@ -0,0 +1,113 @@
+import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { cacheMemoryKeyOf, encodeCacheSortKey, normalizeCacheKey, normalizeCachePartition } from "./LambderCacheKeys.js";
+import { DEFAULT_MAX_VALUE_BYTES, DEFAULT_TTL_SECONDS, resolveCacheTtlSeconds, resolveGetOrSetOptions, serializeCacheValue, } from "./LambderCacheValues.js";
+import { LambderCacheFiller } from "./LambderCacheFiller.js";
+/** DynamoDB orders string range keys by their UTF-8 bytes, which is not JavaScript's UTF-16 order for every character. */
+const compareUtf8 = (first, second) => {
+    const a = new TextEncoder().encode(first);
+    const b = new TextEncoder().encode(second);
+    const length = Math.min(a.length, b.length);
+    for (let index = 0; index < length; index += 1) {
+        if (a[index] !== b[index])
+            return a[index] - b[index];
+    }
+    return a.length - b.length;
+};
+/**
+ * LambderDdbCache's twin, held in memory: the same LambderCache interface and
+ * the same rules, so code written against the interface can be tested
+ * without a table. It refuses the keys and values the DynamoDB cache
+ * refuses, stores a value's JSON text and hands back a fresh parse of it,
+ * expires entries on the same TTL, and lists sort keys in the same order.
+ *
+ * getOrSet runs through the LambderCacheFiller both caches hold: concurrent
+ * calls for one key share a load, every call (the filling one included)
+ * answers the stored JSON parsed, a loader's undefined comes back uncached,
+ * and a set, delete or deletePartition of the key while the loader runs
+ * keeps the fill from storing over it, so a test that passes here passes
+ * against the table.
+ *
+ * It has none of the table's machinery: no compression, no chunks, no fill
+ * lease across containers. It is one process's cache, bounded by
+ * `maxEntries`, and a single-process server could use it as that.
+ */
+export class LambderMemoryCache {
+    entries;
+    /** getOrSet's single-flight and fail-open, shared with LambderDdbCache (see LambderCacheFiller). */
+    filler = new LambderCacheFiller("Memory cache failed open");
+    defaultTtlSeconds;
+    maxValueBytes;
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.defaultTtlSeconds = assertPositiveInteger(options.defaultTtlSeconds ?? DEFAULT_TTL_SECONDS, "defaultTtlSeconds");
+        this.maxValueBytes = assertPositiveInteger(options.maxValueBytes ?? DEFAULT_MAX_VALUE_BYTES, "maxValueBytes");
+        this.entries = new LambderExpiringMap({ now: this.now, maxEntries: options.maxEntries });
+    }
+    async get(key) {
+        const entry = this.entries.get(normalizeCacheKey(key).memoryKey);
+        return entry ? JSON.parse(entry.json) : undefined;
+    }
+    async has(key) {
+        return this.entries.get(normalizeCacheKey(key).memoryKey) !== undefined;
+    }
+    async set(key, value, options = {}) {
+        const address = normalizeCacheKey(key);
+        const ttlSeconds = resolveCacheTtlSeconds(options.ttlSeconds, this.defaultTtlSeconds);
+        this.filler.supersedeFill(address.memoryKey);
+        this.setByAddress(address, value, ttlSeconds);
+    }
+    async delete(key) {
+        const address = normalizeCacheKey(key);
+        this.filler.supersedeFill(address.memoryKey);
+        const existed = this.entries.get(address.memoryKey) !== undefined;
+        this.entries.delete(address.memoryKey);
+        return existed;
+    }
+    async deletePartition(partition) {
+        const normalized = normalizeCachePartition(partition);
+        this.filler.supersedeFillsWithPrefix(cacheMemoryKeyOf(normalized, ""));
+        let removed = 0;
+        for (const { address } of this.entries.values()) {
+            if (address.partition !== normalized)
+                continue;
+            this.entries.delete(address.memoryKey);
+            removed += 1;
+        }
+        return removed;
+    }
+    async listSortKeys(partition, options = {}) {
+        const normalized = normalizeCachePartition(partition);
+        const prefix = options.prefix ?? "";
+        const limit = options.limit === undefined ? undefined : assertPositiveInteger(options.limit, "limit");
+        const sortKeys = this.entries.values()
+            .flatMap(({ address }) => address.partition === normalized && address.sortKey !== null && address.sortKey.startsWith(prefix) ? [address.sortKey] : [])
+            // Ordered as the table orders the items it lists: by the whole
+            // item sort key, which carries a "#" after the encoded key. So
+            // "New York City" sorts before "New York" there (" " is below
+            // "#"), and here too.
+            .sort((first, second) => compareUtf8(`${encodeCacheSortKey(first)}#`, `${encodeCacheSortKey(second)}#`));
+        return limit === undefined ? sortKeys : sortKeys.slice(0, limit);
+    }
+    async getOrSet(key, loader, options = {}) {
+        const address = normalizeCacheKey(key);
+        const { ttlSeconds } = resolveGetOrSetOptions(options, this.defaultTtlSeconds);
+        return this.filler.getOrSet(address.memoryKey, loader, async (load) => {
+            const existing = this.entries.get(address.memoryKey);
+            return existing ? JSON.parse(existing.json) : await load(async (value) => this.setByAddress(address, value, ttlSeconds));
+        });
+    }
+    /** Forgets every entry; a fill in flight meanwhile stores nothing. */
+    reset() {
+        this.filler.supersedeFillsWithPrefix("");
+        this.entries.clear();
+    }
+    /** Stores the value and hands back what was stored, the parse of its JSON. */
+    setByAddress(address, value, ttlSeconds) {
+        const { json } = serializeCacheValue(value, this.maxValueBytes);
+        const expiresAt = Math.floor(this.now() / 1000) + ttlSeconds;
+        this.entries.set(address.memoryKey, { json, address }, expiresAt);
+        return JSON.parse(json);
+    }
+}

package/dist/stores/LambderMemoryIdempotencyStore.d.ts

@@ -2,6 +2,7 @@ import type { LambderIdempotencyStore, LambderIdempotencyDoneRecord, LambderIdem
 type MemoryIdempotencyRecord = {
     state: "pending";
     ownerToken: string;
+    fingerprint: string;
 } | ({
     state: "done";
     ownerToken: string;
@@ -17,14 +18,12 @@ type MemoryIdempotencyRecord = {
  * 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 declare class LambderMemoryIdempotencyStore implements LambderIdempotencyStore {
     private readonly records;
@@ -42,17 +41,19 @@ export declare class LambderMemoryIdempotencyStore implements LambderIdempotency
     /** A settled record as the engine reads it: a copy, so a caller writing onto what it got back cannot rewrite the record. */
     private static answerOf;
     peek(scopeKey: string): Promise<LambderIdempotencyDoneRecord | null>;
-    begin(scopeKey: string, { pendingTtlSeconds }: {
+    begin(scopeKey: string, { pendingTtlSeconds, fingerprint }: {
         pendingTtlSeconds: number;
+        fingerprint: string;
     }): Promise<LambderIdempotencyBeginResult>;
-    complete(scopeKey: string, ownerToken: string, { statusCode, headers, body, ttlSeconds }: LambderIdempotencyDoneRecord & {
+    complete(scopeKey: string, ownerToken: string, { statusCode, headers, body, fingerprint, ttlSeconds }: LambderIdempotencyDoneRecord & {
         ttlSeconds: number;
     }): Promise<"stored" | "too-large" | "lost">;
+    /** Releases a pending claim for its owner; a settled record stays, as LambderIdempotencyStore requires. */
     abandon(scopeKey: string, ownerToken: string): Promise<void>;
     /**
      * 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: string): MemoryIdempotencyRecord | null;
     /** Number of live records held. */