@skyhook-io/radar-app 1.16.3 → 1.17.1

package/src/components/cnpg/runtimeModel.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest'
+import type { CNPGRuntimeInstance, CNPGRuntimeReplication } from '../../api/cnpg'
+import type { CNPGSessionsResponse } from '../../api/cnpg-sessions'
+import { cnpgCheckpointView, cnpgDatabaseHealthRows, cnpgNoStandbyText, cnpgIdAge, cnpgStandbyBacklogTone, cnpgPickedInstance, cnpgSessionAggregatesGap, cnpgSessionsCardShowsConnections, cnpgStandbyHeadline, cnpgTransactionRates } from './runtimeModel'
+
+describe('cnpgCheckpointView', () => {
+  it('flags requested-checkpoint pressure only with enough checkpoints', () => {
+    expect(cnpgCheckpointView({ source: 'pg_stat_checkpointer', timed: 2, requested: 8 }, 'primary')).toMatchObject({ total: 10, requestedShare: 0.8, pressure: true })
+    expect(cnpgCheckpointView({ source: 'pg_stat_checkpointer', timed: 1, requested: 3 }, 'primary').pressure).toBe(false)
+    expect(cnpgCheckpointView({ source: 'pg_stat_checkpointer', timed: 1, requested: 2 }, 'primary').share).toBeUndefined()
+    expect(cnpgCheckpointView({ source: 'pg_stat_checkpointer', timed: 2, requested: 8 }, 'primary').share).toBe('80 %')
+    expect(cnpgCheckpointView({ source: 'pg_stat_bgwriter', timed: 5 }, 'primary').requestedShare).toBeUndefined()
+  })
+  it('shows restartpoints for standbys on PostgreSQL 17+, never from pg_stat_bgwriter', () => {
+    expect(cnpgCheckpointView({ source: 'pg_stat_checkpointer', restartpointsDone: 0 }, 'replica').showRestartpoints).toBe(true)
+    expect(cnpgCheckpointView({ source: 'pg_stat_checkpointer', restartpointsDone: 0 }, 'primary').showRestartpoints).toBe(false)
+    expect(cnpgCheckpointView({ source: 'pg_stat_bgwriter' }, 'replica').showRestartpoints).toBe(false)
+  })
+})
+
+describe('cnpgDatabaseHealthRows', () => {
+  it('joins per-database counters and ages by name and keeps unreported values unknown', () => {
+    const rows = cnpgDatabaseHealthRows({
+      state: 'ok',
+      databases: [
+        { database: 'app', xactCommit: 90, xactRollback: 10, tempFiles: 2, tempBytes: 4096 },
+        { database: 'idle', xactCommit: 0, xactRollback: 0 },
+        { database: 'noroll', xactCommit: 5 },
+      ],
+      xidAge: [{ database: 'app', age: 100 }],
+      mxidAge: [{ database: 'postgres', age: 7 }],
+    })
+    expect(rows.map((r) => r.database)).toEqual(['app', 'idle', 'noroll', 'postgres'])
+    expect(rows[0]).toEqual({ database: 'app', rollbackRatio: 0.1, tempFiles: 2, tempBytes: 4096, xidAge: 100 })
+    expect(rows[1].rollbackRatio).toBeUndefined()
+    expect(rows[1].noTransactions).toBe(true)
+    expect(rows[2].rollbackRatio).toBeUndefined()
+    expect(rows[2].noTransactions).toBeUndefined()
+    expect(rows[3]).toEqual({ database: 'postgres', mxidAge: 7 })
+  })
+})
+
+describe('standby cards', () => {
+  const standby = (status: Partial<CNPGRuntimeInstance['status']>) => ({ pod: 'pg-2', role: 'replica', status: { state: 'ok', ...status } }) as unknown as CNPGRuntimeInstance
+  const rep = { applicationName: 'pg-2', state: 'streaming', syncState: 'async' } as CNPGRuntimeReplication
+
+  it('rates replay delay on the Replication fact scale', () => {
+    expect(cnpgStandbyBacklogTone(0, 2)).toBe('healthy')
+    expect(cnpgStandbyBacklogTone(0, 8)).toBe('degraded')
+    expect(cnpgStandbyBacklogTone(0, 72)).toBe('unhealthy')
+    expect(cnpgStandbyBacklogTone(2 * 1024 ** 3, 0)).toBe('unhealthy')
+    expect(cnpgStandbyBacklogTone(undefined, 72)).toBe('unhealthy')
+    expect(cnpgStandbyBacklogTone(undefined, 8)).toBe('degraded')
+    expect(cnpgStandbyBacklogTone(undefined, 0)).toBe('unknown')
+    expect(cnpgStandbyBacklogTone(undefined, undefined)).toBe('unknown')
+  })
+
+  it('leads with a paused replay, keeping the streaming state secondary', () => {
+    expect(cnpgStandbyHeadline(standby({ roleDetail: 'replayPaused' }), rep, 'healthy', { fenced: false, primaryRead: true })).toEqual({
+      text: 'replay paused',
+      tone: 'degraded',
+      secondary: 'streaming · async',
+    })
+    expect(cnpgStandbyHeadline(standby({ replayPaused: true }), rep, 'unhealthy', { fenced: false, primaryRead: true }).tone).toBe('unhealthy')
+    expect(cnpgStandbyHeadline(standby({ roleDetail: 'streaming' }), rep, 'healthy', { fenced: false, primaryRead: true })).toEqual({ text: 'streaming · async', tone: 'healthy' })
+  })
+
+  it('says a fenced instance stopped only when the instance manager reports it', () => {
+    const fenced = { fenced: true, primaryRead: true }
+    expect(cnpgStandbyHeadline(standby({ state: 'unreachable', error: 'instance is fenced: (PostgreSQL is not running on this instance)' }), undefined, 'unknown', fenced).text).toBe('fenced · PostgreSQL not running')
+    expect(cnpgStandbyHeadline(standby({ state: 'denied' }), undefined, 'unknown', fenced).text).toBe('fenced · shutdown unverified')
+    expect(cnpgStandbyHeadline(standby({ state: 'ok' }), undefined, 'unknown', fenced).text).toBe('fenced · PostgreSQL still answering')
+  })
+
+  it('says a paused standby is not connected when the primary has no row for it', () => {
+    expect(cnpgStandbyHeadline(standby({ replayPaused: true }), undefined, 'unhealthy', { fenced: false, primaryRead: true })).toEqual({
+      text: 'replay paused',
+      tone: 'unhealthy',
+      secondary: 'not connected to the primary',
+    })
+    expect(cnpgStandbyHeadline(standby({ replayPaused: true }), undefined, 'unknown', { fenced: false, primaryRead: false }).secondary).toBeUndefined()
+  })
+})
+
+describe('cnpgTransactionRates', () => {
+  const p = (value: number, at: number, stale = false) => ({ value, at, stale })
+  it('prefers a current Prometheus rate, with its time', () => {
+    expect(cnpgTransactionRates({ commits: p(12.34, 100), rollbacks: p(0.5, 100) }, { commits: 3 }, 'primary only')).toEqual({
+      source: 'prometheus',
+      commits: '12.3',
+      rollbacks: '0.5',
+      at: 100,
+    })
+  })
+  it('never shows a stopped Prometheus series as current', () => {
+    expect(cnpgTransactionRates({ commits: p(12, 100, true), rollbacks: undefined }, { commits: 3 }, 'primary only')).toMatchObject({ source: 'sampled', commits: '3.0' })
+    expect(cnpgTransactionRates({ commits: p(12, 100, true), rollbacks: undefined }, null, 'primary only')).toEqual({
+      source: 'none',
+      commits: 'no recent sample',
+      rollbacks: 'no recent sample',
+      at: 100,
+    })
+  })
+  it('shows Prometheus rates without exporter access, and says why when there is neither', () => {
+    expect(cnpgTransactionRates({ commits: p(4, 1), rollbacks: p(0, 1) }, null, 'needs get pods/proxy')).toMatchObject({ source: 'prometheus', commits: '4.0' })
+    expect(cnpgTransactionRates({ commits: undefined, rollbacks: undefined }, null, 'needs get pods/proxy')).toMatchObject({ source: 'none', commits: 'needs get pods/proxy' })
+  })
+})
+
+describe('Sessions instance and aggregates', () => {
+  const inst = (pod: string, role: string, metrics: Record<string, unknown> = { state: 'ok', sessionsTotal: 3 }) => ({ pod, role, status: { state: 'ok' }, metrics }) as unknown as CNPGRuntimeInstance
+  it('keeps standbys pickable when no primary is reported', () => {
+    const standbys = [inst('pg-2', 'replica'), inst('pg-3', 'replica')]
+    expect(cnpgPickedInstance(standbys, null)?.pod).toBe('pg-2')
+    expect(cnpgPickedInstance([inst('pg-1', 'primary'), ...standbys], null)?.pod).toBe('pg-1')
+    expect(cnpgPickedInstance([inst('pg-1', 'primary'), ...standbys], 'pg-3')?.pod).toBe('pg-3')
+  })
+  it('counts the aggregates as present only when sessions were measured', () => {
+    expect(cnpgSessionAggregatesGap(inst('pg-1', 'primary'))).toBeUndefined()
+    expect(cnpgSessionAggregatesGap(inst('pg-1', 'primary', { state: 'ok' }))).toBe('the metrics exporter on pg-1 reported no session counts')
+    expect(cnpgSessionAggregatesGap(inst('pg-1', 'primary', { state: 'unreachable', error: 'x' }))).toBe('the metrics exporter on pg-1 did not answer (x)')
+  })
+})
+
+describe('cnpgSessionsCardShowsConnections', () => {
+  const inst = (metrics: Record<string, unknown>) => ({ pod: 'pg-1', role: 'primary', status: { state: 'ok' }, metrics }) as unknown as CNPGRuntimeInstance
+  const exec = { pod: 'pg-1', state: 'ok', maxConnections: 100, superuserReservedConnections: 3, clientBackends: 91 } as unknown as CNPGSessionsResponse
+  it('shows headroom once: in the card when it has a figure, otherwise in Blocking', () => {
+    expect(cnpgSessionsCardShowsConnections(inst({ state: 'ok' }), exec)).toBe(true)
+    expect(cnpgSessionsCardShowsConnections(inst({ state: 'ok', sessionsTotal: 5 }), undefined)).toBe(true)
+    expect(cnpgSessionsCardShowsConnections(inst({ state: 'ok' }), undefined)).toBe(false)
+    expect(cnpgSessionsCardShowsConnections(inst({ state: 'unreachable' }), exec)).toBe(false)
+  })
+})
+
+describe('cnpgIdAge', () => {
+  it('reads as a count with k / M / B and never shows a non-zero age as zero', () => {
+    expect(cnpgIdAge(0)).toBe('0')
+    expect(cnpgIdAge(812)).toBe('812')
+    expect(cnpgIdAge(1_234)).toBe('1.2k')
+    expect(cnpgIdAge(45_000)).toBe('45k')
+    expect(cnpgIdAge(3_400_000)).toBe('3.4 M')
+    expect(cnpgIdAge(1_100_000_000)).toBe('1.1 B')
+    expect(cnpgIdAge(12)).not.toBe('0 M')
+  })
+})
+
+describe('cnpgNoStandbyText', () => {
+  it('calls a one-instance cluster single, a larger one short of standbys, and claims neither unread', () => {
+    expect(cnpgNoStandbyText(1)).toBe('Single instance: no replica to fail over to.')
+    expect(cnpgNoStandbyText(2)).toBe('No standby is running: spec.instances is 2, so one standby is expected. Nothing to fail over to until one joins.')
+    expect(cnpgNoStandbyText(3)).toContain('2 standbys are expected')
+    expect(cnpgNoStandbyText(undefined)).toBe('No standby is running.')
+  })
+})
+
+it('keeps the measured connections in Sessions when only its row lists were capped', () => {
+  const inst = { pod: 'pg-1', metrics: { state: 'partial', reason: 'sessions capped', sessionsTotal: 150 } } as CNPGRuntimeInstance
+  expect(cnpgSessionAggregatesGap(inst)).toBeUndefined()
+  expect(cnpgSessionsCardShowsConnections(inst, undefined)).toBe(true)
+})
+
+it('does not treat a captured empty or failed read as a measurement', async () => {
+  const { cnpgRuntimeMeasured } = await import('./runtimeModel')
+  const instance = { pod: 'pg-1', role: 'primary', status: { state: 'ok', capturedAt: 'now' }, metrics: { state: 'ok', capturedAt: 'now', databases: [] } } as CNPGRuntimeInstance
+  expect(cnpgRuntimeMeasured([], 'metrics')).toBe(false)
+  expect(cnpgRuntimeMeasured([instance], 'status')).toBe(false)
+  expect(cnpgRuntimeMeasured([instance], 'metrics')).toBe(false)
+  instance.metrics.sessionsTotal = 0
+  expect(cnpgRuntimeMeasured([instance], 'metrics')).toBe(true)
+  instance.status.slots = []
+  expect(cnpgRuntimeMeasured([instance], 'status')).toBe(true)
+  instance.metrics.state = 'error'
+  expect(cnpgRuntimeMeasured([instance], 'metrics')).toBe(false)
+})

package/src/components/cnpg/runtimeModel.ts

@@ -0,0 +1,196 @@
+import { cnpgLagTone, worseTone, type HealthLevel } from '@skyhook-io/k8s-ui'
+import type { CNPGRuntimeInstance, CNPGRuntimeReplication } from '../../api/cnpg'
+import type { CNPGSessionsResponse } from '../../api/cnpg-sessions'
+import { cnpgConnectionFigure } from './blocking'
+
+type Checkpoints = NonNullable<CNPGRuntimeInstance['metrics']['checkpoints']>
+
+/**
+ * How to read one instance's checkpoint counters. Restartpoints exist as
+ * their own counters only in pg_stat_checkpointer (PostgreSQL 17+), and matter
+ * on a standby or where any were done. Pressure needs enough checkpoints for
+ * the requested share to mean something.
+ */
+const CNPG_CHECKPOINT_SHARE_MIN = 10
+
+export function cnpgCheckpointView(c: Checkpoints, role: CNPGRuntimeInstance['role']) {
+  const total = c.timed !== undefined && c.requested !== undefined ? c.timed + c.requested : undefined
+  const requestedShare = total ? (c.requested as number) / total : undefined
+  const few = total !== undefined && total < CNPG_CHECKPOINT_SHARE_MIN
+  return {
+    total,
+    requestedShare,
+    // Too few checkpoints for a share to mean anything; the counts beside it say it all.
+    share: requestedShare === undefined || few ? undefined : `${(requestedShare * 100).toFixed(0)} %`,
+    pressure: requestedShare !== undefined && !few && requestedShare > 0.5,
+    showRestartpoints: c.source === 'pg_stat_checkpointer' && (role !== 'primary' || !!c.restartpointsDone),
+  }
+}
+
+export interface CNPGDatabaseHealthRow {
+  database: string
+  /** rollbacks / (commits + rollbacks); undefined when either is unreported or there were none. */
+  rollbackRatio?: number
+  /** Commits and rollbacks were both reported and both zero, so there is no ratio to show. */
+  noTransactions?: boolean
+  tempFiles?: number
+  tempBytes?: number
+  xidAge?: number
+  mxidAge?: number
+}
+
+/** One row per database any family names; a value a family did not report stays undefined. */
+export function cnpgDatabaseHealthRows(m: CNPGRuntimeInstance['metrics']): CNPGDatabaseHealthRow[] {
+  const rows = new Map<string, CNPGDatabaseHealthRow>()
+  const row = (database: string) => {
+    let r = rows.get(database)
+    if (!r) rows.set(database, (r = { database }))
+    return r
+  }
+  for (const d of m.databases ?? []) {
+    const r = row(d.database)
+    if (d.xactCommit !== undefined && d.xactRollback !== undefined) {
+      if (d.xactCommit + d.xactRollback > 0) r.rollbackRatio = d.xactRollback / (d.xactCommit + d.xactRollback)
+      else r.noTransactions = true
+    }
+    r.tempFiles = d.tempFiles
+    r.tempBytes = d.tempBytes
+  }
+  for (const x of m.xidAge ?? []) row(x.database).xidAge = x.age
+  for (const x of m.mxidAge ?? []) row(x.database).mxidAge = x.age
+  return [...rows.values()].sort((a, b) => a.database.localeCompare(b.database))
+}
+
+// 16 MiB is one WAL segment: a standby a segment or more behind is visibly
+// catching up, not just between acknowledgements.
+export const CNPG_BACKLOG_DEGRADED = 16 * 1024 * 1024
+const CNPG_BACKLOG_UNHEALTHY = 1024 * 1024 * 1024
+
+/** A standby's catch-up tone: the worse of its byte backlog and replay delay, the delay on the same scale as the cluster's Replication fact. */
+export function cnpgStandbyBacklogTone(bytes: number | undefined, replayLag: number | undefined): HealthLevel {
+  if (bytes === undefined) return replayLag === undefined ? 'unknown' : worseTone('unknown', cnpgLagTone(replayLag))
+  const byBytes: HealthLevel = bytes >= CNPG_BACKLOG_UNHEALTHY ? 'unhealthy' : bytes >= CNPG_BACKLOG_DEGRADED ? 'degraded' : 'healthy'
+  return replayLag === undefined ? byBytes : worseTone(byBytes, cnpgLagTone(replayLag))
+}
+
+export interface CNPGStandbyHeadline {
+  text: string
+  tone: HealthLevel
+  /** The streaming state when the headline says something more pressing. */
+  secondary?: string
+}
+
+/**
+ * What a standby card leads with. A paused replay leads: the standby keeps
+ * streaming and receiving WAL, so "streaming" alone reads as healthy while
+ * nothing is being applied.
+ */
+export function cnpgStandbyHeadline(
+  inst: CNPGRuntimeInstance,
+  rep: CNPGRuntimeReplication | undefined,
+  backlogTone: HealthLevel,
+  ctx: { fenced: boolean; primaryRead: boolean },
+): CNPGStandbyHeadline {
+  const streaming = rep ? [rep.state, rep.syncState].filter(Boolean).join(' · ') : undefined
+  if (inst.status.roleDetail === 'replayPaused' || inst.status.replayPaused) {
+    const secondary = streaming ?? (ctx.primaryRead && !ctx.fenced ? 'not connected to the primary' : undefined)
+    return { text: 'replay paused', tone: worseTone('degraded', backlogTone), secondary }
+  }
+  if (streaming !== undefined) return { text: streaming, tone: backlogTone }
+  // The fence asks the operator to stop PostgreSQL; only the instance manager
+  // reporting it down confirms the shutdown.
+  if (ctx.fenced) {
+    if (inst.status.state === 'ok') return { text: 'fenced · PostgreSQL still answering', tone: 'unknown' }
+    if (/PostgreSQL is not running/.test(inst.status.error ?? '')) return { text: 'fenced · PostgreSQL not running', tone: 'unknown' }
+    return { text: 'fenced · shutdown unverified', tone: 'unknown' }
+  }
+  if (inst.role === 'unknown') return { text: 'role unknown', tone: 'unknown' }
+  // A standby the primary reports no row for receives nothing: a concern, not an unknown.
+  return ctx.primaryRead ? { text: 'not connected to the primary', tone: 'degraded' } : { text: 'unknown', tone: 'unknown' }
+}
+
+type PromLatest = { value: number; at: number; stale: boolean } | undefined
+
+export interface CNPGTransactionRates {
+  /** prometheus: cluster-wide, from history; sampled: the primary's, sampled by this page; none: neither is current. */
+  source: 'prometheus' | 'sampled' | 'none'
+  commits: string
+  rollbacks: string
+  /** Unix seconds of the Prometheus point shown, or of the last one when it is no longer recent. */
+  at?: number
+}
+
+/**
+ * Commit and rollback rates for the Transactions card. A current Prometheus
+ * rate wins; otherwise the page's own sampling when it can sample
+ * (`sampled` is null when it cannot: not the primary, or no exporter access);
+ * a Prometheus series that stopped is reported as such, never as current.
+ */
+export function cnpgTransactionRates(
+  prom: { commits: PromLatest; rollbacks: PromLatest },
+  sampled: { commits?: number; rollbacks?: number } | null,
+  cannotSample: string,
+): CNPGTransactionRates {
+  const fresh = [prom.commits, prom.rollbacks].filter((p) => p && !p.stale) as NonNullable<PromLatest>[]
+  if (fresh.length) {
+    const text = (p: PromLatest) => (p && !p.stale ? p.value.toFixed(1) : '—')
+    return { source: 'prometheus', commits: text(prom.commits), rollbacks: text(prom.rollbacks), at: Math.min(...fresh.map((p) => p.at)) }
+  }
+  if (sampled) {
+    const text = (v?: number) => (v !== undefined ? v.toFixed(1) : 'collecting…')
+    return { source: 'sampled', commits: text(sampled.commits), rollbacks: text(sampled.rollbacks) }
+  }
+  const stale = [prom.commits, prom.rollbacks].filter(Boolean) as NonNullable<PromLatest>[]
+  if (stale.length) return { source: 'none', commits: 'no recent sample', rollbacks: 'no recent sample', at: Math.max(...stale.map((p) => p.at)) }
+  return { source: 'none', commits: cannotSample, rollbacks: cannotSample }
+}
+
+/** The instance Sessions and Transactions read: the one in the URL, else the primary, else the first, so standbys stay reachable without a primary. */
+export function cnpgPickedInstance(instances: CNPGRuntimeInstance[], param: string | null): CNPGRuntimeInstance | undefined {
+  return instances.find((i) => i.pod === param) ?? instances.find((i) => i.role === 'primary') ?? instances[0]
+}
+
+/** Why the exporter's session counts are not shown, or undefined when they were measured. */
+export function cnpgSessionAggregatesGap(inst: CNPGRuntimeInstance | undefined): string | undefined {
+  if (!inst) return 'no instance is reported'
+  const m = inst.metrics
+  if (m.state !== 'ok' && m.state !== 'partial') return `the metrics exporter on ${inst.pod} did not answer${m.error ? ` (${m.error})` : ''}`
+  if (m.sessionsTotal === undefined) return `the metrics exporter on ${inst.pod} reported no session counts`
+  return undefined
+}
+
+/** Whether the Sessions card shows the connections figure, so the Blocking panel does not repeat it. */
+export function cnpgSessionsCardShowsConnections(inst: CNPGRuntimeInstance | undefined, exec: CNPGSessionsResponse | undefined): boolean {
+  return (inst?.metrics.state === 'ok' || inst?.metrics.state === 'partial') && cnpgConnectionFigure(exec, inst.metrics) !== undefined
+}
+
+/** A transaction or multixact ID age as a readable count: 812, 1.2k, 45k, 3.4 M, 1.1 B. A non-zero age never reads as zero. */
+export function cnpgIdAge(v: number): string {
+  const unit = (n: number, d: number, s: string) => {
+    const x = n / d
+    return `${x < 10 ? x.toFixed(1).replace(/\.0$/, '') : Math.round(x)}${s}`
+  }
+  if (v < 1_000) return String(v)
+  if (v < 1_000_000) return unit(v, 1_000, 'k')
+  if (v < 1_000_000_000) return unit(v, 1_000_000, ' M')
+  return unit(v, 1_000_000_000, ' B')
+}
+
+/** Why no standby is listed: a one-instance cluster has none, a larger one is missing them. */
+export function cnpgNoStandbyText(desired: unknown): string {
+  if (typeof desired !== 'number') return 'No standby is running.'
+  if (desired <= 1) return 'Single instance: no replica to fail over to.'
+  const expected = desired - 1
+  return `No standby is running: spec.instances is ${desired}, so ${expected === 1 ? 'one standby is' : `${expected} standbys are`} expected. Nothing to fail over to until one joins.`
+}
+
+export function cnpgRuntimeMeasured(instances: CNPGRuntimeInstance[], source: 'status' | 'metrics'): boolean {
+  return instances.some((instance) => {
+    const report = instance[source]
+    if (report.state !== 'ok' && report.state !== 'partial') return false
+    if (source === 'status') return instance.status.currentLsn !== undefined || instance.status.replayLsn !== undefined || instance.status.timeline !== undefined || instance.status.slots != null
+    return Object.values(instance.metrics).some((value) => typeof value === 'number')
+      || !!instance.metrics.databases?.length || !!instance.metrics.sessions?.length
+      || !!instance.metrics.databaseSizes?.length || instance.metrics.extensionUpdates != null || instance.metrics.checkpoints !== undefined
+  })
+}

package/src/components/cnpg/runtimeParts.test.tsx

@@ -0,0 +1,17 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { expect, it } from 'vitest'
+import { Denied, ProxyDenied } from './runtimeParts'
+
+it('uses the same full-width padding and grant layout for proxy and exec denials', () => {
+  const proxy = renderToStaticMarkup(<ProxyDenied what="Sessions" grant="get pods/proxy in namespace db" />)
+  const exec = renderToStaticMarkup(<Denied title="No access to blocking detail" grant="create pods/exec in namespace db">Blocking is unavailable.</Denied>)
+  const shell = (html: string) => html.match(/^<div class="([^"]+)"/)?.[1]
+  expect(shell(proxy)).toBe(shell(exec))
+  expect(shell(proxy)).toContain('w-full')
+  expect(shell(proxy)).toContain('p-4')
+  for (const html of [proxy, exec]) {
+    expect(html).not.toContain('max-w-2xl')
+    expect(html).toContain('requires:')
+    expect(html).toContain('break-words')
+  }
+})

package/src/components/cnpg/runtimeParts.tsx

@@ -0,0 +1,79 @@
+import type { ReactNode } from 'react'
+import { clsx } from 'clsx'
+import { Lock } from 'lucide-react'
+import { toneTextClass } from '@skyhook-io/k8s-ui'
+import { useLocation } from 'react-router-dom'
+import { useCNPGNavigate } from './useCNPGNavigate'
+import { cnpgClusterProblemsPath, cnpgWithinDetail } from './paths'
+import type { CNPGRuntimeInstance } from '../../api/cnpg'
+
+export function seconds(s?: number): string {
+  if (s === undefined) return '—'
+  if (s < 1) return `${(s * 1000).toFixed(0)} ms`
+  if (s < 90) return `${s.toFixed(1)} s`
+  if (s < 5400) return `${Math.round(s / 60)} min`
+  return `${(s / 3600).toFixed(1)} h`
+}
+
+export function SourceState({ label, state, error, reason }: { label: string; state: string; error?: string; reason?: string }) {
+  if (state === 'ok') return null
+  const detail = [reason, error].filter(Boolean).join(' · ')
+  const text =
+    state === 'denied'
+      ? `${label}: no access (needs get pods/proxy)`
+      : state === 'partial'
+        ? `${label}: partial${detail ? ` · ${detail}` : ''}`
+        : `${label}: ${state}${detail ? ` · ${detail}` : ''}`
+  return <div className="text-xs text-theme-text-tertiary">{text}</div>
+}
+
+// Denied is not zero: the section says what it would show and the grant it needs.
+export function ProxyDenied({ what, grant }: { what: string; grant: string }) {
+  return <Denied title="No access to live instance data" grant={grant}>
+    {what} are read from each instance through the Kubernetes API proxy, which your identity may not use. These readings are unavailable.
+  </Denied>
+}
+
+export function Denied({ title, grant, children }: { title: string; grant: string; children: ReactNode }) {
+  return <div className="w-full rounded-xl border border-dashed border-theme-border p-4">
+    <div className="flex items-center gap-2 text-sm font-medium text-theme-text-primary"><Lock className="h-4 w-4 shrink-0" />{title}</div>
+    <p className="mt-2 text-sm text-theme-text-secondary">{children}</p>
+    <div className="mt-2 break-words rounded-md bg-theme-elevated px-3 py-2 font-mono text-xs text-theme-text-primary">requires: {grant}</div>
+  </div>
+}
+
+export function PrimaryPrerequisite({ namespace, cluster }: { namespace: string; cluster: string }) {
+  const navigate = useCNPGNavigate()
+  const location = useLocation()
+  const overviewPath = `${cnpgClusterProblemsPath(namespace, cluster, new URLSearchParams(location.search).get('ctx') ?? undefined)}&tab=overview`
+  const inPlace = cnpgWithinDetail(location.pathname, location.search, overviewPath)
+  return <div className="text-sm text-theme-text-tertiary">Available once the primary is running. <button type="button" className="text-accent-text hover:underline" onClick={() => navigate(inPlace ?? overviewPath, { replace: !!inPlace, state: location.state })}>See Overview →</button></div>
+}
+
+export function Card({ title, children, footer, aside }: { title: ReactNode; children: ReactNode; footer?: ReactNode; aside?: ReactNode }) {
+  return (
+    <section className="overflow-hidden rounded-xl border border-theme-border bg-theme-surface shadow-theme-sm">
+      <div className="flex flex-wrap items-center gap-x-3 gap-y-1 border-b border-theme-border px-4 py-2.5">
+        <div className="text-sm font-semibold text-theme-text-primary">{title}</div>
+        {aside && <div className="ml-auto text-xs">{aside}</div>}
+      </div>
+      <div className="p-4">{children}</div>
+      {footer && <div className="border-t border-theme-border px-4 py-2 text-xs text-theme-text-tertiary">{footer}</div>}
+    </section>
+  )
+}
+
+export function Unavailable({ inst, what }: { inst?: CNPGRuntimeInstance; what: string }) {
+  if (!inst) return <div className="text-sm text-theme-text-tertiary">No instance is reported, so {what} is unknown.</div>
+  return <SourceState label={what} state={inst.metrics.state} error={inst.metrics.error} reason={inst.metrics.reason} />
+}
+
+export function Metric({ label, value, tone, caption }: { label: string; value: ReactNode; tone?: 'degraded' | 'unhealthy'; caption?: ReactNode }) {
+  return (
+    <div>
+      <div className="text-xs text-theme-text-tertiary">{label}</div>
+      <div className={clsx('font-mono text-base', tone ? toneTextClass(tone) : 'text-theme-text-primary')}>{value}</div>
+      {caption && <div className="text-[11px] text-theme-text-tertiary">{caption}</div>}
+    </div>
+  )
+}

package/src/components/cnpg/shared.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { expect, it, vi } from 'vitest'
+import { CNPGScreenGate, CoverageNotice } from './shared'
+import { buildCNPGFleet, CNPG_WORKSPACE_KEYS, type CNPGWorkspaceResponse } from '@skyhook-io/k8s-ui'
+vi.mock('../../context/ConnectionContext', () => ({ useConnection: () => ({ connection: { context: 'test' } }) }))
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true })
+it('retries an initial failure, disables duplicate retries and shows recovered data', async () => {
+  const refetch = vi.fn(async () => ({}))
+  const query = { isLoading: false, isFetching: false, error: new Error('Connection timed out'), refetch } as any
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  const root = createRoot(host)
+  const render = () => root.render(<CNPGScreenGate query={query} fleet={{} as any}>{() => <span>recovered workspace</span>}</CNPGScreenGate>)
+  await act(async () => render())
+  expect(host.textContent).toContain('Connection timed out')
+  await act(async () => host.querySelector('button')!.click())
+  expect(refetch).toHaveBeenCalledOnce()
+  query.isFetching = true
+  await act(async () => render())
+  expect(host.querySelector('button')!.disabled).toBe(true)
+  expect(host.textContent).toContain('Retrying…')
+  query.data = { installed: true }
+  query.isFetching = false
+  await act(async () => render())
+  expect(host.textContent).toContain('recovered workspace')
+  expect(host.textContent).not.toContain('CloudNativePG data unavailable')
+  act(() => root.unmount())
+  host.remove()
+})
+it('keeps workspace data with its failed-refresh reason and age', () => {
+  const query = { data: { installed: true }, isRefetchError: true, error: new Error('Workspace timeout'), dataUpdatedAt: Date.now() - 120_000 } as any
+  const html = renderToStaticMarkup(<CNPGScreenGate query={query} fleet={{} as any}>{() => <span>retained Cluster</span>}</CNPGScreenGate>)
+  expect(html).toContain('retained Cluster')
+  expect(html).toContain('Last refresh failed: Workspace timeout')
+  expect(html).toContain('2m ago')
+})
+
+it('scopes unread kinds to the screen and its namespace, with details folded', () => {
+  const data: CNPGWorkspaceResponse = { installed: true, context: 'test', namespaces: null, objects: {}, coverage: { ...Object.fromEntries(CNPG_WORKSPACE_KEYS.map((k) => [k, { state: 'full' as const }])), backups: { state: 'partial', allowedNamespaces: ['prod'], deniedNamespaces: ['staging'] }, clusterImageCatalogs: { state: 'uncached' } }, issues: [], audit: [], backupsOmitted: 0, jobCoverage: { state: 'denied' } }
+  const fleet = buildCNPGFleet(data)
+  const html = renderToStaticMarkup(<CoverageNotice data={data} fleet={fleet} kinds={['backups', 'scheduledBackups', 'objectStores']} />)
+  expect(html).toContain('Some data used on this screen was not read.')
+  expect(html).toContain('Backup (no access in staging)')
+  expect(html).toContain('aria-expanded="false"')
+  expect(html).not.toContain('ClusterImageCatalog')
+  expect(html).not.toContain('Job (')
+  expect(renderToStaticMarkup(<CoverageNotice data={data} fleet={fleet} kinds={['backups']} namespace="prod" />)).toBe('')
+})
+
+it('identifies coverage the server did not report without claiming the kind is absent', () => {
+  const data: CNPGWorkspaceResponse = { installed: true, context: 'test', namespaces: null, objects: {}, coverage: Object.fromEntries(CNPG_WORKSPACE_KEYS.filter(k => k !== 'databaseRoles').map(k => [k, { state: 'full' as const }])), issues: [], audit: [], backupsOmitted: 0 }
+  const fleet = buildCNPGFleet(data)
+  const html = renderToStaticMarkup(<CoverageNotice data={data} fleet={fleet} kinds={['databaseRoles']} />)
+  expect(html).toContain('DatabaseRole (not read by this Radar)')
+  expect(html).toContain('Counts over incomplete data are lower bounds')
+})