lambder 7.3.1 → 8.0.2

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/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() } : {}),

package/dist/client.d.ts

@@ -20,10 +20,12 @@ export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.j
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, LambderLogListHandler, } from "./client/LambderCaller.js";
-export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderLogListHandler, } from "./client/LambderCaller.js";
+export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
+export type { LambderIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
+export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderAppRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
 export { compressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/wire/LambderRequestPayload.js";

package/dist/client.js

@@ -19,9 +19,10 @@ export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
 export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
+export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
-export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 // A crash described for a caller allowed to see it (the envelope's `crash` field; pure, no Node built-ins).
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 // Request payload compression (browser-safe: gzip via CompressionStream, no Node built-ins).