@abide/abide 0.51.0 → 0.52.0

package/src/lib/ui/startClient.ts

@@ -1,3 +1,5 @@
+import { applyCacheStalenessLocally } from '../shared/applyCacheStalenessLocally.ts'
+import { cacheStalenessSlot } from '../shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
@@ -8,9 +10,11 @@ import { probeNavigation } from './probeNavigation.ts'
 import { router } from './router.ts'
 import { CELL_SEED } from './runtime/CELL_SEED.ts'
 import { clientPage } from './runtime/clientPage.ts'
+import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
 import { seedBootState } from './seedBootState.ts'
 import { seedStreamedResolution } from './seedStreamedResolution.ts'
+import { subscribeCacheStaleness } from './subscribeCacheStaleness.ts'
 
 /*
 The official abide-ui client entry. Reads the server's `window.__SSR__` payload,
@@ -49,6 +53,10 @@ export function startClient(
     cacheStoreSlot.resolver = () => store
     /* One tab store: cache(fn, { shared: true }) shares it, so shared is a no-op here. */
     sharedCacheStoreSlot.resolver = () => store
+    /* invalidate()/refresh() apply to THIS tab's cache (the server entry installs a
+       broadcaster instead — the ADR-0041 side-swap). Same function as the slot fallback so
+       the local-apply path can't diverge. */
+    cacheStalenessSlot.resolver = () => applyCacheStalenessLocally
     /* Seed both SSR cache partitions through the one streamed-resolution sink: `ssr.cache`
        (inline — reads settled at render-return, in __SSR__) and `__abideResumeCache` (pending
        {#await} reads whose `__abideResolve(...)` chunks the stream pushed during parse, before
@@ -66,6 +74,12 @@ export function startClient(
     if (ssr.cells !== undefined) {
         Object.assign(CELL_SEED, ssr.cells)
     }
+    /* Seed the doc-state warm partition into DOC_SEED before mount: a hydrating `createScope` reads
+       its render-path key to adopt the SSR doc snapshot, so a plain `state(initial)` keeps the server
+       value (the consume-once swap in `scope.replace`) instead of re-running a divergent init. */
+    if (ssr.docs !== undefined) {
+        Object.assign(DOC_SEED, ssr.docs)
+    }
     /* Keep the cache channel live past boot: replace the head's buffering collector with
        the store-connected sink so a post-boot resolution — the inline doc-stream cache
        script — seeds the store through `seedStreamedResolution` directly instead of pushing
@@ -74,5 +88,12 @@ export function startClient(
     ;(globalThis as { __abideResolve?: (resolution: StreamedResolution) => void }).__abideResolve =
         seedStreamedResolution
 
-    return router(target, routes, layoutRoutes, probeNavigation)
+    /* Subscribe to the reserved cache-staleness pipe (ADR-0041) AFTER seeding, so a server
+       broadcast drops/refetches this tab's freshly-hydrated cache — live-only, never replay. */
+    const disposeStaleness = subscribeCacheStaleness()
+    const disposeRouter = router(target, routes, layoutRoutes, probeNavigation)
+    return () => {
+        disposeStaleness()
+        disposeRouter()
+    }
 }

package/src/lib/ui/subscribeCacheStaleness.ts

@@ -0,0 +1,85 @@
+import { abideLog } from '../shared/abideLog.ts'
+import { CACHE_STALENESS_SOCKET } from '../shared/CACHE_STALENESS_SOCKET.ts'
+import { cache } from '../shared/cache.ts'
+import { matcherFromEnvelope } from '../shared/matcherFromEnvelope.ts'
+import { SocketDisconnectedError } from '../shared/SocketDisconnectedError.ts'
+import type { CacheStalenessFrame } from '../shared/types/CacheStalenessFrame.ts'
+import type { Socket } from '../shared/types/Socket.ts'
+import { socketProxy } from './socketProxy.ts'
+
+/*
+The client half of the cross-client staleness broadcast (ADR-0041): every tab
+subscribes to the reserved __abide/cache socket at boot and applies each frame to
+its own cache. A frame rebuilds the entry predicate via matcherFromEnvelope and
+drives the SAME store loop a local invalidate()/refresh() does
+(cache.invalidateMatching / cache.refreshMatching), so wire-driven and local applies
+can't diverge.
+
+LIVE-ONLY, never replay: bare iteration (replay 0) on both boot and reconnect — a
+client applies only frames published while it is connected. The reserved topic keeps
+no tail, so there is nothing to catch up on; a client offline when a frame was
+published misses it and falls back to SWR staleness. Applies are idempotent, so
+correctness has no dependency on frame ordering.
+
+No-op on the server (no window): the broadcast is the server's job, not something it
+consumes. Returns a disposer that stops the loop and closes the subscription.
+*/
+export function subscribeCacheStaleness(injectedSocket?: Socket<CacheStalenessFrame>): () => void {
+    if (typeof window === 'undefined') {
+        return () => undefined
+    }
+    /* Default to the browser channel proxy; tests inject a socket over their own channel. */
+    const socket = injectedSocket ?? socketProxy<CacheStalenessFrame>(CACHE_STALENESS_SOCKET)
+    const controller = new AbortController()
+    /* `let`: a reconnect swaps in a fresh live iterator after a transport loss. */
+    let iterator = socket[Symbol.asyncIterator]()
+    ;(async () => {
+        while (!controller.signal.aborted) {
+            let next: IteratorResult<CacheStalenessFrame>
+            try {
+                next = await iterator.next()
+            } catch (error) {
+                if (controller.signal.aborted) {
+                    return
+                }
+                /* Transport loss: re-open a fresh LIVE subscription (no replay) and keep going. */
+                if (error instanceof SocketDisconnectedError) {
+                    iterator = socket[Symbol.asyncIterator]()
+                    continue
+                }
+                abideLog.error(error)
+                return
+            }
+            if (controller.signal.aborted || next.done === true) {
+                return
+            }
+            /* One malformed frame must not tear down the live pipe: a throw from decode/apply
+               is logged and swallowed so every subsequent frame still delivers. Frames come
+               only from the trusted server (clientPublish is false), so this is defense in
+               depth, not an expected path. */
+            try {
+                applyFrame(next.value)
+            } catch (error) {
+                abideLog.error(error)
+            }
+        }
+    })()
+    return () => {
+        controller.abort()
+        iterator.return?.(undefined)?.catch(() => undefined)
+    }
+}
+
+/* Applies one decoded frame to this tab's cache via the shared apply-by-matcher seam. */
+function applyFrame(frame: CacheStalenessFrame): void {
+    const matches = matcherFromEnvelope(frame)
+    /* The tripwire label + the rpc-error-registry prefix, mirroring what a local selector
+       derives: a tag frame has no key prefix to clear. */
+    const label = frame.mode === 'tags' ? `tags: ${frame.tags.join(', ')}` : frame.match
+    const prefix = frame.mode === 'tags' ? undefined : frame.match
+    if (frame.op === 'invalidate') {
+        cache.invalidateMatching(matches, label, prefix)
+    } else {
+        cache.refreshMatching(matches, label, prefix)
+    }
+}

package/src/serverEntry.ts

@@ -26,11 +26,14 @@ import { shell } from './_virtual/shell.ts'
 import { sockets } from './_virtual/sockets.ts'
 import { exitWithParent } from './lib/bundle/exitWithParent.ts'
 import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
+import { broadcastCacheStaleness } from './lib/server/runtime/cacheStalenessBroadcaster.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { resolvePageSnapshot } from './lib/server/runtime/resolvePageSnapshot.ts'
+import { cacheStalenessSlot } from './lib/shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from './lib/shared/cacheStoreSlot.ts'
 import { createCacheStore } from './lib/shared/createCacheStore.ts'
+import { docSnapshotsSlot } from './lib/shared/docSnapshotsSlot.ts'
 import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { pageSlot } from './lib/shared/pageSlot.ts'
 import { pendingAsyncCellsSlot } from './lib/shared/pendingAsyncCellsSlot.ts'
@@ -79,6 +82,13 @@ sharedCacheStoreSlot.resolver = () => sharedCacheStore
 
 cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedCacheStore
 
+/*
+Server-side invalidate()/refresh() broadcast to every connected client instead of
+mutating a throwaway request store (ADR-0041). The broadcaster is imported ONLY here
+so its server socket code never enters the client reachability graph.
+*/
+cacheStalenessSlot.resolver = () => broadcastCacheStaleness
+
 /* One process-wide fallback list for reads with no request in flight (boot/cron/socket) —
    real requests each carry their own `pendingAsyncCells`, so the SSR barrier drains a
    per-request list and concurrent renders never cross-contaminate. */
@@ -89,6 +99,8 @@ const sharedResolvedCells = { entries: [] }
 resolvedCellsSlot.resolver = () => requestContext.getStore()?.resolvedCells ?? sharedResolvedCells
 const sharedStreamedCells = { entries: [] }
 streamedCellsSlot.resolver = () => requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+const sharedDocSnapshots = { entries: [] }
+docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
 
 pageSlot.resolver = resolvePageSnapshot