cursedbelt-server 1.1.0 → 2.1.0

package/src/server/d1/kysely.ts

@@ -0,0 +1,169 @@
+/**
+ * The cheap half: a Kysely dialect that speaks {@link D1LikeDatabase}, so every session,
+ * config, log, metric and job table crosses the seam at once and the schema types do not
+ * change at all.
+ *
+ * ## 🔴 ONE dialect over the driver, not two dialects side by side
+ *
+ * The obvious port is "swap `BunSqliteDialect` for a D1 dialect behind a factory". It is
+ * the wrong shape, and cheaply so: two dialects are two implementations of value handling,
+ * and the identical-shapes test would then be asserting that two third-party packages
+ * happen to agree about BLOBs, booleans and `undefined` — the four places SQLite drivers
+ * are already known to disagree. Here there is one dialect. It talks to the driver seam,
+ * the driver seam normalizes through `./values`, and "local and remote return the same
+ * shape" is true by construction rather than by luck.
+ *
+ * It also means the D1 half needs no `kysely-d1` dependency, and the local half keeps
+ * working with the `bun:sqlite` handle the rest of a half-ported app still holds.
+ *
+ * ## What a caller gives up
+ *
+ * `ky.transaction()` throws {@link D1UnsupportedError} on BOTH drivers — D1 has no
+ * interactive transaction, and a local dialect that honoured `BEGIN` would be green here
+ * and red in the Worker. Use `db.batch()` for atomicity. Streaming is refused for the same
+ * reason: D1 returns a whole result set.
+ *
+ * The existing `../db/kysely.ts` is untouched and still correct for an app that has not
+ * moved; this is the one to reach for when it does.
+ */
+
+import {
+	type CompiledQuery,
+	type DatabaseConnection,
+	type DatabaseIntrospector,
+	type Dialect,
+	type DialectAdapter,
+	type Driver,
+	Kysely,
+	type QueryCompiler,
+	type QueryResult,
+	SqliteAdapter,
+	SqliteIntrospector,
+	SqliteQueryCompiler,
+} from 'kysely';
+import type { PlumbingSchema } from '../db/plumbingTypes';
+import { refuseInteractiveTransaction } from './local';
+import { type D1LikeBindable, type D1LikeDatabase, D1UnsupportedError } from './types';
+
+/**
+ * Kysely compiles to a parameter list that may contain values our seam refuses
+ * (`undefined` from an optional column, a `Date` from a careless caller). Passing them
+ * through `bind()` is what turns those into a named error at the call site instead of a
+ * NULL locally and a 500 in production.
+ */
+const bindParams = (sql: string, db: D1LikeDatabase, parameters: readonly unknown[]) => {
+	const stmt = db.prepare(sql);
+	return parameters.length > 0 ? stmt.bind(...(parameters as D1LikeBindable[])) : stmt;
+};
+
+/**
+ * Decide whether a compiled query should be read (`.all()`) or executed (`.run()`).
+ *
+ * Kysely needs `numAffectedRows`/`insertId` from a write and rows from a read, and only
+ * `.run()` reports the former. A write carrying `RETURNING` is a read for this purpose —
+ * its rows are the whole point of the statement.
+ */
+function isRowReturning(query: CompiledQuery['query']): boolean {
+	const node = query as { kind?: string; returning?: unknown };
+	if (node.kind === 'SelectQueryNode' || node.kind === 'RawNode') return true;
+	return node.returning !== undefined;
+}
+
+class D1LikeConnection implements DatabaseConnection {
+	constructor(private readonly db: D1LikeDatabase) {}
+
+	async executeQuery<R>(compiled: CompiledQuery): Promise<QueryResult<R>> {
+		const stmt = bindParams(compiled.sql, this.db, compiled.parameters);
+
+		if (isRowReturning(compiled.query)) {
+			const res = await stmt.all<R>();
+			return { rows: res.results };
+		}
+
+		const res = await stmt.run();
+		return {
+			rows: [],
+			numAffectedRows: BigInt(res.meta.changes),
+			insertId: res.meta.last_row_id === null ? undefined : BigInt(res.meta.last_row_id),
+		};
+	}
+
+	// biome-ignore lint/correctness/useYield: it always throws; a generator body with no
+	// yield is the honest shape for an operation the seam does not have.
+	async *streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
+		throw new D1UnsupportedError(
+			'streaming a result set',
+			'D1 returns a whole result set — page with LIMIT/OFFSET, or a keyset cursor',
+		);
+	}
+}
+
+class D1LikeDriver implements Driver {
+	constructor(private readonly db: D1LikeDatabase) {}
+
+	async init(): Promise<void> {}
+
+	async acquireConnection(): Promise<DatabaseConnection> {
+		// A D1 binding is not a connection: there is no pool, nothing to check out and
+		// nothing to close. The local driver shares the app's single handle for the same
+		// reason. So one connection object serves every query.
+		return new D1LikeConnection(this.db);
+	}
+
+	async beginTransaction(): Promise<void> {
+		refuseInteractiveTransaction();
+	}
+
+	async commitTransaction(): Promise<void> {
+		refuseInteractiveTransaction();
+	}
+
+	async rollbackTransaction(): Promise<void> {
+		refuseInteractiveTransaction();
+	}
+
+	async releaseConnection(): Promise<void> {}
+
+	async destroy(): Promise<void> {}
+}
+
+/** The dialect itself — SQLite's adapter, compiler and introspector over our driver. */
+export class D1LikeDialect implements Dialect {
+	constructor(private readonly db: D1LikeDatabase) {}
+
+	createAdapter(): DialectAdapter {
+		return new SqliteAdapter();
+	}
+
+	createDriver(): Driver {
+		return new D1LikeDriver(this.db);
+	}
+
+	createQueryCompiler(): QueryCompiler {
+		return new SqliteQueryCompiler();
+	}
+
+	createIntrospector(db: Kysely<unknown>): DatabaseIntrospector {
+		return new SqliteIntrospector(db);
+	}
+}
+
+/**
+ * A Kysely query builder over either driver.
+ *
+ * Defaults to {@link PlumbingSchema} — sessions, config, logs, metrics and jobs — which is
+ * the boundary `../db/kysely.ts` drew and this keeps: business / `data JSON` tables stay
+ * on the raw statement API, so the Kysely schema never grows a row per feature table.
+ * Apps with their own plumbing pass their own schema.
+ *
+ * ```ts
+ * const db = createLocalD1(sqlite);            // or createRemoteD1(env.DB)
+ * const ky = createD1Kysely(db);
+ * await ky.selectFrom('auth_sessions').selectAll().execute();   // identical on both
+ * ```
+ */
+export function createD1Kysely<Schema = PlumbingSchema>(db: D1LikeDatabase): Kysely<Schema> {
+	return new Kysely<Schema>({ dialect: new D1LikeDialect(db) });
+}
+
+export type D1PlumbingDb = Kysely<PlumbingSchema>;

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

@@ -0,0 +1,90 @@
+import { Database } from 'bun:sqlite';
+import { describe, expect, test } from 'bun:test';
+import { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
+import { createLocalD1 } from './local';
+import { D1LimitError } from './types';
+
+describe('D1 limits are enforced on the LOCAL driver too', () => {
+	// 🔴 The point of every test here: `bun:sqlite` has none of these caps, so without
+	// this enforcement a bulk insert is green on the laptop and fails on the first real
+	// import in production.
+
+	test('101 bound parameters is refused, naming the chunking helper', () => {
+		const db = createLocalD1(new Database(':memory:'));
+		const placeholders = Array(101).fill('?').join(',');
+		expect(() => db.prepare(`SELECT * FROM t WHERE id IN (${placeholders})`).bind(...Array(101).fill(1))).toThrow(
+			D1LimitError,
+		);
+		try {
+			db.prepare(`SELECT * FROM t WHERE id IN (${placeholders})`).bind(...Array(101).fill(1));
+		} catch (e) {
+			expect((e as Error).message).toContain('chunkForBind');
+		}
+	});
+
+	test('exactly 100 bound parameters is allowed — the cap is not off by one', () => {
+		const db = new Database(':memory:');
+		db.run('CREATE TABLE t (id INTEGER)');
+		const seam = createLocalD1(db);
+		const placeholders = Array(100).fill('?').join(',');
+		expect(() =>
+			seam.prepare(`SELECT * FROM t WHERE id IN (${placeholders})`).bind(...Array(100).fill(1)),
+		).not.toThrow();
+	});
+
+	test('a value over 2 MB is refused, and says where media belongs instead', () => {
+		const db = createLocalD1(new Database(':memory:'));
+		const huge = 'x'.repeat(LIMITS.valueBytes + 1);
+		try {
+			db.prepare('INSERT INTO t (v) VALUES (?)').bind(huge);
+			throw new Error('expected a refusal');
+		} catch (e) {
+			expect(e).toBeInstanceOf(D1LimitError);
+			expect((e as Error).message).toContain('R2');
+		}
+	});
+
+	test('SQL longer than 100 KB is refused before the parameter cap bites', () => {
+		// The measured ordering: a generated `IN (...)` list hits the statement-length cap
+		// first, because inlined values carry no parameters at all.
+		const sql = `SELECT * FROM t WHERE x IN (${Array(30_000).fill("'abc'").join(',')})`;
+		expect(() => assertWithinLimits(sql, [])).toThrow(D1LimitError);
+		expect(() => assertWithinLimits(sql, [])).toThrow(/SQL statement length/);
+	});
+
+	test('a batch over 1,000 statements is refused', () => {
+		expect(() => assertBatchSize(1_001)).toThrow(D1LimitError);
+		expect(() => assertBatchSize(1_000)).not.toThrow();
+	});
+
+	describe('chunkForBind does the arithmetic nobody does correctly by eye', () => {
+		test('4 columns → 25 rows a chunk', () => {
+			const chunks = chunkForBind(Array.from({ length: 60 }, (_, i) => i), 4);
+			expect(chunks.map((c) => c.length)).toEqual([25, 25, 10]);
+			// The property that matters: no chunk exceeds the cap once expanded.
+			for (const c of chunks) expect(c.length * 4).toBeLessThanOrEqual(LIMITS.boundParams);
+		});
+
+		test('a chunk is never empty and every item appears exactly once', () => {
+			const items = Array.from({ length: 489 }, (_, i) => i); // family's 489 people
+			const chunks = chunkForBind(items, 7);
+			expect(chunks.flat()).toEqual(items);
+			for (const c of chunks) expect(c.length).toBeGreaterThan(0);
+		});
+
+		test('an empty list yields no chunks rather than one empty one', () => {
+			expect(chunkForBind([], 3)).toEqual([]);
+		});
+
+		test('an item wider than the cap is refused, not silently chunked to zero', () => {
+			// `floor(100 / 101)` is 0, and a chunk size of 0 loops for ever. This is the
+			// guard that turns an infinite loop into a sentence.
+			expect(() => chunkForBind([1, 2], 101)).toThrow(D1LimitError);
+		});
+
+		test('a nonsense chunk width is refused', () => {
+			expect(() => chunkForBind([1], 0)).toThrow(RangeError);
+			expect(() => chunkForBind([1], 1.5)).toThrow(RangeError);
+		});
+	});
+});

package/src/server/d1/limits.ts

@@ -0,0 +1,123 @@
+/**
+ * D1's hard limits, and the helpers that keep a query inside them.
+ *
+ * 🔴 **These shape the schema, not just the bill.** Three of them change how code must be
+ * written, and all three are invisible on `bun:sqlite` — which has no such caps, so every
+ * one of them is a green-here / red-there defect waiting for the first real dataset:
+ *
+ *   · **1,000 queries per Worker invocation.** An N+1 loop over `family`'s 489 people
+ *     exceeds it. Join, or `batch()`; do not loop.
+ *   · **100 bound parameters per query.** Any seed, import or bulk insert hits this. Use
+ *     {@link chunkForBind}, which does the arithmetic rather than leaving it to a guess.
+ *   · **2 MB per string / BLOB / row.** Nothing may store a media byte in D1.
+ *
+ * The limits are asserted by the LOCAL driver as well as the remote one, which is the
+ * whole point: a bulk insert that would fail in production fails on the laptop, at the
+ * call site, with the chunk size it should have used in the message.
+ *
+ * Values are the Workers **Paid** tier, which is what the owner already pays for.
+ */
+
+import { D1LimitError, type D1LikeBindable } from './types';
+
+export const LIMITS = {
+	/** Bound parameters in a single statement. */
+	boundParams: 100,
+	/** Queries a single Worker invocation may issue, including every `batch()` member. */
+	queriesPerInvocation: 1_000,
+	/** Bytes of SQL text in one statement. A generated `IN (…)` list hits this first. */
+	sqlLength: 100_000,
+	/** Bytes in any single string or BLOB value, and in any single row. */
+	valueBytes: 2_000_000,
+	/** Columns in one table. The fleet's `data JSON` pattern stays far under it. */
+	columnsPerTable: 100,
+	/** Wall-clock milliseconds one query may take. */
+	queryDurationMs: 30_000,
+} as const;
+
+const byteLength = (v: D1LikeBindable): number => {
+	if (typeof v === 'string') return Buffer.byteLength(v, 'utf8');
+	if (v instanceof Uint8Array) return v.byteLength;
+	if (v instanceof ArrayBuffer) return v.byteLength;
+	return 0;
+};
+
+/**
+ * Refuse a statement that D1 would refuse — checked on BOTH drivers, at `bind()` time, so
+ * the failure lands on the call site that built the query rather than in production.
+ */
+export function assertWithinLimits(sql: string, params: readonly D1LikeBindable[]): void {
+	if (params.length > LIMITS.boundParams) {
+		throw new D1LimitError(
+			'bound parameters per query',
+			params.length,
+			LIMITS.boundParams,
+			'Chunk the work — `chunkForBind(items, paramsPerItem)` sizes the batches for you, ' +
+				'or use `batch()` for independent statements.',
+		);
+	}
+	const sqlBytes = Buffer.byteLength(sql, 'utf8');
+	if (sqlBytes > LIMITS.sqlLength) {
+		throw new D1LimitError(
+			'SQL statement length (bytes)',
+			sqlBytes,
+			LIMITS.sqlLength,
+			'A generated `IN (...)` list hits this before the parameter cap — bind parameters instead of inlining values.',
+		);
+	}
+	for (let i = 0; i < params.length; i++) {
+		const bytes = byteLength(params[i] as D1LikeBindable);
+		if (bytes > LIMITS.valueBytes) {
+			throw new D1LimitError(
+				`value size for parameter ${i + 1} (bytes)`,
+				bytes,
+				LIMITS.valueBytes,
+				'D1 is not a blob store. Media bytes belong in R2 behind the binary server — see task 193.',
+			);
+		}
+	}
+}
+
+/** Refuse a `batch()` bigger than one Worker invocation may issue. */
+export function assertBatchSize(count: number): void {
+	if (count > LIMITS.queriesPerInvocation) {
+		throw new D1LimitError(
+			'queries per Worker invocation',
+			count,
+			LIMITS.queriesPerInvocation,
+			'Split the work across invocations — a Queue consumer or a Cron Trigger, not one giant batch.',
+		);
+	}
+}
+
+/**
+ * Split a list into chunks that fit under the 100-parameter cap, given how many bound
+ * parameters each item contributes.
+ *
+ * A bulk insert of `n` rows with `c` columns binds `n * c` parameters, so the batch size
+ * is `floor(100 / c)` — the arithmetic nobody does correctly by eye at 3 a.m., which is
+ * why it is a function and not a sentence in a doc.
+ *
+ * ```ts
+ * for (const rows of chunkForBind(people, 4)) {           // 4 columns → 25 rows a chunk
+ *   await db.prepare(insertSql(rows.length)).bind(...rows.flatMap(toParams)).run();
+ * }
+ * ```
+ */
+export function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[][] {
+	if (!Number.isInteger(paramsPerItem) || paramsPerItem < 1) {
+		throw new RangeError(`paramsPerItem must be a positive integer, got ${paramsPerItem}`);
+	}
+	if (paramsPerItem > LIMITS.boundParams) {
+		throw new D1LimitError(
+			'bound parameters per query',
+			paramsPerItem,
+			LIMITS.boundParams,
+			'A single item already exceeds the cap — store fewer columns, or move the wide value out of D1.',
+		);
+	}
+	const size = Math.floor(LIMITS.boundParams / paramsPerItem);
+	const out: T[][] = [];
+	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size) as T[]);
+	return out;
+}

package/src/server/d1/local.ts

@@ -0,0 +1,173 @@
+/**
+ * The LOCAL implementation of {@link D1LikeDatabase}, over `bun:sqlite`.
+ *
+ * This is the half that keeps the gate, the dev loop and a Mac-hosted app working
+ * unchanged while the fleet ports. It is async because the seam is async — not because
+ * anything here awaits I/O. `bun:sqlite` answers synchronously and these methods resolve
+ * an already-computed value, so the cost is a microtask, not a round trip.
+ *
+ * 🔴 **It is deliberately no more permissive than D1.** Every bind goes through
+ * `normalizeBind`, which refuses the two values `bun:sqlite` would have accepted silently
+ * (`undefined`, and out-of-range `bigint`) and coerces the one both can agree on
+ * (`boolean`). D1's limits are asserted here too, and an interactive transaction is
+ * refused here exactly as it is refused remotely. The point of a local driver is to fail
+ * the same way, early and on a laptop.
+ */
+
+import type { Database } from 'bun:sqlite';
+import { assertBatchSize, assertWithinLimits } from './limits';
+import {
+	type D1LikeBindable,
+	type D1LikeDatabase,
+	type D1LikeResult,
+	type D1LikeRow,
+	type D1LikeStatement,
+	type D1LikeValue,
+	D1UnsupportedError,
+} from './types';
+import { makeMeta, normalizeBinds, normalizeRows, normalizeValue } from './values';
+
+/** Shared clock, so `meta.duration` means the same thing on both sides of the seam. */
+const now = (): number => performance.now();
+
+/**
+ * 🔴 The synchronous core, kept separate from the async surface on purpose.
+ *
+ * `batch()` has to run every statement inside one `db.transaction()` callback, and that
+ * callback is synchronous — a promise resolved inside it settles in a later microtask,
+ * long after `transaction()` has already committed. So the statements expose a real
+ * synchronous method that `batch()` calls directly, and the public `all()` merely wraps
+ * it. Reaching for `.then()` inside the transaction callback looks like it works and
+ * silently commits an empty transaction.
+ */
+interface SyncExecutable {
+	allSync<T>(): D1LikeResult<T>;
+}
+
+class LocalStatement implements D1LikeStatement, SyncExecutable {
+	constructor(
+		private readonly db: Database,
+		private readonly sql: string,
+		private readonly params: D1LikeBindable[] = [],
+	) {}
+
+	bind(...values: D1LikeBindable[]): D1LikeStatement {
+		const params = normalizeBinds(values);
+		assertWithinLimits(this.sql, params);
+		return new LocalStatement(this.db, this.sql, params);
+	}
+
+	private stmt() {
+		return this.db.query(this.sql);
+	}
+
+	allSync<T = D1LikeRow>(): D1LikeResult<T> {
+		const started = now();
+		const rows = this.stmt().all(...(this.params as never[])) as Record<string, unknown>[];
+		return {
+			results: normalizeRows<T>(rows),
+			success: true,
+			meta: makeMeta({ duration: now() - started }),
+		};
+	}
+
+	async first<T = D1LikeRow>(column?: string): Promise<T | null> {
+		const row = this.stmt().get(...(this.params as never[])) as Record<string, unknown> | null;
+		if (row === null || row === undefined) return null;
+		if (column === undefined) return normalizeRows<T>([row])[0] ?? null;
+		if (!(column in row)) {
+			throw new RangeError(`column '${column}' is not in the result of: ${this.sql.slice(0, 80)}`);
+		}
+		return normalizeValue(row[column]) as T;
+	}
+
+	async all<T = D1LikeRow>(): Promise<D1LikeResult<T>> {
+		return this.allSync<T>();
+	}
+
+	async run(): Promise<D1LikeResult<never>> {
+		const started = now();
+		const res = this.stmt().run(...(this.params as never[]));
+		return {
+			results: [],
+			success: true,
+			meta: makeMeta({
+				changes: res.changes,
+				last_row_id: res.lastInsertRowid,
+				duration: now() - started,
+			}),
+		};
+	}
+
+	async raw<V = D1LikeValue>(): Promise<V[][]> {
+		const rows = this.stmt().values(...(this.params as never[])) as unknown[][];
+		return rows.map((r) => r.map((v) => normalizeValue(v) as V));
+	}
+}
+
+/**
+ * Wrap a `bun:sqlite` {@link Database} in the async seam.
+ *
+ * The handle is the SAME one a not-yet-ported app still uses directly, so a half-ported
+ * app has one connection, one WAL and one transaction space — the property `createKysely`
+ * was written for. That is what makes a file-at-a-time port possible instead of an
+ * app-at-a-time one, and it is why this takes a `Database` rather than a path.
+ */
+export function createLocalD1(db: Database): D1LikeDatabase {
+	return {
+		flavor: 'local',
+
+		prepare(sql: string): D1LikeStatement {
+			return new LocalStatement(db, sql);
+		},
+
+		/**
+		 * Atomic on both sides. Locally that is a real `bun:sqlite` transaction; on D1 it is
+		 * one round trip the service commits or discards as a unit. The guarantee a caller
+		 * can rely on is the same, which is the only reason `batch()` can be the fleet's
+		 * transaction primitive — see the note on {@link SyncExecutable} for why the body
+		 * below may not await.
+		 */
+		async batch<T = D1LikeRow>(statements: D1LikeStatement[]): Promise<D1LikeResult<T>[]> {
+			assertBatchSize(statements.length);
+			const run = db.transaction((stmts: D1LikeStatement[]): D1LikeResult<T>[] => {
+				const out: D1LikeResult<T>[] = [];
+				for (const s of stmts) {
+					const sync = s as Partial<SyncExecutable>;
+					if (typeof sync.allSync !== 'function') {
+						throw new TypeError(
+							'batch() accepts only statements from this same local database — ' +
+								'a remote statement cannot run inside a local transaction.',
+						);
+					}
+					out.push(sync.allSync<T>());
+				}
+				return out;
+			});
+			return run(statements);
+		},
+
+		async exec(sql: string): Promise<{ count: number; duration: number }> {
+			const started = now();
+			db.exec(sql);
+			// D1's `exec` reports how many statements it ran, and counts them by `;`.
+			// Matching that keeps the field meaning one thing on both sides.
+			const count = sql
+				.split(';')
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0).length;
+			return { count, duration: now() - started };
+		},
+	};
+}
+
+/**
+ * Refuse an interactive transaction, for the same reason D1 refuses it. Exported so the
+ * Kysely dialect and any app-level helper give one message instead of three.
+ */
+export const refuseInteractiveTransaction = (): never => {
+	throw new D1UnsupportedError(
+		'an interactive transaction (BEGIN/COMMIT)',
+		'collect the statements and pass them to `db.batch([...])`, which is atomic on both drivers',
+	);
+};