@pylonsync/sync 0.22.50 → 0.22.58

package/src/session-dedupe.test.ts

@@ -0,0 +1,77 @@
+// `refreshSessionIfStale` (what useSession calls on mount) asks
+// /api/auth/me at most once per session resolve: a screen that mounts many
+// session readers at once must not send one request each.
+
+import { afterEach, expect, test } from "bun:test";
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+let env: TestEnv | null = null;
+let restoreFetch: (() => void) | null = null;
+
+afterEach(async () => {
+  restoreFetch?.();
+  restoreFetch = null;
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+/** Count /api/auth/me requests made through the harness's fetch. */
+function countAuthMe(): () => number {
+  let n = 0;
+  const inner = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (url.endsWith("/api/auth/me")) n++;
+    return inner(input, init);
+  }) as typeof fetch;
+  restoreFetch = () => {
+    globalThis.fetch = inner;
+  };
+  return () => n;
+}
+
+test("readers that mount during start join its request", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.signIn({ userId: "u1" });
+  const count = countAuthMe();
+  const started = env.engine.start();
+  const mounts = Array.from({ length: 8 }, () => env!.engine.refreshSessionIfStale());
+  await Promise.all([started, ...mounts]);
+  expect(env.engine.resolvedSession().userId).toBe("u1");
+  expect(count()).toBe(1);
+});
+
+test("readers that mount after the session resolved send nothing", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.signIn({ userId: "u1" });
+  await env.engine.start();
+  const count = countAuthMe();
+  await Promise.all(Array.from({ length: 8 }, () => env!.engine.refreshSessionIfStale()));
+  expect(count()).toBe(0);
+});
+
+test("a new token is resolved once, however many readers mount", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.signIn({ userId: "u1" });
+  await env.engine.start();
+  const count = countAuthMe();
+  env.signIn({ userId: "u2" });
+  await Promise.all(Array.from({ length: 8 }, () => env!.engine.refreshSessionIfStale()));
+  expect(env.engine.resolvedSession().userId).toBe("u2");
+  expect(count()).toBe(1);
+  // Resolved for the new token: no more requests.
+  await env.engine.refreshSessionIfStale();
+  expect(count()).toBe(1);
+});
+
+test("notifySessionChanged still always asks the server", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.signIn({ userId: "u1" });
+  await env.engine.start();
+  const count = countAuthMe();
+  await env.engine.notifySessionChanged();
+  await env.engine.notifySessionChanged();
+  expect(count()).toBe(2);
+});

package/src/snapshot-catch-up.test.ts

@@ -0,0 +1,101 @@
+// Pull pages and far-behind catch-up.
+//
+//   - Pages grow: 1000 rows, then double per full page up to 10,000, so a
+//     large first sync costs a few round trips instead of hundreds.
+//   - A far-behind cursor is answered with a snapshot of current rows
+//     (`snapshot_ok=1`). The replica is not wiped: rows stay on screen, the
+//     snapshot's rows apply in place, rows it no longer holds are deleted
+//     (writes not yet on the server are kept), and the log resumes from the
+//     snapshot's seq.
+
+import { afterEach, expect, test } from "bun:test";
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+const limits = (urls: string[]) =>
+  urls.map((u) => Number(new URL(u, "http://test").searchParams.get("limit")));
+
+test("a first sync of 25,000 rows takes 5 pages, growing from 1000", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.server.snapshotMode = true;
+  env.signIn({ userId: "u1" });
+  env.server.seed(
+    "Property",
+    Array.from({ length: 25_000 }, (_, i) => ({ id: `p${String(i).padStart(5, "0")}`, n: i })),
+  );
+  await env.engine.start();
+  await env.engine.pull();
+  expect(env.engine.store.list("Property").length).toBe(25_000);
+  const pulls = env.server.pullUrls.filter((u) => u.includes("since=0") || u.includes("snapshot_after"));
+  expect(limits(pulls).slice(0, 5)).toEqual([1000, 2000, 4000, 8000, 10000]);
+  expect(pulls.length).toBe(5);
+});
+
+test("a far-behind client applies a snapshot in place and resumes the log", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.server.snapshotMode = true;
+  env.signIn({ userId: "u1" });
+  env.server.seed("Lead", [
+    { id: "a", name: "A" },
+    { id: "b", name: "B" },
+    { id: "c", name: "C" },
+  ]);
+  await env.engine.start();
+  await env.engine.pull();
+  expect(env.engine.store.list("Lead").map((r) => r.id).sort()).toEqual(["a", "b", "c"]);
+
+  // While the client is away: b is deleted, c renamed, d added.
+  env.server.delete("Lead", "b");
+  env.server.update("Lead", "c", { name: "C2" });
+  env.server.insert("Lead", { id: "d", name: "D" });
+  env.server.farBehind = () => true;
+
+  // Watch for the replica going empty mid-catch-up (a wipe).
+  let emptied = false;
+  const unsubscribe = env.engine.store.subscribe(() => {
+    if (env!.engine.store.list("Lead").length === 0) emptied = true;
+  });
+  const before = env.server.pullUrls.length;
+  await env.engine.pull();
+  unsubscribe();
+
+  const rows = env.engine.store.list("Lead");
+  expect(rows.map((r) => r.id).sort()).toEqual(["a", "c", "d"]);
+  expect(rows.find((r) => r.id === "c")?.name).toBe("C2");
+  expect(emptied).toBe(false);
+  const catchUp = env.server.pullUrls.slice(before);
+  expect(catchUp[0]).toContain("snapshot_ok=1");
+
+  // The log resumes from the snapshot's seq: the next pull is a delta.
+  env.server.farBehind = () => false;
+  env.server.insert("Lead", { id: "e", name: "E" });
+  await env.engine.pull();
+  expect(env.engine.store.list("Lead").map((r) => r.id).sort()).toEqual(["a", "c", "d", "e"]);
+  const last = env.server.pullUrls[env.server.pullUrls.length - 1]!;
+  expect(last).not.toContain("since=0");
+});
+
+test("the sweep keeps rows with writes the server has not seen", async () => {
+  env = await createTestEnv({ transport: "poll" });
+  env.server.snapshotMode = true;
+  env.signIn({ userId: "u1" });
+  env.server.seed("Lead", [{ id: "a", name: "A" }]);
+  await env.engine.start();
+  await env.engine.pull();
+
+  // Offline write: queued, not on the server.
+  env.server.primeNextPushOutcome({ kind: "network" });
+  const localId = await env.engine.insert("Lead", { name: "made offline" });
+  env.server.farBehind = () => true;
+  await env.engine.pull();
+  const ids = env.engine.store.list("Lead").map((r) => r.id);
+  expect(ids).toContain("a");
+  expect(ids).toContain(localId);
+});

package/src/test-harness/env.ts

@@ -71,6 +71,8 @@ export interface CreateTestEnvOptions {
    *  wall-clock waiting on every reconnect scenario; pass a small
    *  value when the test specifically exercises the reconnect path. */
   reconnectDelay?: number;
+  /** Passed through to the engine config (SyncEngineConfig). */
+  autoReconcileIntervalMs?: number;
 }
 
 export interface TestEnv {
@@ -127,6 +129,7 @@ export function createTestEnv(opts: CreateTestEnvOptions = {}): TestEnv {
     transport: opts.transport ?? "websocket",
     reconnectDelay: opts.reconnectDelay,
     resetOnTenantFlip: opts.resetOnTenantFlip,
+    autoReconcileIntervalMs: opts.autoReconcileIntervalMs,
     // Tight timings so scenarios don't have to sleep seconds. The
     // engine's reconcile debounce is also relaxed so back-to-back
     // visibility-change triggers don't get coalesced away in tests.

package/src/test-harness/server.ts

@@ -452,6 +452,60 @@ export class TestServer {
     return this.visible(entity, all, auth).map((r) => this.project(entity, r));
   }
 
+  /** When true, /api/sync/pull answers like the real server's snapshot
+   *  path: a pull from 0 (or a delta pull with `snapshot_ok=1` and a cursor
+   *  `farBehind` accepts) gets the current visible rows as insert events,
+   *  paged by `limit`, flagged `snapshot`, with `snapshot_entities` on the
+   *  last page. Off by default: older tests expect the log replay. */
+  snapshotMode = false;
+  /** In `snapshotMode`: delta cursors answered with a snapshot. */
+  farBehind: (since: number) => boolean = () => false;
+  /** In `snapshotMode`: leave `snapshot_entities` off the last page, like a
+   *  server from before it was added. */
+  omitSnapshotEntities = false;
+
+  /** One snapshot page for `snapshotMode`. `offset` is the continuation. */
+  snapshotPage(
+    token: string | undefined,
+    offset: number,
+    limit: number,
+  ): {
+    changes: ChangeEvent[];
+    cursor: SyncCursor;
+    has_more: boolean;
+    snapshot: true;
+    snapshot_after: string | null;
+    snapshot_entities?: string[];
+  } {
+    if (offset === 0) this.snapshotPullCount += 1;
+    const auth = this.authContextFor(token);
+    const entities = [...this.rows.keys()].sort();
+    const all: ChangeEvent[] = [];
+    for (const entity of entities) {
+      const rows = this.visible(entity, Array.from(this.rows.get(entity)?.values() ?? []), auth);
+      for (const row of rows) {
+        all.push({
+          seq: this.nextSeq,
+          entity,
+          row_id: (row as { id: string }).id,
+          kind: "insert",
+          data: this.project(entity, row),
+          timestamp: "",
+        } as ChangeEvent);
+      }
+    }
+    const page = all.slice(offset, offset + limit);
+    const done = offset + limit >= all.length;
+    return {
+      changes: page,
+      cursor: { last_seq: done ? this.nextSeq : 0 },
+      has_more: !done,
+      snapshot: true,
+      snapshot_after: done ? null : String(offset + limit),
+      ...(done && !this.omitSnapshotEntities ? { snapshot_entities: entities } : {}),
+    };
+  }
+
   /** /api/sync/pull — every visible change since `since`. */
   async pull(token: string | undefined, since: number): Promise<{
     changes: ChangeEvent[];

package/src/test-harness/transport.ts

@@ -251,6 +251,15 @@ async function handle(
     }
     server.pullUrls.push(url);
     const since = Number(new URL(url, "http://test").searchParams.get("since") ?? "0");
+    if (server.snapshotMode) {
+      const params = new URL(url, "http://test").searchParams;
+      const after = params.get("snapshot_after");
+      const limit = Number(params.get("limit") ?? "1000");
+      const snapshotOk = params.get("snapshot_ok") === "1";
+      if (since === 0 || after !== null || (snapshotOk && server.farBehind(since))) {
+        return { status: 200, body: server.snapshotPage(token, Number(after ?? "0"), limit) };
+      }
+    }
     // Cluster-divergence sim: a delta pull lands on an instance that
     // can't serve our cursor → 410. A snapshot (since=0) still succeeds.
     if (since > 0 && server.force410OnDelta) {

package/src/types.ts

@@ -20,6 +20,16 @@ export interface PullResponse {
   changes: ChangeEvent[];
   cursor: SyncCursor;
   has_more: boolean;
+  /** Set on every page of a snapshot (current rows, not the log): a pull
+   *  from 0, or a far-behind catch-up the client accepted with
+   *  `snapshot_ok=1`. */
+  snapshot?: boolean;
+  /** Continuation of a snapshot that spans pages. Opaque; send it back
+   *  verbatim. */
+  snapshot_after?: string | null;
+  /** On a snapshot's last page: the entities it holds every visible row
+   *  of. Rows of these entities that it did not send are gone. */
+  snapshot_entities?: string[];
 }
 
 /**