@inkandswitch/patchwork-bootloader 0.6.2 → 0.7.0

package/src/shared-worker-lifecycle.ts

@@ -0,0 +1,289 @@
+import debug from "debug";
+
+export const lifecycleLog = debug("patchwork:lifecycle");
+
+function describeErrorEvent(event: Event): string {
+  const error = event as ErrorEvent;
+  const where = error.filename
+    ? ` (${error.filename}:${error.lineno}:${error.colno})`
+    : "";
+  return `${error.message || String(event)}${where}`;
+}
+
+// A silent port is not proof of death: the worker may still be evaluating its
+// module graph, or be busy with wasm/sync work. In both cases every queued
+// message is delivered once it catches up, and tearing the port down would lose
+// them. So silence only starts a non-destructive probe: a second connection to
+// the same instance. Only if the probe gets a `hello` while this port stays
+// silent do we know the instance is alive but our port is stranded, and
+// recover.
+const HEARTBEAT_MS = 5_000;
+const HEARTBEAT_TIMEOUT_MS = 25_000;
+// An idle worker hellos within milliseconds of connecting, so before first
+// contact the budget is tighter — probing early rescues stranded boots fast.
+const FIRST_CONTACT_TIMEOUT_MS = 4_000;
+// After a slow boot both connections hello at roughly the same moment and
+// cross-port delivery order isn't guaranteed, so give the suspect this long to
+// also speak before concluding it's stranded.
+const PROBE_GRACE_MS = 500;
+// Below this spacing, skip: if the fresh worker is dead too, its own heartbeat
+// re-triggers recovery later rather than spinning in a tight loop.
+const RECOVERY_MIN_INTERVAL_MS = 15_000;
+
+export type SharedWorkerHandle = {
+  readonly name: string;
+  /** The current instance, spawning one if there isn't a live one. */
+  get(): SharedWorker;
+  /** Send on the current instance's control port. */
+  post(message: unknown, transfer?: Transferable[]): void;
+  /**
+   * The worker died and was replaced. Anything held against the old instance —
+   * a port, a subscription — is stranded; the new one boots with cold state.
+   */
+  onRecreated(listener: () => void): () => void;
+};
+
+/**
+ * A SharedWorker a tab keeps alive: spawned on demand, heartbeated, and rebuilt
+ * if the browser kills it (which it may, under memory pressure).
+ */
+export function sharedWorkerHandle(
+  name: string,
+  /** Read on every spawn, so a site can set the path after this is built. */
+  path: () => string,
+  {
+    debugging,
+    onMessage,
+    onSpawn,
+  }: {
+    debugging: boolean;
+    onMessage: (event: MessageEvent) => void;
+    onSpawn?: (worker: SharedWorker) => void;
+  }
+): SharedWorkerHandle {
+  let current: SharedWorker | undefined;
+  let disposeDeathDetection: (() => void) | undefined;
+  let recovering = false;
+  let lastRecoveryAt = 0;
+  const recreatedListeners = new Set<() => void>();
+
+  const get = (): SharedWorker => {
+    if (current) return current;
+
+    const worker = new SharedWorker(path(), { name, type: "module" });
+    current = worker;
+
+    // Fires when a message can't be structured-deserialized. Silent otherwise:
+    // the message is dropped, which looks identical to a worker that never
+    // replied.
+    worker.port.addEventListener("messageerror", (event) => {
+      console.error(`[${name}] undeserializable message from worker:`, event);
+    });
+    // Replies come back on this port, and we listen with addEventListener
+    // rather than onmessage, so it needs start().
+    worker.port.start();
+    worker.port.addEventListener("message", onMessage);
+    worker.port.postMessage({ type: "debug", debug: debugging });
+
+    onSpawn?.(worker);
+    disposeDeathDetection = installDeathDetection(worker);
+    return worker;
+  };
+
+  async function recover(reason: string, dead: SharedWorker): Promise<void> {
+    if (dead !== current) return;
+    if (recovering) return;
+    const now = Date.now();
+    if (now - lastRecoveryAt < RECOVERY_MIN_INTERVAL_MS) return;
+    recovering = true;
+    lastRecoveryAt = now;
+    lifecycleLog("recreating the %s SharedWorker (%s)", name, reason);
+
+    try {
+      disposeDeathDetection?.();
+      disposeDeathDetection = undefined;
+      current = undefined;
+      try {
+        dead.port.close();
+      } catch {}
+
+      get();
+      for (const listener of recreatedListeners) {
+        try {
+          listener();
+        } catch (error) {
+          console.error(`[${name}] recreated listener threw`, error);
+        }
+      }
+    } finally {
+      recovering = false;
+    }
+  }
+
+  function installDeathDetection(worker: SharedWorker): () => void {
+    let instanceId: string | undefined;
+    let lastHeardAt = Date.now();
+    let warnedUnresponsive = false;
+    let warnedSendFailed = false;
+    let disposed = false;
+    let probe: SharedWorker | undefined;
+    let seq = 0;
+
+    const closeProbe = () => {
+      if (!probe) return;
+      try {
+        probe.port.close();
+      } catch {}
+      probe = undefined;
+    };
+
+    worker.port.addEventListener("message", (event: MessageEvent) => {
+      const data = event.data;
+      if (data?.type !== "hello" && data?.type !== "pong") return;
+      lastHeardAt = Date.now();
+      warnedUnresponsive = false;
+      closeProbe();
+      if (instanceId === undefined) {
+        instanceId = data.instanceId;
+        lifecycleLog(
+          "%s SharedWorker instance %s (via %s)",
+          name,
+          data.instanceId,
+          data.type
+        );
+      } else if (data.instanceId && data.instanceId !== instanceId) {
+        lifecycleLog(
+          "%s SharedWorker instance changed (instance %s, was %s)",
+          name,
+          data.instanceId,
+          instanceId
+        );
+        instanceId = data.instanceId;
+      }
+    });
+
+    worker.port.addEventListener("close", () => {
+      if (disposed) return;
+      lifecycleLog("%s SharedWorker control port closed", name);
+      void recover("control port closed", worker);
+    });
+
+    // Not gated on the debug namespace: a worker that fails to load never
+    // replies to anything, and this is the only signal that says so.
+    worker.addEventListener("error", (event) => {
+      console.error(`${name} SharedWorker error:`, describeErrorEvent(event));
+    });
+
+    const startProbe = (reason: string) => {
+      if (probe || disposed) return;
+      lifecycleLog(
+        "%s SharedWorker %s; probing with a second connection",
+        name,
+        reason
+      );
+      const startedAt = Date.now();
+      const p = new SharedWorker(path(), { name, type: "module" });
+      probe = p;
+      p.port.start();
+      p.port.addEventListener("message", (event: MessageEvent) => {
+        if (event.data?.type !== "hello") return;
+        setTimeout(() => {
+          if (disposed || probe !== p) return;
+          closeProbe();
+          // The suspect spoke while the probe ran: it was merely busy, and
+          // everything queued on it has been delivered.
+          if (lastHeardAt >= startedAt) return;
+          void recover(
+            `port unresponsive on a live worker (${reason}; probe confirmed)`,
+            worker
+          );
+        }, PROBE_GRACE_MS);
+      });
+      // No hello on the probe means the instance is loading or busy. The probe
+      // waits indefinitely rather than tearing anything down on a timer.
+    };
+
+    const heartbeat = setInterval(() => {
+      try {
+        worker.port.postMessage({ type: "ping", id: ++seq });
+      } catch (error) {
+        // Without this a failed send is indistinguishable from a dead worker.
+        if (!warnedSendFailed) {
+          warnedSendFailed = true;
+          console.error(`${name} SharedWorker ping send threw`, error);
+        }
+      }
+
+      const neverHeard = instanceId === undefined;
+      const silentMs = Date.now() - lastHeardAt;
+      const timeoutMs = neverHeard
+        ? FIRST_CONTACT_TIMEOUT_MS
+        : HEARTBEAT_TIMEOUT_MS;
+      if (silentMs <= timeoutMs) return;
+
+      // First contact probes regardless of visibility: SharedWorkers don't
+      // suspend with the tab, and the probe destroys nothing. Post-contact
+      // silence defers to visibility, since a hidden page's throttling can fake
+      // it.
+      const visible =
+        typeof document === "undefined" ||
+        document.visibilityState === "visible";
+      if (!neverHeard && !visible) return;
+
+      const seconds = Math.round(silentMs / 1000);
+      const reason = neverHeard
+        ? `no hello ~${seconds}s after connecting`
+        : `no pong for ~${seconds}s`;
+      if (!warnedUnresponsive) {
+        warnedUnresponsive = true;
+        lifecycleLog("%s SharedWorker %s (tab visible)", name, reason);
+      }
+      startProbe(reason);
+    }, HEARTBEAT_MS);
+
+    return () => {
+      disposed = true;
+      clearInterval(heartbeat);
+      closeProbe();
+    };
+  }
+
+  return {
+    name,
+    get,
+    post(message, transfer) {
+      get().port.postMessage(message, transfer ?? []);
+    },
+    onRecreated(listener) {
+      recreatedListeners.add(listener);
+      return () => {
+        recreatedListeners.delete(listener);
+      };
+    },
+  };
+}
+
+/**
+ * Mirror a worker's forwarded console output into this tab's console, since a
+ * SharedWorker's own console is only visible in chrome://inspect.
+ */
+export function forwardWorkerConsole(name: string, data: any): boolean {
+  if (data?.type !== "console") return false;
+  const { level, args } = data;
+  if (
+    !lifecycleLog.enabled &&
+    typeof args?.[0] === "string" &&
+    args[0].includes("[lifecycle]")
+  ) {
+    return true;
+  }
+  const write = (console as any)[level] ?? console.log;
+  // The worker's logs carry %c directives in args[0] with CSS in the following
+  // args, so the tag has to go inside the format string or the CSS prints raw.
+  if (typeof args[0] === "string") {
+    write(`[${name}] ${args[0]}`, ...args.slice(1));
+  } else {
+    write(`[${name}]`, ...args);
+  }
+  return true;
+}

package/src/siblings.ts

@@ -0,0 +1,32 @@
+import type { RepoConfig } from "@automerge/automerge-repo/slim";
+import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel";
+import { storagePrefix } from "./storage.js";
+
+type SubductionAdapters = NonNullable<RepoConfig["subductionAdapters"]>;
+
+/**
+ * Every Repo on this origin — each tab's, and the automerge protocol handler
+ * worker's — is a full Subduction node with its own storage and its own
+ * sync-server socket. Siblings would still meet through the server,
+ * eventually; this meets them over a BroadcastChannel so an edit in one tab
+ * lands in the others in the time it takes to post a message, online or not.
+ *
+ * What crosses the channel is Subduction: transport frames between two nodes,
+ * authenticated by each one's signer. No classic automerge sync runs here, so
+ * the adapters go to `new Repo({ subductionAdapters })` rather than to the
+ * network subsystem.
+ *
+ * A BroadcastChannel is a mesh in which every node sees every other one, and
+ * Subduction's handshake has an initiator and a responder, so the role is
+ * "mesh": for each pair, the node whose peer id sorts lower speaks first.
+ */
+export function siblingAdapters(): SubductionAdapters {
+  const serviceName = `${storagePrefix}-siblings`;
+  return [
+    {
+      adapter: new BroadcastChannelNetworkAdapter({ channelName: serviceName }),
+      serviceName,
+      role: "mesh",
+    },
+  ];
+}

package/src/types.ts

@@ -6,90 +6,6 @@
  */
 export const HANDOFF_CHANNEL = "@patchwork/handoff";
 
-/**
- * BroadcastChannel on which the automerge shared worker announces remote
- * heads it learns about from the sync server. Any tab can listen to stay
- * informed of sync progress without repo-to-repo gossiping.
- */
-export const SYNCSTATE_CHANNEL = "@patchwork/syncstate";
-
-/**
- * Worker → tabs: the worker's Subduction link to the sync server flipped.
- * `serverPeerIds` are the directly-connected sync-server peer ids (their
- * verifying keys), so a tab can tell which peer rows are *the server* and
- * judge "synced" against them specifically.
- */
-export interface SyncStateConnectionMessage {
-  type: "connection";
-  connected: boolean;
-  serverPeerIds: string[];
-}
-
-/**
- * Worker → tabs: the shared worker's own Subduction identity, so a tab can
- * tell which peer rows are "us". `peerId` is `signer.peerId().toString()` (the
- * value that shows up as a peer id); `verifyingKey` is its hex Ed25519 key.
- */
-export interface SyncStateWhoAmIMessage {
-  type: "whoami";
-  peerId: string;
-  verifyingKey: string;
-}
-
-// What the worker broadcasts on SYNCSTATE_CHANNEL: only the *global* signals
-// now. Per-document heads are addressed to subscribers over the control port
-// instead (see SyncStateDocMessage) rather than fanned out to every tab.
-export type SyncStateBroadcast =
-  | SyncStateConnectionMessage
-  | SyncStateWhoAmIMessage;
-
-/**
- * Tab → worker: please replay the current global sync signals (whoami +
- * connection) so a freshly-opened tab can orient immediately. Per-document
- * heads are no longer replayed here — a tab subscribes to the specific docs it
- * cares about over its control port instead (see {@link SyncSubscribeMessage}).
- */
-export interface SyncStateRequestMessage {
-  type: "request";
-  /** @deprecated ignored — per-doc state is delivered via sync-sub now. */
-  documentId?: string;
-}
-
-// ── Per-tab sync-state subscription (over the SharedWorker control port) ──
-//
-// The broadcast SyncState* messages above are global (connection/whoami).
-// Per-document heads, by contrast, are addressed: a tab subscribes its control
-// port to just the documents it cares about and the worker pushes only those
-// docs' heads back down that port. The worker drops a port's whole
-// subscription set automatically when the port closes (the tab went away), so
-// there's no reference counting or heartbeat to leak.
-
-/** Tab → worker: start pushing me this document's heads (replays current state). */
-export interface SyncSubscribeMessage {
-  type: "sync-sub";
-  documentId: string;
-}
-
-/** Tab → worker: stop pushing me this document's heads. */
-export interface SyncUnsubscribeMessage {
-  type: "sync-unsub";
-  documentId: string;
-}
-
-/**
- * Worker → tab (control port): a peer's heads for a subscribed document — the
- * worker's own (keyed by its peerId) or a Subduction peer's (keyed by its
- * verifying-key storageId). Same payload as the old broadcast remote-heads
- * message, but delivered only to the tabs that asked for this document.
- */
-export interface SyncStateDocMessage {
-  type: "sync-state";
-  documentId: string;
-  storageId: string;
-  heads: string[];
-  timestamp: number;
-}
-
 /**
  * The special URL to resolve, plus enough of the {@link Request} the service
  * worker is holding that the automerge worker can construct one that
@@ -180,9 +96,7 @@ export interface HandoffAbortMessage {
 }
 
 export type HandoffReplyMessage =
-  | HandoffCachedMessage
-  | HandoffResponseMessage
-  | HandoffAbortMessage;
+  HandoffCachedMessage | HandoffResponseMessage | HandoffAbortMessage;
 
 /**
  * Automerge worker → world: broadcast once on startup so the service worker
@@ -200,34 +114,14 @@ export type SetupServiceWorkerOptions = {
   path?: string;
   /**
    * The public path to the automerge shared worker file.
-   * Defaults to `/automerge-worker.js`
+   * Defaults to `/automerge-protocol-handler-worker.js`
    */
   workerPath?: string;
 };
 
-export type ServiceWorkerRepoChannelListener = (
-  port: MessagePort
-) => void | Promise<void>;
-
 export type SetupServiceWorkerResult = {
   shared?: SharedWorker;
   kill?: () => void;
   /** Open a classic Automerge sync WebSocket from the automerge worker. */
   connectClassicSync: (server?: string) => Promise<void>;
-  subscribeToRepoChannel: (
-    listener: ServiceWorkerRepoChannelListener
-  ) => Promise<() => void>;
-  /** Open a fresh repo sync port to the automerge worker (dev console). */
-  getRepoChannel: () => MessagePort;
-  /**
-   * Watch one document's sync heads (this tab's own and each Subduction peer's,
-   * as the worker learns them). Calls `listener` on every update for that doc,
-   * replaying the current state on subscribe. Returns an unsubscribe function;
-   * the worker stops pushing the doc once the last local watcher drops it (and
-   * automatically if this tab goes away).
-   */
-  subscribeSyncState: (
-    documentId: string,
-    listener: (update: SyncStateDocMessage) => void
-  ) => () => void;
 };

package/src/worker-control.ts

@@ -0,0 +1,130 @@
+// The control protocol every patchwork SharedWorker speaks with its tabs:
+// console forwarding, a `hello` on connect, ping/pong for the tab's death
+// detection, and a debug toggle. Everything else is the worker's own business
+// and arrives through `onMessage`.
+
+/** A fresh instance means cold in-memory state, so tabs watch this. */
+const WORKER_INSTANCE_ID = Math.random().toString(36).slice(2);
+const WORKER_BOOT_TIME = Date.now();
+
+const MAX_BUFFER = 200;
+
+export function postToPort(port: MessagePort, message: unknown): void {
+  try {
+    port.postMessage(message);
+  } catch (error) {
+    console.warn("sending failed", error);
+  }
+}
+
+function serializeArg(arg: unknown): string {
+  if (typeof arg === "string") return arg;
+  if (arg instanceof Error) return arg.stack || `${arg.name}: ${arg.message}`;
+  try {
+    return JSON.stringify(arg);
+  } catch {
+    return String(arg);
+  }
+}
+
+export function startWorkerControl(
+  name: string,
+  handlers: {
+    onConnect?: (port: MessagePort) => void;
+    onMessage?: (data: any, port: MessagePort, event: MessageEvent) => void;
+    onClose?: (port: MessagePort) => void;
+  } = {}
+): { log: (...args: unknown[]) => void } {
+  const ports = new Set<MessagePort>();
+  // Logs emitted before any tab connects (wasm boot) would otherwise be lost.
+  const preConnect: Array<{ level: string; args: string[] }> = [];
+  // `debug` reads localStorage, which a SharedWorker doesn't have, so this is
+  // toggled by a control message from a tab instead.
+  let debugging = false;
+
+  // A SharedWorker's own console is buried in chrome://inspect, so mirror
+  // everything over each connected tab's control port.
+  const forward = (level: string, rawArgs: unknown[]) => {
+    const args = rawArgs.map(serializeArg);
+    if (!ports.size) {
+      if (preConnect.length < MAX_BUFFER) preConnect.push({ level, args });
+      return;
+    }
+    for (const port of ports)
+      postToPort(port, { type: "console", level, args });
+  };
+
+  for (const level of ["log", "info", "warn", "error", "debug"] as const) {
+    const original = console[level].bind(console);
+    console[level] = (...args: unknown[]) => {
+      original(...args);
+      forward(level, args);
+    };
+  }
+
+  self.addEventListener("error", (event) => {
+    const e = event as ErrorEvent;
+    forward("error", [
+      `uncaught error: ${e.message}`,
+      e.error instanceof Error ? e.error.stack : undefined,
+    ]);
+  });
+
+  self.addEventListener("unhandledrejection", (event) => {
+    const reason = (event as PromiseRejectionEvent).reason;
+    forward("error", [
+      "unhandled rejection:",
+      reason instanceof Error ? reason.stack || reason.message : reason,
+    ]);
+  });
+
+  self.addEventListener("connect", (event) => {
+    const port = (event as MessageEvent).ports[0];
+    handlers.onConnect?.(port);
+
+    port.addEventListener("message", (messageEvent) => {
+      const data = (messageEvent as MessageEvent).data;
+      if (data?.type === "ping") {
+        postToPort(port, {
+          type: "pong",
+          id: data.id,
+          instanceId: WORKER_INSTANCE_ID,
+        });
+        return;
+      }
+      if (data?.type === "debug") {
+        debugging = data.debug;
+        return;
+      }
+      handlers.onMessage?.(data, port, messageEvent as MessageEvent);
+    });
+
+    // Fires when the owning page is destroyed.
+    port.addEventListener("close", () => {
+      ports.delete(port);
+      handlers.onClose?.(port);
+    });
+
+    port.start();
+    postToPort(port, {
+      type: "hello",
+      instanceId: WORKER_INSTANCE_ID,
+      bootTime: WORKER_BOOT_TIME,
+    });
+
+    ports.add(port);
+    for (const { level, args } of preConnect.splice(0)) {
+      postToPort(port, { type: "console", level, args });
+    }
+  });
+
+  console.warn(
+    `[lifecycle] ${name} SharedWorker started (instance ${WORKER_INSTANCE_ID})`
+  );
+
+  return {
+    log: (...args: unknown[]) => {
+      if (debugging) console.log(`[${name}]`, ...args);
+    },
+  };
+}