Archipelago — open-source initial import

neode-ui/src/composables/useCachedResource.ts

@@ -0,0 +1,138 @@
+// Stale-while-revalidate resource hook over the shared resources store.
+//
+// Usage:
+//   const files = useCachedResource<CloudFile[]>({
+//     key: 'cloud.my-files',
+//     fetcher: (signal) => rpcClient.call({ method: 'content.list', signal, dedup: true }),
+//     ttlMs: 30_000,
+//   })
+//   // template: files.data renders instantly on revisit (cache), while
+//   // files.loadState === 'refreshing' drives a subtle refresh indicator.
+//
+// Behavior:
+// - Synchronous hydrate: memory (survives navigation) → sessionStorage
+//   snapshot (survives reload) → fetch.
+// - Sticky-ready: never regresses ready → loading; refreshes are
+//   'refreshing' so content stays on screen.
+// - Stale-while-revalidate: on mount, cached data is shown immediately and a
+//   background refresh runs only if the TTL has lapsed (or never fetched).
+// - Keep-last-value on error, with `isStale`/`ageMs` for badges.
+// - revalidateOnFocus: refreshes when the tab regains focus and the data is
+//   stale (debounced by TTL, so focus-flapping is free).
+// - Abort-on-unmount: the fetcher receives an AbortSignal that fires when
+//   the last subscribed component unmounts.
+
+import { computed, getCurrentScope, onActivated, onScopeDispose, type ComputedRef } from 'vue'
+import { useResourcesStore, type ResourceEntry, type ResourceLoadState } from '@/stores/resources'
+
+export interface CachedResourceOptions<T> {
+  /** Cache key. Include identifying params, e.g. `peer-files:${onion}`. */
+  key: string
+  /** Fetch fresh data. Receives an abort signal tied to component lifetime. */
+  fetcher: (signal: AbortSignal) => Promise<T>
+  /** Data older than this triggers a background revalidate (default 30s). */
+  ttlMs?: number
+  /** Snapshot to sessionStorage so reloads paint instantly. REQUIRED (no
+   * default) — `persist ?? true` was the exact footgun CR-01 hit (a wallet
+   * resource omitted this and silently persisted balances to
+   * sessionStorage), so every call site must make the decision explicitly.
+   * Sensitive data (money, identity, peer-identity/DID/pubkey payloads)
+   * MUST be `false`; static/aggregate/non-identifying data may be `true`. */
+  persist: boolean
+  /** Revalidate (if stale) when the window regains focus (default true). */
+  revalidateOnFocus?: boolean
+  /** Fetch on first use (default true). Set false for lazy resources. */
+  immediate?: boolean
+}
+
+export interface CachedResource<T> {
+  entry: ResourceEntry<T>
+  /** Convenience computed views over the entry. */
+  data: ComputedRef<T | null>
+  loadState: ComputedRef<ResourceLoadState>
+  error: ComputedRef<string | null>
+  /** True when data exists but is older than the TTL (drive an age badge). */
+  isStale: ComputedRef<boolean>
+  ageMs: ComputedRef<number | null>
+  /** Force a refresh now (deduped with any in-flight one). */
+  refresh: () => Promise<void>
+  /** Mark stale + debounce-refresh all mounted users of this key. */
+  invalidate: () => void
+  /** Optimistically update cached data; returns rollback for RPC failure. */
+  optimistic: (update: (current: T | null) => T) => () => void
+}
+
+export function useCachedResource<T>(opts: CachedResourceOptions<T>): CachedResource<T> {
+  const store = useResourcesStore()
+  const ttlMs = opts.ttlMs ?? 30_000
+  const persist = opts.persist
+  const entry = store.entry<T>(opts.key, persist)
+
+  const aborter = new AbortController()
+  const fetcher = () => opts.fetcher(aborter.signal)
+  const refresh = () => store.refresh(opts.key, fetcher, { persist })
+
+  const stale = () => entry.fetchedAt === null || Date.now() - entry.fetchedAt > ttlMs
+  const refreshIfStale = () => {
+    if (stale()) void refresh()
+  }
+
+  // Register as a live revalidator so invalidate(key) reaches us.
+  const unsubscribe = store.subscribe(opts.key, () => void refresh())
+
+  const onFocus = () => refreshIfStale()
+  if (opts.revalidateOnFocus ?? true) {
+    window.addEventListener('focus', onFocus)
+  }
+
+  // Tied to the owning effect scope (component setup or manual scope);
+  // outside any scope (tests, module init) there's nothing to dispose.
+  if (getCurrentScope()) {
+    onScopeDispose(() => {
+      unsubscribe()
+      window.removeEventListener('focus', onFocus)
+      aborter.abort()
+    })
+
+    // Reactivation (a KeepAlive'd component being shown again) is a distinct
+    // trigger from mount and from window focus: onScopeDispose doesn't fire
+    // on deactivate (the instance is preserved, not destroyed), and the
+    // focus listener doesn't fire on an in-SPA tab switch (the window never
+    // loses focus). Without this a kept-alive tab would paint instantly
+    // forever and never revalidate. Vue no-ops onActivated outside a
+    // <KeepAlive> boundary, so this is safe for every existing consumer.
+    //
+    // `immediate: false` resources are a distinct case (found in 02-04's
+    // audit, once Cloud.vue/Server.vue's main-tab paths joined
+    // KEEP_ALIVE_PATHS): `stale()` is true for any never-fetched entry
+    // (`fetchedAt === null`), so a bare `refreshIfStale()` here would fire
+    // the fetch the moment the tab is first activated — defeating a resource
+    // deliberately marked "fetch on first use" (e.g. a tab-gated fetch that
+    // should wait for the user to open that sub-tab). Only auto-revalidate
+    // an `immediate: false` resource on activation once it has actually been
+    // fetched at least once; before that, activation is a no-op and the
+    // resource's own explicit trigger (a watcher, an onMounted/onActivated
+    // "kick") still owns the first fetch.
+    onActivated(() => {
+      if (opts.immediate === false && entry.fetchedAt === null) return
+      refreshIfStale()
+    })
+  }
+
+  if (opts.immediate ?? true) refreshIfStale()
+
+  return {
+    entry,
+    data: computed(() => entry.data),
+    loadState: computed(() => entry.loadState),
+    error: computed(() => entry.error),
+    isStale: computed(() => entry.data !== null && stale()),
+    ageMs: computed(() => (entry.fetchedAt === null ? null : Date.now() - entry.fetchedAt)),
+    refresh,
+    invalidate: () => store.invalidate(opts.key),
+    // Pass this resource's own already-decided `persist` through explicitly
+    // (WR-04) — store.optimistic() requires it rather than defaulting, so
+    // the entry's persist decision can never silently diverge by omission.
+    optimistic: (update) => store.optimistic<T>(opts.key, update, persist),
+  }
+}