@skyhook-io/radar-app 1.8.6 → 1.8.7

package/src/RadarApp.tsx

@@ -16,23 +16,39 @@
 // Both are applied before any children render so downstream code that
 // reads config synchronously (e.g. URL construction inside fetchJSON)
 // sees the host's values.
-import React from 'react';
-import { BrowserRouter, MemoryRouter } from 'react-router-dom';
-import { QueryClient, QueryClientProvider, MutationCache, QueryCache } from '@tanstack/react-query';
+import React from "react";
+import { BrowserRouter, MemoryRouter } from "react-router-dom";
+import {
+  QueryClient,
+  QueryClientProvider,
+  MutationCache,
+  QueryCache,
+} from "@tanstack/react-query";
 
-import App from './App';
-import { ThemeProvider } from './context/ThemeContext';
-import { ToastProvider, showApiError, showApiSuccess } from './components/ui/Toast';
-import { setApiBase, setBasename } from './api/config';
-import { NavCustomizationProvider } from './context/NavCustomization';
-import { FilterLocationBridge } from './filter/FilterLocationBridge';
-import type { NavCustomization } from './context/NavCustomization';
+import App from "./App";
+import { ThemeProvider } from "./context/ThemeContext";
+import {
+  ToastProvider,
+  showApiError,
+  showApiSuccess,
+} from "./components/ui/Toast";
+import { setApiBase, setBasename } from "./api/config";
+import { NavCustomizationProvider } from "./context/NavCustomization";
+import { FilterLocationBridge } from "./filter/FilterLocationBridge";
+import type { NavCustomization } from "./context/NavCustomization";
+import type { ClusterLoadState } from "./types/clusterLoadState";
+import { TimelineSourceProvider } from "./context/TimelineSource";
+import type { TimelineSourceConfig } from "./api/timelineSource";
+import { DiagnoseCustomizationProvider } from "./context/DiagnoseCustomization";
+import type { RenderDiagnoseAction } from "./context/DiagnoseCustomization";
+import { defaultDiagnoseAction } from "./components/diagnose/LocalDiagnoseAction";
+import { DiagnoseProvider } from "./components/diagnose/DiagnoseContext";
 
 // Declare the shape of mutation meta here — inlined rather than in a
 // separate side-effect-only module so consumers that tree-shake aggressively
 // (package.json sets sideEffects: ["*.css"]) can't drop the augmentation.
 // Any consumer that imports RadarApp will pull in this declaration.
-declare module '@tanstack/react-query' {
+declare module "@tanstack/react-query" {
   interface Register {
     mutationMeta: {
       errorMessage?: string;
@@ -57,7 +73,7 @@ export interface RadarAppProps {
    *     Escape hatch for tests and for host apps that can't restructure
    *     around a single top-level BrowserRouter.
    */
-  router?: 'browser' | 'memory';
+  router?: "browser" | "memory";
   /**
    * Optional QueryClient override. When consuming Radar inside another app
    * that already has a QueryClientProvider higher in the tree, you may
@@ -86,6 +102,14 @@ export interface RadarAppProps {
    * Defaults to `' · Radar'`.
    */
   documentTitleSuffix?: string;
+  /**
+   * Injects a resource-level "Diagnose" action (e.g. a "Diagnose with AI"
+   * button) into every resource detail action bar's right-aligned universal
+   * actions. The host returns the node to render given the resource context.
+   * Standalone Radar omits this and renders no Diagnose button — OSS stays
+   * agent-free. See ./context/DiagnoseCustomization for the render-prop shape.
+   */
+  renderDiagnoseAction?: RenderDiagnoseAction;
   /**
    * Initial route for `router: 'memory'` (ignored for 'browser'). Lets a host
    * deep-link a specific view (e.g. '/topology') without owning the URL bar —
@@ -93,6 +117,26 @@ export interface RadarAppProps {
    * chromeless under the host's own chrome (Radar Hub's per-cluster destinations).
    */
   initialPath?: string;
+  /**
+   * Reports cluster-data warmup after the main connection is usable. Embedders
+   * with their own chrome (Radar Hub) can render this in their topbar while
+   * Radar runs with `navSlots.chrome: 'none'`.
+   */
+  onClusterLoadStateChange?: (state: ClusterLoadState) => void;
+  /**
+   * Selects the store backing the event timeline. Omit for the local event
+   * store the Radar binary keeps (default, standalone behavior). Set
+   * `{ mode: 'retained' }` when embedding behind a proxy that serves a
+   * longer-horizon history at `{apiBase}/timeline/events` +
+   * `{apiBase}/timeline/overview`; `maxRangeDays` caps how far back the
+   * 'all' range reaches. Generic extension point — the backend that answers
+   * the retained endpoints is the host's concern.
+   *
+   * Changing `mode` between renders remounts the timeline view (the local and
+   * retained sources expose different `useEvents` hooks; remounting avoids a
+   * React hook-order violation). Set it once at mount when possible.
+   */
+  timelineSource?: TimelineSourceConfig;
 }
 
 // Default QueryClient with the same shape Radar's standalone binary uses.
@@ -113,13 +157,18 @@ function makeDefaultQueryClient(): QueryClient {
       },
       onSuccess: (_data, _variables, _context, mutation) => {
         const message = mutation.options.meta?.successMessage;
-        if (message) showApiSuccess(message, mutation.options.meta?.successDetail);
+        if (message)
+          showApiSuccess(message, mutation.options.meta?.successDetail);
       },
     }),
     queryCache: new QueryCache({
       onError: (error, query) => {
         if (query.state.data !== undefined) {
-          console.warn('[Background sync failed]', query.queryKey, (error as Error).message);
+          console.warn(
+            "[Background sync failed]",
+            query.queryKey,
+            (error as Error).message,
+          );
         }
       },
     }),
@@ -129,12 +178,15 @@ function makeDefaultQueryClient(): QueryClient {
 export function RadarApp({
   apiBase,
   basename,
-  router = 'browser',
+  router = "browser",
   queryClient,
   navSlots,
   manageDocumentTitle = false,
   documentTitleSuffix,
+  renderDiagnoseAction,
   initialPath,
+  onClusterLoadStateChange,
+  timelineSource,
 }: RadarAppProps): React.ReactElement {
   // Apply runtime config during render so module-level singletons are set
   // before children construct URLs. getApiBase() / getAuthHeaders() /
@@ -147,7 +199,10 @@ export function RadarApp({
 
   // Memo so we don't recreate the QueryClient on every render when the
   // consumer didn't pass one.
-  const client = React.useMemo(() => queryClient ?? makeDefaultQueryClient(), [queryClient]);
+  const client = React.useMemo(
+    () => queryClient ?? makeDefaultQueryClient(),
+    [queryClient],
+  );
 
   const inner = (
     <ThemeProvider>
@@ -155,7 +210,19 @@ export function RadarApp({
         <ToastProvider>
           <NavCustomizationProvider value={navSlots}>
             <FilterLocationBridge>
-              <App manageDocumentTitle={manageDocumentTitle} documentTitleSuffix={documentTitleSuffix} />
+              <TimelineSourceProvider config={timelineSource}>
+                <DiagnoseCustomizationProvider
+                  value={renderDiagnoseAction ?? defaultDiagnoseAction}
+                >
+                  <DiagnoseProvider>
+                    <App
+                      manageDocumentTitle={manageDocumentTitle}
+                      documentTitleSuffix={documentTitleSuffix}
+                      onClusterLoadStateChange={onClusterLoadStateChange}
+                    />
+                  </DiagnoseProvider>
+                </DiagnoseCustomizationProvider>
+              </TimelineSourceProvider>
             </FilterLocationBridge>
           </NavCustomizationProvider>
         </ToastProvider>
@@ -163,11 +230,15 @@ export function RadarApp({
     </ThemeProvider>
   );
 
-  if (router === 'memory') {
-    return <MemoryRouter initialEntries={[initialPath || '/']}>{inner}</MemoryRouter>;
+  if (router === "memory") {
+    return (
+      <MemoryRouter initialEntries={[initialPath || "/"]}>{inner}</MemoryRouter>
+    );
   }
 
-  return <BrowserRouter basename={basename || undefined}>{inner}</BrowserRouter>;
+  return (
+    <BrowserRouter basename={basename || undefined}>{inner}</BrowserRouter>
+  );
 }
 
 export default RadarApp;

package/src/api/client.delta.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { deltaFetchCursor, maxEventSeq, mergeDeltaEvents, type ChangesDeltaMeta } from './client'
+import type { TimelineEvent } from '@skyhook-io/k8s-ui'
+
+const mk = (id: string, seq: number, tsOffsetMs: number): TimelineEvent => ({
+  id,
+  seq,
+  timestamp: new Date(1_700_000_000_000 + tsOffsetMs).toISOString(),
+  source: 'informer',
+  kind: 'Pod',
+  namespace: 'default',
+  name: id,
+  eventType: 'update',
+})
+
+describe('maxEventSeq (delta cursor)', () => {
+  it('returns the highest arrival number', () => {
+    expect(maxEventSeq([mk('a', 3, 0), mk('b', 7, 1000), mk('c', 5, 2000)])).toBe(7)
+  })
+
+  it('returns 0 for an empty page or seq-less events', () => {
+    expect(maxEventSeq([])).toBe(0)
+    expect(maxEventSeq([{ ...mk('a', 0, 0), seq: undefined }])).toBe(0)
+  })
+})
+
+describe('mergeDeltaEvents (delta page into cached page)', () => {
+  it('returns the cached reference untouched for an empty delta', () => {
+    const prev = [mk('a', 1, 0)]
+    expect(mergeDeltaEvents(prev, [], 100)).toBe(prev)
+  })
+
+  it('adds new arrivals in newest-first order', () => {
+    const prev = [mk('b', 2, 1000), mk('a', 1, 0)]
+    const merged = mergeDeltaEvents(prev, [mk('c', 3, 2000)], 100)
+    expect(merged.map((e) => e.id)).toEqual(['c', 'b', 'a'])
+  })
+
+  it('replaces a cached row when the same id re-arrives (K8s Event count bump)', () => {
+    const prev = [{ ...mk('bump', 1, 0), count: 1 }, mk('a', 2, 500)]
+    const merged = mergeDeltaEvents(prev, [{ ...mk('bump', 3, 1000), count: 5 }], 100)
+    expect(merged).toHaveLength(2)
+    expect(merged[0].id).toBe('bump')
+    expect(merged[0].count).toBe(5)
+  })
+
+  it('orders a late arrival by its timestamp, not its arrival number', () => {
+    const prev = [mk('b', 2, 2000), mk('a', 1, 1000)]
+    const merged = mergeDeltaEvents(prev, [mk('late', 3, 0)], 100)
+    expect(merged.map((e) => e.id)).toEqual(['b', 'a', 'late'])
+  })
+
+  it('caps the merged page by dropping the oldest', () => {
+    const prev = [mk('b', 2, 2000), mk('a', 1, 1000)]
+    const merged = mergeDeltaEvents(prev, [mk('c', 3, 3000)], 2)
+    expect(merged.map((e) => e.id)).toEqual(['c', 'b'])
+  })
+})
+
+describe('deltaFetchCursor (cursor selection incl. high-water)', () => {
+  const NOW = 1_700_000_000_000
+  const meta = (over: Partial<ChangesDeltaMeta> = {}): ChangesDeltaMeta => ({
+    epoch: 'e1',
+    lastFullMs: NOW - 10_000,
+    highWaterSeq: 0,
+    ...over,
+  })
+
+  it('requires an epoch-stamped prior load and a cached page', () => {
+    expect(deltaFetchCursor(undefined, [mk('a', 1, 0)], NOW)).toBe(0)
+    expect(deltaFetchCursor(meta({ epoch: '' }), [mk('a', 1, 0)], NOW)).toBe(0)
+    expect(deltaFetchCursor(meta(), undefined, NOW)).toBe(0)
+  })
+
+  it('forces a full resync once the anti-entropy interval elapses', () => {
+    expect(deltaFetchCursor(meta({ lastFullMs: NOW - 6 * 60_000 }), [mk('a', 1, 0)], NOW)).toBe(0)
+  })
+
+  it('uses the cached max seq in the ordinary case', () => {
+    expect(deltaFetchCursor(meta(), [mk('a', 7, 0), mk('b', 3, 1000)], NOW)).toBe(7)
+  })
+
+  it('does not regress when a capped-out delta event held the highest seq', () => {
+    // The seq-9 event was merged then dropped by the cap (oldest timestamp);
+    // cached rows top out at 7. The cursor must hold at the high water or the
+    // same delta gets re-downloaded on every refetch.
+    expect(deltaFetchCursor(meta({ highWaterSeq: 9 }), [mk('a', 7, 0)], NOW)).toBe(9)
+  })
+})

package/src/api/client.deltaSync.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { runDeltaSyncFetch, type ChangesDeltaMeta } from './client'
+import type { TimelineEvent } from '@skyhook-io/k8s-ui'
+
+// Orchestration test for the useChanges delta contract. The pure helpers
+// (deltaFetchCursor / mergeDeltaEvents / maxEventSeq) are covered in
+// client.delta.test.ts; here we drive the full runDeltaSyncFetch loop through
+// the real fetch boundary so the header parsing, cursor priming, epoch-resync,
+// and merge all participate.
+
+const BASE_TS = 1_700_000_000_000
+const mk = (id: string, seq: number, tsOffsetMs: number, extra: Partial<TimelineEvent> = {}): TimelineEvent => ({
+  id,
+  seq,
+  timestamp: new Date(BASE_TS + tsOffsetMs).toISOString(),
+  source: 'informer',
+  kind: 'Pod',
+  namespace: 'default',
+  name: id,
+  eventType: 'update',
+  ...extra,
+})
+
+// A page as the server returns it: an events body plus the two frontier headers
+// that fetchChangesPage reads to derive epoch + maxSeq.
+interface Page {
+  events: TimelineEvent[]
+  epoch: string
+  maxSeq: number
+}
+function pageResponse(page: Page): Response {
+  return new Response(JSON.stringify(page.events), {
+    status: 200,
+    headers: {
+      'X-Radar-Timeline-Epoch': page.epoch,
+      'X-Radar-Timeline-Max-Seq': String(page.maxSeq),
+    },
+  })
+}
+
+// The `since_seq` a fetched URL carries, or null for a full fetch.
+function sinceSeqOf(url: string): number | null {
+  const m = url.match(/[?&]since_seq=(\d+)/)
+  return m ? Number(m[1]) : null
+}
+
+let fetchedUrls: string[]
+let responder: (url: string) => Page
+
+beforeEach(() => {
+  fetchedUrls = []
+  vi.stubGlobal('fetch', (input: RequestInfo | URL) => {
+    const url = String(input)
+    fetchedUrls.push(url)
+    return Promise.resolve(pageResponse(responder(url)))
+  })
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+const PATH = '/changes?limit=200&filter=all'
+const QUERY_STRING = 'limit=200&filter=all'
+const LIMIT = 200
+const META_KEY = 'changes-key'
+
+// A single query's delta loop: fresh meta store per test, cached page threaded
+// forward across polls, an explicit `now` so the anti-entropy full-resync timer
+// stays out of the way unless a test wants it.
+function run(metaStore: Map<string, ChangesDeltaMeta>, cached: TimelineEvent[] | undefined, now: number) {
+  return runDeltaSyncFetch({ path: PATH, queryString: QUERY_STRING, limit: LIMIT, metaKey: META_KEY, cached, metaStore, now })
+}
+
+const lastUrl = () => fetchedUrls[fetchedUrls.length - 1]
+
+describe('runDeltaSyncFetch (useChanges delta orchestration)', () => {
+  it('first fetch (no cursor) is a full fetch; the cursor is primed from the max-seq header', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    // Header frontier 8 exceeds the highest visible event seq (5): rows dropped
+    // by the server's RBAC filter still advance the cursor.
+    responder = () => ({ events: [mk('a', 5, 2000), mk('b', 3, 1000)], epoch: 'e1', maxSeq: 8 })
+
+    const result = await run(metaStore, undefined, 1_000)
+
+    expect(fetchedUrls).toHaveLength(1)
+    expect(sinceSeqOf(fetchedUrls[0])).toBeNull()
+    expect(result.map((e) => e.id)).toEqual(['a', 'b'])
+
+    const meta = metaStore.get(META_KEY)!
+    expect(meta.epoch).toBe('e1')
+    expect(meta.highWaterSeq).toBe(8)
+    expect(meta.lastFullMs).toBe(1_000)
+  })
+
+  it('a subsequent poll sends since_seq=<cursor>, merges delta rows by id, and advances the cursor', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('a', 5, 2000), mk('b', 3, 1000)], epoch: 'e1', maxSeq: 5 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    // A new arrival (c) plus a re-arrival of 'a' under a higher seq (count bump).
+    responder = () => ({ events: [mk('c', 7, 3000), mk('a', 6, 2000, { count: 9 })], epoch: 'e1', maxSeq: 7 })
+    const second = await run(metaStore, first, 2_000)
+
+    expect(sinceSeqOf(lastUrl())).toBe(5)
+    expect(second.map((e) => e.id)).toEqual(['c', 'a', 'b'])
+    expect(second.find((e) => e.id === 'a')!.count).toBe(9)
+    expect(metaStore.get(META_KEY)!.highWaterSeq).toBe(7)
+  })
+
+  it('an empty delta carrying a max-seq header still advances the cursor', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('a', 5, 2000)], epoch: 'e1', maxSeq: 5 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    // The entire page past seq 5 was RBAC-filtered to nothing, but the server
+    // reports the frontier it scanned to.
+    responder = () => ({ events: [], epoch: 'e1', maxSeq: 12 })
+    const second = await run(metaStore, first, 2_000)
+    expect(metaStore.get(META_KEY)!.highWaterSeq).toBe(12)
+
+    // The next poll must ride the advanced cursor, not re-request from 5.
+    responder = () => ({ events: [], epoch: 'e1', maxSeq: 12 })
+    await run(metaStore, second, 3_000)
+    expect(sinceSeqOf(lastUrl())).toBe(12)
+  })
+
+  it('an empty delta returns the cached array reference (no needless re-render)', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('a', 5, 0)], epoch: 'e1', maxSeq: 5 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    responder = () => ({ events: [], epoch: 'e1', maxSeq: 5 })
+    const second = await run(metaStore, first, 2_000)
+    expect(second).toBe(first)
+  })
+
+  it('an epoch change between polls forces a full resync: cursor reset, list replaced', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('old', 9, 0)], epoch: 'e1', maxSeq: 9 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    // The store restarted — seq numbering reset low, so a since_seq=9 delta comes
+    // back EMPTY under a NEW epoch. Trusting that empty delta as "nothing new"
+    // would strand the caller on the previous store's rows; the epoch mismatch
+    // must instead trigger a full resync.
+    const restarted = [mk('fresh', 2, 500)]
+    responder = (url) =>
+      sinceSeqOf(url) != null
+        ? { events: [], epoch: 'e2', maxSeq: 2 }
+        : { events: restarted, epoch: 'e2', maxSeq: 2 }
+    const second = await run(metaStore, first, 2_000)
+
+    expect(second).not.toBe(first)
+    expect(second.map((e) => e.id)).toEqual(['fresh'])
+    // Two fetches: the epoch-mismatched delta probe, then the full resync.
+    expect(sinceSeqOf(fetchedUrls[fetchedUrls.length - 2])).toBe(9)
+    expect(sinceSeqOf(lastUrl())).toBeNull()
+
+    const meta = metaStore.get(META_KEY)!
+    expect(meta.epoch).toBe('e2')
+    expect(meta.highWaterSeq).toBe(2)
+    expect(meta.lastFullMs).toBe(2_000)
+  })
+
+  it('equivalence: full → delta → delta yields the same set as a fresh full fetch of the final state', async () => {
+    // A minimal append/replace server keyed by id with monotonic seq. Each fetch
+    // serializes a snapshot, so pages the loop keeps are decoupled from later
+    // mutations of the log.
+    const epoch = 'e1'
+    const log: TimelineEvent[] = []
+    let nextSeq = 1
+    const upsert = (id: string, tsOffsetMs: number, content: number) => {
+      const seq = nextSeq++
+      const existing = log.find((e) => e.id === id)
+      if (existing) {
+        existing.seq = seq
+        existing.count = content
+      } else {
+        log.push(mk(id, seq, tsOffsetMs, { count: content }))
+      }
+    }
+    const newestFirst = (rows: TimelineEvent[]) =>
+      [...rows].sort((a, b) => {
+        const byTime = new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+        return byTime !== 0 ? byTime : (b.seq ?? 0) - (a.seq ?? 0)
+      })
+    responder = (url) => {
+      const since = sinceSeqOf(url)
+      const rows = since == null ? log : log.filter((e) => (e.seq ?? 0) > since)
+      const maxSeq = log.reduce((m, e) => Math.max(m, e.seq ?? 0), 0)
+      return { events: newestFirst(rows), epoch, maxSeq }
+    }
+
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    upsert('a', 1000, 1)
+    upsert('b', 2000, 1)
+    upsert('c', 3000, 1)
+    const l1 = await run(metaStore, undefined, 1_000)
+
+    upsert('d', 4000, 1)
+    upsert('a', 1000, 2) // a count bump re-arrives under the same id
+    const l2 = await run(metaStore, l1, 2_000)
+
+    upsert('e', 5000, 1)
+    upsert('b', 2000, 2)
+    const l3 = await run(metaStore, l2, 3_000)
+
+    // What a fresh client would get from a single full fetch of the final state.
+    const fresh = newestFirst(log)
+    const asSet = (rows: TimelineEvent[]) => rows.map((e) => `${e.id}:${e.count}`).sort()
+    expect(asSet(l3)).toEqual(asSet(fresh))
+    // No dropped or duplicated ids after two incremental merges.
+    expect(l3).toHaveLength(fresh.length)
+  })
+})