1use std::sync::Arc;
29use axum::{
30 Router,
31 extract::{Path, Query, State},
32 response::{IntoResponse, Response},
33 routing::{delete, get, post},
34 Json,
35};
36use http::StatusCode;
37use serde::{Deserialize, Serialize};
38use uuid::Uuid;
39
40use asyncq::{backend::Backend, job::QueueStats, Queue};
41
42#[derive(Clone)]
45struct AdminState<B: Backend> {
46 queue: Queue<B>,
47 monitored_queues: Vec<String>,
49}
50
51pub fn admin<B: Backend + Clone + 'static>(queue: Queue<B>) -> Router {
58 admin_with_queues(queue, vec![])
59}
60
61pub fn admin_with_queues<B: Backend + Clone + 'static>(
80 queue: Queue<B>,
81 queues: Vec<String>,
82) -> Router {
83 let state = Arc::new(AdminState { queue, monitored_queues: queues });
84 Router::new()
85 .route("/queues/:name", get(queue_stats))
86 .route("/queues/:name/dlq", get(list_dlq))
87 .route("/queues/:name/dlq/retry-all",post(retry_all))
88 .route("/queues/:name/dlq/:id", delete(retry_one))
89 .route("/metrics", get(metrics))
90 .with_state(state)
91}
92
93async fn queue_stats<B: Backend + Clone + 'static>(
96 Path(name): Path<String>,
97 State(s): State<Arc<AdminState<B>>>,
98) -> impl IntoResponse {
99 match s.queue.stats(&name).await {
100 Ok(stats) => Json(StatsResponse::from(stats)).into_response(),
101 Err(e) => error_response(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
102 }
103}
104
105#[derive(Deserialize)]
106struct Pagination {
107 #[serde(default = "default_limit")]
108 limit: i64,
109 #[serde(default)]
110 offset: i64,
111}
112fn default_limit() -> i64 { 50 }
113
114async fn list_dlq<B: Backend + Clone + 'static>(
115 Path(name): Path<String>,
116 Query(p): Query<Pagination>,
117 State(s): State<Arc<AdminState<B>>>,
118) -> impl IntoResponse {
119 match s.queue.dead_jobs(&name, p.limit, p.offset).await {
120 Ok(jobs) => {
121 let items: Vec<DeadJobResponse> = jobs.into_iter().map(DeadJobResponse::from).collect();
122 Json(serde_json::json!({ "jobs": items, "count": items.len() })).into_response()
123 }
124 Err(e) => error_response(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
125 }
126}
127
128async fn retry_all<B: Backend + Clone + 'static>(
129 Path(name): Path<String>,
130 State(s): State<Arc<AdminState<B>>>,
131) -> impl IntoResponse {
132 match s.queue.retry_all_dead(&name).await {
133 Ok(n) => Json(serde_json::json!({ "requeued": n })).into_response(),
134 Err(e) => error_response(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string()),
135 }
136}
137
138async fn retry_one<B: Backend + Clone + 'static>(
139 Path((name, id_str)): Path<(String, String)>,
140 State(s): State<Arc<AdminState<B>>>,
141) -> impl IntoResponse {
142 let id = match Uuid::parse_str(&id_str) {
143 Ok(id) => id,
144 Err(_) => return error_response(StatusCode::BAD_REQUEST, "invalid job id"),
145 };
146 let _ = name; match s.queue.retry_dead(id).await {
148 Ok(()) => StatusCode::NO_CONTENT.into_response(),
149 Err(e) => error_response(StatusCode::NOT_FOUND, &e.to_string()),
150 }
151}
152
153async fn metrics<B: Backend + Clone + 'static>(
154 State(s): State<Arc<AdminState<B>>>,
155) -> impl IntoResponse {
156 let mut lines: Vec<String> = Vec::new();
157
158 let mut all_stats: Vec<(String, QueueStats)> = Vec::new();
160 for q in &s.monitored_queues {
161 if let Ok(stats) = s.queue.stats(q).await {
162 all_stats.push((q.clone(), stats));
163 }
164 }
165
166 lines.push("# HELP asyncq_jobs_pending Jobs waiting to be processed".into());
168 lines.push("# TYPE asyncq_jobs_pending gauge".into());
169 for (q, st) in &all_stats {
170 lines.push(format!("asyncq_jobs_pending{{queue=\"{}\"}} {}", q, st.pending));
171 }
172
173 lines.push("".into());
175 lines.push("# HELP asyncq_jobs_running Jobs currently being processed".into());
176 lines.push("# TYPE asyncq_jobs_running gauge".into());
177 for (q, st) in &all_stats {
178 lines.push(format!("asyncq_jobs_running{{queue=\"{}\"}} {}", q, st.running));
179 }
180
181 lines.push("".into());
183 lines.push("# HELP asyncq_jobs_dead Jobs in the dead-letter queue".into());
184 lines.push("# TYPE asyncq_jobs_dead gauge".into());
185 for (q, st) in &all_stats {
186 lines.push(format!("asyncq_jobs_dead{{queue=\"{}\"}} {}", q, st.dead));
187 }
188
189 lines.push("".into());
191 lines.push("# HELP asyncq_jobs_completed Jobs completed successfully".into());
192 lines.push("# TYPE asyncq_jobs_completed counter".into());
193 for (q, st) in &all_stats {
194 lines.push(format!("asyncq_jobs_completed{{queue=\"{}\"}} {}", q, st.completed));
195 }
196
197 lines.push("".into());
199 lines.push("# HELP asyncq_info asyncq version info".into());
200 lines.push("# TYPE asyncq_info gauge".into());
201 lines.push(format!("asyncq_info{{version=\"{}\"}} 1", env!("CARGO_PKG_VERSION")));
202
203 lines.push("".into());
204 let body = lines.join("\n");
205
206 (
207 StatusCode::OK,
208 [("content-type", "text/plain; version=0.0.4; charset=utf-8")],
209 body,
210 )
211 .into_response()
212}
213
214#[derive(Serialize)]
217struct StatsResponse {
218 queue: String,
219 pending: u64,
220 running: u64,
221 completed: u64,
222 failed: u64,
223 dead: u64,
224}
225
226impl From<QueueStats> for StatsResponse {
227 fn from(s: QueueStats) -> Self {
228 Self {
229 queue: s.queue,
230 pending: s.pending,
231 running: s.running,
232 completed: s.completed,
233 failed: s.failed,
234 dead: s.dead,
235 }
236 }
237}
238
239#[derive(Serialize)]
240struct DeadJobResponse {
241 id: String,
242 kind: String,
243 queue: String,
244 attempt: u32,
245 max_attempts: u32,
246 last_error: Option<String>,
247 created_at: String,
248}
249
250impl From<asyncq::job::JobRecord> for DeadJobResponse {
251 fn from(r: asyncq::job::JobRecord) -> Self {
252 Self {
253 id: r.id.to_string(),
254 kind: r.kind,
255 queue: r.queue,
256 attempt: r.attempt,
257 max_attempts: r.max_attempts,
258 last_error: r.last_error,
259 created_at: r.created_at.to_rfc3339(),
260 }
261 }
262}
263
264fn error_response(status: StatusCode, message: &str) -> Response {
265 (status, Json(serde_json::json!({ "error": message }))).into_response()
266}
267
268#[cfg(test)]
271mod tests {
272 use super::*;
273 use asyncq::{backends::InMemoryBackend, Job, JobContext, JobResult, Perform, Queue, Worker, JobRecord};
274 use axum::{body::Body, http::Request};
275 use serde::{Deserialize, Serialize};
276
277 #[derive(Job, Serialize, Deserialize)]
278 #[job(queue = "admin-test", retries = 1)]
279 struct TestJob;
280
281 impl Perform for TestJob {
282 async fn perform(self, _ctx: JobContext) -> JobResult {
283 Err(asyncq::error::JobError::discard("test discard"))
284 }
285 }
286
287 fn test_app() -> (Router, Queue<InMemoryBackend>) {
288 let backend = InMemoryBackend::new();
289 let queue = Queue::new(backend);
290 let app = Router::new().nest("/admin", admin(queue.clone()));
291 (app, queue)
292 }
293
294 async fn call(app: Router, req: Request<Body>) -> axum::response::Response {
295 use tower::ServiceExt as _;
296 app.oneshot(req).await.unwrap()
297 }
298
299 #[tokio::test]
300 async fn stats_returns_200() {
301 let (app, _) = test_app();
302 let req = Request::builder()
303 .uri("/admin/queues/admin-test")
304 .body(Body::empty())
305 .unwrap();
306 let resp = call(app, req).await;
307 assert_eq!(resp.status(), StatusCode::OK);
308 }
309
310 #[tokio::test]
311 async fn dlq_empty_returns_200() {
312 let (app, _) = test_app();
313 let req = Request::builder()
314 .uri("/admin/queues/admin-test/dlq")
315 .body(Body::empty())
316 .unwrap();
317 let resp = call(app, req).await;
318 assert_eq!(resp.status(), StatusCode::OK);
319 let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
320 let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
321 assert_eq!(json["count"], 0);
322 }
323
324 #[tokio::test]
325 async fn dlq_shows_dead_jobs() {
326 let backend = InMemoryBackend::new();
327 let queue = Queue::new(backend.clone());
328 let app = Router::new().nest("/admin", admin(queue.clone()));
329
330 queue.enqueue(TestJob).await.unwrap();
332 Worker::new(queue.clone()).register::<TestJob>().run_once().await.unwrap();
333
334 let req = Request::builder()
335 .uri("/admin/queues/admin-test/dlq")
336 .body(Body::empty())
337 .unwrap();
338 let resp = call(app, req).await;
339 let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
340 let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
341 assert_eq!(json["count"], 1, "DLQ must show the discarded job");
342 assert_eq!(json["jobs"][0]["kind"], "TestJob");
343 }
344
345 #[tokio::test]
346 async fn retry_all_requeues_from_dlq() {
347 let backend = InMemoryBackend::new();
348 let queue = Queue::new(backend.clone());
349 let app = Router::new().nest("/admin", admin(queue.clone()));
350
351 queue.enqueue(TestJob).await.unwrap();
352 Worker::new(queue.clone()).register::<TestJob>().run_once().await.unwrap();
353 assert_eq!(backend.dead_count("admin-test").await, 1);
354
355 let req = Request::builder()
356 .method("POST")
357 .uri("/admin/queues/admin-test/dlq/retry-all")
358 .body(Body::empty())
359 .unwrap();
360 let resp = call(app, req).await;
361 assert_eq!(resp.status(), StatusCode::OK);
362 let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
363 let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
364 assert_eq!(json["requeued"], 1);
365 assert_eq!(backend.dead_count("admin-test").await, 0);
366 }
367
368 #[tokio::test]
369 async fn retry_one_by_id() {
370 let backend = InMemoryBackend::new();
371 let queue = Queue::new(backend.clone());
372 let app = Router::new().nest("/admin", admin(queue.clone()));
373
374 let payload = serde_json::to_vec(&TestJob).unwrap();
375 let id = queue.enqueue_record(JobRecord::new("TestJob", "admin-test", payload, 1))
376 .await.unwrap();
377 Worker::new(queue.clone()).register::<TestJob>().run_once().await.unwrap();
378 assert_eq!(backend.dead_count("admin-test").await, 1);
379
380 let req = Request::builder()
381 .method("DELETE")
382 .uri(format!("/admin/queues/admin-test/dlq/{id}"))
383 .body(Body::empty())
384 .unwrap();
385 let resp = call(app, req).await;
386 assert_eq!(resp.status(), StatusCode::NO_CONTENT);
387 assert_eq!(backend.dead_count("admin-test").await, 0);
388 }
389
390 #[tokio::test]
391 async fn metrics_returns_prometheus_format() {
392 let (app, _) = test_app();
393 let req = Request::builder()
394 .uri("/admin/metrics")
395 .body(Body::empty())
396 .unwrap();
397 let resp = call(app, req).await;
398 assert_eq!(resp.status(), StatusCode::OK);
399 let ct = resp.headers()
400 .get("content-type").unwrap()
401 .to_str().unwrap();
402 assert!(ct.contains("text/plain"), "metrics must be Prometheus text format");
403 let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
404 let text = std::str::from_utf8(&body).unwrap();
405 assert!(text.contains("# HELP asyncq_info"), "must include HELP comment");
406 assert!(text.contains("asyncq_info{version="), "must include version gauge");
407 }
408
409 #[tokio::test]
410 async fn metrics_with_queues_shows_live_data() {
411 let backend = InMemoryBackend::new();
412 let queue = Queue::new(backend.clone());
413 let app = Router::new().nest(
414 "/admin",
415 admin_with_queues(queue.clone(), vec!["admin-test".into()]),
416 );
417
418 queue.enqueue(TestJob).await.unwrap();
420 queue.enqueue(TestJob).await.unwrap();
421
422 let req = Request::builder()
423 .uri("/admin/metrics")
424 .body(Body::empty())
425 .unwrap();
426 let resp = call(app, req).await;
427 assert_eq!(resp.status(), StatusCode::OK);
428 let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
429 let text = std::str::from_utf8(&body).unwrap();
430
431 assert!(text.contains("asyncq_jobs_pending{queue=\"admin-test\"}"), "must contain pending gauge");
432 assert!(text.contains("asyncq_jobs_dead{queue=\"admin-test\"}"), "must contain dead gauge");
433 assert!(text.contains("asyncq_jobs_pending{queue=\"admin-test\"} 2"), "pending count must be 2");
435 }
436}