lambder 4.6.1 → 4.7.1

package/dist/shared/LambderRequestPayload.js

@@ -0,0 +1,96 @@
+/**
+ * Request payload compression: the wire format both sides speak.
+ *
+ * When a LambderCaller call's payload clears the configured size, the caller
+ * sends the payload's JSON as `payloadGz` (gzip bytes, base64) beside
+ * `payloadBytes` (its UTF-8 byte length) in place of `payload`, and the
+ * server restores it before anything reads the payload. Everything else in
+ * the envelope (apiName, version, token, siteHost, guardInputs,
+ * idempotencyKey) stays plain text, so routing, logging and request mocking
+ * are unaffected.
+ *
+ * Base64 inside the JSON envelope, rather than a binary body with
+ * Content-Encoding: API Gateway hands a binary request body to Lambda
+ * base64-encoded anyway, so binary saves nothing against Lambda's ~6MB
+ * invoke payload cap while adding a content-type negotiation that gateways,
+ * CDNs and mock servers each treat differently. Base64's 4/3 overhead
+ * applies to bytes that already shrank several times over.
+ *
+ * gzip rather than Brotli because the browser's CompressionStream offers
+ * gzip and deflate only; responses, compressed by Node, do prefer Brotli.
+ *
+ * `payloadBytes` is not bookkeeping: it bounds the server's decompression
+ * and the restored length must match it exactly, the same guarantee
+ * LambderCompressionCodec gives stored records, so a malicious or truncated
+ * body fails instead of expanding without limit.
+ */
+/** Envelope field carrying the base64 gzip of the payload's JSON. */
+export const COMPRESSED_PAYLOAD_FIELD = "payloadGz";
+/** Envelope field carrying the UTF-8 byte length of that JSON before compression. */
+export const COMPRESSED_PAYLOAD_BYTES_FIELD = "payloadBytes";
+/**
+ * Defaults, resolved through the shared resolveCompressionOption like every
+ * other compression option. Below a few KB the gzip header, the base64
+ * overhead and the round trip through CompressionStream cost more than the
+ * bytes they save. The caller passes `option ?? false`, because unlike the
+ * at-rest stores this one is off unless asked for.
+ */
+export const DEFAULT_REQUEST_COMPRESSION_SETTINGS = { minBytes: 4096 };
+/**
+ * Default ceiling for a restored payload. Lambda's ~6MB invoke cap already
+ * bounds the compressed bytes; this bounds what they may expand to, so a
+ * highly compressible body cannot exhaust the function's memory.
+ */
+export const DEFAULT_MAX_REQUEST_PAYLOAD_BYTES = 20_000_000;
+/** Chunked so a large payload cannot overflow the argument list of String.fromCharCode. */
+const bytesToBase64 = (bytes) => {
+    const chunkSize = 0x8000;
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    }
+    return btoa(binary);
+};
+/** True when this runtime can compress request payloads (browsers, and Node 18+). */
+export const isRequestCompressionAvailable = () => typeof CompressionStream !== "undefined" && typeof btoa !== "undefined";
+/**
+ * Gzip one payload's JSON for sending, or null when the plain JSON should go
+ * instead: below the threshold, or when compressing did not make it smaller.
+ * The threshold is measured on real UTF-8 bytes, not string length, so a
+ * payload of multi-byte text is judged by what actually goes on the wire.
+ *
+ * The second null matters for the payloads most likely to be large: a
+ * base64 image gzips to nearly its own size, and base64 then inflates the
+ * result past the original. Sending that would cost CPU on both ends for a
+ * request that got bigger, so the compressed form is only ever sent when it
+ * is smaller than the JSON it replaces.
+ */
+export const compressPayloadJson = async (json, minBytes) => {
+    const encoded = new TextEncoder().encode(json);
+    if (encoded.length < minBytes)
+        return null;
+    const stream = new Blob([encoded]).stream().pipeThrough(new CompressionStream("gzip"));
+    const compressed = new Uint8Array(await new Response(stream).arrayBuffer());
+    const base64 = bytesToBase64(compressed);
+    if (base64.length >= encoded.length)
+        return null;
+    return {
+        [COMPRESSED_PAYLOAD_FIELD]: base64,
+        [COMPRESSED_PAYLOAD_BYTES_FIELD]: encoded.length,
+    };
+};
+/**
+ * Restores a payload the caller compressed, for request mocking
+ * (LambderMSW), so a mock handler receives the same payload the server
+ * would. The server does NOT use this: it decompresses through zlib, whose
+ * bounded output is what makes an untrusted body safe to expand.
+ */
+export const decompressPayloadJson = async (payloadGz) => {
+    const binary = atob(payloadGz);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("gzip"));
+    return JSON.parse(await new Response(stream).text());
+};

package/dist/stores/LambderDdbCache.d.ts

@@ -1,5 +1,5 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { type LambderCompressionOption } from "./LambderDdbCompression.js";
+import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
 export interface LambderDdbCacheOptions {
     tableName: string;
     region?: string;

package/dist/stores/LambderDdbCache.js

@@ -1,6 +1,7 @@
 import { BatchWriteItemCommand, DeleteItemCommand, DynamoDBClient, GetItemCommand, PutItemCommand, QueryCommand, } from "@aws-sdk/client-dynamodb";
 import { getCrypto } from "../shared/node-polyfills.js";
-import { brotliCompressText, brotliRestoreText, resolveCompressionOption, } from "./LambderDdbCompression.js";
+import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
 import { LRUCache } from "lru-cache";
 const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
 const DEFAULT_CHUNK_BYTES = 350 * 1024;
@@ -17,7 +18,7 @@ const COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
 // sit in a frontend bundle's import graph (via the package root) without
 // breaking; using the cache at runtime still requires Node. Brotli helpers
 // are shared with LambderDdbIdempotency and LambderSessionManager via
-// ./LambderDdbCompression.js.
+// ../shared/LambderCompressionCodec.js.
 const requireCrypto = async () => {
     const crypto = await getCrypto();
     if (!crypto)
@@ -152,7 +153,7 @@ export class LambderDdbCache {
         }
         const brotli = this.compression && input.length >= this.compression.minBytes ? this.compression : null;
         const encoding = brotli ? "br" : "identity";
-        const stored = brotli ? await brotliCompressText(input, brotli.quality) : input;
+        const stored = brotli ? await compressText(input, "br", brotli.quality) : input;
         if (stored.length > this.maxValueBytes) {
             throw new Error(`Stored cache value exceeds maxValueBytes (${stored.length} > ${this.maxValueBytes})`);
         }
@@ -452,7 +453,7 @@ export class LambderDdbCache {
     }
     /** The JSON text of a stored payload. */
     async decode(stored, encoding, uncompressedBytes) {
-        return encoding === "br" ? await brotliRestoreText(stored, uncompressedBytes) : stored.toString("utf8");
+        return encoding === "br" ? await restoreBoundedText(stored, uncompressedBytes, "br") : stored.toString("utf8");
     }
     remember(key, stored, encoding, uncompressedBytes, expiresAt) {
         if (!this.memory)

package/dist/stores/LambderDdbIdempotency.d.ts

@@ -1,5 +1,5 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { type LambderCompressionOption } from "./LambderDdbCompression.js";
+import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
 export interface LambderDdbIdempotencyOptions {
     tableName: string;
     region?: string;

package/dist/stores/LambderDdbIdempotency.js

@@ -1,6 +1,7 @@
 import crypto from "crypto";
 import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } from "@aws-sdk/client-dynamodb";
-import { brotliCompressText, brotliRestoreText, resolveCompressionOption, } from "./LambderDdbCompression.js";
+import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
 /** Bodies of 1KB or more are stored Brotli-compressed by default; smaller ones stay plain. */
 const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
 /**
@@ -66,7 +67,7 @@ export class LambderDdbIdempotency {
     static async readItemBody(item) {
         const compressed = item.bodyBr?.B;
         if (compressed)
-            return await brotliRestoreText(compressed, Number(item.bodyBytes?.N ?? 0));
+            return await restoreBoundedText(compressed, Number(item.bodyBytes?.N ?? 0), "br");
         return item.body?.S ?? "";
     }
     /**
@@ -157,7 +158,7 @@ export class LambderDdbIdempotency {
         const rawBody = Buffer.from(body, "utf8");
         let bodyAttributes;
         if (this.compression && rawBody.byteLength >= this.compression.minBytes) {
-            const compressed = await brotliCompressText(rawBody, this.compression.quality);
+            const compressed = await compressText(rawBody, "br", this.compression.quality);
             if (compressed.byteLength > MAX_STORED_BODY_BYTES)
                 return "too-large";
             // bodyBytes bounds and verifies decompression on read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "4.6.1",
+  "version": "4.7.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,26 +51,40 @@
     "url": "https://github.com/nesovera/lambder.git"
   },
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.574.0",
-    "@aws-sdk/lib-dynamodb": "^3.574.0",
     "cookie": "^1.0.2",
     "js-cookie": "^3.0.5",
     "lru-cache": "^11.5.2",
     "mime-types": "^2.1.35",
-    "path-to-regexp": "^6.2.1",
-    "zod": "^4.1.12"
+    "path-to-regexp": "^6.2.1"
   },
   "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.574.0",
     "@aws-sdk/client-s3": "^3.574.0",
-    "msw": "^2.0.0"
+    "@aws-sdk/lib-dynamodb": "^3.574.0",
+    "msw": "^2.0.0",
+    "zod": "^4.1.12"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-dynamodb": {
+      "optional": true
+    },
     "msw": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.913.0",
     "@aws-sdk/client-s3": "^3.1127.0",
+    "@aws-sdk/lib-dynamodb": "^3.913.0",
     "@types/aws-lambda": "^8.10.136",
     "@types/cookie": "^0.6.0",
     "@types/js-cookie": "^3.0.6",
@@ -82,6 +96,7 @@
     "aws-sdk-client-mock": "^4.1.0",
     "eslint": "^8.57.0",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^4.1.12"
   }
 }

package/dist/stores/LambderDdbCompression.d.ts

@@ -1,25 +0,0 @@
-/**
- * The compression option every store shares. `true` is on with the store's
- * defaults, `false` is off, an object overrides the defaults: `minBytes` is
- * the UTF-8 size from which a value is stored compressed (0: always),
- * `quality` is Brotli 0-11. Values below minBytes are stored plain, and a
- * store reads records of either shape, so the option can be switched on or
- * off on a live table: records written under the other setting keep
- * reading, and each is rewritten in the current shape on its next write.
- */
-export type LambderCompressionConfig = {
-    minBytes?: number;
-    quality?: number;
-};
-export type LambderCompressionOption = boolean | LambderCompressionConfig;
-export type LambderCompressionSettings = Required<LambderCompressionConfig>;
-/** Resolves a store's compression option against its defaults: null when off. */
-export declare const resolveCompressionOption: (option: LambderCompressionOption | undefined, defaults: LambderCompressionSettings) => LambderCompressionSettings | null;
-export declare const brotliCompressText: (input: Buffer, quality: number) => Promise<Buffer>;
-/**
- * Restores text stored as Brotli bytes beside its declared UTF-8 byte length.
- * The length bounds the decompression and the output must match it exactly,
- * so a truncated or tampered record fails instead of decoding to something
- * else.
- */
-export declare const brotliRestoreText: (compressed: Uint8Array, declaredBytes: number) => Promise<string>;

package/dist/stores/LambderDdbCompression.js

@@ -1,61 +0,0 @@
-import { getZlib } from "../shared/node-polyfills.js";
-/** Resolves a store's compression option against its defaults: null when off. */
-export const resolveCompressionOption = (option, defaults) => {
-    if (option === false)
-        return null;
-    const config = option === true || option === undefined ? {} : option;
-    const settings = { minBytes: config.minBytes ?? defaults.minBytes, quality: config.quality ?? defaults.quality };
-    if (!Number.isSafeInteger(settings.minBytes) || settings.minBytes < 0) {
-        throw new Error("compression.minBytes must be a non-negative integer");
-    }
-    if (!Number.isInteger(settings.quality) || settings.quality < 0 || settings.quality > 11) {
-        throw new Error("compression.quality must be an integer from 0 to 11");
-    }
-    return settings;
-};
-const requireZlib = async () => {
-    const zlib = await getZlib();
-    if (!zlib)
-        throw new Error("Lambder DDB stores require a Node.js environment.");
-    return zlib;
-};
-export const brotliCompressText = async (input, quality) => {
-    const zlib = await requireZlib();
-    return new Promise((resolve, reject) => {
-        zlib.brotliCompress(input, {
-            params: {
-                [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
-                [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
-            },
-        }, (error, output) => {
-            if (error)
-                reject(error);
-            else
-                resolve(output);
-        });
-    });
-};
-/**
- * Restores text stored as Brotli bytes beside its declared UTF-8 byte length.
- * The length bounds the decompression and the output must match it exactly,
- * so a truncated or tampered record fails instead of decoding to something
- * else.
- */
-export const brotliRestoreText = async (compressed, declaredBytes) => {
-    if (!Number.isSafeInteger(declaredBytes) || declaredBytes <= 0) {
-        throw new Error("compressed record is missing its byte length");
-    }
-    const zlib = await requireZlib();
-    const output = await new Promise((resolve, reject) => {
-        zlib.brotliDecompress(Buffer.from(compressed), { maxOutputLength: declaredBytes }, (error, result) => {
-            if (error)
-                reject(error);
-            else
-                resolve(result);
-        });
-    });
-    if (output.length !== declaredBytes) {
-        throw new Error("decompressed length does not match the record");
-    }
-    return output.toString("utf8");
-};