Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

feat(relay): moves leave the checkpoint to one quiet-time publisher [H5]

Corey Olson16c45dd1765b
diff --git a/bin/run-tests.js b/bin/run-tests.js
index 3d6c2d7b..b1efc765 100644
--- a/bin/run-tests.js
+++ b/bin/run-tests.js
@@ -231,6 +231,8 @@ function testEnvironment(sandbox, gateMarkers = {}) {
isolateTestMachine(env, sandbox); // #1068: no settings, resources, runners or host markers of the real machine.
// init and resume start a background view by default; a test opts back in by deleting this.
env.PULLBOARD_VIEW_BACKGROUND = '0';
+ // Likewise the relay checkpoint publishes inside the command; a test of the background publisher opts in (#1014).
+ env.PULLBOARD_RELAY_CHECKPOINT_BACKGROUND = '0';
env.TMPDIR = sandbox;
env.TMP = sandbox;
env.TEMP = sandbox;
diff --git a/src/relay-checkpoint-worker.js b/src/relay-checkpoint-worker.js
new file mode 100644
index 00000000..264da2f8
--- /dev/null
+++ b/src/relay-checkpoint-worker.js
@@ -0,0 +1,62 @@
+/**
+ * The background checkpoint publisher for one board (#1014): waits until moves have been quiet, uploads one
+ * checkpoint under the relay lock, and goes again only if a move arrived meanwhile. One runs per board at a time;
+ * a second exits at once. A failure leaves the sealed checkpoint saved in the link for the next publisher to retry.
+ *
+ * Usage (spawned by scheduleCheckpoint): node relay-checkpoint-worker.js <root> <relay link file>
+ */
+import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { alive, checkpointFiles, checkpointQuietMs } from './relay-checkpoint.js';
+import { publishLatestCheckpoint } from './relay.js';
+
+const [root, file] = process.argv.slice(2);
+const { due, pid, log } = checkpointFiles(file);
+
+/** Read the time of the last move, or 0 when none was noted. */
+function lastMove() {
+ try { return Number(readFileSync(due, 'utf8')) || 0; } catch { return 0; }
+}
+
+/** Claim the publisher's place for this board, replacing only a holder that has gone. */
+function claim() {
+ for (let attempt = 0; attempt < 2; attempt += 1) {
+ try { writeFileSync(pid, `${process.pid}\n`, { flag: 'wx', mode: 0o600 }); return true; }
+ catch (error) {
+ if (error.code !== 'EEXIST') throw error;
+ let holder = 0;
+ try { holder = Number(readFileSync(pid, 'utf8')); } catch { /* Gone between the two reads: try again. */ }
+ if (alive(holder) && holder !== process.pid) return false;
+ rmSync(pid, { force: true });
+ }
+ }
+ return false;
+}
+
+/** Keep a short record of failures beside the link; the next command's status reports pending uploads. */
+const io = {
+ say() {},
+ err(line) { try { appendFileSync(log, `${new Date().toISOString()} ${String(line).trim()}\n`, { mode: 0o600 }); } catch { /* No log is no worse than none. */ } },
+};
+
+/** Publish until a checkpoint covers the last move; returns the time of the move it covered. */
+async function publishUntilQuiet() {
+ const quiet = checkpointQuietMs();
+ for (;;) {
+ const moved = lastMove();
+ const wait = quiet - (Date.now() - moved);
+ if (wait > 0) { await new Promise(next => setTimeout(next, wait)); continue; }
+ await publishLatestCheckpoint(root, io);
+ if (lastMove() === moved) return moved;
+ }
+}
+
+// A move noted after the last look, but before the claim was released, saw a live publisher and spawned none:
+// look once more after releasing, and go again if it is newer than what was covered.
+for (let covered = -1; claim();) {
+ try { covered = await publishUntilQuiet(); }
+ catch (error) { io.err(`checkpoint not published: ${error.message}`); covered = Infinity; }
+ finally {
+ try { if (Number(readFileSync(pid, 'utf8')) === process.pid) rmSync(pid, { force: true }); } catch { /* Already gone. */ }
+ }
+ if (lastMove() <= covered) break;
+}
diff --git a/src/relay-checkpoint.js b/src/relay-checkpoint.js
new file mode 100644
index 00000000..e7f59eea
--- /dev/null
+++ b/src/relay-checkpoint.js
@@ -0,0 +1,76 @@
+/**
+ * The board checkpoint leaves the command path (#1014): a move sends only its own sealed event, and one background
+ * publisher per board uploads the checkpoint once moves have been quiet for about a second.
+ *
+ * Measured 22 Oct: every command rebuilt the full presentation (all item threads and 22,618 shouts, 30.7 MB of JSON,
+ * about 1 s) and re-published the sealed checkpoint (about 6.7 MB gzipped) on nearly every move, under the relay lock,
+ * so moves took minutes and failed RELAY_BUSY. A burst of moves now coalesces into one upload, and the relay lock
+ * keeps one upload in flight; moves during an upload are covered by the next one.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Set to 0 to publish the checkpoint inside the command, as before #1014; the test runner sets it, like the view. */
+export const CHECKPOINT_BACKGROUND_ENV = 'PULLBOARD_RELAY_CHECKPOINT_BACKGROUND';
+/** Overrides how long moves must be quiet before the checkpoint goes out; a test models a burst with it. */
+export const CHECKPOINT_QUIET_ENV = 'PULLBOARD_RELAY_CHECKPOINT_QUIET_MS';
+// Budget: a burst of moves a second apart or closer shares one checkpoint; a phone sees a move within about two seconds.
+export const CHECKPOINT_QUIET_MS = 1_000;
+const WORKER = fileURLToPath(new URL('./relay-checkpoint-worker.js', import.meta.url));
+
+/**
+ * Whether this process leaves the checkpoint to the background publisher.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+export function checkpointInBackground(env = process.env) {
+ return env[CHECKPOINT_BACKGROUND_ENV] !== '0';
+}
+
+/**
+ * The quiet period before a checkpoint goes out, in ms.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {number}
+ */
+export function checkpointQuietMs(env = process.env) {
+ const value = Number(env[CHECKPOINT_QUIET_ENV]);
+ return Number.isSafeInteger(value) && value >= 0 ? value : CHECKPOINT_QUIET_MS;
+}
+
+/**
+ * The files the publisher keeps beside the relay link: when the last move happened, and which process publishes.
+ *
+ * @param {string} file - The relay link file.
+ * @returns {{ due: string, pid: string, log: string }}
+ */
+export function checkpointFiles(file) {
+ const directory = dirname(file);
+ return { due: join(directory, 'relay-checkpoint.due'), pid: join(directory, 'relay-checkpoint.pid'), log: join(directory, 'relay-checkpoint.log') };
+}
+
+/** Whether a process is alive; a process another user owns still is. */
+export function alive(pid) {
+ if (!Number.isSafeInteger(pid) || pid < 1) return false;
+ try { process.kill(pid, 0); return true; }
+ catch (error) { return error.code === 'EPERM'; }
+}
+
+/**
+ * Note a move and make sure one publisher will upload the checkpoint once moves go quiet. Never waits and never
+ * builds the checkpoint: a running publisher sees the new time and waits again, so a burst shares one upload.
+ *
+ * @param {string} root
+ * @param {string} file - The relay link file.
+ */
+export function scheduleCheckpoint(root, file) {
+ const { due, pid } = checkpointFiles(file);
+ writeFileSync(due, `${Date.now()}\n`, { mode: 0o600 });
+ const holder = existsSync(pid) ? Number(readFileSync(pid, 'utf8')) : 0;
+ if (alive(holder)) return;
+ const child = spawn(process.execPath, [WORKER, root, file], { cwd: root, detached: true, stdio: 'ignore', env: process.env });
+ child.unref();
+}
diff --git a/src/relay.js b/src/relay.js
index 4bb74bfd..b8c3bf64 100644
--- a/src/relay.js
+++ b/src/relay.js
@@ -91,6 +91,10 @@ import {
import { terminalQr } from './qr.js';
import { environmentLink } from './relay-environment.js';
import { locked } from './relay-lock.js';
+import {
+ checkpointInBackground,
+ scheduleCheckpoint,
+} from './relay-checkpoint.js';
import {
decideUncertainBaseline,
remoteBoardMissing,
@@ -900,6 +904,24 @@ async function publishCheckpoint(root, file, state, io) {
if (resumed) clearUploadPauseNotices(state);
}
+/**
+ * Publish this board's checkpoint once, under the relay lock: the background publisher's one step (#1014). A board
+ * whose link is gone or being removed publishes nothing.
+ *
+ * @param {string} root
+ * @param {{ err: (line: string) => void, say: (line: string) => void }} io
+ * @returns {Promise<boolean>} Whether a linked board was published.
+ */
+export async function publishLatestCheckpoint(root, io) {
+ const file = linkFile(root);
+ return locked(file, async () => {
+ const state = loadLink(file);
+ if (!state || state.unlinking) return false;
+ await publishCheckpoint(root, file, state, io);
+ return true;
+ }, io);
+}
+
/** Drain a legacy source once, refusing foreign history before it can be silently checkpointed. */
async function ensureOrdered(root, file, state, io) {
requireUnconflictedBaseline(state);
@@ -1229,13 +1251,17 @@ export async function relayOperation(root, operation, args, io, command, applyLo
if (!receipt) throw new Refused('RELAY_RESPONSE', 'the acknowledged operation has no replay receipt; fetch a consistent relay snapshot');
delete state.recovered;
saveLink(file, state);
- // A phone can read a compacted checkpoint; failed presentation uploads do not undo the move.
- try { await publishCheckpoint(root, file, state, io); }
- catch (error) {
- if (!(error instanceof Refused)) throw error;
- if (confirmedDeletion(state, error)) forgetDeletedCopy(root, file, state, io);
- else if (error.code === 'AUTH_REQUIRED') reportExpiredSignIn(state, io);
- else io.err(`pullboard: ${error.message}`);
+ // A phone reads the next checkpoint; the background publisher sends it once moves go quiet (#1014).
+ if (checkpointInBackground()) scheduleCheckpoint(root, file);
+ else {
+ // A phone can read a compacted checkpoint; failed presentation uploads do not undo the move.
+ try { await publishCheckpoint(root, file, state, io); }
+ catch (error) {
+ if (!(error instanceof Refused)) throw error;
+ if (confirmedDeletion(state, error)) forgetDeletedCopy(root, file, state, io);
+ else if (error.code === 'AUTH_REQUIRED') reportExpiredSignIn(state, io);
+ else io.err(`pullboard: ${error.message}`);
+ }
}
if (receipt.outcome.error) throw refusalFromReceipt(receipt.outcome.error);
if (existsSync(file) && ['register', 'ensureCoordinator'].includes(operation)) await actorTransport(root, file, state, receipt.outcome.result, io);
@@ -1274,7 +1300,10 @@ export async function syncRelay(root, io) {
saveLink(file, state);
io.err(`pullboard: the relay ${state.url} did not sequence the previous move; retry that move explicitly if still wanted`);
}
- if (state.checkpoint || state.presentationDigest !== presentationDigest(relayPresentation(root))) await publishCheckpoint(root, file, state, io);
+ // In the background, a command never builds the presentation to compare it: only a saved, unsent checkpoint
+ // asks for a publisher. Otherwise the command publishes a changed presentation itself, as before #1014.
+ if (checkpointInBackground()) { if (state.checkpoint) scheduleCheckpoint(root, file); }
+ else if (state.checkpoint || state.presentationDigest !== presentationDigest(relayPresentation(root))) await publishCheckpoint(root, file, state, io);
await deliverDeviceWraps(root, io);
return summary(root, state);
}
diff --git a/test/relay-checkpoint.test.js b/test/relay-checkpoint.test.js
new file mode 100644
index 00000000..c862e55b
--- /dev/null
+++ b/test/relay-checkpoint.test.js
@@ -0,0 +1,65 @@
+/** A move sends only its own event; one background publisher sends the checkpoint once moves go quiet [H5]. */
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { relayClientFixture } from './relay-client-fixture.js';
+import { CHECKPOINT_BACKGROUND_ENV } from '../src/relay-checkpoint.js';
+
+/** Whether a relay call uploads a checkpoint: an API1 state write or an API2 page publish. */
+function checkpointUpload(call) {
+ return call.method === 'PUT' && /^\/api\/v1\/boards\/[0-9a-f]{32}\/state$/u.test(call.path ?? '')
+ || call.method === 'POST' && /^\/api\/v2\/boards\/[0-9a-f]{32}\/uploads\/[^/]+\/publish$/u.test(call.path ?? '');
+}
+
+/** Wait until the background publisher has uploaded at least `uploads` checkpoints since `from` and finished. */
+async function publisherDone(box, from, uploads) {
+ const directory = dirname(box.linkFile);
+ const deadline = Date.now() + 60_000;
+ while (Date.now() < deadline) {
+ if (box.calls.slice(from).filter(checkpointUpload).length >= uploads && !existsSync(join(directory, 'relay-checkpoint.pid'))) return;
+ await new Promise(next => setTimeout(next, 100));
+ }
+ const log = join(directory, 'relay-checkpoint.log');
+ assert.fail(`the background publisher sent no checkpoint: ${existsSync(log) ? readFileSync(log, 'utf8') : 'no publisher log'}`);
+}
+
+test('a move on a large board sends only its event and never the checkpoint [H5]', async (t) => {
+ // The runner keeps checkpoints inside commands, like the view; this case opts in to the background publisher.
+ const inline = process.env[CHECKPOINT_BACKGROUND_ENV];
+ delete process.env[CHECKPOINT_BACKGROUND_ENV];
+ t.after(() => { if (inline === undefined) delete process.env[CHECKPOINT_BACKGROUND_ENV]; else process.env[CHECKPOINT_BACKGROUND_ENV] = inline; });
+ const box = await relayClientFixture(t);
+
+ // Seed the presentation's heaviest part, as on the 22 Oct board: 20,000 shouts.
+ const db = new DatabaseSync(join(box.root, '.git', 'pullboard', 'board.sqlite'));
+ const insert = db.prepare('INSERT INTO shout(shout_from, shout_to, shout_text, shout_at) VALUES (?, ?, ?, ?)');
+ db.exec('BEGIN');
+ for (let index = 0; index < 20_000; index += 1) insert.run('coordinator', 'all', `seeded shout ${index} with some ordinary words in it`, new Date(Date.UTC(2026, 9, 22, 0, 0, index % 60)).toISOString());
+ db.exec('COMMIT');
+ db.close();
+ await box.link();
+
+ // One move, then let its checkpoint go out, so the burst below starts from a covered board.
+ const warm = box.calls.length;
+ assert.equal((await box.cli('shout', 'all', 'warm up')).code, 0);
+ await publisherDone(box, warm, 1);
+
+ const before = box.calls.length;
+ for (let index = 1; index <= 10; index += 1) {
+ const from = box.calls.length;
+ const started = performance.now();
+ const moved = await box.cli('shout', 'all', `burst ${index}`);
+ const elapsed = performance.now() - started;
+ assert.equal(moved.code, 0, JSON.stringify(moved.document));
+ const sent = box.calls.slice(from);
+ assert.equal(sent.filter(checkpointUpload).length, 0, `move ${index} uploaded no checkpoint`);
+ const bytes = sent.reduce((total, call) => total + (call.requestBytes ?? 0), 0);
+ assert.ok(bytes < 64 * 1024, `move ${index} sent ${bytes} bytes, under 64 KB`);
+ assert.ok(elapsed < 1000, `move ${index} returned in ${Math.round(elapsed)} ms, under one second`);
+ }
+ await publisherDone(box, before, 1);
+ await new Promise(next => setTimeout(next, 2_000)); // budget: a second quiet period, so a second upload would show.
+ assert.equal(box.calls.slice(before).filter(checkpointUpload).length, 1, 'ten moves in a burst produced one checkpoint upload');
+});
diff --git a/test/relay-client-fixture.js b/test/relay-client-fixture.js
index f76cf77f..83d77f56 100644
--- a/test/relay-client-fixture.js
+++ b/test/relay-client-fixture.js
@@ -375,10 +375,13 @@ globalThis.fetch = function tracedFetch(input, init) {
}
return end(chunk, ...args);
};
- res.once('finish', () => recordResponse({ method: req.method, path: req.url,
- request: Buffer.concat(requestChunks), response: Buffer.concat(responseChunks) }));
- calls.push({ method: req.method, path: req.url, accept: req.headers.accept ?? '', engine: req.headers['x-pullboard-engine'],
- browser: String(req.headers.cookie ?? '').includes('pb_session=') });
+ const call = { method: req.method, path: req.url, accept: req.headers.accept ?? '', engine: req.headers['x-pullboard-engine'],
+ browser: String(req.headers.cookie ?? '').includes('pb_session=') };
+ res.once('finish', () => {
+ call.requestBytes = Buffer.concat(requestChunks).length; // What the client sent, for size bounds (#1014).
+ recordResponse({ method: req.method, path: req.url, request: Buffer.concat(requestChunks), response: Buffer.concat(responseChunks) });
+ });
+ calls.push(call);
if (stallApi && (req.url ?? '').startsWith('/api/')) { request.resume(); await new Promise(() => {}); }
if (legacySnapshotApi && req.method === 'GET' && req.url === '/api/v2') {
res.writeHead(legacySnapshotApi === 'bad-route' ? 400 : 200, { 'content-type': 'application/json' });