@pylonsync/sync 0.3.302 → 0.3.304

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

@@ -140,6 +140,17 @@ export declare class TestServer {
     private nextPullHasMore;
     primeNextPullHasMore(): void;
     consumeNextPullHasMore(): boolean;
+    /** Every `/api/sync/pull` URL the engine requested, in order. Lets a test
+     *  assert how the engine encodes query params (e.g. that `snapshot_after` is
+     *  not double-URL-encoded — the bug that caused an infinite re-snapshot loop). */
+    pullUrls: string[];
+    /** One-shot: make the next from-0 snapshot pull return this `snapshot_after`
+     *  token (a continuation cursor), so a test can drive the engine's snapshot
+     *  pagination + assert the resume request echoes the token verbatim. The token
+     *  is what the real server returns: already URL-encoded JSON. */
+    private nextSnapshotAfter;
+    primeSnapshotAfter(token: string): void;
+    consumeSnapshotAfter(): string | null;
     /** Bulk-seed rows for an entity AND emit insert events into the
      *  change log so the engine discovers them via /api/sync/pull at
      *  since=0 — same shape production clients see when they boot

package/package.json

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

package/src/index.ts

@@ -1543,14 +1543,21 @@ export class SyncEngine {
       let firstPass = true;
       while (firstPass || snapshotAfter) {
         firstPass = false;
-        const params = new URLSearchParams();
-        params.set("since", String(this.cursor.last_seq));
+        // `snapshot_after` is an OPAQUE cursor the server already URL-encoded
+        // (it `url_encode`s the JSON payload). It MUST be appended raw — running
+        // it back through URLSearchParams would double-encode it, the server's
+        // single `url_decode` would leave it still-encoded, `serde_json::from_str`
+        // would fail, and the server would treat the page as "no resume" and
+        // 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}`;
         if (snapshotAfter) {
-          params.set("snapshot_after", snapshotAfter);
+          query += `&snapshot_after=${snapshotAfter}`;
         }
         const resp = await this.request<
           PullResponse & { snapshot_after?: string | null }
-        >("GET", `/api/sync/pull?${params.toString()}`);
+        >("GET", `/api/sync/pull?${query}`);
         await this.enqueueApply(resp.changes, resp.cursor, { isPull: true });
         // `snapshot_after` is only set when the server is mid-snapshot.
         // Continue paginating in the same loop iteration so we don't

package/src/scenarios.test.ts

@@ -941,4 +941,34 @@ describe("sync scenarios", () => {
     // follower broadcast and nothing re-pushed.
     expect(env.server.receivedPushKeys).toContain("Note/n1");
   });
+
+  // Pins: the snapshot_after continuation cursor must be appended to the pull
+  // URL VERBATIM. The server returns it already URL-encoded; the client used to
+  // run it back through URLSearchParams, double-encoding it. The server's single
+  // url_decode then left it encoded, serde_json::from_str failed, the resume was
+  // ignored, and the snapshot restarted from row 0 on EVERY page — an infinite
+  // re-snapshot loop (and egress storm) for any synced table past one page
+  // (SNAPSHOT_BATCH_LIMIT rows). Reproduced live on the 10k-product store demo.
+  test("snapshot pagination echoes the cursor verbatim (no double-encode loop)", async () => {
+    env = createTestEnv();
+    // The real server's cursor: url_encode(JSON) — full of %-escapes.
+    const cursor = "%7B%22a%22%3A%22r1%22%2C%22e%22%3A%22Recording%22%2C%22s%22%3A1%7D";
+    env.server.primeSnapshotAfter(cursor);
+
+    await env.start();
+
+    const snapshotPulls = env.server.pullUrls.filter((u) => u.includes("since=0"));
+    // Page 1 (no cursor) + page 2 (resume) — BOUNDED. A regressed engine would
+    // loop forever on page 1; the mock terminates the resume so this stays a
+    // fast assertion instead of a hang.
+    expect(snapshotPulls.length).toBeGreaterThanOrEqual(2);
+    expect(snapshotPulls.length).toBeLessThan(6);
+
+    const resume = snapshotPulls.find((u) => u.includes("snapshot_after="));
+    expect(resume).toBeDefined();
+    const sent = resume!.split("snapshot_after=")[1]!.split("&")[0];
+    // VERBATIM. Double-encoding would have produced `%2522`/`%257B`.
+    expect(sent).toBe(cursor);
+    expect(sent).not.toContain("%2522");
+  });
 });

package/src/test-harness/server.ts

@@ -243,6 +243,25 @@ export class TestServer {
     return v;
   }
 
+  /** Every `/api/sync/pull` URL the engine requested, in order. Lets a test
+   *  assert how the engine encodes query params (e.g. that `snapshot_after` is
+   *  not double-URL-encoded — the bug that caused an infinite re-snapshot loop). */
+  pullUrls: string[] = [];
+
+  /** One-shot: make the next from-0 snapshot pull return this `snapshot_after`
+   *  token (a continuation cursor), so a test can drive the engine's snapshot
+   *  pagination + assert the resume request echoes the token verbatim. The token
+   *  is what the real server returns: already URL-encoded JSON. */
+  private nextSnapshotAfter: string | null = null;
+  primeSnapshotAfter(token: string): void {
+    this.nextSnapshotAfter = token;
+  }
+  consumeSnapshotAfter(): string | null {
+    const v = this.nextSnapshotAfter;
+    this.nextSnapshotAfter = null;
+    return v;
+  }
+
   // ---- Entity data --------------------------------------------------------
 
   /** Bulk-seed rows for an entity AND emit insert events into the

package/src/test-harness/transport.ts

@@ -249,6 +249,7 @@ async function handle(
         body: { error: { code: "RESYNC_REQUIRED" } },
       };
     }
+    server.pullUrls.push(url);
     const since = Number(new URL(url, "http://test").searchParams.get("since") ?? "0");
     // Cluster-divergence sim: a delta pull lands on an instance that
     // can't serve our cursor → 410. A snapshot (since=0) still succeeds.
@@ -258,6 +259,24 @@ async function handle(
         body: { error: { code: "RESYNC_REQUIRED" } },
       };
     }
+    // Snapshot pagination sim (since=0). A primed from-0 pull returns an
+    // already-URL-encoded `snapshot_after` continuation (page 1); the resume
+    // request (page 2) carries it back and gets the final page. The regression
+    // guard lives in the TEST, which inspects the captured page-2 URL: the client
+    // must echo the cursor VERBATIM, not re-encode it (double-encoding broke the
+    // server's single url_decode and restarted the snapshot forever).
+    if (since === 0) {
+      const hasResume = url.includes("snapshot_after=");
+      if (!hasResume) {
+        const token = server.consumeSnapshotAfter();
+        if (token) {
+          const resp = await server.pull(token, since);
+          return { status: 200, body: { ...resp, snapshot_after: token } };
+        }
+      }
+      // Resume page (or no pagination primed): fall through to a normal,
+      // terminating snapshot (no snapshot_after → client exits the loop).
+    }
     const resp = await server.pull(token, since);
     // One-shot has_more on a delta pull → drives the tail-pull recursion.
     if (since > 0 && server.consumeNextPullHasMore()) {