@pylonsync/sync 0.3.177 → 0.3.179

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.177",
+  "version": "0.3.179",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -714,6 +714,18 @@ export class SyncEngine {
    * the client can't hammer the server on auth failures.
    */
   private wsStableTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+
+  /**
+   * Serialized apply queue. Every change-event apply — from WS onmessage,
+   * pull(), or session-changed catchup — chains onto this promise so
+   * applies execute in arrival order. Without this, two WS messages or
+   * two concurrent pull()s race: seq 3's persistence can land before
+   * seq 2's, leaving the row at the older value AND the cursor briefly
+   * regressing if writes complete out of order. The queue also gates
+   * the cursor advance so `last_seq` only moves forward.
+   */
+  private applyQueue: Promise<void> = Promise.resolve();
 
   /**
    * Registered consumers for binary WebSocket frames. SyncEngine itself
@@ -964,6 +976,53 @@ export class SyncEngine {
 
   private pollTimer: ReturnType<typeof setInterval> | null = null;
 
+  /**
+   * Serialize a batch of change applies behind any in-flight applies, and
+   * advance the cursor monotonically when the batch lands. Both the WS
+   * onmessage path and pull() funnel through here so seq 3's persistence
+   * can't race ahead of seq 2's. The returned promise resolves after
+   * THIS batch is applied (not after later batches), so a caller awaiting
+   * pull() still completes deterministically.
+   *
+   * Per-event monotonic filter: re-applies of an already-seen seq are
+   * skipped before touching the store. Without that, a retransmit
+   * (WS + pull window overlap) would have us run applyChange twice
+   * against the local store.
+   */
+  private enqueueApply(
+    changes: ChangeEvent[],
+    targetCursor?: SyncCursor,
+  ): Promise<void> {
+    const prev = this.applyQueue;
+    const next = prev.then(async () => {
+      const filtered = changes.filter(
+        (c) => typeof c.seq === "number" && c.seq > this.cursor.last_seq,
+      );
+      if (filtered.length > 0) {
+        await this.store.applyChangesAsync(filtered);
+      }
+      // Pick the cursor target. Explicit `targetCursor` (from pull) wins
+      // — pull's response carries the server's authoritative current_seq
+      // even when no changes landed in this window. Otherwise derive
+      // from the last applied seq.
+      const candidate =
+        targetCursor ??
+        (filtered.length > 0
+          ? { last_seq: filtered[filtered.length - 1].seq }
+          : null);
+      if (candidate && candidate.last_seq > this.cursor.last_seq) {
+        this.cursor = candidate;
+        if (this.persistence) {
+          await this.persistence.saveCursor(this.cursor);
+        }
+      }
+    });
+    // Errors stay scoped to this batch — don't poison the chain for
+    // future applies.
+    this.applyQueue = next.catch(() => {});
+    return next;
+  }
+
   private startPolling(): void {
     const interval = this.config.pollInterval ?? 1000;
     this.pollTimer = setInterval(() => {
@@ -986,6 +1045,10 @@ export class SyncEngine {
       clearInterval(this.pollTimer);
       this.pollTimer = null;
     }
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
     if (this.visibilityHandler && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.visibilityHandler);
       this.visibilityHandler = null;
@@ -1033,6 +1096,27 @@ export class SyncEngine {
         this.reconnectAttempts = 0;
         this.wsStableTimer = null;
       }, 5_000);
+      // Client-side keepalive ping. The server's per-client reader
+      // thread blocks on a synchronous WS read for as long as no client
+      // message arrives. On the HTTP-multiplexed `/api/sync/ws` path
+      // tiny_http doesn't expose stream-level read timeouts, so the
+      // reader's mutex hold is bounded only by client activity. Without
+      // these pings the broadcaster contends for the same mutex and
+      // wedges — Insert events never reach the tab. A 1s cadence makes
+      // worst-case broadcast latency ~1s even when the user is idle.
+      // Browsers don't expose WebSocket-level PING frames; a JSON
+      // payload with type:"ping" achieves the same effect (the server
+      // reads, looks up an unknown "ping" type, loops back releasing
+      // the mutex; broadcaster grabs it during the gap).
+      if (this.pingTimer) clearInterval(this.pingTimer);
+      this.pingTimer = setInterval(() => {
+        if (this.ws?.readyState !== WebSocket.OPEN) return;
+        try {
+          this.ws.send('{"type":"ping"}');
+        } catch {
+          // ignore — onclose will trigger reconnect
+        }
+      }, 1_000);
       // Re-send any active CRDT subscriptions across the new socket.
       // The server purged them on disconnect (`unsubscribe_all`), so
       // without this resync a tab that was subscribed before a network
@@ -1092,18 +1176,14 @@ export class SyncEngine {
       try {
         const msg = JSON.parse(event.data as string);
 
-        // Sync change event. Persist BEFORE advancing the cursor so a crash
-        // can't leave `last_seq` ahead of the replica on disk.
+        // Sync change event. Persist BEFORE advancing the cursor so a
+        // crash can't leave `last_seq` ahead of the replica on disk.
+        // The shared apply queue serializes WS messages with each other
+        // AND with concurrent pull() calls, so seq order is preserved
+        // and the cursor only advances monotonically.
         if (msg.seq && msg.entity && msg.kind) {
           const change = msg as ChangeEvent;
-          if (change.seq > this.cursor.last_seq) {
-            void this.store.applyChangesAsync([change]).then(async () => {
-              this.cursor = { last_seq: change.seq };
-              if (this.persistence) {
-                await this.persistence.saveCursor(this.cursor);
-              }
-            });
-          }
+          void this.enqueueApply([change]);
           return;
         }
 
@@ -1162,6 +1242,10 @@ export class SyncEngine {
         clearTimeout(this.wsStableTimer);
         this.wsStableTimer = null;
       }
+      if (this.pingTimer) {
+        clearInterval(this.pingTimer);
+        this.pingTimer = null;
+      }
       // Surface the disconnect to UI consumers immediately. If
       // `running` flipped to false (engine stopped), `stop()` already
       // set "offline" — don't override that.
@@ -1229,14 +1313,7 @@ export class SyncEngine {
           const msg = JSON.parse(event.data);
           if (msg.seq && msg.entity && msg.kind) {
             const change = msg as ChangeEvent;
-            if (change.seq > this.cursor.last_seq) {
-              void this.store.applyChangesAsync([change]).then(async () => {
-                this.cursor = { last_seq: change.seq };
-                if (this.persistence) {
-                  await this.persistence.saveCursor(this.cursor);
-                }
-              });
-            }
+            void this.enqueueApply([change]);
           }
         } catch {
           // Ignore malformed events.
@@ -1450,22 +1527,14 @@ export class SyncEngine {
       );
       // Successful response — clear the 410 circuit breaker.
       this.consecutive_410s = 0;
-      if (resp.changes.length > 0) {
-        // Await disk writes before touching the cursor so a crash here can't
-        // persist a cursor that's ahead of what actually landed in IndexedDB.
-        await this.store.applyChangesAsync(resp.changes);
-      }
-      // Always advance the cursor to whatever the server reports, not just
-      // when changes land. If a read policy filters out every event in a
-      // window the server still moves its last_seq forward; clamping to only
-      // "non-empty" responses pins the client at `since=0` forever and turns
-      // every reconnect into another pull for the same empty window.
-      if (resp.cursor && resp.cursor.last_seq > this.cursor.last_seq) {
-        this.cursor = resp.cursor;
-        if (this.persistence) {
-          await this.persistence.saveCursor(this.cursor);
-        }
-      }
+      // Route through the apply queue so concurrent WS messages and
+      // pull responses don't race. The queue's monotonic guard skips
+      // any seq we've already applied (e.g. WS already landed the
+      // events that pull is now redelivering) and only advances the
+      // cursor forward. We still advance even when no changes land,
+      // because the server's last_seq may have moved past us due to
+      // policy-filtered events.
+      await this.enqueueApply(resp.changes, resp.cursor);
       // If there are more, pull again immediately.
       if (resp.has_more) {
         await this.pull();