1#![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#[derive(Clone)]
25struct AppState {
26 config: Arc<ArcSwap<Config>>,
27 pools: Arc<PoolManager>,
28 topology: Arc<TopologyManager>,
29 clients: Arc<ClientRegistry>,
30}
31
32#[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#[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#[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#[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#[derive(Serialize, ToSchema)]
104struct ServerInfo {
105 address: String,
106 role: ServerRole,
107}
108
109#[derive(Serialize, ToSchema)]
111#[serde(rename_all = "lowercase")]
112enum ServerRole {
113 Primary,
114 Replica,
115 Unreachable,
116}
117
118#[derive(Serialize, ToSchema)]
120struct ClusterServers {
121 cluster: String,
122 servers: Vec<ServerInfo>,
123}
124
125#[derive(Serialize, ToSchema)]
127struct ClientInfo {
128 id: u64,
130 remote: String,
132 state: ClientStateDto,
134 uptime_secs: f64,
136 state_since_secs: f64,
138 database: Option<String>,
140 user: Option<String>,
142 #[serde(skip_serializing_if = "Option::is_none")]
145 waiting_for: Option<WaitTargetDto>,
146}
147
148#[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#[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#[derive(Serialize, ToSchema)]
216struct QueueInfoDto {
217 database: String,
218 user: String,
219 role: WaitRoleDto,
220 depth: u32,
222 oldest_wait_secs: f64,
224}
225
226#[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#[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#[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#[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#[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#[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
407pub 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
436pub 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}