Skip to main content

asyncq_actix/
lib.rs

1//! Actix-web integration for asyncq — admin REST endpoints with Prometheus metrics.
2//!
3//! # Setup
4//!
5//! Mount the admin scope in your actix-web application:
6//!
7//! ```rust,no_run
8//! use asyncq::{Queue, backends::InMemoryBackend};
9//! use asyncq_actix::admin;
10//! use actix_web::{web, App, HttpServer};
11//!
12//! #[actix_web::main]
13//! async fn main() -> std::io::Result<()> {
14//!     let queue = Queue::new(InMemoryBackend::new());
15//!
16//!     HttpServer::new(move || {
17//!         App::new()
18//!             .service(web::scope("/admin").configure(admin(queue.clone())))
19//!     })
20//!     .bind("127.0.0.1:8080")?
21//!     .run()
22//!     .await
23//! }
24//! ```
25//!
26//! For live Prometheus metrics, use [`admin_with_queues`]:
27//!
28//! ```rust,no_run
29//! use asyncq_actix::admin_with_queues;
30//! # use asyncq::{Queue, backends::InMemoryBackend};
31//! # use actix_web::{web, App};
32//! # let queue = Queue::new(InMemoryBackend::new());
33//! App::new()
34//!     .service(
35//!         web::scope("/admin")
36//!             .configure(admin_with_queues(queue, vec!["emails".into(), "payments".into()]))
37//!     );
38//! ```
39//!
40//! # Endpoints
41//!
42//! | Method | Path | Description |
43//! |--------|------|-------------|
44//! | GET | `/admin/queues/{name}` | Stats for a queue |
45//! | GET | `/admin/queues/{name}/dlq` | Dead-letter queue (paginated) |
46//! | POST | `/admin/queues/{name}/dlq/retry-all` | Requeue all dead jobs |
47//! | DELETE | `/admin/queues/{name}/dlq/{id}` | Retry one dead job by ID |
48//! | GET | `/admin/metrics` | Prometheus text metrics |
49
50use actix_web::{
51    HttpResponse, Responder,
52    web::{self, Data, Path, Query, ServiceConfig},
53};
54use serde::{Deserialize, Serialize};
55use uuid::Uuid;
56
57use asyncq::{backend::Backend, job::QueueStats, Queue};
58
59// ── State ─────────────────────────────────────────────────────────────────────
60
61#[derive(Clone)]
62struct AdminState<B: Backend> {
63    queue: Queue<B>,
64    monitored_queues: Vec<String>,
65}
66
67// ── Admin configurator ────────────────────────────────────────────────────────
68
69/// Returns an actix-web configurator that mounts admin endpoints.
70/// Apply to a scope: `web::scope("/admin").configure(admin(queue))`.
71///
72/// The `/metrics` endpoint returns a minimal Prometheus stub.
73/// Use [`admin_with_queues`] for live per-queue gauges.
74pub fn admin<B: Backend + Clone + 'static>(
75    queue: Queue<B>,
76) -> impl Fn(&mut ServiceConfig) + Clone {
77    admin_with_queues(queue, vec![])
78}
79
80/// Returns an actix-web configurator with live Prometheus metrics for the given queues.
81pub fn admin_with_queues<B: Backend + Clone + 'static>(
82    queue: Queue<B>,
83    queues: Vec<String>,
84) -> impl Fn(&mut ServiceConfig) + Clone {
85    let state = Data::new(AdminState { queue, monitored_queues: queues });
86
87    move |cfg: &mut ServiceConfig| {
88        cfg.app_data(state.clone())
89            .route("/queues/{name}", web::get().to(queue_stats::<B>))
90            .route("/queues/{name}/dlq", web::get().to(list_dlq::<B>))
91            .route("/queues/{name}/dlq/retry-all", web::post().to(retry_all::<B>))
92            .route("/queues/{name}/dlq/{id}", web::delete().to(retry_one::<B>))
93            .route("/metrics", web::get().to(metrics::<B>));
94    }
95}
96
97// ── Handlers ──────────────────────────────────────────────────────────────────
98
99async fn queue_stats<B: Backend + Clone + 'static>(
100    path: Path<String>,
101    state: Data<AdminState<B>>,
102) -> impl Responder {
103    match state.queue.stats(&path.into_inner()).await {
104        Ok(stats) => HttpResponse::Ok().json(StatsResponse::from(stats)),
105        Err(e) => HttpResponse::InternalServerError()
106            .json(serde_json::json!({ "error": e.to_string() })),
107    }
108}
109
110#[derive(Deserialize)]
111struct Pagination {
112    #[serde(default = "default_limit")]
113    limit: i64,
114    #[serde(default)]
115    offset: i64,
116}
117fn default_limit() -> i64 { 50 }
118
119async fn list_dlq<B: Backend + Clone + 'static>(
120    path: Path<String>,
121    query: Query<Pagination>,
122    state: Data<AdminState<B>>,
123) -> impl Responder {
124    match state.queue.dead_jobs(&path.into_inner(), query.limit, query.offset).await {
125        Ok(jobs) => {
126            let items: Vec<DeadJobResponse> =
127                jobs.into_iter().map(DeadJobResponse::from).collect();
128            let count = items.len();
129            HttpResponse::Ok().json(serde_json::json!({ "jobs": items, "count": count }))
130        }
131        Err(e) => HttpResponse::InternalServerError()
132            .json(serde_json::json!({ "error": e.to_string() })),
133    }
134}
135
136async fn retry_all<B: Backend + Clone + 'static>(
137    path: Path<String>,
138    state: Data<AdminState<B>>,
139) -> impl Responder {
140    match state.queue.retry_all_dead(&path.into_inner()).await {
141        Ok(n) => HttpResponse::Ok().json(serde_json::json!({ "requeued": n })),
142        Err(e) => HttpResponse::InternalServerError()
143            .json(serde_json::json!({ "error": e.to_string() })),
144    }
145}
146
147async fn retry_one<B: Backend + Clone + 'static>(
148    path: Path<(String, String)>,
149    state: Data<AdminState<B>>,
150) -> impl Responder {
151    let (_, id_str) = path.into_inner();
152    let id = match Uuid::parse_str(&id_str) {
153        Ok(id) => id,
154        Err(_) => {
155            return HttpResponse::BadRequest()
156                .json(serde_json::json!({ "error": "invalid job id" }));
157        }
158    };
159    match state.queue.retry_dead(id).await {
160        Ok(()) => HttpResponse::NoContent().finish(),
161        Err(e) => HttpResponse::NotFound()
162            .json(serde_json::json!({ "error": e.to_string() })),
163    }
164}
165
166async fn metrics<B: Backend + Clone + 'static>(
167    state: Data<AdminState<B>>,
168) -> impl Responder {
169    let mut all_stats: Vec<(String, QueueStats)> = Vec::new();
170    for q in &state.monitored_queues {
171        if let Ok(stats) = state.queue.stats(q).await {
172            all_stats.push((q.clone(), stats));
173        }
174    }
175
176    let mut lines: Vec<String> = Vec::new();
177
178    lines.push("# HELP asyncq_jobs_pending Jobs waiting to be processed".into());
179    lines.push("# TYPE asyncq_jobs_pending gauge".into());
180    for (q, st) in &all_stats {
181        lines.push(format!("asyncq_jobs_pending{{queue=\"{}\"}} {}", q, st.pending));
182    }
183
184    lines.push("".into());
185    lines.push("# HELP asyncq_jobs_running Jobs currently being processed".into());
186    lines.push("# TYPE asyncq_jobs_running gauge".into());
187    for (q, st) in &all_stats {
188        lines.push(format!("asyncq_jobs_running{{queue=\"{}\"}} {}", q, st.running));
189    }
190
191    lines.push("".into());
192    lines.push("# HELP asyncq_jobs_dead Jobs in the dead-letter queue".into());
193    lines.push("# TYPE asyncq_jobs_dead gauge".into());
194    for (q, st) in &all_stats {
195        lines.push(format!("asyncq_jobs_dead{{queue=\"{}\"}} {}", q, st.dead));
196    }
197
198    lines.push("".into());
199    lines.push("# HELP asyncq_jobs_completed Jobs completed successfully".into());
200    lines.push("# TYPE asyncq_jobs_completed counter".into());
201    for (q, st) in &all_stats {
202        lines.push(format!("asyncq_jobs_completed{{queue=\"{}\"}} {}", q, st.completed));
203    }
204
205    lines.push("".into());
206    lines.push("# HELP asyncq_info asyncq version info".into());
207    lines.push("# TYPE asyncq_info gauge".into());
208    lines.push(format!(
209        "asyncq_info{{version=\"{}\"}} 1",
210        env!("CARGO_PKG_VERSION")
211    ));
212    lines.push("".into());
213
214    HttpResponse::Ok()
215        .content_type("text/plain; version=0.0.4; charset=utf-8")
216        .body(lines.join("\n"))
217}
218
219// ── Response types ────────────────────────────────────────────────────────────
220
221#[derive(Serialize)]
222struct StatsResponse {
223    queue: String,
224    pending: u64,
225    running: u64,
226    completed: u64,
227    failed: u64,
228    dead: u64,
229}
230
231impl From<QueueStats> for StatsResponse {
232    fn from(s: QueueStats) -> Self {
233        Self {
234            queue: s.queue,
235            pending: s.pending,
236            running: s.running,
237            completed: s.completed,
238            failed: s.failed,
239            dead: s.dead,
240        }
241    }
242}
243
244#[derive(Serialize)]
245struct DeadJobResponse {
246    id: String,
247    kind: String,
248    queue: String,
249    attempt: u32,
250    max_attempts: u32,
251    last_error: Option<String>,
252    created_at: String,
253}
254
255impl From<asyncq::job::JobRecord> for DeadJobResponse {
256    fn from(r: asyncq::job::JobRecord) -> Self {
257        Self {
258            id: r.id.to_string(),
259            kind: r.kind,
260            queue: r.queue,
261            attempt: r.attempt,
262            max_attempts: r.max_attempts,
263            last_error: r.last_error,
264            created_at: r.created_at.to_rfc3339(),
265        }
266    }
267}
268
269// ── Tests ─────────────────────────────────────────────────────────────────────
270
271#[cfg(test)]
272mod tests {
273    use super::*;
274    use actix_web::{test, web, App};
275    use asyncq::{
276        backends::InMemoryBackend, Job, JobContext, JobResult, Perform, Queue, Worker,
277    };
278    use serde::{Deserialize, Serialize};
279
280    #[derive(Job, Serialize, Deserialize)]
281    #[job(queue = "actix-test", retries = 1)]
282    struct TestJob;
283
284    impl Perform for TestJob {
285        async fn perform(self, _ctx: JobContext) -> JobResult {
286            Err(asyncq::error::JobError::discard("test discard"))
287        }
288    }
289
290    async fn test_app(queue: Queue<InMemoryBackend>) -> impl actix_web::dev::Service<
291        actix_http::Request,
292        Response = actix_web::dev::ServiceResponse,
293        Error = actix_web::Error,
294    > {
295        test::init_service(
296            App::new().service(
297                web::scope("/admin").configure(admin(queue))
298            )
299        ).await
300    }
301
302    #[actix_rt::test]
303    async fn stats_returns_200() {
304        let queue = Queue::new(InMemoryBackend::new());
305        let app = test_app(queue).await;
306        let req = test::TestRequest::get()
307            .uri("/admin/queues/actix-test")
308            .to_request();
309        let resp = test::call_service(&app, req).await;
310        assert_eq!(resp.status(), 200);
311    }
312
313    #[actix_rt::test]
314    async fn dlq_empty_returns_200_with_zero_count() {
315        let queue = Queue::new(InMemoryBackend::new());
316        let app = test_app(queue).await;
317        let req = test::TestRequest::get()
318            .uri("/admin/queues/actix-test/dlq")
319            .to_request();
320        let resp = test::call_service(&app, req).await;
321        assert_eq!(resp.status(), 200);
322        let body: serde_json::Value = test::read_body_json(resp).await;
323        assert_eq!(body["count"], 0);
324    }
325
326    #[actix_rt::test]
327    async fn dlq_shows_dead_jobs() {
328        let backend = InMemoryBackend::new();
329        let queue = Queue::new(backend.clone());
330        let app = test_app(queue.clone()).await;
331
332        queue.enqueue(TestJob).await.unwrap();
333        Worker::new(queue).register::<TestJob>().run_once().await.unwrap();
334
335        let req = test::TestRequest::get()
336            .uri("/admin/queues/actix-test/dlq")
337            .to_request();
338        let resp = test::call_service(&app, req).await;
339        let body: serde_json::Value = test::read_body_json(resp).await;
340        assert_eq!(body["count"], 1, "DLQ must show the discarded job");
341        assert_eq!(body["jobs"][0]["kind"], "TestJob");
342    }
343
344    #[actix_rt::test]
345    async fn retry_all_requeues_from_dlq() {
346        let backend = InMemoryBackend::new();
347        let queue = Queue::new(backend.clone());
348        let app = test_app(queue.clone()).await;
349
350        queue.enqueue(TestJob).await.unwrap();
351        Worker::new(queue).register::<TestJob>().run_once().await.unwrap();
352        assert_eq!(backend.dead_count("actix-test").await, 1);
353
354        let req = test::TestRequest::post()
355            .uri("/admin/queues/actix-test/dlq/retry-all")
356            .to_request();
357        let resp = test::call_service(&app, req).await;
358        assert_eq!(resp.status(), 200);
359        let body: serde_json::Value = test::read_body_json(resp).await;
360        assert_eq!(body["requeued"], 1);
361        assert_eq!(backend.dead_count("actix-test").await, 0);
362    }
363
364    #[actix_rt::test]
365    async fn metrics_returns_prometheus_format() {
366        let queue = Queue::new(InMemoryBackend::new());
367        let app = test_app(queue).await;
368        let req = test::TestRequest::get()
369            .uri("/admin/metrics")
370            .to_request();
371        let resp = test::call_service(&app, req).await;
372        assert_eq!(resp.status(), 200);
373        let ct = resp.headers().get("content-type").unwrap().to_str().unwrap();
374        assert!(ct.contains("text/plain"));
375        let body = test::read_body(resp).await;
376        let text = std::str::from_utf8(&body).unwrap();
377        assert!(text.contains("asyncq_info{version="));
378    }
379
380    #[actix_rt::test]
381    async fn metrics_with_queues_shows_live_data() {
382        let backend = InMemoryBackend::new();
383        let queue = Queue::new(backend.clone());
384        let app = test::init_service(
385            App::new().service(
386                web::scope("/admin")
387                    .configure(admin_with_queues(queue.clone(), vec!["actix-test".into()]))
388            )
389        ).await;
390
391        queue.enqueue(TestJob).await.unwrap();
392        queue.enqueue(TestJob).await.unwrap();
393
394        let req = test::TestRequest::get()
395            .uri("/admin/metrics")
396            .to_request();
397        let resp = test::call_service(&app, req).await;
398        let body = test::read_body(resp).await;
399        let text = std::str::from_utf8(&body).unwrap();
400        assert!(text.contains("asyncq_jobs_pending{queue=\"actix-test\"} 2"), "pending must be 2");
401        assert!(text.contains("asyncq_jobs_dead{queue=\"actix-test\"}"));
402    }
403}