pyric 0.0.1 → 0.1.0-alpha.8

package/dist/sandbox/tab-sync/index.js

@@ -0,0 +1,272 @@
+/**
+ * Cross-tab realtime sync for the sandbox — opt-in, Firestore only.
+ *
+ * # Why this exists
+ * Production Firestore uses WebSockets; every tab's `onSnapshot` listener
+ * receives server-pushed updates from other clients automatically. The
+ * sandbox is in-process: a write in Tab A updates Tab A's in-memory
+ * LocalEnvironment, but Tab B's environment is independent — no connection
+ * between them. This module bridges the gap by broadcasting committed writes
+ * over a `BroadcastChannel` (same-origin, no server required) so a write in
+ * Tab A fires `onSnapshot` listeners in Tab B, restoring the cross-client
+ * realtime that production users expect.
+ *
+ * # Design
+ * Three message kinds:
+ *   - `write`  — a committed write event to propagate to other tabs.
+ *   - `hello`  — sent on attach: "I just joined, please send me your state."
+ *   - `state`  — reply to a specific `hello`: current snapshot of all docs.
+ *
+ * Every message carries `origin` (a per-tab random ID) so:
+ *   (a) Echo suppression: a tab ignores messages it posted itself.
+ *   (b) The `state` reply includes `to` so only the requesting tab applies it.
+ *
+ * # Echo / infinite-loop prevention
+ * The critical invariant: applying a received write to the local env MUST NOT
+ * re-broadcast that write. Without protection, the flow would be:
+ *   Tab A writes → broadcasts → Tab B receives → applies via admin → emits
+ *   `kind:'write'` onEvent → Tab B re-broadcasts → Tab A re-applies → loops.
+ *
+ * We break the loop with a boolean re-entrancy guard `applyingRemote`. It is
+ * set to `true` around the synchronous apply call; the `onEvent` subscriber
+ * checks it before broadcasting. Because `adminSetDocument` / `adminDeleteDocument`
+ * are synchronous, the guard resets to `false` before any subsequent call.
+ *
+ * # Late-join handshake (hello/state)
+ * When a tab joins after others have already written data, it sends a `hello`.
+ * A responding tab replies with `state` (its snapshot). The joining tab applies
+ * the snapshot ONLY when its own Firestore state is empty — it's a fresh tab
+ * and the snapshot is the "initial seed". We don't clobber an active tab's
+ * state with a peer's snapshot; that's a multi-writer concern outside our scope.
+ * We also apply the state only once (first `state` message wins; duplicates are
+ * ignored via the `stateApplied` flag).
+ *
+ * # Multi-writer divergence
+ * Two tabs writing to the same document concurrently will produce divergent
+ * local state (last-write-wins per tab, no conflict resolution). This is a
+ * documented limitation — the intended model is a single active writer at a
+ * time (the common UI development pattern: one user interacting with one tab).
+ * Production Firestore also converges via server ordering that the sandbox
+ * cannot replicate offline.
+ *
+ * # RTDB
+ * Real-Time Database is explicitly NOT included here. Follow-on when RTDB
+ * has its own in-process environment analogous to LocalEnvironment.
+ */
+/** Type guard: checks that `v` is a plain object with a `kind` string field. */
+function isTabSyncMessage(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        typeof v.kind === 'string' &&
+        typeof v.origin === 'string');
+}
+// ─── Origin ID generation ─────────────────────────────────────────────────
+let _originCounter = 0;
+/**
+ * Generate a stable per-tab origin ID. Uses `crypto.randomUUID()` when
+ * available (browsers, Node ≥ 19) and falls back to a counter + process
+ * uptime string. The fallback avoids `Date.now()` and `Math.random()` —
+ * both can produce the same value in rapid succession in test environments
+ * (especially with fake timers). `process.hrtime.bigint()` or
+ * `performance.now()` would be better but aren't universally available;
+ * a simple monotonic counter is collision-free within one process.
+ */
+function generateOriginId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `tab-${crypto.randomUUID()}`;
+    }
+    // Fallback: process-unique counter. Not cryptographic, but sufficient
+    // for same-process test environments where collision-resistance matters
+    // most (two sandboxes in the same test must have different IDs).
+    return `tab-${++_originCounter}-${typeof performance !== 'undefined' ? performance.now().toFixed(3) : String(Date.now())}`;
+}
+// ─── Core attach helper ───────────────────────────────────────────────────
+/**
+ * Attach cross-tab sync to a sandbox. Called by `SandboxImpl.enableTabSync`;
+ * kept in a separate module so `sandbox-impl.ts` stays thin.
+ *
+ * Returns a `disable` function: calling it unsubscribes the onEvent listener,
+ * removes the channel message listener, and closes the channel.
+ *
+ * @param sandbox  The sandbox to sync. Must expose `onEvent`, `admin`, and `snapshot`.
+ * @param options  Optional channel and origin override.
+ */
+export function attachTabSync(sandbox, options = {}) {
+    // ── Channel setup ────────────────────────────────────────────────────
+    let channel;
+    let channelOwnedByUs = false; // track ownership so we close only our own channel
+    if (options.channel) {
+        channel = options.channel;
+        // Caller owns this channel; we don't close it on disable.
+        channelOwnedByUs = false;
+    }
+    else if (typeof BroadcastChannel !== 'undefined') {
+        channel = new BroadcastChannel('pyric:tabsync');
+        channelOwnedByUs = true;
+    }
+    else {
+        // No BroadcastChannel available (e.g. SSR / old Node). Return a
+        // no-op disable function so the call site doesn't need to guard.
+        return () => { };
+    }
+    const originId = options.originId ?? generateOriginId();
+    // ── Re-entrancy guard ────────────────────────────────────────────────
+    //
+    // WHY THIS EXISTS: applying a received write via `sandbox.admin.*`
+    // causes `LocalEnvironment.adminSetDocument` → `notifyListenersForPaths`
+    // → `SandboxImpl.emit` → our `onEvent` subscriber fires again. Without
+    // a guard, that re-fire would postMessage the same event back to the
+    // channel, which other tabs would receive and re-apply, and so on —
+    // an infinite cross-tab loop. Setting `applyingRemote = true` before
+    // the synchronous apply call and `false` after it breaks the cycle:
+    // our onEvent subscriber checks the flag and skips broadcasting when
+    // it knows the event came from a remote tab, not a local user write.
+    //
+    // The guard is a simple boolean because:
+    //   1. `adminSetDocument` / `adminDeleteDocument` are synchronous.
+    //   2. JavaScript is single-threaded — no concurrent mutation of the flag.
+    //   3. A listener callback triggered by the admin apply is also synchronous
+    //      (notification happens inside the admin call, not deferred).
+    let applyingRemote = false;
+    // ── State-applied flag for late-join ─────────────────────────────────
+    //
+    // We only apply a `state` message ONCE per enable() call. If multiple
+    // tabs respond to our `hello`, we use the first reply and ignore the rest.
+    // This prevents a second tab's snapshot from overwriting data that the
+    // first snapshot plus our own interim writes produced.
+    let stateApplied = false;
+    // ── onEvent subscription: broadcast local writes ─────────────────────
+    const unsubscribeOnEvent = sandbox.onEvent((event) => {
+        // Only forward committed write events. Request/listener/lifecycle
+        // events are local observational artifacts, not replayable state.
+        if (event.kind !== 'write')
+            return;
+        // ECHO/LOOP SUPPRESSION — primary guard. If we are currently applying
+        // a remote write, the `kind:'write'` event we receive here is the
+        // downstream effect of that apply (the LocalEnvironment emitting a write
+        // event for the admin set/delete). We MUST NOT re-broadcast it.
+        if (applyingRemote)
+            return;
+        const msg = { kind: 'write', origin: originId, event };
+        channel.postMessage(msg);
+    });
+    // ── Channel message listener: receive and apply remote writes ────────
+    const handleMessage = (ev) => {
+        if (!isTabSyncMessage(ev.data))
+            return;
+        const msg = ev.data;
+        // ECHO SUPPRESSION — secondary guard. The BroadcastChannel spec does
+        // NOT deliver messages to the sender (it's broadcast-to-others by spec),
+        // but injected test channels may differ. Filtering here makes the logic
+        // correct regardless of channel semantics.
+        if (msg.origin === originId)
+            return;
+        if (msg.kind === 'write') {
+            applyRemoteWrite(msg.event);
+        }
+        else if (msg.kind === 'hello') {
+            // A new tab joined and wants our current state. Reply with a snapshot
+            // addressed specifically to it (`to: msg.origin`) so only that tab
+            // applies it. All other tabs that receive this `state` message will
+            // see `to !== their originId` and ignore it.
+            const reply = {
+                kind: 'state',
+                origin: originId,
+                to: msg.origin,
+                snapshot: sandbox.snapshot(),
+            };
+            channel.postMessage(reply);
+        }
+        else if (msg.kind === 'state') {
+            // Only apply a `state` snapshot if:
+            //   (a) It was addressed to us.
+            //   (b) We haven't already applied a state in this enable() session.
+            //   (c) Our local Firestore store is currently empty (we're a fresh tab).
+            //
+            // Condition (c) prevents a second state reply from overwriting a tab
+            // that has already accumulated its own writes after the first state
+            // was applied. It also ensures an active tab that calls enableTabSync
+            // mid-session doesn't lose its own data to a peer's snapshot.
+            if (msg.to !== originId)
+                return;
+            if (stateApplied)
+                return;
+            const localFirestoreDocs = Object.keys(sandbox.snapshot().firestore);
+            if (localFirestoreDocs.length > 0) {
+                // Tab already has data — don't clobber it. We still mark
+                // stateApplied so further state messages are ignored.
+                stateApplied = true;
+                return;
+            }
+            // Apply the remote snapshot's Firestore docs under the re-entrancy
+            // guard so the resulting admin-write events are not re-broadcast.
+            applyingRemote = true;
+            try {
+                for (const [path, data] of Object.entries(msg.snapshot.firestore)) {
+                    sandbox.admin.setDocument(path, data);
+                }
+            }
+            finally {
+                applyingRemote = false;
+            }
+            stateApplied = true;
+        }
+    };
+    channel.addEventListener('message', handleMessage);
+    // ── Late-join hello ───────────────────────────────────────────────────
+    //
+    // Broadcast a `hello` immediately after wiring up the message listener.
+    // Other tabs that receive it will reply with `state`. We process the
+    // reply in `handleMessage` above. The hello fires AFTER the listener is
+    // registered to avoid a race where the state reply arrives before we
+    // start listening (even though BroadcastChannel is async microtask-like
+    // in browsers, the test channel may be synchronous — ordering matters).
+    const helloMsg = { kind: 'hello', origin: originId };
+    channel.postMessage(helloMsg);
+    // ── Disable function ──────────────────────────────────────────────────
+    return () => {
+        unsubscribeOnEvent();
+        channel.removeEventListener('message', handleMessage);
+        // Only close the channel when we created it. If the caller supplied
+        // their own channel, they own its lifecycle.
+        if (channelOwnedByUs) {
+            channel.close();
+        }
+    };
+    // ── Inner: apply a remote write to the local env ─────────────────────
+    function applyRemoteWrite(event) {
+        // Apply under the re-entrancy guard so the resulting onEvent emission
+        // (from adminSetDocument → notifyListenersForPaths → SandboxImpl.emit)
+        // is NOT re-broadcast. This is the loop-breaking mechanism.
+        //
+        // WHY admin path: the write was already authorized by the originating tab's
+        // rules engine. Applying it as admin on the receiving tab bypasses rules on
+        // the write side, which is correct — we're replicating a committed write.
+        // Read-side rules are NOT bypassed: the `notifyListenersForPaths` call
+        // triggered by `adminSetDocument`/`adminDeleteDocument` re-evaluates each
+        // snapshot listener under ITS OWN registered auth identity (the listener's
+        // `auth` field captured at subscribe time). So a listener that couldn't
+        // read a document before still can't read it after the remote write — the
+        // normal read-rules path applies.
+        applyingRemote = true;
+        try {
+            if (event.method === 'delete') {
+                sandbox.admin.deleteDocument(event.path);
+            }
+            else {
+                // set / create / update — in all cases `nextState` is the post-
+                // resolution document data we want the receiving tab to have.
+                // We use setDocument (replace semantics) because `nextState` is
+                // already the fully-resolved final state; we don't need to re-merge.
+                const data = event.nextState;
+                if (data !== null && data !== undefined) {
+                    sandbox.admin.setDocument(event.path, data);
+                }
+            }
+        }
+        finally {
+            applyingRemote = false;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/tab-sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/tab-sync/index.ts"],"names":[],"mappings":"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"}