@inkandswitch/patchwork-bootloader 0.3.1 → 0.3.2

package/src/automerge-worker.ts

@@ -26,6 +26,8 @@ import {
   stringifyAutomergeUrl,
   type AutomergeUrl,
   type DocHandle,
+  type DocumentId,
+  type UrlHeads,
 } from "@automerge/automerge-repo/slim";
 import { resolvePath } from "@inkandswitch/patchwork-filesystem";
 
@@ -41,11 +43,15 @@ import {
 
 import {
   HANDOFF_CHANNEL,
+  SYNCSTATE_CHANNEL,
   type HandoffCachedMessage,
   type HandoffOnlineMessage,
   type HandoffRequest,
   type HandoffRequestMessage,
   type HandoffResponseMessage,
+  type SyncStateBroadcast,
+  type SyncStateDocMessage,
+  type SyncStateRequestMessage,
 } from "./types.js";
 
 declare const __SITE_NAME__: string;
@@ -66,6 +72,46 @@ const WORKER_BOOT_TIME = Date.now();
 // post back over every connected tab's control port, tagged [automerge-worker].
 
 const controlPorts = new Set<MessagePort>();
+
+// ── Per-tab sync-state subscriptions ────────────────────────────────────
+// Each tab's control port subscribes to the documents it cares about; we push
+// only those docs' heads back down that port (addressed — tab A never sees tab
+// B's docs), and drop a port's whole subscription set when it closes (the tab
+// went away), so there's nothing to reference-count or time out. The global
+// connection/whoami signals still go over SYNCSTATE_CHANNEL.
+const syncWatchers = new Map<MessagePort, Set<string>>();
+
+// Installed by setupSyncStateBroadcast once the repo's snapshot exists, so a
+// fresh `sync-sub` can be replayed the doc's current heads immediately. Null
+// until then; subscriptions taken during boot are replayed when it installs.
+let replaySyncForPort:
+  | ((documentId: string, port: MessagePort) => void)
+  | null = null;
+
+function syncSubscribe(port: MessagePort, documentId: string): void {
+  let docs = syncWatchers.get(port);
+  if (!docs) syncWatchers.set(port, (docs = new Set()));
+  if (docs.has(documentId)) return;
+  docs.add(documentId);
+  replaySyncForPort?.(documentId, port);
+}
+
+function syncUnsubscribe(port: MessagePort, documentId: string): void {
+  syncWatchers.get(port)?.delete(documentId);
+}
+
+// Push one document's heads to every control port currently watching it.
+function pushSyncState(message: SyncStateDocMessage): void {
+  for (const [port, docs] of syncWatchers) {
+    if (!docs.has(message.documentId)) continue;
+    try {
+      port.postMessage(message);
+    } catch {
+      // Port already gone; its close handler will reap the entry.
+    }
+  }
+}
+
 // Logs emitted before any tab has connected (e.g. during wasm boot) would
 // otherwise be lost — buffer a bounded number and flush on first connect.
 const preConnectBuffer: Array<{ level: string; args: string[] }> = [];
@@ -172,6 +218,14 @@ const SUBDUCTION_ENDPOINTS = [
 ];
 const RESOLVE_TIMEOUT_MS = 30_000;
 
+// Backoff re-sync of stuck/diverged docs. Only this worker is connected to the
+// sync server, so it's the only place that can notice a doc whose heads have
+// settled out of sync with the server and re-arm a sync round for it.
+const RESYNC_GRACE_MS = 8_000; // must be *stably* diverged this long first
+const RESYNC_INITIAL_DELAY_MS = 5_000; // first backoff cooldown after a resync
+const RESYNC_MAX_DELAY_MS = 60_000; // backoff cap
+const RESYNC_REVIEW_INTERVAL_MS = 5_000; // how often stuck docs are re-checked
+
 const DEFAULT_CLASSIC_SYNC_SERVER = "wss://sync3.automerge.org";
 
 let classicSyncServer = DEFAULT_CLASSIC_SYNC_SERVER;
@@ -248,6 +302,15 @@ function getRepoHive() {
 
       if (!useKeyhive) {
         const signer = await WebCryptoSigner.setup();
+        const identity = {
+          peerId: signer.peerId().toString(),
+          verifyingKey: (
+            signer.verifyingKey() as Uint8Array<ArrayBufferLike> & {
+              toHex(): string;
+            }
+          ).toHex(),
+        };
+        console.log("[patchwork] shared-worker subduction identity:", identity);
 
         const repo = new Repo({
           storage: new IndexedDBWorkerStorageAdapter(),
@@ -264,6 +327,8 @@ function getRepoHive() {
         });
 
         (self as any).repo = repo;
+        (self as any).syncIdentity = identity;
+        setupSyncStateBroadcast(repo, identity);
         log("repo constructed (no keyhive), waiting for network subsystem");
 
         repo.networkSubsystem.whenReady().then(() => {
@@ -296,6 +361,7 @@ function getRepoHive() {
 
       (self as any).repo = repo;
       (self as any).hive = hive;
+      setupSyncStateBroadcast(repo);
       log("repo constructed, waiting for network subsystem");
 
       // Don't block getRepoHive() on whenReady() — the network subsystem starts
@@ -322,6 +388,306 @@ function getRepoHive() {
   return repoHivePromise;
 }
 
+// ── Sync-state broadcast ───────────────────────────────────────────────
+//
+// Only this worker is directly connected to the sync server, so it's the only
+// place that learns the server's heads (the repo's "subduction-remote-heads"
+// event, keyed by each Subduction peer's verifying-key storageId) and whether
+// the server link is up ("subduction-connection"). We rebroadcast both on
+// SYNCSTATE_CHANNEL so every tab can render a sync indicator without holding
+// its own server connection. A tab that opens mid-stream posts {type:"request"}
+// to get the current snapshot replayed.
+
+let syncStateWired = false;
+
+function setupSyncStateBroadcast(
+  repo: Repo,
+  identity?: { peerId: string; verifyingKey: string }
+): void {
+  if (syncStateWired) return;
+  syncStateWired = true;
+
+  const channel = new BroadcastChannel(SYNCSTATE_CHANNEL);
+  // documentId -> storageId (verifying key) -> last-known heads
+  const snapshot = new Map<
+    string,
+    Map<string, { heads: string[]; timestamp: number }>
+  >();
+  let connected = repo.isSubductionConnected();
+  // Directly-connected sync-server peer ids (verifying keys). Stable once
+  // known; tabs use this to judge "synced" against the server specifically.
+  let serverPeerIds: string[] = [];
+
+  const postWhoAmI = () => {
+    if (!identity) return;
+    channel.postMessage({
+      type: "whoami",
+      peerId: identity.peerId,
+      verifyingKey: identity.verifyingKey,
+    } satisfies SyncStateBroadcast);
+  };
+  // Announce our identity so tabs can label which peer rows are this worker.
+  postWhoAmI();
+
+  // Heads are addressed, not broadcast: push a doc's heads only to the control
+  // ports that subscribed to it (see syncWatchers / pushSyncState).
+  const postHeads = (
+    documentId: string,
+    storageId: string,
+    heads: string[],
+    timestamp: number
+  ) =>
+    pushSyncState({
+      type: "sync-state",
+      documentId,
+      storageId,
+      heads,
+      timestamp,
+    });
+
+  // Let a `sync-sub` (which may have arrived while the repo was still booting)
+  // replay this doc's current snapshot to the subscribing port immediately.
+  const replayDoc = (documentId: string, port: MessagePort) => {
+    const byStorage = snapshot.get(documentId);
+    if (!byStorage) return;
+    for (const [storageId, { heads, timestamp }] of byStorage) {
+      try {
+        port.postMessage({
+          type: "sync-state",
+          documentId,
+          storageId,
+          heads,
+          timestamp,
+        } satisfies SyncStateDocMessage);
+      } catch {
+        // Port gone; its close handler reaps it.
+      }
+    }
+  };
+  replaySyncForPort = replayDoc;
+  // Catch up any ports that subscribed before this wiring existed.
+  for (const [port, docs] of syncWatchers) {
+    for (const documentId of docs) replayDoc(documentId, port);
+  }
+
+  const postConnection = () =>
+    channel.postMessage({
+      type: "connection",
+      connected,
+      serverPeerIds,
+    } satisfies SyncStateBroadcast);
+
+  // Learn (and re-announce) which connected Subduction peer is the sync server.
+  // The peer list is empty until the handshake finishes, so retry briefly.
+  const refreshServerPeers = async () => {
+    for (let attempt = 0; attempt < 6; attempt++) {
+      try {
+        const ids = await repo.connectedSubductionPeerIds();
+        if (ids.length > 0) {
+          serverPeerIds = ids;
+          postConnection();
+          return;
+        }
+      } catch {
+        // repo has no subduction source / not ready yet
+      }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  };
+
+  // Advertise the worker's OWN heads for every doc it holds (keyed by our
+  // verifying key), so the worker hop is visible on every document.
+  //
+  // Docs pushed in by Subduction that this worker never explicitly opened don't
+  // surface via the repo's "document" event, so we discover them by re-scanning
+  // repo.handles (on a tick, and whenever the server reports a doc) and attach a
+  // heads-changed listener once per doc. No-op when there's no identity (keyhive
+  // path).
+  const ownTracked = new Set<string>();
+  const broadcastOwnHeads = (handle: {
+    documentId: string;
+    heads: () => string[];
+  }) => {
+    if (!identity) return;
+    const documentId = handle.documentId;
+    let heads: string[];
+    try {
+      heads = [...handle.heads()];
+    } catch {
+      return; // handle not ready yet
+    }
+    const timestamp = Date.now();
+    let byStorage = snapshot.get(documentId);
+    if (!byStorage) {
+      byStorage = new Map();
+      snapshot.set(documentId, byStorage);
+    }
+    byStorage.set(identity.peerId, { heads, timestamp });
+    postHeads(documentId, identity.peerId, heads, timestamp);
+    reviewResync(documentId);
+  };
+  const trackOwnHandle = (handle: {
+    documentId: string;
+    heads: () => string[];
+    on: (ev: "heads-changed", cb: () => void) => void;
+  }) => {
+    if (!identity || ownTracked.has(handle.documentId)) return;
+    ownTracked.add(handle.documentId);
+    handle.on("heads-changed", () => broadcastOwnHeads(handle));
+    broadcastOwnHeads(handle);
+  };
+  const scanOwnHandles = () => {
+    if (!identity) return;
+    for (const handle of Object.values(repo.handles)) {
+      trackOwnHandle(handle as never);
+    }
+  };
+
+  // ── Backoff re-sync of stuck/diverged docs ──────────────────────────
+  //
+  // Subduction sync is event-driven and only retries syncs it observed *fail*;
+  // a doc that settles missing commits the server holds — or whose heal retries
+  // were exhausted — is otherwise never retried. When we're behind and the
+  // server's advertised heads haven't advanced for a grace window (so it's
+  // genuinely stuck, not just lagging a live edit), we re-arm its sync round
+  // with per-doc exponential backoff. Convergence clears the state.
+  const serverHeadSetsFor = (documentId: string): string[][] => {
+    const byStorage = snapshot.get(documentId);
+    if (!byStorage) return [];
+    const sets: string[][] = [];
+    for (const [storageId, { heads }] of byStorage) {
+      if (serverPeerIds.includes(storageId)) sets.push(heads);
+    }
+    return sets;
+  };
+  const resyncState = new Map<
+    string,
+    { serverSig: string; since: number; delay: number; lastResyncAt: number }
+  >();
+  // Inspectable from the SharedWorker console as `self.patchworkResync` to see
+  // whether/how often a doc is being re-synced and against which server heads.
+  const resyncDiag: { fires: number; byDoc: Record<string, unknown> } =
+    ((self as any).patchworkResync ??= { fires: 0, byDoc: {} });
+  const reviewResync = (documentId: string) => {
+    if (!identity || !connected) {
+      resyncState.delete(documentId);
+      return;
+    }
+    const handle = repo.handles[documentId as DocumentId];
+    if (!handle) return;
+    const serverSets = serverHeadSetsFor(documentId);
+    if (serverSets.length === 0) {
+      resyncState.delete(documentId); // no server signal to compare against
+      return;
+    }
+    // The server advertises subduction *sedimentree* heads (loose-commit +
+    // fragment-boundary commit ids), which are NOT the Automerge frontier — so
+    // never compare them to handle.heads() for equality. Instead ask whether we
+    // already hold every commit the server advertises (`DocHandle.containsHeads`).
+    // If we do, the server has nothing we're missing → caught up. If not, we're
+    // genuinely behind and a re-sync can pull the rest.
+    const serverHeadsUrl = [...new Set(serverSets.flat())] as UrlHeads;
+    let haveAll: boolean;
+    try {
+      haveAll = handle.containsHeads(serverHeadsUrl);
+    } catch {
+      return; // doc not ready, or an undecodable head
+    }
+    if (haveAll) {
+      resyncState.delete(documentId); // we hold everything the server has
+      return;
+    }
+    // Behind. "Stuck" = the server's advertised set hasn't advanced (no
+    // progress) for a while. Key the grace timer on the server heads only, so
+    // your own edits churning don't keep resetting it.
+    const serverSig = [...serverHeadsUrl].sort().join(",");
+    const now = Date.now();
+    const prev = resyncState.get(documentId);
+    if (!prev || prev.serverSig !== serverSig) {
+      // First sighting, or the server advanced its view (progress): restart.
+      resyncState.set(documentId, {
+        serverSig,
+        since: now,
+        delay: RESYNC_INITIAL_DELAY_MS,
+        lastResyncAt: 0,
+      });
+      return;
+    }
+    if (now - prev.since < RESYNC_GRACE_MS) return; // not stuck long enough yet
+    if (now - prev.lastResyncAt < prev.delay) return; // within backoff cooldown
+    log("re-syncing behind doc", documentId, { serverSets });
+    resyncDiag.fires++;
+    resyncDiag.byDoc[documentId] = {
+      at: now,
+      count:
+        ((resyncDiag.byDoc[documentId] as { count?: number } | undefined)
+          ?.count ?? 0) + 1,
+      serverSets,
+    };
+    try {
+      repo.resyncSubduction(documentId as DocumentId);
+    } catch (e) {
+      log("resyncSubduction failed", e);
+    }
+    prev.lastResyncAt = now;
+    prev.delay = Math.min(prev.delay * 2, RESYNC_MAX_DELAY_MS);
+  };
+  const reviewAllResync = () => {
+    if (!identity) return;
+    for (const documentId of snapshot.keys()) reviewResync(documentId);
+    for (const id of [...resyncState.keys()]) {
+      if (!snapshot.has(id)) resyncState.delete(id);
+    }
+  };
+
+  repo.on(
+    "subduction-remote-heads",
+    ({ documentId, storageId, heads, timestamp }) => {
+      const headsCopy = [...heads];
+      let byStorage = snapshot.get(documentId);
+      if (!byStorage) {
+        byStorage = new Map();
+        snapshot.set(documentId, byStorage);
+      }
+      byStorage.set(storageId, { heads: headsCopy, timestamp });
+      postHeads(documentId, storageId, headsCopy, timestamp);
+      // A doc the server reported is one we hold — make sure we're advertising
+      // our own heads for it too.
+      scanOwnHandles();
+      reviewResync(documentId);
+    }
+  );
+
+  repo.on("subduction-connection", ({ connected: isConnected }) => {
+    connected = isConnected;
+    postConnection();
+    if (isConnected) void refreshServerPeers();
+  });
+
+  // A BroadcastChannel never receives its own posts, so this only sees tabs'
+  // requests, never our own broadcasts. We replay just the global signals here;
+  // a late tab gets per-doc heads by subscribing (sync-sub), not from this.
+  channel.addEventListener("message", (event: MessageEvent) => {
+    const data = event.data as SyncStateRequestMessage;
+    if (data?.type !== "request") return;
+    postWhoAmI();
+    postConnection();
+  });
+
+  // In case we're already connected by the time this wires up.
+  void refreshServerPeers();
+
+  // Discover the worker's docs by re-scanning repo.handles initially and on a
+  // tick (Subduction-pushed docs don't surface via the "document" event).
+  scanOwnHandles();
+  if (identity) setInterval(scanOwnHandles, 3000);
+
+  // Drive the backoff re-sync of stuck/diverged docs. A tick is essential here:
+  // the "stuck" case is precisely when no head events are firing, so the
+  // grace/backoff timers can only advance on a timer.
+  if (identity) setInterval(reviewAllResync, RESYNC_REVIEW_INTERVAL_MS);
+}
+
 // ── Tab connections ────────────────────────────────────────────────────
 
 // Each tab connects with a control port (the SharedWorker connect port) and
@@ -436,6 +802,14 @@ function handleControlMessage(
         });
       }
     );
+  } else if (data?.type === "sync-sub") {
+    if (typeof data.documentId === "string") {
+      syncSubscribe(controlPort, data.documentId);
+    }
+  } else if (data?.type === "sync-unsub") {
+    if (typeof data.documentId === "string") {
+      syncUnsubscribe(controlPort, data.documentId);
+    }
   } else if (data?.type === "debug") {
     debugging = data.debug;
     log("automerge worker debugging enabled");
@@ -481,6 +855,9 @@ self.addEventListener("connect", (event) => {
   // event fall back to the adapters' lazy useWeakRef cleanup.
   controlPort.addEventListener("close", () => {
     controlPorts.delete(controlPort);
+    // The tab is gone — drop its sync subscriptions wholesale so we stop
+    // pushing it heads (no per-doc unsub needed, no leak).
+    syncWatchers.delete(controlPort);
     void dropConnection(connection);
   });
 

package/src/setup.ts

@@ -2,6 +2,7 @@ import type {
   ServiceWorkerRepoChannelListener,
   SetupServiceWorkerOptions,
   SetupServiceWorkerResult,
+  SyncStateDocMessage,
 } from "./types.js";
 import {
   readClassicSyncServer,
@@ -107,6 +108,10 @@ export function getAutomergeWorker(): SharedWorker {
     // Surface the SharedWorker's console output and uncaught errors in this
     // tab's console (it has its own console that's awkward to find otherwise).
     automergeWorker.port.addEventListener("message", (event: MessageEvent) => {
+      if (event.data?.type === "sync-state") {
+        dispatchSyncState(event.data as SyncStateDocMessage);
+        return;
+      }
       if (event.data?.type !== "console") return;
       const { level, args } = event.data;
       // Gate forwarded [lifecycle] logs on the toggle too.
@@ -205,6 +210,53 @@ function installWorkerDeathDetection(worker: SharedWorker): void {
   }, HEARTBEAT_MS);
 }
 
+// ── Sync-state subscriptions ────────────────────────────────────────────
+// The automerge worker pushes per-document heads only to the tabs that ask for
+// them (see SyncStateDocMessage). We ref-count locally so several callers in
+// this tab can watch the same doc with a single worker subscription, and tear
+// the worker subscription down when the last local watcher drops.
+type SyncStateListener = (update: SyncStateDocMessage) => void;
+const syncStateListeners = new Map<string, Set<SyncStateListener>>();
+
+function dispatchSyncState(update: SyncStateDocMessage): void {
+  const listeners = syncStateListeners.get(update.documentId);
+  if (!listeners) return;
+  for (const listener of listeners) {
+    try {
+      listener(update);
+    } catch (err) {
+      console.error("sync-state listener threw", err);
+    }
+  }
+}
+
+export function subscribeSyncState(
+  documentId: string,
+  listener: SyncStateListener
+): () => void {
+  const worker = getAutomergeWorker();
+  let listeners = syncStateListeners.get(documentId);
+  if (!listeners) {
+    syncStateListeners.set(documentId, (listeners = new Set()));
+    // First local watcher for this doc — ask the worker to start pushing it.
+    worker.port.postMessage({ type: "sync-sub", documentId });
+  }
+  listeners.add(listener);
+
+  let active = true;
+  return () => {
+    if (!active) return; // idempotent
+    active = false;
+    const set = syncStateListeners.get(documentId);
+    if (!set) return;
+    set.delete(listener);
+    if (set.size === 0) {
+      syncStateListeners.delete(documentId);
+      worker.port.postMessage({ type: "sync-unsub", documentId });
+    }
+  };
+}
+
 export function connectClassicSync(
   server: string = readClassicSyncServer()
 ): Promise<void> {
@@ -367,6 +419,7 @@ export default async function setupServiceWorker(
     shared,
     connectClassicSync,
     getRepoChannel,
+    subscribeSyncState,
     async subscribeToRepoChannel(listener: ServiceWorkerRepoChannelListener) {
       // The automerge worker outlives the page, so unlike the old in-service-
       // worker repo there's nothing to reconnect: one port, handed over once.