emdash 0.17.1 → 0.18.0

package/src/utils/init-lock.ts

@@ -0,0 +1,143 @@
+/**
+ * Reclaimable initialization lock for isolate-lifetime singletons.
+ *
+ * Guards "first request initializes, everyone else waits" sections
+ * (runtime creation, database init) against a workerd failure mode: if the
+ * request that owns the initialization is cancelled mid-await (client
+ * disconnect, context teardown), its continuation — including any `finally`
+ * that would release the lock — never runs. A plain boolean or shared
+ * promise then stays stuck forever and every subsequent request in the
+ * isolate hangs until the platform kills it (observed as 524s at the
+ * 100-second wall limit, with the isolate poisoned until eviction).
+ *
+ * This lock instead records *when* the owner started. Waiters poll — we
+ * deliberately never await a promise created by another request, which
+ * workerd flags — and if the owner has held the lock past `deadlineMs`,
+ * the next waiter assumes the owner is dead, reclaims the lock, and runs
+ * the initialization itself. Waiters also give up after `maxWaitMs` so a
+ * request degrades to an error response rather than hanging.
+ */
+
+export interface InitLock {
+	/** Epoch ms when the current owner claimed the lock, or null when free. */
+	ownerStartedAt: number | null;
+	/**
+	 * Monotonic claim counter identifying the current owner. Release is
+	 * gated on it: a slow owner that finishes after a waiter has reclaimed
+	 * the lock must not clear the reclaimer's claim — that would let yet
+	 * another caller claim the lock and start a third concurrent init.
+	 */
+	generation: number;
+}
+
+export function createInitLock(): InitLock {
+	return { ownerStartedAt: null, generation: 0 };
+}
+
+export interface InitLockOptions {
+	/**
+	 * Reclaim the lock if the owner has held it longer than this. Must be
+	 * comfortably above the slowest legitimate init (cold migrations on a
+	 * contended D1, including the concurrent-migrator wait) — a too-short
+	 * deadline risks two concurrent inits, a too-long one delays recovery
+	 * of a poisoned isolate. Nested locks must compose: an outer lock's
+	 * deadline must exceed the deadline of any lock its init acquires.
+	 */
+	deadlineMs?: number;
+	/** Waiter poll interval. */
+	pollMs?: number;
+	/**
+	 * Give up waiting after this long and throw instead of hanging.
+	 * Defaults to `deadlineMs` plus headroom so a waiter always survives
+	 * long enough to reclaim a dead owner before giving up.
+	 */
+	maxWaitMs?: number;
+	/**
+	 * Called with the in-flight init promise (errors pre-swallowed) so the
+	 * caller can hand it to the host's lifetime extender (waitUntil via
+	 * `after()`). If the owning request is cancelled mid-init, the anchored
+	 * promise keeps the context alive: init completes, populates the cache,
+	 * and the `finally` below releases the lock — preventing the poisoning
+	 * instead of merely recovering from it via reclaim.
+	 */
+	anchor?: (promise: Promise<void>) => void;
+}
+
+const DEFAULT_DEADLINE_MS = 15_000;
+const DEFAULT_POLL_MS = 50;
+const MAX_WAIT_HEADROOM_MS = 15_000;
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Return the cached value if present, otherwise initialize it under the
+ * lock. `init` is responsible for storing the value so that `getCached`
+ * returns it on subsequent calls — waiters re-check `getCached` after the
+ * owner finishes rather than sharing the owner's promise.
+ *
+ * `init` receives an `isCurrentClaim` predicate and must gate its cache
+ * publication on it: a slow init that was reclaimed past the deadline
+ * must not overwrite the value published by the reclaimer (for the
+ * runtime singleton that would orphan the reclaimer's active cron
+ * scheduler). A losing init should also tear down any side resources it
+ * started, since its result will never be published.
+ */
+export async function initWithLock<T>(
+	lock: InitLock,
+	getCached: () => T | null | undefined,
+	init: (isCurrentClaim: () => boolean) => Promise<T>,
+	options?: InitLockOptions,
+): Promise<T> {
+	const deadlineMs = options?.deadlineMs ?? DEFAULT_DEADLINE_MS;
+	const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
+	const maxWaitMs = options?.maxWaitMs ?? deadlineMs + MAX_WAIT_HEADROOM_MS;
+	// Date.now() is deliberate and only works because every loop iteration
+	// awaits: in workerd the clock only advances across I/O, so a sync spin
+	// would never observe the deadline. Don't "optimize" away the sleep.
+	const waitStart = Date.now();
+
+	for (;;) {
+		const cached = getCached();
+		if (cached !== null && cached !== undefined) {
+			return cached;
+		}
+
+		const ownerStartedAt = lock.ownerStartedAt;
+		if (ownerStartedAt === null || Date.now() - ownerStartedAt > deadlineMs) {
+			// Free, or the owner has been gone past the deadline — claim it.
+			// Synchronous between awaits, so two waiters can't both claim.
+			lock.generation += 1;
+			const claim = lock.generation;
+			lock.ownerStartedAt = Date.now();
+			try {
+				// Promise.resolve().then(...) so a synchronous throw from
+				// init still becomes a rejection after the anchor attaches.
+				const isCurrentClaim = () => lock.generation === claim;
+				const initPromise = Promise.resolve().then(() => init(isCurrentClaim));
+				options?.anchor?.(
+					initPromise.then(
+						() => undefined,
+						() => undefined,
+					),
+				);
+				return await initPromise;
+			} finally {
+				// If this request dies mid-init unanchored this never runs;
+				// the next waiter reclaims after deadlineMs instead. Release
+				// only while still the current owner: a reclaimer may have
+				// taken the lock while this (slow) init was running, and
+				// clearing its claim would admit a third concurrent init.
+				if (lock.generation === claim) {
+					lock.ownerStartedAt = null;
+				}
+			}
+		}
+
+		if (Date.now() - waitStart > maxWaitMs) {
+			throw new Error(`initWithLock: timed out after ${maxWaitMs}ms waiting for initialization`);
+		}
+		await sleep(pollMs);
+	}
+}

package/dist/dialect-helpers-BKCvISIQ.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"dialect-helpers-BKCvISIQ.mjs","names":[],"sources":["../src/database/dialect-helpers.ts"],"sourcesContent":["/**\n * Dialect-specific SQL helpers\n *\n * Every function takes a Kysely `db` instance and detects the dialect from\n * the adapter class. No module-level state, no globals, no heuristics —\n * the adapter is the source of truth.\n *\n * This is NOT an ORM abstraction — just targeted helpers for the ~15 places\n * that use raw dialect-specific SQL. Most Kysely schema builder code already\n * works cross-dialect.\n */\n\nimport type { ColumnDataType, Kysely, RawBuilder } from \"kysely\";\nimport { sql } from \"kysely\";\n\nimport type { DatabaseDialectType } from \"../db/adapters.js\";\nimport { validateIdentifier, validateJsonFieldName } from \"./validate.js\";\n\nexport type { DatabaseDialectType };\n\n/**\n * Detect dialect type from a Kysely instance via the adapter class name.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function detectDialect(db: Kysely<any>): DatabaseDialectType {\n\tconst name = db.getExecutor().adapter.constructor.name;\n\tif (name === \"PostgresAdapter\") return \"postgres\";\n\treturn \"sqlite\";\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function isSqlite(db: Kysely<any>): boolean {\n\treturn detectDialect(db) === \"sqlite\";\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function isPostgres(db: Kysely<any>): boolean {\n\treturn detectDialect(db) === \"postgres\";\n}\n\n/**\n * Default timestamp expression for column defaults.\n * Wrapped in parens for use in CREATE TABLE ... DEFAULT (...).\n *\n * sqlite:   (datetime('now'))\n * postgres: CURRENT_TIMESTAMP\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function currentTimestamp(db: Kysely<any>): RawBuilder<string> {\n\tif (isPostgres(db)) {\n\t\treturn sql`CURRENT_TIMESTAMP`;\n\t}\n\treturn sql`(datetime('now'))`;\n}\n\n/**\n * Timestamp expression for use in WHERE clauses and SET expressions.\n * No wrapping parens.\n *\n * sqlite:   datetime('now')\n * postgres: CURRENT_TIMESTAMP\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function currentTimestampValue(db: Kysely<any>): RawBuilder<string> {\n\tif (isPostgres(db)) {\n\t\treturn sql`CURRENT_TIMESTAMP`;\n\t}\n\treturn sql`datetime('now')`;\n}\n\n/**\n * Check if a table exists in the database.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport async function tableExists(db: Kysely<any>, tableName: string): Promise<boolean> {\n\tif (isPostgres(db)) {\n\t\tconst result = await sql<{ exists: boolean }>`\n\t\t\tSELECT EXISTS(\n\t\t\t\tSELECT 1 FROM information_schema.tables\n\t\t\t\tWHERE table_schema = 'public' AND table_name = ${tableName}\n\t\t\t) as exists\n\t\t`.execute(db);\n\t\treturn result.rows[0]?.exists === true;\n\t}\n\n\tconst result = await sql<{ name: string }>`\n\t\tSELECT name FROM sqlite_master\n\t\tWHERE type = 'table' AND name = ${tableName}\n\t`.execute(db);\n\treturn result.rows.length > 0;\n}\n\n/**\n * Check if an index exists in the database.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport async function indexExists(db: Kysely<any>, indexName: string): Promise<boolean> {\n\tif (isPostgres(db)) {\n\t\tconst result = await sql<{ exists: boolean }>`\n\t\t\tSELECT EXISTS(\n\t\t\t\tSELECT 1 FROM pg_indexes\n\t\t\t\tWHERE schemaname = current_schema() AND indexname = ${indexName}\n\t\t\t) as exists\n\t\t`.execute(db);\n\t\treturn result.rows[0]?.exists === true;\n\t}\n\n\tconst result = await sql<{ name: string }>`\n\t\tSELECT name FROM sqlite_master\n\t\tWHERE type = 'index' AND name = ${indexName}\n\t`.execute(db);\n\treturn result.rows.length > 0;\n}\n\n/**\n * Check if a column exists in the database.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport async function columnExists(\n\tdb: Kysely<any>,\n\ttableName: string,\n\tcolumnName: string,\n): Promise<boolean> {\n\tif (isPostgres(db)) {\n\t\tconst result = await sql<{ exists: boolean }>`\n\t\t\tSELECT EXISTS(\n\t\t\t\tSELECT 1 FROM information_schema.columns\n\t\t\t\tWHERE table_schema = current_schema()\n\t\t\t\t\tAND table_name = ${tableName}\n\t\t\t\t\tAND column_name = ${columnName}\n\t\t\t) as exists\n\t\t`.execute(db);\n\t\treturn result.rows[0]?.exists === true;\n\t}\n\n\tconst result = await sql<{ name: string }>`\n\t\tSELECT name FROM pragma_table_info(${tableName})\n\t\tWHERE name = ${columnName}\n\t`.execute(db);\n\treturn result.rows.length > 0;\n}\n\n/**\n * List tables matching a LIKE pattern.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport async function listTablesLike(db: Kysely<any>, pattern: string): Promise<string[]> {\n\tif (isPostgres(db)) {\n\t\tconst result = await sql<{ table_name: string }>`\n\t\t\tSELECT table_name FROM information_schema.tables\n\t\t\tWHERE table_schema = 'public' AND table_name LIKE ${pattern}\n\t\t`.execute(db);\n\t\treturn result.rows.map((r) => r.table_name);\n\t}\n\n\tconst result = await sql<{ name: string }>`\n\t\tSELECT name FROM sqlite_master\n\t\tWHERE type = 'table' AND name LIKE ${pattern}\n\t`.execute(db);\n\treturn result.rows.map((r) => r.name);\n}\n\n/**\n * Column type for binary data.\n *\n * sqlite:   blob\n * postgres: bytea\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function binaryType(db: Kysely<any>): ColumnDataType {\n\tif (isPostgres(db)) {\n\t\treturn \"bytea\";\n\t}\n\treturn \"blob\";\n}\n\n/**\n * SQL expression for extracting a field from a JSON/JSONB column.\n *\n * sqlite:   json_extract(column, '$.path')\n * postgres: column->>'path'\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance\nexport function jsonExtractExpr(db: Kysely<any>, column: string, path: string): string {\n\tvalidateIdentifier(column, \"JSON column name\");\n\tvalidateJsonFieldName(path, \"JSON path\");\n\tif (isPostgres(db)) {\n\t\treturn `${column}->>'${path}'`;\n\t}\n\treturn `json_extract(${column}, '$.${path}')`;\n}\n"],"mappings":";;;;;;;AAwBA,SAAgB,cAAc,IAAsC;AAEnE,KADa,GAAG,aAAa,CAAC,QAAQ,YAAY,SACrC,kBAAmB,QAAO;AACvC,QAAO;;AAIR,SAAgB,SAAS,IAA0B;AAClD,QAAO,cAAc,GAAG,KAAK;;AAI9B,SAAgB,WAAW,IAA0B;AACpD,QAAO,cAAc,GAAG,KAAK;;;;;;;;;AAW9B,SAAgB,iBAAiB,IAAqC;AACrE,KAAI,WAAW,GAAG,CACjB,QAAO,GAAG;AAEX,QAAO,GAAG;;;;;;;;;AAWX,SAAgB,sBAAsB,IAAqC;AAC1E,KAAI,WAAW,GAAG,CACjB,QAAO,GAAG;AAEX,QAAO,GAAG;;;;;AAOX,eAAsB,YAAY,IAAiB,WAAqC;AACvF,KAAI,WAAW,GAAG,CAOjB,SANe,MAAM,GAAwB;;;qDAGM,UAAU;;IAE3D,QAAQ,GAAG,EACC,KAAK,IAAI,WAAW;AAOnC,SAJe,MAAM,GAAqB;;oCAEP,UAAU;GAC3C,QAAQ,GAAG,EACC,KAAK,SAAS;;;;;AA6B7B,eAAsB,aACrB,IACA,WACA,YACmB;AACnB,KAAI,WAAW,GAAG,CASjB,SARe,MAAM,GAAwB;;;;wBAIvB,UAAU;yBACT,WAAW;;IAEhC,QAAQ,GAAG,EACC,KAAK,IAAI,WAAW;AAOnC,SAJe,MAAM,GAAqB;uCACJ,UAAU;iBAChC,WAAW;GACzB,QAAQ,GAAG,EACC,KAAK,SAAS;;;;;AAO7B,eAAsB,eAAe,IAAiB,SAAoC;AACzF,KAAI,WAAW,GAAG,CAKjB,SAJe,MAAM,GAA2B;;uDAEK,QAAQ;IAC3D,QAAQ,GAAG,EACC,KAAK,KAAK,MAAM,EAAE,WAAW;AAO5C,SAJe,MAAM,GAAqB;;uCAEJ,QAAQ;GAC5C,QAAQ,GAAG,EACC,KAAK,KAAK,MAAM,EAAE,KAAK;;;;;;;;AAUtC,SAAgB,WAAW,IAAiC;AAC3D,KAAI,WAAW,GAAG,CACjB,QAAO;AAER,QAAO;;;;;;;;AAUR,SAAgB,gBAAgB,IAAiB,QAAgB,MAAsB;AACtF,oBAAmB,QAAQ,mBAAmB;AAC9C,uBAAsB,MAAM,YAAY;AACxC,KAAI,WAAW,GAAG,CACjB,QAAO,GAAG,OAAO,MAAM,KAAK;AAE7B,QAAO,gBAAgB,OAAO,OAAO,KAAK"}