@absolutejs/sync 1.18.0 → 1.18.2

package/dist/engine/syncEngine.d.ts

@@ -51,15 +51,26 @@ export type SubscribeArgs<T, P, Ctx> = {
     params: P;
     /** Caller context (e.g. session); passed to hydrate/match/authorize. */
     ctx: Ctx;
-    /** Receives every non-empty diff (with its version) after the initial reply. */
-    onDiff: (diff: ViewDiff<T>, version: number) => void;
     /**
-     * Resume from a version the client already applied. When the change log still
-     * covers `(since, now]` for a single-table collection, the engine replies with
-     * a catch-up diff instead of a full snapshot; otherwise it falls back to a
-     * snapshot.
+     * Receives every non-empty diff (with its version) after the initial
+     * reply. 1.18.0+: a third optional `cursor` argument carries the
+     * cross-instance resume cursor as of this diff. Callers that ignore
+     * the 3rd arg keep working unchanged.
      */
-    since?: number;
+    onDiff: (diff: ViewDiff<T>, version: number, cursor?: string) => void;
+    /**
+     * Resume from a point the client already applied. When the change log still
+     * covers `(since, now]` for a single-table collection, the engine replies
+     * with a catch-up diff instead of a full snapshot; otherwise it falls back
+     * to a snapshot.
+     *
+     * Accepts `number` (legacy pre-1.17 — interpreted as the version of THIS
+     * engine instance) or a `string` cursor (1.17.0+ — opaque vector of
+     * `(instanceId, version)` per origin, returned by the engine on every
+     * subscription/diff and round-tripped by the client unmodified). Use the
+     * cursor form for cross-instance resume.
+     */
+    since?: number | string;
     /**
      * Cancellation handle (1.15.0). Two effects:
      *  1. If the signal is already aborted when `subscribe` is called, the
@@ -79,8 +90,18 @@ export type Subscription<T> = {
     initial: T[];
     /** Catch-up diff when resuming via `since` (instead of `initial`). */
     catchup?: ViewDiff<T>;
-    /** The engine version this reply brings the client up to. */
+    /** The engine's local version this reply brings the client up to. */
     version: number;
+    /**
+     * Opaque cross-instance resume cursor (1.17.0+). Encodes the per-origin
+     * vector of `(instanceId, version)` the client is now up-to-date with;
+     * pass it back as `SubscribeArgs.since` on reconnect. Works for resume
+     * against ANY instance in a cluster, not just the one that issued it —
+     * the receiving instance decodes the cursor, walks its log for entries
+     * the client hasn't seen yet, and either replies with a catch-up diff
+     * or a fresh snapshot.
+     */
+    cursor: string;
     /** Stop receiving diffs and release the view. */
     unsubscribe: () => void;
 };
@@ -295,6 +316,7 @@ export type SyncEngine = {
  * all sharing the same `version`.
  */
 export type LoggedChange = {
+    /** This engine's local monotonic version when the change was logged. */
     version: number;
     table: string;
     change: RowChange<unknown>;
@@ -305,6 +327,24 @@ export type LoggedChange = {
      * Added in 1.13.0; pre-1.13.0 consumers of `LoggedChange` ignore it.
      */
     at: number;
+    /**
+     * Instance id that originated this change. For locally-committed changes
+     * this is the engine's own `instanceId`; for cluster-received changes,
+     * the originating peer's id.
+     *
+     * Added in 1.17.0; pre-1.17 consumers ignore it.
+     */
+    origin: string;
+    /**
+     * The ORIGINATOR's local version at commit time. For locally-committed
+     * changes this equals `version`; for cluster-received changes, the
+     * peer's version. Resume cursors (1.17.0+) carry `(origin, originVersion)`
+     * pairs so a client's last-seen point matches against peer entries this
+     * engine has logged via the bus.
+     *
+     * Added in 1.17.0; pre-1.17 consumers ignore it.
+     */
+    originVersion: number;
 };
 /** Thrown by {@link SyncEngine.streamChanges} when `since` is older than the
  * oldest entry retained in the bounded change log (i.e. the consumer was
@@ -345,6 +385,16 @@ export declare class CdcConsumerSlowError extends Error {
     constructor(maxBuffer: number, lastDeliveredVersion: number);
 }
 export type SyncEngineOptions = {
+    /**
+     * Stable identifier for this engine instance. Defaults to a per-process
+     * random UUID. Pass a stable value (e.g. `${hostname}:${shardId}`) when
+     * running a fleet of engines behind a cluster bus — 1.17.0+ resume
+     * cursors carry the originating `instanceId`, so a client that reconnects
+     * to a different shard can request a catch-up against the original's
+     * change feed only if that instance's id matches a peer the new shard
+     * knows about.
+     */
+    instanceId?: string;
     /**
      * How many recent changes to retain for resumable reconnects. A client that
      * reconnects within this window gets a catch-up diff; beyond it, a fresh

package/dist/index.js

@@ -230,12 +230,13 @@ var parseFrame = (raw, serializer) => {
   }
   const frame = value;
   if (frame.type === "subscribe") {
+    const since = typeof frame.since === "number" || typeof frame.since === "string" ? frame.since : undefined;
     return typeof frame.id === "string" && typeof frame.collection === "string" ? {
       type: "subscribe",
       id: frame.id,
       collection: frame.collection,
       params: frame.params,
-      since: typeof frame.since === "number" ? frame.since : undefined
+      since
     } : undefined;
   }
   if (frame.type === "unsubscribe") {
@@ -287,6 +288,7 @@ var createSyncConnection = ({
   };
   let pending = [];
   let pendingVersion;
+  let pendingCursor;
   let flushScheduled = false;
   const flush = () => {
     if (pending.length === 0) {
@@ -294,8 +296,10 @@ var createSyncConnection = ({
     }
     const diffs = pending;
     const version = pendingVersion;
+    const cursor = pendingCursor;
     pending = [];
     pendingVersion = undefined;
+    pendingCursor = undefined;
     if (diffs.length === 1) {
       const only = diffs[0];
       send({
@@ -304,10 +308,11 @@ var createSyncConnection = ({
         added: only.added,
         removed: only.removed,
         changed: only.changed,
-        version
+        version,
+        cursor
       });
     } else {
-      send({ type: "frame", diffs, version });
+      send({ type: "frame", diffs, version, cursor });
     }
   };
   const scheduleFlush = () => {
@@ -320,12 +325,14 @@ var createSyncConnection = ({
       flush();
     });
   };
-  const bufferDiff = (diff, diffVersion) => {
+  const bufferDiff = (diff, diffVersion, cursor) => {
     if (pending.length > 0 && pendingVersion !== diffVersion) {
       flush();
     }
     pending.push(diff);
     pendingVersion = diffVersion;
+    if (cursor !== undefined)
+      pendingCursor = cursor;
     scheduleFlush();
   };
   const handle = async (raw) => {
@@ -401,13 +408,13 @@ var createSyncConnection = ({
         params: frame.params,
         ctx,
         since: frame.since,
-        onDiff: (diff, diffVersion) => {
+        onDiff: (diff, diffVersion, cursor) => {
           bufferDiff({
             id: frame.id,
             added: diff.added,
             removed: diff.removed,
             changed: diff.changed
-          }, diffVersion);
+          }, diffVersion, cursor);
         }
       });
       subscriptions.set(frame.id, subscription);
@@ -418,14 +425,16 @@ var createSyncConnection = ({
           added: subscription.catchup.added,
           removed: subscription.catchup.removed,
           changed: subscription.catchup.changed,
-          version: subscription.version
+          version: subscription.version,
+          cursor: subscription.cursor
         });
       } else {
         send({
           type: "snapshot",
           id: frame.id,
           rows: subscription.initial,
-          version: subscription.version
+          version: subscription.version,
+          cursor: subscription.cursor
         });
       }
     } catch (error) {
@@ -1298,11 +1307,11 @@ var createSyncEngine = (options = {}) => {
   };
   const streamSubscribers = new Set;
   const runInTransaction = options.transaction;
-  const instanceId = globalThis.crypto?.randomUUID?.() ?? `i${Math.random()}`;
+  const instanceId = options.instanceId ?? globalThis.crypto?.randomUUID?.() ?? `i${Math.random()}`;
   let clusterBus;
-  const broadcast = (changes) => {
+  const broadcast = (changes, originVersion) => {
     if (clusterBus !== undefined && changes.length > 0) {
-      clusterBus.publish({ changes, origin: instanceId });
+      clusterBus.publish({ changes, origin: instanceId, originVersion });
     }
   };
   const subsFor = (collection) => {
@@ -1679,11 +1688,44 @@ var createSyncEngine = (options = {}) => {
       subscriber(entry);
     }
   };
+  const encodeCursor = (versions) => JSON.stringify(versions);
+  const decodeCursor = (cursor) => {
+    try {
+      const parsed = JSON.parse(cursor);
+      if (typeof parsed !== "object" || parsed === null)
+        return null;
+      const out = {};
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === "number")
+          out[k] = v;
+      }
+      return out;
+    } catch {
+      return null;
+    }
+  };
+  const currentCursor = () => {
+    const versions = { [instanceId]: version };
+    for (let i = changeLog.length - 1;i >= 0; i--) {
+      const entry = changeLog[i];
+      if (versions[entry.origin] === undefined) {
+        versions[entry.origin] = entry.originVersion;
+      }
+    }
+    return encodeCursor(versions);
+  };
   const applyChange = async (table, change, shouldBroadcast = true) => {
     version += 1;
     const changeVersion = version;
     const at = Date.now();
-    logChange(changeVersion, { version: changeVersion, table, change, at });
+    logChange(changeVersion, {
+      version: changeVersion,
+      table,
+      change,
+      at,
+      origin: instanceId,
+      originVersion: changeVersion
+    });
     emitActivity({
       type: "change",
       at,
@@ -1702,14 +1744,15 @@ var createSyncEngine = (options = {}) => {
       { table, key: changedKeyFor(table, change), row: change.row }
     ]));
     emissions.push(...searchPairs([{ table, change }]));
+    const cursorForBatch = currentCursor();
     for (const [subscription, diff] of emissions) {
-      subscription.onDiff(diff, changeVersion);
+      subscription.onDiff(diff, changeVersion, cursorForBatch);
     }
     if (shouldBroadcast) {
-      broadcast([{ table, change }]);
+      broadcast([{ table, change }], changeVersion);
     }
   };
-  const applyChangeBatch = async (changes, shouldBroadcast = true) => {
+  const applyChangeBatch = async (changes, shouldBroadcast = true, peerOrigin) => {
     if (changes.length === 0) {
       return;
     }
@@ -1718,8 +1761,17 @@ var createSyncEngine = (options = {}) => {
     const perSubscription = new Map;
     const reactiveChanges = [];
     const batchAt = Date.now();
+    const batchOrigin = peerOrigin?.origin ?? instanceId;
+    const batchOriginVersion = peerOrigin?.originVersion ?? batchVersion;
     for (const { table, change } of changes) {
-      logChange(batchVersion, { version: batchVersion, table, change, at: batchAt });
+      logChange(batchVersion, {
+        version: batchVersion,
+        table,
+        change,
+        at: batchAt,
+        origin: batchOrigin,
+        originVersion: batchOriginVersion
+      });
       emitActivity({
         type: "change",
         at: batchAt,
@@ -1751,29 +1803,70 @@ var createSyncEngine = (options = {}) => {
     }
     emissions.push(...await reactivePairs(reactiveChanges));
     emissions.push(...searchPairs(changes));
+    const cursorForBatch = currentCursor();
     for (const [subscription, diff] of emissions) {
-      subscription.onDiff(diff, batchVersion);
+      subscription.onDiff(diff, batchVersion, cursorForBatch);
     }
     if (shouldBroadcast) {
-      broadcast(changes);
+      broadcast(changes, batchVersion);
+    }
+  };
+  const normalizeSince = (since) => {
+    if (typeof since === "number") {
+      return { [instanceId]: since };
     }
+    return decodeCursor(since);
   };
   const canResume = (since, incremental) => {
     if (!incremental) {
       return false;
     }
-    if (since >= version) {
-      return true;
+    const sinceVec = normalizeSince(since);
+    if (sinceVec === null) {
+      return false;
+    }
+    const oldestPerOrigin = new Map;
+    for (const entry of changeLog) {
+      const current = oldestPerOrigin.get(entry.origin);
+      if (current === undefined || entry.originVersion < current) {
+        oldestPerOrigin.set(entry.origin, entry.originVersion);
+      }
+    }
+    const oldestLogVersion = changeLog[0]?.version;
+    for (const [origin, lastSeen] of Object.entries(sinceVec)) {
+      if (origin === instanceId) {
+        if (lastSeen >= version)
+          continue;
+        const oldestLocal = oldestPerOrigin.get(instanceId);
+        if (oldestLocal !== undefined) {
+          if (oldestLocal > lastSeen + 1)
+            return false;
+          continue;
+        }
+        if (oldestLogVersion !== undefined && oldestLogVersion > lastSeen + 1) {
+          return false;
+        }
+      } else {
+        const oldestPeer = oldestPerOrigin.get(origin);
+        if (oldestPeer === undefined) {
+          if (lastSeen > 0)
+            return false;
+        } else if (oldestPeer > lastSeen + 1) {
+          return false;
+        }
+      }
     }
-    const oldest = changeLog[0];
-    return oldest !== undefined && oldest.version <= since + 1;
+    return true;
   };
   const buildCatchup = (since, tables, key, match) => {
+    const sinceVec = normalizeSince(since) ?? {};
     const latest = new Map;
     for (const entry of changeLog) {
-      if (entry.version <= since || !tables.includes(entry.table)) {
+      if (!tables.includes(entry.table))
+        continue;
+      const lastSeen = sinceVec[entry.origin];
+      if (lastSeen !== undefined && entry.originVersion <= lastSeen)
         continue;
-      }
       const row = entry.change.row;
       const present = entry.change.op !== "delete" && match(row) ? "upsert" : "remove";
       latest.set(key(row), { op: present, row });
@@ -1818,6 +1911,7 @@ var createSyncEngine = (options = {}) => {
     set.add(subscription);
     return {
       initial: op.rows(),
+      cursor: currentCursor(),
       version: atVersion,
       unsubscribe: () => {
         set.delete(subscription);
@@ -1844,6 +1938,7 @@ var createSyncEngine = (options = {}) => {
     set.add(subscription);
     return {
       initial,
+      cursor: currentCursor(),
       version: atVersion,
       unsubscribe: () => {
         set.delete(subscription);
@@ -1905,6 +2000,7 @@ var createSyncEngine = (options = {}) => {
     reactiveSubs.add(subscription);
     return {
       initial: first.rows,
+      cursor: currentCursor(),
       version: atVersion,
       unsubscribe: () => {
         set.delete(subscription);
@@ -1949,6 +2045,7 @@ var createSyncEngine = (options = {}) => {
     searchSubs.add(subscription);
     return {
       initial,
+      cursor: currentCursor(),
       version: atVersion,
       unsubscribe: () => {
         set.delete(subscription);
@@ -2050,12 +2147,14 @@ var createSyncEngine = (options = {}) => {
         return wrapReturn({
           initial: [],
           catchup: buildCatchup(since, tables, key, boundMatch),
+          cursor: currentCursor(),
           version: atVersion,
           unsubscribe
         });
       }
       return wrapReturn({
         initial: view.rows(),
+        cursor: currentCursor(),
         version: atVersion,
         unsubscribe
       });
@@ -2094,7 +2193,10 @@ var createSyncEngine = (options = {}) => {
         if (message.origin === instanceId) {
           return;
         }
-        applyChangeBatch(message.changes, false);
+        applyChangeBatch(message.changes, false, {
+          origin: message.origin,
+          originVersion: message.originVersion ?? 0
+        });
       });
       clusterBus = bus;
       return async () => {
@@ -2891,5 +2993,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=B96A4C67BAC0D9FB64756E2164756E21
+//# debugId=34EB2D2EE376D7EC64756E2164756E21
 //# sourceMappingURL=index.js.map