Skip to main content

halephant_core/admin/
mod.rs

1// The `OpenApi` derive macro generates code that uses `for_each`.
2#![allow(clippy::needless_for_each)]
3use std::sync::Arc;
4
5use arc_swap::ArcSwap;
6use axum::Router;
7use axum::extract::State;
8use axum::response::Json;
9use axum::routing::get;
10use serde::Serialize;
11use tokio::net::TcpListener;
12use utoipa::{OpenApi, ToSchema};
13use utoipa_scalar::{Scalar, Servable};
14
15use crate::clients::ClientRegistry;
16use crate::config::Config;
17use crate::pool::PoolManager;
18use crate::topology::TopologyManager;
19
20// ---------------------------------------------------------------------------
21// Shared state
22// ---------------------------------------------------------------------------
23
24#[derive(Clone)]
25struct AppState {
26    config: Arc<ArcSwap<Config>>,
27    pools: Arc<PoolManager>,
28    topology: Arc<TopologyManager>,
29    clients: Arc<ClientRegistry>,
30}
31
32// ---------------------------------------------------------------------------
33// OpenAPI
34// ---------------------------------------------------------------------------
35
36#[derive(OpenApi)]
37#[openapi(
38    paths(health, ready, get_pools, get_servers, get_clients, get_queues),
39    components(schemas(
40        HealthResponse,
41        HealthStatus,
42        ReadyResponse,
43        ClusterReadiness,
44        PoolInfo,
45        ClusterServers,
46        ServerInfo,
47        ServerRole,
48        ClientInfo,
49        ClientStateDto,
50        WaitTargetDto,
51        WaitRoleDto,
52        QueueInfoDto,
53    )),
54    info(
55        title = "Halephant Admin API",
56        version = "0.1.0",
57        description = "Operational endpoints for health checks and pool introspection."
58    )
59)]
60struct ApiDoc;
61
62// ---------------------------------------------------------------------------
63// Response types
64// ---------------------------------------------------------------------------
65
66/// Health check response.
67#[derive(Serialize, ToSchema)]
68struct HealthResponse {
69    status: HealthStatus,
70}
71
72#[derive(Serialize, ToSchema)]
73#[serde(rename_all = "lowercase")]
74enum HealthStatus {
75    Ok,
76}
77
78/// Readiness check response.
79#[derive(Serialize, ToSchema)]
80struct ReadyResponse {
81    ready: bool,
82    clusters: Vec<ClusterReadiness>,
83}
84
85#[derive(Serialize, ToSchema)]
86struct ClusterReadiness {
87    name: String,
88    has_primary: bool,
89}
90
91/// Pool connection statistics.
92#[derive(Serialize, ToSchema)]
93struct PoolInfo {
94    node: String,
95    database: String,
96    user: String,
97    active: u32,
98    idle: u32,
99    resetting: u32,
100}
101
102/// Upstream server status within a cluster.
103#[derive(Serialize, ToSchema)]
104struct ServerInfo {
105    address: String,
106    role: ServerRole,
107}
108
109/// Upstream server role.
110#[derive(Serialize, ToSchema)]
111#[serde(rename_all = "lowercase")]
112enum ServerRole {
113    Primary,
114    Replica,
115    Unreachable,
116}
117
118/// Cluster server topology.
119#[derive(Serialize, ToSchema)]
120struct ClusterServers {
121    cluster: String,
122    servers: Vec<ServerInfo>,
123}
124
125/// Point-in-time state of a single connected client.
126#[derive(Serialize, ToSchema)]
127struct ClientInfo {
128    /// Stable client identifier within this halephant process.
129    id: u64,
130    /// Remote address of the client's TCP socket.
131    remote: String,
132    /// High-level state of the client.
133    state: ClientStateDto,
134    /// Seconds since the client was accepted.
135    uptime_secs: f64,
136    /// Seconds the client has been in its current state.
137    state_since_secs: f64,
138    /// Database name from the client's startup message, if known.
139    database: Option<String>,
140    /// PostgreSQL user from the client's startup message, if known.
141    user: Option<String>,
142    /// Populated only while `state` is `waiting` — identifies the
143    /// specific role queue the client is blocked on.
144    #[serde(skip_serializing_if = "Option::is_none")]
145    waiting_for: Option<WaitTargetDto>,
146}
147
148/// Client state category as exposed by the admin API.
149#[derive(Serialize, ToSchema)]
150#[serde(rename_all = "snake_case")]
151enum ClientStateDto {
152    Negotiating,
153    Authenticating,
154    Idle,
155    InTransaction,
156    Waiting,
157}
158
159impl From<crate::clients::ClientState> for ClientStateDto {
160    fn from(s: crate::clients::ClientState) -> Self {
161        use crate::clients::ClientState;
162        match s {
163            ClientState::Negotiating => Self::Negotiating,
164            ClientState::Authenticating => Self::Authenticating,
165            ClientState::Idle => Self::Idle,
166            ClientState::InTransaction => Self::InTransaction,
167            ClientState::Waiting => Self::Waiting,
168        }
169    }
170}
171
172/// The `(database, user, role)` queue key a client is blocked on while
173/// waiting for pool capacity.
174#[derive(Serialize, ToSchema)]
175struct WaitTargetDto {
176    database: String,
177    user: String,
178    role: WaitRoleDto,
179}
180
181#[derive(Serialize, ToSchema)]
182#[serde(rename_all = "snake_case")]
183enum WaitRoleDto {
184    Primary,
185    Replica,
186}
187
188impl From<crate::pool::Routing> for WaitRoleDto {
189    fn from(role: crate::pool::Routing) -> Self {
190        use crate::pool::Routing;
191        match role {
192            Routing::Primary => WaitRoleDto::Primary,
193            Routing::Replica => WaitRoleDto::Replica,
194        }
195    }
196}
197
198impl From<crate::clients::WaitTarget> for WaitTargetDto {
199    fn from(t: crate::clients::WaitTarget) -> Self {
200        use crate::clients::WaitRole;
201        Self {
202            database: t.database,
203            user: t.user,
204            role: match t.role {
205                WaitRole::Primary => WaitRoleDto::Primary,
206                WaitRole::Replica => WaitRoleDto::Replica,
207            },
208        }
209    }
210}
211
212/// Snapshot of one wait queue: how many clients are currently blocked
213/// on this `(database, user, role)` and how long the oldest has been
214/// waiting. Only active (non-empty) queues are returned.
215#[derive(Serialize, ToSchema)]
216struct QueueInfoDto {
217    database: String,
218    user: String,
219    role: WaitRoleDto,
220    /// Number of clients currently blocked on this queue.
221    depth: u32,
222    /// Seconds the oldest queued waiter has been blocked.
223    oldest_wait_secs: f64,
224}
225
226// ---------------------------------------------------------------------------
227// Handlers
228// ---------------------------------------------------------------------------
229
230/// Liveness probe. Always returns 200.
231#[utoipa::path(
232    get,
233    path = "/health",
234    responses((status = 200, body = HealthResponse)),
235    tag = "health"
236)]
237async fn health() -> Json<HealthResponse> {
238    Json(HealthResponse {
239        status: HealthStatus::Ok,
240    })
241}
242
243/// Readiness probe. Returns 200 when all clusters have a discovered primary,
244/// 503 otherwise.
245#[utoipa::path(
246    get,
247    path = "/ready",
248    responses(
249        (status = 200, body = ReadyResponse, description = "All clusters have a primary"),
250        (status = 503, body = ReadyResponse, description = "One or more clusters lack a primary")
251    ),
252    tag = "health"
253)]
254async fn ready(State(state): State<AppState>) -> (axum::http::StatusCode, Json<ReadyResponse>) {
255    let cfg = state.config.load_full();
256    let clusters: Vec<ClusterReadiness> = cfg
257        .cluster
258        .keys()
259        .map(|name| {
260            let has_primary = state.topology.primary(name).is_some();
261            ClusterReadiness {
262                name: name.clone(),
263                has_primary,
264            }
265        })
266        .collect();
267
268    let all_ready = clusters.iter().all(|c| c.has_primary);
269    let status = if all_ready {
270        axum::http::StatusCode::OK
271    } else {
272        axum::http::StatusCode::SERVICE_UNAVAILABLE
273    };
274
275    (
276        status,
277        Json(ReadyResponse {
278            ready: all_ready,
279            clusters,
280        }),
281    )
282}
283
284/// Pool connection statistics per node, database, and user.
285#[utoipa::path(
286    get,
287    path = "/admin/pools",
288    responses((status = 200, body = Vec<PoolInfo>)),
289    tag = "admin"
290)]
291async fn get_pools(State(state): State<AppState>) -> Json<Vec<PoolInfo>> {
292    let stats = state
293        .pools
294        .pool_stats()
295        .into_iter()
296        .map(|(key, stats)| PoolInfo {
297            node: key.node,
298            database: key.database,
299            user: key.user,
300            active: stats.active,
301            idle: stats.idle,
302            resetting: stats.resetting,
303        })
304        .collect();
305    Json(stats)
306}
307
308/// Upstream server topology per cluster.
309#[utoipa::path(
310    get,
311    path = "/admin/servers",
312    responses((status = 200, body = Vec<ClusterServers>)),
313    tag = "admin"
314)]
315async fn get_servers(State(state): State<AppState>) -> Json<Vec<ClusterServers>> {
316    let cfg = state.config.load_full();
317    let result = cfg
318        .cluster
319        .keys()
320        .map(|name| {
321            let mut servers = Vec::new();
322            if let Some(topo) = state.topology.get(name) {
323                if let Some(ref primary) = topo.primary {
324                    servers.push(ServerInfo {
325                        address: primary.clone(),
326                        role: ServerRole::Primary,
327                    });
328                }
329                for replica in &topo.replicas {
330                    servers.push(ServerInfo {
331                        address: replica.clone(),
332                        role: ServerRole::Replica,
333                    });
334                }
335                for node in &topo.unreachable {
336                    servers.push(ServerInfo {
337                        address: node.clone(),
338                        role: ServerRole::Unreachable,
339                    });
340                }
341            }
342            ClusterServers {
343                cluster: name.clone(),
344                servers,
345            }
346        })
347        .collect();
348    Json(result)
349}
350
351/// Currently connected clients with their state and identity, if known.
352#[utoipa::path(
353    get,
354    path = "/admin/clients",
355    responses((status = 200, body = Vec<ClientInfo>)),
356    tag = "admin"
357)]
358async fn get_clients(State(state): State<AppState>) -> Json<Vec<ClientInfo>> {
359    let now = std::time::Instant::now();
360    let result = state
361        .clients
362        .snapshot()
363        .into_iter()
364        .map(|entry| ClientInfo {
365            id: entry.id.as_u64(),
366            remote: entry.remote.to_string(),
367            state: entry.state.into(),
368            uptime_secs: now
369                .saturating_duration_since(entry.accepted_at)
370                .as_secs_f64(),
371            state_since_secs: now
372                .saturating_duration_since(entry.state_since)
373                .as_secs_f64(),
374            database: entry.database,
375            user: entry.user,
376            waiting_for: entry.waiting_for.map(Into::into),
377        })
378        .collect();
379    Json(result)
380}
381
382/// Active wait queues — one entry per `(database, user, role)` with
383/// current depth and oldest wait duration. Empty queues are omitted so
384/// the response only reflects live contention.
385#[utoipa::path(
386    get,
387    path = "/admin/queues",
388    responses((status = 200, body = Vec<QueueInfoDto>)),
389    tag = "admin"
390)]
391async fn get_queues(State(state): State<AppState>) -> Json<Vec<QueueInfoDto>> {
392    let result = state
393        .pools
394        .queue_stats()
395        .into_iter()
396        .map(|q| QueueInfoDto {
397            database: q.database,
398            user: q.user,
399            role: WaitRoleDto::from(q.role),
400            depth: q.depth,
401            oldest_wait_secs: q.oldest_wait_secs,
402        })
403        .collect();
404    Json(result)
405}
406
407// ---------------------------------------------------------------------------
408// Server
409// ---------------------------------------------------------------------------
410
411/// Build the admin API router.
412pub fn router(
413    config: Arc<ArcSwap<Config>>,
414    pools: Arc<PoolManager>,
415    topology: Arc<TopologyManager>,
416    clients: Arc<ClientRegistry>,
417) -> Router {
418    let state = AppState {
419        config,
420        pools,
421        topology,
422        clients,
423    };
424
425    Router::new()
426        .route("/health", get(health))
427        .route("/ready", get(ready))
428        .route("/admin/pools", get(get_pools))
429        .route("/admin/servers", get(get_servers))
430        .route("/admin/clients", get(get_clients))
431        .route("/admin/queues", get(get_queues))
432        .merge(Scalar::with_url("/docs", ApiDoc::openapi()))
433        .with_state(state)
434}
435
436/// Start the admin HTTP server on the given address.
437pub async fn serve(
438    addr: &str,
439    config: Arc<ArcSwap<Config>>,
440    pools: Arc<PoolManager>,
441    topology: Arc<TopologyManager>,
442    clients: Arc<ClientRegistry>,
443) -> std::io::Result<()> {
444    let app = router(config, pools, topology, clients);
445    let listener = TcpListener::bind(addr).await?;
446    tracing::info!(%addr, "admin API listening");
447    axum::serve(listener, app).await?;
448    Ok(())
449}