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.

fix(relay): show pending moves until checkpoint arrives [H5,H16]

Corey Olsone95fde940dbc
diff --git a/relay/browser-client.js b/relay/browser-client.js
index 7ae00d38..efeee3b5 100644
--- a/relay/browser-client.js
+++ b/relay/browser-client.js
@@ -142,6 +142,46 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
Object.defineProperties(entry.state, Object.getOwnPropertyDescriptors(value));
}
+ /** Keep newer received events visible while only a native checkpoint may replace item state. */
+ function checkpointState(entry, state, sequence) {
+ const pending = (entry.state?.pendingEvents ?? []).filter(event => event.sequence > sequence);
+ delete state.pendingEvents;
+ if (pending.length) state.pendingEvents = pending;
+ const requests = (entry.state?.personRequests ?? []).filter(request => request.sequence > sequence);
+ if (requests.length) {
+ const known = new Set((state.personRequests ?? []).map(request => request.id));
+ state.personRequests = [...(state.personRequests ?? []), ...requests.filter(request => !known.has(request.id))];
+ }
+ return state;
+ }
+
+ /** Advance the checkpoint cursor independently of the already authenticated event prefix. */
+ function installCheckpoint(entry, state, sequence) {
+ installState(entry, checkpointState(entry, state, sequence));
+ entry.checkpointCursor = sequence;
+ entry.cursor = Math.max(entry.cursor, sequence);
+ }
+
+ /** Poll in the cursor queue without blocking later events while the native publisher is behind. */
+ function pendingCheckpoint(entry) {
+ if (entry.snapshotPolling || !entry.state?.pendingEvents?.length || access.signal.aborted) return;
+ entry.snapshotPolling = true;
+ entry.snapshotTimer = setTimeout(() => {
+ entry.snapshotTimer = null;
+ if (access.signal.aborted || paired.get(entry.id) !== entry) { entry.snapshotPolling = false; return; }
+ void enqueue(entry, async () => {
+ const previous = entry.checkpointCursor;
+ await snapshot(entry);
+ if (access.signal.aborted || paired.get(entry.id) !== entry) return;
+ notice();
+ if (entry.checkpointCursor !== previous) onUpdate();
+ }).catch(error => {
+ if (access.signal.aborted || paired.get(entry.id) !== entry) return;
+ failure = error.message; failureBoard = entry.id; notice();
+ }).finally(() => { entry.snapshotPolling = false; pendingCheckpoint(entry); });
+ }, 1000);
+ }
+
/** Discard decrypted memory and this document when relay authorization is lost. */
async function denied(error) {
if (accessLost) return;
@@ -206,6 +246,12 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
paragraph.textContent = text;
element.append(paragraph);
}
+ for (const entry of paired.values()) for (const event of entry.state?.pendingEvents ?? []) {
+ const paragraph = document.createElement('p');
+ const operation = String(event.operation).replace(/([a-z])([A-Z])/gu, '$1 $2').toLowerCase();
+ paragraph.textContent = 'Pending event #' + event.sequence + ' on ' + entry.repository + ': ' + operation + (event.title ? ' — ' + event.title : '');
+ element.append(paragraph);
+ }
// A phone has no local-view screen to fall back to: keep its shell and the real reason until a board is readable.
const root = document.documentElement;
const phoneWaiting = root.dataset.relayDevice === 'phone' && (!rendered || paired.size === 0);
@@ -251,11 +297,11 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
function historyFor(entry) {
entry.history ??= createPhoneHistory({
active: () => !accessLost && paired.get(entry.id) === entry,
- current: () => ({ id: entry.pages?.id, sequence: entry.cursor }),
+ current: () => ({ id: entry.pages?.id, sequence: entry.checkpointCursor }),
install(full, details) {
const state = presentationState(full, entry.id);
if (details) state.items = state.items.map(item => details.get(item.id) ?? item);
- installState(entry, { ...state, historyProgress: entry.history.status() });
+ installState(entry, checkpointState(entry, { ...state, historyProgress: entry.history.status() }, entry.checkpointCursor));
entry.historyChanged = true;
},
changed() {
@@ -303,12 +349,15 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
});
if (accessLost) throw accessError;
const unchanged = entry.pages?.id === page.id && entry.state;
- if (row.sequence >= entry.cursor && !unchanged) {
+ if (row.sequence >= entry.checkpointCursor && !unchanged) {
const value = await page.presentation();
if (accessLost) throw accessError;
- installState(entry, presentationState(value, entry.id));
- entry.shouts = null; entry.cursor = row.sequence;
+ installCheckpoint(entry, presentationState(value, entry.id), row.sequence);
+ entry.shouts = null;
+ } else if (unchanged && row.sequence > entry.checkpointCursor) {
+ installCheckpoint(entry, { ...entry.state }, row.sequence);
}
+ if (row.sequence < entry.checkpointCursor) return;
entry.pages = page;
const history = historyFor(entry);
history.queue(page, row.sequence);
@@ -321,23 +370,11 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
const state = snapshotState(value, entry.id);
if (accessLost) throw new Error('Sign in again to read this board.');
entry.snapshotTag = response.headers.get('etag');
- if (row.sequence >= entry.cursor) {
+ if (row.sequence >= entry.checkpointCursor) {
entry.history?.close(); entry.history = null; entry.pages = null; entry.pageCache?.clear();
- installState(entry, state);
+ installCheckpoint(entry, state, row.sequence);
entry.shouts = Array.isArray(value.presentation?.shouts) ? value.presentation.shouts : null;
- entry.cursor = row.sequence;
- }
- }
-
- /** Wait for an acknowledged device snapshot instead of consuming an event with no projection. */
- async function waitForSnapshot(entry, sequence) {
- const deadline = Date.now() + 15000;
- while (Date.now() < deadline) {
- await snapshot(entry);
- if (entry.state && entry.cursor >= sequence) return;
- await new Promise(resolveSnapshot => setTimeout(resolveSnapshot, 100));
}
- throw new Error('The relay snapshot has not caught up to this move. Retry this board.');
}
/** Apply a sealed presentation in strict sequence; newer executable formats are never guessed. */
@@ -372,13 +409,15 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
if (move.engine !== ENGINE_VERSION) throw new Refused('RELAY_ENGINE_VERSION', 'This board needs engine ' + move.engine + '; this browser reads engine ' + ENGINE_VERSION + '. Upgrade the browser client.');
if (move.presentation) {
entry.history?.close(); entry.history = null; entry.pages = null; entry.pageCache?.clear();
- installState(entry, presentationState(move.presentation, entry.id));
+ installCheckpoint(entry, presentationState(move.presentation, entry.id), row.event_id);
entry.shouts = Array.isArray(move.presentation.shouts) ? move.presentation.shouts : null;
entry.cursor = row.event_id;
} else {
- // A snapshot may be uploaded just after this ACK and compact the event immediately. Keep
- // the cursor where it is until a valid snapshot actually covers this row.
- await waitForSnapshot(entry, row.event_id);
+ const title = move.args?.find(value => value && typeof value === 'object' && typeof value.title === 'string')?.title;
+ entry.state.pendingEvents ??= [];
+ entry.state.pendingEvents.push({ sequence: row.event_id, operation: move.operation ?? move.event?.event_kind ?? 'move', ...(title ? { title } : {}) });
+ entry.cursor = row.event_id;
+ pendingCheckpoint(entry);
}
}
@@ -512,7 +551,7 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
if (paired.has(board.id) && pair?.board !== board.id && encodeBoardKey(paired.get(board.id).key) === encoded) continue;
if (!encoded) continue;
try {
- const entry = { id: board.id, repository: board.repository, key: decodeBoardKey(encoded), cursor: -1, state: null, shouts: null, outbox: null };
+ const entry = { id: board.id, repository: board.repository, key: decodeBoardKey(encoded), cursor: -1, checkpointCursor: -1, state: null, shouts: null, outbox: null };
await snapshot(entry);
await catchUp(entry);
if (accessLost) throw new Error('Sign in again to read this board.');
@@ -530,6 +569,7 @@ export async function createTransport({ onUpdate = () => {}, onOpenBoard = () =>
try { sessionStorage.removeItem(PENDING); } catch { /* Device storage can be unavailable. */ }
}
subscribe(entry);
+ pendingCheckpoint(entry);
} catch (error) {
if (['NO_BOARD', 'NO_SNAPSHOT'].includes(error?.code) || /\[(?:NO_BOARD|NO_SNAPSHOT)\]/u.test(error.message)) {
waitForFirstSnapshot({ id: board.id, repository: board.repository });
diff --git a/test/relay-browser-client.test.js b/test/relay-browser-client.test.js
index 7146c3cf..19083093 100644
--- a/test/relay-browser-client.test.js
+++ b/test/relay-browser-client.test.js
@@ -6,7 +6,7 @@ import { tmpdir, userInfo } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { gzipSync } from 'node:zlib';
-import { findChromeExecutable, relayWorkBudgetMs, startChrome } from './relay-browser-fixture.js';
+import { findChromeExecutable, startChrome } from './relay-browser-fixture.js';
/** The hosted page's real secure origin, answered from memory: no network is used. */
const ORIGIN = 'https://app.pullboard.dev/';
@@ -211,6 +211,36 @@ test('the sealed gzip snapshot decodes through a Response body, the way WebKit a
t.diagnostic('WebKit ran: ' + webkit);
});
+/** Publish the later checkpoint with the real API2 CLI writer inside the private fixture. */
+async function publishApi2Checkpoint(box, boardId, sequence) {
+ const before = relaySnapshot(box.root);
+ assert.equal(before.presentation.state.items.filter(item => item.title.startsWith('PHONE_PENDING_')).length, 3,
+ 'the local native projection contains all three acknowledged moves before publishing');
+
+ // The actual CLI runs inside relayClientFixture's isolated HOME/PULLBOARD_HOME and publishes through
+ // the configured production page writer; it never touches the user's page-cache directory.
+ const published = await box.cli('status');
+ assert.equal(published.code, 0, published.document?.error?.message);
+
+ const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
+ assert.equal(link.snapshotApiVersion, 2, 'the private board used the API2 paged snapshot writer');
+ const pageWrites = box.calls.filter(call => call.method === 'PUT'
+ && /^\/api\/v2\/boards\/[0-9a-f]{32}\/uploads\/[A-Za-z0-9-]+\/objects\/[0-9a-f]{64}$/u.test(call.path));
+ const publishes = box.calls.filter(call => call.method === 'POST'
+ && /^\/api\/v2\/boards\/[0-9a-f]{32}\/uploads\/[A-Za-z0-9-]+\/publish$/u.test(call.path));
+ assert.ok(pageWrites.length > 0 && publishes.length > 0,
+ 'actual API2 page objects and the root publish reached the private relay');
+
+ const state = await fetch(box.origin + '/api/v2/boards/' + boardId + '/state', {
+ headers: { authorization: 'Bearer ' + link.token, 'x-pullboard-engine': String(ENGINE_VERSION) },
+ });
+ assert.equal(state.status, 200, 'the private relay serves its API2 published head');
+ const head = await state.json();
+ assert.equal(head.state.apiVersion, 2);
+ assert.equal(head.state.sequence, sequence, 'the API2 root covers the exact final move position');
+ return head.state;
+}
+
/** Add one genuine sealed move to the private loopback relay and replay its acknowledged receipt locally. */
async function postAndApplyMove(box, link, key, sequence, move) {
const sealed = Buffer.from(await seal(key, new TextEncoder().encode(JSON.stringify(move)), {
@@ -235,11 +265,11 @@ async function postAndApplyMove(box, link, key, sequence, move) {
return event;
}
-test('the phone shows moves past its checkpoint as pending [H5,H16]', {
+for (const apiVersion of [1, 2]) test('the phone shows moves past its checkpoint as pending (API' + apiVersion + ') [H5,H16]', {
skip: !findChromeExecutable() && 'Chrome is not installed',
}, async t => {
const box = await relayClientFixture(t);
- box.legacySnapshotApi(); // This case explicitly publishes sealed API1 checkpoints.
+ if (apiVersion === 1) box.legacySnapshotApi(); // Keep explicit historical and current paged wire coverage.
const initialTitle = 'PHONE_CHECKPOINT_INITIAL_1113';
const pendingTitles = ['PHONE_PENDING_ONE_1113', 'PHONE_PENDING_TWO_1113', 'PHONE_PENDING_THREE_1113'];
assert.equal((await box.cli('add', box.lane, initialTitle)).code, 0);
@@ -247,7 +277,7 @@ test('the phone shows moves past its checkpoint as pending [H5,H16]', {
const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));
const key = decodeBoardKey(readFileSync(box.keyFile, 'utf8').trim());
const credential = link.agentTokens.coordinator.token;
- const stateResponse = await fetch(box.origin + '/api/v1/boards/' + link.board + '/state', {
+ const stateResponse = await fetch(box.origin + '/api/v' + apiVersion + '/boards/' + link.board + '/state', {
headers: { authorization: 'Bearer ' + credential, 'x-pullboard-engine': String(ENGINE_VERSION) },
});
assert.equal(stateResponse.status, 200, 'the checkpoint at N is present before phone startup');
@@ -291,16 +321,18 @@ test('the phone shows moves past its checkpoint as pending [H5,H16]', {
const checkpointN3 = relaySnapshot(box.root);
assert.equal(checkpointN3.presentation.state.items.filter(item => pendingTitles.includes(item.title)).length, 3,
'the later native checkpoint includes all three acknowledged operations');
- const sealedCheckpoint = Buffer.from(await seal(key, new TextEncoder().encode(JSON.stringify(checkpointN3)), {
- boardId: link.board, kind: 'snapshot', sequence: checkpointN + 3,
- })).toString('base64url');
- const published = await fetch(box.origin + '/api/v1/boards/' + link.board + '/state', {
- method: 'PUT', headers: {
- authorization: 'Bearer ' + credential,
- 'x-pullboard-engine': String(ENGINE_VERSION), 'content-type': 'application/json',
- }, body: JSON.stringify({ sequence: checkpointN + 3, sealed: sealedCheckpoint }),
- });
- assert.equal(published.status, 200, 'the private relay accepts checkpoint N+3');
+ if (apiVersion === 1) {
+ const sealedCheckpoint = Buffer.from(await seal(key, new TextEncoder().encode(JSON.stringify(checkpointN3)), {
+ boardId: link.board, kind: 'snapshot', sequence: checkpointN + 3,
+ })).toString('base64url');
+ const published = await fetch(box.origin + '/api/v1/boards/' + link.board + '/state', {
+ method: 'PUT', headers: {
+ authorization: 'Bearer ' + credential,
+ 'x-pullboard-engine': String(ENGINE_VERSION), 'content-type': 'application/json',
+ }, body: JSON.stringify({ sequence: checkpointN + 3, sealed: sealedCheckpoint }),
+ });
+ assert.equal(published.status, 200, 'the private relay accepts checkpoint N+3');
+ } else await publishApi2Checkpoint(box, link.board, checkpointN + 3);
await chrome.waitFor(pendingTitles.map(title => 'document.querySelector("#chain")?.textContent.includes(' + JSON.stringify(title) + ')').join(' && '));
const settledView = await chrome.evaluate(`(() => ({
items: Array.from(document.querySelectorAll('#chain [data-item]'), row => ({ id: row.dataset.item, title: row.getAttribute('title') })),