lambder 8.1.1 → 8.3.1

package/dist/build/generatedTables.js

@@ -0,0 +1,99 @@
+import { canonicalJson } from "../shared/util/canonicalJson.js";
+import { moduleUrlOf } from "./moduleLocation.js";
+import { writeFileAtomically } from "./writeFileAtomically.js";
+/** Imports the module, finds the instance under its export, and answers what it reports. `generator` names the caller in the errors. */
+export const loadApiOptionEntries = async (location, generator) => {
+    const moduleUrl = moduleUrlOf(location.module);
+    const exportName = location.exportName ?? "default";
+    let namespace;
+    try {
+        namespace = await import(moduleUrl);
+    }
+    catch (err) {
+        throw new Error(`${generator} could not load ${moduleUrl}`, { cause: err });
+    }
+    const source = namespace[exportName];
+    if (typeof source?.apiOptionEntries !== "function") {
+        throw new Error(`${moduleUrl} has no export "${exportName}" that reports API options: name the export holding the instance in exportName`);
+    }
+    return source.apiOptionEntries();
+};
+/** One table of a generated file, read back as data, or null for a file that does not hold it as written. */
+export const readGeneratedTable = (contents, exportName) => {
+    const match = new RegExp(`export const ${exportName}\\s*=\\s*([\\s\\S]*?)\\s+as const\\b`).exec(contents);
+    if (!match)
+        return null;
+    try {
+        const table = JSON.parse(match[1]);
+        return table !== null && typeof table === "object" && !Array.isArray(table) ? table : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** How one table's entries differ from the ones a file held, by name, compared as canonical JSON so key order is not a change. */
+export const nameChangesOf = (current, previous) => {
+    const same = (name) => canonicalJson(current[name]) === canonicalJson(previous[name]);
+    return {
+        changed: Object.keys(current).filter((name) => name in previous && !same(name)).sort(),
+        added: Object.keys(current).filter((name) => !(name in previous)).sort(),
+        removed: Object.keys(previous).filter((name) => !(name in current)).sort(),
+    };
+};
+/** One line per name that moved, marked `~` changed, `+` added or `-` removed, under the table's name. */
+const movedLinesOf = (tableName, changes) => [
+    ...changes.changed.map((name) => `  ~ ${tableName} ${name}`),
+    ...changes.added.map((name) => `  + ${tableName} ${name}`),
+    ...changes.removed.map((name) => `  - ${tableName} ${name}`),
+];
+/** The opening comment of a generated file, one `//` line per line of the header. */
+export const headerLinesOf = (header) => header.split("\n").map((line) => line ? `// ${line}` : "//");
+/**
+ * One table as a statement: its doc comment, the `// prettier-ignore` that
+ * keeps a formatter off the JSON a check reads back, and the table itself,
+ * `as const` with whatever `satisfies` clause the caller gives.
+ */
+export const tableStatementLines = (table) => [
+    `/** ${table.doc} */`,
+    "// prettier-ignore",
+    `export const ${table.name} = ${JSON.stringify(table.value, null, 4)} as const${table.satisfies ? ` satisfies ${table.satisfies}` : ""}${table.semicolon}`,
+];
+/**
+ * The end of a generator's run. With `check`, it answers whether the file
+ * holds what the instance reports and writes nothing. Otherwise it writes
+ * the file unless it already holds these tables, however it is formatted, so
+ * a watcher or an incremental build sees no change where there is none (a
+ * change of header or semicolons shows the next time a table changes).
+ * Either way the lines say what moved.
+ */
+export const settleGeneratedFile = (run) => {
+    const movedLines = run.tables.flatMap((table) => movedLinesOf(table.name, table.changes));
+    const summary = run.tables.map(({ name, count, changes }) => `${name}: ${changes.changed.length} changed, ${changes.added.length} added, ${changes.removed.length} removed (${count - changes.changed.length - changes.added.length} unchanged)`).join("; ");
+    const unchanged = run.readBack && movedLines.length === 0;
+    if (run.check) {
+        if (unchanged)
+            return { ok: true, written: false, lines: [`✓ ${run.name} matches the ${run.held}`] };
+        return {
+            ok: false,
+            written: false,
+            lines: [
+                run.previousText !== null && !run.readBack
+                    ? `✗ ${run.name} does not hold ${run.tablesNoun} as written: regenerate it`
+                    : `✗ ${run.name} is stale: regenerate it`,
+                `  ${summary}`,
+                ...movedLines,
+            ],
+        };
+    }
+    const written = !unchanged;
+    if (written)
+        writeFileAtomically(run.file, run.render(), run.previousText !== null);
+    return {
+        ok: true,
+        written,
+        lines: [
+            written ? `✓ Wrote ${run.name} (${run.held})` : `✓ ${run.name} is up to date (${run.held})`,
+            ...(movedLines.length ? [`  ${summary}`, ...movedLines] : [`  ${run.unmovedLine}`]),
+        ],
+    };
+};

package/dist/build/writeApiContract.d.ts

@@ -47,7 +47,8 @@ export type LambderApiContractFileResult = {
  * written module imports nothing, not even lambder, and exports one type
  * alias, `typeName`. Only the default library's interfaces (Date) are printed
  * by name. A non-generic named type is printed once, as a declaration of its
- * own that the entries refer to.
+ * own that the entries refer to; two that want one name are numbered by where
+ * each is declared, never by the order the APIs were registered in.
  *
  * Anything with no plain form fails the call and names where it sits: a
  * function, a symbol-keyed property, an enum, a class's private member, or a

package/dist/build/writeApiContract.js

@@ -24,7 +24,8 @@ const DIAGNOSTIC_LIMIT = 20;
  * written module imports nothing, not even lambder, and exports one type
  * alias, `typeName`. Only the default library's interfaces (Date) are printed
  * by name. A non-generic named type is printed once, as a declaration of its
- * own that the entries refer to.
+ * own that the entries refer to; two that want one name are numbered by where
+ * each is declared, never by the order the APIs were registered in.
  *
  * Anything with no plain form fails the call and names where it sits: a
  * function, a symbol-keyed property, an enum, a class's private member, or a

package/dist/build/writeApiGuardParams.d.ts

@@ -0,0 +1,60 @@
+import type { LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderNameChanges } from "./generatedTables.js";
+export type LambderApiGuardParamsFileOptions = {
+    /**
+     * The module that exports the instance, usually the server's entry: a
+     * path relative to the working directory, or a file URL. It is imported
+     * in this process, so a TypeScript module needs the process's loader
+     * (`tsx`, `node --import tsx`), as the generator script itself does.
+     */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The guard whose parameters the file holds, as the server declares it. A name the server declares no guard under throws. */
+    guard: string;
+    /** The TypeScript module to write, exporting `guardParams`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk holds what the instance reports now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiGuardParams() and the guard. */
+    header?: string;
+    /** End the generated statement with a semicolon. Default: true. The table itself is JSON, double quotes included, whatever the project's style: that is what lets a check read it back. */
+    semicolons?: boolean;
+};
+export type LambderApiGuardParamsFileResult = {
+    /** False when a check found the file stale or unreadable. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** True when the file was (re)written; a file that already holds this table is left untouched, however it is formatted. */
+    written: boolean;
+    /** How many APIs declare the guard. */
+    count: number;
+    /** Which APIs moved against the file that was on disk. */
+    changes: LambderNameChanges;
+    /** What happened, as lines to print: a summary, then one line per name that moved. */
+    lines: string[];
+};
+/**
+ * Writes one guard's parameters as a module of plain data, or checks the one
+ * on disk, and says which APIs moved.
+ *
+ * ```ts
+ * import { writeApiGuardParams } from "lambder/build";
+ *
+ * const result = await writeApiGuardParams({
+ *     module: "server/src/index.ts",
+ *     exportName: "lambder",
+ *     guard: "store",
+ *     file: "web/src/generated/storeGuardParams.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * ```
+ *
+ * The module exports `guardParams`, `as const`, so a client reads its types
+ * straight off it: `keyof typeof guardParams` is the APIs behind the guard,
+ * and `(typeof guardParams)[K]` the literal API K declared, `true` for a
+ * guard named without a parameter (the string and list forms). A parameter
+ * that is not plain data fails the write, as it does for writeApiOptions.
+ */
+export declare const writeApiGuardParams: (options: LambderApiGuardParamsFileOptions) => Promise<LambderApiGuardParamsFileResult>;

package/dist/build/writeApiGuardParams.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { apiGuardParam } from "../shared/wire/LambderApiOptionEntries.js";
+import { headerLinesOf, loadApiOptionEntries, nameChangesOf, readGeneratedTable, settleGeneratedFile, tableStatementLines, } from "./generatedTables.js";
+/*
+ * One guard's parameters as a generated module a browser may carry: for each
+ * API that declares the guard, the parameter it gives it, and nothing else
+ * about any API.
+ *
+ * The file writeApiOptions writes holds every declaration, because a mock
+ * and a test need every declaration. A screen that decides whether to offer
+ * a control by the permission an endpoint's guard asks needs one guard's
+ * parameter, and a browser that imports the whole table as a value carries
+ * every API name, every mode and every guard's parameter, a reviewer's
+ * reason beside an open endpoint included. This is the least that screen
+ * needs: the names of the APIs behind the guard (which the client calls, so
+ * its own code names them already) and what each asks.
+ */
+const TABLE_NAME = "guardParams";
+const defaultHeader = (guard) => [
+    "Generated by writeApiGuardParams() from lambder/build. Do not edit.",
+    "",
+    `The parameter each API the server guards with "${guard}" gives that guard,`,
+    "and nothing else about any API: what a client decides with it, without",
+    "carrying the server's other declarations.",
+].join("\n");
+/**
+ * Writes one guard's parameters as a module of plain data, or checks the one
+ * on disk, and says which APIs moved.
+ *
+ * ```ts
+ * import { writeApiGuardParams } from "lambder/build";
+ *
+ * const result = await writeApiGuardParams({
+ *     module: "server/src/index.ts",
+ *     exportName: "lambder",
+ *     guard: "store",
+ *     file: "web/src/generated/storeGuardParams.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * ```
+ *
+ * The module exports `guardParams`, `as const`, so a client reads its types
+ * straight off it: `keyof typeof guardParams` is the APIs behind the guard,
+ * and `(typeof guardParams)[K]` the literal API K declared, `true` for a
+ * guard named without a parameter (the string and list forms). A parameter
+ * that is not plain data fails the write, as it does for writeApiOptions.
+ */
+export const writeApiGuardParams = async (options) => {
+    const file = resolve(options.file);
+    const entries = await loadApiOptionEntries(options, "writeApiGuardParams");
+    if (!Object.prototype.hasOwnProperty.call(entries.guards, options.guard)) {
+        const declared = Object.keys(entries.guards);
+        throw new Error(`writeApiGuardParams: the server declares no guard "${options.guard}" (it declares ${declared.length ? declared.map((name) => `"${name}"`).join(", ") : "none"}).`);
+    }
+    const params = {};
+    for (const name of Object.keys(entries.apis).sort()) {
+        const param = apiGuardParam(entries.apis, name, options.guard);
+        if (param !== undefined)
+            params[name] = param;
+    }
+    const previousText = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const previous = previousText === null ? null : readGeneratedTable(previousText, TABLE_NAME);
+    const changes = nameChangesOf(params, previous ?? {});
+    const count = Object.keys(params).length;
+    const settled = settleGeneratedFile({
+        name: options.file, file, check: options.check, previousText, readBack: previous !== null,
+        tables: [{ name: TABLE_NAME, count, changes }],
+        held: `${count} APIs guarded by "${options.guard}"`,
+        tablesNoun: "the table",
+        unmovedLine: "no parameters changed",
+        render: () => [
+            ...headerLinesOf(options.header ?? defaultHeader(options.guard)),
+            "",
+            ...tableStatementLines({
+                name: TABLE_NAME,
+                doc: `The parameter each API guarded by "${options.guard}" gives it: the value as declared, or true for the guard named without one.`,
+                value: params,
+                semicolon: options.semicolons === false ? "" : ";",
+            }),
+            "",
+        ].join("\n"),
+    });
+    return { ...settled, file, count, changes };
+};

package/dist/build/writeApiOptions.d.ts

@@ -0,0 +1,68 @@
+import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
+import type { LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderNameChanges } from "./generatedTables.js";
+type TableKey = keyof LambderApiOptionEntries;
+export type LambderApiOptionsFileOptions = {
+    /**
+     * The module that exports the instance, usually the server's entry: a
+     * path relative to the working directory, or a file URL. It is imported
+     * in this process, so a TypeScript module needs the process's loader
+     * (`tsx`, `node --import tsx`), as the generator script itself does.
+     */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The TypeScript module to write, exporting `apiOptions`, `rateLimitPolicies` and `guardDeclarations`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk holds what the instance reports now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiOptions(). */
+    header?: string;
+    /** End the generated statements with semicolons. Default: true. The tables themselves are JSON, double quotes included, whatever the project's style: that is what lets a check read them back. */
+    semicolons?: boolean;
+};
+export type LambderApiOptionsFileResult = {
+    /** False when a check found the file stale or unreadable. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** True when the file was (re)written; a file that already holds these tables is left untouched, however it is formatted. */
+    written: boolean;
+    /** How many APIs, policies and guards the tables hold. */
+    counts: Record<TableKey, number>;
+    /** What moved, per table, against the file that was on disk. */
+    changes: Record<TableKey, LambderNameChanges>;
+    /** What happened, as lines to print: a summary, then one line per name that moved. */
+    lines: string[];
+};
+/** The tables a generated file holds, read back as data, or null for a file that does not hold all three as written (never written, or rewritten by hand). */
+export declare const readOptionTables: (contents: string) => LambderApiOptionEntries | null;
+/**
+ * Writes the declared options of an app's APIs as a module of plain data, or
+ * checks the one on disk, and says which APIs, policies and guards moved.
+ *
+ * Call it from a generator script beside writeApiSignatures, naming the
+ * module that exports the app's instance:
+ *
+ * ```ts
+ * import { writeApiOptions } from "lambder/build";
+ *
+ * const result = await writeApiOptions({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiOptions.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * The tables are compared as the data the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it is neither
+ * stale nor rewritten, and a file whose data is current is left as it is.
+ * There is no fresh-process check: nothing here is digested, so nothing can
+ * differ per process. A module that does not load, an export that is not an
+ * instance, or a guard parameter that is not plain data throws.
+ */
+export declare const writeApiOptions: (options: LambderApiOptionsFileOptions) => Promise<LambderApiOptionsFileResult>;
+export {};

package/dist/build/writeApiOptions.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { headerLinesOf, loadApiOptionEntries, nameChangesOf, readGeneratedTable, settleGeneratedFile, tableStatementLines, } from "./generatedTables.js";
+/*
+ * The declared options of an app's APIs as a generated module of plain data:
+ * every API's mode and its guards, rateLimit and idempotency options as
+ * written, every rate-limit policy less its key handler, and every guard's
+ * input mode, session flag and place in the call. The contract already
+ * carries the options as types; this is the same fact as a value, for the
+ * code that decides something at runtime with it: a mock restating the
+ * server's declarations, a test walking the public surface. Neither imports
+ * the server for it. The file names every endpoint, so a production bundle
+ * imports none of it: a screen that gates on a guard reads that guard's
+ * parameters alone (writeApiGuardParams).
+ *
+ * Plain data by construction: the instance refuses to report a guard
+ * parameter that is code or a class instance (see Lambder.apiOptionEntries),
+ * a policy's key handler is reduced to `per: "custom"`, and a guard's schema
+ * to its input mode. No secret can reach the file, because nothing that could
+ * hold one is written.
+ */
+const DEFAULT_HEADER = [
+    "Generated by writeApiOptions() from lambder/build. Do not edit.",
+    "",
+    "Every API the server registers with its declared options, every rate-limit",
+    "policy less its key handler, and every guard's input mode: the server's",
+    "declarations as plain data, for the code that decides something with them",
+    "without importing the server.",
+].join("\n");
+/** The three tables the module exports, in the order they are written. */
+const TABLES = [
+    { name: "apiOptions", key: "apis", type: "LambderApiOptionEntry", doc: "Every API the server registers: its mode and its guards, rateLimit and idempotency options as written." },
+    { name: "rateLimitPolicies", key: "rateLimitPolicies", type: "LambderRateLimitPolicyEntry", doc: "Every rate-limit policy the server declares, its key reduced to what it counts: an address, a session, or a key the app derives (\"custom\")." },
+    { name: "guardDeclarations", key: "guards", type: "LambderGuardDeclarationEntry", doc: "Every guard the server declares: how it is fed, whether it needs a session, and when it runs." },
+];
+/** The tables a generated file holds, read back as data, or null for a file that does not hold all three as written (never written, or rewritten by hand). */
+export const readOptionTables = (contents) => {
+    const tables = {};
+    for (const table of TABLES) {
+        const read = readGeneratedTable(contents, table.name);
+        if (!read)
+            return null;
+        tables[table.key] = read;
+    }
+    return tables;
+};
+const renderOptionsFile = (entries, options) => {
+    const semicolon = options.semicolons === false ? "" : ";";
+    return [
+        ...headerLinesOf(options.header ?? DEFAULT_HEADER),
+        `import type { ${TABLES.map((table) => table.type).join(", ")} } from "lambder/client"${semicolon}`,
+        ...TABLES.flatMap((table) => [
+            "",
+            ...tableStatementLines({ name: table.name, doc: table.doc, value: entries[table.key], satisfies: `Record<string, ${table.type}>`, semicolon }),
+        ]),
+        "",
+    ].join("\n");
+};
+/**
+ * Writes the declared options of an app's APIs as a module of plain data, or
+ * checks the one on disk, and says which APIs, policies and guards moved.
+ *
+ * Call it from a generator script beside writeApiSignatures, naming the
+ * module that exports the app's instance:
+ *
+ * ```ts
+ * import { writeApiOptions } from "lambder/build";
+ *
+ * const result = await writeApiOptions({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiOptions.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * The tables are compared as the data the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it is neither
+ * stale nor rewritten, and a file whose data is current is left as it is.
+ * There is no fresh-process check: nothing here is digested, so nothing can
+ * differ per process. A module that does not load, an export that is not an
+ * instance, or a guard parameter that is not plain data throws.
+ */
+export const writeApiOptions = async (options) => {
+    const file = resolve(options.file);
+    const entries = await loadApiOptionEntries(options, "writeApiOptions");
+    const previousText = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const previous = previousText === null ? null : readOptionTables(previousText);
+    const changes = Object.fromEntries(TABLES.map((table) => [table.key, nameChangesOf(entries[table.key], previous?.[table.key] ?? {})]));
+    const counts = Object.fromEntries(TABLES.map((table) => [table.key, Object.keys(entries[table.key]).length]));
+    const settled = settleGeneratedFile({
+        name: options.file, file, check: options.check, previousText, readBack: previous !== null,
+        tables: TABLES.map((table) => ({ name: table.name, count: counts[table.key], changes: changes[table.key] })),
+        held: `${counts.apis} APIs, ${counts.rateLimitPolicies} policies, ${counts.guards} guards`,
+        tablesNoun: "the three tables",
+        unmovedLine: "no options changed",
+        render: () => renderOptionsFile(entries, options),
+    });
+    return { ...settled, file, counts, changes };
+};

package/dist/build.d.ts

@@ -2,13 +2,19 @@
  * Build entry point (`import ... from "lambder/build"`).
  *
  * What a generator script runs at build time to write the files a deployment
- * ships: the signature file both sides read, from the app's own instance, and
- * the contract a client compiles against, from the server's sources. Node-only
- * and imported by nothing else in the package, so no deployment or bundle
- * carries it.
+ * ships: the signature file both sides read, the declared options as plain
+ * data, and one guard's parameters as the least a browser needs of them, all
+ * from the app's own instance; and the contract a client compiles against,
+ * from the server's sources. Node-only and imported by nothing else
+ * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export type { LambderApiSignatureSource, LambderApiSignatureFileOptions, LambderApiSignatureFileResult, } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
 export type { LambderApiContractFileOptions, LambderApiContractFileResult, } from "./build/writeApiContract.js";
+export { writeApiOptions } from "./build/writeApiOptions.js";
+export type { LambderApiOptionsFileOptions, LambderApiOptionsFileResult, } from "./build/writeApiOptions.js";
+export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
+export type { LambderApiGuardParamsFileOptions, LambderApiGuardParamsFileResult, } from "./build/writeApiGuardParams.js";
+export type { LambderApiOptionsSource, LambderNameChanges } from "./build/generatedTables.js";
 export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -2,10 +2,13 @@
  * Build entry point (`import ... from "lambder/build"`).
  *
  * What a generator script runs at build time to write the files a deployment
- * ships: the signature file both sides read, from the app's own instance, and
- * the contract a client compiles against, from the server's sources. Node-only
- * and imported by nothing else in the package, so no deployment or bundle
- * carries it.
+ * ships: the signature file both sides read, the declared options as plain
+ * data, and one guard's parameters as the least a browser needs of them, all
+ * from the app's own instance; and the contract a client compiles against,
+ * from the server's sources. Node-only and imported by nothing else
+ * in the package, so no deployment or bundle carries it.
  */
 export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
+export { writeApiOptions } from "./build/writeApiOptions.js";
+export { writeApiGuardParams } from "./build/writeApiGuardParams.js";

package/dist/client/LambderUploadRunner.d.ts

@@ -48,10 +48,11 @@ export type LambderUploadRunnerOptions<Reference, Receipt> = {
     /**
      * How storage is tried again when it cannot be reached, stalls, or answers
      * a failure a retry can cure (a 5xx, RequestTimeout, SlowDown). Each wait
-     * is a random time between `baseDelayMs` and a ceiling that doubles with
-     * every failed attempt, never past `maxDelayMs`, so many browsers dropped
-     * together do not come back in step. Default: 4 attempts, waits from one
-     * second to 15.
+     * is `baseDelayMs` plus a random share of a ceiling that starts at
+     * `baseDelayMs` and doubles with every failed attempt, the whole never
+     * past `maxDelayMs` (the ladder of LambderBackoffTimer), so many browsers
+     * dropped together do not come back in step, not even the first time.
+     * Default: 4 attempts, waits from one second to 15.
      */
     storageRetry?: {
         attempts?: number;
@@ -69,8 +70,8 @@ export type LambderUploadRunnerOptions<Reference, Receipt> = {
 export declare class LambderUploadRunner<Reference, Receipt> {
     private readonly options;
     private readonly attempts;
-    private readonly baseDelayMs;
-    private readonly maxDelayMs;
+    /** The ladder one upload's waits climb; each upload() builds a timer of its own from it, so two uploads never share a count. */
+    private readonly backoff;
     private readonly stallTimeoutMs;
     constructor(options: LambderUploadRunnerOptions<Reference, Receipt>);
     /** For a file input's `accept`, so the picker only offers what the rule takes. */
@@ -90,7 +91,6 @@ export declare class LambderUploadRunner<Reference, Receipt> {
     }): Promise<Receipt>;
     /** Forgets a confirmed upload through the app's endpoint, when it declared one. */
     discard(receipt: Receipt): Promise<void>;
-    private waitBeforeRetry;
     /** One post of the file to storage. Never throws: every ending is an outcome. */
     private post;
 }

package/dist/client/LambderUploadRunner.js

@@ -1,4 +1,5 @@
 import { checkUploadRule, } from "../shared/contracts/LambderUploadBucket.js";
+import { LambderBackoffTimer } from "../shared/util/LambderBackoffTimer.js";
 import { sha256Base64Of } from "../shared/util/LambderTextDigest.js";
 /** How an upload failed: `reason` for a screen to word, the underlying error as `cause`. */
 export class LambderUploadError extends Error {
@@ -21,14 +22,16 @@ const TRANSIENT_STORAGE_CODES = new Set(["RequestTimeout", "SlowDown", "Internal
 export class LambderUploadRunner {
     options;
     attempts;
-    baseDelayMs;
-    maxDelayMs;
+    /** The ladder one upload's waits climb; each upload() builds a timer of its own from it, so two uploads never share a count. */
+    backoff;
     stallTimeoutMs;
     constructor(options) {
         this.options = options;
         this.attempts = Math.max(1, options.storageRetry?.attempts ?? 4);
-        this.baseDelayMs = options.storageRetry?.baseDelayMs ?? 1_000;
-        this.maxDelayMs = options.storageRetry?.maxDelayMs ?? 15_000;
+        const baseDelayMs = options.storageRetry?.baseDelayMs ?? 1_000;
+        const maxDelayMs = options.storageRetry?.maxDelayMs ?? 15_000;
+        // A longest wait below the shortest is every wait at the shortest.
+        this.backoff = { baseMs: baseDelayMs, maxMs: Math.max(baseDelayMs, maxDelayMs) };
         this.stallTimeoutMs = options.stallTimeoutMs ?? 60_000;
     }
     /** For a file input's `accept`, so the picker only offers what the rule takes. */
@@ -59,18 +62,16 @@ export class LambderUploadRunner {
         };
         stopIfCancelled();
         report("hashing");
-        let bytes;
-        try {
-            bytes = new Uint8Array(await file.arrayBuffer());
-        }
-        catch (cause) {
-            throw new LambderUploadError("fileUnreadable", { cause });
-        }
         const fileFacts = {
             fileName: file.name,
             mimeType: file.type,
             byteSize: file.size,
-            sha256Base64: await sha256Base64Of(bytes),
+            // Read straight into the digest, never into a variable: the buffer
+            // is the size of the file, and a local would keep it through
+            // every await of the upload that follows.
+            sha256Base64: await sha256Base64Of(new Uint8Array(await file.arrayBuffer().catch((cause) => {
+                throw new LambderUploadError("fileUnreadable", { cause });
+            }))),
         };
         stopIfCancelled();
         const requestTicket = async () => {
@@ -83,6 +84,7 @@ export class LambderUploadRunner {
             }
         };
         let issued = await requestTicket();
+        const backoff = new LambderBackoffTimer(this.backoff);
         let failedAttempts = 0;
         let ticketRenewals = 0;
         for (;;) {
@@ -105,7 +107,10 @@ export class LambderUploadRunner {
             // connection does not leave the app a record per attempt.
             if (++failedAttempts >= this.attempts)
                 throw new LambderUploadError("networkFailed");
-            await this.waitBeforeRetry(failedAttempts, signal);
+            // The wait rejects only for the signal: nothing else cancels it.
+            await backoff.wait(signal).catch((cause) => {
+                throw new LambderUploadError("cancelled", { cause });
+            });
         }
         report("confirming", file.size);
         try {
@@ -119,22 +124,6 @@ export class LambderUploadRunner {
     async discard(receipt) {
         await this.options.discardUpload?.(receipt);
     }
-    waitBeforeRetry(failedAttempts, signal) {
-        const ceiling = Math.max(this.baseDelayMs, Math.min(this.baseDelayMs * 2 ** (failedAttempts - 1), this.maxDelayMs));
-        return new Promise((resolve, reject) => {
-            if (signal?.aborted)
-                return reject(new LambderUploadError("cancelled"));
-            const cancel = () => {
-                clearTimeout(timer);
-                reject(new LambderUploadError("cancelled"));
-            };
-            const timer = setTimeout(() => {
-                signal?.removeEventListener("abort", cancel);
-                resolve();
-            }, this.baseDelayMs + Math.random() * (ceiling - this.baseDelayMs));
-            signal?.addEventListener("abort", cancel, { once: true });
-        });
-    }
     /** One post of the file to storage. Never throws: every ending is an outcome. */
     post(ticket, file, signal, onSent) {
         if (signal?.aborted)
@@ -218,8 +207,10 @@ const xmlText = (text) => text.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (entity, na
 /**
  * Storage explains a refusal in XML, `<Error><Code/><Message/></Error>`,
  * read here without a DOM so the runner works wherever fetch does. A
- * transient code is tried again like a dropped connection, and an expired
- * ticket is the one refusal a new ticket cures.
+ * transient code is tried again like a dropped connection. An expired ticket
+ * is the one refusal a new ticket cures, and so is ExpiredToken: the
+ * temporary credentials that signed the ticket ran out before it did, and
+ * the next one is signed with fresh ones.
  */
 const rejectedOutcome = (status, body) => {
     const code = xmlText(/<Code>([^<]*)<\/Code>/.exec(body)?.[1] ?? "") || `HTTP ${status}`;
@@ -228,7 +219,7 @@ const rejectedOutcome = (status, body) => {
         return { kind: "unreachable" };
     return {
         kind: "rejected",
-        ticketExpired: code === "AccessDenied" && /expired/i.test(message),
+        ticketExpired: code === "ExpiredToken" || (code === "AccessDenied" && /expired/i.test(message)),
         detail: message ? `${code}: ${message}` : code,
     };
 };