/** * A small read cache in front of the Brainerce API for storefronts that run on Cloudflare Workers. * * WHY. A storefront on Workers renders on the server, so every page makes API calls from Cloudflare's egress addresses, * which can be shared by many stores and all their shoppers. The API limits requests per address, and without this layer a * dozen page views a minute are enough to get HTTP 429 for the whole site (measured on 2026-11-11: 70 to 80 percent of page * requests failed at 21 requests a second). Two things make it worse by default: the API already marks its public, static * reads (store info, regions, categories, payment and shipping options, ...) with `Cache-Control`, but a Worker's `fetch` * does not use it; and the SDK, on a 429 with `Retry-After`, SLEEPS that long inside the server render and retries once. * * WHAT IT DOES, for GET requests to the API origin only: * - honours the API's own `Cache-Control: max-age` (never longer than {@link MAX_TTL_MS}), keyed by URL and by the request * headers the API varies on, in memory of the running isolate (no platform cache is assumed to exist); * - serves a stale copy (up to the answer's own `stale-while-revalidate` time) when the API fails or answers 429/5xx; * - removes `Retry-After` from a 429 it passes on, so the SDK fails fast instead of sleeping inside a render. * * WHAT IT NEVER DOES: cache a request that carries credentials (`Authorization` or cookies: a customer's own data), a write, * a response without an explicit public `max-age`, or anything for another host. Products, prices, stock, carts and * checkouts carry no `max-age` from the API, so they are always live. * * It deliberately does NOT merge identical requests that are in flight at the same moment: a Worker cannot wait on a promise * that belongs to another request (see the note in the code), and trying it hung a whole isolate under load. * * It is installed only on the Workers runtime (or when `BRAINERCE_READ_CACHE=1`), so a store that runs anywhere else behaves * exactly as before. See `scripts/check-read-cache.mjs`. */ /** The longest an answer is kept fresh, whatever the API says. */ export const MAX_TTL_MS = 5 * 60_000; /** The longest a stale copy may be served when the API fails, whatever the API says. */ export const MAX_STALE_MS = 10 * 60_000; /** Entries kept per isolate; the oldest goes first. */ export const MAX_ENTRIES = 200; /** A larger body is not cached (a catalog page): memory in an isolate is small. */ export const MAX_BODY_BYTES = 256 * 1024; /** The request headers the API's answer can depend on (its `Vary`), part of every cache key. */ const KEY_HEADERS = ['origin', 'accept-language', 'x-brainerce-features', 'accept']; interface Entry { status: number; statusText: string; headers: Array<[string, string]>; body: ArrayBuffer; /** Fresh until. */ freshUntil: number; /** Usable as a fallback until. */ staleUntil: number; } type FetchFn = typeof fetch; export interface ReadCacheOptions { /** The API origin, e.g. `https://api.brainerce.com`. Requests to any other origin pass through untouched. */ apiOrigin: string; now?: () => number; } /** `public, max-age=60, stale-while-revalidate=300` -> `{ maxAge: 60, swr: 300 }`; `null` unless explicitly public. */ export function parseCacheControl(value: string | null): { maxAge: number; swr: number } | null { if (!value) return null; const parts = value .toLowerCase() .split(',') .map((p) => p.trim()); if (parts.includes('no-store') || parts.includes('private') || parts.includes('no-cache')) return null; if (!parts.includes('public')) return null; const num = (name: string) => { const part = parts.find((p) => p.startsWith(`${name}=`)); const n = part ? Number(part.slice(name.length + 1)) : NaN; return Number.isFinite(n) && n >= 0 ? n : null; }; const maxAge = num('max-age'); if (maxAge === null || maxAge === 0) return null; return { maxAge, swr: num('stale-while-revalidate') ?? 0 }; } function requestUrl(input: RequestInfo | URL): string { if (typeof input === 'string') return input; if (input instanceof URL) return input.toString(); return input.url; } function headerOf( input: RequestInfo | URL, init: RequestInit | undefined, name: string ): string | null { const fromInit = init?.headers ? new Headers(init.headers).get(name) : null; if (fromInit !== null) return fromInit; if (typeof input === 'object' && !(input instanceof URL) && 'headers' in input) return input.headers.get(name); return null; } function methodOf(input: RequestInfo | URL, init: RequestInit | undefined): string { const m = init?.method ?? (typeof input === 'object' && !(input instanceof URL) && 'method' in input ? input.method : 'GET'); return m.toUpperCase(); } /** Wraps `baseFetch`. Pure and testable: no global is touched here. */ export function createReadCachingFetch(baseFetch: FetchFn, options: ReadCacheOptions): FetchFn { const now = options.now ?? (() => Date.now()); const cache = new Map(); const toResponse = (e: Entry) => new Response(e.body.slice(0), { status: e.status, statusText: e.statusText, headers: e.headers, }); const remember = (key: string, e: Entry) => { cache.delete(key); cache.set(key, e); while (cache.size > MAX_ENTRIES) { const oldest = cache.keys().next().value; if (oldest === undefined) break; cache.delete(oldest); } }; /** A 429 handed to the SDK without `Retry-After`: it throws at once instead of sleeping inside a render. */ const withoutRetryAfter = (res: Response): Response => { if (res.status !== 429 || !res.headers.has('retry-after')) return res; const headers = new Headers(res.headers); headers.delete('retry-after'); return new Response(res.body, { status: res.status, statusText: res.statusText, headers }); }; const cached: FetchFn = async (input, init) => { const url = requestUrl(input); let parsed: URL; try { parsed = new URL(url); } catch { return baseFetch(input, init); } if (parsed.origin !== options.apiOrigin || methodOf(input, init) !== 'GET') return baseFetch(input, init); // Anything that carries a person's credentials is theirs alone: never shared. if (headerOf(input, init, 'authorization') || headerOf(input, init, 'cookie')) return baseFetch(input, init); const key = [parsed.toString(), ...KEY_HEADERS.map((h) => headerOf(input, init, h) ?? '')].join( '\n' ); const t = now(); const hit = cache.get(key); if (hit && hit.freshUntil > t) return toResponse(hit); // ⛔ No sharing of an in-flight request between two requests. A Worker may not wait on a promise that belongs to ANOTHER // request's I/O: when that request ends (a client that hangs up, a timeout), the promise never settles, and every later // request for the same key waits on it forever, so the whole isolate stops answering. Measured on 2026-11-11: with merging on, // a load test left every request hanging until the isolate was recycled. Only finished, plain data (an ArrayBuffer) is shared. const run = (async (): Promise => { let res: Response | null = null; try { res = await baseFetch(input, init); } catch (error) { if (hit && hit.staleUntil > now()) return toResponse(hit); throw error; } if (res.ok) { const cc = parseCacheControl(res.headers.get('cache-control')); if (cc) { const length = Number(res.headers.get('content-length')); if (!Number.isFinite(length) || length <= MAX_BODY_BYTES) { const body = await res.clone().arrayBuffer(); if (body.byteLength <= MAX_BODY_BYTES) { const at = now(); const ttl = Math.min(cc.maxAge * 1000, MAX_TTL_MS); remember(key, { status: res.status, statusText: res.statusText, headers: [...res.headers.entries()], body, freshUntil: at + ttl, staleUntil: at + Math.min(ttl + cc.swr * 1000, MAX_STALE_MS), }); } } } return res; } // The API is limited or failing: a copy that is still within its stale window is better than an error page. if ((res.status === 429 || res.status >= 500) && hit && hit.staleUntil > now()) return toResponse(hit); return withoutRetryAfter(res); })(); return run; }; return cached; } let installed = false; /** `true` on Cloudflare Workers, or when `BRAINERCE_READ_CACHE=1` (to try it anywhere else). */ export function readCacheWanted(): boolean { if (process.env.BRAINERCE_READ_CACHE === '0') return false; if (process.env.BRAINERCE_READ_CACHE === '1') return true; return typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers'; } /** * Puts the cache in front of the global `fetch`, once per isolate. Called from the server client factory, so it is in place * before the SDK makes its first call. A no-op where {@link readCacheWanted} is false. */ export function installHostedReadCache(apiUrl: string): void { if (installed || !readCacheWanted()) return; let apiOrigin: string; try { apiOrigin = new URL(apiUrl).origin; } catch { return; } installed = true; globalThis.fetch = createReadCachingFetch(globalThis.fetch.bind(globalThis), { apiOrigin }); }