lambder 14.1.1 → 15.0.2

package/dist/stores/LambderDdbSessionStore.d.ts

@@ -1,4 +1,4 @@
-import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { type LambderCompressionOption } from "../shared/wire/LambderCompressionOption.js";
 import type { LambderSessionChanges, LambderSessionRecord, LambderSessionStore, LambderSessionUpdateResult } from "../shared/contracts/LambderSessionStore.js";
 export type LambderDdbSessionStoreOptions = {
@@ -16,8 +16,8 @@ export type LambderDdbSessionStoreOptions = {
      * it can be switched on or off on a live table.
      */
     compression?: LambderCompressionOption;
-    /** A ready document client, e.g. one shared with the rest of the app. */
-    client?: DynamoDBDocumentClient;
+    /** A ready client, e.g. one shared with the rest of the app; the stores' shared one for the region otherwise. */
+    client?: DynamoDBClient;
 };
 /**
  * Sessions at rest in DynamoDB: one item per session under the two hashes,
@@ -46,19 +46,34 @@ export declare class LambderDdbSessionStore<SessionData = unknown> implements La
     private keyOf;
     /**
      * 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.
+     * when compressed, a plain `data` attribute 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,
+     * as JSON drops it, rather than handed to marshallJsonValue, which
+     * refuses one and would fail the write (a login answering 500) only when
+     * compression is off.
+     *
+     * Data too large for a record is refused here, before anything is
+     * written, with the size and the limit it passed: DynamoDB would refuse
+     * the item with a ValidationException that names neither, and data past
+     * the restore ceiling would be written only to read back as no session.
+     * Create and update measure the same attributes, so data one accepts the
+     * other does too.
      */
     private dataAttributes;
-    /** The item for a record: the two hashes under the table's key names, the data plain or compressed. */
+    /**
+     * The item for a record: the two hashes under the table's key names, the
+     * record's other fields under their own names (strings and numbers, an
+     * absent dataExpiresAt left out), the data plain or compressed. The
+     * attribute names and types are the ones items have always carried, so
+     * records written before and after read alike.
+     */
     private toItem;
     /**
      * The record for an item. A compressed record decodes back into `data`;
-     * one whose data cannot be decoded is malformed and reads as no session,
-     * like a record missing its csrfTokenHash.
+     * one whose data cannot be decoded, or declares more of it than the store
+     * ever writes, is malformed and reads as no session, like a record
+     * missing its csrfTokenHash.
      *
      * This is where read failures and malformed records separate. A read
      * failure is infrastructure and must surface as a 500: signing somebody

package/dist/stores/LambderDdbSessionStore.js

@@ -1,5 +1,5 @@
-import { createDynamoDocumentClientLoader, isConditionalCheckFailure } from "./LambderDdbSdk.js";
-import { compressText, restoreText } from "../shared/wire/LambderCompressionCodec.js";
+import { attributeValueBytes, createDynamoClientLoader, isConditionalCheckFailure, marshallJsonValue, MAX_ITEM_BYTES, storedNumber, unmarshallJsonValue, } from "./LambderDdbSdk.js";
+import { restoreStoredText, storedTextOf } from "./LambderStoredText.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"];
@@ -7,11 +7,30 @@ const UPDATABLE_FIELDS = ["dataExpiresAt", "lastAccessedAt", "expiresAt"];
  * Session compression defaults: every record compressed (see
  * LambderCompressionOption for the option's shape and toggle semantics).
  * A compressed record carries the data's JSON as Brotli bytes (`dataBr`)
- * beside its byte length (`dataBytes`), the scheme LambderDdbCache and
- * LambderDdbIdempotencyStore use; below minBytes, or with compression off, the
- * record keeps a plain `data` attribute.
+ * beside its byte length (`dataBytes`), the scheme every DynamoDB store here
+ * keeps text in (see LambderStoredText); below minBytes, or with compression
+ * off, the record keeps a plain `data` attribute.
  */
 const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
+/**
+ * The longest session.data a record holds, in UTF-8 bytes of its JSON: the
+ * most the store writes, and so the ceiling it restores a compressed record
+ * under. Far past what a session should carry, since it is read on every
+ * request, and the same 32 MiB the cache and the idempotency store keep.
+ */
+const DATA_CEILING = { user: "LambderDdbSessionStore", maxTextBytes: 32 * 1024 * 1024 };
+/**
+ * What session.data may take of a record as stored, sized as DynamoDB sizes
+ * an item: its item limit less 8 KB for the record's other attributes (three
+ * hashes, the session key and a handful of numbers, a few hundred bytes with
+ * any session key of sensible length).
+ */
+const MAX_STORED_DATA_BYTES = MAX_ITEM_BYTES - 8 * 1024;
+/** A number attribute's value, or undefined when the attribute is missing or holds no finite number. */
+const numberAttributeOf = (attribute) => {
+    const value = attribute?.N === undefined ? NaN : Number(attribute.N);
+    return Number.isFinite(value) ? value : undefined;
+};
 /**
  * Sessions at rest in DynamoDB: one item per session under the two hashes,
  * with session.data Brotli-compressed by default. The store maps the
@@ -42,40 +61,66 @@ export class LambderDdbSessionStore {
         this.partitionKey = options.partitionKey ?? "pk";
         this.sortKey = options.sortKey ?? "sk";
         this.compression = resolveCompressionOption(options.compression, SESSION_COMPRESSION_DEFAULTS);
-        this.ready = createDynamoDocumentClientLoader({
-            user: "LambderDdbSessionStore",
-            ...(options.region !== undefined ? { region: options.region } : {}),
-            ...(options.client ? { client: options.client } : {}),
-        });
+        this.ready = createDynamoClientLoader({ user: "LambderDdbSessionStore", region: options.region, client: options.client });
     }
     keyOf(sessionKeyHash, secretHash) {
-        return { [this.partitionKey]: sessionKeyHash, [this.sortKey]: secretHash };
+        return { [this.partitionKey]: { S: sessionKeyHash }, [this.sortKey]: { S: 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.
+     * when compressed, a plain `data` attribute 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,
+     * as JSON drops it, rather than handed to marshallJsonValue, which
+     * refuses one and would fail the write (a login answering 500) only when
+     * compression is off.
+     *
+     * Data too large for a record is refused here, before anything is
+     * written, with the size and the limit it passed: DynamoDB would refuse
+     * the item with a ValidationException that names neither, and data past
+     * the restore ceiling would be written only to read back as no session.
+     * Create and update measure the same attributes, so data one accepts the
+     * other does too.
      */
     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 };
+        const utf8 = Buffer.from(json, "utf8");
+        if (utf8.byteLength > DATA_CEILING.maxTextBytes) {
+            throw new Error(`LambderDdbSessionStore: session.data is ${utf8.byteLength} bytes of JSON, over the ${DATA_CEILING.maxTextBytes}-byte limit of a session record. Keep less in the session.`);
         }
-        return { data: JSON.parse(json) };
+        const text = await storedTextOf(utf8, this.compression);
+        const attributes = text.encoding === "br"
+            ? { dataBr: { B: text.stored }, dataBytes: { N: String(text.textBytes) } }
+            : { data: marshallJsonValue(JSON.parse(json)) };
+        const storedBytes = Object.entries(attributes)
+            .reduce((total, [name, value]) => total + Buffer.byteLength(name, "utf8") + attributeValueBytes(value), 0);
+        if (storedBytes > MAX_STORED_DATA_BYTES) {
+            const remedy = text.encoding === "br" ? "Keep less in the session." : "Keep less in the session, or let the store's compression option compress it.";
+            throw new Error(`LambderDdbSessionStore: session.data is ${storedBytes} bytes as stored, over the ${MAX_STORED_DATA_BYTES} bytes a session record leaves it inside DynamoDB's ${MAX_ITEM_BYTES}-byte item limit. ${remedy}`);
+        }
+        return attributes;
     }
-    /** The item for a record: the two hashes under the table's key names, the data plain or compressed. */
+    /**
+     * The item for a record: the two hashes under the table's key names, the
+     * record's other fields under their own names (strings and numbers, an
+     * absent dataExpiresAt left out), the data plain or compressed. The
+     * attribute names and types are the ones items have always carried, so
+     * records written before and after read alike.
+     */
     async toItem(record) {
-        const { sessionKeyHash, secretHash, data, ...rest } = record;
-        return { ...this.keyOf(sessionKeyHash, secretHash), ...rest, ...await this.dataAttributes(data) };
+        const { sessionKeyHash, secretHash, data, ...fields } = record;
+        const item = { ...this.keyOf(sessionKeyHash, secretHash), ...await this.dataAttributes(data) };
+        for (const [name, value] of Object.entries(fields)) {
+            if (value !== undefined)
+                item[name] = marshallJsonValue(value);
+        }
+        return item;
     }
     /**
      * The record for an item. A compressed record decodes back into `data`;
-     * one whose data cannot be decoded is malformed and reads as no session,
-     * like a record missing its csrfTokenHash.
+     * one whose data cannot be decoded, or declares more of it than the store
+     * ever writes, is malformed and reads as no session, like a record
+     * missing its csrfTokenHash.
      *
      * This is where read failures and malformed records separate. A read
      * failure is infrastructure and must surface as a 500: signing somebody
@@ -85,44 +130,60 @@ export class LambderDdbSessionStore {
      * 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;
-        let restored = data;
-        if (dataBr) {
-            try {
-                restored = JSON.parse(await restoreText(dataBr, "br", { declaredBytes: dataBytes }));
-            }
-            catch (err) {
-                console.warn(`LambderDdbSessionStore: a session record in "${this.tableName}" could not be decoded, so it reads as no session.`, err);
-                return null;
-            }
+        let data;
+        try {
+            const compressed = item.dataBr?.B;
+            if (compressed)
+                data = JSON.parse(await restoreStoredText(compressed, storedNumber(item.dataBytes?.N, 0), DATA_CEILING));
+            else if (item.data)
+                data = unmarshallJsonValue(item.data);
+        }
+        catch (err) {
+            console.warn(`LambderDdbSessionStore: a session record in "${this.tableName}" could not be decoded, so it reads as no session.`, err);
+            return null;
         }
-        // The load-bearing fields are checked before the cast, because
-        // 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
-        // (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" || typeof rest.dataVersion !== "number") {
+        const sessionKeyHash = item[this.partitionKey]?.S;
+        const secretHash = item[this.sortKey]?.S;
+        const csrfTokenHash = item.csrfTokenHash?.S;
+        const sessionKey = item.sessionKey?.S;
+        const createdAt = numberAttributeOf(item.createdAt);
+        const expiresAt = numberAttributeOf(item.expiresAt);
+        const lastAccessedAt = numberAttributeOf(item.lastAccessedAt);
+        const ttlInSeconds = numberAttributeOf(item.ttlInSeconds);
+        const dataVersion = numberAttributeOf(item.dataVersion);
+        const dataExpiresAt = numberAttributeOf(item.dataExpiresAt);
+        // The load-bearing fields are checked before the record is built,
+        // because 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 (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 (sessionKeyHash === undefined || secretHash === undefined || csrfTokenHash === undefined || sessionKey === undefined
+            || createdAt === undefined || expiresAt === undefined || ttlInSeconds === undefined || dataVersion === undefined) {
             return null;
         }
-        // The one cast: session.data is whatever the app put there, and JSON
-        // (or the plain attribute) hands it back as any. Nothing in the store
-        // can check it, because the shape is the app's, not this layer's.
-        return { sessionKeyHash, secretHash, data: restored, ...rest };
+        // The cast: session.data is whatever the app put there, and JSON (or
+        // the plain attribute) hands it back untyped. Nothing in the store can
+        // check it, because the shape is the app's, not this layer's. The
+        // other unchecked field is lastAccessedAt: written with every record,
+        // and read as absent from an item without it rather than refusing it.
+        return {
+            sessionKeyHash, secretHash, csrfTokenHash, sessionKey, data: data,
+            createdAt, expiresAt, ttlInSeconds, dataVersion,
+            ...(lastAccessedAt !== undefined ? { lastAccessedAt } : {}),
+            ...(dataExpiresAt !== undefined ? { dataExpiresAt } : {}),
+        };
     }
     async get(sessionKeyHash, secretHash) {
         const { client, sdk } = await this.ready();
-        const response = await client.send(new sdk.GetCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash), ConsistentRead: true }));
+        const response = await client.send(new sdk.GetItemCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash), ConsistentRead: true }));
         if (!response.Item)
             return null;
         return await this.fromItem(response.Item);
@@ -130,7 +191,7 @@ export class LambderDdbSessionStore {
     async create(record) {
         const item = await this.toItem(record);
         const { client, sdk } = await this.ready();
-        await client.send(new sdk.PutCommand({
+        await client.send(new sdk.PutItemCommand({
             TableName: this.tableName,
             Item: item,
             ConditionExpression: "attribute_not_exists(#sk)",
@@ -148,8 +209,9 @@ export class LambderDdbSessionStore {
             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];
+                const value = attributes[attribute];
+                if (value) {
+                    values[`:${attribute}`] = value;
                     set.push(`#${attribute} = :${attribute}`);
                 }
                 else {
@@ -161,25 +223,25 @@ export class LambderDdbSessionStore {
             if (changes[field] === undefined)
                 continue;
             names[`#${field}`] = field;
-            values[`:${field}`] = changes[field];
+            values[`:${field}`] = marshallJsonValue(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;
+            values[":dataVersionStep"] = { N: "1" };
             add.push("#dataVersion :dataVersionStep");
         }
         let conditionExpression = "attribute_exists(#sk)";
         if (condition) {
             names["#dataVersion"] = "dataVersion";
-            values[":readDataVersion"] = condition.dataVersion;
+            values[":readDataVersion"] = marshallJsonValue(condition.dataVersion);
             conditionExpression += " AND #dataVersion = :readDataVersion";
         }
         try {
             const { client, sdk } = await this.ready();
-            await client.send(new sdk.UpdateCommand({
+            await client.send(new sdk.UpdateItemCommand({
                 TableName: this.tableName,
                 Key: this.keyOf(sessionKeyHash, secretHash),
                 UpdateExpression: [
@@ -205,7 +267,7 @@ export class LambderDdbSessionStore {
     }
     async delete(sessionKeyHash, secretHash) {
         const { client, sdk } = await this.ready();
-        const response = await client.send(new sdk.DeleteCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash), ReturnValues: "ALL_OLD" }));
+        const response = await client.send(new sdk.DeleteItemCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash), ReturnValues: "ALL_OLD" }));
         return response.Attributes ? await this.fromItem(response.Attributes) : null;
     }
     async listSecretHashes(sessionKeyHash) {
@@ -214,7 +276,7 @@ export class LambderDdbSessionStore {
             KeyConditionExpression: "#pk = :pv",
             ProjectionExpression: "#sk",
             ExpressionAttributeNames: { "#pk": this.partitionKey, "#sk": this.sortKey },
-            ExpressionAttributeValues: { ":pv": sessionKeyHash },
+            ExpressionAttributeValues: { ":pv": { S: sessionKeyHash } },
             // Consistent: "log out everywhere" has to find a session created
             // a moment before it, and an eventually consistent read may not.
             ConsistentRead: true,
@@ -223,8 +285,11 @@ export class LambderDdbSessionStore {
         for (;;) {
             const { client, sdk } = await this.ready();
             const { Items, LastEvaluatedKey } = await client.send(new sdk.QueryCommand(params));
-            for (const item of Items ?? [])
-                hashes.push(item[this.sortKey]);
+            for (const item of Items ?? []) {
+                const secretHash = item[this.sortKey]?.S;
+                if (secretHash !== undefined)
+                    hashes.push(secretHash);
+            }
             if (LastEvaluatedKey === undefined)
                 return hashes;
             params.ExclusiveStartKey = LastEvaluatedKey;

package/dist/stores/LambderMemoryCache.d.ts

@@ -1,4 +1,4 @@
-import type { LambderCache, LambderCacheKey, LambderCacheListOptions, LambderCacheSetOptions } from "../shared/contracts/LambderCache.js";
+import type { LambderCache, LambderCacheGetOrSetOptions, LambderCacheKey, LambderCacheListOptions, LambderCacheSetOptions } from "../shared/contracts/LambderCache.js";
 export interface LambderMemoryCacheOptions {
     /** Default: one year, as LambderDdbCache's. */
     defaultTtlSeconds?: number;
@@ -41,7 +41,7 @@ export declare class LambderMemoryCache implements LambderCache {
     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>;
+    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheGetOrSetOptions): 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. */

package/dist/stores/LambderS3FileSource.d.ts

@@ -43,8 +43,9 @@ export declare class LambderS3FileSource implements LambderFileSource {
     private readonly clientConfig;
     private readonly notFoundErrorNames;
     private client;
-    private sdk;
+    private clientSdk;
     constructor({ bucket, prefix, client, clientConfig, notFoundErrorNames }: LambderS3FileSourceOptions);
-    private loadSdk;
     read(relativePath: string): Promise<LambderFile | null>;
+    /** The SDK, loaded on the first read, and the client: the one supplied, or one made from clientConfig. */
+    private s3;
 }

package/dist/stores/LambderS3FileSource.js

@@ -1,4 +1,5 @@
 import { remoteStoreFile } from "../shared/contracts/LambderFileSource.js";
+import { withInstallHint } from "./LambderSdkInstallHint.js";
 const DEFAULT_NOT_FOUND_ERROR_NAMES = ["NoSuchKey", "NotFound", "AccessDenied", "KeyTooLongError", "InvalidURI", "InvalidObjectName"];
 /**
  * Files from an S3 bucket, or any S3-compatible store such as Cloudflare
@@ -18,7 +19,7 @@ export class LambderS3FileSource {
     clientConfig;
     notFoundErrorNames;
     client;
-    sdk;
+    clientSdk;
     constructor({ bucket, prefix = "", client, clientConfig, notFoundErrorNames = DEFAULT_NOT_FOUND_ERROR_NAMES }) {
         if (!bucket.trim())
             throw new Error("bucket is required");
@@ -28,21 +29,11 @@ export class LambderS3FileSource {
         this.clientConfig = clientConfig;
         this.notFoundErrorNames = notFoundErrorNames;
     }
-    loadSdk() {
-        if (!this.sdk) {
-            this.sdk = import("@aws-sdk/client-s3").catch(() => {
-                throw new Error("LambderS3FileSource requires @aws-sdk/client-s3: npm install @aws-sdk/client-s3");
-            });
-        }
-        return this.sdk;
-    }
     async read(relativePath) {
-        const { S3Client, GetObjectCommand } = await this.loadSdk();
-        if (!this.client)
-            this.client = new S3Client(this.clientConfig ?? {});
+        const { sdk, client } = await this.s3();
         let output;
         try {
-            output = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: `${this.prefix}${relativePath}` }));
+            output = await client.send(new sdk.GetObjectCommand({ Bucket: this.bucket, Key: `${this.prefix}${relativePath}` }));
         }
         catch (err) {
             const name = err.name;
@@ -54,4 +45,11 @@ export class LambderS3FileSource {
             return null;
         return remoteStoreFile(Buffer.from(await output.Body.transformToByteArray()), output.ContentType);
     }
+    /** The SDK, loaded on the first read, and the client: the one supplied, or one made from clientConfig. */
+    async s3() {
+        this.clientSdk ??= withInstallHint(import("@aws-sdk/client-s3"), "@aws-sdk/client-s3", "LambderS3FileSource", () => { this.clientSdk = undefined; });
+        const sdk = await this.clientSdk;
+        this.client ??= new sdk.S3Client(this.clientConfig ?? {});
+        return { sdk, client: this.client };
+    }
 }

package/dist/stores/LambderS3UploadBucket.d.ts

@@ -1,5 +1,7 @@
 import type { S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
 import { type LambderUploadBucket, type LambderUploadContentDisposition, type LambderUploadFileFacts, type LambderUploadMethod, type LambderUploadObjectOptions, type LambderUploadRule, type LambderUploadTicket, type LambderUploadVerdict } from "../shared/contracts/LambderUploadBucket.js";
+import type { LambderMemoryUploadBucketOptions } from "./LambderMemoryUploadBucket.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 export type LambderS3UploadBucketOptions = {
     bucket: string;
     /** A ready client, e.g. one shared with the rest of the app. */
@@ -50,6 +52,16 @@ export declare class LambderS3UploadBucket implements LambderUploadBucket {
     private presignedPostSdk;
     private requestPresignerSdk;
     constructor({ bucket, client, clientConfig, ticketLifetimeSeconds, downloadLifetimeSeconds, uploadMethod }: LambderS3UploadBucketOptions);
+    /**
+     * Puts a memory twin under this bucket in place, for `lambder/testing`:
+     * every LambderUploadBucket member answers from the twin from then on.
+     * The twin signs with this bucket's own lifetimes and upload method, so a
+     * client takes the path against it that it takes against this bucket.
+     * Keyed by a symbol no entry point exports; see registerSwappableInstance.
+     */
+    [LAMBDER_BACKEND_SWAP](twins: {
+        uploadBucket(options: LambderMemoryUploadBucketOptions): LambderUploadBucket;
+    }): void;
     issueUploadTicket({ objectKey, fileFacts, uploadRule, lifetimeSeconds, object }: {
         objectKey: string;
         fileFacts: LambderUploadFileFacts;

package/dist/stores/LambderS3UploadBucket.js

@@ -3,8 +3,15 @@ import { contentDispositionHeader } from "../shared/util/LambderContentDispositi
 import { uploadObjectFormFields, uploadObjectHeaders } from "../shared/wire/LambderUploadObjectFields.js";
 import { refuseUnacceptedUpload } from "../shared/wire/LambderUploadRefusal.js";
 import { withInstallHint } from "./LambderSdkInstallHint.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
+import { delegateToTwin, registerSwappableInstance } from "../shared/util/LambderSwappableInstances.js";
 /** The S3 error names that mean nothing is stored under the key: HeadObject answers NotFound, the other calls NoSuchKey. */
 const MISSING_OBJECT_ERROR_NAMES = ["NotFound", "NoSuchKey"];
+/** Every LambderUploadBucket member, which the swap door hands to a memory twin. */
+const UPLOAD_BUCKET_MEMBERS = {
+    issueUploadTicket: true, verifyUploadedObject: true, issueDownloadUrl: true,
+    readObject: true, writeObject: true, copyObject: true, deleteObject: true,
+};
 /**
  * An S3 bucket browsers upload to directly (see LambderUploadBucket).
  *
@@ -46,6 +53,22 @@ export class LambderS3UploadBucket {
         this.ticketLifetimeSeconds = ticketLifetimeSeconds;
         this.downloadLifetimeSeconds = downloadLifetimeSeconds;
         this.uploadMethod = uploadMethod;
+        registerSwappableInstance(this);
+    }
+    /**
+     * Puts a memory twin under this bucket in place, for `lambder/testing`:
+     * every LambderUploadBucket member answers from the twin from then on.
+     * The twin signs with this bucket's own lifetimes and upload method, so a
+     * client takes the path against it that it takes against this bucket.
+     * Keyed by a symbol no entry point exports; see registerSwappableInstance.
+     */
+    [LAMBDER_BACKEND_SWAP](twins) {
+        const twin = twins.uploadBucket({
+            ticketLifetimeSeconds: this.ticketLifetimeSeconds,
+            downloadLifetimeSeconds: this.downloadLifetimeSeconds,
+            uploadMethod: this.uploadMethod,
+        });
+        delegateToTwin(this, twin, UPLOAD_BUCKET_MEMBERS);
     }
     async issueUploadTicket({ objectKey, fileFacts, uploadRule, lifetimeSeconds = this.ticketLifetimeSeconds, object }) {
         assertPinnedObjectKey(objectKey);

package/dist/stores/LambderStorageBackedCache.d.ts

@@ -1,4 +1,4 @@
-import type { LambderCache, LambderCacheKey, LambderCacheListOptions, LambderCacheSetOptions } from "../shared/contracts/LambderCache.js";
+import type { LambderCache, LambderCacheGetOrSetOptions, LambderCacheKey, LambderCacheListOptions, LambderCacheSetOptions } from "../shared/contracts/LambderCache.js";
 import { type LambderCacheAddress } from "./LambderCacheKeys.js";
 /** One entry as a storage keeps it: the value's JSON text and the second it stops being live. */
 export interface LambderCacheStoredEntry {
@@ -85,7 +85,7 @@ export declare class LambderStorageBackedCache implements LambderCache {
     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>;
+    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheGetOrSetOptions): Promise<T>;
     /** Whole seconds, as entries expire in every cache here, so a TTL ends on the same second as the memory cache's. */
     private nowSeconds;
     /** The entry at the address while it is live; the storage may still hold one past its expiry. */

package/dist/stores/LambderStoredText.d.ts

@@ -0,0 +1,26 @@
+import type { LambderCompressionSettings } from "../shared/wire/LambderCompressionOption.js";
+/** Text as a store keeps it: `stored` is the Brotli bytes ("br") or the UTF-8 bytes themselves ("identity"). */
+export interface LambderStoredText {
+    encoding: "br" | "identity";
+    stored: Buffer;
+    /** The text's UTF-8 byte length: the declared length a compressed text is restored under. */
+    textBytes: number;
+}
+/** What a store restores stored text under: the most it ever writes, and its own name for the refusal. */
+export interface LambderStoredTextCeiling {
+    user: string;
+    maxTextBytes: number;
+}
+/**
+ * The text's UTF-8 bytes as the store keeps them, under its compression
+ * settings (null: compression off). The plain form is the bytes handed in,
+ * not a copy.
+ */
+export declare const storedTextOf: (utf8: Buffer, compression: LambderCompressionSettings | null) => Promise<LambderStoredText>;
+/**
+ * The text a compressed record holds, restored under the length it declares,
+ * or a throw: a plain Error naming the store when the declared length is over
+ * its ceiling, and the codec's LambderCompressionError when the length is
+ * missing or the bytes do not restore to exactly that length.
+ */
+export declare const restoreStoredText: (compressed: Uint8Array, declaredBytes: number, ceiling: LambderStoredTextCeiling) => Promise<string>;

package/dist/stores/LambderStoredText.js

@@ -0,0 +1,25 @@
+import { compressText, restoreText } from "../shared/wire/LambderCompressionCodec.js";
+/**
+ * The text's UTF-8 bytes as the store keeps them, under its compression
+ * settings (null: compression off). The plain form is the bytes handed in,
+ * not a copy.
+ */
+export const storedTextOf = async (utf8, compression) => {
+    const textBytes = utf8.byteLength;
+    if (compression && textBytes > 0 && textBytes >= compression.minBytes) {
+        return { encoding: "br", stored: await compressText(utf8, "br", compression.quality), textBytes };
+    }
+    return { encoding: "identity", stored: utf8, textBytes };
+};
+/**
+ * The text a compressed record holds, restored under the length it declares,
+ * or a throw: a plain Error naming the store when the declared length is over
+ * its ceiling, and the codec's LambderCompressionError when the length is
+ * missing or the bytes do not restore to exactly that length.
+ */
+export const restoreStoredText = async (compressed, declaredBytes, ceiling) => {
+    if (declaredBytes > ceiling.maxTextBytes) {
+        throw new Error(`${ceiling.user}: a stored record declares ${declaredBytes} bytes of text, over the ${ceiling.maxTextBytes}-byte limit it restores, so the record is unusable.`);
+    }
+    return await restoreText(compressed, "br", { declaredBytes });
+};

package/dist/testing/LambderConformanceRunner.d.ts

@@ -38,8 +38,15 @@ export type LambderConformanceRunner = {
 export type LambderConformanceSetup = {
     now: () => number;
 };
-/** Where every case's clock starts: a fixed moment, so the records a case writes are the same on every run. */
-export declare const CONFORMANCE_START_MILLIS = 1700000000000;
+/**
+ * Where every case's clock starts: 2100-01-01T00:00:00Z. Fixed, so the
+ * records a case writes are the same on every run, and far in the future, so
+ * a storage that also hands its records to a native TTL (a database that
+ * deletes expired rows itself, Redis's EXPIREAT) holds every one a case
+ * writes, and a record counts as expired only when the store says so by the
+ * case's clock. In seconds it still fits 32 bits unsigned.
+ */
+export declare const CONFORMANCE_START_MILLIS = 4102444800000;
 /** The clock of one case: `now` for the store, `set` for the case. */
 export declare const conformanceClock: () => LambderConformanceSetup & {
     set(millis: number): void;

package/dist/testing/LambderConformanceRunner.js

@@ -9,8 +9,15 @@
  * under vitest, jest, or any runner with a jest-style `expect`, and the
  * package depends on none of them.
  */
-/** Where every case's clock starts: a fixed moment, so the records a case writes are the same on every run. */
-export const CONFORMANCE_START_MILLIS = 1_700_000_000_000;
+/**
+ * Where every case's clock starts: 2100-01-01T00:00:00Z. Fixed, so the
+ * records a case writes are the same on every run, and far in the future, so
+ * a storage that also hands its records to a native TTL (a database that
+ * deletes expired rows itself, Redis's EXPIREAT) holds every one a case
+ * writes, and a record counts as expired only when the store says so by the
+ * case's clock. In seconds it still fits 32 bits unsigned.
+ */
+export const CONFORMANCE_START_MILLIS = 4_102_444_800_000;
 /** The clock of one case: `now` for the store, `set` for the case. */
 export const conformanceClock = () => {
     let millis = CONFORMANCE_START_MILLIS;