Files
Alaister Young 928049ce2c [FE-3717] feat(studio): Multigres cluster topology diagram (#49298)
Adds an infrastructure/topology diagram for High Availability
(Multigres) projects showing the real cluster topology — gateway tier,
shard group, and the primary + read replicas inside it — on both the
project homepage and the database/replication page, replacing the
primary-only view and the "Replication unavailable" empty state.

<img width="790" height="541" alt="Screenshot 2026-08-20 at 8 23 42 PM"
src="https://github.com/user-attachments/assets/0bce21e3-2091-4285-84ca-60fdecb10d39"
/>

Addresses
[FE-3717](https://linear.app/supabase/issue/FE-3717/show-replicas-in-replication-diagram).

**Added:**

- `data/ha-admin/` — read-only queries for the mgmt-api
`/ha-admin/v1/{gateways,poolers,cells,databases}` multiadmin passthrough
(ported from `bobbie/ha-stub`, re-authored to `queryOptions`). Responses
are validated with zod at the fetch boundary (all fields optional per
proto3 zero-value omission; enum-shaped fields stay plain strings so new
proto values degrade gracefully); malformed payloads surface through the
diagram's error fallback.
- `HaTopology.utils.ts` — pure topology mapper (+ 26 unit tests): shard
grouping, primary identified via `routingState.role` (deprecated `type`
as fallback) with **failover-safe election** — when the outgoing and
incoming primary briefly both claim `ROUTING_ROLE_PRIMARY`, the highest
routing rule (coordinator term, leader subterm) wins, matching the
multigateway's own election — plus status mapping onto the existing
Healthy / Coming up / Going down / Unhealthy vocabulary, and an AZ
formatter for `id.cell` that degrades to the raw cell name.
- HA diagram nodes/edges: `Multigateway` card, shard group box with
header pill (`Shard 1`, `Automatic failover` + tooltip), `Primary
Database` card styled like the standard diagram's — neutral border,
green icon chip (with the standard CPU / Disk / RAM footer — connections
omitted until their meaning through the multigateway is confirmed),
`Read Replica` cards, and the standard animated replication edges
(status lives on the card badges). Poolers and gateways poll every 30s
without re-running layout (topology projection + structural sharing).
Drag-to-pan works through the shard group box, and the metrics footer's
skeleton matches the loaded row height so the card doesn't shift.
- Accessibility: the failover tooltip trigger is a keyboard-focusable
button, status badges sit in stable `role="status"` live regions, the
region flag is decorative (`alt=""`), and the edge dash/spinner
animations respect `prefers-reduced-motion` (applied to the pipelines
diagram's edges too).
- Fallbacks: `AlertError` ("Failed to retrieve cluster topology") when
either ha-admin query errors, and a "Cluster topology unavailable" empty
state when the topology comes back empty — never a half-rendered
diagram.

**Changed:**

- `InstanceConfiguration` is now topology-source-aware: it branches
internally on `useHighAvailability()`, so both surfaces (homepage
`TopSection` and the replication page) get the right diagram with no new
wiring. The two-pass measured dagre layout moved into a shared
`DiagramFlow`; `nodeTypes`/`edgeTypes` are module-level consts.
- `getEdgeVisual` + the mid-edge icon chip lifted out of
`ReplicationDiagram/Edges.tsx` into
`components/ui/ReactFlow/EdgeVisual.tsx` so both diagrams derive edge
icon + line style from one state object (no behavior change for the
pipelines diagram). The primary card's CPU/Disk/RAM footer is likewise
extracted into a shared `ComputeMetricsFooter`.
- Fixes a latent relayout loop inherited from the region-box pattern:
handing React Flow a freshly created (unmeasured) group node on every
layout pass reset `nodesInitialized`, re-triggering the measured pass
and `fitView` forever — which made the diagram snap back to center and
effectively unpannable. The shared `DiagramFlow` now re-attaches known
measurements to group nodes, which also covers the standard diagram's
region boxes.
- Standard diagram: the API Load Balancer → primary edge is now static —
no data flows over it, the line only indicates a relation.
- `database/replication` page: the HA early-return empty state is
replaced by the diagram under a "High Availability cluster topology"
header. Non-HA projects are untouched.

**Intentional deviations from the mock** (for design review):

1. **No per-replica regions** — alpha replicas are one-per-cell inside a
single region, so the mock's `eu-west-1` / `ap-southeast-1` on sibling
replicas would be false. Availability zone per node, region shown once
on the primary.
2. **"Primary Database", not "Main Database"** — matches the string both
existing diagrams already ship, and the same component now renders both
project types.
3. **No collapse chevron on the shard header** — alpha has exactly one
shard; collapsing it would hide the whole diagram. The group box still
ships; add collapse when `shards.length > 1`.
4. **Failover shown on the shard group, not replica cards** — failover
is a cohort property; per-card badging would assert readiness we can't
verify without a per-pooler `/status` fanout.
5. **Standard node/edge styling reused** (per review) — neutral primary
border + green chip and the default animated edges instead of the mock's
green ring and dashed green arrowed edges, keeping the HA and non-HA
diagrams visually consistent.

**Confirmed against a real local Multigres cluster:** cells are named
`cell-1`/`cell-2`/… (not AZ-shaped — the AZ formatter falls back to the
raw cell name as designed); `GET /platform/projects/{ref}/databases`
returns only the primary row for HA projects; and the `/ha-admin`
passthrough returns **each gateway/pooler record once per cell it fans
out to** — the topology mapper dedupes by id, but worth confirming with
@sbc-bobbie whether the backend should dedupe.

**Known alpha limitation:** node health and the "replicating" edge state
derive from the pooler's *topology record*
(`lifecycleStatus`/`servingStatus`), not a live probe — a pooler that
crashes without publishing a terminal state can read as healthy until
the topology evicts its record, and a serving replica with paused replay
still shows a green edge. This matches the existing replication
diagram's semantics (`ACTIVE_HEALTHY` ⇒ animated edge). Live per-pooler
signals (WAL receiver state, replay position) exist on `GET
/poolers/{cell}/{name}/status` but need a per-pooler fanout —
deliberately deferred, noted on `getPoolerStatus`.

**Still to confirm** (doesn't block review): whether the `/ha-admin`
passthrough is deployed to production or staging-only (if staging-only,
this should get a flag before GA).

## To test

Tested end-to-end locally against a real Multigres project
(standard-project regression pass, HA creation flow, error fallback
against real 500s, and full topology + polling + console checks against
live multiadmin data):

- **HA project homepage**: diagram card shows Multigateway → shard box
(`Shard 1`, count badge, `Automatic failover` tooltip) → green-bordered
Primary Database (region, AZ, size) + Read Replica cards (AZ), dashed
green animated edges to healthy replicas. No flow/map toggle for HA.
- **HA project → Database → Replication**: same diagram under a "High
Availability cluster topology" header; no Destinations section; the old
"Replication unavailable…" state is gone.
- **Error path**: if `/ha-admin/v1/*` fails, both surfaces show "Failed
to retrieve cluster topology" with Contact support — no partial diagram.
- **Standard project regression**: homepage diagram (primary card, flow
⇄ map toggle round-trips), replication page (pipelines diagram +
Destinations) all unchanged; zero requests to `/ha-admin/*`.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
  - Added High Availability topology diagrams to the Replication page.
- Display gateways, primary databases, replicas, shards, statuses,
regions, infrastructure details, and compute metrics.
- Added observability links and live topology updates with loading,
error, and unavailable states.

- **Bug Fixes**
- Improved handling of incomplete infrastructure identities and
unexpected data.
  - Corrected topology layout, node spacing, and visual edge behavior.

- **Accessibility**
- Reduced-motion preferences now disable diagram animations and loading
effects.
  - Improved status announcements for assistive technologies.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
2026-08-26 16:51:36 +08:00

127 lines
4.3 KiB
TypeScript

import { ReadReplicaSetupError, ReadReplicaSetupProgress } from '@supabase/shared-types/out/events'
import type { AWS_REGIONS_KEYS } from 'shared-data'
import { AWS_REGIONS } from 'shared-data'
export interface Region {
key: AWS_REGIONS_KEYS
name: string
region: string
coordinates: [number, number]
}
export type NodeData = {
id: string
provider: string
region: Region
computeSize?: string
status: string
inserted_at: string
}
export type PrimaryNodeData = NodeData & {
numReplicas: number
numRegions: number
hasLoadBalancer: boolean
}
export type LoadBalancerData = NodeData & {
numDatabases: number
}
export type ReplicaNodeData = NodeData & {
onSelectRestartReplica: () => void
onSelectResizeReplica: () => void
onSelectDropReplica: () => void
}
export type EdgeData = {
status: string
identifier: string
connectionString: string | null | undefined
}
// ReactFlow is scaling everything by the factor of 2
export const NODE_WIDTH = 660
export const NODE_SEP = 20
// Rendered width of the node cards; dagre lays out with NODE_WIDTH / 2 so
// cards get a little breathing room between columns.
export const NODE_CARD_WIDTH = NODE_WIDTH / 2 - 10
// The region wrapper is a static, non-measured sibling node with a fixed size.
export const REGION_NODE_HEIGHT = 162
// The shard wrapper is a static, non-measured background node sized around its
// children, with room reserved above them for the group header pill.
export const SHARD_NODE_PADDING = 16
export const SHARD_HEADER_HEIGHT = 42
// dagre rank separation for the High Availability layout — leaves room for the
// shard group header between the gateway row and the primary row.
export const HA_RANKSEP = 96
// First-paint fallback heights for the dagre layout, only used before React
// Flow has measured the real nodes. Subsequent layouts use node.measured.height.
export const NODE_HEIGHT_FALLBACKS: Record<string, number> = {
LOAD_BALANCER: 64,
PRIMARY: 140,
READ_REPLICA: 140,
REGION: REGION_NODE_HEIGHT,
HA_GATEWAY: 64,
HA_PRIMARY: 150,
HA_REPLICA: 90,
}
// [Joshen] Coordinates from https://github.com/tobilg/aws-edge-locations/blob/main/data/aws-edge-locations.json
// In the format of [lon, lat]
export const AWS_REGIONS_COORDINATES: { [key: string]: [number, number] } = {
SOUTHEAST_ASIA: [103.8, 1.37],
NORTHEAST_ASIA: [139.42, 35.41],
NORTHEAST_ASIA_2: [126.98, 37.56],
CENTRAL_CANADA: [-73.6, 45.5],
WEST_US: [-121.96, 37.35],
WEST_US_2: [-122.67, 45.51],
EAST_US: [-78.45, 38.13],
WEST_EU: [-8, 53],
WEST_EU_2: [-0.1, 51],
CENTRAL_EU: [8, 50],
SOUTH_ASIA: [72.88, 19.08],
OCEANIA: [151.2, -33.86],
SOUTH_AMERICA: [-46.38, -23.34],
CENTRAL_EU_2: [8.54, 47.45],
EAST_US_2: [-83, 39.96],
NORTH_EU: [17.91, 59.65],
WEST_EU_3: [2.35, 48.86],
}
// [Joshen] Just to make sure that we just depend on AWS_REGIONS to determine available
export const AVAILABLE_REPLICA_REGIONS: Region[] = Object.keys(AWS_REGIONS)
.map((key) => {
return {
key: key as AWS_REGIONS_KEYS,
name: AWS_REGIONS?.[key as AWS_REGIONS_KEYS].displayName,
region: AWS_REGIONS?.[key as AWS_REGIONS_KEYS].code,
coordinates: AWS_REGIONS_COORDINATES[key],
}
})
.filter((x) => x.coordinates !== undefined)
// [Joshen] Just a more user friendly language, so that all the verbs are progressive
export const INIT_PROGRESS = {
[ReadReplicaSetupProgress.Requested]: 'Requesting replica instance',
[ReadReplicaSetupProgress.Started]: 'Launching replica instance',
[ReadReplicaSetupProgress.LaunchedReadReplicaInstance]: 'Initiating replica setup',
[ReadReplicaSetupProgress.InitiatedReadReplicaSetup]: 'Downloading base backup',
[ReadReplicaSetupProgress.DownloadedBaseBackup]: 'Replaying WAL archives',
[ReadReplicaSetupProgress.ReplayedWalArchives]: 'Completing set up',
[ReadReplicaSetupProgress.CompletedReadReplicaSetup]: 'Completed',
}
export const ERROR_STATES = {
[ReadReplicaSetupError.ReadReplicaInstanceLaunchFailed]: 'Failed to launch replica',
[ReadReplicaSetupError.InitiateReadReplicaSetupFailed]: 'Failed to initiate replica',
[ReadReplicaSetupError.DownloadBaseBackupFailed]: 'Failed to download backup',
[ReadReplicaSetupError.ReplayWalArchivesFailed]: 'Failed to replay WAL archives',
[ReadReplicaSetupError.CompleteReadReplicaSetupFailed]: 'Failed to set up replica',
}