# QRush Separate Process Quick Reference

## TL;DR

**Current**: Workers run inside your web server process (integrated mode)  
**Goal**: Workers run in separate `qrush-engine` process (separate process mode)

## Architecture Comparison

### Current (Integrated)
```
Web Server Process
├── HTTP Server
├── Job Enqueue
└── Job Workers  ← Runs here
```

### Separate Process Mode
```
Web Server Process          qrush-engine Process
├── HTTP Server             ├── Job Workers
└── Job Enqueue  ──Redis──▶ └── Cron Scheduler
```

## Quick Setup Steps

### 1. Create Shared Jobs Module
```rust
// test/src/shared_jobs/mod.rs
pub mod notify_user_job;
pub mod daily_report_job;

use qrush_engine::registry::register_job;
use crate::shared_jobs::notify_user_job::NotifyUserJob;
use crate::shared_jobs::daily_report_job::DailyReportJob;

pub fn register_all_jobs() {
    register_job(NotifyUserJob::name(), NotifyUserJob::handler);
    register_job(DailyReportJob::name(), DailyReportJob::handler);
}
```

### 2. Create Engine Binary
```rust
// test/src/bin/qrush_engine.rs
use qrush_engine::config::QueueConfig;
use test::shared_jobs::register_all_jobs;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    register_all_jobs();  // ← MUST be before initialize
    
    let queues = vec![
        QueueConfig::new("default", 5, 1),
        QueueConfig::new("critical", 10, 0),
    ];
    
    QueueConfig::initialize(redis_url, queues).await?;
    
    // Wait for Ctrl+C
    tokio::signal::ctrl_c().await?;
    Ok(())
}
```

### 3. Update main.rs
```rust
// REMOVE these lines:
// QrushIntegrated::initialize(None).await;
// QrushEngine::initialize(None).await;

// ADD this:
use crate::shared_jobs::register_all_jobs;
register_all_jobs();  // For enqueue serialization
```

### 4. Update Cargo.toml
```toml
[[bin]]
name = "qrush_engine"
path = "src/bin/qrush_engine.rs"
```

### 5. Run Both Processes
```bash
# Terminal 1: Web Server
cargo run

# Terminal 2: QRush Engine  
cargo run --bin qrush_engine
```

## Command Reference

### Using Built-in qrush-engine Binary
```bash
# From qrush-engine crate
cd /Users/snm/ws/xsnm/ws/crates/qrush-engine
cargo build --release --bin qrush-engine

# Run with custom queues
./target/release/qrush-engine \
  --redis redis://127.0.0.1:6379 \
  --queues default:5,critical:10:0
```

### Environment Variables
```bash
REDIS_URL=redis://127.0.0.1:6379  # Required for both
RUST_LOG=info                     # Optional, for logging
```

## Key Differences

| Task | Integrated Mode | Separate Process |
|------|----------------|------------------|
| **Initialize Workers** | `QrushIntegrated::initialize()` | `QueueConfig::initialize()` in engine binary |
| **Register Jobs** | In `initialize()` | In engine binary before `initialize()` |
| **Enqueue Jobs** | `qrush::queue::enqueue()` | `qrush_engine::queue::enqueue()` |
| **Process Jobs** | Same process | Separate process |
| **Web Routes** | `/qrush/metrics` in web server | Optional in engine |

## Common Issues

### ❌ Jobs not processing
- **Fix**: Ensure `register_all_jobs()` is called BEFORE `QueueConfig::initialize()`

### ❌ "Job not registered" error
- **Fix**: Register jobs in both web server (for enqueue) and engine (for processing)

### ❌ Jobs enqueued but not found
- **Fix**: Check Redis connection, verify queue names match

### ❌ Engine crashes on start
- **Fix**: Check Redis is running: `redis-cli ping`

## File Checklist

- [ ] Create `test/src/shared_jobs/mod.rs`
- [ ] Create `test/src/shared_jobs/notify_user_job.rs`
- [ ] Create `test/src/shared_jobs/daily_report_job.rs`
- [ ] Create `test/src/bin/qrush_engine.rs`
- [ ] Update `test/src/main.rs` (remove worker init)
- [ ] Update `test/Cargo.toml` (add binary)
- [ ] Update `test/src/services/data_service.rs` (use `qrush_engine::queue`)

## Production Deployment

### systemd Example
```ini
# /etc/systemd/system/qrush-engine.service
[Unit]
Description=QRush Engine Worker
After=redis.service

[Service]
Type=simple
ExecStart=/path/to/qrush_engine
Environment="REDIS_URL=redis://127.0.0.1:6379"
Restart=always

[Install]
WantedBy=multi-user.target
```

### Docker Compose Example
```yaml
services:
  web:
    build: .
    command: cargo run --release
  
  qrush-engine:
    build: .
    command: cargo run --release --bin qrush_engine
    deploy:
      replicas: 2  # Scale workers
```

## Benefits

✅ **Resource Isolation** - Web and workers don't compete  
✅ **Independent Scaling** - Scale workers separately  
✅ **Better Fault Tolerance** - Worker crashes don't affect web  
✅ **Production Ready** - Matches common worker process patterns

## See Also

- `SIDEKIQ_STYLE_GUIDE.md` - Detailed guide (separate process mode)
- `EXAMPLE_CHANGES.md` - Complete code examples
- `README.md` - QRush documentation
