1use 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#[derive(Clone)]
62struct AdminState<B: Backend> {
63 queue: Queue<B>,
64 monitored_queues: Vec<String>,
65}
66
67pub fn admin<B: Backend + Clone + 'static>(
75 queue: Queue<B>,
76) -> impl Fn(&mut ServiceConfig) + Clone {
77 admin_with_queues(queue, vec![])
78}
79
80pub 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
97async 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#[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#[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}