@devries-cameron20 / t3code Mirror · read-only / commits / a2a3388c5e
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 21:00 UTC

fix(server): keep writes moving while readers pin the WAL (#23496)

Julius Marminge committed Nov 11, 2026 at 15:42 UTC a2a3388c5ec82d1f33e5e69ed34303529d882e17
2 files changed +126 -13
packages/shared/src/nodeSqliteClient.test.ts
+109
@@ -491,3 +491,112 @@ it.effect.each([
491 );
492 }).pipe(Effect.provide(SqliteClient.layer({ filename: ":memory:" }))),
493 );
494 +
495 +const PAYLOAD = new Uint8Array(1024 * 1024).fill(7);
496 +const WAL_SIZE_LIMIT = 32 * 1024 * 1024;
497 +
498 +// Fails instead of hanging when admission holds the write: the worker retries a blocked
499 +// checkpoint on its own, so two blocked reports for one WAL generation mean a held write.
500 +const insertUnlessHeld = Effect.fnUntraced(function* (
501 + sql: SqlClient.SqlClient,
502 + worker: NodeWorkerThreads.Worker,
503 + label: string,
504 +) {
505 + const stalled = yield* Deferred.make<void>();
506 + let seen: unknown;
507 + const onMessage = (message: { type?: unknown; blocked?: unknown; generation?: unknown }) => {
508 + if (message?.type !== "checkpoint" || message.blocked !== true) return;
509 + if (message.generation === seen) Deferred.doneUnsafe(stalled, Effect.void);
510 + seen = message.generation;
511 + };
512 + worker.on("message", onMessage);
513 + const held = yield* Effect.raceFirst(
514 + sql`INSERT INTO blobs VALUES (${PAYLOAD})`.pipe(Effect.as(false)),
515 + Deferred.await(stalled).pipe(Effect.as(true)),
516 + ).pipe(Effect.ensuring(Effect.sync(() => worker.off("message", onMessage))));
517 + if (held) assert.fail(`${label} is held by admission while an outside reader pins the WAL`);
518 +});
519 +
520 +// `outside` stands in for `sqlite3 statev2.sqlite` or a backup script reading the database.
521 +const withOutsideConnection = <A, E>(
522 + use: (options: {
523 + readonly sql: SqlClient.SqlClient;
524 + readonly worker: NodeWorkerThreads.Worker;
525 + readonly outside: NodeSqlite.DatabaseSync;
526 + readonly walSize: Effect.Effect<number>;
527 + }) => Effect.Effect<A, E, SqlClient.SqlClient>,
528 +) =>
529 + Effect.gen(function* () {
530 + const fs = yield* FileSystem.FileSystem;
531 + const path = yield* Path.Path;
532 + const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-pinned-wal-" });
533 + const filename = path.join(directory, "state.sqlite");
534 + const outside = yield* Effect.acquireRelease(
535 + Effect.sync(() => new NodeSqlite.DatabaseSync(filename)),
536 + (db) =>
537 + Effect.sync(() => {
538 + if (db.isTransaction) db.exec("COMMIT");
539 + db.close();
540 + }),
541 + );
542 + outside.exec(`
543 + PRAGMA journal_mode = WAL;
544 + PRAGMA wal_autocheckpoint = 0;
545 + CREATE TABLE blobs(data BLOB NOT NULL);
546 + `);
547 + const walSize = fs.stat(`${filename}-wal`).pipe(
548 + Effect.map((info) => Number(info.size)),
549 + Effect.orDie,
550 + );
551 + yield* Effect.gen(function* () {
552 + const sql = yield* SqlClient.SqlClient;
553 + yield* sql.unsafe(`PRAGMA journal_size_limit = ${WAL_SIZE_LIMIT}`);
554 + return yield* use({ sql, worker: startedWorkers.at(-1)!, outside, walSize });
555 + }).pipe(Effect.provide(SqliteClient.layer({ filename, checkpointWorker: true })));
556 + }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
557 +
558 +const openReadTransaction = (db: NodeSqlite.DatabaseSync) => {
559 + db.exec("BEGIN");
560 + db.prepare("SELECT COUNT(*) FROM blobs").get();
561 +};
562 +
563 +it.effect("keeps admitting writes while an outside read transaction pins the WAL", () =>
564 + withOutsideConnection(({ sql, worker, outside }) =>
565 + Effect.gen(function* () {
566 + yield* sql`INSERT INTO blobs VALUES (${PAYLOAD})`;
567 + openReadTransaction(outside);
568 + // 140 MiB passes both the 32 MiB size limit and the 32,768-frame ceiling.
569 + for (let write = 1; write <= 140; write++) {
570 + yield* insertUnlessHeld(sql, worker, `write ${write}`);
571 + }
572 + const rows = yield* sql<{ count: number }>`SELECT COUNT(*) AS count FROM blobs`;
573 + assert.equal(rows[0]?.count, 141);
574 + }),
575 + ),
576 +);
577 +
578 +it.effect("keeps admitting writes while a reader stops TRUNCATE, then resets the WAL", () =>
579 + withOutsideConnection(({ sql, worker, outside, walSize }) =>
580 + Effect.gen(function* () {
581 + const insert = outside.prepare("INSERT INTO blobs VALUES (?)");
582 + for (let write = 1; write <= 40; write++) insert.run(PAYLOAD);
583 + // A snapshot of an unbackfilled WAL lets PASSIVE finish but stops TRUNCATE.
584 + openReadTransaction(outside);
585 + const stopped = yield* Deferred.make<void>();
586 + const reset = yield* Deferred.make<void>();
587 + worker.on("message", (message: { type?: unknown; truncateId?: unknown; log?: unknown }) => {
588 + if (message?.type !== "checkpoint" || message.truncateId === undefined) return;
589 + Deferred.doneUnsafe(message.log === 0 ? reset : stopped, Effect.void);
590 + });
591 + // Starts a checkpoint without appending a frame past the reader's snapshot.
592 + yield* sql`DELETE FROM blobs WHERE 0`;
593 + yield* Deferred.await(stopped);
594 + yield* insertUnlessHeld(sql, worker, "a write after the failed TRUNCATE");
595 + assert.isAbove(yield* walSize, WAL_SIZE_LIMIT);
596 + outside.exec("COMMIT");
597 + // No further write arrives; the worker has to retry on its own.
598 + yield* Deferred.await(reset);
599 + assert.equal(yield* walSize, 0);
600 + }),
601 + ),
602 +);
packages/shared/src/nodeSqliteClient.ts
+17 -13
@@ -524,8 +524,9 @@ const initialize = () => {
524 const atCeiling = (state) => state.log >= workerData.backpressureFrames;
525 const exceedsSizeLimit = () =>
526 journalSizeLimit >= 0 && statSync(workerData.filename + "-wal").size > journalSizeLimit;
527 -const schedule = (state, blocked) => {
528 - if (blocked || state.log - state.checkpointed >= workerData.frames) {
527 +// Retry a WAL past its limits even with admission open, so it resets once a pinning reader closes.
528 +const schedule = (state, retry) => {
529 + if (retry || state.log - state.checkpointed >= workerData.frames) {
530 idle = setTimeout(() => check(undefined, undefined, true), workerData.idleMs);
531 }
532 };
@@ -535,8 +536,11 @@ const check = (id, nextJournalSizeLimit, force, nextGeneration = generation) =>
536 if (Number.isSafeInteger(nextJournalSizeLimit)) journalSizeLimit = nextJournalSizeLimit;
537 let state = frames.get();
538 const oversized = exceedsSizeLimit();
539 + let pinned = false;
540 if (force || state.log - state.checkpointed >= workerData.frames || oversized) {
539 - checkpoint.get();
541 + const result = checkpoint.get();
542 + // A reader's snapshot stopped the backfill; holding writes cannot let it catch up.
543 + pinned = result.checkpointed < result.log;
544 state = frames.get();
545 }
546 if (state.checkpointed === state.log && (atCeiling(state) || oversized)) {
@@ -550,24 +554,22 @@ const check = (id, nextJournalSizeLimit, force, nextGeneration = generation) =>
554 });
555 return;
556 }
553 - const blocked = (atCeiling(state) || oversized) && state.checkpointed < state.log;
557 + const blocked = !pinned && (atCeiling(state) || oversized) && state.checkpointed < state.log;
558 parentPort.postMessage({ type: "checkpoint", id, generation, ...state, blocked });
555 - schedule(state, blocked);
559 + schedule(state, atCeiling(state) || oversized);
560 };
561 const finishTruncate = (truncateId) => {
562 if (pendingTruncate === undefined || pendingTruncate.truncateId !== truncateId) return;
563 const pending = pendingTruncate;
564 parentPort.postMessage({ type: "truncate-start", truncateId });
561 - let busy;
565 // Admission is paused here; a pinned reader must not make truncation wait.
566 db.exec("PRAGMA busy_timeout = 0;");
567 try {
565 - busy = truncate.get().busy !== 0;
568 + truncate.get();
569 } finally {
570 db.exec("PRAGMA busy_timeout = 5000;");
571 }
572 const state = frames.get();
570 - const blocked = (atCeiling(state) && (busy || state.checkpointed < state.log)) || exceedsSizeLimit();
573 pendingTruncate = undefined;
574 parentPort.postMessage({
575 type: "checkpoint",
@@ -575,13 +577,15 @@ const finishTruncate = (truncateId) => {
577 generation: pending.generation,
578 truncateId,
579 ...state,
578 - blocked,
580 + // With writes held, only a reader can stop the reset, and holding them longer would not
581 + // release it.
582 + blocked: false,
583 });
584 while (pendingBarriers > 0) {
585 pendingBarriers--;
586 parentPort.postMessage("barrier");
587 }
584 - schedule(state, blocked);
588 + schedule(state, atCeiling(state) || exceedsSizeLimit());
589 };
590 parentPort.on("message", (request) => {
591 clearTimeout(idle);
@@ -669,9 +673,7 @@ const startCheckpointWorker = Effect.fnUntraced(function* (
673 const waiters: Array<Waiter> = [];
674 let elected: Waiter | undefined;
675 const gated = () =>
672 - !stopped &&
673 - !writer.isTransaction &&
674 - (unknown || blocked || truncate !== undefined || log >= CHECKPOINT_BACKPRESSURE_FRAMES);
676 + !stopped && !writer.isTransaction && (unknown || blocked || truncate !== undefined);
677 const wake = () => {
678 if (!gated() && elected === undefined) {
679 elected = waiters.shift();
@@ -719,6 +721,8 @@ const startCheckpointWorker = Effect.fnUntraced(function* (
721 log = nextLog;
722 checkpointed = nextCheckpointed;
723 unknown = false;
724 + // Past the ceiling, hold writes until the worker judges this WAL; a reader can pin it there.
725 + if (log >= CHECKPOINT_BACKPRESSURE_FRAMES) blocked = true;
726 } catch {
727 unknown = true;
728 }