jazz-tools 0.20.18 → 0.20.19

package/src/tools/implementation/sessionDurabilityMarker.ts

@@ -0,0 +1,93 @@
+import type { LocalStoreDurabilityListener, SessionID } from "cojson";
+
+/**
+ * Persists a per-session "dirty" flag that survives crashes.
+ *
+ * The flag is set while the session has transactions that were sent to a sync
+ * server but are not yet durably stored locally. If the process dies inside
+ * that window, local storage is behind what the server received for the
+ * session, and reusing it would fork the session's hash chain. Session
+ * providers must skip sessions whose flag is still set and mint a fresh
+ * session instead.
+ */
+export interface SessionDurabilityMarker {
+  /**
+   * Must be initiated synchronously: the write has to win the race against
+   * the network send that immediately follows it.
+   */
+  set(sessionID: SessionID): void;
+  clear(sessionID: SessionID): void;
+  isSet(sessionID: SessionID): boolean | Promise<boolean>;
+}
+
+/**
+ * Storage key under which a session's dirty flag is persisted. Shared by all
+ * platform marker implementations so the key format cannot silently diverge.
+ */
+export function sessionDurabilityMarkerKey(sessionID: SessionID) {
+  return `jazz_session_dirty_${sessionID}`;
+}
+
+export const SESSION_DURABILITY_CLEAR_DEBOUNCE_MS = 200;
+
+/**
+ * Adapts a SessionDurabilityMarker to LocalNode's onLocalStoreDurabilityChange
+ * hook. Setting is immediate (correctness-critical); clearing is debounced so
+ * the marker doesn't churn on every batch while the user is actively editing.
+ * A crash inside the debounce at worst abandons one session unnecessarily.
+ *
+ * Returns undefined when no marker is provided, matching the optional
+ * listener slot on LocalNode creation options.
+ */
+export function makeDurabilityMarkerListener(
+  marker: SessionDurabilityMarker,
+  clearDebounceMs?: number,
+): LocalStoreDurabilityListener;
+export function makeDurabilityMarkerListener(
+  marker: SessionDurabilityMarker | undefined,
+  clearDebounceMs?: number,
+): LocalStoreDurabilityListener | undefined;
+export function makeDurabilityMarkerListener(
+  marker: SessionDurabilityMarker | undefined,
+  clearDebounceMs: number = SESSION_DURABILITY_CLEAR_DEBOUNCE_MS,
+): LocalStoreDurabilityListener | undefined {
+  if (!marker) {
+    return undefined;
+  }
+
+  let clearTimer: ReturnType<typeof setTimeout> | undefined;
+  let markerIsSet = false;
+
+  return (hasPending, sessionID) => {
+    if (clearTimer !== undefined) {
+      clearTimeout(clearTimer);
+      clearTimer = undefined;
+    }
+
+    if (hasPending) {
+      // A window reopening within the clear debounce finds the marker still
+      // set: skip the write so steady-state editing costs no marker I/O
+      if (markerIsSet) {
+        return;
+      }
+
+      try {
+        marker.set(sessionID);
+        markerIsSet = true;
+      } catch (err) {
+        console.warn("Failed to set session durability marker", err);
+      }
+    } else {
+      clearTimer = setTimeout(() => {
+        clearTimer = undefined;
+
+        try {
+          marker.clear(sessionID);
+          markerIsSet = false;
+        } catch (err) {
+          console.warn("Failed to clear session durability marker", err);
+        }
+      }, clearDebounceMs);
+    }
+  };
+}

package/src/tools/internal.ts

@@ -33,6 +33,7 @@ export * from "./lib/cache.js";
 export * from "./lib/utils.js";
 export * from "./lib/utilityTypes.js";
 export * from "./implementation/createContext.js";
+export * from "./implementation/sessionDurabilityMarker.js";
 
 export * from "./types.js";
 export * from "./implementation/zodSchema/zodSchema.js";

package/src/tools/tests/sessionDurabilityMarker.test.ts

@@ -0,0 +1,183 @@
+import type { SessionID } from "cojson";
+import { WasmCrypto } from "cojson/crypto/WasmCrypto";
+import { LocalNode } from "cojson";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { makeDurabilityMarkerListener } from "../implementation/sessionDurabilityMarker.js";
+import {
+  Credentials,
+  InMemoryKVStore,
+  KvStoreContext,
+  MockSessionProvider,
+  createJazzContextFromExistingCredentials,
+} from "../exports.js";
+import {
+  createJazzTestAccount,
+  getPeerConnectedToTestSyncServer,
+  setupJazzTestSync,
+} from "../testing.js";
+
+const sessionID = "co_ztest_session_ztest" as SessionID;
+
+function mockMarker() {
+  return { set: vi.fn(), clear: vi.fn(), isSet: vi.fn(() => false) };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("makeDurabilityMarkerListener", () => {
+  test("sets the marker synchronously when the window opens", () => {
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker);
+
+    listener(true, sessionID);
+
+    expect(marker.set).toHaveBeenCalledWith(sessionID);
+    expect(marker.clear).not.toHaveBeenCalled();
+  });
+
+  test("clears the marker only after the debounce delay", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    expect(marker.clear).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(200);
+    expect(marker.clear).toHaveBeenCalledWith(sessionID);
+  });
+
+  test("a new pending window cancels a scheduled clear", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    listener(true, sessionID); // window re-opens within the debounce
+    vi.advanceTimersByTime(500);
+
+    expect(marker.clear).not.toHaveBeenCalled();
+  });
+
+  test("consecutive clears don't leave an orphaned timer that clears a fresh set", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    listener(false, sessionID); // must supersede (not orphan) the first timer
+    listener(true, sessionID); // window re-opens: no clear may fire anymore
+    vi.advanceTimersByTime(500);
+
+    expect(marker.clear).not.toHaveBeenCalled();
+  });
+
+  test("a reopen within the debounce doesn't rewrite the still-set marker", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    listener(true, sessionID); // marker was never cleared: no write needed
+
+    expect(marker.set).toHaveBeenCalledTimes(1);
+
+    // ...but after an actual clear, the next window writes again
+    listener(false, sessionID);
+    vi.advanceTimersByTime(200);
+    listener(true, sessionID);
+
+    expect(marker.clear).toHaveBeenCalledTimes(1);
+    expect(marker.set).toHaveBeenCalledTimes(2);
+  });
+
+  test("returns undefined when no marker is provided", () => {
+    expect(makeDurabilityMarkerListener(undefined)).toBeUndefined();
+  });
+
+  test("marker errors are swallowed with a warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const marker = mockMarker();
+    marker.set.mockImplementation(() => {
+      throw new Error("quota exceeded");
+    });
+    const listener = makeDurabilityMarkerListener(marker);
+
+    expect(() => listener(true, sessionID)).not.toThrow();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+const Crypto = await WasmCrypto.create();
+KvStoreContext.getInstance().initialize(new InMemoryKVStore());
+
+describe("createContext wiring", () => {
+  test("passes a durability listener to LocalNode when the provider has a marker", async () => {
+    await setupJazzTestSync();
+    const account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const credentials: Credentials = {
+      accountID: account.$jazz.id,
+      secret: account.$jazz.localNode.getCurrentAgent().agentSecret,
+    };
+
+    const spy = vi.spyOn(LocalNode, "withLoadedAccount");
+
+    const provider = new MockSessionProvider();
+    provider.durabilityMarker = mockMarker();
+
+    const context = await createJazzContextFromExistingCredentials({
+      credentials,
+      peers: [getPeerConnectedToTestSyncServer()],
+      crypto: Crypto,
+      sessionProvider: provider,
+      asActiveAccount: false,
+    });
+    context.done();
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onLocalStoreDurabilityChange: expect.any(Function),
+      }),
+    );
+  });
+
+  test("passes no listener when the provider has no marker", async () => {
+    await setupJazzTestSync();
+    const account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const credentials: Credentials = {
+      accountID: account.$jazz.id,
+      secret: account.$jazz.localNode.getCurrentAgent().agentSecret,
+    };
+
+    const spy = vi.spyOn(LocalNode, "withLoadedAccount");
+
+    const context = await createJazzContextFromExistingCredentials({
+      credentials,
+      peers: [getPeerConnectedToTestSyncServer()],
+      crypto: Crypto,
+      sessionProvider: new MockSessionProvider(),
+      asActiveAccount: false,
+    });
+    context.done();
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onLocalStoreDurabilityChange: undefined,
+      }),
+    );
+  });
+});