@pylonsync/sync 0.22.25 → 0.22.27

package/src/push-scheduling.test.ts

@@ -0,0 +1,171 @@
+import { afterEach, expect, test } from "bun:test";
+import { createTestEnv, type TestEnv } from "./test-harness";
+import type { PendingMutation } from "./mutation-queue";
+
+let env: TestEnv | undefined;
+afterEach(async () => { await env?.dispose(); env = undefined; });
+
+async function start() {
+  env = createTestEnv({ transport: "poll" });
+  env.signIn({ userId: "u1" });
+  await env.start();
+  return env;
+}
+
+test("concurrent offline writes share one queue snapshot and request", async () => {
+  const { engine, server } = await start();
+  const pending = engine.mutations.pending.bind(engine.mutations);
+  let copies = 0;
+  engine.mutations.pending = () => {
+    const rows = pending();
+    copies += rows.length;
+    return rows;
+  };
+  server.primeNextPushOutcome({ kind: "network" });
+  await Promise.all(Array.from({ length: 1000 }, (_, i) => engine.insert("Note", { title: String(i) })));
+  expect(server.pushRequestCount).toBe(1);
+  expect(copies).toBe(1000);
+  expect(pending()).toHaveLength(1000);
+  expect(engine.store.list("Note")).toHaveLength(1000);
+});
+
+test("new offline writes retain one retry and explicit recovery sends the queue", async () => {
+  const { engine, server } = await start();
+  const internals = engine as unknown as { retryTimers: Set<unknown>; pushRetryTimer: unknown };
+  server.primeNextPushOutcome({ kind: "network" });
+  await engine.insert("Note", { title: "first" });
+  const timer = internals.pushRetryTimer;
+  for (let i = 1; i < 100; i++) await engine.insert("Note", { title: String(i) });
+  expect(server.pushRequestCount).toBe(1);
+  expect(internals.pushRetryTimer).toBe(timer);
+  expect(internals.retryTimers.size).toBe(1);
+  expect(engine.mutations.pending()).toHaveLength(100);
+  await engine.push();
+  expect(server.pushRequestCount).toBe(2);
+  expect(engine.mutations.pending()).toHaveLength(0);
+  expect(internals.pushRetryTimer).toBeNull();
+  expect(internals.retryTimers.size).toBe(0);
+});
+
+test("writes added during a request drain after it completes", async () => {
+  const { engine, server } = await start();
+  const fetch = globalThis.fetch;
+  let release!: () => void;
+  let entered!: () => void;
+  const started = new Promise<void>((resolve) => { entered = resolve; });
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  let first = true;
+  globalThis.fetch = (async (input, init) => {
+    if (String(input).endsWith("/api/sync/push") && first) {
+      first = false;
+      entered();
+      await gate;
+    }
+    return fetch(input, init);
+  }) as typeof fetch;
+  const a = engine.insert("Note", { title: "first" });
+  await started;
+  const b = engine.insert("Note", { title: "second" });
+  release();
+  await Promise.all([a, b]);
+  expect(server.pushRequestCount).toBe(2);
+  expect(engine.mutations.pending()).toHaveLength(0);
+  expect(server.receivedPushKeys).toHaveLength(2);
+});
+
+test("follower writes forward only new entries and explicit replay forwards all", async () => {
+  const { engine } = await start();
+  const internals = engine as unknown as {
+    isMultiTabLeader: boolean;
+    broadcastToTabs(payload: { type: string; ops?: PendingMutation[] }): void;
+  };
+  internals.isMultiTabLeader = false;
+  const batches: number[] = [];
+  internals.broadcastToTabs = (payload) => {
+    if (payload.type !== "mutations") return;
+    batches.push(payload.ops!.length);
+    for (const op of payload.ops!) engine.mutations.settleQueued(op.id);
+  };
+  for (let i = 0; i < 100; i++) await engine.insert("Note", { title: String(i) });
+  expect(batches).toEqual(Array(100).fill(1));
+  expect(engine.mutations.pending()).toHaveLength(100);
+  await engine.push();
+  expect(batches.at(-1)).toBe(100);
+});
+
+test("stop cancels the pending push retry", async () => {
+  const { engine, server } = await start();
+  server.primeNextPushOutcome({ kind: "network" });
+  await engine.insert("Note", { title: "offline" });
+  engine.stop();
+  const internals = engine as unknown as { retryTimers: Set<unknown>; pushRetryTimer: unknown };
+  expect(internals.pushRetryTimer).toBeNull();
+  expect(internals.retryTimers.size).toBe(0);
+});
+
+test("explicit replay during a request includes writes added directly to the queue", async () => {
+  const { engine, server } = await start();
+  const fetch = globalThis.fetch;
+  let release!: () => void;
+  let entered!: () => void;
+  const started = new Promise<void>((resolve) => { entered = resolve; });
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  let first = true;
+  globalThis.fetch = (async (input, init) => {
+    if (String(input).endsWith("/api/sync/push") && first) {
+      first = false;
+      entered();
+      await gate;
+    }
+    return fetch(input, init);
+  }) as typeof fetch;
+  const a = engine.insert("Note", { title: "first" });
+  await started;
+  engine.mutations.add({ entity: "Note", row_id: "direct", kind: "insert", data: { id: "direct" } }, undefined, "u1");
+  const replay = engine.push();
+  release();
+  await Promise.all([a, replay]);
+  expect(server.pushRequestCount).toBe(2);
+  expect(server.receivedPushKeys).toContain("Note/direct");
+  expect(engine.mutations.pending()).toHaveLength(0);
+});
+
+test("writes added during a failed request wait for the same retry", async () => {
+  const { engine, server } = await start();
+  const fetch = globalThis.fetch;
+  let release!: () => void;
+  let entered!: () => void;
+  const started = new Promise<void>((resolve) => { entered = resolve; });
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  let first = true;
+  globalThis.fetch = (async (input, init) => {
+    if (String(input).endsWith("/api/sync/push") && first) {
+      first = false;
+      entered();
+      await gate;
+    }
+    return fetch(input, init);
+  }) as typeof fetch;
+  server.primeNextPushOutcome({ kind: "network" });
+  const a = engine.insert("Note", { title: "first" });
+  await started;
+  const b = engine.insert("Note", { title: "second" });
+  release();
+  await Promise.all([a, b]);
+  expect(server.pushRequestCount).toBe(1);
+  expect(engine.mutations.pending()).toHaveLength(2);
+  await engine.push();
+  expect(server.pushRequestCount).toBe(2);
+  expect(engine.mutations.pending()).toHaveLength(0);
+});
+
+test("identity reset clears the previous queue's retry delay", async () => {
+  const { engine, server } = await start();
+  server.primeNextPushOutcome({ kind: "network" });
+  await engine.insert("Note", { title: "old" });
+  await engine.resetReplica({ wipeMutations: true });
+  await engine.insert("Note", { title: "new" });
+  expect(server.pushRequestCount).toBe(2);
+  expect(engine.mutations.pending()).toHaveLength(0);
+  expect(engine.store.list("Note")).toHaveLength(1);
+});

package/src/reconcile.test.ts

@@ -248,6 +248,25 @@ describe("SyncEngine.reconcile", () => {
     expect(engine.store.list("DeletedEntity").length).toBe(0);
   });
 
+  test("a stale 404 cannot remove rows loaded after reset", async () => {
+    let respond!: (value: { status: number; body: unknown }) => void;
+    let started!: () => void;
+    const ready = new Promise<void>((resolve) => { started = resolve; });
+    restore = installFetch(async () => {
+      started();
+      return new Promise((resolve) => { respond = resolve; });
+    });
+    const engine = makeEngine();
+    seedStore(engine, "Doc", [{ id: "same", title: "old" }]);
+    const pending = engine.reconcile(["Doc"]);
+    await ready;
+    await (engine as unknown as { resetReplicaInner(): Promise<void> }).resetReplicaInner();
+    seedStore(engine, "Doc", [{ id: "same", title: "new" }]);
+    respond({ status: 404, body: {} });
+    await pending;
+    expect(engine.store.get("Doc", "same")?.title).toBe("new");
+  });
+
   test("transient 403 keeps rows; two consecutive 403s drop them (#343)", async () => {
     // A single 403 can be a bearer caught mid-refresh or a momentary policy
     // blip; nuking the cache on the first one made rows flash away and return

package/src/round6-codex.test.ts

@@ -184,10 +184,7 @@ describe("codex round-6: mutations-acked broadcast filters by status", () => {
 
     // The mutation stays in the queue, status=failed, with the error
     // string preserved.
-    const all = (engine.mutations as unknown as {
-      queue: { id: string; status: string; error?: string }[];
-    }).queue;
-    const found = all.find((m) => m.id === "op-x");
+    const found = env.engine.mutations.get("op-x");
     expect(found).toBeDefined();
     expect(found?.status).toBe("failed");
     expect(found?.error).toBe("server rejected");

package/src/scenarios.test.ts

@@ -741,9 +741,7 @@ describe("sync scenarios", () => {
     // makes the standard reconnect push re-ship it. (insert() returns the
     // ROW id; match the mutation by row_id, not its op_id.)
     expect(env.engine.store.get("Note", id)).not.toBeNull();
-    const mine = (env.engine.mutations as unknown as {
-      queue: { change: { row_id: string }; status: string }[];
-    }).queue.filter((m) => m.change.row_id === id);
+    const mine = env.engine.mutations.pending().filter((m) => m.change.row_id === id);
     expect(mine).toHaveLength(1);
     expect(mine[0]!.status).toBe("pending");
   });
@@ -811,12 +809,12 @@ describe("sync scenarios", () => {
     env.server.primeNextPushOutcome({ kind: "network" });
     await env.engine.insert("Note", { title: "draft" });
     await env.flush();
-    const queue = (env.engine.mutations as unknown as { queue: unknown[] }).queue;
-    expect(queue.length).toBeGreaterThan(0);
+    const queue = (env.engine.mutations as unknown as { queue: Map<string, unknown> }).queue;
+    expect(queue.size).toBeGreaterThan(0);
 
     // Identity flip → wipe.
     await env.engine.resetReplica({ wipeMutations: true });
-    expect((env.engine.mutations as unknown as { queue: unknown[] }).queue).toHaveLength(0);
+    expect((env.engine.mutations as unknown as { queue: Map<string, unknown> }).queue.size).toBe(0);
   });
 
   // TRANSPORT CYCLE ON IDENTITY FLIP. The WS binds the bearer token at
@@ -869,13 +867,13 @@ describe("sync scenarios", () => {
     env.server.primeNextPushOutcome({ kind: "network" });
     await env.engine.insert("Note", { title: "draft" });
     await env.flush();
-    const before = (env.engine.mutations as unknown as { queue: unknown[] }).queue.length;
+    const before = (env.engine.mutations as unknown as { queue: Map<string, unknown> }).queue.size;
     expect(before).toBeGreaterThan(0);
 
     // 410 RESYNC path is the default (wipeMutations omitted) — KEEP writes.
     await env.engine.resetReplica();
     expect(
-      (env.engine.mutations as unknown as { queue: unknown[] }).queue.length,
+      (env.engine.mutations as unknown as { queue: Map<string, unknown> }).queue.size,
     ).toBe(before);
   });
 

package/src/server-subscriptions.ts

@@ -49,6 +49,12 @@ export class ServerSubscriptions {
     return this.specs.has(key);
   }
 
+  /** Request fresh state for an existing subscription. */
+  refresh(key: string): void {
+    const message = this.specs.get(key);
+    if (message !== undefined) this.sendWs(message);
+  }
+
   /** Re-send every registered subscribe message. Called from
    *  `ws.onopen` after the socket reconnects — the server purges
    *  per-client subscription state on disconnect, so without this

package/src/subscription-coordinator.test.ts

@@ -86,10 +86,13 @@ describe("SubscriptionCoordinator CRDT subs", () => {
       "follower-a",
     );
     expect(h.serverSubs.has("Todo\x00r1")).toBe(true);
-    // Leader's own subscribe doesn't re-send (already alive via fwd).
+    // A first local consumer requests a full bootstrap.
     const before = h.wsSent.length;
     h.coord.subscribeCrdt("Todo", "r1");
-    expect(h.wsSent.length).toBe(before);
+    expect(h.wsSent.length).toBe(before + 1);
+    h.coord.subscribeCrdt("Todo", "r1");
+    expect(h.wsSent.length).toBe(before + 1);
+    h.coord.unsubscribeCrdt("Todo", "r1");
     // Leader unsubscribe with follower still wanting it keeps the WS sub alive.
     h.coord.unsubscribeCrdt("Todo", "r1");
     expect(h.serverSubs.has("Todo\x00r1")).toBe(true);

package/src/subscription-coordinator.ts

@@ -53,13 +53,6 @@ const OWN_TAB = "__self__";
 export interface SubscriptionCoordinatorContext {
   isLeader(): boolean;
   broadcastToTabs(payload: unknown): void;
-  /** Leader-side replay of the cached CRDT snapshot for a row (see
-   *  SyncEngine.lastCrdtFrames). Called when a follower registers
-   *  interest in a row whose WS subscription is ALREADY alive — the
-   *  server only ships its catch-up snapshot on a fresh
-   *  `crdt-subscribe`, so without the replay the new tab's doc stays
-   *  empty until the next live edit. */
-  replayCrdtFrame?(entity: string, rowId: string): void;
 }
 
 interface ReactiveSpec {
@@ -124,8 +117,8 @@ export class SubscriptionCoordinator {
     this.crdtSubscribers.set(key, prev + 1);
     if (prev !== 0) return;
     if (this.ctx.isLeader()) {
-      // Leader: only send the WS subscribe if no follower had already
-      // forwarded one (in which case the WS sub is already alive).
+      // A first local consumer also needs a full document if only
+      // followers held the existing subscription.
       const hasFwd = (this.crdtForwarders.get(key)?.size ?? 0) > 0;
       if (!hasFwd) {
         this.serverSubs.register(key, {
@@ -133,6 +126,8 @@ export class SubscriptionCoordinator {
           entity,
           rowId,
         });
+      } else {
+        this.serverSubs.refresh(key);
       }
     } else {
       // Follower: ask the leader to subscribe on our behalf. The leader
@@ -279,6 +274,7 @@ export class SubscriptionCoordinator {
         fwd = new Set();
         this.crdtForwarders.set(key, fwd);
       }
+      if (fwd.has(fromTabId)) return;
       fwd.add(fromTabId);
       // Register if nothing else owned this key — local count and
       // forwarder set together gate the WS subscribe.
@@ -290,11 +286,9 @@ export class SubscriptionCoordinator {
           rowId,
         });
       } else {
-        // Subscription already alive → the server won't send a fresh
-        // catch-up snapshot. Replay the leader's cached one so the
-        // follower converges immediately instead of staying empty
-        // until the next live edit.
-        this.ctx.replayCrdtFrame?.(entity, rowId);
+        // Incremental frames cannot bootstrap a new document. Ask the
+        // server for a full snapshot and a fresh authorization check.
+        this.serverSubs.refresh(key);
       }
       return;
     }
@@ -474,6 +468,10 @@ export class SubscriptionCoordinator {
   hasCrdtForwarders(): boolean {
     return this.crdtForwarders.size > 0;
   }
+
+  hasCrdtForwardersFor(entity: string, rowId: string): boolean {
+    return (this.crdtForwarders.get(crdtKey(entity, rowId))?.size ?? 0) > 0;
+  }
 }
 
 /** Internal CRDT key format: `${entity}\x00${rowId}`. Centralized so