cursedbelt-server 1.1.0 → 2.1.0

package/src/server/d1/backup.ts

@@ -0,0 +1,186 @@
+/**
+ * The backup seam — `PRAGMA wal_checkpoint(TRUNCATE)` locally, Time Travel remotely.
+ *
+ * ## 🔴 BOTH, not one
+ *
+ * D1 has no WAL a caller can checkpoint, and 30 days of free point-in-time restore is
+ * strictly better than the file copy it replaces. It is tempting to read that as "the
+ * checkpoint goes away". It does not: `PRAGMA wal_checkpoint(TRUNCATE)` is in the backup
+ * path of every app in this fleet and it is load-bearing while any of them is still
+ * Mac-hosted. Measured previously, `family.sqlite` was **2.2 MB of principal against a
+ * 2.1 MB WAL** — an un-checkpointed copy is half a database, and `VACUUM INTO` merging
+ * the WAL is the only reason the existing `../sqlite/backup.ts` is safe.
+ *
+ * So the local implementation keeps checkpointing, the remote one records a restore
+ * coordinate, and both answer the same interface. An app's backup job stops caring which
+ * side it is on — which is the property that lets the job move before the database does.
+ *
+ * ## The remote side does not "take" a backup, and that is not a gap
+ *
+ * Time Travel is automatic and continuous: D1 retains 30 days and restores to any
+ * timestamp or bookmark within it. There is nothing to trigger, so
+ * {@link createTimeTravelBackup} records the coordinate rather than inventing an API call
+ * that does not exist. The coordinate IS the backup — `wrangler d1 time-travel restore`
+ * takes a timestamp.
+ *
+ * 🔴 **`wrangler d1 export` is the off-Cloudflare leg, and a Worker cannot run it.** A
+ * Worker has no shell. That leg belongs to a Cron Trigger on this Mac or in CI, which is
+ * why {@link BackupPoint.exportCommand} hands back the command rather than running it —
+ * the same split as the binary server, where the bytes and the thing that copies them are
+ * deliberately not the same process.
+ */
+
+import type { Database } from 'bun:sqlite';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { snapshotSqlite } from '../sqlite/backup';
+
+/** A restore coordinate — a file on this Mac, or a point in D1's retention window. */
+export interface BackupPoint {
+	kind: 'file' | 'time-travel';
+	/** A filesystem path for `file`; an ISO-8601 timestamp for `time-travel`. */
+	ref: string;
+	createdAt: string;
+	/** Bytes on disk, or `null` where the platform does not tell us. */
+	bytes: number | null;
+	/** The exact command that restores this point. Printed in the job log, not executed. */
+	restoreCommand: string;
+	/** For `time-travel`, the command that pulls a copy OFF Cloudflare. `null` locally. */
+	exportCommand: string | null;
+}
+
+export interface DatabaseBackup {
+	/** Capture a restore point now, and describe it. */
+	capture(): Promise<BackupPoint>;
+	/** Whether this side needs a periodic capture at all. Time Travel does not. */
+	readonly needsPeriodicCapture: boolean;
+}
+
+export interface LocalBackupOpts {
+	/** The live handle — checkpointed before the snapshot is taken. */
+	db: Database;
+	/** Path of the database file being backed up. */
+	sourcePath: string;
+	/** Directory the snapshot is written into. Created if missing. */
+	destDir: string;
+	/** Override the snapshot's file name. Defaults to `<name>-<ISO>.sqlite`. */
+	nameFor?: (now: Date) => string;
+}
+
+/**
+ * Force the WAL back into the principal database and truncate the log file.
+ *
+ * `TRUNCATE` — not `PASSIVE` — because `PASSIVE` gives up silently when a reader holds the
+ * WAL, leaving a WAL that never drains while every log line says the backup succeeded.
+ *
+ * 🔴 **`busy` is the only field worth reading, and that is a measured correction.** Under
+ * `TRUNCATE` SQLite reports the counters from AFTER the truncation, so a completely
+ * successful checkpoint returns `(busy 0, log 0, checkpointed 0)` — measured 2026-09-16,
+ * draining a 70,072-byte WAL to zero reported `checkpointed: 0`. Anything asserting
+ * `checkpointed > 0` as proof of work is asserting a value that is structurally always
+ * zero here. The honest post-condition is the WAL file's SIZE, which is what
+ * `backup.spec.ts` checks; the honest error signal is `busy`.
+ */
+export function checkpointWal(db: Database): { busy: boolean; logPages: number; checkpointed: number } {
+	// One row: (busy, log, checkpointed). See the note above on what they mean here.
+	const row = db.query('PRAGMA wal_checkpoint(TRUNCATE)').get() as
+		| { busy?: number; log?: number; checkpointed?: number }
+		| null;
+	return {
+		busy: (row?.busy ?? 0) === 1,
+		logPages: row?.log ?? 0,
+		checkpointed: row?.checkpointed ?? 0,
+	};
+}
+
+/**
+ * The Mac-hosted implementation: checkpoint, then `VACUUM INTO` a fresh file.
+ *
+ * `VACUUM INTO` is already transactionally consistent under WAL, so the checkpoint is not
+ * what makes the copy correct — it is what keeps the WAL from growing without bound on a
+ * database that is written far more often than it is read, which is how a 2.2 MB database
+ * came to carry a 2.1 MB WAL.
+ */
+export function createLocalBackup(opts: LocalBackupOpts): DatabaseBackup {
+	return {
+		needsPeriodicCapture: true,
+
+		async capture(): Promise<BackupPoint> {
+			const checkpoint = checkpointWal(opts.db);
+			if (checkpoint.busy) {
+				// Not fatal — `VACUUM INTO` still produces a consistent copy — but it is the
+				// signal that the WAL is not draining, and silence here is how it grows.
+				console.warn(
+					`[d1/backup] wal_checkpoint(TRUNCATE) reported BUSY for ${opts.sourcePath} — ` +
+						`${checkpoint.logPages} page(s) still in the WAL. A reader is holding it open.`,
+				);
+			}
+			if (!existsSync(opts.destDir)) mkdirSync(opts.destDir, { recursive: true });
+
+			const now = new Date();
+			const stamp = now.toISOString().replace(/[:.]/g, '-');
+			const name = opts.nameFor?.(now) ?? `backup-${stamp}.sqlite`;
+			const dest = join(opts.destDir, name);
+
+			const bytes = snapshotSqlite(opts.sourcePath, dest);
+			return {
+				kind: 'file',
+				ref: dest,
+				createdAt: now.toISOString(),
+				bytes,
+				restoreCommand: `cp '${dest}' '${opts.sourcePath}'   # with the app stopped`,
+				exportCommand: null,
+			};
+		},
+	};
+}
+
+export interface TimeTravelOpts {
+	/** The database name as `wrangler` knows it — what the restore command needs. */
+	databaseName: string;
+	/** Where an export should be written, for the off-Cloudflare leg. */
+	exportPath?: string;
+	/** Injected for the test; defaults to the real clock. */
+	now?: () => Date;
+}
+
+/**
+ * The D1 implementation: record the coordinate, because retention is automatic.
+ *
+ * 🔴 It reports `needsPeriodicCapture: false`, and a scheduler must honour that rather
+ * than calling `capture()` on a timer — a nightly no-op job that logs "backup complete"
+ * is worse than no job, because it reads as evidence.
+ */
+export function createTimeTravelBackup(opts: TimeTravelOpts): DatabaseBackup {
+	const clock = opts.now ?? (() => new Date());
+	const exportPath = opts.exportPath ?? `./${opts.databaseName}-export.sql`;
+	return {
+		needsPeriodicCapture: false,
+
+		async capture(): Promise<BackupPoint> {
+			const at = clock().toISOString();
+			return {
+				kind: 'time-travel',
+				ref: at,
+				createdAt: at,
+				// Cloudflare does not report a size for a restore point, and a fabricated
+				// number would read as a measurement.
+				bytes: null,
+				restoreCommand: `wrangler d1 time-travel restore ${opts.databaseName} --timestamp=${at}`,
+				exportCommand: `wrangler d1 export ${opts.databaseName} --remote --output=${exportPath}`,
+			};
+		},
+	};
+}
+
+/**
+ * Pick the backup implementation from the driver flavor, so an app's job definition reads
+ * the same on both sides.
+ */
+export function backupFor(
+	flavor: 'local' | 'd1',
+	local: () => LocalBackupOpts,
+	remote: () => TimeTravelOpts,
+): DatabaseBackup {
+	return flavor === 'local' ? createLocalBackup(local()) : createTimeTravelBackup(remote());
+}

package/src/server/d1/fakeD1.ts

@@ -0,0 +1,193 @@
+/**
+ * A `bun:sqlite`-backed stand-in for a real D1 binding, for tests that must run without a
+ * Worker.
+ *
+ * ## 🔴 It is a DIVERGENCE SIMULATOR, not a mirror of our driver
+ *
+ * The whole value of this file rests on one discipline: it reproduces the ways D1 differs
+ * from `bun:sqlite`, deliberately and on purpose. A fake written to agree with
+ * `createRemoteD1` would make `sameShape.spec.ts` assert that our code agrees with itself,
+ * which is a test that can never fail and therefore is not one.
+ *
+ * So it does the awkward things D1 really does, each measured against `bun:sqlite` on
+ * 2026-09-16 and each one a real defect this fleet would otherwise ship:
+ *
+ *   1. **BLOBs come back as `number[]`**, not `Uint8Array` — D1 crosses the wire as JSON.
+ *   2. **`undefined` and `boolean` binds are REFUSED**, where `bun:sqlite` silently binds
+ *      NULL and silently coerces to 0/1.
+ *   3. **`bigint` binds are refused** — `bun:sqlite` coerces them to numbers, losing
+ *      precision above 2^53 without a word.
+ *   4. **Results are wrapped** in `{ results, success, meta }` rather than returned bare.
+ *   5. **`BEGIN`/`COMMIT` is refused** — D1 has no interactive transaction.
+ *
+ * SQL semantics are real: it runs against an actual in-memory SQLite. Only the edges are
+ * emulated, which are exactly the edges under test.
+ *
+ * 🔴 **It is not a substitute for running against real D1 once.** It cannot reproduce
+ * network failure, a `rows_read` budget or the 30-second query cap. It is the thing that
+ * makes a port testable on a laptop, and `190`'s Worker preview is the thing that proves
+ * it.
+ */
+
+import type { Database } from 'bun:sqlite';
+import type { D1BindingLike, D1BindingResult, D1BindingStatement } from './remote';
+
+/** The bind types a real D1 binding accepts. Everything else throws. */
+function assertD1Bindable(value: unknown, index: number): void {
+	if (value === null) return;
+	const t = typeof value;
+	if (t === 'string' || t === 'number') {
+		if (t === 'number' && !Number.isFinite(value as number)) {
+			throw new TypeError(`D1_TYPE_ERROR: value ${String(value)} at position ${index + 1} is not a finite number`);
+		}
+		return;
+	}
+	if (value instanceof ArrayBuffer || value instanceof Uint8Array) return;
+	throw new TypeError(
+		`D1_TYPE_ERROR: Type '${t === 'undefined' ? 'undefined' : ((value as object)?.constructor?.name ?? t)}' ` +
+			`not supported for value at position ${index + 1}`,
+	);
+}
+
+/** D1 returns BLOB columns as plain arrays of byte values, because the wire is JSON. */
+function toWireValue(value: unknown): unknown {
+	if (value instanceof Uint8Array) return Array.from(value);
+	if (typeof value === 'bigint') return Number(value);
+	return value ?? null;
+}
+
+const toWireRow = (row: Record<string, unknown>): Record<string, unknown> => {
+	const out: Record<string, unknown> = {};
+	for (const k of Object.keys(row)) out[k] = toWireValue(row[k]);
+	return out;
+};
+
+const REFUSED_SQL = /^\s*(begin|commit|rollback|savepoint|release|vacuum|attach|detach|pragma\s+journal_mode)\b/i;
+
+function assertRunnableOnD1(sql: string): void {
+	if (REFUSED_SQL.test(sql)) {
+		throw new Error(
+			`D1_ERROR: not authorized — D1 does not permit '${sql.trim().split(/\s+/)[0]}'. ` +
+				'Use batch() for atomicity; D1 has no interactive transaction and no WAL to configure.',
+		);
+	}
+}
+
+class FakeD1Statement implements D1BindingStatement {
+	constructor(
+		private readonly db: Database,
+		/** Public so `batch()` can re-run the statement inside its transaction. */
+		readonly sql: string,
+		readonly params: unknown[] = [],
+	) {}
+
+	bind(...values: unknown[]): D1BindingStatement {
+		values.forEach((v, i) => assertD1Bindable(v, i));
+		// A real binding stores what it was given; the ArrayBuffer→Uint8Array conversion
+		// here is `bun:sqlite`'s requirement, not D1's, and happens below the emulated edge.
+		const stored = values.map((v) => (v instanceof ArrayBuffer ? new Uint8Array(v) : v));
+		return new FakeD1Statement(this.db, this.sql, stored);
+	}
+
+	private meta(started: number, changes = 0, lastRowId = 0) {
+		return {
+			duration: performance.now() - started,
+			changes,
+			last_row_id: lastRowId,
+			// D1 reports these; the numbers here are not meaningful, but their PRESENCE is
+			// what the driver's `meta` mapping has to cope with.
+			rows_read: 0,
+			rows_written: changes,
+			served_by: 'fake-d1',
+		};
+	}
+
+	async first(column?: string): Promise<unknown> {
+		assertRunnableOnD1(this.sql);
+		const row = this.db.query(this.sql).get(...(this.params as never[])) as Record<string, unknown> | null;
+		if (!row) return null;
+		const wire = toWireRow(row);
+		if (column === undefined) return wire;
+		if (!(column in wire)) throw new Error(`D1_ERROR: no such column: ${column}`);
+		return wire[column];
+	}
+
+	async all(): Promise<D1BindingResult> {
+		assertRunnableOnD1(this.sql);
+		const started = performance.now();
+		const rows = this.db.query(this.sql).all(...(this.params as never[])) as Record<string, unknown>[];
+		return { results: rows.map(toWireRow), success: true, meta: this.meta(started) };
+	}
+
+	async run(): Promise<D1BindingResult> {
+		assertRunnableOnD1(this.sql);
+		const started = performance.now();
+		const res = this.db.query(this.sql).run(...(this.params as never[]));
+		return {
+			results: [],
+			success: true,
+			meta: this.meta(started, res.changes, Number(res.lastInsertRowid)),
+		};
+	}
+
+	async raw(): Promise<unknown[][]> {
+		assertRunnableOnD1(this.sql);
+		const rows = this.db.query(this.sql).values(...(this.params as never[])) as unknown[][];
+		return rows.map((r) => r.map(toWireValue));
+	}
+}
+
+/**
+ * Wrap a real `bun:sqlite` database in D1's API and D1's restrictions.
+ *
+ * ```ts
+ * const sqlite = new Database(':memory:');
+ * const db = createRemoteD1(createFakeD1Binding(sqlite));   // behaves like the real thing
+ * ```
+ */
+export function createFakeD1Binding(db: Database): D1BindingLike {
+	return {
+		prepare(sql: string): D1BindingStatement {
+			return new FakeD1Statement(db, sql);
+		},
+
+		async batch(statements: D1BindingStatement[]): Promise<D1BindingResult[]> {
+			// D1's batch is atomic — it is the only atomicity D1 offers. A real `bun:sqlite`
+			// transaction is the faithful local equivalent.
+			const results: D1BindingResult[] = [];
+			const run = db.transaction((stmts: D1BindingStatement[]) => {
+				for (const s of stmts) {
+					const started = performance.now();
+					const inner = s as FakeD1Statement;
+					assertRunnableOnD1(inner.sql);
+					const rows = db.query(inner.sql).all(...(inner.params as never[])) as Record<string, unknown>[];
+					results.push({
+						results: rows.map(toWireRow),
+						success: true,
+						meta: {
+							duration: performance.now() - started,
+							changes: 0,
+							last_row_id: 0,
+							rows_read: rows.length,
+							rows_written: 0,
+							served_by: 'fake-d1',
+						},
+					});
+				}
+			});
+			run(statements);
+			return results;
+		},
+
+		async exec(sql: string): Promise<{ count: number; duration: number }> {
+			const started = performance.now();
+			const statements = sql
+				.split(';')
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0);
+			for (const s of statements) assertRunnableOnD1(s);
+			for (const s of statements) db.exec(s);
+			return { count: statements.length, duration: performance.now() - started };
+		},
+	};
+}

package/src/server/d1/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `cursedbelt-server/d1` — the async database seam the fleet crosses to reach Cloudflare
+ * Workers, with a local `bun:sqlite` implementation so the gate, the dev loop and every
+ * still-Mac-hosted app keep working unchanged.
+ *
+ * Start at `./types`, which explains why the interface is async on BOTH sides and why the
+ * local driver is deliberately as strict as D1 rather than as lenient as Bun.
+ *
+ * ```ts
+ * import { createLocalD1, createRemoteD1, createD1Kysely } from 'cursedbelt-server/d1';
+ *
+ * const db = env.DB ? createRemoteD1(env.DB) : createLocalD1(sqlite);
+ * const row = await db.prepare('SELECT * FROM people WHERE id = ?').bind(id).first();
+ * const ky  = createD1Kysely(db);
+ * ```
+ */
+
+export {
+	backupFor,
+	type BackupPoint,
+	checkpointWal,
+	createLocalBackup,
+	createTimeTravelBackup,
+	type DatabaseBackup,
+	type LocalBackupOpts,
+	type TimeTravelOpts,
+} from './backup';
+export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
+export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
+export { createLocalD1, refuseInteractiveTransaction } from './local';
+export {
+	createRemoteD1,
+	type D1BindingLike,
+	type D1BindingMeta,
+	type D1BindingResult,
+	type D1BindingStatement,
+} from './remote';
+export {
+	classifySchedule,
+	cronFieldCount,
+	jobsForCron,
+	type PortableJob,
+	type PortableJobContext,
+	type ScheduleVerdict,
+	toCronTriggers,
+	toFiveField,
+	type TriggerShape,
+	type WorkersPrimitive,
+} from './scheduling';
+export {
+	D1BindError,
+	type D1LikeBindable,
+	type D1LikeDatabase,
+	type D1LikeMeta,
+	type D1LikeResult,
+	type D1LikeRow,
+	type D1LikeStatement,
+	type D1LikeValue,
+	D1LimitError,
+	D1UnsupportedError,
+} from './types';
+export { makeMeta, normalizeBind, normalizeBinds, normalizeRow, normalizeRows, normalizeValue } from './values';

package/src/server/d1/kysely.spec.ts

@@ -0,0 +1,145 @@
+/**
+ * The cheap half, proved on BOTH drivers with the same assertions — the point being that
+ * `createD1Kysely` is one dialect over the driver seam, so a plumbing query cannot tell
+ * which side it is on.
+ */
+
+import { Database } from 'bun:sqlite';
+import { describe, expect, test } from 'bun:test';
+import type { Kysely } from 'kysely';
+import { createFakeD1Binding } from './fakeD1';
+import { createD1Kysely } from './kysely';
+import { createLocalD1 } from './local';
+import { createRemoteD1 } from './remote';
+import { D1UnsupportedError, type D1LikeDatabase } from './types';
+
+const DDL = `CREATE TABLE app_config (
+  key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL, updated_by TEXT
+)`;
+
+interface Schema {
+	app_config: { key: string; value: string; updated_at: string; updated_by: string | null };
+}
+
+/** The same schema behind each driver, so every test below runs twice. */
+const drivers = (): Array<[string, () => D1LikeDatabase]> => [
+	[
+		'local',
+		() => {
+			const db = new Database(':memory:');
+			db.run(DDL);
+			return createLocalD1(db);
+		},
+	],
+	[
+		'd1',
+		() => {
+			const db = new Database(':memory:');
+			db.run(DDL);
+			return createRemoteD1(createFakeD1Binding(db));
+		},
+	],
+];
+
+for (const [flavor, make] of drivers()) {
+	describe(`createD1Kysely on the ${flavor} driver`, () => {
+		const fresh = (): Kysely<Schema> => createD1Kysely<Schema>(make());
+
+		test('selectAll on an empty table returns []', async () => {
+			expect(await fresh().selectFrom('app_config').selectAll().execute()).toEqual([]);
+		});
+
+		test('insert + select round-trips a row', async () => {
+			const ky = fresh();
+			await ky
+				.insertInto('app_config')
+				.values({ key: 'media_backend', value: 'disk', updated_at: 't', updated_by: null })
+				.execute();
+
+			const row = await ky
+				.selectFrom('app_config')
+				.select(['key', 'value'])
+				.where('key', '=', 'media_backend')
+				.executeTakeFirst();
+
+			expect(row).toEqual({ key: 'media_backend', value: 'disk' });
+		});
+
+		test('an insert reports the rows it affected', async () => {
+			const ky = fresh();
+			const res = await ky
+				.insertInto('app_config')
+				.values({ key: 'a', value: '1', updated_at: 't', updated_by: null })
+				.executeTakeFirst();
+			expect(Number(res.numInsertedOrUpdatedRows)).toBe(1);
+		});
+
+		test('update and delete report their affected row counts', async () => {
+			const ky = fresh();
+			await ky
+				.insertInto('app_config')
+				.values({ key: 'a', value: '1', updated_at: 't', updated_by: null })
+				.execute();
+
+			const updated = await ky
+				.updateTable('app_config')
+				.set({ value: '2' })
+				.where('key', '=', 'a')
+				.executeTakeFirst();
+			expect(Number(updated.numUpdatedRows)).toBe(1);
+
+			const deleted = await ky.deleteFrom('app_config').where('key', '=', 'a').executeTakeFirst();
+			expect(Number(deleted.numDeletedRows)).toBe(1);
+		});
+
+		test('RETURNING gives back rows rather than a count', async () => {
+			const ky = fresh();
+			const returned = await ky
+				.insertInto('app_config')
+				.values({ key: 'k', value: 'v', updated_at: 't', updated_by: null })
+				.returning(['key', 'value'])
+				.executeTakeFirst();
+			expect(returned).toEqual({ key: 'k', value: 'v' });
+		});
+
+		test('a NULL column comes back as null on both', async () => {
+			const ky = fresh();
+			await ky
+				.insertInto('app_config')
+				.values({ key: 'a', value: '1', updated_at: 't', updated_by: null })
+				.execute();
+			const row = await ky.selectFrom('app_config').selectAll().executeTakeFirstOrThrow();
+			expect(row.updated_by).toBeNull();
+		});
+
+		test('🔴 an interactive transaction is REFUSED — D1 has none, so neither does local', async () => {
+			// The trap this closes: a local dialect that honoured BEGIN would be green here
+			// and red in the Worker. `db.batch()` is the atomicity primitive instead.
+			const ky = fresh();
+			await expect(
+				ky.transaction().execute(async (trx) => {
+					await trx
+						.insertInto('app_config')
+						.values({ key: 'x', value: '1', updated_at: 't', updated_by: null })
+						.execute();
+				}),
+			).rejects.toThrow(D1UnsupportedError);
+		});
+
+		test('a refused transaction leaves NOTHING behind', async () => {
+			const db = make();
+			const ky = createD1Kysely<Schema>(db);
+			await ky
+				.transaction()
+				.execute(async (trx) => {
+					await trx
+						.insertInto('app_config')
+						.values({ key: 'x', value: '1', updated_at: 't', updated_by: null })
+						.execute();
+				})
+				.catch(() => {});
+			const rows = await ky.selectFrom('app_config').selectAll().execute();
+			expect(rows).toEqual([]);
+		});
+	});
+}