@syncular/client 0.29.1 → 0.30.1

package/src/multi-tab.ts

@@ -11,11 +11,13 @@
  * survive `postMessage` on a BroadcastChannel):
  *
  *   follower → leader
- *     hello  {t,epoch?,fromId}                — "who's the leader?" on join,
+ *     hello  {t,epoch?,fromId,protocol,schemaVersion}
+ *                                              — "who's the leader?" on join,
  *                                                and the follower's liveness probe
- *     req    {t,epoch,fromId,reqId,method,args}
+ *     req    {t,epoch,fromId,reqId,method,args,protocol,schemaVersion}
  *   leader → all
- *     announce {t,epoch,clientId}             — "I am the leader, this epoch";
+ *     announce {t,epoch,clientId,protocol,schemaVersion}
+ *                                              — "I am the leader, this epoch";
  *                                                the answer to every hello
  *     res      {t,epoch,reqId,ok,value|error} — reply to one req
  *     event    {t,epoch,event}                — fan-out (invalidate/presence/…)
@@ -30,6 +32,14 @@
  * promoter reads the highest epoch it has seen and adds one, so successive
  * leaders always strictly increase it even across the lock-handover gap.
  *
+ * Identity: every hello, req, and announce carries the sender's
+ * {@link MULTI_TAB_PROTOCOL_VERSION} and application schema version. A leader
+ * serves only requests with its own identity. A follower whose leader has a
+ * different identity goes `blocked` with `leader-incompatible` and sends it
+ * nothing. A leader that hears a hello from a newer tab closes its core and
+ * releases the lock, so the newer tab takes over. Tabs from before protocol 1
+ * send no identity and count as older.
+ *
  * Liveness is follower-driven: the leader runs no timer. Browsers throttle
  * the timers of a hidden tab (Chrome's intensive throttling wakes them about
  * once a minute) but still dispatch its BroadcastChannel messages, so a leader
@@ -39,6 +49,9 @@
  * stays unanswered for the rest of the timeout. A leader tab whose main thread
  * processes no messages (hung or frozen) therefore still blocks its followers
  * within `callTimeoutMs`, and a closed leader hands over through the lock.
+ * A forwarded call has no deadline of its own: a live leader may run it behind
+ * a long sync round, exactly as it runs its own tab's calls. It rejects when
+ * the link blocks, when another leader announces, or when the link closes.
  *
  * Presence identity: all tabs share the leader's one connection, so a device
  * is exactly ONE presence peer collectively — `(actorId, leaderClientId)`.
@@ -52,7 +65,43 @@ import { WORKER_FAILED_CODE } from './worker-protocol';
 /** Client-local: a follower call could not reach a leader before its deadline. */
 export const FOLLOWER_TIMEOUT_CODE = 'client.follower_timeout';
 
-/** Default deadline for a follower request (covers a leader-handover gap). */
+/** Client-local: the leader runs a different protocol or schema version. */
+export const LEADER_INCOMPATIBLE_CODE = 'client.leader_incompatible';
+
+/** Client-local: the leader that received a call stopped leading before it answered. */
+export const LEADER_HANDOVER_CODE = 'client.leader_handover';
+
+/**
+ * Version of the leader/follower wire and the forwarded handle API. Bump it
+ * with every change to a message shape or to a forwarded method's arguments
+ * or result, so tabs of different builds never serve each other.
+ */
+export const MULTI_TAB_PROTOCOL_VERSION = 1;
+
+/** What a tab must share with its leader to be served by it. */
+export interface TabIdentity {
+  readonly protocol: number;
+  readonly schemaVersion: number;
+}
+
+/**
+ * Order a peer's identity against our own: -1 older, 0 same, 1 newer. A peer
+ * from before protocol 1 sends no identity and is older.
+ */
+export function compareTabIdentity(
+  peer: { readonly protocol?: number; readonly schemaVersion?: number },
+  own: TabIdentity,
+): -1 | 0 | 1 {
+  if (peer.protocol === undefined || peer.schemaVersion === undefined)
+    return -1;
+  if (peer.protocol !== own.protocol)
+    return peer.protocol < own.protocol ? -1 : 1;
+  if (peer.schemaVersion !== own.schemaVersion)
+    return peer.schemaVersion < own.schemaVersion ? -1 : 1;
+  return 0;
+}
+
+/** Default deadline for a call queued while no leader is bound (the handover gap). */
 export const DEFAULT_FOLLOWER_CALL_TIMEOUT_MS = 10_000;
 /** Max follower calls queued across a handover before we fail loudly. */
 export const DEFAULT_FOLLOWER_QUEUE_LIMIT = 256;
@@ -73,13 +122,27 @@ export type LeadershipState =
       readonly reason: 'leader-unreachable';
       readonly code: typeof FOLLOWER_TIMEOUT_CODE;
       readonly retryable: true;
+    }
+  | {
+      readonly state: 'blocked';
+      readonly reason: 'leader-incompatible';
+      readonly code: typeof LEADER_INCOMPATIBLE_CODE;
+      /** Whether the tab holding the database runs an older or a newer build. */
+      readonly leader: 'older' | 'newer';
+      readonly retryable: true;
     };
 
 // ---------------------------------------------------------------------------
 // Wire messages
 // ---------------------------------------------------------------------------
 
-interface HelloMessage {
+/** Identity fields; absent in messages from tabs before protocol 1. */
+interface IdentityFields {
+  readonly protocol?: number;
+  readonly schemaVersion?: number;
+}
+
+interface HelloMessage extends IdentityFields {
   readonly t: 'hello';
   readonly fromId: string;
   /** Highest epoch the sender has observed (helps a promoter monotonically
@@ -87,7 +150,7 @@ interface HelloMessage {
   readonly epoch?: number;
 }
 
-interface ReqMessage {
+interface ReqMessage extends IdentityFields {
   readonly t: 'req';
   readonly epoch: number;
   readonly fromId: string;
@@ -96,7 +159,7 @@ interface ReqMessage {
   readonly args: readonly unknown[];
 }
 
-interface AnnounceMessage {
+interface AnnounceMessage extends IdentityFields {
   readonly t: 'announce';
   readonly epoch: number;
   readonly clientId: string;
@@ -169,16 +232,20 @@ export function newTabId(): string {
  * Runs on the leader tab. Announces leadership, answers follower `req`s by
  * invoking the (already-running) worker via `invoke`, and rebroadcasts every
  * worker event to followers. Owns nothing about the worker lifecycle — the
- * worker-host stays the single core owner; this is a relay.
+ * worker-host stays the single core owner; this is a relay. A hello from a
+ * newer tab calls `onNewerTab`, whose owner closes the core and releases the
+ * lock.
  */
 export class LeaderBridge {
   readonly #channel: CrossTabChannel;
   readonly #epoch: number;
   readonly #clientId: string;
+  readonly #identity: TabIdentity;
   readonly #invoke: (
     method: string,
     args: readonly unknown[],
   ) => Promise<unknown>;
+  readonly #onNewerTab: () => void;
   readonly #onMessage: (event: { data: MultiTabMessage }) => void;
   #closed = false;
 
@@ -186,12 +253,16 @@ export class LeaderBridge {
     channel: CrossTabChannel;
     epoch: number;
     clientId: string;
+    identity: TabIdentity;
     invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
+    onNewerTab: () => void;
   }) {
     this.#channel = options.channel;
     this.#epoch = options.epoch;
     this.#clientId = options.clientId;
+    this.#identity = options.identity;
     this.#invoke = options.invoke;
+    this.#onNewerTab = options.onNewerTab;
     this.#onMessage = (event) => this.#handle(event.data);
     this.#channel.addEventListener('message', this.#onMessage);
     this.announce();
@@ -204,6 +275,7 @@ export class LeaderBridge {
       t: 'announce',
       epoch: this.#epoch,
       clientId: this.#clientId,
+      ...this.#identity,
     });
   }
 
@@ -216,7 +288,12 @@ export class LeaderBridge {
   #handle(message: MultiTabMessage): void {
     if (this.#closed) return;
     if (message.t === 'hello') {
-      // A follower joined or probes liveness: tell it who leads.
+      // A newer tab takes over; any other follower learns who leads.
+      if (compareTabIdentity(message, this.#identity) > 0) {
+        this.close();
+        this.#onNewerTab();
+        return;
+      }
       this.announce();
       return;
     }
@@ -225,6 +302,20 @@ export class LeaderBridge {
     // follower will re-stamp once it sees our announce.
     if (message.epoch !== this.#epoch) return;
     const { reqId, method, args } = message;
+    if (compareTabIdentity(message, this.#identity) !== 0) {
+      this.#channel.postMessage({
+        t: 'res',
+        epoch: this.#epoch,
+        reqId,
+        ok: false,
+        error: {
+          code: LEADER_INCOMPATIBLE_CODE,
+          message: 'the leader runs a different protocol or schema version',
+          retryable: true,
+        },
+      });
+      return;
+    }
     this.#invoke(method, args).then(
       (value) => {
         this.#channel.postMessage({
@@ -289,7 +380,6 @@ interface QueuedCall {
 interface InFlight {
   readonly resolve: (value: unknown) => void;
   readonly reject: (error: unknown) => void;
-  readonly cancelTimer: () => void;
 }
 
 /**
@@ -299,11 +389,13 @@ interface InFlight {
  * Feeds fanned-out events to `onEvent`. Learns leadership changes and hands
  * the resolved leader `clientId` back through `onLeaderChange`. Probes the
  * bound leader with `hello` after a quiet period and reports `blocked` only
- * when a probe goes unanswered (see the module comment).
+ * when a probe goes unanswered, or when the leader's identity differs from
+ * this tab's (see the module comment).
  */
 export class FollowerLink {
   readonly #channel: CrossTabChannel;
   readonly #fromId: string;
+  readonly #identity: TabIdentity;
   readonly #onEvent: (event: SyncWorkerEvent) => void;
   readonly #onLeaderChange: (clientId: string) => void;
   readonly #onStateChange: (state: LeadershipState) => void;
@@ -335,6 +427,7 @@ export class FollowerLink {
   constructor(options: {
     channel: CrossTabChannel;
     fromId: string;
+    identity: TabIdentity;
     onEvent: (event: SyncWorkerEvent) => void;
     onLeaderChange: (clientId: string) => void;
     onStateChange?: (state: LeadershipState) => void;
@@ -344,6 +437,7 @@ export class FollowerLink {
   }) {
     this.#channel = options.channel;
     this.#fromId = options.fromId;
+    this.#identity = options.identity;
     this.#onEvent = options.onEvent;
     this.#onLeaderChange = options.onLeaderChange;
     this.#onStateChange = options.onStateChange ?? (() => {});
@@ -442,13 +536,7 @@ export class FollowerLink {
       );
     }
     if (this.#state.state === 'blocked') {
-      return Promise.reject(
-        new ClientSyncError(
-          FOLLOWER_TIMEOUT_CODE,
-          'the follower cannot reach the tab that owns the database',
-          true,
-        ),
-      );
+      return Promise.reject(this.#blockedError());
     }
     return new Promise((resolve, reject) => {
       const queued: QueuedCall = {
@@ -491,22 +579,11 @@ export class FollowerLink {
 
   #send(queued: QueuedCall): void {
     const reqId = this.#nextReqId++;
-    // The deadline fails this one call. Leader reachability is decided by the
-    // liveness probe alone, so a slow call against a live leader leaves the
-    // link bound.
+    // No deadline: a live leader may queue the call behind a long sync round.
+    // The liveness probe, a leader change, or close settles it otherwise.
     this.#inFlight.set(reqId, {
       resolve: queued.resolve,
       reject: queued.reject,
-      cancelTimer: this.#schedule(() => {
-        this.#inFlight.delete(reqId);
-        queued.reject(
-          new ClientSyncError(
-            FOLLOWER_TIMEOUT_CODE,
-            'the leader did not answer within the follower call timeout',
-            true,
-          ),
-        );
-      }, this.#callTimeoutMs),
     });
     this.#channel.postMessage({
       t: 'req',
@@ -515,9 +592,33 @@ export class FollowerLink {
       reqId,
       method: queued.method,
       args: queued.args,
+      ...this.#identity,
     });
   }
 
+  /** The rejection for a call made while the link is blocked. */
+  #blockedError(): ClientSyncError {
+    return this.#state.state === 'blocked' &&
+      this.#state.reason === 'leader-incompatible'
+      ? new ClientSyncError(
+          LEADER_INCOMPATIBLE_CODE,
+          'the tab that owns the database runs a different protocol or schema version',
+          true,
+        )
+      : new ClientSyncError(
+          FOLLOWER_TIMEOUT_CODE,
+          'the follower cannot reach the tab that owns the database',
+          true,
+        );
+  }
+
+  /** Reject every forwarded call; their leader will not answer them. */
+  #rejectInFlight(error: ClientSyncError): void {
+    const pending = [...this.#inFlight.values()];
+    this.#inFlight.clear();
+    for (const inflight of pending) inflight.reject(error);
+  }
+
   #dropQueued(queued: QueuedCall): void {
     const index = this.#queue.indexOf(queued);
     if (index >= 0) this.#queue.splice(index, 1);
@@ -531,9 +632,24 @@ export class FollowerLink {
       }
       // Ignore a stale announce (older than the leader we already track).
       if (message.epoch < this.#epoch) return;
+      const relation = compareTabIdentity(message, this.#identity);
+      if (relation !== 0) {
+        this.#setIncompatible(relation < 0 ? 'older' : 'newer');
+        return;
+      }
       const changed =
         message.epoch !== this.#epoch ||
         message.clientId !== this.#leaderClientId;
+      // Calls sent to the previous leader get no answer from this one.
+      if (changed && this.#epoch >= 0) {
+        this.#rejectInFlight(
+          new ClientSyncError(
+            LEADER_HANDOVER_CODE,
+            'the leader changed before it answered the call',
+            true,
+          ),
+        );
+      }
       this.#epoch = message.epoch;
       this.#leaderClientId = message.clientId;
       if (changed) this.#onLeaderChange(message.clientId);
@@ -554,7 +670,6 @@ export class FollowerLink {
       const inflight = this.#inFlight.get(message.reqId);
       if (inflight === undefined) return;
       this.#inFlight.delete(message.reqId);
-      inflight.cancelTimer();
       if (message.ok) {
         inflight.resolve(message.value);
       } else {
@@ -590,11 +705,18 @@ export class FollowerLink {
   /**
    * The leader we were bound to went away (its lock released). Un-bind so new
    * calls queue again; re-request an announce so the next leader finds us.
-   * In-flight calls stay pending — their per-call timeout is the backstop,
-   * and the winner's announce will flush any that were queued.
+   * Calls in flight to the departed leader reject; the winner's announce
+   * flushes the queued ones.
    */
   unbind(): void {
     if (this.#closed) return;
+    this.#rejectInFlight(
+      new ClientSyncError(
+        LEADER_HANDOVER_CODE,
+        'the leader released the database before it answered the call',
+        true,
+      ),
+    );
     this.#epoch = -1;
     this.#leaderClientId = '';
     this.#setState({ state: 'waiting', reason: 'handover' });
@@ -602,6 +724,22 @@ export class FollowerLink {
     this.#probe();
   }
 
+  /**
+   * This tab won the lock and runs its own core: calls queued for the next
+   * leader run on `invoke` instead of failing, then the link closes.
+   */
+  handOver(
+    invoke: (method: string, args: readonly unknown[]) => Promise<unknown>,
+  ): void {
+    const queued = this.#queue;
+    this.#queue = [];
+    for (const call of queued) {
+      call.cancelTimer?.();
+      invoke(call.method, call.args).then(call.resolve, call.reject);
+    }
+    this.close();
+  }
+
   close(): void {
     if (this.#closed) return;
     this.#closed = true;
@@ -611,11 +749,7 @@ export class FollowerLink {
       WORKER_FAILED_CODE,
       'the follower link was closed',
     );
-    for (const inflight of this.#inFlight.values()) {
-      inflight.cancelTimer();
-      inflight.reject(closedError);
-    }
-    this.#inFlight.clear();
+    this.#rejectInFlight(closedError);
     for (const queued of this.#queue) {
       queued.cancelTimer?.();
       queued.reject(closedError);
@@ -631,7 +765,12 @@ export class FollowerLink {
     const previous = this.#state;
     if (
       previous.state === state.state &&
-      (state.state === 'blocked' ||
+      ((state.state === 'blocked' &&
+        previous.state === 'blocked' &&
+        previous.reason === state.reason &&
+        (state.reason !== 'leader-incompatible' ||
+          (previous.reason === 'leader-incompatible' &&
+            previous.leader === state.leader))) ||
         (state.state === 'waiting' &&
           previous.state === 'waiting' &&
           previous.reason === state.reason) ||
@@ -656,7 +795,35 @@ export class FollowerLink {
       t: 'hello',
       fromId: this.#fromId,
       epoch: this.#maxEpochSeen,
+      ...this.#identity,
+    });
+  }
+
+  /**
+   * The leader runs another build. Send it nothing and stay unbound until a
+   * leader with this tab's identity announces (a newer leader's own hello
+   * already asked an older one to step down; see the module comment).
+   */
+  #setIncompatible(leader: 'older' | 'newer'): void {
+    this.#clearReachabilityTimers();
+    this.#epoch = -1;
+    this.#leaderClientId = '';
+    this.#setState({
+      state: 'blocked',
+      reason: 'leader-incompatible',
+      code: LEADER_INCOMPATIBLE_CODE,
+      leader,
+      retryable: true,
     });
+    const error = this.#blockedError();
+    this.#rejectInFlight(error);
+    const queued = this.#queue;
+    this.#queue = [];
+    for (const call of queued) {
+      call.cancelTimer?.();
+      call.reject(error);
+    }
+    this.#resolveBindWaiters();
   }
 
   /**
@@ -671,6 +838,7 @@ export class FollowerLink {
       code: FOLLOWER_TIMEOUT_CODE,
       retryable: true,
     });
+    this.#rejectInFlight(this.#blockedError());
     const reprobe = (): void => {
       this.#cancelProbe = this.#schedule(() => {
         reprobe();

package/src/reactive-store.ts

@@ -1,4 +1,5 @@
 import {
+  blockedLeadershipAvailability,
   classifySyncAvailability,
   type SyncAvailability,
 } from './availability';
@@ -314,6 +315,8 @@ function reconcileRows<Row>(
 
 interface CachedObservation {
   onChange(batch: ClientChangeBatch): void;
+  /** A leader serves this tab again (it leads or follows a bound leader). */
+  onLeaderServing?(): void;
   reset(): void;
   dispose(): void;
 }
@@ -355,6 +358,9 @@ class ObservationCache {
   onChange(batch: ClientChangeBatch): void {
     for (const entry of this.#active) entry.onChange(batch);
   }
+  onLeaderServing(): void {
+    for (const entry of this.#active) entry.onLeaderServing?.();
+  }
   clear(): void {
     for (const entry of this.#entries.values()) entry.dispose();
     this.#entries.clear();
@@ -432,51 +438,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
         this.#onRoundFailureChange(),
       );
       this.#onAvailabilityChange();
-      if (this.spec.claimCoverage !== false) {
-        const claims: Promise<void>[] = [];
-        // A composed spec carries one coverage entry per query branch, and
-        // several branches can target the same base. One claim per distinct
-        // base covers the union of their units; a later entry for the same
-        // base does not replace the earlier one.
-        const unitsByBase = new Map<
-          string,
-          { base: WindowBase; units: Set<string> }
-        >();
-        for (const coverage of this.spec.coverage ?? []) {
-          const baseKey = windowBaseKey(coverage.base);
-          const existing = unitsByBase.get(baseKey);
-          if (existing === undefined) {
-            unitsByBase.set(baseKey, {
-              base: coverage.base,
-              units: new Set(coverage.units),
-            });
-          } else {
-            for (const unit of coverage.units) existing.units.add(unit);
-          }
-        }
-        for (const { base, units } of unitsByBase.values()) {
-          claims.push(this.store.setWindowClaim(this.#owner, base, [...units]));
-        }
-        const generation = this.#generation;
-        this.#claimPending = claims.length > 0;
-        if (claims.length > 0)
-          void Promise.all(claims).then(
-            () => {
-              if (generation !== this.#generation || this.#listeners.size === 0)
-                return;
-              this.#claimPending = false;
-              if (!this.#running && this.#state.phase !== 'ready')
-                this.#requestRead();
-            },
-            (error: unknown) => {
-              if (generation !== this.#generation || this.#listeners.size === 0)
-                return;
-              this.#claimPending = false;
-              this.#claimError = errorOf(error);
-              this.#requestRead();
-            },
-          );
-      }
+      this.#claimCoverage();
       this.#requestRead();
     }
     return () => {
@@ -492,6 +454,54 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     };
   };
 
+  /** Claim this query's window coverage; a failure surfaces on the next read. */
+  #claimCoverage(): void {
+    if (this.spec.claimCoverage === false) return;
+    const claims: Promise<void>[] = [];
+    // A composed spec carries one coverage entry per query branch, and
+    // several branches can target the same base. One claim per distinct
+    // base covers the union of their units; a later entry for the same
+    // base does not replace the earlier one.
+    const unitsByBase = new Map<
+      string,
+      { base: WindowBase; units: Set<string> }
+    >();
+    for (const coverage of this.spec.coverage ?? []) {
+      const baseKey = windowBaseKey(coverage.base);
+      const existing = unitsByBase.get(baseKey);
+      if (existing === undefined) {
+        unitsByBase.set(baseKey, {
+          base: coverage.base,
+          units: new Set(coverage.units),
+        });
+      } else {
+        for (const unit of coverage.units) existing.units.add(unit);
+      }
+    }
+    for (const { base, units } of unitsByBase.values()) {
+      claims.push(this.store.setWindowClaim(this.#owner, base, [...units]));
+    }
+    const generation = this.#generation;
+    this.#claimPending = claims.length > 0;
+    if (claims.length > 0)
+      void Promise.all(claims).then(
+        () => {
+          if (generation !== this.#generation || this.#listeners.size === 0)
+            return;
+          this.#claimPending = false;
+          if (!this.#running && this.#state.phase !== 'ready')
+            this.#requestRead();
+        },
+        (error: unknown) => {
+          if (generation !== this.#generation || this.#listeners.size === 0)
+            return;
+          this.#claimPending = false;
+          this.#claimError = errorOf(error);
+          this.#requestRead();
+        },
+      );
+  }
+
   refresh = (): void => {
     if (this.#delegate !== undefined) this.#delegate.refresh();
     else this.#requestRead(true);
@@ -518,6 +528,15 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     this.reset();
   }
 
+  /** A claim rejected while no leader served this tab (blocked, handover,
+   * another build) is claimed again; its stored error would fail every read. */
+  onLeaderServing(): void {
+    if (this.#delegate !== undefined || this.#claimError === undefined) return;
+    this.#claimError = undefined;
+    this.#claimCoverage();
+    this.#requestRead();
+  }
+
   onChange(batch: ClientChangeBatch): void {
     if (!batchMatches(batch, this.spec)) return;
     if (batch.revision > this.#desiredRevision) {
@@ -979,12 +998,10 @@ export class ReactiveClientStore {
     const snapshot = this.status.getSnapshot();
     if (snapshot.status === undefined) {
       return snapshot.leadership?.state === 'blocked'
-        ? {
-            state: 'blocked',
-            reason: 'leader-unreachable',
-            currentSchemaVersion: this.client.currentSchemaVersion ?? 0,
-            retryable: true,
-          }
+        ? blockedLeadershipAvailability(
+            snapshot.leadership,
+            this.client.currentSchemaVersion ?? 0,
+          )
         : { state: 'ready' };
     }
     return classifySyncAvailability(snapshot.status, snapshot.leadership);
@@ -1173,6 +1190,14 @@ export class ReactiveClientStore {
         leadership,
       });
       if (previous.isLoading) this.status.refresh();
+      // Window edits that failed while no leader served this tab apply now;
+      // an applied group compares equal and makes no call.
+      if (leadership.state === 'leader' || leadership.state === 'follower') {
+        for (const group of this.#windowClaims.values()) {
+          if (group.claims.size > 0) this.#scheduleWindow(group);
+        }
+        this.#queries.onLeaderServing();
+      }
     });
     this.status.refresh();
     this.conflicts.refresh();