@pylonsync/sync 0.3.363 → 0.3.365

package/dist/test-harness/server.d.ts

@@ -73,6 +73,11 @@ export declare class TestServer {
     /** Count of snapshot pulls served (since = 0). The egress storm was a
      *  runaway count here; the regression test bounds it. */
     snapshotPullCount: number;
+    /** When set, delta pulls (since > 0) page their response to this many
+     *  events per request with a real per-page cursor + has_more — models
+     *  the production DELTA_BATCH_LIMIT so catch-up pagination and
+     *  fetch/apply pipelining can be exercised. */
+    deltaPageSize: number | null;
     /** Count of /api/sync/push requests received. Lets a test assert the
      *  engine actually shipped a batch (e.g. hydrated offline writes that
      *  must drain once leader-elected), independent of the no-op push

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.363",
+  "version": "0.3.365",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -1714,16 +1714,40 @@ export class SyncEngine {
     // has_more, 410 recursion) run at a non-zero cursor → they don't touch
     // this, and their applies pass `isPull` so they're never held.
     if (startedFromZero) this.snapshotHold = [];
+    // Declared outside the try: on a mid-loop fetch error the previous
+    // page's apply may still be in flight, and the catch (410 reset →
+    // re-pull) MUST let it settle first — otherwise the orphaned apply
+    // races the replica wipe and re-writes stale rows into the fresh
+    // store (and drags the cursor forward under the recursive pull).
+    let pendingApply: Promise<void> | null = null;
     try {
       // Snapshot pagination: when the cursor is 0 and the server's
       // table is larger than a single batch, the response carries
-      // `snapshot_after` for the next page. Loop until exhausted
-      // BEFORE returning so a fresh client always observes a
-      // consistent full snapshot, not a 1k-row prefix it mistakes
-      // for the whole replica.
+      // `snapshot_after` for the next page. The change-log tail
+      // paginates via `has_more`. Both loop until exhausted BEFORE
+      // returning so a fresh client always observes a consistent full
+      // snapshot (not a 1k-row prefix it mistakes for the whole
+      // replica) and a catching-up client drains the whole tail.
+      //
+      // Fetch/apply pipelining: applying a page (IndexedDB writes) and
+      // fetching the next one are independent, so page N's apply runs
+      // WHILE page N+1 is in flight — catch-up latency is
+      // max(network, apply) per page instead of their sum. Ordering is
+      // safe because enqueueApply chains every batch onto the same
+      // applyQueue in call order; page N+1 is only ENQUEUED after page
+      // N's apply resolved, so a failed apply aborts the loop instead
+      // of letting later pages advance the cursor over a hole.
+      //
+      // The next `since` comes from each RESPONSE's cursor, not
+      // `this.cursor` — the apply is what advances `this.cursor`, and
+      // waiting on it is exactly what pipelining removes. Mid-snapshot
+      // the server pins the response cursor at 0, which keeps routing
+      // to the snapshot path.
       let snapshotAfter: string | undefined;
+      let hasMore = false;
       let firstPass = true;
-      while (firstPass || snapshotAfter) {
+      let nextSince = this.cursor.last_seq;
+      while (firstPass || snapshotAfter || hasMore) {
         firstPass = false;
         // `snapshot_after` is an OPAQUE cursor the server already URL-encoded
         // (it `url_encode`s the JSON payload). It MUST be appended raw — running
@@ -1733,33 +1757,28 @@ export class SyncEngine {
         // restart the snapshot from row 0 — an infinite re-snapshot loop for any
         // table larger than one page (SNAPSHOT_BATCH_LIMIT rows). `since` is a
         // plain integer, so it's safe to inline.
-        let query = `since=${this.cursor.last_seq}`;
+        let query = `since=${nextSince}`;
         if (snapshotAfter) {
           query += `&snapshot_after=${snapshotAfter}`;
         }
         const resp = await this.request<
           PullResponse & { snapshot_after?: string | null }
         >("GET", `/api/sync/pull?${query}`);
-        await this.enqueueApply(resp.changes, resp.cursor, { isPull: true });
+        if (pendingApply) await pendingApply;
+        pendingApply = this.enqueueApply(resp.changes, resp.cursor, {
+          isPull: true,
+        });
+        // Guard against a server that reports more pages without
+        // advancing the cursor (a transient no-progress page): break
+        // rather than refetch the same page forever. The next poll /
+        // change event re-drives the pull.
+        const advanced = resp.cursor.last_seq > nextSince;
+        nextSince = resp.cursor.last_seq;
         // `snapshot_after` is only set when the server is mid-snapshot.
-        // Continue paginating in the same loop iteration so we don't
-        // leave a fresh client with a partial replica.
         snapshotAfter = resp.snapshot_after ?? undefined;
-        // The change-log tail also paginates via `has_more` — drain it
-        // by recursing into `pullInner` directly. We are INSIDE the
-        // `pull` op-queue slot right now; calling the public `pull()`
-        // would re-enqueue under the same "pull" key, which coalesces
-        // to the promise we're currently running inside (op-queue.ts
-        // deletes the key only after `fn` resolves) and `await` it →
-        // permanent self-deadlock that bricks the entire pull path for
-        // the session. This is the exact hazard the 410 handler avoids;
-        // `pullInner` re-reads `this.cursor.last_seq` (already advanced
-        // by enqueueApply) so the recursion resumes at the right cursor.
-        if (!snapshotAfter && resp.has_more) {
-          await this.pullInner();
-          break;
-        }
+        hasMore = !snapshotAfter && resp.has_more && advanced;
       }
+      if (pendingApply) await pendingApply;
       // Clear the resync circuit breaker ONLY on a successful DELTA
       // pull — one that started from a real, non-zero cursor the server
       // honored. A snapshot pull from cursor=0 succeeding does NOT prove
@@ -1795,6 +1814,12 @@ export class SyncEngine {
         if (held.length > 0) await this.enqueueApply(held);
       }
     } catch (err) {
+      // Settle any in-flight page apply before acting on the error —
+      // the 410 path below wipes the replica, and an apply landing
+      // after the wipe would resurrect stale rows and advance the
+      // cursor under the recursive re-pull. Failures are already
+      // handled batch-locally; only settlement matters here.
+      if (pendingApply) await pendingApply.catch(() => {});
       // Swallow network + transient errors so the poll/reconnect loop
       // keeps trying — but on 429 bump the backoff counter so the next
       // reconnect waits noticeably longer. Without this, a rate-limited

package/src/scenarios.test.ts

@@ -555,6 +555,74 @@ describe("sync scenarios", () => {
     expect(env.engine.store.get("Note", "n2")).not.toBeNull();
   });
 
+  // CATCH-UP PIPELINING (pins the pullInner fetch/apply overlap). A
+  // multi-page delta catch-up used to serialize fetch page N → apply
+  // page N → fetch page N+1, paying network + apply per page in SUM.
+  // The pipelined loop derives the next `since` from each RESPONSE's
+  // cursor and starts the next fetch while the previous page is still
+  // applying, so per-page cost is max(network, apply). This test slows
+  // applies down and asserts (a) a later page's fetch arrives at the
+  // server WHILE an apply is still in flight, and (b) every page still
+  // lands, in order, with nothing skipped.
+  test("multi-page delta catch-up overlaps fetch with apply and drains completely", async () => {
+    let deltaFetches = 0;
+    let applyEnds = 0;
+    let overlapped = false;
+    env = createTestEnv({
+      transport: "poll",
+      beforePull: (_auth, since) => {
+        if (since > 0) {
+          deltaFetches++;
+          // The serialized loop finishes apply k-1 BEFORE issuing
+          // fetch k, so it always arrives with applyEnds == k-1. A
+          // fetch arriving with fewer applies completed is the
+          // pipeline overlap.
+          if (deltaFetches >= 2 && applyEnds < deltaFetches - 1) {
+            overlapped = true;
+          }
+        }
+      },
+    });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Note", [{ id: "n0", title: "seed" }]);
+    await env.start();
+    await env.flush();
+
+    // 30 changes behind, served 10 per page → a 3-page catch-up.
+    for (let i = 1; i <= 30; i++) {
+      env.server.insert("Note", { id: `n${i}`, title: `t${i}` });
+    }
+    env.server.deltaPageSize = 10;
+
+    // Make applies observably slow so the overlap window is real.
+    const store = env.engine.store as unknown as {
+      applyChangesAsync: (c: unknown[]) => Promise<boolean>;
+    };
+    const realApply = store.applyChangesAsync.bind(store);
+    store.applyChangesAsync = async (changes) => {
+      await new Promise((r) => setTimeout(r, 25));
+      const out = await realApply(changes);
+      applyEnds++;
+      return out;
+    };
+
+    await env.engine.pull();
+    await env.flush();
+
+    // Every page landed — first, middle, and last row all present.
+    expect(env.engine.store.get("Note", "n1")).not.toBeNull();
+    expect(env.engine.store.get("Note", "n15")).not.toBeNull();
+    expect(env.engine.store.get("Note", "n30")).not.toBeNull();
+    // It really paginated (≥3 delta pages), and at least one later
+    // fetch overlapped an in-flight apply. A serialized loop never
+    // trips `overlapped` because each fetch waits for the apply.
+    const deltaPulls = env.server.pullUrls.filter(
+      (u) => !u.includes("since=0"),
+    ).length;
+    expect(deltaPulls).toBeGreaterThanOrEqual(3);
+    expect(overlapped).toBe(true);
+  });
+
   // OFFLINE WRITES (pins the transient/permanent split in pushInner).
   // A push that fails with a NETWORK error (offline — fetch rejects, no
   // HTTP status) must keep the mutation `pending` and the optimistic

package/src/test-harness/server.ts

@@ -102,6 +102,11 @@ export class TestServer {
   /** Count of snapshot pulls served (since = 0). The egress storm was a
    *  runaway count here; the regression test bounds it. */
   snapshotPullCount = 0;
+  /** When set, delta pulls (since > 0) page their response to this many
+   *  events per request with a real per-page cursor + has_more — models
+   *  the production DELTA_BATCH_LIMIT so catch-up pagination and
+   *  fetch/apply pipelining can be exercised. */
+  deltaPageSize: number | null = null;
   /** Count of /api/sync/push requests received. Lets a test assert the
    *  engine actually shipped a batch (e.g. hydrated offline writes that
    *  must drain once leader-elected), independent of the no-op push

package/src/test-harness/transport.ts

@@ -278,6 +278,23 @@ async function handle(
       // terminating snapshot (no snapshot_after → client exits the loop).
     }
     const resp = await server.pull(token, since);
+    // Delta paging sim: slice to `deltaPageSize` events with a real
+    // per-page cursor + has_more, like the production DELTA_BATCH_LIMIT.
+    if (
+      since > 0 &&
+      server.deltaPageSize != null &&
+      resp.changes.length > server.deltaPageSize
+    ) {
+      const page = resp.changes.slice(0, server.deltaPageSize);
+      return {
+        status: 200,
+        body: {
+          changes: page,
+          cursor: { last_seq: page[page.length - 1]!.seq },
+          has_more: true,
+        },
+      };
+    }
     // One-shot has_more on a delta pull → drives the tail-pull recursion.
     if (since > 0 && server.consumeNextPullHasMore()) {
       return { status: 200, body: { ...resp, has_more: true } };