@pylonsync/sync 0.22.47 → 0.22.58

package/src/multi-tab-orchestrator.test.ts

@@ -36,6 +36,8 @@ function makeRig(opts: { isLeader?: boolean } = {}) {
       onMutationsAcked: record("mutationsAcked"),
       onMutationsFailed: record("mutationsFailed"),
       onMutationsQueued: record("mutationsQueued"),
+      onMutationsRemoved: record("mutationsRemoved"),
+      onUploadsChanged: record("uploadsChanged"),
       onSyncedReceived: record("synced"),
       onSyncStatusRequested: record("syncStatusRequested"),
       onBinaryReceived: record("binary"),

package/src/multi-tab-orchestrator.ts

@@ -95,6 +95,10 @@ export interface MultiTabOrchestratorHooks {
   /** Leader → followers: the leader's push failed transiently and
    *  these op ids stay queued for retry. */
   onMutationsQueued(opIds: string[]): void;
+  /** Another tab retried or dismissed these failed writes. */
+  onMutationsRemoved(opIds: string[]): void;
+  /** Another tab changed the upload queue in storage. */
+  onUploadsChanged(): void;
   /** Leader → follower: a binary frame from the WS. Engine routes
    *  to its local binary handlers. */
   onBinaryReceived(bytes: Uint8Array): void;
@@ -404,6 +408,15 @@ export class MultiTabOrchestrator {
         if (Array.isArray(opIds)) this.hooks.onMutationsQueued(opIds);
         break;
       }
+      case "uploads-changed": {
+        this.hooks.onUploadsChanged();
+        break;
+      }
+      case "mutations-removed": {
+        const opIds = msg.opIds as string[] | undefined;
+        if (Array.isArray(opIds)) this.hooks.onMutationsRemoved(opIds);
+        break;
+      }
       case "sub-register": {
         // Follower → leader. Leader-only — no work to do on a follower
         // because it can't act on a peer's request.

package/src/mutation-queue.ts

@@ -55,6 +55,9 @@ export interface PendingMutation {
   error?: string;
   /** Server error code for a failed mutation, when the server sent one. */
   errorCode?: string;
+  /** When the write was made, in ms since the epoch. Missing on writes
+   *  queued by an older client; those sort first. */
+  createdAt?: number;
   /** User id the write was made as (`null` = anonymous). Persisted with
    *  the queue so a write is only ever pushed as the user who made it.
    *  `undefined` = unknown (queued by an older client). */
@@ -71,6 +74,49 @@ export interface PendingMutation {
   prevRow?: Row | null;
 }
 
+/** One write as the outbox shows it. */
+export interface OutboxItem {
+  /** Op id. Pass it to `retryWrite` / `dismissWrite`. */
+  id: string;
+  entity: string;
+  rowId: string;
+  /** `"upload"` is a file from `queueUpload`; `entity`/`rowId` is the
+   *  record it attaches to. */
+  kind: "insert" | "update" | "delete" | "upload";
+  /** The fields the write sets. Empty for a delete. For an upload:
+   *  `field`, `urlField`, `filename`, `contentType`, `size`. */
+  data: Row;
+  /** When the write was made, in ms since the epoch (0 when unknown). */
+  createdAt: number;
+  /** The server's message, for a failed write. */
+  error?: string;
+  /** The server's error code (`POLICY_DENIED`, `VALIDATION_FAILED`, ...),
+   *  for a failed write. */
+  errorCode?: string;
+}
+
+/** Writes not yet on the server, and writes the server rejected. */
+export interface Outbox {
+  pending: OutboxItem[];
+  failed: OutboxItem[];
+}
+
+export function toOutboxItem(m: PendingMutation): OutboxItem {
+  const item: OutboxItem = {
+    id: m.id,
+    entity: m.change.entity,
+    rowId: m.change.row_id,
+    kind: m.change.kind,
+    data: { ...(m.change.data ?? {}) },
+    createdAt: m.createdAt ?? 0,
+  };
+  if (m.status === "failed") {
+    if (m.error !== undefined) item.error = m.error;
+    if (m.errorCode !== undefined) item.errorCode = m.errorCode;
+  }
+  return item;
+}
+
 /**
  * Optional persistence backend. The default IndexedDB persistence
  * layer supports incremental writes with `saveChanges`. Custom backends
@@ -94,11 +140,32 @@ export class MutationQueue {
   /** Callers waiting for a mutation's outcome, by op id. Memory-only:
    *  a promise cannot outlive the page that created it. */
   private waiters = new Map<string, OutcomeWaiter[]>();
+  /** Called after every change to what the queue holds or to a write's
+   *  status. The engine turns it into a store notification so the outbox
+   *  re-renders. */
+  private changeListener: (() => void) | null = null;
+  /** Bumped on every change; lets readers cache a snapshot. */
+  private _version = 0;
 
   constructor(persistence?: MutationQueuePersistence) {
     this.persistence = persistence;
   }
 
+  /** Set the one listener called after each queue change. */
+  setChangeListener(listener: (() => void) | null): void {
+    this.changeListener = listener;
+  }
+
+  /** Changes so far. Equal versions mean the same contents. */
+  version(): number {
+    return this._version;
+  }
+
+  private changed(): void {
+    this._version += 1;
+    this.changeListener?.();
+  }
+
   /**
    * Attach a persistence backend after construction. The SyncEngine
    * swaps in IndexedDB-backed persistence once the DB has opened.
@@ -125,7 +192,10 @@ export class MutationQueue {
           mergedAny = true;
         }
       }
-      if (mergedAny) this.flush();
+      if (mergedAny) {
+        this.flush();
+        this.changed();
+      }
     } catch (err) {
       // Broken storage shouldn't prevent the app from running — warn
       // and degrade to memory-only mode.
@@ -146,18 +216,26 @@ export class MutationQueue {
     prevRow?: Row | null,
     owner?: string | null,
     ownerPending?: boolean,
+    createdAt?: number,
   ): string {
     const id =
       typeof change.op_id === "string" && change.op_id.length > 0
         ? change.op_id
-        : `mut_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        : newOpId();
     if (this.queue.has(id)) return id;
     const changeWithOp: ClientChange = { ...change, op_id: id };
-    const entry: PendingMutation = { id, change: changeWithOp, status: "pending", prevRow };
+    const entry: PendingMutation = {
+      id,
+      change: changeWithOp,
+      status: "pending",
+      prevRow,
+      createdAt: createdAt ?? Date.now(),
+    };
     if (owner !== undefined) entry.owner = owner;
     if (ownerPending) entry.ownerPending = true;
     this.queue.set(id, entry);
     this.flush([entry]);
+    this.changed();
     return id;
   }
 
@@ -169,6 +247,61 @@ export class MutationQueue {
     return pending;
   }
 
+  /** Writes the server rejected, oldest first. They stay until the user
+   *  retries or dismisses them. */
+  failed(): PendingMutation[] {
+    return byCreatedAt(Array.from(this.queue.values()).filter((m) => m.status === "failed"));
+  }
+
+  /**
+   * Queue a failed write again under a new op id, with `data` (when
+   * given) merged over the original change's fields. The failed entry is
+   * removed in the same persistence write, so a reload never sees both.
+   * The new write keeps the original's owner and `createdAt`. `prevRow`
+   * is the row before the caller re-applied the write locally, for the
+   * rollback if the server rejects it again. Returns the new op id.
+   *
+   * The server forgets a rejected op id (it never applied it), so the new
+   * id cannot be applied alongside the old one.
+   */
+  retry(id: string, data: Row | undefined, prevRow: Row | null | undefined): string {
+    const m = this.queue.get(id);
+    if (!m || m.status !== "failed") {
+      throw new Error(`no failed write with id ${id}`);
+    }
+    const newId = newOpId();
+    const change: ClientChange = { ...m.change, op_id: newId };
+    if (data !== undefined && m.change.kind !== "delete") {
+      change.data = { ...(m.change.data ?? {}), ...data };
+      if (m.change.kind === "insert") change.data.id = m.change.row_id;
+    }
+    const entry: PendingMutation = {
+      id: newId,
+      change,
+      status: "pending",
+      prevRow,
+      createdAt: m.createdAt,
+    };
+    if (m.owner !== undefined) entry.owner = m.owner;
+    this.queue.delete(id);
+    this.queue.set(newId, entry);
+    this.flush([entry], [id]);
+    this.changed();
+    return newId;
+  }
+
+  /** Drop a failed write after the user has seen it. Returns false when
+   *  there is no failed write with that id (pending writes cannot be
+   *  dismissed: they may already be on the server). */
+  dismiss(id: string): boolean {
+    const m = this.queue.get(id);
+    if (!m || m.status !== "failed") return false;
+    this.queue.delete(id);
+    this.flush([], [id]);
+    this.changed();
+    return true;
+  }
+
   /** Look up a queued mutation by op id (any status). Used by the
    *  follower's mutations-failed handler to reach the captured
    *  `prevRow` for rollback. */
@@ -237,7 +370,10 @@ export class MutationQueue {
         changed.push(m);
       }
     }
-    if (changed.length > 0) this.flush(changed);
+    if (changed.length > 0) {
+      this.flush(changed);
+      this.changed();
+    }
     for (const id of ids) this.resolveWaiters(id);
   }
 
@@ -248,7 +384,10 @@ export class MutationQueue {
       m.error = error;
       if (errorCode) m.errorCode = errorCode;
     }
-    if (m) this.flush([m]);
+    if (m) {
+      this.flush([m]);
+      this.changed();
+    }
     const waiters = this.waiters.get(id);
     if (!waiters) return;
     this.waiters.delete(id);
@@ -283,7 +422,10 @@ export class MutationQueue {
         removedIds.push(id);
       }
     }
-    if (removedIds.length > 0) this.flush([], removedIds);
+    if (removedIds.length > 0) {
+      this.flush([], removedIds);
+      this.changed();
+    }
   }
 
   /** Stamp every write whose owner was pending with the user the first
@@ -307,6 +449,7 @@ export class MutationQueue {
     const m = this.get(id);
     this.queue.delete(id);
     this.flush([], [id]);
+    if (m) this.changed();
     const waiters = this.waiters.get(id);
     if (!waiters) return;
     this.waiters.delete(id);
@@ -326,8 +469,9 @@ export class MutationQueue {
   /** Remove a specific mutation by id. Used by the UI after user
    *  ack of failures. */
   remove(id: string): void {
-    this.queue.delete(id);
+    if (!this.queue.delete(id)) return;
     this.flush([], [id]);
+    this.changed();
   }
 
   /**
@@ -345,6 +489,7 @@ export class MutationQueue {
     const dropped = this.queue;
     this.queue = new Map();
     this.flush();
+    if (dropped.size > 0) this.changed();
     // Nobody will push these writes any more. Reject their waiters so a
     // caller awaiting the outcome does not hang.
     for (const m of dropped.values()) {
@@ -378,6 +523,16 @@ export class MutationQueue {
   }
 }
 
+/** A new op id. The server deduplicates pushes by it. */
+function newOpId(): string {
+  return `mut_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+
+/** Oldest first; writes without `createdAt` (older clients) first of all. */
+export function byCreatedAt(list: PendingMutation[]): PendingMutation[] {
+  return list.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+}
+
 function rejectionFor(m: PendingMutation): MutationRejectedError {
   return new MutationRejectedError(m.error ?? "The server rejected the write.", {
     code: m.errorCode,

package/src/offline-conflict.test.ts

@@ -0,0 +1,110 @@
+// What happens today when two clients edit the same row while offline and
+// then reconnect (Plan 013 step 5). This records the behavior; it does not
+// change it.
+//
+// Result: the server applies each update as a field-level patch in the order
+// the pushes arrive. Different fields both survive. On the same field the
+// last push wins. Both pushes come back "applied", so neither client is told
+// that another edit replaced its value: the earlier writer's edit is
+// overwritten in silence, and its screen changes when the other edit syncs.
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { SyncEngine, type Row } from "./index";
+import type { Storage } from "./storage";
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+class MemoryStorage implements Storage {
+  private map = new Map<string, string>();
+  get(key: string) {
+    return this.map.get(key) ?? null;
+  }
+  set(key: string, value: string) {
+    this.map.set(key, value);
+  }
+  remove(key: string) {
+    this.map.delete(key);
+  }
+}
+
+describe("two clients edit one row offline", () => {
+  let env: TestEnv | null = null;
+  let second: SyncEngine | null = null;
+  afterEach(async () => {
+    second?.stop();
+    second = null;
+    if (env) await env.dispose();
+    env = null;
+  });
+
+  async function twoClients() {
+    // Client A is the harness engine; client B is a second engine against
+    // the same server, signed in as another rep.
+    env = createTestEnv({ transport: "poll", appName: "rep-a" });
+    env.signIn({ userId: "rep-a" });
+    env.server.seed("Lead", [{ id: "l1", status: "new", note: "", phone: "" }]);
+    await env.start();
+    const storage = new MemoryStorage();
+    storage.set("pylon:rep-b:token", env.server.signIn({ userId: "rep-b" }));
+    second = new SyncEngine({
+      baseUrl: "http://test.invalid",
+      appName: "rep-b",
+      persist: false,
+      storage,
+      transport: "poll",
+      multiTab: false,
+    });
+    await second.start();
+    await env.flush();
+    return { a: env.engine, b: second, server: env.server };
+  }
+
+  /** Let each push's catch-up pull finish, then pull the other's edit
+   *  (on the poll transport nothing pushes it). */
+  async function syncBoth(a: SyncEngine, b: SyncEngine) {
+    await env!.flush(20);
+    await a.pull();
+    await b.pull();
+  }
+
+  async function offlineUpdate(engine: SyncEngine, patch: Row) {
+    env!.server.primeNextPushOutcome({ kind: "network" });
+    await engine.update("Lead", "l1", patch);
+    expect(engine.pendingCount()).toBe(1);
+  }
+
+  test("different fields: both edits survive", async () => {
+    const { a, b, server } = await twoClients();
+    await offlineUpdate(a, { status: "sold" });
+    await offlineUpdate(b, { note: "dog in yard" });
+
+    await a.push();
+    await b.push();
+    await syncBoth(a, b);
+
+    const [row] = await server.listEntityRows("Lead", env!.token);
+    expect(row).toMatchObject({ status: "sold", note: "dog in yard" });
+    expect(a.store.get("Lead", "l1")).toMatchObject({ status: "sold", note: "dog in yard" });
+    expect(b.store.get("Lead", "l1")).toMatchObject({ status: "sold", note: "dog in yard" });
+  });
+
+  test("same field: the last push wins and neither client is told", async () => {
+    const { a, b, server } = await twoClients();
+    await offlineUpdate(a, { status: "sold" });
+    await offlineUpdate(b, { status: "not interested" });
+
+    // A reconnects first, then B.
+    await a.push();
+    await b.push();
+    await syncBoth(a, b);
+
+    const [row] = await server.listEntityRows("Lead", env!.token);
+    expect(row).toMatchObject({ status: "not interested" });
+    // A's edit was replaced: A now shows B's value...
+    expect(a.store.get("Lead", "l1")).toMatchObject({ status: "not interested" });
+    // ...and nothing reports it. Both writes were applied, so neither
+    // outbox has a failed write.
+    expect(a.outbox()).toEqual({ pending: [], failed: [] });
+    expect(b.outbox()).toEqual({ pending: [], failed: [] });
+  });
+});