import test from 'node:test'; import assert from 'node:assert/strict'; import { createWorldClock } from './worldClock.js'; import { createSnapshotTimeline, SNAPSHOT_HOLD_MARGIN_MS, SNAPSHOT_PREFETCH_MS, SNAPSHOT_RETRY_MS, SNAPSHOT_WAIT_MS, snapshotAnswer, } from './snapshotTimeline.js'; const STEP = 10_000; const WALL = Date.UTC(2026, 10, 1, 12); function harness({ timeline = true, coverage, spanMs, stepMs = STEP, live = () => true, } = {}) { const t = { wall: WALL, mono: 1_000, timers: new Map(), nextId: 1, }; const clock = createWorldClock({ now: () => t.wall, monotonicNow: () => t.mono, setInterval: () => 0, clearInterval: () => {}, requestFrame: null, cancelFrame: null, }); let span = coverage === undefined ? { start: WALL - 3_600_000, end: WALL } : coverage; const coverageListeners = new Set(); const source = { getSnapshot() {}, ...(timeline && { timeline: { coverage: () => span, stepMs, ...(spanMs && { spanMs }), subscribe(listener) { coverageListeners.add(listener); return () => coverageListeners.delete(listener); }, }, }), }; const calls = []; const pending = []; const timers = { setTimeout: (fn, ms) => { const id = t.nextId++; t.timers.set(id, { fn, at: t.mono + ms }); return id; }, clearTimeout: (id) => t.timers.delete(id), }; const follower = createSnapshotTimeline({ id: 'flights', clock, source: () => source, load: (atMs, { signal, replace }) => new Promise((resolve, reject) => { calls.push({ type: 'load', atMs, replace }); pending.push({ atMs, replace, signal, resolve, reject }); }), clear: () => calls.push({ type: 'clear' }), resumeLive: () => { calls.push({ type: 'live' }); return live(); }, now: () => t.mono, ...timers, }); return { t, clock, follower, calls, pending, setCoverage(next) { span = next; for (const listener of coverageListeners) listener(); }, coverageListeners, advance(ms) { t.wall += ms; t.mono += ms; for (const [id, timer] of [...t.timers]) { if (timer.at > t.mono) continue; t.timers.delete(id); timer.fn(); } }, async answer(index = 0, value = true) { pending.splice(index, 1)[0].resolve(value); await flush(); }, }; } const flush = () => new Promise((resolve) => setImmediate(resolve)); const loads = (calls) => calls.filter((call) => call.type === 'load'); test('a source with no timeline never follows the clock nor asks for a time', async () => { const h = harness({ timeline: false }); h.follower.start(); assert.equal(h.follower.timeline, null); assert.equal(h.clock.follows('flights'), false); assert.equal(h.clock.coverage(), null); h.clock.seek(WALL - 600_000); h.clock.play(); h.advance(30_000); h.clock.goLive(); await flush(); assert.equal(h.follower.active(), false); assert.deepEqual(h.calls, []); h.follower.stop(); }); test('at the live edge a layer with a timeline only follows and registers', async () => { const h = harness(); h.follower.start(); await flush(); assert.equal(h.clock.follows('flights'), true); assert.deepEqual(h.clock.coverage(), { start: WALL - 3_600_000, end: WALL, marks: [], markDetails: [], }); assert.equal(h.follower.active(), false); assert.deepEqual(h.calls, []); h.follower.stop(); assert.equal(h.clock.follows('flights'), false); assert.equal(h.clock.coverage(), null); }); test('a seek asks for the step at or before the time, holding play while it loads', async () => { const h = harness(); h.follower.start(); const at = WALL - 600_000 + 4_321; h.clock.seek(at); await flush(); assert.equal(h.follower.active(), true); assert.deepEqual(loads(h.calls), [ { type: 'load', atMs: WALL - 600_000, replace: true }, ]); h.clock.play(); h.advance(2_000); assert.equal(h.clock.now(), at, 'play waits on the snapshot'); assert.equal(h.clock.getState().buffering, true); await h.answer(); assert.equal(h.clock.getState().buffering, false); h.follower.stop(); }); test('a seek back replaces the contacts and an older answer is dropped', async () => { const h = harness(); h.follower.start(); h.clock.seek(WALL - 600_000); await flush(); const first = h.pending[0]; h.clock.seek(WALL - 1_200_000); await flush(); assert.equal(first.signal.aborted, true, 'the older load is cancelled'); first.resolve(true); await flush(); assert.deepEqual( loads(h.calls).map(({ atMs, replace }) => [atMs, replace]), [ [WALL - 600_000, true], [WALL - 1_200_000, true], ], ); await h.answer(1); // Going backwards in time is a jump too, even without a seek. h.clock.seek(WALL - 1_300_000); await flush(); assert.equal(loads(h.calls).at(-1).replace, true); h.follower.stop(); }); test('playing on asks for the next step and play does not pass it unloaded', async () => { const h = harness(); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.play(); h.advance(100); // A tick: the clock tells its listeners as play goes on. h.clock.coverageChanged(); await flush(); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at + STEP, replace: false, }); h.advance(STEP * 2); assert.equal(h.clock.now(), at + STEP, 'gated at the step still loading'); h.clock.coverageChanged(); assert.equal(h.clock.getState().buffering, true); await h.answer(h.pending.length - 1); assert.equal(h.clock.getState().buffering, false); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at + 2 * STEP, replace: false, }); // A step that never comes holds play for at most SNAPSHOT_WAIT_MS. h.advance(STEP * 2); h.clock.coverageChanged(); assert.equal(h.clock.getState().buffering, true); h.advance(SNAPSHOT_WAIT_MS); assert.equal(h.clock.getState().buffering, false); h.advance(1_000); assert.ok(h.clock.now() > at + 2 * STEP, 'play went on without it'); h.follower.stop(); }); test('a failed snapshot clears the time and is asked again later', async () => { const h = harness(); h.follower.start(); h.clock.seek(WALL - 600_000); await flush(); await h.answer(0, false); assert.deepEqual(h.calls.at(-1), { type: 'clear' }); assert.equal(loads(h.calls).length, 1); h.advance(SNAPSHOT_RETRY_MS); await flush(); assert.equal(loads(h.calls).length, 2); assert.equal(loads(h.calls)[1].replace, true); h.follower.stop(); }); test('outside coverage the layer is cleared and nothing loads; unknown coverage waits', async () => { const h = harness({ coverage: null }); h.follower.start(); h.clock.seek(WALL - 600_000); await flush(); assert.deepEqual(h.calls, [], 'no coverage yet: nothing loads or clears'); h.setCoverage({ start: WALL - 3_600_000, end: WALL }); await flush(); assert.deepEqual(loads(h.calls), [ { type: 'load', atMs: WALL - 600_000, replace: true }, ]); await h.answer(); h.clock.seek(WALL - 7_200_000); await flush(); assert.deepEqual(h.calls.at(-1), { type: 'clear' }); assert.equal(loads(h.calls).length, 1); h.follower.stop(); assert.equal(h.coverageListeners.size, 0); }); test('back at live the layer polls at once and keeps its contacts for the live snapshot', async () => { const h = harness(); h.follower.start(); h.clock.seek(WALL - 600_000); await flush(); const inflight = h.pending[0]; h.clock.goLive(); await flush(); assert.equal(inflight.signal.aborted, true); assert.deepEqual(h.calls.at(-1), { type: 'live' }); assert.equal( h.calls.some((call) => call.type === 'clear'), false, 'the live snapshot takes the place of the contacts; nothing is cleared', ); assert.equal(h.follower.active(), false); h.follower.stop(); }); test('back at live, a live snapshot that cannot be had clears the layer', async () => { for (const answer of [ () => false, () => Promise.resolve(false), () => Promise.reject(new Error('down')), ]) { const h = harness({ live: answer }); h.follower.start(); h.clock.seek(WALL - 600_000); await flush(); await h.answer(); h.clock.goLive(); await flush(); assert.deepEqual(h.calls.slice(-2), [{ type: 'live' }, { type: 'clear' }]); h.follower.stop(); } }); test('back at live, a live poll dropped for a newer one, or answered after leaving live, clears nothing', async () => { const dropped = harness({ live: () => Promise.reject( Object.assign(new Error('dropped'), { name: 'AbortError' }), ), }); dropped.follower.start(); dropped.clock.seek(WALL - 600_000); await flush(); await dropped.answer(); dropped.clock.goLive(); await flush(); assert.deepEqual(dropped.calls.at(-1), { type: 'live' }); dropped.follower.stop(); let fail; const late = harness({ live: () => new Promise((resolve) => (fail = () => resolve(false))), }); late.follower.start(); late.clock.seek(WALL - 600_000); await flush(); await late.answer(); late.clock.goLive(); await flush(); late.clock.seek(WALL - 1_200_000); await flush(); fail(); await flush(); assert.equal( late.calls.some((call) => call.type === 'clear'), false, 'the time shown now is not cleared by the old live answer', ); late.follower.stop(); }); test('a load the source drops for a newer one is no failure: nothing clears, it is asked again', async () => { const h = harness(); h.follower.start(); h.clock.seek(WALL - 600_000); await flush(); h.pending .shift() .reject(new DOMException('Superseded by a newer request', 'AbortError')); await flush(); assert.equal( h.calls.some((call) => call.type === 'clear'), false, 'the layer keeps what it shows', ); assert.equal(loads(h.calls).length, 1); h.advance(SNAPSHOT_RETRY_MS); await flush(); assert.equal(loads(h.calls).length, 2, 'the time is asked for again'); assert.equal(loads(h.calls)[1].replace, true); h.follower.stop(); }); test('a layer never has two loads out: the older is aborted before a newer starts', async () => { const h = harness(); h.follower.start(); const live = () => h.pending.filter(({ signal }) => !signal.aborted).length; h.clock.seek(WALL - 600_000); await flush(); await h.answer(); h.clock.play(); await flush(); assert.equal(live(), 1, 'the next step loads'); h.follower.reload(); await flush(); assert.equal(live(), 1, 'a reload drops it first'); h.clock.seek(WALL - 900_000); await flush(); assert.equal(live(), 1, 'a seek drops it first'); assert.equal(h.pending.length, 3); h.follower.stop(); assert.equal(live(), 0); }); test('a source that tells of a better answer has the paused time loaded again, not a playing one', async () => { const h = harness(); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); const before = loads(h.calls).length; for (const listener of h.coverageListeners) listener(); await flush(); assert.equal(loads(h.calls).length, before + 1); assert.equal(loads(h.calls).at(-1).atMs, at); await h.answer(h.pending.length - 1); h.clock.play(); const playing = loads(h.calls).length; for (const listener of h.coverageListeners) listener(); await flush(); assert.ok( loads(h.calls) .slice(playing) .every((call) => call.atMs !== at), 'playing, the time shown is not loaded again', ); h.clock.goLive(); await flush(); const live = loads(h.calls).length; for (const listener of h.coverageListeners) listener(); await flush(); assert.equal(loads(h.calls).length, live, 'live, nothing is loaded'); h.follower.stop(); }); test('with fixes either side, a move back within them asks for its step once, clearing nothing and holding nothing', async () => { const SPAN = 5 * STEP; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); assert.equal(loads(h.calls).length, 1); // Within the step loaded: the contacts move along their fixes. h.clock.seek(at + STEP / 2); h.clock.seek(at + 1_000); await flush(); assert.equal(loads(h.calls).length, 1); // Back two steps: the contacts move along their fixes, and the step there // stands in for every contact once it loads, bringing back any that left // after it. Nothing is cleared and play does not wait. const before = h.calls.length; h.clock.seek(at - 2 * STEP); await flush(); assert.deepEqual(h.calls.slice(before), [ { type: 'load', atMs: at - 2 * STEP, replace: true }, ]); assert.equal(h.clock.getState().buffering, false); // Moving within that step while it loads asks for nothing more. h.clock.seek(at - 2 * STEP + 1_000); await flush(); assert.equal(loads(h.calls).length, 2); await h.answer(); h.clock.seek(at - 2 * STEP + 2_000); await flush(); assert.equal(loads(h.calls).length, 2); // Playing on from there asks for the next step, as play does. h.clock.play(); h.advance(STEP - 2_000); h.clock.coverageChanged(); await flush(); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at - STEP, replace: false, }); await h.answer(); h.clock.pause(); // Paused past the outer half after the newest: the step there. const newest = loads(h.calls).at(-1).atMs; h.clock.seek(newest + 3 * STEP + 1_000); await flush(); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: newest + 3 * STEP, replace: false, }); await h.answer(); // Beyond the fixes is a jump: the time is shown afresh, play held. h.clock.seek(at - 60 * STEP); await flush(); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at - 60 * STEP, replace: true, }); h.follower.stop(); }); test('playing, a seek back within the fixes does not hold play on its step', async () => { const SPAN = 5 * STEP; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.play(); h.clock.seek(at - 2 * STEP + 1_000); await flush(); assert.equal(loads(h.calls).at(-1).atMs, at - 2 * STEP); h.advance(STEP / 4); h.clock.coverageChanged(); await flush(); assert.equal(h.clock.getState().buffering, false); h.follower.stop(); }); test('without a span every move back is a jump', async () => { const h = harness(); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.seek(at - STEP); await flush(); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at - STEP, replace: true, }); h.follower.stop(); }); test('a snapshot the loaded fixes do not reach starts the held stretch afresh', async () => { const SPAN = 5 * STEP; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 1_200_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.play(); h.advance(100); h.clock.coverageChanged(); await flush(); // The next step is slow: play holds near the end of the fixes, then goes // on without it, far past them. h.advance(SPAN); h.clock.coverageChanged(); h.advance(SNAPSHOT_WAIT_MS); h.advance(30 * STEP); h.clock.coverageChanged(); await h.answer(); const far = loads(h.calls).at(-1).atMs; assert.ok(far > at + STEP + 2 * SPAN, 'asked for a step past the fixes'); assert.equal( loads(h.calls).at(-1).replace, true, 'in place of every contact', ); await h.answer(); h.clock.pause(); // Back between the two: no snapshot's fixes cover it, so it is a jump. h.clock.seek(at + SPAN + 2 * STEP); await flush(); assert.equal(loads(h.calls).at(-1).replace, true); h.follower.stop(); }); test('the held stretch is kept to the newest stretch every contact covers', async () => { const SPAN = 5 * STEP; const h = harness({ spanMs: SPAN, coverage: { start: WALL - 6 * 3_600_000, end: WALL }, }); h.follower.start(); const at = WALL - 3 * 3_600_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.play(); // Playing on for well over TIMELINE_HELD_MS, a step at a time. for (let k = 0; k < 160; k++) { h.advance(STEP); h.clock.coverageChanged(); await flush(); while (h.pending.length) await h.answer(h.pending.length - 1); } h.clock.pause(); // Back to the first snapshot's time: past what is held, so a jump. h.clock.seek(at); await flush(); assert.equal(loads(h.calls).at(-1).replace, true); h.follower.stop(); }); test('a step a move back asked for that the source drops is asked again', async () => { const SPAN = 5 * STEP; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.seek(at - 2 * STEP); await flush(); const asked = loads(h.calls).length; h.pending .shift() .reject(Object.assign(new Error('dropped'), { name: 'AbortError' })); await flush(); h.advance(SNAPSHOT_RETRY_MS); await flush(); assert.equal(loads(h.calls).length, asked + 1); assert.equal(loads(h.calls).at(-1).atMs, at - 2 * STEP); h.follower.stop(); }); test('a step a move back asked for that fails clears nothing and is asked again while paused', async () => { const SPAN = 5 * STEP; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 600_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.seek(at - 3 * STEP - 1_000); await flush(); const asked = loads(h.calls).length; await h.answer(0, false); assert.equal( h.calls.some((call) => call.type === 'clear'), false, ); h.advance(SNAPSHOT_RETRY_MS); await flush(); assert.equal(loads(h.calls).length, asked + 1); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at - 4 * STEP, replace: true, }); h.follower.stop(); }); test('with fixes past each snapshot, play holds near their end, not at the step still loading', async () => { const SPAN = 600_000; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 1_800_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.play(); h.advance(100); h.clock.coverageChanged(); await flush(); assert.deepEqual(loads(h.calls).at(-1), { type: 'load', atMs: at + STEP, replace: false, }); // Past the step still loading: the newest snapshot's fixes carry them. h.advance(3 * STEP); h.clock.coverageChanged(); assert.ok(h.clock.now() > at + 3 * STEP); assert.equal(h.clock.getState().buffering, false); // Play holds a margin short of the end of those fixes, and waits there. h.advance(SPAN); assert.equal(h.clock.now(), at + SPAN - SNAPSHOT_HOLD_MARGIN_MS); h.clock.coverageChanged(); assert.equal(h.clock.getState().buffering, true); await h.answer(); assert.equal(h.clock.getState().buffering, false); h.follower.stop(); }); test('with fixes past each snapshot, a fast play asks for steps well ahead of the time', async () => { const SPAN = 600_000; const RATE = 60; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 1_800_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.setRate(RATE); h.clock.play(); h.advance(100); h.clock.coverageChanged(); await flush(); // Each step answered asks for the next until they reach far enough ahead. while (h.pending.length) await h.answer(); const ahead = RATE * SNAPSHOT_PREFETCH_MS; const newest = loads(h.calls).at(-1).atMs; const time = h.clock.now(); assert.ok(newest - time >= ahead, 'steps asked for ahead of the time'); assert.ok(newest - time < ahead + STEP, 'and no further'); assert.ok( loads(h.calls).every((call, k) => k === 0 || call.replace === false), 'each in step with the last, moving contacts on', ); h.follower.stop(); }); test('without fixes past each snapshot, a fast play still asks a step at a time', async () => { const h = harness(); h.follower.start(); const at = WALL - 1_800_000; h.clock.seek(at); await flush(); await h.answer(); h.clock.setRate(60); h.clock.play(); h.advance(10); h.clock.coverageChanged(); await flush(); assert.equal(loads(h.calls).at(-1).atMs, at + STEP); await h.answer(); assert.equal(h.pending.length, 1); assert.equal(loads(h.calls).at(-1).atMs, at + 2 * STEP); h.follower.stop(); }); test('play holds short of where the applied snapshot’s fixes actually reach, when that is short of the span', async () => { const SPAN = 600_000; const h = harness({ spanMs: SPAN }); h.follower.start(); const at = WALL - 1_800_000; h.clock.seek(at); await flush(); // Its records' fixes end two minutes after its time, not ten. await h.answer(0, { reachMs: at + 120_000 }); h.clock.play(); h.advance(100); h.clock.coverageChanged(); await flush(); h.advance(SPAN); assert.equal(h.clock.now(), at + 120_000 - SNAPSHOT_HOLD_MARGIN_MS); h.follower.stop(); }); test('a layer answers how far an applied snapshot’s fixes reach', () => { assert.equal(snapshotAnswer({ records: [{ id: 'a' }] }), true); assert.deepEqual( snapshotAnswer({ records: [ { fixes: [{ atMs: 3 }, { atMs: 9 }] }, { fixes: [{ atMs: 12 }, { atMs: 'x' }] }, { id: 'b' }, ], }), { reachMs: 12 }, ); // One record reaching far ahead does not stand for the rest. const records = Array.from({ length: 20 }, (_, k) => ({ fixes: [{ atMs: k === 0 ? 900 : 100 + k }], })); assert.deepEqual(snapshotAnswer({ records }), { reachMs: 118 }); });