emdash 0.19.0 → 0.21.0

package/src/utils/single-flight-cache.ts

@@ -0,0 +1,194 @@
+/**
+ * Global-scope async value cache with single-flight and poison-immunity.
+ *
+ * Built for the "compute once for the lifetime of the JS global scope, read
+ * on every request" caches (site settings, search-health verification, ...).
+ * That global scope is the process on Node and the isolate on Cloudflare
+ * Workers — this helper is platform-neutral; the hazard it defends against is
+ * specific to workerd but the cache itself is not.
+ *
+ * These caches must coalesce concurrent cold reads into one query — but the
+ * obvious way to do that, caching the in-flight *promise* on a global and
+ * awaiting it from later requests, is unsafe on workerd: if the request that
+ * created the promise is cancelled mid-await (client disconnect, context
+ * teardown), its continuation never runs, so the promise neither resolves nor
+ * rejects. Every later request that awaits that shared promise then hangs
+ * until the isolate is evicted (observed as 524s at the 100s wall, near-zero
+ * CPU). A `.catch`/`.finally` that clears the cache doesn't help — a cancelled
+ * request settles neither way.
+ *
+ * This cache stores the resolved *value* (not a promise) and coalesces via
+ * `initWithLock`: one request becomes the owner and runs `fetch`, everyone
+ * else polls for the published value and never awaits the owner's promise.
+ * A cancelled owner can therefore never strand a waiter — the worst case is
+ * the lock looks held until `deadlineMs`, then the next caller reclaims. The
+ * owner's `fetch` is also anchored (waitUntil) so a cancelled originator's
+ * query still completes and populates the cache, and bounded by
+ * `ownerTimeoutMs` so a genuinely stuck fetch reclaims instead of hanging.
+ *
+ * Invalidation bumps `version`; reads compare against the version captured at
+ * call time and refetch on mismatch.
+ */
+
+import { createInitLock, type InitLock, initWithLock } from "./init-lock.js";
+
+export interface SingleFlightCache<T> {
+	/** Last resolved value, valid only when `hasValue` is true. */
+	value: T | null;
+	/**
+	 * Presence flag, separate from `value` so that falsy/`undefined`/`void`
+	 * results cache correctly (a plain null check can't distinguish "cached
+	 * undefined" from "never fetched").
+	 */
+	hasValue: boolean;
+	/** Invalidation counter; bumped by `invalidateSingleFlightCache`. */
+	version: number;
+	/** The `version` the cached value was fetched at. */
+	valueVersion: number;
+	/** Reclaimable single-flight lock (see init-lock.ts). */
+	lock: InitLock;
+}
+
+export function createSingleFlightCache<T>(): SingleFlightCache<T> {
+	return { value: null, hasValue: false, version: 0, valueVersion: -1, lock: createInitLock() };
+}
+
+/**
+ * Force the next `singleFlightCached` call to refetch. An in-flight owner
+ * fetched at the old version will not publish into the new version, so its
+ * result is ignored by subsequent reads.
+ */
+export function invalidateSingleFlightCache(cache: SingleFlightCache<unknown>): void {
+	cache.version++;
+	cache.hasValue = false;
+	cache.value = null;
+	cache.valueVersion = -1;
+	// Free the single-flight lock so a reader at the new version starts the
+	// refetch immediately instead of waiting out a stale owner's deadline. A
+	// still-running old-version owner can neither publish into the new version
+	// (version gate) nor clobber a new owner (claim gate), so releasing here
+	// is safe; the worst case is one brief duplicate fetch.
+	cache.lock.ownerStartedAt = null;
+}
+
+/**
+ * Headroom between the owner's own timeout and the waiter reclaim deadline.
+ * The reclaim deadline must sit *above* `ownerTimeoutMs` so a slow-but-live
+ * owner times out (and releases the lock) before a waiter would reclaim it —
+ * otherwise a fetch slower than the deadline is superseded before it can
+ * publish, and steady traffic turns that into a self-sustaining stampede.
+ */
+const RECLAIM_HEADROOM_MS = 5_000;
+
+export interface SingleFlightCachedOptions {
+	/**
+	 * Hand the in-flight fetch to the host's lifetime extender (waitUntil via
+	 * `after()`), so a cancelled originating request still drives it to
+	 * completion and populates the cache.
+	 */
+	anchor?: (promise: Promise<void>) => void;
+	/** Reclaim the single-flight lock if the owner holds it past this. */
+	deadlineMs?: number;
+	/** Waiter poll interval. */
+	pollMs?: number;
+	/** Waiter gives up and throws after this long rather than hanging. */
+	maxWaitMs?: number;
+	/**
+	 * Bound the owner's own `fetch`: if it doesn't settle within this, the
+	 * owner rejects (and releases the lock) instead of waiting indefinitely.
+	 * The anchored copy keeps running, so a slow-but-live fetch can still
+	 * publish for a later caller. Omit to leave the owner unbounded.
+	 */
+	ownerTimeoutMs?: number;
+}
+
+/** Boxed cache hit so a `void`/falsy value is still distinguishable from a miss. */
+interface Box<T> {
+	v: T;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(new Error(`singleFlightCached: owner fetch exceeded ${ms}ms`));
+		}, ms);
+		// Settle from the underlying promise (whichever wins the race with the
+		// timer), and always clear the timer so a resolved fetch doesn't leave
+		// a pending timeout holding the isolate alive.
+		promise.then(resolve, reject).finally(() => {
+			clearTimeout(timer);
+		});
+	});
+}
+
+/**
+ * Return the cached value for `cache`, computing it via `fetch` under a
+ * single-flight lock on a miss. Concurrent callers coalesce onto one fetch;
+ * a cancelled owner cannot poison later callers (see file header).
+ */
+export function singleFlightCached<T>(
+	cache: SingleFlightCache<T>,
+	fetch: () => Promise<T>,
+	options: SingleFlightCachedOptions = {},
+): Promise<T> {
+	// Capture the version once: a value published at this version satisfies
+	// this call; an invalidation that lands mid-fetch makes the published
+	// value stale for *later* calls (which captured the newer version) but
+	// still valid for this one.
+	const versionAtCall = cache.version;
+
+	// Ignore a non-positive / non-finite owner timeout rather than letting it
+	// degenerate into an instant-reject (setTimeout coerces NaN/0 to ~0ms).
+	const ownerTimeoutMs =
+		options.ownerTimeoutMs !== undefined &&
+		Number.isFinite(options.ownerTimeoutMs) &&
+		options.ownerTimeoutMs > 0
+			? options.ownerTimeoutMs
+			: undefined;
+
+	// Keep the reclaim deadline above the owner timeout (see RECLAIM_HEADROOM_MS):
+	// the owner's own timeout, not a waiter reclaim, is the primary release.
+	const deadlineMs =
+		ownerTimeoutMs === undefined
+			? options.deadlineMs
+			: Math.max(options.deadlineMs ?? 0, ownerTimeoutMs + RECLAIM_HEADROOM_MS);
+
+	return initWithLock<Box<T>>(
+		cache.lock,
+		() =>
+			cache.hasValue && cache.valueVersion === versionAtCall
+				? // eslint-disable-next-line typescript/no-unsafe-type-assertion -- hasValue gates that `value` holds a real T
+					({ v: cache.value as T } satisfies Box<T>)
+				: null,
+		(isCurrentClaim) => {
+			// The real work, anchored independently so a cancelled owner's
+			// fetch still settles and publishes. Publication is gated on the
+			// claim so a reclaimed slow owner can't clobber the reclaimer's
+			// value (same contract as initWithLock's own callers).
+			const real = (async (): Promise<Box<T>> => {
+				const value = await fetch();
+				if (isCurrentClaim()) {
+					cache.value = value;
+					cache.hasValue = true;
+					cache.valueVersion = versionAtCall;
+				}
+				return { v: value };
+			})();
+			// Anchor the real fetch (not the timeout race): this is what must
+			// survive a cancelled owner and run to publication. initWithLock is
+			// left to manage only the lock; we don't double-anchor.
+			options.anchor?.(
+				real.then(
+					() => undefined,
+					() => undefined,
+				),
+			);
+			return ownerTimeoutMs === undefined ? real : withTimeout(real, ownerTimeoutMs);
+		},
+		{
+			deadlineMs,
+			pollMs: options.pollMs,
+			maxWaitMs: options.maxWaitMs,
+		},
+	).then((box) => box.v);
+}

package/src/widgets/index.ts

@@ -1,4 +1,5 @@
 import { getDb } from "../loader.js";
+import { requestCached } from "../request-cache.js";
 import { getWidgetComponents as getComponentRegistry } from "./components.js";
 import type { Widget, WidgetArea, WidgetRow, WidgetComponentDef } from "./types.js";
 
@@ -22,62 +23,64 @@ export type {
  * row with null widget columns, which we skip when mapping.
  */
 export async function getWidgetArea(name: string): Promise<WidgetArea | null> {
-	const db = await getDb();
-	const rows = await db
-		.selectFrom("_emdash_widget_areas as a")
-		.leftJoin("_emdash_widgets as w", "w.area_id", "a.id")
-		.select([
-			"a.id as a_id",
-			"a.name as a_name",
-			"a.label as a_label",
-			"a.description as a_description",
-			"w.id as w_id",
-			"w.type as w_type",
-			"w.title as w_title",
-			"w.content as w_content",
-			"w.menu_name as w_menu_name",
-			"w.component_id as w_component_id",
-			"w.component_props as w_component_props",
-			"w.area_id as w_area_id",
-			"w.sort_order as w_sort_order",
-			"w.created_at as w_created_at",
-		])
-		.where("a.name", "=", name)
-		.orderBy("w.sort_order", "asc")
-		.execute();
+	return requestCached(`widget-area:${name}`, async () => {
+		const db = await getDb();
+		const rows = await db
+			.selectFrom("_emdash_widget_areas as a")
+			.leftJoin("_emdash_widgets as w", "w.area_id", "a.id")
+			.select([
+				"a.id as a_id",
+				"a.name as a_name",
+				"a.label as a_label",
+				"a.description as a_description",
+				"w.id as w_id",
+				"w.type as w_type",
+				"w.title as w_title",
+				"w.content as w_content",
+				"w.menu_name as w_menu_name",
+				"w.component_id as w_component_id",
+				"w.component_props as w_component_props",
+				"w.area_id as w_area_id",
+				"w.sort_order as w_sort_order",
+				"w.created_at as w_created_at",
+			])
+			.where("a.name", "=", name)
+			.orderBy("w.sort_order", "asc")
+			.execute();
 
-	const first = rows[0];
-	if (!first) return null;
-	const widgets: Widget[] = [];
-	for (const row of rows) {
-		if (row.w_id === null) continue; // area has no widgets (left-join null row)
-		// Left-join makes every w_* column nullable in the type; at runtime
-		// they're all non-null once w_id is (we match on widgets.area_id, so
-		// a widget row always has the not-null columns filled). Cast is the
-		// price of that structural fact.
-		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- left-join row is non-null when w_id is set; see above
-		const widgetRow = {
-			id: row.w_id,
-			type: row.w_type,
-			title: row.w_title,
-			content: row.w_content,
-			menu_name: row.w_menu_name,
-			component_id: row.w_component_id,
-			component_props: row.w_component_props,
-			area_id: row.w_area_id,
-			sort_order: row.w_sort_order,
-			created_at: row.w_created_at,
-		} as WidgetRow;
-		widgets.push(rowToWidget(widgetRow));
-	}
+		const first = rows[0];
+		if (!first) return null;
+		const widgets: Widget[] = [];
+		for (const row of rows) {
+			if (row.w_id === null) continue; // area has no widgets (left-join null row)
+			// Left-join makes every w_* column nullable in the type; at runtime
+			// they're all non-null once w_id is (we match on widgets.area_id, so
+			// a widget row always has the not-null columns filled). Cast is the
+			// price of that structural fact.
+			// eslint-disable-next-line typescript/no-unsafe-type-assertion -- left-join row is non-null when w_id is set; see above
+			const widgetRow = {
+				id: row.w_id,
+				type: row.w_type,
+				title: row.w_title,
+				content: row.w_content,
+				menu_name: row.w_menu_name,
+				component_id: row.w_component_id,
+				component_props: row.w_component_props,
+				area_id: row.w_area_id,
+				sort_order: row.w_sort_order,
+				created_at: row.w_created_at,
+			} as WidgetRow;
+			widgets.push(rowToWidget(widgetRow));
+		}
 
-	return {
-		id: first.a_id,
-		name: first.a_name,
-		label: first.a_label,
-		description: first.a_description ?? undefined,
-		widgets,
-	};
+		return {
+			id: first.a_id,
+			name: first.a_name,
+			label: first.a_label,
+			description: first.a_description ?? undefined,
+			widgets,
+		};
+	});
 }
 
 /**