@yugabytedb/perf-advisor-ui 1.0.160 → 1.0.162

package/dist/helpers/dtos.d.ts

@@ -979,4 +979,153 @@ export interface QueryPlanData {
     totalTime: number;
     universeId: string;
 }
+export declare enum HaMemberRole {
+    LEADER = "LEADER",
+    FOLLOWER = "FOLLOWER"
+}
+/**
+ * Lifecycle state of an HA member. Mirrors {@code HaMember.State} on the backend:
+ * <ul>
+ *   <li>{@code PENDING} - freshly added; bootstrap not started yet.</li>
+ *   <li>{@code JOINING} - bootstrap streaming in progress; not eligible for promotion.</li>
+ *   <li>{@code READY} - bootstrap done and change feed caught up; eligible for promotion.</li>
+ *   <li>{@code FAILED} - bootstrap retry budget exhausted; requires operator to hit the
+ *       "Retry Bootstrap" action ({@code POST /api/ha/member/bootstrap/restart}) after
+ *       resolving the underlying cause. Not eligible for promotion.</li>
+ * </ul>
+ * The Promote button in the members table is disabled for anything other than {@code READY}.
+ */
+export declare enum HaMemberLifecycleState {
+    PENDING = "PENDING",
+    JOINING = "JOINING",
+    READY = "READY",
+    FAILED = "FAILED",
+    /**
+     * Bootstrap completed cleanly at some point, but one or more CONFIG-class change entries
+     * or bootstrap rows failed to apply locally because of schema drift the follower can't
+     * heal on its own (typically a NOT NULL column on the follower that the newer leader
+     * stopped emitting, or the reverse across an N-1 to N+1 upgrade). The promotion gate
+     * refuses this state unless the operator confirms via the "Force Promote" dialog and
+     * accepts the possibly-lossy handover. Auto-clears back to READY on the next successful
+     * full-or-CONFIG bootstrap.
+     */
+    STALE_CONFIG = "STALE_CONFIG"
+}
+export interface HaMemberSpec {
+    uuid: string;
+    paEndpoint: string;
+    isLocal?: boolean;
+}
+export interface HaMemberState {
+    uuid: string;
+    paEndpoint: string;
+    role: HaMemberRole;
+    /**
+     * Lifecycle state carried on every {@code GET /api/ha/state} response. Undefined only when
+     * talking to a pre-lifecycle backend - treat as {@code READY} in that case to preserve the
+     * old behavior where every present member was implicitly promotable.
+     */
+    state?: HaMemberLifecycleState | null;
+    lastAppliedSeq: number;
+    lastSeen?: string | null;
+    isLocal: boolean;
+    /**
+     * Number of consecutive failed bootstrap attempts. Zero on a healthy member; non-zero while
+     * the follower is retrying and mid-JOINING. Renders as "N failed attempts" alongside the
+     * state badge in the HA members table. Undefined against pre-retry-tracking backends.
+     */
+    bootstrapAttempts?: number | null;
+    /**
+     * Timestamp of the last bootstrap attempt (success or failure). Combined with the server's
+     * retry interval this lets the UI show "next retry in ~Xm" while a bootstrap is in flight
+     * with a non-zero attempt count.
+     */
+    bootstrapLastAttemptAt?: string | null;
+    /**
+     * Short human-readable reason attached to the most recent bootstrap failure. Present only
+     * while state is JOINING with pending retries or {@code FAILED}. Rendered as a tooltip on
+     * the state badge so operators can triage from the UI without opening server logs.
+     */
+    bootstrapLastError?: string | null;
+    /**
+     * PA release string the peer is currently running, as observed via the {@code X-PA-HA-Version}
+     * wire header (leader-side) or {@code HaChangesResponse.leaderVersion} (follower-side). Null
+     * against pre-V84 backends or on freshly-added members before the first heartbeat has landed.
+     * Rendered in the "PA Version" column of the members table so operators can spot version
+     * drift during a rolling upgrade at a glance; the backend uses it to refuse promotion of a
+     * peer whose version is strictly older than the current leader's (unless force=true).
+     */
+    paVersion?: string | null;
+    /**
+     * Wall-clock timestamp of the READY -> STALE_CONFIG transition on this member. Rendered
+     * in the state cell tooltip so operators can tell "we just noticed this drift" from
+     * "we've been stuck for 15 minutes". Cleared to null when the state auto-clears back to
+     * READY after a successful full-or-CONFIG bootstrap. Null on any member that has not
+     * entered STALE_CONFIG in the current lifecycle.
+     */
+    staleConfigSince?: string | null;
+}
+export interface HaState {
+    groupConfigured: boolean;
+    groupUuid?: string | null;
+    currentTerm: number;
+    leaderMemberUuid?: string | null;
+    localMemberUuid?: string | null;
+    members: HaMemberState[];
+    /**
+     * Computed "is this PA currently scraping" bit. Sourced from
+     * {@code HaService.isScrapingEnabled()} on the backend: {@code true} when this PA is not part
+     * of an HA group at all, when it's the LEADER inside one, or when the deployment runs with
+     * {@code yb.cloud.enabled=true}. Exposed for read-only display in the HA page's status card;
+     * the UI does not toggle it directly (the retired {@code POST /api/ha/scraper} endpoint used
+     * to serve that role, but that persistent override was removed once follower-side leave
+     * started wiping leader-owned config).
+     */
+    scraperEnabled: boolean;
+    /**
+     * Cluster key from the local {@code ha_group} row. Present on the admin-token
+     * {@code GET /api/ha/state} surface only - the UI uses it to power the "Copy cluster key"
+     * affordance so operators can add another standby at any time without regenerating the key
+     * and invalidating existing peers. Absent (undefined) when no group is configured.
+     */
+    clusterKey?: string | null;
+}
+export declare enum HaGroupMode {
+    ACTIVE = "ACTIVE",
+    STANDBY = "STANDBY"
+}
+export interface HaGroupRequest {
+    groupUuid: string;
+    clusterKey: string;
+    members: HaMemberSpec[];
+    initialLeaderUuid?: string | null;
+    term: number;
+    /**
+     * Bootstrap flavor. Defaults to {@link HaGroupMode.ACTIVE} on the backend for backward
+     * compatibility. Use {@link HaGroupMode.STANDBY} to register as a follower - the local PA
+     * fetches the authoritative topology from {@link HaGroupRequest.remoteLeaderEndpoint} before
+     * persisting anything, so it lands on the same {@code groupUuid} / {@code currentTerm} /
+     * leader as the active PA.
+     */
+    mode?: HaGroupMode;
+    /**
+     * Required for {@link HaGroupMode.STANDBY}: base URL of the active PA (e.g.
+     * {@code https://active-pa.example.com:8080}). The backend calls {@code
+     * <remoteLeaderEndpoint>/api/ha/topology} with the shared cluster key at bootstrap; if the
+     * fetch fails the whole {@code POST /api/ha/group} call fails and the standby stays
+     * unconfigured, matching the "no half-configured state" invariant the leader-push flow
+     * relies on. Ignored in {@link HaGroupMode.ACTIVE}.
+     */
+    remoteLeaderEndpoint?: string;
+}
+export interface HaPromoteRequest {
+    memberUuid: string;
+    term: number;
+    /**
+     * When true, bypass the promote gates (version-order and STALE_CONFIG). Defaults to false
+     * on the backend if omitted. The UI only sends true after the operator confirms in the
+     * "Force Promote" dialog and accepts the possibly-lossy handover semantics.
+     */
+    force?: boolean;
+}
 export {};

package/dist/helpers/useHaStandby.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Result of `useHaStandby`. Kept as a plain object (not a class) so callers can destructure at
+ * the point of use without repeated hook fields; the JSDoc on each field is the source of
+ * truth for what "standby" means.
+ */
+export interface HaStandbyStatus {
+    /**
+     * `true` iff this PA is currently a FOLLOWER in an HA group. `false` for LEADER and for the
+     * (much more common) case of a PA that is not in any HA group at all. Callers should treat
+     * `false` as "you are on the correct PA to make mutations" - the primary consumer is the
+     * per-page mutation-button disable logic which grays out actions and points operators at
+     * the leader when this is `true`.
+     *
+     * <p>Deliberately conservative: while the initial `/api/ha/state` fetch is in flight (or has
+     * errored), we return `false`. Reasoning: (a) blocking every action on a network round-trip
+     * would regress every dev/single-node deploy; (b) the server-side {@code
+     * HaService.requireLeaderOrStandalone} refuses on the wire anyway, so a UI that "leaks" a
+     * click through will still get a 409 with a helpful message, not a silent write. The banner
+     * appearing after the fetch resolves is a strictly-better failure mode than the whole app
+     * locking up on load.
+     */
+    isStandby: boolean;
+    /**
+     * When {@link #isStandby} is `true`, the {@code pa_endpoint} of the current leader as
+     * reported by `/api/ha/state`. Null when we can't identify a leader (e.g. group has no
+     * leader elected, or the leader row is missing an endpoint). The standby banner uses this
+     * to render a "go to <endpoint>" link so operators can jump to the correct PA in one
+     * click; button tooltips also embed this string when non-null.
+     */
+    leaderEndpoint: string | null;
+    /** `true` while the underlying HA state fetch has not yet resolved once. */
+    isLoading: boolean;
+}
+/**
+ * React hook that resolves to the current PA's HA-standby status.
+ *
+ * <p>Design notes:
+ *
+ * <ul>
+ *   <li>Shares the {@code QUERY_KEY.fetchHaState} key with the HA UI page, so on a session
+ *       where the operator opens both a regular page and the HA UI page we only hit
+ *       `/api/ha/state` once every 30s (react-query dedupes by key).
+ *   <li>The 30s refetch interval matches the follower poll cadence: any role change on the
+ *       server appears in the UI within one poll cycle even without any operator action.
+ *   <li>Errors during fetch are absorbed: we return {@code isStandby: false} so a temporary
+ *       network hiccup doesn't lock down mutation controls on a healthy leader.
+ * </ul>
+ *
+ * @param apiUrl Optional API URL prefix (e.g. when this PA is served behind YBA at a
+ *     non-root path). If omitted, relative `/api/ha/state` is used.
+ */
+export declare const useHaStandby: (apiUrl?: string) => HaStandbyStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/perf-advisor-ui",
-  "version": "1.0.160",
+  "version": "1.0.162",
   "type": "module",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",