@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/dist/sqlite-worker.js

@@ -0,0 +1,439 @@
+import { a as renderOrderSql, i as projectedDataSql, l as resolveRelations, n as openDb, o as renderWhereSql, r as project, s as reviveRow, u as stableKey } from "./sqlite-open.js";
+import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+
+//#region src/services/database/sqlite-lock-verify.ts
+const LOCK_VERIFY_TIMEOUT_MS = 2e3;
+async function verifyLockStillHeld$1(locks, name, fence, timeoutMs = LOCK_VERIFY_TIMEOUT_MS, warn = () => {}) {
+	if (!locks || !name || typeof locks.query !== "function") return;
+	let timer;
+	try {
+		const state = await Promise.race([locks.query(), new Promise((resolve) => {
+			timer = setTimeout(() => resolve(null), timeoutMs);
+		})]);
+		if (state === null) {
+			warn(`lock verification did not answer within ${timeoutMs}ms; trusting the steal callback`);
+			return;
+		}
+		if (!(state.held ?? []).some((l) => l.name === name)) await fence("lock missing after suspected freeze");
+	} catch {} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+//#endregion
+//#region src/services/database/sqlite-select.ts
+function ensureTable(db, table) {
+	if (db.knownTables.has(table)) return;
+	db.run(`CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`);
+	db.knownTables.add(table);
+}
+function execRows(db, sql, bind) {
+	return db.exec(sql, bind).map((r) => reviveRow(r.data));
+}
+/** Mirrors the engine's `selectByIds`: fetch by primary id, preserving `ids`
+*  order unless an ORDER BY overrides it. */
+function selectByIds(db, table, ids, opts) {
+	if (ids.length === 0) return [];
+	ensureTable(db, table);
+	const keys = ids.map(stableKey);
+	const placeholders = keys.map(() => "?").join(", ");
+	const bind = [];
+	const dataCol = opts?.select ? projectedDataSql(opts.select, bind) : "data";
+	bind.push(...keys);
+	let sql = `SELECT ${dataCol} FROM "${table}" WHERE id IN (${placeholders})`;
+	if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
+	let rows = execRows(db, sql, bind);
+	if (!opts?.orderBy || opts.orderBy.length === 0) {
+		const pos = new Map(keys.map((k, i) => [k, i]));
+		rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
+	}
+	return rows;
+}
+/** Mirrors the engine's `fetchRelation` SQL exactly. */
+function fetchRelation(db, req) {
+	ensureTable(db, req.table);
+	const keys = req.keys.map(stableKey);
+	const placeholders = keys.map(() => "?").join(", ");
+	const bind = [...keys];
+	const lhs = req.matchField === "id" ? "id" : `json_extract(data, '$.${req.matchField}')`;
+	let sql = `SELECT data FROM "${req.table}" WHERE ${lhs} IN (${placeholders})`;
+	if (req.where && req.where.length > 0) sql += ` AND ${renderWhereSql(req.where, bind, {})}`;
+	if (req.orderBy && req.orderBy.length > 0) sql += renderOrderSql(req.orderBy);
+	const rows = execRows(db, sql, bind);
+	return req.select ? rows.map((r) => project(r, req.select)) : rows;
+}
+async function executeSelect(plan, params, db) {
+	const counter = { n: 0 };
+	const fetcher = { fetchRelation: (req) => {
+		counter.n++;
+		return Promise.resolve(fetchRelation(db, req));
+	} };
+	if (plan.ids) {
+		const rows = selectByIds(db, plan.table, plan.ids, {
+			select: plan.select,
+			orderBy: plan.orderBy
+		});
+		await resolveRelations(rows, plan.relations, fetcher);
+		return {
+			rows,
+			relationFetches: counter.n
+		};
+	}
+	ensureTable(db, plan.table);
+	const bind = [];
+	let sql = `SELECT ${plan.select ? projectedDataSql(plan.select, bind) : "data"} FROM "${plan.table}"`;
+	if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
+	if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
+	else sql += ` ORDER BY id`;
+	if (plan.limit !== void 0) sql += ` LIMIT ${Number(plan.limit)}`;
+	if (plan.offset !== void 0) sql += ` OFFSET ${Number(plan.offset)}`;
+	const rows = execRows(db, sql, bind);
+	await resolveRelations(rows, plan.relations, fetcher);
+	return {
+		rows,
+		relationFetches: counter.n
+	};
+}
+
+//#endregion
+//#region src/services/database/sqlite-worker.ts
+/**
+* Dedicated Web Worker that owns the SQLite-WASM handle. All DB access is
+* funnelled through here (the main thread never touches the wasm module), which
+* is also what the OPFS VFS requires — file access must happen off the main
+* thread. Persistence uses the **OPFS SAHPool VFS**: durable, and (unlike the
+* classic OPFS VFS) it does NOT require COOP/COEP cross-origin isolation
+* headers, so host apps embedding the client need no server changes. When OPFS
+* is unavailable it retries, then falls back to an in-memory DB and REPORTS the
+* loss of durability (see `sqlite-open.ts`) instead of degrading silently.
+*
+* Message protocol (request/response keyed by `id`; replies go to the channel
+* the request arrived on):
+*   { id, type: 'open',   payload: { dbName, useOpfs, workerLockName? } }
+*        -> { id, ok, persisted, opfsError? }
+*   { id, type: 'exec',   payload: { sql, bind } }  -> { id, ok, rows }
+*   { id, type: 'run',    payload: { sql, bind } }  -> { id, ok }
+*   { id, type: 'batch',  payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+*   { id, type: 'select', payload: { plan, params } } -> { id, ok, rows, relationFetches }
+*   { id, type: 'close' }
+*   { id, type: 'shutdown' }                     (owner only: close + pauseVfs + self.close)
+*   { id, type: 'relock', payload: { workerLockName } }               (owner only)
+*   { id, type: 'add-client', payload: { clientId } } + ev.ports[0]   (owner only)
+*   { id, type: 'remove-client', payload: { clientId } }              (owner only)
+*
+* Multi-client (shared-tabs mode): the OWNER (the leader tab's engine) speaks
+* on the worker's own channel and controls the lifecycle. Follower tabs get a
+* MessagePort each (`add-client`) and may only issue data ops
+* (exec/run/batch/select). Every op, from any channel, runs through ONE op
+* chain so an async `select` from one client can never interleave with another
+* client's `batch` at the VFS layer.
+*
+* Leader fencing (shared-tabs mode): `open` may carry `workerLockName`, a Web
+* Lock this worker acquires BEFORE opening the pool and holds for the DB's
+* lifetime. The name is unique per leadership, so the lock being gone has
+* exactly one meaning: the broker stole it because this tab was presumed dead
+* (usually frozen). When that happens the worker FENCES itself: closes the DB,
+* releases the OPFS sync access handles (pauseVfs), tells the owner, and
+* refuses every further op. A frozen-then-thawed ex-leader therefore can never
+* write the durable file after a new leader took over. The thaw gate below
+* closes the wake-up ordering race where a queued write could run before the
+* lock-loss callback fires.
+*
+* `select` executes a whole QueryPlan — table creation, base select, the full
+* `.related()` tree (shared `resolveRelations`), and JSON row parsing — in ONE
+* round-trip, returning structured-clone row objects. This is the first-load
+* hot path; the per-statement ops remain for the write/shim paths.
+*/
+let db = null;
+let pool = null;
+/** Once fenced, every op is refused and the DB stays closed. Terminal. */
+let fenced = false;
+/** The per-leadership lock currently held (null = no fencing active). A
+*  relock (same-leader re-promotion after a broker restart) briefly holds two
+*  locks: the new one is installed here first, then the old one's own release
+*  is called, so there is no window where neither is held. */
+let currentLock = null;
+function workerLocks() {
+	const nav = globalThis.navigator;
+	return nav?.locks && typeof nav.locks.request === "function" ? nav.locks : null;
+}
+/**
+* Acquire `name` exclusively without waiting. Resolves with a handle when
+* granted, null when someone else holds it. If the request settles while the
+* holder still believes it owns the lock, the broker stole it: fence.
+*/
+function acquireWorkerLock(name) {
+	const locks = workerLocks();
+	if (!locks) return Promise.resolve({
+		name,
+		release() {}
+	});
+	return new Promise((resolve) => {
+		let granted = false;
+		let intentional = false;
+		let releaseGrant = null;
+		locks.request(name, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, (lock) => {
+			if (!lock) {
+				resolve(null);
+				return;
+			}
+			granted = true;
+			resolve({
+				name,
+				release() {
+					intentional = true;
+					releaseGrant?.();
+				}
+			});
+			return new Promise((release) => {
+				releaseGrant = release;
+			});
+		}).then(() => {
+			if (granted && !intentional) fence("worker lock stolen");
+		}, () => {
+			if (granted && !intentional) fence("worker lock request failed");
+		});
+	});
+}
+function releaseHeldLock() {
+	currentLock?.release();
+	currentLock = null;
+}
+/**
+* Terminal teardown after leadership loss. Closing the DB first makes
+* pauseVfs legal (it throws while files are open); pausing releases the sync
+* access handles so the NEW leader's open succeeds without waiting for this
+* worker to be garbage collected.
+*/
+async function fence(reason) {
+	if (fenced) return;
+	fenced = true;
+	console.error(`[sp00ky] sqlite worker fenced (${reason}): leadership was taken over, closing the database and refusing further ops.`);
+	try {
+		db?.close();
+	} catch {}
+	db = null;
+	try {
+		pool?.pauseVfs?.();
+	} catch {}
+	pool = null;
+	try {
+		self.postMessage({
+			type: "lock-lost",
+			reason
+		});
+	} catch {}
+	releaseHeldLock();
+	self.close();
+}
+/**
+* A frozen tab's worker resumes with its message queue intact, and a queued
+* write could run BEFORE the lock-steal callback fires. Both the 1s interval
+* and every op call `noteTick()`; whichever runs first after a long gap kicks
+* off a lock verification, and ops await it before touching the DB. The gap
+* threshold must stay BELOW the broker's pong timeout: a freeze shorter than
+* the threshold cannot have triggered a steal yet, so skipping the check for
+* small gaps is safe.
+*/
+const FREEZE_SUSPECT_MS = 1e4;
+let lastTickAt = performance.now();
+let thawVerification = null;
+function noteTick() {
+	const now = performance.now();
+	const gap = now - lastTickAt;
+	lastTickAt = now;
+	if (gap > FREEZE_SUSPECT_MS && currentLock && !fenced && !thawVerification) thawVerification = verifyLockStillHeld().finally(() => {
+		thawVerification = null;
+	});
+}
+setInterval(noteTick, 1e3);
+function verifyLockStillHeld() {
+	return verifyLockStillHeld$1(workerLocks(), currentLock?.name, (reason) => fence(reason), void 0, (msg) => console.warn(`[sqlite-worker] ${msg}`));
+}
+async function open(dbName, useOpfs, systemTables = [], workerLockName, openOptions) {
+	if (workerLockName) {
+		const handle = await acquireWorkerLock(workerLockName);
+		if (!handle) throw new Error("worker-lock-unavailable");
+		releaseHeldLock();
+		currentLock = handle;
+	}
+	const result = await openDb(await sqlite3InitModule(), dbName, useOpfs, openOptions ?? {});
+	db = result.db;
+	pool = result.pool ?? null;
+	for (const t of systemTables) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+	try {
+		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
+	} catch {}
+	return {
+		persisted: result.persisted,
+		opfsError: result.opfsError
+	};
+}
+function closeDb() {
+	db?.close();
+	db = null;
+	pool = null;
+	selectDb.knownTables.clear();
+	releaseHeldLock();
+}
+function exec(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	return db.exec({
+		sql,
+		bind,
+		rowMode: "object",
+		returnValue: "resultRows"
+	});
+}
+function run(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({
+		sql,
+		bind
+	});
+}
+function batch(stmts) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({ sql: "BEGIN" });
+	try {
+		for (const s of stmts) db.exec({
+			sql: s.sql,
+			bind: s.bind
+		});
+		db.exec({ sql: "COMMIT" });
+	} catch (e) {
+		try {
+			db.exec({ sql: "ROLLBACK" });
+		} catch {}
+		throw e;
+	}
+}
+/** DB handle for `executeSelect` (see `sqlite-select.ts`, the unit-testable
+*  plan executor). `knownTables` is cleared on open/close, which covers both
+*  the solo fresh-worker path and the shared-mode same-worker bucket switch. */
+const selectDb = {
+	exec: (sql, bind) => exec(sql, bind),
+	run,
+	knownTables: /* @__PURE__ */ new Set()
+};
+/** Follower client ports, keyed by the clientId the owner assigned. */
+const clients = /* @__PURE__ */ new Map();
+/** Data ops a follower client port may issue; lifecycle stays owner-only. */
+const CLIENT_OPS = new Set([
+	"exec",
+	"run",
+	"batch",
+	"select"
+]);
+/**
+* ONE chain for every op from every channel. The handlers for `open` and
+* `select` are async; without this, a follower's select could interleave with
+* the owner's batch mid-transaction at the VFS layer. (Solo mode kept this
+* invariant on the main thread via the engine's opQueue; with multiple client
+* ports only the worker can.)
+*/
+let opChain = Promise.resolve();
+async function handle(type, payload, source) {
+	if (fenced) throw new Error("sqlite: fenced, leadership was taken over");
+	if (source === "client" && !CLIENT_OPS.has(type)) throw new Error(`sqlite worker: op ${type} is not allowed on a client port`);
+	switch (type) {
+		case "open":
+			selectDb.knownTables.clear();
+			{
+				const result = await open(payload.dbName, payload.useOpfs, payload.systemTables, payload.workerLockName, payload.openOptions);
+				for (const t of payload.systemTables ?? []) selectDb.knownTables.add(t);
+				return result;
+			}
+		case "relock": {
+			const handle = await acquireWorkerLock(payload.workerLockName);
+			if (!handle) throw new Error("worker-lock-unavailable");
+			releaseHeldLock();
+			currentLock = handle;
+			return {};
+		}
+		case "select": return executeSelect(payload.plan, payload.params ?? {}, selectDb);
+		case "exec": return { rows: exec(payload.sql, payload.bind) };
+		case "run":
+			run(payload.sql, payload.bind);
+			return {};
+		case "batch":
+			batch(payload);
+			return {};
+		case "close":
+			closeDb();
+			return {};
+		case "shutdown":
+			try {
+				db?.close();
+			} catch {}
+			db = null;
+			try {
+				pool?.pauseVfs?.();
+			} catch {}
+			pool = null;
+			releaseHeldLock();
+			queueMicrotask(() => self.close());
+			return {};
+		case "remove-client":
+			clients.get(payload.clientId)?.close();
+			clients.delete(payload.clientId);
+			return {};
+		default: throw new Error(`sqlite worker: unknown message ${type}`);
+	}
+}
+function dispatch(target, data, source) {
+	const { id, type, payload } = data ?? {};
+	noteTick();
+	const t0 = performance.now();
+	const runOp = async () => {
+		try {
+			if (thawVerification) await thawVerification;
+			const result = await handle(type, payload, source);
+			target.postMessage({
+				id,
+				ok: true,
+				wt: performance.now() - t0,
+				...result
+			});
+		} catch (err) {
+			target.postMessage({
+				id,
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	};
+	opChain = opChain.then(runOp, runOp);
+}
+self.onmessage = (ev) => {
+	const data = ev.data ?? {};
+	if (data.type === "add-client") {
+		const port = ev.ports?.[0];
+		const clientId = data.payload?.clientId;
+		if (!port || !clientId) {
+			self.postMessage({
+				id: data.id,
+				ok: false,
+				error: "sqlite worker: add-client needs a clientId and a transferred port"
+			});
+			return;
+		}
+		clients.get(clientId)?.close();
+		clients.set(clientId, port);
+		port.onmessage = (pe) => dispatch(port, pe.data, "client");
+		port.start?.();
+		self.postMessage({
+			id: data.id,
+			ok: true,
+			wt: 0
+		});
+		return;
+	}
+	dispatch(self, data, "owner");
+};
+
+//#endregion
+export {  };

package/dist/tabs-broker-worker.d.ts

@@ -0,0 +1,8 @@
+//#region src/services/tabs/tabs-broker-worker.d.ts
+/** Attach a connecting tab's port. Exported for the node test harness, which
+ *  drives the broker with fake MessagePort pairs instead of a SharedWorker. */
+declare function handleConnect(port: MessagePort): void;
+/** Test-only: wipe module state so each test starts with a fresh broker. */
+declare function __resetBrokerForTests(): void;
+//#endregion
+export { __resetBrokerForTests, handleConnect };