lambder 4.6.2 → 4.7.3

package/dist/core/LambderResponse.d.ts

@@ -1,3 +1,4 @@
+import type { LambderCompressionOption, LambderCompressionSettingsBase, LambderEncoding } from "../shared/LambderCompressionOption.js";
 import type { LambderRenderContext } from "./LambderContext.js";
 export type HttpStatusCode = 100 | 101 | 200 | 201 | 202 | 203 | 204 | 206 | 300 | 301 | 302 | 303 | 304 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 408 | 409 | 410 | 412 | 413 | 415 | 416 | 418 | 422 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504;
 export type LambderHeadersInput = Record<string, string | string[]>;
@@ -53,14 +54,31 @@ export declare class LambderResponse {
 }
 export declare const isCompressibleContentType: (contentType: string | undefined) => boolean;
 export declare const acceptsEncoding: (acceptEncoding: string | undefined | null, encoding: string) => boolean;
+/** Response-side settings: the threshold plus what the wire can negotiate. */
+export type LambderResponseCompressionSettings = LambderCompressionSettingsBase & {
+    /** Preference order; the first the client accepts wins. */
+    encodings: LambderEncoding[];
+    /** Brotli quality 0-11, the same field the at-rest stores take. Kept low: this runs per request, and 11 is orders of magnitude slower. */
+    quality: number;
+};
+/** The `compression` option at creation: `true` for the defaults, `false` for off, or overrides. */
+export type LambderResponseCompressionOption = LambderCompressionOption<LambderResponseCompressionSettings>;
 export type LambderFinalizeOptions = {
-    compression: false | {
-        minBytes: number;
-    };
+    /** Resolved settings, or null when compression is off: the same `Settings | null` contract the stores hold. */
+    compression: LambderResponseCompressionSettings | null;
     etag: boolean;
     /** Guard against Lambda's ~6MB response cap with a clear error. */
     maxResponseBytes: number;
 };
+/**
+ * Brotli first: every browser that accepts it produces smaller bodies than
+ * gzip at comparable speed on quality 5, typically 15-25% on markup and
+ * prose and substantially more on the repetitive record lists API responses
+ * tend to be. That is bandwidth saved and, because the ~6MB cap applies to
+ * the encoded bytes, headroom gained. Clients that do not offer `br` fall
+ * through to gzip.
+ */
+export declare const DEFAULT_RESPONSE_COMPRESSION_SETTINGS: LambderResponseCompressionSettings;
 export declare const DEFAULT_FINALIZE_OPTIONS: LambderFinalizeOptions;
 /**
  * Convert an intermediate LambderResponse into the final Lambda response:

package/dist/core/LambderResponse.js

@@ -1,4 +1,5 @@
-import { getZlib, getCrypto } from "../shared/node-polyfills.js";
+import { getCrypto } from "../shared/node-polyfills.js";
+import { compressText } from "../shared/LambderCompressionCodec.js";
 export const normalizeHeaders = (headers) => Object.fromEntries(Object.entries(headers ?? {}).map(([k, v]) => [k, Array.isArray(v) ? [...v] : [v]]));
 /**
  * Intermediate response object returned by all response builder methods and by
@@ -83,8 +84,21 @@ export const acceptsEncoding = (acceptEncoding, encoding) => {
         return !q || Number(q.slice(2)) > 0;
     });
 };
+/**
+ * Brotli first: every browser that accepts it produces smaller bodies than
+ * gzip at comparable speed on quality 5, typically 15-25% on markup and
+ * prose and substantially more on the repetitive record lists API responses
+ * tend to be. That is bandwidth saved and, because the ~6MB cap applies to
+ * the encoded bytes, headroom gained. Clients that do not offer `br` fall
+ * through to gzip.
+ */
+export const DEFAULT_RESPONSE_COMPRESSION_SETTINGS = {
+    minBytes: 860,
+    encodings: ["br", "gzip"],
+    quality: 5,
+};
 export const DEFAULT_FINALIZE_OPTIONS = {
-    compression: { minBytes: 860 },
+    compression: DEFAULT_RESPONSE_COMPRESSION_SETTINGS,
     etag: true,
     maxResponseBytes: 5_500_000,
 };
@@ -141,18 +155,21 @@ export const finalizeResponse = async (ctx, response, options, format = "v1") =>
         const alreadyEncoded = !!response.getHeader("Content-Encoding");
         const eligibleForCompression = !alreadyEncoded && (response.compress === true ||
             (response.compress === "auto" &&
-                options.compression !== false &&
+                options.compression !== null &&
                 bodyBuffer.length >= options.compression.minBytes &&
                 isCompressibleContentType(contentType)));
         if (eligibleForCompression) {
             // Vary even when this client didn't accept an encoding, to keep caches correct.
             response.addHeader("Vary", "Accept-Encoding");
-            if (acceptsEncoding(getRequestHeader(ctx, "accept-encoding"), "gzip")) {
-                const zlib = await getZlib();
-                if (zlib) {
-                    bodyBuffer = zlib.gzipSync(bodyBuffer);
-                    response.setHeader("Content-Encoding", "gzip");
-                }
+            // compress: true forces compression even with it globally off, so
+            // the settings fall back to the defaults rather than being absent.
+            const settings = options.compression ?? DEFAULT_RESPONSE_COMPRESSION_SETTINGS;
+            const acceptEncoding = getRequestHeader(ctx, "accept-encoding");
+            const encoding = settings.encodings.find((candidate) => acceptsEncoding(acceptEncoding, candidate));
+            if (encoding) {
+                // The same codec, quality and TEXT mode a stored record gets.
+                bodyBuffer = await compressText(bodyBuffer, encoding, settings.quality);
+                response.setHeader("Content-Encoding", encoding);
             }
         }
         if (Buffer.isBuffer(response.body) || response.getHeader("Content-Encoding")) {

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder
 export { default as LambderResolver } from "./core/LambderResolver.js";
 export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
 export { default as LambderSessionController } from "./session/LambderSessionController.js";
-export { LambderResponse, finalizeResponse, acceptsEncoding, type HttpStatusCode, type LambderHttpResponse, type LambderHttpEventFormat, type LambderHeadersInput, type LambderFinalizeOptions, } from "./core/LambderResponse.js";
+export { LambderResponse, finalizeResponse, acceptsEncoding, type HttpStatusCode, type LambderHttpResponse, type LambderHttpEventFormat, type LambderHeadersInput, type LambderFinalizeOptions, type LambderResponseCompressionSettings, type LambderResponseCompressionOption, } from "./core/LambderResponse.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
@@ -23,7 +23,10 @@ export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export type { LambderS3FileSourceOptions } from "./stores/LambderS3FileSource.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
 export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
-export type { LambderCompressionOption, LambderCompressionConfig } from "./stores/LambderDdbCompression.js";
+export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/LambderCompressionOption.js";
+export type { LambderCompressionOption, LambderCompressionSettings, LambderCompressionSettingsBase, LambderEncoding, } from "./shared/LambderCompressionOption.js";
+export { compressText, restoreBoundedText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "./shared/LambderCompressionCodec.js";
+export type { LambderRestoreFailure } from "./shared/LambderCompressionCodec.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
@@ -41,5 +44,7 @@ export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, Lambd
 export { type ApiContractShape, type LambderApiResponse, type LambderApiResponseConfig, } from "./shared/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./core/LambderContext.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
+export { COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_REQUEST_PAYLOAD_BYTES, } from "./shared/LambderRequestPayload.js";
+export type { LambderCompressedPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/LambderRequestPayload.js";
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./core/LambderCookie.js";
 export type { LambderCookieOptions, LambderClearCookieOptions, LambderCookieDomain } from "./core/LambderCookie.js";

package/dist/index.js

@@ -18,6 +18,11 @@ export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
 export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
+// Compression: the option every site shares, and the one codec behind them all.
+export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/LambderCompressionOption.js";
+// Brotli/gzip plus the bounded, length-verified restore every compressed
+// value in Lambder (records at rest, request payloads) goes through.
+export { compressText, restoreBoundedText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "./shared/LambderCompressionCodec.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 // DynamoDB-backed compressed cache (standalone, server-only)
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
@@ -32,5 +37,7 @@ export { lambderRateLimitKey } from "./policies/LambderApiRateLimits.js";
 // Typed translations (standalone, isomorphic)
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
+// Request payload compression: the wire format LambderCaller and the server share.
+export { COMPRESSED_PAYLOAD_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_REQUEST_PAYLOAD_BYTES, } from "./shared/LambderRequestPayload.js";
 // Cookies (res.setCookie / res.clearCookie build on these; exported for code holding a LambderResponse)
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./core/LambderCookie.js";

package/dist/session/LambderSessionManager.d.ts

@@ -1,4 +1,4 @@
-import { type LambderCompressionOption } from "../stores/LambderDdbCompression.js";
+import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
 export type LambderSessionContext<SessionData = any> = {
     [x: string]: any;
     /**

package/dist/session/LambderSessionManager.js

@@ -1,7 +1,8 @@
 import crypto from "crypto";
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
-import { brotliCompressText, brotliRestoreText, resolveCompressionOption, } from "../stores/LambderDdbCompression.js";
+import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
 /**
  * Session compression defaults: every record compressed (see
  * LambderCompressionOption for the option's shape and toggle semantics).
@@ -95,7 +96,7 @@ export default class LambderSessionManager {
         const { data, ...item } = session;
         const raw = this.compression && Buffer.from(JSON.stringify(data), "utf8");
         if (this.compression && raw && raw.byteLength >= this.compression.minBytes) {
-            item.dataBr = await brotliCompressText(raw, this.compression.quality);
+            item.dataBr = await compressText(raw, "br", this.compression.quality);
             item.dataBytes = raw.byteLength;
         }
         else {
@@ -201,7 +202,7 @@ export default class LambderSessionManager {
         // that fails to decode throws, which the controller treats like any
         // malformed record: no session.
         if (session.dataBr) {
-            session.data = JSON.parse(await brotliRestoreText(session.dataBr, session.dataBytes));
+            session.data = JSON.parse(await restoreBoundedText(session.dataBr, session.dataBytes, "br"));
             delete session.dataBr;
             delete session.dataBytes;
         }

package/dist/shared/LambderApiError.d.ts

@@ -87,6 +87,8 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly invalidIdempotencyKey: "lambder/invalid-idempotency-key";
     /** No API is registered under the requested name. */
     readonly apiNotFound: "lambder/api-not-found";
+    /** The request's compressed payload is malformed or over the size limit (400). */
+    readonly invalidRequestPayload: "lambder/invalid-request-payload";
 };
 export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
 export type LambderRefuseOptions = {

package/dist/shared/LambderApiError.js

@@ -53,6 +53,8 @@ export const LAMBDER_REFUSAL_CODES = {
     invalidIdempotencyKey: "lambder/invalid-idempotency-key",
     /** No API is registered under the requested name. */
     apiNotFound: "lambder/api-not-found",
+    /** The request's compressed payload is malformed or over the size limit (400). */
+    invalidRequestPayload: "lambder/invalid-request-payload",
 };
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid

package/dist/shared/LambderCompressionCodec.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The one place Lambder compresses and decompresses bytes.
+ *
+ * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
+ * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
+ * and request payloads (gzip, because the browser's CompressionStream
+ * offers nothing else). They all compress text, so TEXT mode throughout,
+ * and they all restore it the same way: the compressed bytes beside the
+ * text's original UTF-8 byte length.
+ *
+ * That length is the safety mechanism, not bookkeeping. It bounds the
+ * decompression, so a body that would expand without limit is cut off
+ * rather than allocated, and the restored length must match it exactly, so
+ * a truncated or tampered input fails instead of decoding to something
+ * merely plausible. Every caller gets that guarantee from this one
+ * implementation: a bug fixed here is fixed for records at rest and for
+ * untrusted request bodies alike.
+ *
+ * zlib is loaded lazily through node-polyfills, so a module importing this
+ * one can still sit in a frontend bundle's import graph via the package
+ * root. The option that decides WHETHER to compress, and the encoding
+ * vocabulary, live in LambderCompressionOption, which stays free of zlib
+ * entirely so the browser entry can resolve it.
+ */
+import type { LambderEncoding } from "./LambderCompressionOption.js";
+/** Why a bounded restore failed, for callers that answer rather than throw. */
+export declare const LAMBDER_RESTORE_FAILURES: {
+    /** The declared byte length is absent or not a positive integer. */
+    readonly missingLength: "missing-length";
+    /** zlib refused the bytes: not this algorithm, truncated, or over the bound. */
+    readonly undecodable: "undecodable";
+    /** It decompressed, but not to the length it declared. */
+    readonly lengthMismatch: "length-mismatch";
+};
+export type LambderRestoreFailure = (typeof LAMBDER_RESTORE_FAILURES)[keyof typeof LAMBDER_RESTORE_FAILURES];
+/**
+ * A restore that could not be trusted. Stores let it propagate (any throw
+ * means "unusable record"); the request pipeline catches it and turns
+ * `reason` into a client-facing refusal.
+ */
+export declare class LambderCompressionError extends Error {
+    readonly reason: LambderRestoreFailure;
+    constructor(reason: LambderRestoreFailure, message: string, options?: ErrorOptions);
+}
+/**
+ * Compresses text. `quality` is the Brotli quality (0-11) and is ignored by
+ * gzip, which has no comparable knob worth exposing.
+ */
+export declare const compressText: (input: Buffer, encoding: LambderEncoding, quality: number) => Promise<Buffer>;
+/**
+ * Restores text from compressed bytes beside the declared UTF-8 byte length
+ * of the original, bounded and verified by that length. Throws
+ * LambderCompressionError on anything it cannot vouch for.
+ */
+export declare const restoreBoundedText: (compressed: Uint8Array, declaredBytes: number, encoding: LambderEncoding) => Promise<string>;

package/dist/shared/LambderCompressionCodec.js

@@ -0,0 +1,113 @@
+/**
+ * The one place Lambder compresses and decompresses bytes.
+ *
+ * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
+ * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
+ * and request payloads (gzip, because the browser's CompressionStream
+ * offers nothing else). They all compress text, so TEXT mode throughout,
+ * and they all restore it the same way: the compressed bytes beside the
+ * text's original UTF-8 byte length.
+ *
+ * That length is the safety mechanism, not bookkeeping. It bounds the
+ * decompression, so a body that would expand without limit is cut off
+ * rather than allocated, and the restored length must match it exactly, so
+ * a truncated or tampered input fails instead of decoding to something
+ * merely plausible. Every caller gets that guarantee from this one
+ * implementation: a bug fixed here is fixed for records at rest and for
+ * untrusted request bodies alike.
+ *
+ * zlib is loaded lazily through node-polyfills, so a module importing this
+ * one can still sit in a frontend bundle's import graph via the package
+ * root. The option that decides WHETHER to compress, and the encoding
+ * vocabulary, live in LambderCompressionOption, which stays free of zlib
+ * entirely so the browser entry can resolve it.
+ */
+import { getZlib } from "./node-polyfills.js";
+/** Why a bounded restore failed, for callers that answer rather than throw. */
+export const LAMBDER_RESTORE_FAILURES = {
+    /** The declared byte length is absent or not a positive integer. */
+    missingLength: "missing-length",
+    /** zlib refused the bytes: not this algorithm, truncated, or over the bound. */
+    undecodable: "undecodable",
+    /** It decompressed, but not to the length it declared. */
+    lengthMismatch: "length-mismatch",
+};
+/**
+ * A restore that could not be trusted. Stores let it propagate (any throw
+ * means "unusable record"); the request pipeline catches it and turns
+ * `reason` into a client-facing refusal.
+ */
+export class LambderCompressionError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = "LambderCompressionError";
+        this.reason = reason;
+    }
+}
+// Not a LambderCompressionError: nothing was wrong with the bytes, so there
+// is no restore `reason` to report. Callers that map reasons fall through to
+// their generic failure, which is the honest answer here.
+const requireZlib = async () => {
+    const zlib = await getZlib();
+    if (!zlib)
+        throw new Error("Lambder compression requires a Node.js environment.");
+    return zlib;
+};
+/**
+ * Compresses text. `quality` is the Brotli quality (0-11) and is ignored by
+ * gzip, which has no comparable knob worth exposing.
+ */
+export const compressText = async (input, encoding, quality) => {
+    const zlib = await requireZlib();
+    return await new Promise((resolve, reject) => {
+        const done = (error, output) => { if (error)
+            reject(error);
+        else
+            resolve(output); };
+        if (encoding === "br") {
+            zlib.brotliCompress(input, {
+                params: {
+                    [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+                    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+                },
+            }, done);
+        }
+        else {
+            zlib.gzip(input, done);
+        }
+    });
+};
+/**
+ * Restores text from compressed bytes beside the declared UTF-8 byte length
+ * of the original, bounded and verified by that length. Throws
+ * LambderCompressionError on anything it cannot vouch for.
+ */
+export const restoreBoundedText = async (compressed, declaredBytes, encoding) => {
+    if (!Number.isSafeInteger(declaredBytes) || declaredBytes <= 0) {
+        throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.missingLength, "compressed value is missing its byte length");
+    }
+    const zlib = await requireZlib();
+    let output;
+    try {
+        // zlib reads any Uint8Array in place; a request-sized body is not copied first.
+        output = await new Promise((resolve, reject) => {
+            const done = (error, result) => { if (error)
+                reject(error);
+            else
+                resolve(result); };
+            // maxOutputLength is the bound: zlib stops rather than allocating past it.
+            if (encoding === "br")
+                zlib.brotliDecompress(compressed, { maxOutputLength: declaredBytes }, done);
+            else
+                zlib.gunzip(compressed, { maxOutputLength: declaredBytes }, done);
+        });
+    }
+    catch (err) {
+        throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.undecodable, "compressed value could not be decompressed", { cause: err });
+    }
+    if (output.length !== declaredBytes) {
+        throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.lengthMismatch, "decompressed length does not match the declared length");
+    }
+    return output.toString("utf8");
+};

package/dist/shared/LambderCompressionOption.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The compression option every part of Lambder speaks, and the one function
+ * that resolves it.
+ *
+ * Five places compress something: sessions, LambderDdbCache and
+ * LambderDdbIdempotency (Brotli at rest in DynamoDB), HTTP responses
+ * (Brotli/gzip on the wire) and request payloads (gzip on the wire). They
+ * differ in what they can be tuned with, so each declares its own settings
+ * type, but they share one vocabulary and one resolution: `true` is on with
+ * that site's defaults, `false` is off, an object overrides individual
+ * fields, and `minBytes` is always the size from which a value is
+ * compressed (0: always). Resolved settings are `null` when off, so every
+ * consumer holds `Settings | null` and reads `minBytes` the same way.
+ *
+ * Nothing here touches zlib, so the browser entry can resolve the caller's
+ * option without pulling Node built-ins into the bundle; the compression
+ * primitives themselves live in LambderCompressionCodec, which does load zlib.
+ */
+/** Algorithms Lambder can produce. Brotli at rest and preferred on responses; gzip everywhere a browser has to do the compressing. */
+export declare const LAMBDER_ENCODINGS: readonly ["br", "gzip"];
+export type LambderEncoding = (typeof LAMBDER_ENCODINGS)[number];
+/** Fields common to every site's settings. Sites add their own (`quality`, `encodings`). */
+export type LambderCompressionSettingsBase = {
+    minBytes: number;
+};
+/** Tuning for Brotli-at-rest: the shape sessions and the DynamoDB stores take. */
+export type LambderCompressionSettings = LambderCompressionSettingsBase & {
+    /** Brotli quality 0-11. */
+    quality: number;
+};
+/**
+ * The option a site accepts: `true` for that site's defaults, `false` for
+ * off, or an object overriding any of its settings. Parameterized by the
+ * site's settings; the default is the at-rest shape the stores and sessions
+ * take, and the request and response sites alias their own.
+ */
+export type LambderCompressionOption<TSettings extends LambderCompressionSettingsBase = LambderCompressionSettings> = boolean | Partial<TSettings>;
+/**
+ * Resolves one site's option against its defaults: `null` when off,
+ * otherwise the defaults with any supplied fields on top. `undefined` means
+ * "unspecified", so a site whose default is off passes `option ?? false`
+ * and one whose default is on passes the option through. A field set to
+ * `undefined` inside the object is unspecified too, so `{ minBytes:
+ * config.threshold }` with an optional threshold keeps the default.
+ *
+ * Validation is deliberately at resolution (construction) rather than at
+ * use: a misconfigured threshold, quality or encoding list is a startup
+ * error, not a surprise on some later request. The resolver knows the whole
+ * shared vocabulary and checks each field a site carries.
+ */
+export declare const resolveCompressionOption: <TSettings extends LambderCompressionSettingsBase>(option: LambderCompressionOption<TSettings> | undefined, defaults: TSettings) => TSettings | null;

package/dist/shared/LambderCompressionOption.js

@@ -0,0 +1,52 @@
+/**
+ * The compression option every part of Lambder speaks, and the one function
+ * that resolves it.
+ *
+ * Five places compress something: sessions, LambderDdbCache and
+ * LambderDdbIdempotency (Brotli at rest in DynamoDB), HTTP responses
+ * (Brotli/gzip on the wire) and request payloads (gzip on the wire). They
+ * differ in what they can be tuned with, so each declares its own settings
+ * type, but they share one vocabulary and one resolution: `true` is on with
+ * that site's defaults, `false` is off, an object overrides individual
+ * fields, and `minBytes` is always the size from which a value is
+ * compressed (0: always). Resolved settings are `null` when off, so every
+ * consumer holds `Settings | null` and reads `minBytes` the same way.
+ *
+ * Nothing here touches zlib, so the browser entry can resolve the caller's
+ * option without pulling Node built-ins into the bundle; the compression
+ * primitives themselves live in LambderCompressionCodec, which does load zlib.
+ */
+/** Algorithms Lambder can produce. Brotli at rest and preferred on responses; gzip everywhere a browser has to do the compressing. */
+export const LAMBDER_ENCODINGS = ["br", "gzip"];
+/**
+ * Resolves one site's option against its defaults: `null` when off,
+ * otherwise the defaults with any supplied fields on top. `undefined` means
+ * "unspecified", so a site whose default is off passes `option ?? false`
+ * and one whose default is on passes the option through. A field set to
+ * `undefined` inside the object is unspecified too, so `{ minBytes:
+ * config.threshold }` with an optional threshold keeps the default.
+ *
+ * Validation is deliberately at resolution (construction) rather than at
+ * use: a misconfigured threshold, quality or encoding list is a startup
+ * error, not a surprise on some later request. The resolver knows the whole
+ * shared vocabulary and checks each field a site carries.
+ */
+export const resolveCompressionOption = (option, defaults) => {
+    if (option === false)
+        return null;
+    const config = option === true || option === undefined ? {} : option;
+    const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+    const settings = { ...defaults, ...overrides };
+    if (!Number.isSafeInteger(settings.minBytes) || settings.minBytes < 0) {
+        throw new Error("compression.minBytes must be a non-negative integer");
+    }
+    if (settings.quality !== undefined && (!Number.isInteger(settings.quality) || settings.quality < 0 || settings.quality > 11)) {
+        throw new Error("compression.quality must be an integer from 0 to 11");
+    }
+    if (settings.encodings !== undefined && (!Array.isArray(settings.encodings)
+        || settings.encodings.length === 0
+        || settings.encodings.some((encoding) => !LAMBDER_ENCODINGS.includes(encoding)))) {
+        throw new Error(`compression.encodings must be a non-empty list of ${LAMBDER_ENCODINGS.map((e) => `"${e}"`).join(", ")}`);
+    }
+    return settings;
+};

package/dist/shared/LambderRequestPayload.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+import type { LambderCompressionOption } from "./LambderCompressionOption.js";
+/** Envelope field carrying the base64 gzip of the payload's JSON. */
+export declare const COMPRESSED_PAYLOAD_FIELD = "payloadGz";
+/** Envelope field carrying the UTF-8 byte length of that JSON before compression. */
+export declare const COMPRESSED_PAYLOAD_BYTES_FIELD = "payloadBytes";
+/** The pair a compressed call sends in place of `payload`. */
+export type LambderCompressedPayload = {
+    [COMPRESSED_PAYLOAD_FIELD]: string;
+    [COMPRESSED_PAYLOAD_BYTES_FIELD]: number;
+};
+/**
+ * Caller-side settings. Only a threshold: the browser's CompressionStream
+ * exposes no quality knob, so there is nothing else to tune.
+ */
+export type LambderRequestCompressionSettings = {
+    minBytes: number;
+};
+export type LambderRequestCompressionOption = LambderCompressionOption<LambderRequestCompressionSettings>;
+/**
+ * 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 declare const DEFAULT_REQUEST_COMPRESSION_SETTINGS: LambderRequestCompressionSettings;
+/**
+ * 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 declare const DEFAULT_MAX_REQUEST_PAYLOAD_BYTES = 20000000;
+/** True when this runtime can compress request payloads (browsers, and Node 18+). */
+export declare const isRequestCompressionAvailable: () => boolean;
+/**
+ * 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 declare const compressPayloadJson: (json: string, minBytes: number) => Promise<LambderCompressedPayload | null>;
+/**
+ * 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 declare const decompressPayloadJson: (payloadGz: string) => Promise<unknown>;