@spooky-sync/core 0.0.1-canary.16 → 0.0.1-canary.161

package/src/services/tabs/broker-client.ts

@@ -0,0 +1,283 @@
+/**
+ * Per-tab connection to the SharedWorker broker. Owns: the hello handshake,
+ * pong replies + the ping watchdog (a silent broker means the browser killed
+ * the SharedWorker; reconnect with a fresh one), visibility reporting, and the
+ * pagehide/freeze shutdown notifications. Role decisions and port handling are
+ * the coordinator's job; this class only surfaces them as events.
+ */
+import type { Logger } from '../logger/index';
+import {
+  PING_INTERVAL_MS,
+  PONG_TIMEOUT_MS,
+  type BrokerToTabMessage,
+  type HeldLeadership,
+  type TabId,
+  type TabToBrokerMessage,
+  type TabVisibility,
+} from './protocol';
+
+export interface BrokerClientEvents {
+  onBecomeLeader(msg: {
+    leadershipId: number;
+    forceTakeover: boolean;
+    allowMemoryFallback: boolean;
+    resumeHeld: boolean;
+  }): void;
+  onDemote(leadershipId: number): void;
+  onLeaderReady(leadershipId: number, leaderTabId: TabId): void;
+  /** Leader side: the broker minted ports for a follower. */
+  onAttachFollowerPorts(
+    followerTabId: TabId,
+    leadershipId: number,
+    dbPort: MessagePort,
+    syncPort: MessagePort
+  ): void;
+  /** Follower side: our ports into the current leader. */
+  onUseFollowerPorts(
+    leaderTabId: TabId,
+    leadershipId: number,
+    dbPort: MessagePort,
+    syncPort: MessagePort
+  ): void;
+  onCloseFollowerPorts(leadershipId: number): void;
+  onUnsupported(reason: string): void;
+  /** The broker restarted (instance id changed or pings stopped); the client
+   *  already re-helloed. Roles survive only via become-leader/use-ports. */
+  onBrokerRestarted(): void;
+}
+
+/** What the tab reports about itself on (re)connect. */
+export interface BrokerHello {
+  fingerprint: string;
+  bucketId: string;
+  heldLeadership: () => HeldLeadership | null;
+}
+
+export class TabBrokerClient {
+  private worker: SharedWorker | null = null;
+  private brokerInstanceId: string | null = null;
+  private watchdog: ReturnType<typeof setInterval> | null = null;
+  private lastPingAt = 0;
+  private closed = false;
+  private helloState: BrokerHello | null = null;
+
+  constructor(
+    private workerUrl: URL,
+    readonly tabId: TabId,
+    private events: BrokerClientEvents,
+    private logger: Logger
+  ) {}
+
+  /** Connect and hello. Resolves once broker-hello arrives (or rejects on
+   *  timeout / SharedWorker error, in which case the caller goes solo). */
+  connect(hello: BrokerHello): Promise<void> {
+    this.helloState = hello;
+    this.installLifecycleListeners();
+    return this.openWorker();
+  }
+
+  private openWorker(): Promise<void> {
+    if (this.closed || !this.helloState) return Promise.reject(new Error('broker client closed'));
+    return new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const settle = (fn: () => void) => {
+        if (!settled) {
+          settled = true;
+          fn();
+        }
+      };
+      let worker: SharedWorker;
+      try {
+        worker = new SharedWorker(this.workerUrl, { type: 'module', name: 'sp00ky-tabs-broker' });
+      } catch (e) {
+        reject(e);
+        return;
+      }
+      this.worker = worker;
+      const timeout = setTimeout(() => settle(() => reject(new Error('broker hello timeout'))), 5000);
+      worker.onerror = () => {
+        clearTimeout(timeout);
+        settle(() => reject(new Error('SharedWorker failed to start')));
+      };
+      worker.port.onmessage = (ev: MessageEvent) => {
+        const msg = ev.data as BrokerToTabMessage;
+        if (!msg || typeof msg !== 'object') return;
+        if (msg.type === 'broker-hello') {
+          clearTimeout(timeout);
+          this.noteInstance(msg.brokerInstanceId);
+          this.lastPingAt = Date.now();
+          this.startWatchdog();
+          settle(resolve);
+          return;
+        }
+        this.handleMessage(msg, (ev.ports ?? []) as readonly MessagePort[]);
+      };
+      worker.port.onmessageerror = () => this.reconnect('messageerror');
+      worker.port.start?.();
+      this.send({
+        type: 'hello',
+        tabId: this.tabId,
+        fingerprint: this.helloState!.fingerprint,
+        bucketId: this.helloState!.bucketId,
+        visibility: currentVisibility(),
+        heldLeadership: this.helloState!.heldLeadership(),
+      });
+    });
+  }
+
+  private noteInstance(id: string): void {
+    if (this.brokerInstanceId !== null && this.brokerInstanceId !== id) {
+      this.events.onBrokerRestarted();
+    }
+    this.brokerInstanceId = id;
+  }
+
+  private handleMessage(msg: BrokerToTabMessage, ports: readonly MessagePort[]): void {
+    // Any message from a NEW instance implies a restart happened while our
+    // watchdog had not fired yet.
+    if ('brokerInstanceId' in msg) this.noteInstance(msg.brokerInstanceId);
+    switch (msg.type) {
+      case 'ping':
+        this.lastPingAt = Date.now();
+        this.send({ type: 'pong', tabId: this.tabId });
+        break;
+      case 'become-leader':
+        this.events.onBecomeLeader({
+          leadershipId: msg.leadershipId,
+          forceTakeover: msg.forceTakeover,
+          allowMemoryFallback: msg.allowMemoryFallback,
+          resumeHeld: msg.resumeHeld,
+        });
+        break;
+      case 'demote':
+        this.events.onDemote(msg.leadershipId);
+        break;
+      case 'leader-ready':
+        this.events.onLeaderReady(msg.leadershipId, msg.leaderTabId);
+        break;
+      case 'attach-follower-ports':
+        if (ports.length >= 2) {
+          this.events.onAttachFollowerPorts(msg.followerTabId, msg.leadershipId, ports[0], ports[1]);
+        }
+        break;
+      case 'use-follower-ports':
+        if (ports.length >= 2) {
+          this.events.onUseFollowerPorts(msg.leaderTabId, msg.leadershipId, ports[0], ports[1]);
+        }
+        break;
+      case 'close-follower-ports':
+        this.events.onCloseFollowerPorts(msg.leadershipId);
+        break;
+      case 'unsupported':
+        this.logger.warn(
+          { reason: msg.reason, Category: 'sp00ky-client::BrokerClient' },
+          'Broker rejected this tab; running solo'
+        );
+        this.events.onUnsupported(msg.reason);
+        this.close();
+        break;
+    }
+  }
+
+  send(msg: TabToBrokerMessage): void {
+    try {
+      this.worker?.port.postMessage(msg);
+    } catch {
+      /* dead port; watchdog reconnects */
+    }
+  }
+
+  /** The tab moved to a different bucket: re-hello under the new namespace.
+   *  The broker treats a re-hello of a known tabId as leave + rejoin. */
+  rehello(hello: BrokerHello): Promise<void> {
+    this.helloState = hello;
+    if (!this.worker) return this.openWorker();
+    this.send({
+      type: 'hello',
+      tabId: this.tabId,
+      fingerprint: hello.fingerprint,
+      bucketId: hello.bucketId,
+      visibility: currentVisibility(),
+      heldLeadership: hello.heldLeadership(),
+    });
+    return Promise.resolve();
+  }
+
+  private startWatchdog(): void {
+    if (this.watchdog) return;
+    this.watchdog = setInterval(() => {
+      if (Date.now() - this.lastPingAt > PING_INTERVAL_MS + PONG_TIMEOUT_MS) {
+        this.reconnect('broker pings stopped');
+      }
+    }, PING_INTERVAL_MS);
+  }
+
+  private reconnect(reason: string): void {
+    if (this.closed) return;
+    this.logger.info(
+      { reason, Category: 'sp00ky-client::BrokerClient' },
+      'Reconnecting to the tabs broker'
+    );
+    try {
+      this.worker?.port.close();
+    } catch {
+      /* ignore */
+    }
+    this.worker = null;
+    this.brokerInstanceId = null;
+    this.events.onBrokerRestarted();
+    void this.openWorker().catch((e) => {
+      this.logger.warn(
+        { err: e, Category: 'sp00ky-client::BrokerClient' },
+        'Broker reconnect failed; staying detached until the next watchdog tick'
+      );
+    });
+  }
+
+  private installLifecycleListeners(): void {
+    if (typeof window === 'undefined' || typeof document === 'undefined') return;
+    document.addEventListener('visibilitychange', () => {
+      if (!this.helloState) return;
+      this.send({
+        type: 'visibility',
+        tabId: this.tabId,
+        bucketId: this.helloState.bucketId,
+        visibility: currentVisibility(),
+      });
+    });
+    // pagehide fires for both close and bfcache entry; treat both as a full
+    // departure (a bfcache restore re-hellos via pageshow below). freeze is
+    // Chromium's battery-saver signal; leaving proactively hands leadership
+    // over in ~0s instead of waiting out the pong timeout.
+    const leave = () => {
+      if (this.helloState) {
+        this.send({ type: 'shutdown', tabId: this.tabId, bucketId: this.helloState.bucketId });
+      }
+    };
+    window.addEventListener('pagehide', leave);
+    document.addEventListener('freeze', leave);
+    window.addEventListener('pageshow', (e: PageTransitionEvent) => {
+      if (e.persisted && this.helloState) void this.rehello(this.helloState);
+    });
+    document.addEventListener('resume', () => {
+      if (this.helloState) void this.rehello(this.helloState);
+    });
+  }
+
+  close(): void {
+    this.closed = true;
+    if (this.watchdog) clearInterval(this.watchdog);
+    this.watchdog = null;
+    try {
+      this.worker?.port.close();
+    } catch {
+      /* ignore */
+    }
+    this.worker = null;
+  }
+}
+
+function currentVisibility(): TabVisibility {
+  if (typeof document === 'undefined') return 'visible';
+  return document.visibilityState === 'hidden' ? 'hidden' : 'visible';
+}

package/src/services/tabs/broker.test.ts

@@ -0,0 +1,278 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { handleConnect, __resetBrokerForTests } from './tabs-broker-worker';
+import { fakeChannel, flush, FakePort } from './fake-ports.fixture';
+import type { BrokerToTabMessage, TabToBrokerMessage } from './protocol';
+
+/** A connected fake tab: records broker messages, exposes a send helper. */
+interface TestTab {
+  tabId: string;
+  received: { msg: BrokerToTabMessage; ports: FakePort[] }[];
+  send: (msg: TabToBrokerMessage) => void;
+  port: FakePort;
+  /** Messages of one type, newest last. */
+  ofType: <T extends BrokerToTabMessage['type']>(
+    t: T
+  ) => Extract<BrokerToTabMessage, { type: T }>[];
+}
+
+function connectTab(tabId: string, opts: { bucket?: string; fingerprint?: string } = {}): TestTab {
+  const { port1, port2 } = fakeChannel();
+  handleConnect(port1 as unknown as MessagePort);
+  const received: TestTab['received'] = [];
+  port2.onmessage = (ev) => received.push({ msg: ev.data, ports: ev.ports });
+  const tab: TestTab = {
+    tabId,
+    received,
+    port: port2,
+    send: (msg) => port2.postMessage(msg),
+    ofType: (t) => received.filter((r) => r.msg.type === t).map((r) => r.msg) as any,
+  };
+  tab.send({
+    type: 'hello',
+    tabId,
+    fingerprint: opts.fingerprint ?? 'fp-test',
+    bucketId: opts.bucket ?? 'anon',
+    visibility: 'visible',
+    heldLeadership: null,
+  });
+  return tab;
+}
+
+/** Complete the promotion handshake for whichever tab got become-leader. */
+async function ackLeadership(tab: TestTab, bucket = 'anon'): Promise<number> {
+  await flush();
+  const grants = tab.ofType('become-leader');
+  expect(grants.length).toBeGreaterThan(0);
+  const leadershipId = grants[grants.length - 1].leadershipId;
+  tab.send({ type: 'leader-ready', tabId: tab.tabId, bucketId: bucket, leadershipId });
+  await flush();
+  return leadershipId;
+}
+
+beforeEach(() => {
+  __resetBrokerForTests();
+  vi.useFakeTimers();
+});
+afterEach(() => {
+  __resetBrokerForTests();
+  vi.useRealTimers();
+});
+
+// The broker is the single arbiter of who owns the OPFS pool. These tests
+// drive it with fake ports exactly like real tabs would.
+describe('tabs broker: election', () => {
+  it('elects exactly one leader for the first tab and announces readiness', async () => {
+    const a = connectTab('tab-a');
+    await flush();
+    expect(a.ofType('broker-hello')).toHaveLength(1);
+    const id = await ackLeadership(a);
+    expect(a.ofType('leader-ready').map((m) => m.leaderTabId)).toContain('tab-a');
+    expect(id).toBeGreaterThan(0);
+  });
+
+  it('attaches a second tab as follower with a db+sync port pair', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+
+    // No second become-leader; instead ports flow both ways.
+    expect(b.ofType('become-leader')).toHaveLength(0);
+    const attach = a.received.filter((r) => r.msg.type === 'attach-follower-ports');
+    const use = b.received.filter((r) => r.msg.type === 'use-follower-ports');
+    expect(attach).toHaveLength(1);
+    expect(use).toHaveLength(1);
+    expect(attach[0].ports).toHaveLength(2);
+    expect(use[0].ports).toHaveLength(2);
+    // The two db ports are entangled ends of ONE channel: a message posted on
+    // the leader's end arrives on the follower's end. (The broker mints REAL
+    // node MessageChannels here; only the control-plane ports are fakes.)
+    const leaderDb = attach[0].ports[0] as unknown as MessagePort;
+    const followerDb = use[0].ports[0] as unknown as MessagePort;
+    const got = new Promise<unknown>((resolve) => {
+      followerDb.onmessage = (ev: MessageEvent) => resolve(ev.data);
+    });
+    leaderDb.postMessage('entangled?');
+    vi.useRealTimers();
+    await expect(got).resolves.toBe('entangled?');
+    leaderDb.close();
+    followerDb.close();
+    vi.useFakeTimers();
+  });
+
+  it('stops re-minting follower ports once the leader confirms attachment', async () => {
+    const a = connectTab('tab-a');
+    const leadershipId = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({
+      type: 'follower-port-attached',
+      tabId: 'tab-a',
+      bucketId: 'anon',
+      leadershipId,
+      followerTabId: 'tab-b',
+    });
+    await flush();
+    const before = b.ofType('use-follower-ports').length;
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(b.ofType('use-follower-ports').length).toBe(before);
+  });
+
+  it('re-mints follower ports with backoff while unconfirmed', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    expect(b.ofType('use-follower-ports')).toHaveLength(1);
+    await vi.advanceTimersByTimeAsync(1000);
+    await flush();
+    expect(b.ofType('use-follower-ports')).toHaveLength(2);
+    await vi.advanceTimersByTimeAsync(2000);
+    await flush();
+    expect(b.ofType('use-follower-ports')).toHaveLength(3);
+  });
+
+  it('rejects a tab whose fingerprint differs from the first hello', async () => {
+    connectTab('tab-a', { fingerprint: 'fp-1' });
+    const b = connectTab('tab-b', { fingerprint: 'fp-2' });
+    await flush();
+    expect(b.ofType('unsupported').map((m) => m.reason)).toEqual(['fingerprint-mismatch']);
+  });
+
+  it('keeps leadership ids monotonic across handoffs', async () => {
+    const a = connectTab('tab-a');
+    const id1 = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({ type: 'shutdown', tabId: 'tab-a', bucketId: 'anon' });
+    await flush();
+    const id2 = await ackLeadership(b);
+    expect(id2).toBeGreaterThan(id1);
+  });
+});
+
+describe('tabs broker: failover', () => {
+  it('promotes the follower when the leader shuts down gracefully', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({ type: 'shutdown', tabId: 'tab-a', bucketId: 'anon' });
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+  });
+
+  it('evicts a leader that misses pongs and re-elects', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    // b keeps answering pings, a goes silent.
+    b.port.onmessage = (ev) => {
+      b.received.push({ msg: ev.data, ports: ev.ports });
+      if (ev.data.type === 'ping') b.send({ type: 'pong', tabId: 'tab-b' });
+    };
+    await vi.advanceTimersByTimeAsync(21_000);
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+  });
+
+  it('applies a failure backoff and grants allowMemoryFallback after 3 opfs cycles', async () => {
+    const a = connectTab('tab-a');
+    await flush();
+    for (let cycle = 0; cycle < 3; cycle++) {
+      const grants = a.ofType('become-leader');
+      const last = grants[grants.length - 1];
+      expect(last.allowMemoryFallback).toBe(false);
+      a.send({
+        type: 'leader-failed',
+        tabId: 'tab-a',
+        bucketId: 'anon',
+        leadershipId: last.leadershipId,
+        reason: 'opfs-unavailable: locked',
+      });
+      await flush();
+      // The 1s candidate backoff must pass before the next nomination.
+      await vi.advanceTimersByTimeAsync(1100);
+      await flush();
+    }
+    const grants = a.ofType('become-leader');
+    expect(grants[grants.length - 1].allowMemoryFallback).toBe(true);
+  });
+
+  it('demotes a stale leader-ready from a superseded promotion', async () => {
+    const a = connectTab('tab-a');
+    const staleId = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({ type: 'shutdown', tabId: 'tab-a', bucketId: 'anon' });
+    await flush();
+    await ackLeadership(b);
+    // The departed tab reconnects and replays its OLD leader-ready.
+    const a2 = connectTab('tab-a');
+    await flush();
+    a2.send({ type: 'leader-ready', tabId: 'tab-a', bucketId: 'anon', leadershipId: staleId });
+    await flush();
+    expect(a2.ofType('demote').map((m) => m.leadershipId)).toContain(staleId);
+  });
+
+  it('prefers a candidate that still holds a live worker (broker restart path)', async () => {
+    // Fresh broker instance, two tabs hello simultaneously; one held leadership
+    // from before the restart.
+    const a = connectTab('tab-a');
+    await flush();
+    const idA = await ackLeadership(a);
+    void idA;
+    __resetBrokerForTests();
+    const b2 = connectTab('tab-b');
+    void b2;
+    const { port1, port2 } = fakeChannel();
+    handleConnect(port1 as unknown as MessagePort);
+    const received: TestTab['received'] = [];
+    port2.onmessage = (ev) => received.push({ msg: ev.data, ports: ev.ports });
+    port2.postMessage({
+      type: 'hello',
+      tabId: 'tab-a',
+      fingerprint: 'fp-test',
+      bucketId: 'anon',
+      visibility: 'hidden',
+      heldLeadership: { leadershipId: 7, workerLockName: 'sp00ky-tabs:fp-test:anon:worker:7' },
+    });
+    await flush();
+    // Despite being hidden (b is visible), the holder wins with resumeHeld.
+    const grant = received.find((r) => r.msg.type === 'become-leader');
+    expect(grant).toBeDefined();
+    expect((grant!.msg as { resumeHeld: boolean }).resumeHeld).toBe(true);
+  });
+});
+
+describe('tabs broker: namespaces', () => {
+  it('separates tabs by bucket: one leader per bucket', async () => {
+    const a = connectTab('tab-a', { bucket: 'user1' });
+    await ackLeadership(a, 'user1');
+    const b = connectTab('tab-b', { bucket: 'user2' });
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+  });
+
+  it('re-elects the old namespace immediately when a leader re-hellos into a new bucket', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    // a switches buckets: same tabId, new bucket. b must be promoted in anon
+    // without waiting for a pong eviction.
+    a.send({
+      type: 'hello',
+      tabId: 'tab-a',
+      fingerprint: 'fp-test',
+      bucketId: 'user1',
+      visibility: 'visible',
+      heldLeadership: null,
+    });
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+    // and a is offered leadership of the new bucket.
+    expect(a.ofType('become-leader').length).toBeGreaterThan(1);
+  });
+});