cursedbelt-server 1.1.0 → 2.0.0

package/src/server/sync/planner.ts

@@ -1,12 +1,31 @@
 /**
- * The pure loop planner — vault's `planNextSync`, unchanged in spirit: back off after
- * a failure, else honor a debounced dirty flag, else the steady interval. Pure so
- * the timer is a thin wrapper and this is fake-clock testable.
+ * The pure loop planner: back off after a failure, else honor a debounced dirty
+ * flag, else **do not wake at all**. Pure so the timer is a thin wrapper and this
+ * is fake-clock testable.
+ *
+ * ── 🔴 There is no steady interval, and that is the whole point ──────────────────
+ *
+ * This used to end with `else: the steady interval` — `intervalMs: 5 * 60_000`, a
+ * dial at a configured peer every five minutes whether or not either side had
+ * anything to say. The owner ruled that out on 2026-09-15: *"There should be no
+ * polling in cb unless you can make some good case for it that beats the api
+ * option."* No such case was found, so the field is gone rather than defaulted to
+ * zero — a config key that reintroduces a poll is a config key somebody sets.
+ *
+ * What is left are the two wake-ups that have a REASON, and neither is a poll:
+ *
+ *   · **debounce** — there are local ops to push. The side that has news says so;
+ *     the wait only coalesces a burst.
+ *   · **backoff** — the last attempt failed. This runs *only while disconnected*,
+ *     never against a healthy peer, which is exactly the carve-out the ruling
+ *     names for a reconnect timer.
+ *
+ * A clean, healthy loop returns `waitMs: null` — "nothing to do, do not book a
+ * timer" — and the process goes quiet until something happens. News from the far
+ * side arrives over `./signal`, not by asking.
  */
 
 export interface SyncLoopConfig {
-	/** Steady poll cadence when reachable and idle. */
-	intervalMs: number;
 	/** How long after a local write to wait before syncing, so a burst coalesces. */
 	debounceMs: number;
 	/** First backoff step after a failure. */
@@ -16,7 +35,6 @@ export interface SyncLoopConfig {
 }
 
 export const DEFAULT_LOOP: SyncLoopConfig = {
-	intervalMs: 5 * 60_000,
 	debounceMs: 3_000,
 	backoffBaseMs: 30_000,
 	backoffMaxMs: 30 * 60_000,
@@ -31,25 +49,44 @@ export interface SyncLoopState {
 	dirtySince: number | null;
 }
 
+/**
+ * What the loop should do next.
+ *
+ * 🔴 `waitMs: null` means **do not schedule anything** — not "wait zero" and not
+ * "wait forever". It is the idle state, and a caller that turns it into a number
+ * has put the poll back.
+ */
+export interface SyncPlan {
+	runNow: boolean;
+	/** Milliseconds until the next wake-up, or `null` when there is no reason to wake. */
+	waitMs: number | null;
+	/** Why the loop will wake — `null` alongside `waitMs: null`. */
+	reason: "retry" | "dirty" | null;
+}
+
 export function planNextSync(
 	state: SyncLoopState,
 	now: number,
 	cfg: SyncLoopConfig = DEFAULT_LOOP,
-): { runNow: boolean; waitMs: number } {
+): SyncPlan {
 	if (state.consecutiveFailures > 0) {
 		const step = Math.min(
 			cfg.backoffMaxMs,
 			cfg.backoffBaseMs * 2 ** (state.consecutiveFailures - 1),
 		);
 		const due = state.lastAttempt + step;
-		return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+		return now >= due
+			? { runNow: true, waitMs: 0, reason: "retry" }
+			: { runNow: false, waitMs: due - now, reason: "retry" };
 	}
 	if (state.dirtySince !== null) {
 		const due = state.dirtySince + cfg.debounceMs;
-		return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+		return now >= due
+			? { runNow: true, waitMs: 0, reason: "dirty" }
+			: { runNow: false, waitMs: due - now, reason: "dirty" };
 	}
-	const due = state.lastAttempt + cfg.intervalMs;
-	return now >= due ? { runNow: true, waitMs: 0 } : { runNow: false, waitMs: due - now };
+	// Clean and healthy: nothing to push, nothing to retry. Stay silent.
+	return { runNow: false, waitMs: null, reason: null };
 }
 
 /** A peer that is asleep (the nightly EC2 window) or an internet-less Mac is NORMAL,

package/src/server/sync/signal.spec.ts

@@ -0,0 +1,306 @@
+/**
+ * The replacement for the dialer, proven to be one: a connected client asks the
+ * peer for NOTHING, and still learns the moment its log grows.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	connectSyncSignal,
+	createSyncSignalHub,
+	encodeNewsFrame,
+	parseNewsFrame,
+	signalStream,
+	type SyncNews,
+} from "./signal";
+
+const news = (head: number): SyncNews => ({ head, instanceId: "peer-a" });
+
+describe("the signal hub", () => {
+	test("announces to every subscriber and stops on unsubscribe", () => {
+		const hub = createSyncSignalHub();
+		const seen: SyncNews[] = [];
+		const off = hub.subscribe((n) => seen.push(n));
+		hub.subscribe((n) => seen.push(n));
+		expect(hub.subscriberCount).toBe(2);
+		hub.announce(news(1));
+		expect(seen).toHaveLength(2);
+		off();
+		off(); // idempotent
+		expect(hub.subscriberCount).toBe(1);
+		hub.announce(news(2));
+		expect(seen).toHaveLength(3);
+	});
+
+	test("a throwing listener is dropped, never raised to the producer", () => {
+		// `announce` may be called from inside an op-log write; it can never throw up.
+		const hub = createSyncSignalHub();
+		const seen: SyncNews[] = [];
+		hub.subscribe(() => {
+			throw new Error("this transport is gone");
+		});
+		hub.subscribe((n) => seen.push(n));
+		expect(() => hub.announce(news(1))).not.toThrow();
+		expect(seen).toHaveLength(1);
+		expect(hub.subscriberCount).toBe(1);
+	});
+
+	test("a closed hub accepts no more subscribers and announces nothing", () => {
+		const hub = createSyncSignalHub();
+		const seen: SyncNews[] = [];
+		hub.subscribe((n) => seen.push(n));
+		hub.close();
+		expect(hub.subscriberCount).toBe(0);
+		hub.announce(news(1));
+		hub.subscribe((n) => seen.push(n));
+		hub.announce(news(2));
+		expect(seen).toHaveLength(0);
+	});
+});
+
+describe("frame coding", () => {
+	test("a news frame round-trips", () => {
+		expect(parseNewsFrame(encodeNewsFrame(news(7)).trimEnd())).toEqual(news(7));
+	});
+
+	test("a heartbeat and any malformed frame parse to null, never to a fake event", () => {
+		expect(parseNewsFrame(": keep-alive")).toBeNull();
+		expect(parseNewsFrame("event: news\ndata: not json")).toBeNull();
+		expect(parseNewsFrame("event: news\ndata: {}")).toBeNull();
+		expect(parseNewsFrame('event: other\ndata: {"head":1,"instanceId":"x"}')).toBeNull();
+		expect(parseNewsFrame('data: {"head":1,"instanceId":"x"}')).toBeNull();
+	});
+});
+
+/** Read whatever bytes are currently available on a stream, without blocking. */
+async function drain(stream: ReadableStream<Uint8Array>, reads: number): Promise<string> {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let out = "";
+	for (let i = 0; i < reads; i++) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		out += decoder.decode(value, { stream: true });
+	}
+	void reader.cancel();
+	return out;
+}
+
+describe("the SSE stream", () => {
+	test("opens with the catch-up frame, then carries announcements", async () => {
+		const hub = createSyncSignalHub();
+		const stream = signalStream(hub, {
+			initial: news(10),
+			setIntervalFn: () => 0,
+			clearIntervalFn: () => undefined,
+		});
+		// Announce after `start` has run and subscribed.
+		await Promise.resolve();
+		hub.announce(news(11));
+		const text = await drain(stream, 2);
+		expect(text).toContain('"head":10');
+		expect(text).toContain('"head":11');
+	});
+
+	test("the heartbeat is a comment frame — it wakes no handler and asks nothing", async () => {
+		const hub = createSyncSignalHub();
+		let beat: (() => void) | null = null;
+		const stream = signalStream(hub, {
+			heartbeatMs: 1,
+			setIntervalFn: (fn) => {
+				beat = fn;
+				return 1;
+			},
+			clearIntervalFn: () => undefined,
+		});
+		await Promise.resolve();
+		expect(beat).not.toBeNull();
+		beat?.();
+		const text = await drain(stream, 1);
+		expect(text).toBe(": keep-alive\n\n");
+		expect(parseNewsFrame(text)).toBeNull();
+	});
+
+	test("an aborted request tears the subscription down — no leaked interval", async () => {
+		const hub = createSyncSignalHub();
+		const controller = new AbortController();
+		let cleared = 0;
+		signalStream(hub, {
+			signal: controller.signal,
+			setIntervalFn: () => 1,
+			clearIntervalFn: () => {
+				cleared += 1;
+			},
+		});
+		await Promise.resolve();
+		expect(hub.subscriberCount).toBe(1);
+		controller.abort();
+		expect(hub.subscriberCount).toBe(0);
+		expect(cleared).toBe(1);
+	});
+});
+
+/** A `fetch` that answers with a stream the test drives by hand. */
+function fakePeer() {
+	let push: ((chunk: string) => void) | null = null;
+	let end: (() => void) | null = null;
+	let calls = 0;
+	const encoder = new TextEncoder();
+	const fetchImpl = (async () => {
+		calls += 1;
+		const body = new ReadableStream<Uint8Array>({
+			start(controller) {
+				push = (chunk) => controller.enqueue(encoder.encode(chunk));
+				end = () => {
+					try {
+						controller.close();
+					} catch {
+						// already closed
+					}
+				};
+			},
+		});
+		return new Response(body, { status: 200 });
+	}) as unknown as typeof fetch;
+	return {
+		fetchImpl,
+		calls: () => calls,
+		push: (chunk: string) => push?.(chunk),
+		end: () => end?.(),
+	};
+}
+
+const settle = async () => {
+	for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0));
+};
+
+describe("the signal client", () => {
+	/**
+	 * 🔴 The measurement the 2026-09-15 ruling is about, on the replacement rather
+	 * than on the thing it replaced. The old fast lane cost one request every 20
+	 * seconds — 4,320 a day, 68 % of `vault`'s entire traffic. This asserts the new
+	 * one costs **one**, total, for as long as the connection holds, and that no
+	 * amount of elapsed time changes that: a connected client never sleeps, so a
+	 * `sleepFn` that is never called IS the proof there is no retry cadence running
+	 * underneath a healthy stream.
+	 */
+	test("a connected client issues exactly ONE outbound request, forever", async () => {
+		const peer = fakePeer();
+		let sleeps = 0;
+		const seen: SyncNews[] = [];
+		const client = connectSyncSignal({
+			basePath: "https://peer.example/api/sync",
+			token: "t",
+			selfId: "mac",
+			onNews: (n) => seen.push(n),
+			fetchImpl: peer.fetchImpl,
+			sleepFn: async (ms) => {
+				sleeps += 1;
+				void ms;
+			},
+		});
+		await settle();
+		expect(client.connected).toBe(true);
+		expect(client.requestCount).toBe(1);
+
+		// 24 hours' worth of the old cadence would be 4,320 requests. Drive the
+		// peer instead: news arrives on the SAME connection, costing nothing.
+		for (let i = 0; i < 4_320; i++) {
+			peer.push(encodeNewsFrame(news(i)));
+		}
+		await settle();
+		expect(seen).toHaveLength(4_320);
+		expect(
+			client.requestCount,
+			"a connected client asked the peer for something — that is the poll coming back",
+		).toBe(1);
+		expect(sleeps, "a connected client must never be in a backoff sleep").toBe(0);
+		expect(peer.calls()).toBe(1);
+		client.stop();
+	});
+
+	test("a dropped stream reconnects with jittered backoff — the allowed timer", async () => {
+		const peer = fakePeer();
+		const waits: number[] = [];
+		const client = connectSyncSignal({
+			basePath: "https://peer.example/api/sync",
+			token: "t",
+			selfId: "mac",
+			onNews: () => undefined,
+			fetchImpl: peer.fetchImpl,
+			backoffBaseMs: 1_000,
+			jitterFn: () => 0, // deterministic: the low end of the jitter window
+			sleepFn: async (ms) => {
+				waits.push(ms);
+			},
+		});
+		await settle();
+		expect(client.requestCount).toBe(1);
+		peer.end(); // the peer goes away
+		await settle();
+		// It reconnected, and it waited before doing so.
+		expect(client.requestCount).toBeGreaterThan(1);
+		expect(waits.length).toBeGreaterThan(0);
+		expect(waits[0]).toBeGreaterThan(0);
+		client.stop();
+	});
+
+	test("a heartbeat frame is not mistaken for news", async () => {
+		const peer = fakePeer();
+		const seen: SyncNews[] = [];
+		const client = connectSyncSignal({
+			basePath: "https://peer.example/api/sync",
+			token: "t",
+			selfId: "mac",
+			onNews: (n) => seen.push(n),
+			fetchImpl: peer.fetchImpl,
+			sleepFn: async () => undefined,
+		});
+		await settle();
+		peer.push(": keep-alive\n\n");
+		peer.push(": keep-alive\n\n");
+		await settle();
+		expect(seen).toHaveLength(0);
+		expect(client.connected).toBe(true);
+		client.stop();
+	});
+
+	test("a frame split across chunks is reassembled, not dropped", async () => {
+		const peer = fakePeer();
+		const seen: SyncNews[] = [];
+		const client = connectSyncSignal({
+			basePath: "https://peer.example/api/sync",
+			token: "t",
+			selfId: "mac",
+			onNews: (n) => seen.push(n),
+			fetchImpl: peer.fetchImpl,
+			sleepFn: async () => undefined,
+		});
+		await settle();
+		const frame = encodeNewsFrame(news(42));
+		peer.push(frame.slice(0, 12));
+		await settle();
+		expect(seen).toHaveLength(0);
+		peer.push(frame.slice(12));
+		await settle();
+		expect(seen).toEqual([news(42)]);
+		client.stop();
+	});
+
+	test("stop() ends the stream and books no further request", async () => {
+		const peer = fakePeer();
+		const client = connectSyncSignal({
+			basePath: "https://peer.example/api/sync",
+			token: "t",
+			selfId: "mac",
+			onNews: () => undefined,
+			fetchImpl: peer.fetchImpl,
+			sleepFn: async () => undefined,
+		});
+		await settle();
+		const before = client.requestCount;
+		client.stop();
+		peer.end();
+		await settle();
+		expect(client.requestCount).toBe(before);
+		expect(client.connected).toBe(false);
+	});
+});