cursedbelt-server 1.1.0 → 2.0.0

package/src/server/sync/signal.ts

@@ -0,0 +1,422 @@
+/**
+ * **The peer says it has news. Nobody asks.**
+ *
+ * This is the half of the replication story that deleting the dialer (`./timer`,
+ * `./http`'s old `GET /requested`) would otherwise have left open, and it is the
+ * reason that deletion costs nothing.
+ *
+ * ## The three ways, and why this is the one
+ *
+ * Push-from-the-Mac answers Mac → peer completely: the side that has news calls
+ * `markDirty()` and pushes. It does not answer **peer → Mac**, and something must:
+ *
+ * | | |
+ * |---|---|
+ * | the Mac polls an outbox | ❌ polling. Ruled out 2026-09-15 |
+ * | the peer dials the Mac | ❌ needs the Mac reachable — a tunnel, an open port, a laptop that cannot sleep. That is the thing we are trying to delete |
+ * | 🟢 **the Mac holds a stream open and the peer pushes down it** | ✅ the Mac is still purely a client: it dials **out**, listens on nothing, and no timer fires |
+ *
+ * So: one long-lived outbound connection, opened by the dialing half, carrying a
+ * `news` frame whenever the receiver's op log grows. The Mac's reaction is
+ * `syncNow()` — the push it would have made anyway, at the moment there is a reason
+ * for it instead of 4,320 times a day on the chance.
+ *
+ * ## 🔴 Two honest caveats, neither of which is a poll
+ *
+ *   · **A sleeping Mac drops the connection.** On wake it reconnects and catches up
+ *     from `since` — the same catch-up a push model needs anyway, so it costs
+ *     nothing extra. `since` is the receiver's head as the client last saw it.
+ *   · **The reconnect backoff is a timer.** It runs *only while disconnected*, never
+ *     against a healthy peer, and it is written below as an `await sleep()` in a
+ *     loop rather than a `setTimeout` that calls `fetch` — the shape matters,
+ *     because the second one is indistinguishable from the poll this file exists to
+ *     replace. A connected client issues **exactly one** outbound request for as
+ *     long as it stays connected, and `signal.spec.ts` measures that over 24
+ *     simulated hours.
+ *
+ * ## Why this is not `cursedbelt-cc`'s `serverPush.ts`
+ *
+ * `libs/cursedbelt-cc/src/server/stream/serverPush.ts` is the real tenant-scoped
+ * push tier — heartbeats, backpressure, SSE — and on shape it is exactly this.
+ * It is not imported here for a reason that survives the preference:
+ * `cursedbelt-server/sync` is a **leaf** whose only runtime dependency is `hono`
+ * (see `./index.ts`), and `cursedbelt-cc` is a separate published package with zero
+ * consumers today, parked whole. Importing it would make every app that wants an
+ * op log install the cc platform to get one — the precise trade `./index.ts` was
+ * split to refuse, and the one `leafSubpathsImportNothing.spec.ts` now gates.
+ *
+ * The hub below is therefore the same model at a tenth the surface: this channel
+ * carries one frame kind, to one peer, with no tenant dimension. If `cursedbelt-cc`
+ * ever gains consumers and the two packages can depend on each other, {@link
+ * SyncSignalHub} is a strict subset of `ServerPushHub` and swaps in without
+ * touching a producer.
+ *
+ * ## The Workers path, named and not required yet
+ *
+ * On Cloudflare the durable form of "the Mac holds a connection all day" is a
+ * **Durable Object with WebSocket Hibernation**: the socket stays open while the
+ * object is evicted from memory, so an idle connection is not billed for duration.
+ * That is what keeps this free at rest, and it is the shape task `195` (the Mac is
+ * a client, never an origin) lands on. Nothing here needs it today — SSE over the
+ * existing receiver works on Bun and on Workers alike — but the frame format below
+ * is deliberately transport-free so the move is a transport swap, not a protocol
+ * change.
+ */
+
+/** SSE frame headers. `x-accel-buffering` keeps nginx from holding the stream in a
+ *  proxy buffer, which turns a live channel into a silent one — the same trap that
+ *  makes a cached `200` sit over a dead origin elsewhere in this fleet. */
+export const SIGNAL_SSE_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+	"content-type": "text/event-stream",
+	"cache-control": "no-store",
+	connection: "keep-alive",
+	"x-accel-buffering": "no",
+});
+
+/**
+ * Comment-frame interval. Without it an idle stream dies silently behind a proxy
+ * with an idle timeout and the client never learns it should reconnect.
+ *
+ * 🔴 This is a heartbeat on an ALREADY-OPEN socket, not a request. It is row (c) of
+ * the 2026-09-15 ruling — a local housekeeping timer that issues no outbound
+ * request — and it is why that row had to be carved out explicitly: a rule that
+ * said "no `setInterval`" would have deleted the one mechanism that keeps a
+ * no-polling design alive.
+ */
+const HEARTBEAT_MS = 15_000;
+
+/** What the receiver tells the dialing half. One kind, deliberately. */
+export interface SyncNews {
+	/** The receiver's op-log head at the moment it announced. The client's `since`. */
+	head: number;
+	/** The announcing instance, so a client linked to several can tell them apart. */
+	instanceId: string;
+}
+
+export interface SyncSignalHub {
+	/** Tell every listener the log grew. Never throws, never blocks on a socket. */
+	announce(news: SyncNews): void;
+	/** Attach a listener. The returned handle is safe to call more than once. */
+	subscribe(listener: (news: SyncNews) => void): () => void;
+	/** Live subscriber count — the reconnect tests assert against this. */
+	readonly subscriberCount: number;
+	/** Drop every subscriber (server shutdown). */
+	close(): void;
+}
+
+export function createSyncSignalHub(): SyncSignalHub {
+	const listeners = new Set<(news: SyncNews) => void>();
+	let closed = false;
+	return {
+		announce(news) {
+			if (closed) return;
+			// Snapshot: a listener that unsubscribes itself mid-fanout (the normal
+			// teardown path) must not mutate the set being iterated.
+			for (const listener of [...listeners]) {
+				try {
+					listener(news);
+				} catch {
+					// A broken transport is that subscriber's problem, never the
+					// producer's: drop it and keep fanning out. An `announce` may be
+					// called from inside an op-log write, so it can never throw upward.
+					listeners.delete(listener);
+				}
+			}
+		},
+		subscribe(listener) {
+			if (closed) return () => undefined;
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		get subscriberCount() {
+			return listeners.size;
+		},
+		close() {
+			if (closed) return;
+			closed = true;
+			listeners.clear();
+		},
+	};
+}
+
+export interface SignalStreamOptions {
+	/** Overridden only in tests, so the heartbeat can be driven by hand. */
+	setIntervalFn?: (fn: () => void, ms: number) => unknown;
+	clearIntervalFn?: (handle: unknown) => void;
+	heartbeatMs?: number;
+	/** Cancels the stream (the request's abort signal). */
+	signal?: AbortSignal;
+	/**
+	 * Sent as the first frame so a client that reconnects after a sleep learns the
+	 * current head without a round trip. This is the `since` catch-up.
+	 */
+	initial?: SyncNews;
+}
+
+/**
+ * Bridge a hub subscription onto a `ReadableStream` of SSE bytes.
+ *
+ * The stream ends when the client disconnects (`signal`) or the hub closes; both
+ * paths run the same teardown, so a dropped connection cannot leave a subscription
+ * — or an interval — behind.
+ */
+export function signalStream(
+	hub: SyncSignalHub,
+	options: SignalStreamOptions = {},
+): ReadableStream<Uint8Array> {
+	const heartbeatMs = options.heartbeatMs ?? HEARTBEAT_MS;
+	const setIntervalFn = options.setIntervalFn ?? ((fn, ms) => setInterval(fn, ms));
+	const clearIntervalFn =
+		options.clearIntervalFn ??
+		((handle) => clearInterval(handle as ReturnType<typeof setInterval>));
+	const encoder = new TextEncoder();
+
+	let unsubscribe: () => void = () => undefined;
+	let heartbeat: unknown = null;
+	let done = false;
+
+	return new ReadableStream<Uint8Array>({
+		start(controller) {
+			const teardown = (): void => {
+				if (done) return;
+				done = true;
+				unsubscribe();
+				if (heartbeat !== null) clearIntervalFn(heartbeat);
+				heartbeat = null;
+				try {
+					controller.close();
+				} catch {
+					// Already closed by the runtime when the socket died — expected.
+				}
+			};
+
+			const write = (chunk: string): void => {
+				if (done) return;
+				try {
+					controller.enqueue(encoder.encode(chunk));
+				} catch {
+					teardown();
+				}
+			};
+
+			if (options.initial) write(encodeNewsFrame(options.initial));
+
+			unsubscribe = hub.subscribe((news) => {
+				write(encodeNewsFrame(news));
+			});
+
+			heartbeat = setIntervalFn(() => {
+				// A comment frame. It wakes no client-side handler and issues no
+				// request — it keeps proxies from calling the connection idle.
+				write(": keep-alive\n\n");
+			}, heartbeatMs);
+
+			if (options.signal) {
+				if (options.signal.aborted) teardown();
+				else options.signal.addEventListener("abort", teardown, { once: true });
+			}
+		},
+		cancel() {
+			done = true;
+			unsubscribe();
+			if (heartbeat !== null) clearIntervalFn(heartbeat);
+			heartbeat = null;
+		},
+	});
+}
+
+/** Serialize one announcement as an SSE frame. */
+export const encodeNewsFrame = (news: SyncNews): string =>
+	`event: news\ndata: ${JSON.stringify(news)}\n\n`;
+
+/** A ready-to-return SSE `Response` — what the receiver's `GET /signal` answers. */
+export const signalResponse = (
+	hub: SyncSignalHub,
+	options: SignalStreamOptions = {},
+): Response =>
+	new Response(signalStream(hub, options), { headers: { ...SIGNAL_SSE_HEADERS } });
+
+/* ----------------------------------------------------------------- the client */
+
+export interface SignalClientOptions {
+	/** Where the peer mounted its receiver, e.g. `https://peer.example/api/sync`. */
+	basePath: string;
+	/** The same bearer the rest of the sync surface uses. */
+	token: string;
+	/** This instance's id, echoed as `x-sync-peer` so the far side can label us. */
+	selfId: string;
+	/**
+	 * The peer has news. Wire this to {@link import("./timer").SyncTimerHandle.syncNow}
+	 * — the whole point is that a reconciliation now happens for a REASON.
+	 */
+	onNews: (news: SyncNews) => void;
+	fetchImpl?: typeof fetch;
+	/** First reconnect step. Doubles to {@link backoffMaxMs}. Default 1s. */
+	backoffBaseMs?: number;
+	/** Reconnect ceiling — an offline laptop settles here. Default 5 min. */
+	backoffMaxMs?: number;
+	/** Swapped in tests. Resolves after `ms`; never issues a request. */
+	sleepFn?: (ms: number) => Promise<void>;
+	/** Jitter in [0,1). Real randomness by default — see the note on the stampede. */
+	jitterFn?: () => number;
+	log?: (msg: string) => void;
+}
+
+export interface SignalClient {
+	/** Close the stream and stop reconnecting. Idempotent. */
+	stop(): void;
+	/** Whether a stream is open right now — the tests assert against this. */
+	readonly connected: boolean;
+	/** Outbound requests issued since start. 🔴 The number the ruling is about. */
+	readonly requestCount: number;
+}
+
+/**
+ * Hold one stream open against the peer, calling {@link SignalClientOptions.onNews}
+ * on every `news` frame, and reconnect with jittered backoff **while disconnected**.
+ *
+ * 🔴 Read the loop shape as load-bearing. The reconnect is `await sleep(ms)` inside
+ * an async loop, NOT a `setTimeout` whose callback calls `fetch`. The second shape
+ * is byte-for-byte what a poll looks like, and a reviewer — or a checker — cannot
+ * tell the two apart once it is written that way. Here, a connected client is
+ * parked on `reader.read()` and issues nothing; `requestCount` stops moving the
+ * moment a connection succeeds, and that is what `signal.spec.ts` asserts over 24
+ * simulated hours.
+ *
+ * The jitter is not decoration either: a fixed backoff across N clients recovering
+ * from the same outage is a synchronized stampede at the instant the peer comes
+ * back up — the worst possible moment to send it a thundering herd.
+ */
+export function connectSyncSignal(options: SignalClientOptions): SignalClient {
+	const doFetch = options.fetchImpl ?? fetch;
+	const base = options.basePath.replace(/\/$/, "");
+	const backoffBase = options.backoffBaseMs ?? 1_000;
+	const backoffMax = options.backoffMaxMs ?? 5 * 60_000;
+	const sleep = options.sleepFn ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+	const jitter = options.jitterFn ?? Math.random;
+	const log = options.log ?? (() => undefined);
+
+	let stopped = false;
+	let connected = false;
+	let requests = 0;
+	let failures = 0;
+	let abort: AbortController | null = null;
+
+	/** Open one stream and stay on it until it ends. Throws on any failure. */
+	const runOnce = async (): Promise<void> => {
+		const controller = new AbortController();
+		abort = controller;
+		requests += 1;
+		const response = await doFetch(`${base}/signal?peer=${encodeURIComponent(options.selfId)}`, {
+			// 🔴 A followed redirect is how a moved hostname became eight days of
+			// silence on the `/pull` side — see `./http.ts`'s header. Same rule here.
+			redirect: "manual",
+			headers: {
+				authorization: `Bearer ${options.token}`,
+				"x-sync-peer": options.selfId,
+				accept: "text/event-stream",
+			},
+			signal: controller.signal,
+		});
+		if (response.status >= 300 && response.status < 400) {
+			throw new Error(
+				`sync/signal: ${response.status} — the peer address redirects to ` +
+					`${response.headers.get("location") ?? "an unnamed destination"}.`,
+			);
+		}
+		if (!response.ok) throw new Error(`sync/signal: ${response.status}`);
+		if (!response.body) throw new Error("sync/signal: the peer sent no stream body");
+
+		connected = true;
+		failures = 0;
+		const reader = response.body.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+		try {
+			while (!stopped) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				// SSE frames are separated by a blank line. A partial tail stays in
+				// the buffer until the rest of it arrives.
+				let split = buffer.indexOf("\n\n");
+				while (split !== -1) {
+					const frame = buffer.slice(0, split);
+					buffer = buffer.slice(split + 2);
+					const news = parseNewsFrame(frame);
+					if (news) options.onNews(news);
+					split = buffer.indexOf("\n\n");
+				}
+			}
+		} finally {
+			connected = false;
+			try {
+				await reader.cancel();
+			} catch {
+				// The socket is already gone — that is the normal end of a stream.
+			}
+		}
+	};
+
+	/**
+	 * The supervisor. Every `await` here is either the open stream itself or a sleep
+	 * between failures; there is no path that waits on a healthy peer in order to
+	 * ask it something.
+	 */
+	const supervise = async (): Promise<void> => {
+		while (!stopped) {
+			try {
+				await runOnce();
+			} catch (error) {
+				if (stopped) return;
+				failures += 1;
+				if (failures === 1) {
+					log(
+						`[sync] signal stream lost — reconnecting. This is normal (peer asleep / offline): ` +
+							`${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+			if (stopped) return;
+			const step = Math.min(backoffMax, backoffBase * 2 ** Math.max(0, failures - 1));
+			await sleep(Math.round(step * (0.5 + jitter() * 0.5)));
+		}
+	};
+
+	void supervise();
+
+	return {
+		stop() {
+			stopped = true;
+			abort?.abort();
+			abort = null;
+		},
+		get connected() {
+			return connected;
+		},
+		get requestCount() {
+			return requests;
+		},
+	};
+}
+
+/** `event: news\ndata: {...}` → {@link SyncNews}, or null for a heartbeat/unknown. */
+export function parseNewsFrame(frame: string): SyncNews | null {
+	let isNews = false;
+	let data: string | null = null;
+	for (const line of frame.split("\n")) {
+		if (line.startsWith(":")) continue; // comment frame — the heartbeat
+		if (line.startsWith("event:")) isNews = line.slice(6).trim() === "news";
+		else if (line.startsWith("data:")) data = line.slice(5).trim();
+	}
+	if (!isNews || data === null) return null;
+	try {
+		const parsed = JSON.parse(data) as Partial<SyncNews>;
+		if (typeof parsed.head !== "number" || typeof parsed.instanceId !== "string") return null;
+		return { head: parsed.head, instanceId: parsed.instanceId };
+	} catch {
+		return null;
+	}
+}

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

@@ -1,7 +1,7 @@
 /**
  * Fake-clock tests: capture scheduled callbacks, fire them by hand. The timer's
- * contract is vault's — single-flight, unreachable-is-quiet, sync-now fast lane,
- * peer re-resolved every tick.
+ * contract is single-flight, unreachable-is-quiet, peer re-resolved every run —
+ * and, since 2026-09-15, **silent when there is nothing to say**.
  */
 import { describe, expect, test } from "bun:test";
 import { createSyncStatusReporter } from "./status";
@@ -35,7 +35,6 @@ function harness(overrides: Partial<SyncTimerDeps> = {}) {
 		},
 		head: () => 0,
 		status,
-		requestPollMs: 0, // the fast lane has its own test
 		now: () => now,
 		setTimer: (fn, ms) => {
 			const entry = { fn: fn as () => void, ms };
@@ -51,15 +50,18 @@ function harness(overrides: Partial<SyncTimerDeps> = {}) {
 		...overrides,
 	};
 	const handle = startSyncTimer(deps);
+	const settle = async () => {
+		// Let the sync promise chain settle.
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		await new Promise((resolve) => setTimeout(resolve, 0));
+	};
 	/** Fire the most recently scheduled callback, advancing the clock by its delay. */
 	const fire = async () => {
 		const entry = scheduled.pop();
 		if (!entry) throw new Error("nothing scheduled");
 		now += entry.ms;
 		entry.fn();
-		// Let the sync promise chain settle.
-		await new Promise((resolve) => setTimeout(resolve, 0));
-		await new Promise((resolve) => setTimeout(resolve, 0));
+		await settle();
 	};
 	return {
 		scheduled,
@@ -67,6 +69,10 @@ function harness(overrides: Partial<SyncTimerDeps> = {}) {
 		status,
 		handle,
 		fire,
+		settle,
+		advance: (ms: number) => {
+			now += ms;
+		},
 		setOutcome: (fn: typeof outcome) => {
 			outcome = fn;
 		},
@@ -82,8 +88,35 @@ describe("sync timer", () => {
 		expect(h.runs).toHaveLength(1);
 		expect(h.status.read().lastOutcome).toBe("ok");
 		expect(h.status.read().role).toBe("dialer");
-		// The next steady tick is booked.
-		expect(h.scheduled).toHaveLength(1);
+	});
+
+	/**
+	 * 🔴 The check this whole change exists for, measured as BEHAVIOUR rather than
+	 * shape. Whatever mechanism a future edit reaches for — a `setInterval`, a
+	 * re-added `intervalMs`, an injected `checkRequest` dep, a recursive `schedule`
+	 * — it has to book a callback through `setTimer` to fire, and this asserts that
+	 * after the boot catch-up there is nothing booked at all.
+	 *
+	 * Simulated 24 hours: the loop is handed a healthy peer and a clean op log, and
+	 * must dial exactly ONCE (the boot catch-up) and then go quiet forever.
+	 */
+	test("a healthy peer with no local news is dialed ONCE at boot, then never", async () => {
+		const h = harness();
+		await h.fire(); // the boot catch-up
+		expect(h.runs).toHaveLength(1);
+
+		// Nothing booked, and advancing a day cannot conjure anything: there is no
+		// callback left to fire.
+		expect(h.scheduled).toHaveLength(0);
+		for (let hour = 0; hour < 24; hour++) {
+			h.advance(60 * 60_000);
+			await h.settle();
+			expect(
+				h.scheduled,
+				`hour ${hour + 1}: the loop booked a wake-up with a healthy peer and nothing to push — that is the poll the 2026-09-15 ruling deleted`,
+			).toHaveLength(0);
+		}
+		expect(h.runs, "24 hours of a healthy idle peer must cost exactly one dial").toHaveLength(1);
 	});
 
 	test("a failure backs off and reports unreachable quietly", async () => {
@@ -94,10 +127,34 @@ describe("sync timer", () => {
 		await h.fire(); // kickoff → fails
 		expect(h.status.read().lastOutcome).toBe("unreachable");
 		expect(h.status.read().consecutiveFailures).toBe(1);
-		await h.fire(); // backoff wait tick → plan says run (clock advanced past step)
+		// 🔴 The allowed timer: a retry books a wake-up, because the peer is DOWN.
+		expect(h.scheduled).toHaveLength(1);
+		await h.fire();
 		expect(h.status.read().consecutiveFailures).toBe(2);
 	});
 
+	test("recovering from a failure stops the retry timer rather than settling into it", async () => {
+		const h = harness();
+		h.setOutcome(async () => {
+			throw new Error("fetch failed");
+		});
+		await h.fire(); // fails, books a retry
+		expect(h.scheduled).toHaveLength(1);
+		h.setOutcome(async () => ({
+			remoteId: "peer",
+			pushed: 0,
+			pulled: 0,
+			conflicts: 0,
+			held: 0,
+		}));
+		await h.fire(); // the retry succeeds
+		expect(h.status.read().consecutiveFailures).toBe(0);
+		expect(
+			h.scheduled,
+			"a recovered peer must go quiet — a retry loop that survives success is a poll",
+		).toHaveLength(0);
+	});
+
 	test("a version-skew pause reports pausedOn without counting as a failure", async () => {
 		const h = harness();
 		h.setOutcome(async () => ({
@@ -115,7 +172,7 @@ describe("sync timer", () => {
 		expect(s.consecutiveFailures).toBe(0);
 	});
 
-	test("syncNow forces an immediate run", async () => {
+	test("syncNow forces an immediate run — this is the push, not a poll", async () => {
 		const h = harness();
 		await h.fire(); // kickoff
 		expect(h.runs).toHaveLength(1);
@@ -124,22 +181,46 @@ describe("sync timer", () => {
 		expect(h.runs).toHaveLength(2);
 	});
 
-	test("an unlinked peer is a quiet no-op re-checked next tick", async () => {
+	test("an unlinked peer is a quiet no-op — no re-check timer", async () => {
 		const h = harness({ resolvePeer: () => null });
 		await h.fire();
 		expect(h.runs).toHaveLength(0);
-		expect(h.scheduled).toHaveLength(1); // re-check booked
+		expect(
+			h.scheduled,
+			"polling for a peer that is not linked yet is still polling",
+		).toHaveLength(0);
 	});
 
-	test("markDirty schedules a prompt run (debounced by the planner)", async () => {
+	/**
+	 * 🔴 With the interval gone this is the ONLY thing that pushes a local write, so
+	 * it is now required wiring rather than an optimization. `apps/vault` drops the
+	 * `markDirty` handle today and the interval covered for it; on adoption of 2.0.0
+	 * it must wire this or sit silent. See the task filed alongside this change.
+	 */
+	test("markDirty is what pushes a local write", async () => {
 		let head = 0;
 		const h = harness({ head: () => head });
 		await h.fire(); // kickoff
+		expect(h.scheduled).toHaveLength(0); // quiet
 		head = 3;
 		h.handle.markDirty();
-		await h.fire(); // the dirty tick — planner may debounce once
-		if (h.runs.length === 1) await h.fire();
-		expect(h.runs.length).toBeGreaterThanOrEqual(2);
+		expect(h.scheduled, "markDirty must book the debounced push").toHaveLength(1);
+		await h.fire(); // the debounce elapses → run
+		expect(h.runs).toHaveLength(2);
+		// …and having pushed, it goes quiet again rather than settling into a loop.
+		expect(h.scheduled).toHaveLength(0);
+	});
+
+	test("markDirty does not push an imminent forced run out to the debounce", async () => {
+		const h = harness();
+		await h.fire(); // kickoff
+		h.handle.syncNow();
+		const forced = h.scheduled.at(-1);
+		h.handle.markDirty();
+		expect(
+			h.scheduled.at(-1),
+			"markDirty replaced the ~1ms forced wake with a 3s debounce",
+		).toBe(forced);
 	});
 
 	test("stop() cancels everything", async () => {