lambder 7.3.1 → 8.1.1

package/dist/client/LambderReloadLoopBreaker.js

@@ -1,71 +1,115 @@
 /**
  * Stops a stale client from reloading forever.
  *
- * A versionExpired answer means "this client's signature for the endpoint is
- * not the one the server holds", and the ordinary response is to reload and
- * get the current bundle. When the bundle being served is itself the stale
- * one (a frontend deployed with a signature map the server does not match, a
- * cached bundle, a server deploy that failed behind a fresh frontend), the
- * reload brings back the same signature, the same call fails the same way,
- * and the page reloads again, indefinitely.
+ * A versionExpired answer means this client's signature for the endpoint is
+ * not the one the server holds (or its version is below the server's floor),
+ * and the ordinary response is to reload for the current bundle. When the
+ * served bundle is itself stale (a frontend deployed with a signature map the
+ * server does not match, a cached bundle, a server deploy that failed behind
+ * a fresh frontend), the reload brings back the same bundle, the calls fail
+ * the same way, and the page reloads again, indefinitely.
  *
- * The evidence of that loop is a versionExpired for the same endpoint with
- * the same signature shortly after the last one: a bundle that had actually
- * changed the endpoint would carry a different signature. The record lives
- * in sessionStorage, which is per tab and survives a reload, so the new page
- * instance sees what the previous one saw; without sessionStorage (a test, a
- * non-browser runtime) an in-memory record does the same within one page.
+ * The evidence is a versionExpired for a call an earlier load refused within
+ * the window: the same endpoint with the same signature and version. A bundle
+ * that had changed the endpoint would carry a different signature, and a
+ * rebuilt one a different version. Each call is kept with the time it was
+ * refused, and only one refused before this document loaded counts: a call
+ * this page refused itself (a retry, another caller's) has seen no reload
+ * since. Every call refused within the window is kept, not only the latest,
+ * because a stale bundle is usually stale for several endpoints and they
+ * answer in no fixed order: whichever of them answers first on the next load
+ * has to find itself in the record.
  *
- * Once a repeat is confirmed, every versionExpired within the window from
- * the first one counts as a repeat too, whichever endpoint it names: a stale
- * bundle is usually stale for several endpoints, and one reload per endpoint
- * is still a loop, only a slower one. After the window a reload is allowed
- * again, so a client stuck on a stale bundle retries a few times an hour and
- * recovers by itself once the deploy is fixed.
+ * A page asks one versionExpiredHandler at a time. While it runs, the rest of
+ * what the page hears (the other stale endpoints it boots with, a retry,
+ * another caller's) is recorded and answered quietly, since the page is being
+ * asked already. A handler that has returned while the page is still here may
+ * not have reloaded it (a per-call handler that does something else, a reload
+ * cancelled at a beforeunload prompt), so the next versionExpired asks again;
+ * where it did, asking again before the page unloads only repeats the reload
+ * under way. An instance is one page: LambderCaller keeps one at module
+ * scope, shared by every caller the page builds (in a runtime with no page,
+ * every caller of the process).
+ *
+ * Once a repeat is confirmed, every versionExpired within the window counts
+ * as one, whichever endpoint it names, so an endpoint the stale bundle calls
+ * only later does not earn a reload of its own. The window runs from the
+ * first versionExpired recorded, not from the latest. After it a reload is
+ * allowed again, so a client stuck on a stale bundle retries a few times an
+ * hour and recovers once the deploy is fixed.
+ *
+ * The record has to outlive the reload it watches for, so it lives in
+ * sessionStorage, per tab and per origin. Where that does not work (storage
+ * blocked, a runtime with no page) nothing outlives the page: it still asks
+ * one handler at a time, and a stale bundle there reloads as it would without
+ * this class.
  */
 /** How long after the first versionExpired a repeat counts as the same loop. */
 export const RELOAD_LOOP_WINDOW_MS = 5 * 60 * 1000;
 const STORAGE_KEY = "lambder:version-expired";
-const isExpiredRecord = (value) => typeof value === "object" && value !== null
-    && typeof value.apiName === "string"
-    && typeof value.signature === "string"
+const isRefusedCall = (value) => Array.isArray(value) && value.length === 4
+    && typeof value[0] === "string" && typeof value[1] === "string" && typeof value[2] === "string"
+    && typeof value[3] === "number";
+const isVersionExpiredRecord = (value) => typeof value === "object" && value !== null
     && typeof value.at === "number"
-    && typeof value.confirmed === "boolean";
+    && typeof value.confirmed === "boolean"
+    && Array.isArray(value.calls)
+    && value.calls.every(isRefusedCall);
+/** A record from the future (a clock set back) is outside the window rather than inside it forever. */
+const isWithinWindow = (at, now) => now >= at && now - at < RELOAD_LOOP_WINDOW_MS;
 export class LambderReloadLoopBreaker {
-    /** The record when sessionStorage is unavailable; sessionStorage is read first wherever it exists. */
-    memory = null;
-    /**
-     * Records this versionExpired and says whether it repeats a recent one,
-     * in which case the caller must not invoke versionExpiredHandler again.
-     */
-    isRepeat(apiName, signature, now = Date.now()) {
-        const last = this.read();
-        if (last && now - last.at < RELOAD_LOOP_WINDOW_MS && (last.confirmed || (last.apiName === apiName && last.signature === signature))) {
-            // `at` stays the first event's, so the window runs from the start
-            // of the loop rather than being pushed forward by every repeat.
-            this.write({ apiName, signature, at: last.at, confirmed: true });
-            return true;
+    loadedAt;
+    /** Whether the handler this page asked is still running: what the page hears meanwhile stays quiet. */
+    reloadAskPending = false;
+    /** loadedAt: when this document loaded. A call refused before it was refused by an earlier load, with a reload in between. */
+    constructor(loadedAt = performance.timeOrigin) {
+        this.loadedAt = loadedAt;
+    }
+    /** Records this versionExpired and decides what the caller does about it. */
+    recordVersionExpired(apiName, signature, version, now = Date.now()) {
+        const stored = this.read();
+        const record = stored && isWithinWindow(stored.at, now) ? stored : { at: now, confirmed: false, calls: [] };
+        const earlier = record.calls.find(([name, sig, ver]) => name === apiName && sig === signature && ver === version);
+        if (!earlier)
+            record.calls.push([apiName, signature, version, now]);
+        let decision;
+        if (this.reloadAskPending)
+            decision = "alreadyAsked";
+        else if (record.confirmed || (earlier !== undefined && earlier[3] < this.loadedAt))
+            decision = "loopConfirmed";
+        else
+            decision = "askForReload";
+        if (decision === "loopConfirmed")
+            record.confirmed = true;
+        this.write(record);
+        return decision;
+    }
+    /** Runs the ask an askForReload decision calls for; until it settles, every versionExpired is alreadyAsked. */
+    async runReloadAsk(ask) {
+        this.reloadAskPending = true;
+        try {
+            await ask();
+        }
+        finally {
+            this.reloadAskPending = false;
         }
-        this.write({ apiName, signature, at: now, confirmed: false });
-        return false;
     }
     read() {
         try {
-            const raw = globalThis.sessionStorage?.getItem(STORAGE_KEY);
-            if (raw) {
-                const parsed = JSON.parse(raw);
-                if (isExpiredRecord(parsed))
+            const stored = globalThis.sessionStorage?.getItem(STORAGE_KEY);
+            if (stored) {
+                const parsed = JSON.parse(stored);
+                if (isVersionExpiredRecord(parsed))
                     return parsed;
             }
         }
-        catch { /* a private window or blocked storage: the in-memory record stands in */ }
-        return this.memory;
+        catch { /* blocked storage, or a record that is not JSON: read as no record */ }
+        return null;
     }
     write(record) {
-        this.memory = record;
         try {
             globalThis.sessionStorage?.setItem(STORAGE_KEY, JSON.stringify(record));
         }
-        catch { /* same: the in-memory record stands in */ }
+        catch { /* blocked or full: nothing outlives this page */ }
     }
 }

package/dist/client/LambderUploadRunner.d.ts

@@ -0,0 +1,96 @@
+import { type LambderUploadFileFacts, type LambderUploadRule, type LambderUploadRuleVerdict, type LambderUploadTicket } from "../shared/contracts/LambderUploadBucket.js";
+/** Where an upload is, in order. `sentBytes` only moves during `uploading`. */
+export type LambderUploadPhase = "hashing" | "requesting" | "uploading" | "confirming";
+export type LambderUploadProgress = {
+    phase: LambderUploadPhase;
+    sentBytes: number;
+    totalBytes: number;
+};
+export type LambderUploadFailureReason = LambderUploadRuleVerdict
+/** The browser could not read the file (moved, deleted, or a cloud placeholder that never downloaded). */
+ | "fileUnreadable"
+/** The app's ticket endpoint would not issue a ticket. */
+ | "ticketRefused"
+/** Storage answered and said no, for a reason a retry cannot cure. */
+ | "storageRejected"
+/** Storage could not be reached, or kept stalling, through every attempt. */
+ | "networkFailed"
+/** The bytes are stored, and the app's confirm endpoint would not confirm them. */
+ | "confirmRefused" | "cancelled";
+/** How an upload failed: `reason` for a screen to word, the underlying error as `cause`. */
+export declare class LambderUploadError extends Error {
+    readonly reason: LambderUploadFailureReason;
+    constructor(reason: LambderUploadFailureReason, options?: {
+        cause?: unknown;
+        detail?: string;
+    });
+}
+export type LambderUploadRunnerOptions<Reference, Receipt> = {
+    uploadRule: LambderUploadRule;
+    /**
+     * The app's ticket endpoint. `reference` is whatever its confirm endpoint
+     * needs to find this upload again (the id of the record it made), and
+     * means nothing to the runner. `signal` is the upload's own, for the call
+     * to pass on so a cancel stops it too.
+     */
+    requestTicket: (fileFacts: LambderUploadFileFacts, call: {
+        signal: AbortSignal | undefined;
+    }) => Promise<{
+        ticket: LambderUploadTicket;
+        reference: Reference;
+    }>;
+    /** The app's confirm endpoint: the server checks the stored object and answers its record of it. */
+    confirmUpload: (reference: Reference, call: {
+        signal: AbortSignal | undefined;
+    }) => Promise<Receipt>;
+    /** The app's way of forgetting a confirmed upload the person removed again. Without one, discard() does nothing. */
+    discardUpload?: (receipt: Receipt) => Promise<void>;
+    /**
+     * 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.
+     */
+    storageRetry?: {
+        attempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    /**
+     * How long a post may be open and move nothing before it counts as
+     * dropped. Default: 60 seconds. Watched where XMLHttpRequest exists,
+     * which reports a body's progress; a runtime with only fetch posts
+     * unwatched.
+     */
+    stallTimeoutMs?: number;
+};
+export declare class LambderUploadRunner<Reference, Receipt> {
+    private readonly options;
+    private readonly attempts;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly stallTimeoutMs;
+    constructor(options: LambderUploadRunnerOptions<Reference, Receipt>);
+    /** For a file input's `accept`, so the picker only offers what the rule takes. */
+    get acceptedTypes(): string;
+    get maxBytes(): number;
+    /** The rule's verdict on a file, or null when it may be uploaded. Costs nothing, so a screen can ask on drop. */
+    checkFile(file: Blob): LambderUploadRuleVerdict | null;
+    /**
+     * Uploads one file and answers the app's receipt, or throws a
+     * LambderUploadError. Aborting `signal` stops it wherever it is: the
+     * runner's own steps at once, and the app's calls as far as they pass
+     * the signal on.
+     */
+    upload(file: File, { onProgress, signal }?: {
+        onProgress?: (progress: LambderUploadProgress) => void;
+        signal?: AbortSignal;
+    }): 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

@@ -0,0 +1,234 @@
+import { checkUploadRule, } from "../shared/contracts/LambderUploadBucket.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 {
+    reason;
+    constructor(reason, options = {}) {
+        super(options.detail ? `${reason}: ${options.detail}` : reason, { cause: options.cause });
+        this.name = "LambderUploadError";
+        this.reason = reason;
+    }
+}
+/**
+ * How many times one upload asks for a new ticket because storage called the
+ * last one expired. A new ticket is asked for at once and spends no attempt
+ * at storage; the bound is for a clock so far off that every ticket arrives
+ * expired.
+ */
+const TICKET_RENEWAL_LIMIT = 2;
+/** S3's refusals that are the connection's or the service's fault rather than the file's, which its own SDK retries too. */
+const TRANSIENT_STORAGE_CODES = new Set(["RequestTimeout", "SlowDown", "InternalError", "ServiceUnavailable"]);
+export class LambderUploadRunner {
+    options;
+    attempts;
+    baseDelayMs;
+    maxDelayMs;
+    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;
+        this.stallTimeoutMs = options.stallTimeoutMs ?? 60_000;
+    }
+    /** For a file input's `accept`, so the picker only offers what the rule takes. */
+    get acceptedTypes() {
+        return this.options.uploadRule.mimeTypes.join(",");
+    }
+    get maxBytes() {
+        return this.options.uploadRule.maxBytes;
+    }
+    /** The rule's verdict on a file, or null when it may be uploaded. Costs nothing, so a screen can ask on drop. */
+    checkFile(file) {
+        return checkUploadRule(this.options.uploadRule, { mimeType: file.type, byteSize: file.size });
+    }
+    /**
+     * Uploads one file and answers the app's receipt, or throws a
+     * LambderUploadError. Aborting `signal` stops it wherever it is: the
+     * runner's own steps at once, and the app's calls as far as they pass
+     * the signal on.
+     */
+    async upload(file, { onProgress, signal } = {}) {
+        const rejection = this.checkFile(file);
+        if (rejection)
+            throw new LambderUploadError(rejection);
+        const report = (phase, sentBytes = 0) => onProgress?.({ phase, sentBytes, totalBytes: file.size });
+        const stopIfCancelled = () => {
+            if (signal?.aborted)
+                throw new LambderUploadError("cancelled");
+        };
+        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),
+        };
+        stopIfCancelled();
+        const requestTicket = async () => {
+            report("requesting");
+            try {
+                return await this.options.requestTicket(fileFacts, { signal });
+            }
+            catch (cause) {
+                throw new LambderUploadError(signal?.aborted ? "cancelled" : "ticketRefused", { cause });
+            }
+        };
+        let issued = await requestTicket();
+        let failedAttempts = 0;
+        let ticketRenewals = 0;
+        for (;;) {
+            stopIfCancelled();
+            report("uploading");
+            const outcome = await this.post(issued.ticket, file, signal, (sentBytes) => report("uploading", sentBytes));
+            if (outcome.kind === "stored")
+                break;
+            if (outcome.kind === "cancelled")
+                throw new LambderUploadError("cancelled");
+            if (outcome.kind === "rejected") {
+                // An expired ticket needs no wait and costs no attempt, only a
+                // new ticket; any other refusal is the file's, and final.
+                if (!outcome.ticketExpired || ++ticketRenewals > TICKET_RENEWAL_LIMIT)
+                    throw new LambderUploadError("storageRejected", { detail: outcome.detail });
+                issued = await requestTicket();
+                continue;
+            }
+            // The ticket is kept through a network retry, so a flaky
+            // connection does not leave the app a record per attempt.
+            if (++failedAttempts >= this.attempts)
+                throw new LambderUploadError("networkFailed");
+            await this.waitBeforeRetry(failedAttempts, signal);
+        }
+        report("confirming", file.size);
+        try {
+            return await this.options.confirmUpload(issued.reference, { signal });
+        }
+        catch (cause) {
+            throw new LambderUploadError(signal?.aborted ? "cancelled" : "confirmRefused", { cause });
+        }
+    }
+    /** Forgets a confirmed upload through the app's endpoint, when it declared one. */
+    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)
+            return Promise.resolve({ kind: "cancelled" });
+        const form = new FormData();
+        for (const [name, value] of Object.entries(ticket.formFields))
+            form.append(name, value);
+        // Storage ignores every field that comes after the file.
+        form.append("file", file);
+        return typeof XMLHttpRequest === "function"
+            ? postWithXhr(ticket.uploadUrl, form, file.size, this.stallTimeoutMs, signal, onSent)
+            : postWithFetch(ticket.uploadUrl, form, file.size, signal, onSent);
+    }
+}
+/** XMLHttpRequest rather than fetch where it exists: fetch cannot report how much of a request body has been sent. */
+const postWithXhr = (url, form, fileBytes, stallTimeoutMs, signal, onSent) => new Promise((resolve) => {
+    const request = new XMLHttpRequest();
+    let stalled = false;
+    let stallTimer;
+    const watchForStall = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => {
+            stalled = true;
+            request.abort();
+        }, stallTimeoutMs);
+    };
+    const cancel = () => request.abort();
+    const settle = (outcome) => {
+        clearTimeout(stallTimer);
+        signal?.removeEventListener("abort", cancel);
+        resolve(outcome);
+    };
+    request.upload.onprogress = (event) => {
+        watchForStall();
+        // `loaded` counts the form's own framing too, a little over the file.
+        onSent(Math.min(event.loaded, fileBytes));
+    };
+    request.onload = () => {
+        if (request.status >= 200 && request.status < 300)
+            return settle({ kind: "stored" });
+        if (request.status >= 500)
+            return settle({ kind: "unreachable" });
+        settle(rejectedOutcome(request.status, request.responseText));
+    };
+    request.onerror = () => settle({ kind: "unreachable" });
+    request.onabort = () => settle(stalled ? { kind: "unreachable" } : { kind: "cancelled" });
+    signal?.addEventListener("abort", cancel, { once: true });
+    watchForStall();
+    try {
+        request.open("POST", url);
+        request.send(form);
+    }
+    catch {
+        // A URL the browser will not open, or a request it will not send, answers nothing.
+        settle({ kind: "unreachable" });
+    }
+});
+const postWithFetch = async (url, form, fileBytes, signal, onSent) => {
+    let response;
+    try {
+        response = await fetch(url, { method: "POST", body: form, signal });
+    }
+    catch {
+        return signal?.aborted ? { kind: "cancelled" } : { kind: "unreachable" };
+    }
+    if (response.ok) {
+        onSent(fileBytes);
+        return { kind: "stored" };
+    }
+    if (response.status >= 500)
+        return { kind: "unreachable" };
+    return rejectedOutcome(response.status, await response.text().catch(() => ""));
+};
+const XML_ENTITIES = { amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'" };
+const xmlText = (text) => text.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (entity, name) => {
+    if (name[0] !== "#")
+        return XML_ENTITIES[name] ?? entity;
+    const codePoint = Number(name[1]?.toLowerCase() === "x" ? `0${name.slice(1)}` : name.slice(1));
+    return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : entity;
+});
+/**
+ * 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.
+ */
+const rejectedOutcome = (status, body) => {
+    const code = xmlText(/<Code>([^<]*)<\/Code>/.exec(body)?.[1] ?? "") || `HTTP ${status}`;
+    const message = xmlText(/<Message>([^<]*)<\/Message>/.exec(body)?.[1] ?? "");
+    if (TRANSIENT_STORAGE_CODES.has(code))
+        return { kind: "unreachable" };
+    return {
+        kind: "rejected",
+        ticketExpired: code === "AccessDenied" && /expired/i.test(message),
+        detail: message ? `${code}: ${message}` : code,
+    };
+};

package/dist/client/lambderFetchTransport.d.ts

@@ -2,7 +2,10 @@ import type { LambderApiTransport } from "../shared/transport/LambderApiTranspor
 /**
  * The production transport: one POST of the envelope to the API path over
  * fetch, with the cookie and CORS behaviour a browser call needs. The
- * caller's default, built from its isCorsEnabled option.
+ * caller's default, built from its isCorsEnabled option. `cors` defaults to
+ * whether the call's apiPath is on another origin than the page's: a browser
+ * refuses a same-origin mode request to another origin outright, and a
+ * credentialed cross-origin one is what a separate API host needs.
  */
 export declare const lambderFetchTransport: (options?: {
     cors?: boolean;

package/dist/client/lambderFetchTransport.js

@@ -1,20 +1,19 @@
 import { buildTransportEnvelope, LambderTransportFailure } from "../shared/transport/LambderApiTransport.js";
 /**
- * fetch, with one failure worth a better sentence than the platform gives it.
- * A relative apiPath is resolved against the page; outside a page there is no
- * page to resolve it against, so fetch rejects with a URL parse error that
- * arrives at the caller looking like the network is down. The condition is
- * read from the actual failure rather than guessed beforehand, so a runtime
- * that resolves relative URLs some other way is left alone.
+ * fetch, with a clearer error for one failure. Outside a page a relative
+ * apiPath has nothing to resolve against, so fetch rejects with a URL parse
+ * error that reaches the caller looking like the network is down. The
+ * condition is read from the actual failure rather than guessed beforehand,
+ * so a runtime that resolves relative URLs some other way is left alone.
  */
 const fetchOrExplain = async (url, init) => {
     try {
         return await fetch(url, init);
     }
     catch (err) {
-        // Narrow on purpose: only the URL failing to parse, which is what
-        // this is. A transport that rejected for any other reason, a stubbed
-        // one included, keeps its own meaning.
+        // Narrow on purpose: only a URL parse failure is rewritten. A fetch
+        // that rejected for any other reason, a stubbed one included, keeps
+        // its own error.
         const failedToParseUrl = err instanceof TypeError && /failed to parse url|invalid url/i.test(String(err.message));
         if (failedToParseUrl && url.startsWith("/") && typeof globalThis.location?.href !== "string") {
             throw new LambderTransportFailure("protocol", `lambderFetchTransport could not resolve the relative apiPath "${url}": there is no page to resolve it against outside a browser. `
@@ -26,10 +25,32 @@ const fetchOrExplain = async (url, init) => {
 /**
  * The production transport: one POST of the envelope to the API path over
  * fetch, with the cookie and CORS behaviour a browser call needs. The
- * caller's default, built from its isCorsEnabled option.
+ * caller's default, built from its isCorsEnabled option. `cors` defaults to
+ * whether the call's apiPath is on another origin than the page's: a browser
+ * refuses a same-origin mode request to another origin outright, and a
+ * credentialed cross-origin one is what a separate API host needs.
  */
 export const lambderFetchTransport = (options = {}) => async (request) => {
-    const cors = options.cors ?? false;
+    let cors = options.cors;
+    if (cors === undefined) {
+        // Resolved against the page, so a protocol-relative `//api.example.com`
+        // counts as another origin too. Outside a page a relative path
+        // resolves against nothing and an absolute one has no page origin to
+        // match, and neither matters there: a fetch outside a browser does
+        // not enforce the mode.
+        try {
+            cors = new URL(request.apiPath, globalThis.location?.href).origin !== globalThis.location?.origin;
+        }
+        catch {
+            cors = false;
+        }
+    }
+    // The headers this transport sets itself leave the caller's set in any
+    // spelling: fetch merges header names case-insensitively, so a
+    // `content-type` beside the transport's `Content-Type` would join it
+    // ("text/plain, application/json") rather than give way to it.
+    const owned = new Set(['content-type', ...(request.cookies?.length ? ['cookie'] : [])]);
+    const callerHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).filter(([name]) => !owned.has(name.toLowerCase())));
     const response = await fetchOrExplain(request.apiPath, {
         method: 'POST', cache: 'no-cache',
         // Cross-origin API hosts need CORS mode and included credentials.
@@ -37,33 +58,36 @@ export const lambderFetchTransport = (options = {}) => async (request) => {
         credentials: cors ? 'include' : 'same-origin',
         redirect: 'follow', referrerPolicy: 'origin',
         headers: {
-            // The caller's own headers go on first, so the ones this transport
-            // owns cannot be displaced by them, the way the synthesized invoke
-            // event does it. With the spread last, a per-call `Cookie` header
-            // (to carry one extra cookie, say) replaced the whole Cookie
-            // header a jar had just built, and the session went missing with
-            // nothing in the failure pointing at the cause.
-            ...(request.headers ?? {}),
+            // The caller's own headers go on first so they cannot displace the
+            // ones this transport owns (the synthesized invoke event does the
+            // same). With the spread last, a per-call `Cookie` header would
+            // replace the whole Cookie header a jar had just built, and the
+            // session would go missing with nothing pointing at the cause.
+            ...callerHeaders,
             'Content-Type': 'application/json',
-            // The cookies the request is meant to carry, which is how a cookie
-            // jar works over fetch outside a browser: undici sends this
-            // header, and a page cannot (Cookie is a forbidden header name, so
-            // a browser drops it silently and uses its own cookie store, which
-            // is the right answer there). Without it the jar collected every
-            // Set-Cookie and sent none of them back, so a Node script against
-            // a deployed app got its CSRF token filled in and sessionExpired
-            // on every session call.
+            // The cookies the request carries: this is how a cookie jar works
+            // over fetch outside a browser, where undici sends the header. A
+            // page cannot (Cookie is a forbidden header name, so a browser
+            // drops it and uses its own cookie store, which is right there).
+            // Without it a jar would collect every Set-Cookie and send none
+            // back, and a Node script against a deployed app would get
+            // sessionExpired on every session call.
             ...(request.cookies?.length ? { Cookie: request.cookies.join('; ') } : {}),
         },
         body: JSON.stringify(buildTransportEnvelope(request)),
         ...(request.signal ? { signal: request.signal } : {}),
     });
+    // Read here, inside the call, so the caller's timeout and abort cover the
+    // whole answer: fetch resolves on the headers, and a body abandoned while
+    // it downloads would otherwise read as a malformed answer (a server
+    // error) rather than the timeout or abort it was.
+    const body = await response.text();
     return {
         status: response.status,
         statusText: response.statusText,
         header: (name) => response.headers?.get?.(name) ?? null,
-        json: () => response.json(),
-        text: () => response.text(),
+        json: async () => JSON.parse(body),
+        text: async () => body,
         // Set-Cookie is unreadable from a page's script; where the runtime
         // exposes it (Node's fetch), a cookie jar can still consume it.
         ...(typeof response.headers?.getSetCookie === "function" ? { setCookies: response.headers.getSetCookie() } : {}),