Skip to content
Open
4 changes: 2 additions & 2 deletions .github/workflows/desktop-storage-soak.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@ jobs:
matrix:
os: [macos-26, windows-latest, ubuntu-24.04]
group:
- name: contract, T3–T6
cases: contract,T3,T4,T5,T6
- name: contract, T3–T6, quit during a copy
cases: contract,T3,T4,T4-copy,T5,T6
- name: T1 kill during append
cases: T1,T1-dense
- name: T2 kill during compaction
Expand Down
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,34 @@ since the previous tag.

## [Unreleased]

### Desktop P2.6 decision 5: daily copies never hold up a save or a quit

A daily `VACUUM INTO` on the storage worker blocked every save behind it, for
up to 9 s on a Windows runner. That included the quit flush, so a quit during
a copy could drop the final batch of edits. The copy now runs in its own
thread and can be stopped.

#### Changed

- **Desktop:** the daily copy (`desktop/storage/engine/copy-library.ts`)
- copies the library in batches of at most 256 rows or about 4 MiB, from
one read-only snapshot, inside one transaction;
- creates the schema verbatim and copies `sqlite_sequence`,
`user_version` and `application_id`;
- checks row counts and `integrity_check` before the copy is renamed into
place, then runs a passive WAL checkpoint;
- on failure, keeps the previous copies and records `daily_copy_failed`.
- **Desktop:** the storage worker runs that copy in a second thread
(`desktop/storage/copy-worker.ts`), so saves never wait on it. On quit it
stops the copy in milliseconds and deletes the partial file; the previous
copy stays. Opening the library sweeps any partial copy left behind.
- **Tests:** soak case `T4-copy` quits during a copy on all three OSes. T8
compares the copy's time and size with `VACUUM INTO`'s on the year-end
library. A unit test restores a copy and runs the `DocStore` contract on it.
- **Docs:** the architecture spec records the quit budget (3 s flush, then
2 s worker shutdown), the batched copy, and `utilityProcess` as the
upgrade path once P2.5 exists.

### Desktop P2.6: the library storage worker

The SQLite engine behind the desktop library, where documents, folders and
Expand Down
15 changes: 11 additions & 4 deletions desktop/dev/bun-sqlite-driver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* connection with live statements open as a zombie that keeps the file
* handles, which on Windows blocks deleting or replacing the library.
*/
import { Database } from "bun:sqlite";
import { constants, Database } from "bun:sqlite";

import type {
OpenSqlite,
Expand All @@ -19,9 +19,16 @@ import type {
} from "@/desktop/storage/engine/driver";

export const openBunSqlite: OpenSqlite = (path, { readOnly }) => {
const db = readOnly
? new Database(path, { readonly: true })
: new Database(path, { create: true });
// SQLITE_OPEN_URI: the daily copy ATTACHes the library as
// `file:…?mode=ro`. node:sqlite accepts URIs by default; Bun's bundled
// SQLite (Linux, Windows) only with this flag.
const db = new Database(
path,
constants.SQLITE_OPEN_URI |
(readOnly
? constants.SQLITE_OPEN_READONLY
: constants.SQLITE_OPEN_READWRITE | constants.SQLITE_OPEN_CREATE),
);
const cache = new Map<string, SqliteStatement>();
const statements: { finalize(): void }[] = [];
const driver: SqliteDriver = {
Expand Down
1 change: 1 addition & 0 deletions desktop/storage-harness/build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ const result = await Bun.build({
entrypoints: [
path.join(root, "main.ts"),
path.join(root, "../storage/worker.ts"),
path.join(root, "../storage/copy-worker.ts"),
],
outdir: path.join(root, "dist"),
target: "node",
Expand Down
85 changes: 85 additions & 0 deletions desktop/storage-harness/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
* - `readonly`: opens a newer library (T6) and tries to write.
* - `commit-timing`: append round trips with `fullfsync` on or off (T3).
* - `startup`: worker spawn → ready → sidebar rows (T8, the §10 budget).
* - `copy-quit`: quit while the daily copy runs in its thread (decision 5).
* - `copy-time`: how long the batched daily copy takes (decision 5).
*
* An uncaught throw in Electron main opens a modal dialog, so every failure
* exits with `process.exit(1)` after printing `HARNESS_FAIL`.
Expand Down Expand Up @@ -279,6 +281,87 @@ async function commitTiming() {
await client.shutdown();
}

/**
* Decision 5: quit while the daily copy runs in its thread. Waits for the
* library to go idle (the copy starts), keeps typing through the copy (the
* writer must not wait on it), then runs the quit flush.
*/
async function copyQuit() {
const docId = args.doc ?? fail("--doc is required");
const client = await StorageClient.start(workerPath(), {
dir: dir(),
trace: true,
idleMs: 300,
idlePollMs: 100,
});
const owner = "copy-quit";
const loaded = await client.call("load", { docId, owner });
const doc = new Y.Doc();
if (loaded.snapshot) Y.applyUpdate(doc, loaded.snapshot);
for (const update of loaded.updates) Y.applyUpdate(doc, update);
let k =
editCount(doc.getText(TEXT).toString()) ?? fail("stored text is broken");
say(`READY ${k}`);
// Stay idle until the copy thread is running, then type through it.
const waitUntil = performance.now() + 10_000;
while (!(await client.call("stats", {})).dailyCopyRunning) {
if (performance.now() > waitUntil) fail("the daily copy never started");
await new Promise((r) => setTimeout(r, 10));
}
const appendMs: number[] = [];
const typeFor = Number(args["type-ms"] ?? 150);
const started = performance.now();
while (performance.now() - started < typeFor) {
k += 1;
let update: Uint8Array = new Uint8Array();
doc.once("update", (u: Uint8Array) => {
update = u;
});
const text = doc.getText(TEXT);
text.insert(text.length, `${k};`);
const t0 = performance.now();
await client.call("append", {
docId,
owner,
record: { origin: "local", update },
});
appendMs.push(performance.now() - t0);
await new Promise((r) => setTimeout(r, 20));
}
const quitAt = performance.now();
const outcome = await client.shutdown();
say(
`QUIT ${outcome} ${k} ${Math.round(performance.now() - quitAt)} ${Math.round(Math.max(...appendMs))}`,
);
}

/** Decision 5: how long the batched daily copy takes on node:sqlite. */
async function copyTime() {
const client = await StorageClient.start(workerPath(), {
dir: dir(),
idleMs: 0,
idlePollMs: 50,
});
const today = (await client.call("stats", {})).today;
const deadline = performance.now() + 300_000;
for (;;) {
const stats = await client.call("stats", {});
if (stats.lastDailyCopy === today || stats.lastDailyCopyError) {
say(
`COPYTIME ${JSON.stringify({
ms: stats.lastDailyCopyMs,
error: stats.lastDailyCopyError,
libraryBytes: stats.bytes,
})}`,
);
break;
}
if (performance.now() > deadline) fail("the daily copy never finished");
await new Promise((r) => setTimeout(r, 100));
}
await client.shutdown();
}

async function startup() {
// performance.now() counts from process start in Node and Electron main.
const spawnAt = performance.now();
Expand Down Expand Up @@ -310,6 +393,8 @@ const MODES: Record<string, () => Promise<void>> = {
readonly,
"commit-timing": commitTiming,
startup,
"copy-quit": copyQuit,
"copy-time": copyTime,
};

app.whenReady().then(async () => {
Expand Down
8 changes: 7 additions & 1 deletion desktop/storage/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
* pending call rejects with `worker_restarting`, which the renderer's
* batcher retries (resending an append is harmless).
*/
import { dirname, join } from "node:path";
import { Worker } from "node:worker_threads";

import type { StorageErrorEnvelope } from "./engine/errors";
Expand Down Expand Up @@ -86,7 +87,12 @@ export class StorageClient {
events: StorageClientEvents = {},
): Promise<StorageClient> {
const started = performance.now();
const worker = new Worker(workerPath, { workerData: options });
const worker = new Worker(workerPath, {
workerData: {
copyWorkerPath: join(dirname(workerPath), "copy-worker.cjs"),
...options,
},
});
return new Promise((resolve, reject) => {
const onError = (error: Error) => reject(error);
worker.once("error", onError);
Expand Down
36 changes: 36 additions & 0 deletions desktop/storage/copy-worker.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/**
* The daily-copy thread (P2.6 decision 5). The storage worker starts one per
* copy; it reads the library through its own read-only connection, so the
* writer never waits on it, and it yields between batches, so the storage
* worker can `terminate()` it on quit within milliseconds.
*
* Replies once: `{ ok: true, report, ms }` or `{ ok: false, code, message }`.
*/
import { parentPort, workerData } from "node:worker_threads";

import { openNodeSqlite } from "./drivers/node-sqlite";
import { copyLibraryBatched } from "./engine/copy-library";
import { toEnvelope } from "./engine/errors";

export type CopyWorkerData = {
source: string;
partial: string;
batchRows?: number;
};

const port = parentPort;
if (!port) throw new Error("the copy worker must run in a worker_thread");
const { source, partial, batchRows } = workerData as CopyWorkerData;
const started = performance.now();

copyLibraryBatched(openNodeSqlite, source, partial, {
batchRows,
yieldNow: () => new Promise((resolve) => setImmediate(resolve)),
}).then(
(report) =>
port.postMessage({ ok: true, report, ms: performance.now() - started }),
(error) => {
const { code, message } = toEnvelope(error);
port.postMessage({ ok: false, code, message });
},
);
Loading
Loading