Skip to main content

asyncq_axum/
lib.rs

1//! Axum integration for asyncq — admin REST endpoints with Prometheus metrics.
2//!
3//! # Setup
4//!
5//! Mount the admin router on any path in your axum application:
6//!
7//! ```rust,no_run
8//! use asyncq::{Queue, backends::InMemoryBackend};
9//! use asyncq_axum::admin;
10//! use axum::Router;
11//!
12//! let queue = Queue::new(InMemoryBackend::new());
13//! let app = Router::new()
14//!     .nest("/admin", admin(queue))
15//!     /* ... your other routes ... */;
16//! ```
17//!
18//! # Endpoints
19//!
20//! | Method | Path | Description |
21//! |--------|------|-------------|
22//! | GET | `/admin/queues/:name` | Stats for a queue |
23//! | GET | `/admin/queues/:name/dlq` | Dead-letter queue (paginated) |
24//! | POST | `/admin/queues/:name/dlq/retry-all` | Requeue all dead jobs |
25//! | DELETE | `/admin/queues/:name/dlq/:id` | Retry one dead job by ID |
26//! | GET | `/admin/metrics` | Prometheus text metrics |
27
28use 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// ── State ─────────────────────────────────────────────────────────────────────
43
44#[derive(Clone)]
45struct AdminState<B: Backend> {
46    queue: Queue<B>,
47    /// Queue names exposed in /metrics. Empty = metrics stub only.
48    monitored_queues: Vec<String>,
49}
50
51// ── Admin router ──────────────────────────────────────────────────────────────
52
53/// Build the admin Router. Mount it with `router.nest("/admin", admin(queue))`.
54///
55/// The `/metrics` endpoint returns a minimal Prometheus stub. To get live
56/// per-queue gauges, use [`admin_with_queues`] instead.
57pub fn admin<B: Backend + Clone + 'static>(queue: Queue<B>) -> Router {
58    admin_with_queues(queue, vec![])
59}
60
61/// Build the admin Router with live Prometheus metrics for the given queue names.
62///
63/// ```rust,no_run
64/// use asyncq::{Queue, backends::InMemoryBackend};
65/// use asyncq_axum::admin_with_queues;
66/// use axum::Router;
67///
68/// let queue = Queue::new(InMemoryBackend::new());
69/// let app = Router::new()
70///     .nest("/admin", admin_with_queues(queue, vec!["emails".into(), "payments".into()]));
71/// ```
72///
73/// The `/metrics` endpoint will then expose:
74/// ```text
75/// asyncq_jobs_pending{queue="emails"} 3
76/// asyncq_jobs_running{queue="emails"} 1
77/// asyncq_jobs_dead{queue="emails"} 0
78/// ```
79pub 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
93// ── Handlers ──────────────────────────────────────────────────────────────────
94
95async 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; // queue is implicit from the job record
147    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    // Collect live stats for each monitored queue
159    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    // pending
167    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    // running
174    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    // dead
182    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    // completed
190    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    // version info
198    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// ── Response types ────────────────────────────────────────────────────────────
215
216#[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// ── Tests ─────────────────────────────────────────────────────────────────────
269
270#[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        // Enqueue and discard a job → it lands in DLQ
331        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        // Enqueue two jobs so stats are non-zero
419        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        // 2 pending jobs
434        assert!(text.contains("asyncq_jobs_pending{queue=\"admin-test\"} 2"), "pending count must be 2");
435    }
436}