@remit/drizzle-service 0.0.99 → 0.0.100

package/src/tx.sqlite.test.ts

@@ -1,83 +0,0 @@
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { after, before, describe, test } from "node:test";
-import Database from "better-sqlite3";
-import { sql } from "drizzle-orm";
-import { drizzle } from "drizzle-orm/better-sqlite3";
-import type { Db } from "./db.js";
-import { runInTransaction } from "./tx.js";
-
-/**
- * A write set that reads before it writes, against the file four processes
- * share (RFC 036 D3).
- *
- * SQLite gives a deferred transaction its write lock at its first write, and by
- * then a unit that read first is holding a snapshot. Another process committing
- * in that gap makes the upgrade impossible, and SQLite refuses it at once —
- * `busy_timeout` waits for a lock, not for a snapshot that is already stale. The
- * unit then dies with "database is locked" however long that timeout is, which
- * is what answered a calendar write 500 while the imap-worker was syncing.
- */
-
-const PRAGMAS = [
-	"journal_mode = WAL",
-	"busy_timeout = 5000",
-	"synchronous = NORMAL",
-	"foreign_keys = ON",
-];
-
-let directory: string;
-let sqlite: Database.Database;
-let other: Database.Database;
-let db: Db<Record<string, never>>;
-
-before(() => {
-	directory = mkdtempSync(join(tmpdir(), "remit-tx-"));
-	const path = join(directory, "remit.db");
-
-	sqlite = new Database(path);
-	for (const pragma of PRAGMAS) sqlite.pragma(pragma);
-	sqlite.exec("CREATE TABLE row (id INTEGER PRIMARY KEY, v TEXT NOT NULL)");
-	sqlite.exec("INSERT INTO row (id, v) VALUES (1, 'read'), (2, 'other')");
-
-	// The other writer, as a second connection. It refuses instead of waiting,
-	// so the run finishes in its own time whichever of the two holds the lock.
-	other = new Database(path);
-	other.pragma("busy_timeout = 0");
-
-	db = drizzle(sqlite) as unknown as Db<Record<string, never>>;
-});
-
-after(() => {
-	other.close();
-	sqlite.close();
-	rmSync(directory, { recursive: true, force: true });
-});
-
-describe("a top-level sqlite unit that reads before it writes", () => {
-	test("commits through another connection's write landing between the two", async () => {
-		const outcome = await runInTransaction(db, async (tx) => {
-			await tx.get(sql`SELECT v FROM row WHERE id = 1`);
-
-			// The other process, arriving in the gap an async write set leaves
-			// open. Whether its own write lands is not the claim here — only that
-			// this unit can still finish the one it came to make.
-			try {
-				other.prepare("UPDATE row SET v = 'moved' WHERE id = 2").run();
-			} catch {
-				// Refused because this unit holds the write lock, which is the
-				// outcome that keeps the unit below alive.
-			}
-
-			await tx.run(sql`UPDATE row SET v = 'written' WHERE id = 1`);
-			return "committed";
-		});
-
-		assert.equal(outcome, "committed");
-		assert.deepEqual(sqlite.prepare("SELECT v FROM row WHERE id = 1").get(), {
-			v: "written",
-		});
-	});
-});

package/src/tx.ts

@@ -1,233 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID } from "node:crypto";
-import { type SQL, sql } from "drizzle-orm";
-import type { Db } from "./db.js";
-
-// Runs a write set in one transaction.
-//
-// better-sqlite3's native transaction runner rejects a callback that returns a
-// promise, and the repos' write sets are async, so drizzle's own
-// `db.transaction()` cannot be used. A top-level unit is bracketed with
-// `BEGIN IMMEDIATE` / `COMMIT` instead, and a nested one with a SAVEPOINT.
-//
-// IMMEDIATE, not the deferred transaction a bare `BEGIN` or `SAVEPOINT` opens.
-// A deferred transaction takes its write lock at its first write, and a unit
-// that reads before it writes (every unit that checks a row before updating it)
-// has by then taken a read snapshot. If another process commits in between,
-// SQLite refuses the upgrade with SQLITE_BUSY_SNAPSHOT — and that refusal is
-// immediate, because `busy_timeout` cannot wait out a snapshot that is already
-// stale. Four processes write this file (RFC 036 D3), so the gap is real: it
-// answered a calendar write 500 while the imap-worker was syncing. Taking the
-// write lock at BEGIN closes it — an IMMEDIATE that meets another writer waits
-// out the `busy_timeout` and then proceeds, which is what that timeout is for.
-//
-// All writers on this backend share one better-sqlite3 connection (RFC 036 D3),
-// and every query runs synchronously, but an async callback still yields the
-// event loop at each `await`. Two concurrent top-level transactions would
-// therefore interleave their SAVEPOINT/RELEASE on the shared connection and
-// corrupt each other's boundaries — and the existing callers do run concurrently
-// (message-sync's `unitOfWork.transaction` under pMap). So top-level sqlite
-// transactions are serialized behind an async queue: one runs start-to-finish
-// before the next begins, which is exactly the global write serialization D3
-// accepts at single-box scale. Nested calls (a repo opening its own transaction
-// while a unit-of-work already holds one) are detected via AsyncLocalStorage and
-// take a nested savepoint on the same open transaction instead of re-queuing,
-// which would deadlock.
-
-const inSqliteTx = new AsyncLocalStorage<true>();
-
-let sqliteQueue: Promise<unknown> = Promise.resolve();
-
-function serializeSqlite<T>(task: () => Promise<T>): Promise<T> {
-	const result = sqliteQueue.then(task, task);
-	// Keep the queue alive regardless of this task's outcome.
-	sqliteQueue = result.then(
-		() => undefined,
-		() => undefined,
-	);
-	return result;
-}
-
-async function runSqliteSavepoint<TSchema extends Record<string, unknown>, T>(
-	db: Db<TSchema>,
-	fn: (tx: Db<TSchema>) => Promise<T>,
-): Promise<T> {
-	const runner = db as unknown as { run: (query: SQL) => unknown };
-	const name = `sp_${randomUUID().replace(/-/g, "")}`;
-	runner.run(sql.raw(`SAVEPOINT ${name}`));
-	try {
-		const result = await fn(db);
-		runner.run(sql.raw(`RELEASE SAVEPOINT ${name}`));
-		return result;
-	} catch (error) {
-		try {
-			runner.run(sql.raw(`ROLLBACK TO SAVEPOINT ${name}`));
-			runner.run(sql.raw(`RELEASE SAVEPOINT ${name}`));
-		} catch {
-			// A failed rollback must not mask the error that caused it; surface
-			// the original below.
-		}
-		throw error;
-	}
-}
-
-async function runSqliteImmediate<TSchema extends Record<string, unknown>, T>(
-	db: Db<TSchema>,
-	fn: (tx: Db<TSchema>) => Promise<T>,
-): Promise<T> {
-	const runner = db as unknown as { run: (query: SQL) => unknown };
-	runner.run(sql.raw("BEGIN IMMEDIATE"));
-	try {
-		const result = await fn(db);
-		runner.run(sql.raw("COMMIT"));
-		return result;
-	} catch (error) {
-		try {
-			runner.run(sql.raw("ROLLBACK"));
-		} catch {
-			// A failed rollback must not mask the error that caused it; surface
-			// the original below.
-		}
-		throw error;
-	}
-}
-
-export async function runInTransaction<
-	TSchema extends Record<string, unknown>,
-	T,
->(db: Db<TSchema>, fn: (tx: Db<TSchema>) => Promise<T>): Promise<T> {
-	if (inSqliteTx.getStore()) {
-		// Already inside a top-level transaction on this connection — nest with a
-		// savepoint, do not re-queue.
-		return runSqliteSavepoint(db, fn);
-	}
-
-	return serializeSqlite(() =>
-		inSqliteTx.run(true, () => runSqliteImmediate(db, fn)),
-	);
-}
-
-// Every write on the shared better-sqlite3 connection must run start-to-finish
-// with the connection in autocommit — never during the `await` gap of a
-// top-level `runInTransaction` unit, where a plain single statement would join
-// the open SAVEPOINT and be lost on its rollback (the uncommitted-read /
-// rollback hazard from RFC 036 D3, named on PR #1310). A single statement runs
-// synchronously, so the hazard only exists when it lands inside another unit's
-// open savepoint; routing it through the same async queue that serializes
-// transactions guarantees no savepoint is open when it executes.
-//
-// Inside a top-level unit (ALS flag set), the savepoint already holds the queue
-// slot — running directly is correct and re-queuing would deadlock.
-function runSqliteWrite<T>(execute: () => T | Promise<T>): Promise<T> {
-	if (inSqliteTx.getStore()) return Promise.resolve(execute());
-	return serializeSqlite(async () => execute());
-}
-
-const SQLITE_WRITE_METHODS = new Set(["insert", "update", "delete"]);
-
-// The methods that actually run a drizzle write builder's query. Every one of
-// them must run under the write queue, not just the `await` (`then`) path — a
-// repo (now or later) could execute a write via any of these and must not
-// bypass serialization. `values` is an executor only on a runnable (a builder
-// with `execute` — including a `.prepare()`d query); on the pre-`.values(rows)`
-// insert builder it is the chain method, which the runnable gate below leaves
-// to the pass-through path.
-const SQLITE_EXECUTORS = new Set(["execute", "run", "all", "get", "values"]);
-
-// A drizzle write builder is identified by its `execute` method. A Promise (what
-// the executors above return) has `then` but no `execute`, so it is never
-// mistaken for a builder and re-wrapped — re-wrapping a Promise would make its
-// intercepted `then` call the non-existent `promise.execute()`.
-const isWriteBuilder = (value: unknown): value is { execute: () => unknown } =>
-	typeof value === "object" &&
-	value !== null &&
-	typeof (value as { execute?: unknown }).execute === "function";
-
-const runBuilder = (builder: object): Promise<unknown> =>
-	runSqliteWrite(() => (builder as { execute: () => unknown }).execute());
-
-// Wrap a drizzle insert/update/delete builder so every terminal — the `await`
-// (`then`/`catch`/`finally`) and the explicit executors (`execute`/`run`/`all`/
-// `get`/`values`) — runs the query through `runSqliteWrite` instead of inline.
-// Terminals exist only on a runnable (`execute` present), so interception is
-// gated on that: on a pre-`.values(rows)` insert builder nothing is
-// intercepted and the chain passes through untouched. The chain
-// methods (`.values().returning().onConflictDoUpdate()`, `.set()`, `.where()`)
-// return builders, so each chained result is re-wrapped until a terminal fires.
-// Reads never reach here — only the write entry points below.
-function wrapWriteBuilder<B extends object>(builder: B): B {
-	return new Proxy(builder, {
-		get(target, prop, receiver) {
-			if (isWriteBuilder(target)) {
-				if (prop === "then") {
-					return (
-						onFulfilled?: ((value: unknown) => unknown) | null,
-						onRejected?: ((reason: unknown) => unknown) | null,
-					) => runBuilder(target).then(onFulfilled, onRejected);
-				}
-				if (prop === "catch") {
-					return (onRejected?: ((reason: unknown) => unknown) | null) =>
-						runBuilder(target).catch(onRejected);
-				}
-				if (prop === "finally") {
-					return (onFinally?: (() => void) | null) =>
-						runBuilder(target).finally(onFinally);
-				}
-			}
-			if (
-				typeof prop === "string" &&
-				SQLITE_EXECUTORS.has(prop) &&
-				isWriteBuilder(target)
-			) {
-				return (...args: unknown[]) =>
-					runSqliteWrite(() =>
-						(target as unknown as Record<string, (...a: unknown[]) => unknown>)[
-							prop
-						](...args),
-					);
-			}
-			const value = Reflect.get(target, prop, receiver);
-			if (typeof value === "function") {
-				return (...args: unknown[]) => {
-					const result = (value as (...a: unknown[]) => unknown).apply(
-						target,
-						args,
-					);
-					return result === target || isWriteBuilder(result)
-						? wrapWriteBuilder(result as object)
-						: result;
-				};
-			}
-			return value;
-		},
-	});
-}
-
-// Route every repo write through the write queue (RFC 036 D3). The handle a repo
-// holds intercepts `insert`/`update`/`delete` and serializes the resulting
-// query, so no repo insert/update/delete can land inside another unit's open
-// SAVEPOINT. Deliberate escape hatches pass straight through: `run` (the
-// savepoint DDL, already inside a serialized unit), `transaction`, and reads —
-// reads are not serialized, so a read issued during another unit's open
-// transaction can still observe uncommitted rows; the wrapper closes the
-// write-side rollback hazard, not read isolation.
-export function serializeSqliteWrites<TDb extends Db<Record<string, unknown>>>(
-	db: TDb,
-): TDb {
-	return new Proxy(db, {
-		get(target, prop, receiver) {
-			const value = Reflect.get(target, prop, receiver);
-			if (
-				typeof prop === "string" &&
-				SQLITE_WRITE_METHODS.has(prop) &&
-				typeof value === "function"
-			) {
-				return (...args: unknown[]) =>
-					wrapWriteBuilder(
-						(value as (...a: unknown[]) => object).apply(target, args),
-					);
-			}
-			return typeof value === "function" ? value.bind(target) : value;
-		},
-	}) as TDb;
-}