cursedbelt-server 2.0.0 → 2.1.0

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',
+	);
+};

package/src/server/d1/remote.ts

@@ -0,0 +1,182 @@
+/**
+ * The REMOTE implementation of {@link D1LikeDatabase}, over a Cloudflare D1 binding.
+ *
+ * It is thin on purpose. D1's own API is the shape `./types` mirrors, so nearly all of
+ * this file is the normalization that makes a D1 answer indistinguishable from a
+ * `bun:sqlite` one — the same `normalizeBind` / `normalizeValue` the local driver calls,
+ * so "the two drivers agree" is a property of one implementation rather than a
+ * coincidence between two.
+ *
+ * 🔴 **`workerd` is not imported here, and must not be.** This package is built and tested
+ * with Bun, and `@cloudflare/workers-types` would be a dependency the other 99 % of the
+ * library does not need. The binding is described structurally by {@link D1BindingLike}
+ * below, which is the subset of Cloudflare's `D1Database` this driver actually calls — so
+ * a real binding satisfies it without a cast, and the test suite can satisfy it with a
+ * fake that has no `workerd` in sight.
+ */
+
+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';
+
+/** What D1 reports back about a statement. Its `meta` is richer than the local driver's. */
+export interface D1BindingMeta {
+	duration?: number;
+	changes?: number;
+	last_row_id?: number;
+	rows_read?: number;
+	rows_written?: number;
+	served_by?: string;
+}
+
+export interface D1BindingResult {
+	results?: unknown[];
+	success?: boolean;
+	meta?: D1BindingMeta;
+	error?: string;
+}
+
+/** The subset of Cloudflare's `D1PreparedStatement` this driver calls. */
+export interface D1BindingStatement {
+	bind(...values: unknown[]): D1BindingStatement;
+	first(column?: string): Promise<unknown>;
+	all(): Promise<D1BindingResult>;
+	run(): Promise<D1BindingResult>;
+	raw(): Promise<unknown[][]>;
+}
+
+/** The subset of Cloudflare's `D1Database` this driver calls. A real binding satisfies it. */
+export interface D1BindingLike {
+	prepare(sql: string): D1BindingStatement;
+	batch(statements: D1BindingStatement[]): Promise<D1BindingResult[]>;
+	exec(sql: string): Promise<{ count: number; duration: number }>;
+}
+
+/**
+ * D1 reports a failed statement by RESOLVING with `success: false` in some paths rather
+ * than rejecting, so a driver that only catches rejections reports a silent no-op as a
+ * successful write. Every result goes through here.
+ */
+function assertSucceeded(res: D1BindingResult, sql: string): void {
+	if (res.success === false || res.error) {
+		throw new Error(`D1 refused the statement: ${res.error ?? 'success: false'}\n  ${sql.slice(0, 160)}`);
+	}
+}
+
+const toMeta = (res: D1BindingResult) =>
+	makeMeta({
+		changes: res.meta?.changes ?? 0,
+		last_row_id: res.meta?.last_row_id ?? null,
+		duration: res.meta?.duration ?? 0,
+		rows_read: res.meta?.rows_read ?? null,
+		rows_written: res.meta?.rows_written ?? null,
+	});
+
+class RemoteStatement implements D1LikeStatement {
+	constructor(
+		private readonly stmt: D1BindingStatement,
+		private readonly sql: string,
+	) {}
+
+	/** The underlying binding statement — how `batch()` reaches the real objects. */
+	get binding(): D1BindingStatement {
+		return this.stmt;
+	}
+
+	bind(...values: D1LikeBindable[]): D1LikeStatement {
+		const params = normalizeBinds(values);
+		assertWithinLimits(this.sql, params);
+		// D1 accepts ArrayBuffer for BLOBs; `normalizeBind` has already reduced every blob
+		// to a `Uint8Array`, so this is the one place that converts back out.
+		const wire = params.map((p) => (p instanceof Uint8Array ? p.buffer.slice(p.byteOffset, p.byteOffset + p.byteLength) : p));
+		return new RemoteStatement(this.stmt.bind(...wire), this.sql);
+	}
+
+	async first<T = D1LikeRow>(column?: string): Promise<T | null> {
+		const row = await this.stmt.first(column);
+		if (row === null || row === undefined) return null;
+		if (column !== undefined) return normalizeValue(row) as T;
+		return normalizeRows<T>([row as Record<string, unknown>])[0] ?? null;
+	}
+
+	async all<T = D1LikeRow>(): Promise<D1LikeResult<T>> {
+		const res = await this.stmt.all();
+		assertSucceeded(res, this.sql);
+		return {
+			results: normalizeRows<T>((res.results ?? []) as Record<string, unknown>[]),
+			success: true,
+			meta: toMeta(res),
+		};
+	}
+
+	async run(): Promise<D1LikeResult<never>> {
+		const res = await this.stmt.run();
+		assertSucceeded(res, this.sql);
+		return { results: [], success: true, meta: toMeta(res) };
+	}
+
+	async raw<V = D1LikeValue>(): Promise<V[][]> {
+		const rows = await this.stmt.raw();
+		return rows.map((r) => r.map((v) => normalizeValue(v) as V));
+	}
+}
+
+/**
+ * Wrap a Cloudflare D1 binding in the async seam.
+ *
+ * On a Worker this is constructed per request from `env.DB` — a binding is not a
+ * connection and holds no state worth caching, so there is nothing to pool and nothing to
+ * close.
+ */
+export function createRemoteD1(binding: D1BindingLike): D1LikeDatabase {
+	return {
+		flavor: 'd1',
+
+		prepare(sql: string): D1LikeStatement {
+			return new RemoteStatement(binding.prepare(sql), sql);
+		},
+
+		async batch<T = D1LikeRow>(statements: D1LikeStatement[]): Promise<D1LikeResult<T>[]> {
+			assertBatchSize(statements.length);
+			const bindings = statements.map((s) => {
+				const b = (s as Partial<RemoteStatement>).binding;
+				if (!b) {
+					throw new TypeError(
+						'batch() accepts only statements from this same D1 database — ' +
+							'a local statement cannot run inside a D1 batch.',
+					);
+				}
+				return b;
+			});
+			const results = await binding.batch(bindings);
+			return results.map((res, i) => {
+				assertSucceeded(res, `batch statement ${i + 1}`);
+				return {
+					results: normalizeRows<T>((res.results ?? []) as Record<string, unknown>[]),
+					success: true as const,
+					meta: toMeta(res),
+				};
+			});
+		},
+
+		exec(sql: string): Promise<{ count: number; duration: number }> {
+			return binding.exec(sql);
+		},
+	};
+}
+
+/** Re-exported so both drivers refuse an interactive transaction with one message. */
+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',
+	);
+};