QRush Integration Guide (Actix Web)

This guide shows how to integrate QRush into an Actix Web application — exactly like your test app:

• Redis-backed queue
• Workers & delayed mover
• Jobs with Job trait
• Metrics UI mounted at /qrush/metrics
• Optional Basic Auth for the metrics panel
• Seconds-based scheduling (enqueue_in(job, delay_secs))

1) Add dependencies

# Cargo.toml
[dependencies]
actix-web = "4"
dotenv = "0.15"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
serde = { version = "1", features = ["derive"] }
anyhow = "1"
async-trait = "0.1"

# the queue
qrush = "<latest>"

2) Environment variables

# REQUIRED Redis connection
export REDIS_URL="redis://127.0.0.1:6379"

# REQUIRED Basic Auth for metrics (username:password)
export QRUSH_BASIC_AUTH="admin:strongpassword"

# Optional: server bind (used by your test app)
export SERVER_ADDRESS="0.0.0.0:8080"

3) Define a job

Implement the Job trait for your payload. Keep name() and queue() consistent with registration.

// /test/src/jobs/notify_user.rs
use qrush::job::Job;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};

#[derive(Clone, Serialize, Deserialize)]
pub struct NotifyUser {
    pub user_id: String,
    pub message: String,
}

#[async_trait]
impl Job for NotifyUser {
    async fn perform(&self) -> anyhow::Result<()> {
        println!("Notify {} -> {}", self.user_id, self.message);
        Ok(())
    }

    fn name(&self) -> &'static str { "NotifyUser" }
    fn queue(&self) -> &'static str { "default" }
}

4) QRush initializer (as in your test app)

This sets optional Basic Auth, registers jobs, initializes queues in a background task, then waits until ready.

// /test/src/jobs/qrush.rs
use actix_web::web;
use std::sync::Arc;
use tokio::sync::Notify;
use qrush::config::{QueueConfig, QUEUE_INITIALIZED, set_basic_auth, QrushBasicAuthConfig};
use qrush::registry::register_job;
use crate::jobs::notify_user::NotifyUser;
use qrush::routes::metrics_route::qrush_metrics_routes;

pub struct QrushInitializer;

impl QrushInitializer {
    pub async fn initialize(basic_auth: Option<QrushBasicAuthConfig>) {
        let queue_notify = Arc::new(Notify::new());

        // Basic Auth from param or env (QRUSH_BASIC_AUTH="user:pass")
        let basic_auth = basic_auth.or_else(|| {
            std::env::var("QRUSH_BASIC_AUTH").ok().and_then(|auth| {
                let parts: Vec<&str> = auth.splitn(2, ':').collect();
                (parts.len() == 2).then(|| QrushBasicAuthConfig {
                    username: parts[0].to_string(),
                    password: parts[1].to_string(),
                })
            })
        });
        let _ = set_basic_auth(basic_auth);

        // Expose the notify handle if other parts need it
        let _ = QUEUE_INITIALIZED.set(queue_notify.clone());

        // Register job handlers
        register_job(NotifyUser::name(), NotifyUser::handler);

        // Initialize queues in the background
        tokio::spawn({
            let queue_notify = queue_notify.clone();
            async move {
                let redis_url = std::env::var("REDIS_URL")
                    .unwrap_or_else(|_| "redis://127.0.0.1:6379".to_string());

                // queue_name, concurrency, priority
                let queues = vec![
                    QueueConfig::new("default", 5, 1),
                    QueueConfig::new("critical", 10, 0),
                ];

                if let Err(err) = QueueConfig::initialize(redis_url, queues).await {
                    eprintln!("❌ Failed to initialize qrush: {:?}", err);
                } else {
                    println!("✅ qrush started successfully");
                    queue_notify.notify_waiters();
                }
            }
        });

        // Wait until init completes
        queue_notify.notified().await;
        println!("🚀 Queue initialization complete. Continuing main logic...");
    }

    pub fn get_qrush_metrics_routes(cfg: &mut web::ServiceConfig) {
        qrush_metrics_routes(cfg)
    }
}

5) Wire it into main.rs

• Initialize QRush (awaits until queues are ready).
• Mount metrics under /qrush/metrics.
• Seed a few jobs to verify the dashboard.

// /test/src/main.rs
use actix_web::{web, App, HttpServer, HttpResponse, Responder, middleware::Logger};
use dotenv::dotenv;
use std::env;
use crate::jobs::qrush::QrushInitializer;
use qrush::queue::{enqueue, enqueue_in};
use crate::jobs::notify_user::NotifyUser;

async fn health_check() -> impl Responder {
    HttpResponse::Ok().body("Test App Backend is Running!")
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    dotenv().ok();

    // Initialize QRush (wait until queues are up)
    QrushInitializer::initialize(None).await;

    // Seed some jobs
    let _ = enqueue(NotifyUser {
        user_id: "abc".into(),
        message: "Hello from Qrush!".into(),
    }).await;

    let _ = enqueue_in(NotifyUser {
        user_id: "abc".into(),
        message: "Delayed job after 60s".into(),
    }, 60).await;

    let _ = enqueue_in(NotifyUser {
        user_id: "abc".into(),
        message: "Delayed job after 120s".into(),
    }, 120).await;

    let _ = enqueue_in(NotifyUser {
        user_id: "abc".into(),
        message: "Delayed job after 180s".into(),
    }, 180).await;

    // Bind address
    let server_address = env::var("SERVER_ADDRESS")
        .unwrap_or_else(|_| "0.0.0.0:8080".to_string());

    HttpServer::new(move || {
        App::new()
            .wrap(Logger::default())
            // Metrics UI
            .service(
                web::scope("/qrush")
                    .configure(|cfg| QrushInitializer::get_qrush_metrics_routes(cfg))
            )
            .route("/", web::get().to(health_check))
            .route("/health", web::get().to(health_check))
    })
    .bind(server_address)?
    .run()
    .await
}

6) Enqueue from anywhere

use qrush::queue::{enqueue, enqueue_in};

let _ = enqueue(NotifyUser {
    user_id: "u-1".into(),
    message: "Immediate",
}).await;

let _ = enqueue_in(NotifyUser {
    user_id: "u-2".into(),
    message: "Later",
}, 300).await; // in 300 seconds

7) Run

# Start Redis
redis-server        # or: docker run -p 6379:6379 redis:7

# Run your service
cargo run

Open:

• Dashboard: http://localhost:8080/qrush/metrics
• Per-queue: http://localhost:8080/qrush/metrics/queues/default
• Health: http://localhost:8080/qrush/metrics/health

If you set QRUSH_BASIC_AUTH, include Basic auth in requests:

curl -u admin:strongpassword http://localhost:8080/qrush/metrics/health

8) Endpoints (under /qrush/metrics)

• GET / — queues overview (success / failed / retry / pending)
• GET /queues/{queue} — jobs in a queue
• GET /queues/{queue}/export — CSV export
• GET /extras/delayed — delayed jobs
• GET /extras/dead — dead jobs
• GET /extras/scheduled — scheduled jobs
• GET /extras/workers — worker status
• GET /health — health probe
• POST /jobs/action — job actions ({"action":"retry|delete|queue","job_id":"..."})

Notes & tips

• Scheduling: enqueue_in(job, delay_secs) uses seconds (integer), matching your test app.
• QueueConfig: you used two queues (default, critical) with different concurrency/priority; tune as needed.
• Register jobs before init: ensure register_job(name, handler) runs before workers start.
• Templates: metrics UI uses Tera templates. If a Tera parse error occurs, restart the process (once_cell poison).
• Security: protect metrics with Basic Auth via QRUSH_BASIC_AUTH or your own middleware.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Actix Web - Fast, powerful web framework
• UI powered by TailwindCSS - Utility-first CSS framework

📞 Support

• 📖 How it works
• 📖 Support
• 📖 Documentation
• 💬 Discussions
• 🐛 Issues
• 📧 Email: sxmmaurya@gmail.com

Made with ❤️ by the rustacean360 (Snm Maurya)