lambder 7.2.5 → 8.0.2

package/dist/shared/wire/LambderIdempotencyKeyScope.js

@@ -0,0 +1,146 @@
+import { LAMBDER_REFUSAL_CODES } from "./LambderApiRefusal.js";
+/** The outcome of an attempt that ended before anything was sent: it tried nothing. */
+export const IDEMPOTENT_ATTEMPT_NOT_SENT = { ok: false, reason: "notSent" };
+/**
+ * Refusals that answer this request itself, so the same request would get
+ * the same answer again and what the person sends next is a new operation.
+ */
+const REFUSAL_REASONS = new Set(["validation", "notAuthorized", "errorMessage"]);
+/** Answers that never reached the operation: the same request may pass later. */
+const UNTRIED_REASONS = new Set(["sessionExpired", "versionExpired", "payloadTooLarge", "notSent"]);
+/**
+ * Generate an idempotency key for one logical operation. Create it when the
+ * operation begins (a form opens, a draft starts), send the same key on every
+ * attempt of that operation, and generate a new one after a confirmed
+ * success; createIdempotencyKeyScope() does that bookkeeping itself. Uses
+ * crypto.randomUUID when available, else a v4 UUID from getRandomValues,
+ * because randomUUID only exists in secure contexts (plain-http LAN device
+ * testing lacks it).
+ *
+ * A runtime with neither throws rather than using Math.random: the key
+ * scopes the replay record for a logged-out client, so a guessable one hands
+ * that client's stored response to whoever guesses it.
+ */
+export const createIdempotencyKey = () => {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID)
+        return cryptoObj.randomUUID();
+    if (!cryptoObj?.getRandomValues)
+        throw new Error("createIdempotencyKey needs crypto.getRandomValues: an idempotency key must be unguessable, and this runtime offers no random source that is.");
+    const bytes = new Uint8Array(16);
+    cryptoObj.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+/** What a scope's attempts are started through: the class hands it out once, below, so it is reachable from this module alone. */
+let beginAttemptOf;
+/**
+ * One logical operation's rotating idempotency key, from
+ * createIdempotencyKeyScope(). Every attempt of the operation
+ * sends the current key, and the scope moves to a new key once an answer
+ * settles the operation:
+ *
+ * - A success settles it, and so does a key refused as reused for another
+ *   request, since that key can never carry this one.
+ * - A refusal of this request (a rejected input, not authorized, an
+ *   errorMessage) settles it, unless another attempt under the same key is
+ *   still in flight or went unanswered. That attempt may run or have run the
+ *   operation, and guards, validation and rate limits refuse before the
+ *   replay record is claimed, so the refusal of a retry or a double-tap says
+ *   nothing about it. Keeping the key lets the next attempt replay the
+ *   original's answer rather than run again.
+ * - A rate limit, an expired session, a stale version, and an attempt that
+ *   ended before anything was sent keep the key.
+ * - Anything that is not an answer (a network failure, a timeout, a 5xx, a
+ *   crash) keeps the key and marks it as possibly used, and so does a
+ *   duplicate of an original still in flight, unless the scope has another
+ *   attempt of its own still waiting for its answer (a double-tap): that
+ *   attempt is the original, and its answer settles the key, a refusal
+ *   included.
+ *
+ * An answer to a key the scope has already moved past changes nothing: a
+ * slow original answering after the person moved on must not rotate away
+ * the key their current attempt is using.
+ */
+export class LambderIdempotencyKeyScope {
+    #key = createIdempotencyKey();
+    #possiblyUsed = false;
+    /** Attempts under the current key that have not settled yet. */
+    #inFlight = 0;
+    static {
+        beginAttemptOf = (scope) => scope.#beginAttempt();
+    }
+    /** The key for the operation currently in progress. */
+    get current() { return this.#key; }
+    /** Moves on to a new operation by hand, for a caller that settles operations itself. Returns the new key. */
+    rotate() {
+        this.#key = createIdempotencyKey();
+        this.#possiblyUsed = false;
+        this.#inFlight = 0;
+        return this.#key;
+    }
+    /**
+     * Starts one attempt under the current key; the callers do this for
+     * every call handed the scope. Private, and reached through
+     * beginIdempotentAttempt: an attempt started and never settled holds the
+     * in-flight count up, so a refusal would stop moving the key.
+     */
+    #beginAttempt() {
+        const key = this.#key;
+        this.#inFlight += 1;
+        let settled = false;
+        return { key, settle: (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (key !== this.#key)
+                    return;
+                this.#inFlight -= 1;
+                const code = outcome.errorMessage?.code;
+                if (outcome.ok || code === LAMBDER_REFUSAL_CODES.idempotencyKeyReused) {
+                    this.rotate();
+                    return;
+                }
+                // A rate limit refuses before the claim, whatever code a policy's
+                // own message carries, so its status is what names it.
+                if (UNTRIED_REASONS.has(outcome.reason ?? "") || outcome.status === 429 || code === LAMBDER_REFUSAL_CODES.rateLimited)
+                    return;
+                if (REFUSAL_REASONS.has(outcome.reason ?? "") && code !== LAMBDER_REFUSAL_CODES.duplicateInFlight) {
+                    if (!this.#possiblyUsed && this.#inFlight === 0)
+                        this.rotate();
+                    return;
+                }
+                // A duplicate while another attempt of this scope still waits for
+                // its answer: unless an earlier attempt went unanswered (which
+                // marked the key already), the running original is that attempt,
+                // and its own answer settles the key. Marked here, the key would
+                // outlive that answer when it is a refusal, and the corrected
+                // request after it would be refused as a reused key.
+                if (code === LAMBDER_REFUSAL_CODES.duplicateInFlight && this.#inFlight > 0)
+                    return;
+                // No answer, or an original this scope has no attempt waiting
+                // for: the operation may have run under this key.
+                this.#possiblyUsed = true;
+            } };
+    }
+}
+/**
+ * A self-rotating idempotency key for a component or form that performs the
+ * same logical operation repeatedly. Pass the scope itself as the call's
+ * `idempotencyKey`, on LambderCaller or LambderInvokeCaller: every attempt of
+ * one operation (a retry after a dropped connection, a double-tap) sends its
+ * current key, so the server collapses them, and the caller rotates it once
+ * an answer settles the operation (a success, or a refusal of this request),
+ * so the next attempt, a corrected form included, is a new operation.
+ * LambderIdempotencyKeyScope says which answers settle it.
+ *
+ * ```typescript
+ * const submitKey = createIdempotencyKeyScope();
+ * await caller.api("order.create", payload, { idempotencyKey: submitKey });
+ * ```
+ */
+export const createIdempotencyKeyScope = () => new LambderIdempotencyKeyScope();
+/** The attempt a call makes with its idempotencyKey option: a scope's current key, or a plain key with nothing to settle. */
+export const beginIdempotentAttempt = (option) => option instanceof LambderIdempotencyKeyScope ? beginAttemptOf(option) : { key: option, settle: () => { } };

package/dist/shared/wire/LambderInvokeApiId.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `requestContext.apiId` of an event LambderInvokeCaller synthesizes, and
+ * what the server reads to tell a direct invoke from a gateway's request.
+ *
+ * A gateway writes its own id there: API Gateway and a Function URL both
+ * generate theirs as lowercase letters and digits, so no request through one
+ * arrives carrying this hyphenated value, whatever headers it sends. Only a
+ * direct invoke delivers an event whose sender wrote the id, and a direct
+ * invoke is authorized by IAM. Declared in shared because the invoke caller
+ * writes it and the server reads it, and the two must agree byte for byte.
+ */
+export declare const LAMBDER_INVOKE_API_ID = "lambder-invoke";
+/**
+ * The `requestContext.apiId` of a browser-shaped event Lambder synthesizes
+ * (lambder/testing, lambderHandlerTransport): a request standing for one a
+ * gateway delivered, not an invoke. Hyphenated like LAMBDER_INVOKE_API_ID,
+ * so no gateway's event carries it either.
+ *
+ * The server reads it, like the invoke id, as "Lambder's own event builder
+ * wrote this": that builder always delivers a 2.0 event's path decoded, so
+ * the path is not decoded a second time whatever host the request names, a
+ * Function URL's included. A direct invoker that writes it gains nothing: it
+ * writes the whole event, the path included, either way. Declared beside the
+ * invoke id for the same reason: the builder writes it and the server reads
+ * it.
+ */
+export declare const LAMBDER_LOCAL_API_ID = "lambder-local";

package/dist/shared/wire/LambderInvokeApiId.js

@@ -0,0 +1,27 @@
+/**
+ * The `requestContext.apiId` of an event LambderInvokeCaller synthesizes, and
+ * what the server reads to tell a direct invoke from a gateway's request.
+ *
+ * A gateway writes its own id there: API Gateway and a Function URL both
+ * generate theirs as lowercase letters and digits, so no request through one
+ * arrives carrying this hyphenated value, whatever headers it sends. Only a
+ * direct invoke delivers an event whose sender wrote the id, and a direct
+ * invoke is authorized by IAM. Declared in shared because the invoke caller
+ * writes it and the server reads it, and the two must agree byte for byte.
+ */
+export const LAMBDER_INVOKE_API_ID = "lambder-invoke";
+/**
+ * The `requestContext.apiId` of a browser-shaped event Lambder synthesizes
+ * (lambder/testing, lambderHandlerTransport): a request standing for one a
+ * gateway delivered, not an invoke. Hyphenated like LAMBDER_INVOKE_API_ID,
+ * so no gateway's event carries it either.
+ *
+ * The server reads it, like the invoke id, as "Lambder's own event builder
+ * wrote this": that builder always delivers a 2.0 event's path decoded, so
+ * the path is not decoded a second time whatever host the request names, a
+ * Function URL's included. A direct invoker that writes it gains nothing: it
+ * writes the whole event, the path included, either way. Declared beside the
+ * invoke id for the same reason: the builder writes it and the server reads
+ * it.
+ */
+export const LAMBDER_LOCAL_API_ID = "lambder-local";

package/dist/shared/wire/LambderOutcomeAssertions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Two assertions over a call's outcome, for tests.
+ *
+ * An outcome is a discriminated union, so a test that expects a refusal must
+ * narrow before it can read what the refusal carries: check `ok`, branch on
+ * it, check `reason`. Written by hand, the failing case prints "expected
+ * false to be true" and says nothing about what came back, the one thing
+ * worth knowing when a call that should have been refused went through, or
+ * crashed instead.
+ *
+ * These narrow through an `asserts` signature, so the lines after one read
+ * the arm it proved, and they throw a plain Error naming what the outcome
+ * was. No test runner is imported: the same two functions serve vitest, jest
+ * and node:test, from `lambder/testing` over a real server and from
+ * `lambder/mock` over a mock one. Pure and dependency-free, like the outcome
+ * vocabulary they read.
+ *
+ * Typed structurally over `ok` and `reason` rather than over
+ * LambderApiOutcome, so a LambderInvokeOutcome, whose failure side names
+ * other reasons, is narrowed by the same functions and a misspelled reason is
+ * a compile error against whichever union was passed.
+ */
+/** What both callers' outcomes have in common: the discriminant, and a reason on the failure side. */
+type LambderOutcomeShape = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Every reason the failure side of an outcome union can carry. */
+type LambderFailureReasonOf<TOutcome> = TOutcome extends {
+    ok: false;
+    reason: infer TReason;
+} ? TReason : never;
+/**
+ * The failure arms that can carry one of the given reasons, each narrowed to
+ * it. Per arm rather than through Extract: one arm may carry several reasons
+ * (`network`, `timeout`, `server` and `unknown` share theirs), and Extract
+ * would drop that arm for any single one of them.
+ */
+type LambderFailureWithReason<TOutcome, TReason> = TOutcome extends {
+    ok: false;
+    reason: infer TArmReason;
+} ? [TReason & TArmReason] extends [never] ? never : TOutcome & {
+    reason: TReason & TArmReason;
+} : never;
+/** What else a failure is expected to carry, beside its reason. */
+export type LambderExpectedFailure = {
+    /** The refusal's machine-readable code (`errorMessage.code`), e.g. a LAMBDER_REFUSAL_CODES value or the app's own. */
+    code?: string;
+    /** The HTTP status the answer came with. */
+    status?: number;
+};
+/**
+ * Asserts that a call succeeded, and narrows the outcome to its success arm,
+ * so `outcome.payload` reads directly on the next line.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.create", { sku });
+ * assertApiSuccess(outcome);
+ * expect(outcome.payload?.orderId).toBeDefined();
+ * ```
+ */
+export declare function assertApiSuccess<TOutcome extends LambderOutcomeShape>(outcome: TOutcome): asserts outcome is Extract<TOutcome, {
+    ok: true;
+}>;
+/**
+ * Asserts that a call failed, with the given reason when one is named, and
+ * narrows the outcome to the arms that reason can be, so what it carries
+ * (`zodError` after "validation", `response` after an envelope reason,
+ * `error` after the rest) reads directly on the next line.
+ *
+ * ```typescript
+ * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
+ * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * ```
+ */
+export declare function assertApiFailure<TOutcome extends LambderOutcomeShape, TReason extends LambderFailureReasonOf<TOutcome> = LambderFailureReasonOf<TOutcome>>(outcome: TOutcome, reason?: TReason, expected?: LambderExpectedFailure): asserts outcome is LambderFailureWithReason<TOutcome, TReason>;
+export {};

package/dist/shared/wire/LambderOutcomeAssertions.js

@@ -0,0 +1,112 @@
+/**
+ * Two assertions over a call's outcome, for tests.
+ *
+ * An outcome is a discriminated union, so a test that expects a refusal must
+ * narrow before it can read what the refusal carries: check `ok`, branch on
+ * it, check `reason`. Written by hand, the failing case prints "expected
+ * false to be true" and says nothing about what came back, the one thing
+ * worth knowing when a call that should have been refused went through, or
+ * crashed instead.
+ *
+ * These narrow through an `asserts` signature, so the lines after one read
+ * the arm it proved, and they throw a plain Error naming what the outcome
+ * was. No test runner is imported: the same two functions serve vitest, jest
+ * and node:test, from `lambder/testing` over a real server and from
+ * `lambder/mock` over a mock one. Pure and dependency-free, like the outcome
+ * vocabulary they read.
+ *
+ * Typed structurally over `ok` and `reason` rather than over
+ * LambderApiOutcome, so a LambderInvokeOutcome, whose failure side names
+ * other reasons, is narrowed by the same functions and a misspelled reason is
+ * a compile error against whichever union was passed.
+ */
+const MAX_DESCRIBED_VALUE_LENGTH = 300;
+/** A value as it can be printed in an assertion message: JSON, cut short, never throwing over a cyclic one. */
+const describeValue = (value) => {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > MAX_DESCRIBED_VALUE_LENGTH ? `${text.slice(0, MAX_DESCRIBED_VALUE_LENGTH)}...` : text;
+};
+/**
+ * The error a failure carries, which becomes the cause of the assertion's
+ * own: a test runner prints the chain, so an app that crashed under
+ * `lambder/testing` shows the handler's stack under the failed assertion.
+ */
+const errorOf = (outcome) => {
+    const error = outcome.error;
+    return error instanceof Error ? error : undefined;
+};
+/** One line saying what an outcome was, for the message of an assertion it failed. */
+const describeOutcome = (outcome) => {
+    if (outcome.ok)
+        return `a success carrying ${describeValue(outcome.payload)}`;
+    const failure = outcome;
+    const details = [];
+    if (failure.status !== undefined)
+        details.push(`status ${failure.status}`);
+    if (failure.errorMessage !== undefined)
+        details.push(`errorMessage ${describeValue(failure.errorMessage)}`);
+    if (failure.zodError !== undefined)
+        details.push(`zodError ${describeValue(failure.zodError.message)}`);
+    // The error's own message, and its cause when it has one: an in-process
+    // transport reports a handler that threw as a failure whose cause is
+    // what actually threw, and that is the line a test author needs.
+    if (failure.error instanceof Error) {
+        const cause = failure.error.cause instanceof Error ? ` (cause: ${failure.error.cause.message})` : "";
+        details.push(`error "${failure.error.message}"${cause}`);
+    }
+    return `a failure with reason "${failure.reason}"${details.length ? `, ${details.join(", ")}` : ""}`;
+};
+/**
+ * Asserts that a call succeeded, and narrows the outcome to its success arm,
+ * so `outcome.payload` reads directly on the next line.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.create", { sku });
+ * assertApiSuccess(outcome);
+ * expect(outcome.payload?.orderId).toBeDefined();
+ * ```
+ */
+export function assertApiSuccess(outcome) {
+    if (!outcome.ok)
+        throw new Error(`Expected the call to succeed, but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+}
+/**
+ * Asserts that a call failed, with the given reason when one is named, and
+ * narrows the outcome to the arms that reason can be, so what it carries
+ * (`zodError` after "validation", `response` after an envelope reason,
+ * `error` after the rest) reads directly on the next line.
+ *
+ * ```typescript
+ * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
+ * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * ```
+ */
+export function assertApiFailure(outcome, reason, expected = {}) {
+    const wanted = [
+        reason !== undefined ? `reason "${String(reason)}"` : null,
+        expected.code !== undefined ? `code "${expected.code}"` : null,
+        expected.status !== undefined ? `status ${expected.status}` : null,
+    ].filter((part) => part !== null).join(", ");
+    const refuse = () => {
+        throw new Error(`Expected the call to fail${wanted ? ` with ${wanted}` : ""}, but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+    };
+    if (outcome.ok)
+        return refuse();
+    if (reason !== undefined && outcome.reason !== reason)
+        return refuse();
+    if (expected.code !== undefined) {
+        // Only the structured errorMessage carries a code; a plain string has none to match.
+        const errorMessage = outcome.errorMessage;
+        const code = errorMessage && typeof errorMessage === "object" ? errorMessage.code : undefined;
+        if (code !== expected.code)
+            return refuse();
+    }
+    if (expected.status !== undefined && outcome.status !== expected.status)
+        return refuse();
+}

package/dist/shared/wire/LambderRequestPayload.d.ts

@@ -2,27 +2,27 @@
  * 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
+ * sends the payload's JSON as `payloadGz` (gzip bytes, base64) plus
  * `payloadBytes` (its UTF-8 byte length) in place of `payload`, and the
  * server restores it before anything reads the payload. A Node caller
  * (LambderInvokeCaller) sends `payloadBr` instead, Brotli under the same
- * rules; the server accepts either. Everything else in the envelope
- * (apiName, version, token, siteHost, guardInputs, idempotencyKey) stays
- * plain text, so routing, logging and request mocking are unaffected.
+ * rules; the server accepts either. The rest of 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.
+ * Base64 inside the JSON envelope rather than a binary body with
+ * Content-Encoding: API Gateway hands a binary body to Lambda base64-encoded
+ * anyway, so binary saves nothing against Lambda's ~6MB invoke cap while
+ * adding 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.
+ * only gzip and deflate; responses, compressed by Node, 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
+ * `payloadBytes` is not bookkeeping: it bounds the server's decompression,
+ * and the restored length must match it exactly (the guarantee
+ * LambderCompressionCodec gives stored records), so a malicious or truncated
  * body fails instead of expanding without limit.
  */
 import type { LambderCompressionOption, LambderCompressionSettings } from "./LambderCompressionOption.js";
@@ -76,9 +76,8 @@ export declare const DEFAULT_MAX_RESTORED_PAYLOAD_BYTES = 20000000;
  * `compressRequest: true` means "whatever the size", which is a threshold of
  * zero rather than a separate path.
  *
- * Both callers decide this, and the three-line ternary they each wrote is the
- * one place a caller can get the override backwards, so it is written once
- * beside the compressors it feeds.
+ * Both callers decide this, and the override is easy to get backwards, so it
+ * is written once, beside the compressors it feeds.
  */
 export declare const resolveRequestCompressionMinBytes: (compressRequest: boolean | undefined, settings: {
     minBytes: number;
@@ -87,11 +86,10 @@ export declare const resolveRequestCompressionMinBytes: (compressRequest: boolea
 export declare const isRequestCompressionAvailable: () => boolean;
 /**
  * Gzip one payload's JSON for sending, or null when the plain JSON should go
- * instead (see compressPayloadWith for the two rules). The second null
+ * instead (see compressPayloadWith for the two rules). The second rule
  * 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.
+ * original, so sending it would cost CPU on both ends for a bigger request.
  */
 export declare const compressPayloadGzip: (json: string, minBytes: number) => Promise<LambderCompressedGzipPayload | null>;
 /** Request Brotli when `requestCompression: true` on LambderInvokeCaller: the HTTP request threshold, at the quality every other Lambder site uses. */

package/dist/shared/wire/LambderRequestPayload.js

@@ -51,9 +51,8 @@ const compressPayloadWith = async (json, minBytes, field, compress) => {
  * `compressRequest: true` means "whatever the size", which is a threshold of
  * zero rather than a separate path.
  *
- * Both callers decide this, and the three-line ternary they each wrote is the
- * one place a caller can get the override backwards, so it is written once
- * beside the compressors it feeds.
+ * Both callers decide this, and the override is easy to get backwards, so it
+ * is written once, beside the compressors it feeds.
  */
 export const resolveRequestCompressionMinBytes = (compressRequest, settings) => compressRequest === true ? 0
     : compressRequest === false ? null
@@ -62,11 +61,10 @@ export const resolveRequestCompressionMinBytes = (compressRequest, settings) =>
 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 (see compressPayloadWith for the two rules). The second null
+ * instead (see compressPayloadWith for the two rules). The second rule
  * 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.
+ * original, so sending it would cost CPU on both ends for a bigger request.
  */
 export const compressPayloadGzip = (json, minBytes) => compressPayloadWith(json, minBytes, COMPRESSED_PAYLOAD_GZ_FIELD, async (bytes) => {
     const stream = new Blob([bytes]).stream().pipeThrough(new CompressionStream("gzip"));

package/dist/stores/LambderCacheFiller.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a cache's fill runs the loader and keeps its value: `store` writes the
+ * value where the cache keeps it and answers it as stored. Handed to the
+ * cache at the point it fills, so the store can carry what only that point
+ * knows (LambderDdbCache's fill lease).
+ */
+export type LambderCacheLoad<T> = (store: (value: T) => Promise<T>) => Promise<T>;
+/**
+ * getOrSet's contract, shared by every cache here: concurrent calls for one
+ * key in one process share a single load, each handed a parse of its own as
+ * every read is, a loader's failure is the caller's, and the cache's own
+ * failure (a read, a lease, a write) never is.
+ * A cache failure after the loader answered hands that value back uncached,
+ * and one before the loader ran calls the loader directly, so the loader runs
+ * at most once per call whatever breaks. A loader's undefined has nothing to
+ * cache and comes back as it is, so the next call loads again (a loader
+ * answers null to cache "not found"); anything else is answered as the JSON
+ * it was stored as, the filling call included, so it has the shape every
+ * later hit has.
+ *
+ * A write of the key (set, delete, deletePartition) while a fill is loading
+ * wins over the fill: the loader may have read its source before whatever
+ * that write records, so storing its value afterwards would put back what the
+ * write replaced. The write takes the fill out of the in-flight map, a fill
+ * stores only while the map still holds it, and a call arriving after the
+ * write starts a load of its own instead of joining the old one. The old
+ * fill's callers get its value uncached.
+ *
+ * LambderDdbCache and LambderMemoryCache each supply only their read-then-fill
+ * and hold one filler, so the two cannot drift on any of the above.
+ */
+export declare class LambderCacheFiller {
+    private readonly inFlight;
+    /** Opens the log line of a fail-open, naming the cache: "DynamoDB cache failed open in geo". */
+    private readonly failOpenLabel;
+    constructor(failOpenLabel: string);
+    /**
+     * The value for `memoryKey`: `readOrFill` is the cache's own read, and
+     * its fill when the read finds nothing, handed `load` to call (at most
+     * once) at that point with the store that keeps the loader's value.
+     */
+    getOrSet<T>(memoryKey: string, loader: () => Promise<T>, readOrFill: (load: LambderCacheLoad<T>) => Promise<T>): Promise<T>;
+    /** Called by a write of `memoryKey` before it writes: the fill in flight for it stores nothing (see the class comment). */
+    supersedeFill(memoryKey: string): void;
+    /** supersedeFill for every key starting with `memoryKeyPrefix`: one partition's keys, or all of them for "". */
+    supersedeFillsWithPrefix(memoryKeyPrefix: string): void;
+    private failOpen;
+}

package/dist/stores/LambderCacheFiller.js

@@ -0,0 +1,119 @@
+import { asStoredJson } from "./LambderCacheValues.js";
+/**
+ * getOrSet's contract, shared by every cache here: concurrent calls for one
+ * key in one process share a single load, each handed a parse of its own as
+ * every read is, a loader's failure is the caller's, and the cache's own
+ * failure (a read, a lease, a write) never is.
+ * A cache failure after the loader answered hands that value back uncached,
+ * and one before the loader ran calls the loader directly, so the loader runs
+ * at most once per call whatever breaks. A loader's undefined has nothing to
+ * cache and comes back as it is, so the next call loads again (a loader
+ * answers null to cache "not found"); anything else is answered as the JSON
+ * it was stored as, the filling call included, so it has the shape every
+ * later hit has.
+ *
+ * A write of the key (set, delete, deletePartition) while a fill is loading
+ * wins over the fill: the loader may have read its source before whatever
+ * that write records, so storing its value afterwards would put back what the
+ * write replaced. The write takes the fill out of the in-flight map, a fill
+ * stores only while the map still holds it, and a call arriving after the
+ * write starts a load of its own instead of joining the old one. The old
+ * fill's callers get its value uncached.
+ *
+ * LambderDdbCache and LambderMemoryCache each supply only their read-then-fill
+ * and hold one filler, so the two cannot drift on any of the above.
+ */
+export class LambderCacheFiller {
+    inFlight = new Map();
+    /** Opens the log line of a fail-open, naming the cache: "DynamoDB cache failed open in geo". */
+    failOpenLabel;
+    constructor(failOpenLabel) {
+        this.failOpenLabel = failOpenLabel;
+    }
+    /**
+     * The value for `memoryKey`: `readOrFill` is the cache's own read, and
+     * its fill when the read finds nothing, handed `load` to call (at most
+     * once) at that point with the store that keeps the loader's value.
+     */
+    getOrSet(memoryKey, loader, readOrFill) {
+        const current = this.inFlight.get(memoryKey);
+        if (current) {
+            // A parse of its own, as a read hands back: the first call's
+            // object is that caller's to change, and a change must not show
+            // in anyone else's answer.
+            current.joiners += 1;
+            return current.answer.then((value) => current.answerJson === undefined ? value : JSON.parse(current.answerJson));
+        }
+        const leave = () => {
+            // A write may have handed the key to a newer fill meanwhile.
+            if (this.inFlight.get(memoryKey) === shared)
+                this.inFlight.delete(memoryKey);
+        };
+        const shared = {
+            joiners: 0,
+            answer: this.failOpen(loader, readOrFill, () => this.inFlight.get(memoryKey) !== shared).then((value) => {
+                // Out of the map in the same step the text is taken, and
+                // before any caller holds the value: no call joins after
+                // this, and none has changed the value yet.
+                leave();
+                if (shared.joiners > 0) {
+                    // A value JSON cannot hold (a bigint the loader
+                    // answered on a fail-open) goes to every caller as it is.
+                    try {
+                        shared.answerJson = JSON.stringify(value);
+                    }
+                    catch { }
+                }
+                return value;
+            }, (error) => {
+                leave();
+                throw error;
+            }),
+        };
+        this.inFlight.set(memoryKey, shared);
+        return shared.answer;
+    }
+    /** Called by a write of `memoryKey` before it writes: the fill in flight for it stores nothing (see the class comment). */
+    supersedeFill(memoryKey) {
+        this.inFlight.delete(memoryKey);
+    }
+    /** supersedeFill for every key starting with `memoryKeyPrefix`: one partition's keys, or all of them for "". */
+    supersedeFillsWithPrefix(memoryKeyPrefix) {
+        for (const memoryKey of [...this.inFlight.keys()]) {
+            if (memoryKey.startsWith(memoryKeyPrefix))
+                this.inFlight.delete(memoryKey);
+        }
+    }
+    async failOpen(loader, readOrFill, superseded) {
+        let loaderStarted = false;
+        let loaderCompleted = false;
+        let loaderValue;
+        const trackedLoader = async () => {
+            loaderStarted = true;
+            loaderValue = await loader();
+            loaderCompleted = true;
+            return loaderValue;
+        };
+        const load = async (store) => {
+            const value = await trackedLoader();
+            if (value === undefined)
+                return value;
+            if (superseded())
+                return asStoredJson(value);
+            return await store(value);
+        };
+        try {
+            return await readOrFill(load);
+        }
+        catch (error) {
+            if (loaderStarted && !loaderCompleted)
+                throw error;
+            // The key stays out of the line: it is the app's data (an email
+            // address, a user id), and the other engines keep theirs out too.
+            console.error(`${this.failOpenLabel}; the loader's value is handed back uncached.`, error);
+            if (loaderCompleted)
+                return asStoredJson(loaderValue);
+            return asStoredJson(await trackedLoader());
+        }
+    }
+}