The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,033 lines 42.7 KB
Raw
1 import * as NodeSqlite from "node:sqlite";
2 import type * as NodeWorkerThreads from "node:worker_threads";
3 import * as NodeServices from "@effect/platform-node/NodeServices";
4 import { assert, it } from "@effect/vitest";
5 import * as Deferred from "effect/Deferred";
6 import * as Cause from "effect/Cause";
7 import * as Duration from "effect/Duration";
8 import * as Effect from "effect/Effect";
9 import * as Exit from "effect/Exit";
10 import * as Fiber from "effect/Fiber";
11 import * as FileSystem from "effect/FileSystem";
12 import * as Layer from "effect/Layer";
13 import * as Logger from "effect/Logger";
14 import * as Path from "effect/Path";
15 import * as Queue from "effect/Queue";
16 import * as SqlClient from "effect/sql/SqlClient";
17 import * as SqlError from "effect/sql/SqlError";
18 import * as Statement from "effect/sql/Statement";
19 import { ChildProcess, ChildProcessSpawner } from "effect/process";
20 import * as Stream from "effect/Stream";
21 import * as TestClock from "effect/testing/TestClock";
22 import type * as Tracer from "effect/Tracer";
23 import { vi } from "vite-plus/test";
24
25 import * as SqliteClient from "./nodeSqliteClient.ts";
26
27 const startedWorkers = vi.hoisted((): Array<NodeWorkerThreads.Worker> => []);
28 const workerExits = vi.hoisted(() => new WeakMap<NodeWorkerThreads.Worker, Promise<void>>());
29 const silentWorkers = vi.hoisted(() => ({ on: false, readyOnTerminate: false }));
30 const failingWorkers = vi.hoisted(() => ({ message: undefined as string | undefined }));
31 const checkpointWorkers = vi.hoisted((): Array<NodeWorkerThreads.Worker> => []);
32
33 vi.mock("node:worker_threads", async (importOriginal) => {
34 const actual = await importOriginal<typeof NodeWorkerThreads>();
35 class RecordedWorker extends actual.Worker {
36 constructor(...args: ConstructorParameters<typeof actual.Worker>) {
37 super(
38 ...((silentWorkers.on
39 ? ["setInterval(() => {}, 1 << 30);", { eval: true }]
40 : failingWorkers.message !== undefined
41 ? [`throw new Error(${JSON.stringify(failingWorkers.message)});`, { eval: true }]
42 : args) as ConstructorParameters<typeof actual.Worker>),
43 );
44 startedWorkers.push(this);
45 workerExits.set(this, new Promise((resolve) => this.once("exit", () => resolve())));
46 if (args[1]?.workerData?.frames !== undefined) checkpointWorkers.push(this);
47 }
48 override terminate() {
49 // A "ready" already queued when termination starts reaches the parent before "exit".
50 if (silentWorkers.readyOnTerminate) this.emit("message", { type: "ready" });
51 return super.terminate();
52 }
53 }
54 return { ...actual, Worker: RecordedWorker };
55 });
56
57 const withReaderClient = <A, E>(
58 use: (sql: SqlClient.SqlClient) => Effect.Effect<A, E, SqlClient.SqlClient>,
59 ) =>
60 Effect.gen(function* () {
61 const fs = yield* FileSystem.FileSystem;
62 const path = yield* Path.Path;
63 const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-reader-" });
64 const filename = path.join(directory, "state.sqlite");
65 return yield* Effect.gen(function* () {
66 const sql = yield* SqlClient.SqlClient;
67 yield* sql`PRAGMA journal_mode = WAL`;
68 yield* sql`CREATE TABLE entries(name TEXT NOT NULL)`;
69 yield* sql`INSERT INTO entries VALUES ('first')`;
70 return yield* use(sql);
71 }).pipe(Effect.provide(SqliteClient.layer({ filename, readerWorker: true })));
72 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
73
74 const countEntries = (sql: SqlClient.SqlClient) =>
75 Effect.map(
76 sql<{ count: number }>`SELECT COUNT(*) AS count FROM entries`,
77 (rows) => rows[0]?.count,
78 );
79
80 const layer = it.layer(SqliteClient.layer({ filename: ":memory:" }));
81
82 layer("NodeSqliteClient", (it) => {
83 it.effect("records the writer connection owner on a waiting query", () =>
84 Effect.gen(function* () {
85 const sql = yield* SqlClient.SqlClient;
86 const held = yield* Deferred.make<void>();
87 const release = yield* Deferred.make<void>();
88 const holder = yield* sql
89 .withTransaction(
90 sql`SELECT 1`.pipe(
91 Effect.andThen(Deferred.succeed(held, undefined)),
92 Effect.andThen(Deferred.await(release)),
93 ),
94 )
95 .pipe(Effect.withSpan("test.writerHolder"), Effect.forkChild);
96 yield* Deferred.await(held);
97
98 const waitingSpan = yield* Deferred.make<Tracer.Span>();
99 const observeWaiter: Statement.Transformer = (statement, _sql, _fiber, span) =>
100 Deferred.succeed(waitingSpan, span).pipe(Effect.as(statement));
101 const waiter = yield* sql`SELECT 1`.pipe(
102 Effect.provideService(Statement.CurrentTransformer, observeWaiter),
103 Effect.provideService(Statement.SpanPropagationEnabled, true),
104 (effect) => Effect.forkChild(effect, { startImmediately: true }),
105 );
106 const span = yield* Deferred.await(waitingSpan);
107 yield* Deferred.succeed(release, undefined);
108 yield* Fiber.join(holder);
109 yield* Fiber.join(waiter);
110
111 assert.equal(span.attributes.get("db.lock_owner_at_start.name"), "test.writerHolder");
112 assert.typeOf(span.attributes.get("db.lock_owner_at_start.fiber_id"), "number");
113 assert.typeOf(span.attributes.get("db.lock_owner_at_start.trace_id"), "string");
114 assert.typeOf(span.attributes.get("db.lock_owner_at_start.span_id"), "string");
115 }),
116 );
117
118 it.effect("retries preparing a query after the missing schema becomes available", () =>
119 Effect.gen(function* () {
120 const sql = yield* SqlClient.SqlClient;
121 const select = sql<{ name: string }>`SELECT name FROM created_after_prepare_failure`;
122 const error = yield* select.pipe(Effect.flip);
123 assert.equal(error._tag, "SqlError");
124 assert.equal(error.reason.operation, "prepare");
125
126 yield* sql`CREATE TABLE created_after_prepare_failure(name TEXT NOT NULL)`;
127 yield* sql`INSERT INTO created_after_prepare_failure VALUES ('recovered')`;
128 assert.deepEqual(yield* select, [{ name: "recovered" }]);
129 assert.deepEqual(yield* select.values, [["recovered"]]);
130 }),
131 );
132
133 it.effect("classifies constraint failures by their SQLite result code", () =>
134 Effect.gen(function* () {
135 const sql = yield* SqlClient.SqlClient;
136 yield* sql`CREATE TABLE constrained(name TEXT NOT NULL UNIQUE)`;
137 yield* sql`INSERT INTO constrained VALUES ('taken')`;
138
139 const duplicate = yield* sql`INSERT INTO constrained VALUES ('taken')`.pipe(Effect.flip);
140 assert(duplicate.reason._tag === "UniqueViolation");
141 assert.equal(duplicate.reason.constraint, "constrained.name");
142
143 const missing = yield* sql`INSERT INTO constrained VALUES (NULL)`.pipe(Effect.flip);
144 assert.equal(missing.reason._tag, "ConstraintError");
145 }),
146 );
147 });
148
149 const largeText = "x".repeat(64 * 1024 + 1);
150
151 it.effect("reads integers on the values path as the caller asked, cached or not", () =>
152 Effect.gen(function* () {
153 const sql = yield* SqlClient.SqlClient;
154 for (const value of ["small", largeText]) {
155 const values = sql`SELECT 1 AS id, length(${value}) AS size`.values;
156 assert.deepEqual(yield* values.pipe(Effect.provideService(SqlClient.SafeIntegers, true)), [
157 [1n, BigInt(value.length)],
158 ]);
159 assert.deepEqual(yield* values, [[1, value.length]]);
160 }
161 }).pipe(Effect.provide(SqliteClient.layer({ filename: ":memory:" }))),
162 );
163
164 const makeTempDatabase = Effect.gen(function* () {
165 const fs = yield* FileSystem.FileSystem;
166 const path = yield* Path.Path;
167 const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-transaction-" });
168 const filename = path.join(directory, "state.sqlite");
169 const other = yield* Effect.acquireRelease(
170 Effect.sync(() => new NodeSqlite.DatabaseSync(filename)),
171 (database) => Effect.sync(() => database.close()),
172 );
173 yield* Effect.sync(() => {
174 other.exec(`
175 PRAGMA journal_mode = WAL;
176 CREATE TABLE counters(id INTEGER PRIMARY KEY, value INTEGER NOT NULL);
177 INSERT INTO counters VALUES (1, 0);
178 `);
179 });
180 return { filename, other };
181 });
182
183 it.effect.each([false, true])("batches worker results without losing rows (reader=%s)", (reader) =>
184 Effect.gen(function* () {
185 const { filename } = yield* makeTempDatabase;
186 yield* Effect.gen(function* () {
187 const sql = yield* SqlClient.SqlClient;
188 const route = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
189 reader ? effect.pipe(SqliteClient.readOnly) : effect;
190 yield* route(sql`SELECT 1`);
191 const worker = startedWorkers
192 .filter((candidate) => !checkpointWorkers.includes(candidate))
193 .at(-1)!;
194 const batches: Array<ReadonlyArray<unknown>> = [];
195 const record = (reply: { rows?: ReadonlyArray<unknown> }) => {
196 if (Array.isArray(reply.rows) && reply.rows.length > 0) batches.push(reply.rows);
197 };
198 worker.prependListener("message", record);
199 yield* Effect.gen(function* () {
200 const text = "x".repeat(16 * 1024);
201 const query = sql<{ n: number; text: string }>`
202 WITH RECURSIVE sequence(n) AS (
203 SELECT 1 UNION ALL SELECT n + 1 FROM sequence WHERE n < 300
204 ) SELECT n, ${text} AS text FROM sequence
205 `;
206 const rows = yield* reader ? route(query.values) : query;
207 assert.equal(rows.length, 300);
208 for (const [index, row] of rows.entries()) {
209 assert.deepEqual(row, reader ? [index + 1, text] : { n: index + 1, text });
210 }
211 assert.isAbove(batches.length, 1);
212 for (const batch of batches) {
213 assert.isAtMost(batch.length, 16_384);
214 assert.isAtMost(batch.length * text.length * 2, 8 * 1024 * 1024);
215 }
216 batches.length = 0;
217 const narrow = sql<{ n: number }>`
218 WITH RECURSIVE sequence(n) AS (
219 SELECT 1 UNION ALL SELECT n + 1 FROM sequence WHERE n < 10000
220 ) SELECT n FROM sequence
221 `;
222 const narrowRows = yield* reader ? route(narrow.values) : narrow;
223 assert.equal(narrowRows.length, 10_000);
224 assert.deepEqual(narrowRows.at(-1), reader ? [10_000] : { n: 10_000 });
225 assert.equal(batches.length, 1);
226 }).pipe(Effect.ensuring(Effect.sync(() => worker.off("message", record))));
227 }).pipe(
228 Effect.provide(SqliteClient.layer({ filename, writerWorker: true, readerWorker: true })),
229 );
230 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
231 );
232
233 it.effect("coalesces savepoints with queries and preserves nested rollback", () =>
234 Effect.gen(function* () {
235 const { filename } = yield* makeTempDatabase;
236 yield* Effect.gen(function* () {
237 const sql = yield* SqlClient.SqlClient;
238 const worker = startedWorkers.filter((entry) => !checkpointWorkers.includes(entry)).at(-1)!;
239 using messages = vi.spyOn(worker, "postMessage");
240 yield* sql.withTransaction(
241 Effect.forEach(Array.from({ length: 53 }), () => sql.withTransaction(Effect.void)),
242 );
243 assert.equal(messages.mock.calls.length, 2);
244
245 yield* sql.withTransaction(
246 Effect.gen(function* () {
247 yield* sql`UPDATE counters SET value = 1 WHERE id = 1`;
248 const failure = yield* sql
249 .withTransaction(
250 sql`UPDATE counters SET value = 2 WHERE id = 1`.pipe(
251 Effect.andThen(Effect.fail("bad update")),
252 ),
253 )
254 .pipe(Effect.flip);
255 assert.equal(failure, "bad update");
256 const sent = messages.mock.calls.length;
257 assert.equal(
258 yield* sql.withTransaction(Effect.fail("empty update")).pipe(Effect.flip),
259 "empty update",
260 );
261 assert.equal(messages.mock.calls.length, sent);
262 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`, [{ value: 1 }]);
263 assert.deepEqual(messages.mock.calls.at(-1)?.[0].savepoints, []);
264 yield* sql.withTransaction(
265 sql
266 .withTransaction(
267 sql`UPDATE counters SET value = 3 WHERE id = 1`.pipe(
268 Effect.andThen(Effect.fail("nested update")),
269 ),
270 )
271 .pipe(Effect.flip),
272 );
273 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`, [{ value: 1 }]);
274
275 yield* sql.withTransaction(sql`UPDATE counters SET value = 4 WHERE id = 1`);
276 yield* sql`UPDATE counters SET value = 5 WHERE id = 1`;
277 const unsent = yield* sql
278 .withTransaction(sql.unsafe("SELECT ?", [Symbol("uncloneable")]))
279 .pipe(Effect.exit);
280 assert.isTrue(Exit.isFailure(unsent));
281 }),
282 );
283 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`, [{ value: 5 }]);
284 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
285 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
286 );
287
288 it.effect("reuses a worker query after an iterator constraint failure", () =>
289 Effect.gen(function* () {
290 const { filename } = yield* makeTempDatabase;
291 yield* Effect.gen(function* () {
292 const sql = yield* SqlClient.SqlClient;
293 yield* sql`CREATE TABLE unique_entries(name TEXT UNIQUE)`;
294 const insert = (name: string) =>
295 sql<{ name: string }>`INSERT INTO unique_entries VALUES (${name}) RETURNING name`;
296 yield* insert("first");
297 const error = yield* insert("first").pipe(Effect.flip);
298 assert.equal(error.reason._tag, "UniqueViolation");
299 assert.deepEqual(yield* insert("second"), [{ name: "second" }]);
300 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
301 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
302 );
303
304 it.effect("commits on the worker writer after a returning write timed out on a lock", () =>
305 Effect.gen(function* () {
306 const { filename, other } = yield* makeTempDatabase;
307 yield* Effect.gen(function* () {
308 const sql = yield* SqlClient.SqlClient;
309 yield* sql`PRAGMA busy_timeout = 0`;
310 yield* Effect.sync(() => other.exec("BEGIN IMMEDIATE"));
311 const error = yield* sql`UPDATE counters SET value = 1 WHERE id = 1 RETURNING value`.pipe(
312 Effect.flip,
313 );
314 assert.equal(error.reason._tag, "LockTimeoutError");
315 yield* Effect.sync(() => other.exec("COMMIT"));
316
317 yield* sql.withTransaction(sql`UPDATE counters SET value = 2 WHERE id = 1`);
318 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`.values, [[2]]);
319 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
320 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
321 );
322
323 it.effect("keeps another connection from committing between a transaction's read and write", () =>
324 Effect.gen(function* () {
325 const { filename, other } = yield* makeTempDatabase;
326 yield* Effect.gen(function* () {
327 const sql = yield* SqlClient.SqlClient;
328 yield* sql.withTransaction(
329 Effect.gen(function* () {
330 const [row] = yield* sql<{ readonly value: number }>`
331 SELECT value FROM counters WHERE id = 1
332 `;
333 // Deferred BEGIN permits a competing commit, causing SQLITE_BUSY_SNAPSHOT that no timeout can resolve.
334 yield* Effect.sync(() =>
335 assert.throws(
336 () => other.exec("UPDATE counters SET value = value + 1 WHERE id = 1"),
337 /database is locked/,
338 ),
339 );
340 yield* sql`UPDATE counters SET value = ${(row?.value ?? 0) + 10} WHERE id = 1`;
341 }),
342 );
343 yield* Effect.sync(() => other.exec("UPDATE counters SET value = value + 1 WHERE id = 1"));
344 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`.values, [[11]]);
345 }).pipe(Effect.provide(SqliteClient.layer({ filename })));
346 }).pipe(Effect.provide(NodeServices.layer)),
347 );
348
349 it.effect("waits for another process's lock while the database opens", () =>
350 Effect.gen(function* () {
351 const fs = yield* FileSystem.FileSystem;
352 const path = yield* Path.Path;
353 const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-open-" });
354 const filename = path.join(directory, "state.sqlite");
355 const seed = new NodeSqlite.DatabaseSync(filename);
356 seed.exec("PRAGMA journal_mode = WAL; CREATE TABLE entries(name TEXT NOT NULL)");
357 seed.close();
358 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
359 const holder = yield* spawner.spawn(
360 ChildProcess.make(process.execPath, [
361 "-e",
362 `const db = new (require("node:sqlite").DatabaseSync)(process.argv[1]);
363 db.exec("PRAGMA locking_mode = EXCLUSIVE; BEGIN EXCLUSIVE");
364 console.log("held");
365 setTimeout(() => db.close(), 300);`,
366 filename,
367 ]),
368 );
369 yield* Stream.runHead(holder.stdout);
370 yield* Effect.gen(function* () {
371 const sql = yield* SqlClient.SqlClient;
372 assert.deepEqual(yield* sql`SELECT COUNT(*) FROM entries`.values, [[0]]);
373 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
374 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
375 );
376
377 it.effect("reports a transaction blocked by another writer as a lock timeout", () =>
378 Effect.gen(function* () {
379 const { filename, other } = yield* makeTempDatabase;
380 yield* Effect.gen(function* () {
381 const sql = yield* SqlClient.SqlClient;
382 yield* sql`PRAGMA busy_timeout = 0`;
383 const read = sql.withTransaction(sql`SELECT value FROM counters WHERE id = 1`.values);
384
385 yield* Effect.sync(() => other.exec("BEGIN IMMEDIATE"));
386 const error = yield* read.pipe(Effect.flip);
387 assert.equal(error.reason._tag, "LockTimeoutError");
388
389 yield* Effect.sync(() => other.exec("COMMIT"));
390 assert.deepEqual(yield* read, [[0]]);
391 }).pipe(Effect.provide(SqliteClient.layer({ filename })));
392 }).pipe(Effect.provide(NodeServices.layer)),
393 );
394
395 it.effect("lets the event loop run while a write waits for another connection's lock", () =>
396 Effect.gen(function* () {
397 const { filename, other } = yield* makeTempDatabase;
398 yield* Effect.gen(function* () {
399 const sql = yield* SqlClient.SqlClient;
400 yield* sql`PRAGMA busy_timeout = 5000`;
401 yield* Effect.sync(() => other.exec("BEGIN IMMEDIATE"));
402 const write = yield* Effect.forkChild(
403 sql`UPDATE counters SET value = value + 1 WHERE id = 1`,
404 { startImmediately: true },
405 );
406 // A writer on the event loop sleeps in SQLite's busy handler here, so this commit
407 // cannot run until that write has already timed out.
408 yield* eventLoopTurn;
409 yield* Effect.sync(() => other.exec("UPDATE counters SET value = 10 WHERE id = 1; COMMIT"));
410 yield* Fiber.join(write);
411 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`.values, [[11]]);
412 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
413 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
414 );
415
416 it.effect("finishes a write already sent to the writer before its caller is interrupted", () =>
417 Effect.gen(function* () {
418 const { filename, other } = yield* makeTempDatabase;
419 yield* Effect.gen(function* () {
420 const sql = yield* SqlClient.SqlClient;
421 yield* sql`PRAGMA busy_timeout = 5000`;
422 yield* Effect.sync(() => other.exec("BEGIN IMMEDIATE"));
423 const write = yield* Effect.forkChild(
424 sql`UPDATE counters SET value = value + 1 WHERE id = 1`,
425 { startImmediately: true },
426 );
427 yield* eventLoopTurn;
428 const interrupted = yield* Effect.forkChild(Fiber.interrupt(write), {
429 startImmediately: true,
430 });
431 yield* eventLoopTurn;
432 // The write is waiting in the worker for the lock, so the interrupt has to wait too.
433 assert.isUndefined(interrupted.pollUnsafe());
434 yield* Effect.sync(() => other.exec("COMMIT"));
435 yield* Fiber.join(interrupted);
436 assert.deepEqual(yield* sql`SELECT value FROM counters WHERE id = 1`.values, [[1]]);
437 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
438 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
439 );
440
441 it.effect("lets the writer commit while a read-only transaction is open", () =>
442 withReaderClient((sql) =>
443 Effect.gen(function* () {
444 const snapshotTaken = yield* Deferred.make<void>();
445 const writer = yield* Effect.forkChild(
446 Deferred.await(snapshotTaken).pipe(
447 Effect.andThen(sql`INSERT INTO entries VALUES ('second')`),
448 ),
449 );
450 const counts = yield* sql
451 .withTransaction(
452 Effect.gen(function* () {
453 const before = yield* countEntries(sql);
454 yield* Deferred.succeed(snapshotTaken, undefined);
455 // Holding the writer lock here would deadlock this join.
456 yield* Fiber.join(writer);
457 const after = yield* countEntries(sql);
458 return { before, after };
459 }),
460 )
461 .pipe(SqliteClient.readOnly);
462
463 assert.deepEqual(counts, { before: 1, after: 1 });
464 assert.equal(yield* countEntries(sql).pipe(SqliteClient.readOnly), 2);
465 }),
466 ),
467 );
468
469 it.effect("serves another read while a read-only transaction is open", () =>
470 withReaderClient((sql) =>
471 Effect.gen(function* () {
472 const opened = yield* Deferred.make<void>();
473 const other = yield* Effect.forkChild(
474 Deferred.await(opened).pipe(Effect.andThen(countEntries(sql).pipe(SqliteClient.readOnly))),
475 );
476 yield* sql
477 .withTransaction(
478 Effect.gen(function* () {
479 yield* countEntries(sql);
480 yield* Deferred.succeed(opened, undefined);
481 // One shared reader would make this join wait on the transaction forever.
482 assert.equal(yield* Fiber.join(other), 1);
483 }),
484 )
485 .pipe(SqliteClient.readOnly);
486 }),
487 ),
488 );
489
490 it.effect("gives a queued read the first reader that frees up", () =>
491 withReaderClient((sql) =>
492 Effect.gen(function* () {
493 const holders = yield* Effect.forEach([0, 1, 2, 3], () =>
494 Effect.gen(function* () {
495 const held = yield* Deferred.make<void>();
496 const release = yield* Deferred.make<void>();
497 const fiber = yield* sql
498 .withTransaction(
499 countEntries(sql).pipe(
500 Effect.andThen(Deferred.succeed(held, undefined)),
501 Effect.andThen(Deferred.await(release)),
502 ),
503 )
504 .pipe(SqliteClient.readOnly, Effect.forkChild);
505 yield* Deferred.await(held);
506 return { fiber, release };
507 }),
508 );
509 const cancelled = yield* Effect.uninterruptibleMask((restore) =>
510 SqliteClient.readOnly(restore(sql.withTransaction(countEntries(sql)))),
511 ).pipe((effect) => Effect.forkChild(effect, { startImmediately: true }));
512 yield* Fiber.interrupt(cancelled);
513 const cancelledRead = yield* Effect.uninterruptibleMask((restore) =>
514 SqliteClient.readOnly(restore(countEntries(sql))),
515 ).pipe((effect) => Effect.forkChild(effect, { startImmediately: true }));
516 yield* Fiber.interrupt(cancelledRead);
517 const queuedSpan = yield* Deferred.make<Tracer.Span>();
518 const observeQueued: Statement.Transformer = (statement, _sql, _fiber, span) =>
519 Deferred.succeed(queuedSpan, span).pipe(Effect.as(statement));
520 const queued = yield* countEntries(sql).pipe(
521 Effect.provideService(Statement.CurrentTransformer, observeQueued),
522 Effect.provideService(Statement.SpanPropagationEnabled, true),
523 SqliteClient.readOnly,
524 (effect) => Effect.forkChild(effect, { startImmediately: true }),
525 );
526 // Masked read-only work keeps its cancellation pending and still runs once a reader frees up.
527 let maskedRan = 0;
528 const maskedRuns = yield* Effect.forEach(
529 [
530 Effect.scoped(
531 Effect.flatMap(sql.reserve, (connection) =>
532 connection.executeUnprepared("SELECT 1", [], undefined),
533 ),
534 ).pipe(Effect.asVoid),
535 sql.withTransaction(countEntries(sql)).pipe(Effect.asVoid),
536 ],
537 (effect) =>
538 effect.pipe(
539 Effect.andThen(Effect.sync(() => maskedRan++)),
540 Effect.uninterruptible,
541 SqliteClient.readOnly,
542 (masked) => Effect.forkChild(masked, { startImmediately: true }),
543 ),
544 );
545 const interrupting = yield* Effect.forEach(maskedRuns, (fiber) =>
546 Effect.forkChild(Fiber.interrupt(fiber), { startImmediately: true }),
547 );
548 yield* TestClock.adjust("1 second");
549 yield* Deferred.succeed(holders[1]!.release, undefined);
550 yield* Fiber.join(holders[1]!.fiber);
551 // Pinned to the first reader it saw, this read would wait for that reader's transaction.
552 assert.equal(yield* Fiber.join(queued), 1);
553 assert.equal((yield* Deferred.await(queuedSpan)).attributes.get("db.lock_wait_ms"), 1000);
554 for (const { fiber, release } of [holders[0]!, holders[2]!, holders[3]!]) {
555 yield* Deferred.succeed(release, undefined);
556 yield* Fiber.join(fiber);
557 }
558 yield* Effect.forEach(interrupting, Fiber.join);
559 assert.equal(maskedRan, 2);
560 }),
561 ),
562 );
563
564 // regression: #19226 read-only transactions run on the separate reader connection
565 it.effect("rejects a write in a read-only transaction", () =>
566 withReaderClient((sql) =>
567 Effect.gen(function* () {
568 const error = yield* sql
569 .withTransaction(sql`INSERT INTO entries VALUES ('blocked')`)
570 .pipe(SqliteClient.readOnly, Effect.flip);
571
572 assert.equal(error._tag, "SqlError");
573 assert.include(String(error.reason.cause), "readonly database");
574 assert.equal(yield* countEntries(sql), 1);
575 }),
576 ),
577 );
578
579 it.effect("keeps the reader read-only even if a statement turns query_only off", () =>
580 withReaderClient((sql) =>
581 Effect.gen(function* () {
582 const error = yield* sql
583 .withTransaction(
584 Effect.gen(function* () {
585 yield* sql`PRAGMA query_only = OFF`;
586 yield* sql`INSERT INTO entries VALUES ('blocked')`;
587 }),
588 )
589 .pipe(SqliteClient.readOnly, Effect.flip);
590
591 assert.equal(error._tag, "SqlError");
592 assert.include(String(error.reason.cause), "readonly database");
593 assert.equal(yield* countEntries(sql), 1);
594 }),
595 ),
596 );
597
598 it.effect("keeps read-only work inside a write transaction on the writer", () =>
599 withReaderClient((sql) =>
600 sql.withTransaction(
601 Effect.gen(function* () {
602 yield* sql`INSERT INTO entries VALUES ('uncommitted')`;
603 const count = yield* sql.withTransaction(countEntries(sql)).pipe(SqliteClient.readOnly);
604 assert.equal(count, 2);
605 }),
606 ),
607 ),
608 );
609
610 it.effect("fails a read-only transaction whose reader stops, then starts a new reader", () =>
611 withReaderClient((sql) =>
612 Effect.gen(function* () {
613 const startedBefore = startedWorkers.length;
614 const error = yield* sql
615 .withTransaction(
616 Effect.gen(function* () {
617 yield* countEntries(sql);
618 yield* Effect.promise(() => startedWorkers.at(-1)!.terminate());
619 return yield* countEntries(sql);
620 }),
621 )
622 .pipe(SqliteClient.readOnly, Effect.flip);
623
624 assert.equal(error._tag, "SqlError");
625 assert.include(String(error.reason.cause), "Database reader exited");
626 assert.equal(yield* countEntries(sql).pipe(SqliteClient.readOnly), 1);
627 assert.equal(startedWorkers.length, startedBefore + 2);
628 }),
629 ),
630 );
631
632 const withFileClient = <A, E>(
633 setup: (
634 sql: SqlClient.SqlClient,
635 filename: string,
636 ) => Effect.Effect<A, E, SqlClient.SqlClient | FileSystem.FileSystem>,
637 ) =>
638 Effect.gen(function* () {
639 const fs = yield* FileSystem.FileSystem;
640 const path = yield* Path.Path;
641 const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-reader-off-" });
642 const filename = path.join(directory, "state.sqlite");
643 return yield* Effect.gen(function* () {
644 return yield* setup(yield* SqlClient.SqlClient, filename);
645 }).pipe(Effect.provide(SqliteClient.layer({ filename, readerWorker: true })));
646 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
647
648 it.effect("uses the writer when the reader cannot open the database", () =>
649 withFileClient((sql, filename) =>
650 Effect.gen(function* () {
651 yield* sql`PRAGMA journal_mode = WAL`;
652 yield* sql`CREATE TABLE entries(name TEXT NOT NULL)`;
653 yield* sql`INSERT INTO entries VALUES ('kept')`;
654 yield* (yield* FileSystem.FileSystem).remove(filename);
655 const startedBefore = startedWorkers.length;
656
657 assert.equal(yield* sql.withTransaction(countEntries(sql)).pipe(SqliteClient.readOnly), 1);
658 assert.equal(yield* sql.withTransaction(countEntries(sql)).pipe(SqliteClient.readOnly), 1);
659
660 // A read beside an open read transaction must not start a worker on the next slot.
661 const held = yield* Deferred.make<void>();
662 const release = yield* Deferred.make<void>();
663 const holder = yield* sql
664 .withTransaction(
665 countEntries(sql).pipe(
666 Effect.andThen(Deferred.succeed(held, undefined)),
667 Effect.andThen(Deferred.await(release)),
668 ),
669 )
670 .pipe(SqliteClient.readOnly, Effect.forkChild);
671 yield* Deferred.await(held);
672 const other = yield* countEntries(sql).pipe(SqliteClient.readOnly, (effect) =>
673 Effect.forkChild(effect, { startImmediately: true }),
674 );
675 yield* Deferred.succeed(release, undefined);
676 yield* Fiber.join(holder);
677 assert.equal(yield* Fiber.join(other), 1);
678 assert.equal(startedWorkers.length, startedBefore + 1);
679 }),
680 ),
681 );
682
683 const withLogLines = <A, E, R>(
684 use: (lines: Queue.Queue<ReadonlyArray<unknown>>) => Effect.Effect<A, E, R>,
685 ) =>
686 Effect.gen(function* () {
687 const lines = yield* Queue.unbounded<ReadonlyArray<unknown>>();
688 const logger = Logger.make(({ logLevel, message }) => {
689 Queue.offerUnsafe(lines, [logLevel, ...(message as ReadonlyArray<unknown>)]);
690 });
691 return yield* use(lines).pipe(
692 Effect.provide(Logger.layer([logger], { mergeWithExisting: false })),
693 );
694 });
695
696 const readConnection = (sql: SqlClient.SqlClient) =>
697 Effect.gen(function* () {
698 const spans: Array<Tracer.Span> = [];
699 const observe: Statement.Transformer = (statement, _sql, _fiber, span) =>
700 Effect.sync(() => {
701 spans.push(span);
702 return statement;
703 });
704 const count = yield* countEntries(sql).pipe(
705 SqliteClient.readOnly,
706 Effect.provideService(Statement.CurrentTransformer, observe),
707 Effect.provideService(Statement.SpanPropagationEnabled, true),
708 );
709 return { count, connection: spans.map((span) => span.attributes.get("db.connection")) };
710 });
711
712 const withWorkers = <A, E, R>(
713 mode: { readonly failWith?: string; readonly silent?: boolean },
714 effect: Effect.Effect<A, E, R>,
715 ) =>
716 Effect.acquireUseRelease(
717 Effect.sync(() => {
718 failingWorkers.message = mode.failWith;
719 silentWorkers.on = mode.silent ?? false;
720 }),
721 () => effect,
722 () =>
723 Effect.sync(() => {
724 failingWorkers.message = undefined;
725 silentWorkers.on = false;
726 }),
727 );
728
729 const unavailableWarning = "SQLite reader worker unavailable; reads use the writer";
730
731 const notWal = "database uses journal_mode delete, not wal";
732
733 it.effect.each([
734 {
735 failure: "a crash",
736 workers: { failWith: "reader start failed" },
737 startup: Duration.zero,
738 reason: "Database reader failed: reader start failed",
739 },
740 {
741 failure: "a startup timeout",
742 workers: { silent: true },
743 startup: Duration.seconds(10),
744 reason: "Database reader did not open the database within 10000 ms",
745 },
746 ])(
747 "reads on the writer after $failure until a retry starts the reader again",
748 ({ workers, startup, reason }) =>
749 withLogLines((lines) =>
750 withReaderClient((sql) =>
751 Effect.gen(function* () {
752 const failed = yield* withWorkers(
753 workers,
754 Effect.gen(function* () {
755 const read = yield* Effect.forkChild(readConnection(sql), {
756 startImmediately: true,
757 });
758 yield* TestClock.adjust(startup);
759 return yield* Fiber.join(read);
760 }),
761 );
762 assert.deepEqual(failed, { count: 1, connection: ["writer"] });
763 const startedBefore = startedWorkers.length;
764 assert.deepEqual(yield* readConnection(sql), { count: 1, connection: ["writer"] });
765 assert.equal(startedWorkers.length, startedBefore);
766 assert.deepEqual(yield* Queue.take(lines), ["Warn", unavailableWarning, { reason }]);
767
768 yield* TestClock.adjust("1 second");
769 assert.equal(startedWorkers.length, startedBefore + 1);
770 assert.deepEqual(yield* Queue.take(lines), [
771 "Info",
772 "SQLite reader worker available again; reads use the reader workers",
773 ]);
774 assert.deepEqual(yield* readConnection(sql), { count: 1, connection: ["reader"] });
775 assert.equal(Queue.sizeUnsafe(lines), 0);
776 }),
777 ),
778 ),
779 );
780
781 it.effect("backs off a reader that never starts without logging each retry", () =>
782 withLogLines((lines) =>
783 withReaderClient((sql) =>
784 withWorkers(
785 { silent: true },
786 Effect.gen(function* () {
787 const read = yield* Effect.forkChild(readConnection(sql), { startImmediately: true });
788 yield* TestClock.adjust("10 seconds");
789 assert.deepEqual(yield* Fiber.join(read), { count: 1, connection: ["writer"] });
790
791 const startedBefore = startedWorkers.length;
792 // Each retry waits 10 s for startup; the gaps between them double from 1 s up to a minute.
793 yield* TestClock.adjust("10 minutes");
794 assert.equal(startedWorkers.length - startedBefore, 12);
795 assert.equal(Queue.sizeUnsafe(lines), 1);
796 }),
797 ),
798 ),
799 ),
800 );
801
802 it.effect.each([
803 { phase: "the retry waits", beforeClose: Duration.zero, retries: 0 },
804 { phase: "a retried reader starts", beforeClose: Duration.seconds(1), retries: 1 },
805 ])("stops retrying the reader when the client closes while $phase", ({ beforeClose, retries }) =>
806 withWorkers(
807 { silent: true },
808 Effect.gen(function* () {
809 const startedAtClose = yield* withReaderClient((sql) =>
810 Effect.gen(function* () {
811 const read = yield* Effect.forkChild(readConnection(sql), { startImmediately: true });
812 yield* TestClock.adjust("10 seconds");
813 assert.deepEqual(yield* Fiber.join(read), { count: 1, connection: ["writer"] });
814
815 const startedBefore = startedWorkers.length;
816 yield* TestClock.adjust(beforeClose);
817 assert.equal(startedWorkers.length - startedBefore, retries);
818 return startedWorkers.length;
819 }),
820 );
821 yield* TestClock.adjust("10 minutes");
822 assert.equal(startedWorkers.length, startedAtClose);
823 }),
824 ),
825 );
826
827 it.effect.each([
828 {
829 when: "the database is not in WAL mode",
830 journalMode: "DELETE",
831 workers: {},
832 starts: 1,
833 logged: [["Warn", unavailableWarning, { reason: notWal }]],
834 },
835 {
836 when: "a retry finds the database out of WAL mode",
837 journalMode: "WAL",
838 workers: { failWith: "reader start failed" },
839 starts: 2,
840 logged: [
841 ["Warn", unavailableWarning, { reason: "Database reader failed: reader start failed" }],
842 [
843 "Info",
844 "SQLite reader worker retries stopped permanently; reads use the writer",
845 { reason: notWal },
846 ],
847 ],
848 },
849 ])(
850 "keeps readers off without further retries when $when",
851 ({ journalMode, workers, starts, logged }) =>
852 withLogLines((lines) =>
853 withFileClient((sql) =>
854 Effect.gen(function* () {
855 yield* sql.unsafe(`PRAGMA journal_mode = ${journalMode}`);
856 yield* sql`CREATE TABLE entries(name TEXT NOT NULL)`;
857 yield* sql`INSERT INTO entries VALUES ('kept')`;
858 const startedBefore = startedWorkers.length;
859
860 const failed = yield* withWorkers(workers, readConnection(sql));
861 assert.deepEqual(failed, { count: 1, connection: ["writer"] });
862 yield* sql`PRAGMA journal_mode = DELETE`;
863 yield* TestClock.adjust("1 second");
864 yield* Effect.promise(() => workerExits.get(startedWorkers.at(-1)!)!);
865 yield* TestClock.adjust("1 hour");
866 assert.deepEqual(yield* readConnection(sql), { count: 1, connection: ["writer"] });
867 assert.equal(startedWorkers.length, startedBefore + starts);
868 assert.deepEqual(yield* Queue.clear(lines), logged);
869 }),
870 ),
871 ),
872 );
873
874 it.effect("fails with a typed SqlError when the database file is not SQLite", () =>
875 Effect.gen(function* () {
876 const fs = yield* FileSystem.FileSystem;
877 const path = yield* Path.Path;
878 const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-notadb-" });
879 const filename = path.join(directory, "state.sqlite");
880 yield* fs.writeFileString(filename, "not a db\n");
881
882 const exit = yield* Layer.build(SqliteClient.layer({ filename, writerWorker: true })).pipe(
883 Effect.exit,
884 );
885
886 assert.isTrue(Exit.isFailure(exit));
887 if (Exit.isFailure(exit)) assert.isTrue(SqlError.isSqlError(Cause.squash(exit.cause)));
888 if (Exit.isFailure(exit)) assert.isFalse(Cause.hasDies(exit.cause));
889 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
890 );
891
892 it.effect("finishes masked database cleanup after its caller is interrupted", () =>
893 Effect.gen(function* () {
894 const sql = yield* SqlClient.SqlClient;
895 yield* sql`CREATE TABLE cleanup_writes(value INTEGER PRIMARY KEY)`;
896 const entered = yield* Deferred.make<void>();
897 const work = yield* Effect.forkChild(
898 Deferred.succeed(entered, undefined).pipe(
899 Effect.andThen(Effect.never),
900 Effect.onInterrupt(() =>
901 Effect.gen(function* () {
902 yield* sql`INSERT INTO cleanup_writes VALUES (1)`;
903 yield* sql.withTransaction(sql`INSERT INTO cleanup_writes VALUES (2)`);
904 }),
905 ),
906 ),
907 { startImmediately: true },
908 );
909 yield* Deferred.await(entered);
910 yield* Fiber.interrupt(work);
911 assert.deepEqual(yield* sql`SELECT value FROM cleanup_writes ORDER BY value`.values, [
912 [1],
913 [2],
914 ]);
915 }).pipe(Effect.provide(SqliteClient.layer({ filename: ":memory:" }))),
916 );
917
918 // oxlint-disable-next-line t3code/no-real-time-wait-in-tests -- a zero-delay macrotask boundary that lets the worker's queued messages land, not a wait for time
919 const eventLoopTurn = Effect.promise(() => new Promise<void>((resolve) => setImmediate(resolve)));
920
921 it.effect.each([
922 { reservation: false, masked: false },
923 { reservation: false, masked: true },
924 { reservation: true, masked: false },
925 { reservation: true, masked: true },
926 ])(
927 "preserves caller cancellation while waiting (reservation=$reservation, masked=$masked)",
928 ({ reservation, masked }) =>
929 Effect.gen(function* () {
930 const sql = yield* SqlClient.SqlClient;
931 yield* sql`CREATE TABLE entries(value INTEGER)`;
932 const held = yield* Deferred.make<void>();
933 const release = yield* Deferred.make<void>();
934 const holder = yield* Effect.forkChild(
935 sql.withTransaction(
936 Deferred.succeed(held, undefined).pipe(Effect.andThen(Deferred.await(release))),
937 ),
938 { startImmediately: true },
939 );
940 yield* Deferred.await(held);
941 const entered = yield* Deferred.make<void>();
942 const body = sql`INSERT INTO entries VALUES (1)`.pipe(
943 Effect.andThen(Deferred.succeed(entered, undefined)),
944 );
945 const acquire = reservation
946 ? Effect.scoped(
947 Effect.gen(function* () {
948 const connection = yield* sql.reserve;
949 yield* connection.executeUnprepared("INSERT INTO entries VALUES (1)", [], undefined);
950 yield* Deferred.succeed(entered, undefined);
951 }),
952 )
953 : sql.withTransaction(body);
954 const waiter = yield* Effect.forkChild(masked ? Effect.uninterruptible(acquire) : acquire, {
955 startImmediately: true,
956 });
957 const cancelled = yield* Effect.forkChild(Fiber.interrupt(waiter), {
958 startImmediately: true,
959 });
960 yield* Effect.gen(function* () {
961 yield* eventLoopTurn;
962 assert.equal(cancelled.pollUnsafe() !== undefined, !masked);
963 assert.isFalse(yield* Deferred.isDone(entered));
964 }).pipe(Effect.ensuring(Deferred.succeed(release, undefined)));
965 yield* Fiber.join(holder);
966 yield* Fiber.join(cancelled);
967 assert.equal(yield* Deferred.isDone(entered), masked);
968 yield* sql.withTransaction(sql`INSERT INTO entries VALUES (2)`);
969 assert.deepEqual(
970 yield* sql`SELECT value FROM entries ORDER BY value`.values,
971 masked ? [[1], [2]] : [[2]],
972 );
973 }).pipe(Effect.provide(SqliteClient.layer({ filename: ":memory:" }))),
974 );
975
976 it.effect("keeps writes moving while an outside reader pins the WAL, then trims the WAL", () =>
977 Effect.gen(function* () {
978 const fs = yield* FileSystem.FileSystem;
979 const path = yield* Path.Path;
980 const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-pinned-wal-" });
981 const filename = path.join(directory, "state.sqlite");
982 // Stands in for `sqlite3 statev2.sqlite` or a backup script reading the database.
983 const outside = yield* Effect.acquireRelease(
984 Effect.sync(() => new NodeSqlite.DatabaseSync(filename)),
985 (db) =>
986 Effect.sync(() => {
987 if (db.isTransaction) db.exec("COMMIT");
988 db.close();
989 }),
990 );
991 outside.exec("PRAGMA journal_mode = WAL; CREATE TABLE blobs(data BLOB NOT NULL)");
992 const walSize = fs.stat(`${filename}-wal`).pipe(
993 Effect.map((info) => Number(info.size)),
994 Effect.orDie,
995 );
996 const limit = 8 * 1024 * 1024;
997 const payload = new Uint8Array(1024 * 1024).fill(7);
998 yield* Effect.gen(function* () {
999 const sql = yield* SqlClient.SqlClient;
1000 yield* sql.unsafe(`PRAGMA journal_size_limit = ${limit}`);
1001 yield* sql`INSERT INTO blobs VALUES (${payload})`;
1002 outside.exec("BEGIN");
1003 outside.prepare("SELECT COUNT(*) FROM blobs").get();
1004 for (let write = 0; write < 24; write++) yield* sql`INSERT INTO blobs VALUES (${payload})`;
1005 assert.isAbove(yield* walSize, limit);
1006 outside.exec("COMMIT");
1007 const checkpointer = checkpointWorkers.at(-1)!;
1008 const caughtUp = Effect.callback<void>((resume) => {
1009 const onMessage = (message: { type?: unknown; log?: unknown; checkpointed?: unknown }) => {
1010 if (
1011 message?.type === "checked" &&
1012 typeof message.log === "number" &&
1013 message.log > 0 &&
1014 message.log === message.checkpointed
1015 ) {
1016 resume(Effect.void);
1017 }
1018 };
1019 checkpointer.on("message", onMessage);
1020 checkpointer.ref();
1021 return Effect.sync(() => {
1022 checkpointer.off("message", onMessage);
1023 checkpointer.unref();
1024 });
1025 });
1026 // The worker checkpoints the released frames; the next write restarts the WAL at the limit.
1027 yield* Effect.all([caughtUp, sql`DELETE FROM blobs WHERE rowid = 1`], { concurrency: 2 });
1028 yield* sql`DELETE FROM blobs WHERE rowid = 2`;
1029 assert.isAtMost(yield* walSize, limit);
1030 assert.deepEqual(yield* sql`SELECT COUNT(*) FROM blobs`.values, [[23]]);
1031 }).pipe(Effect.provide(SqliteClient.layer({ filename, writerWorker: true })));
1032 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
1033 );