### Install RustQueue Go SDK

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Use 'go get' to install the RustQueue Go SDK. Requires Go 1.21 or later.

```bash
go get github.com/rustqueue/rustqueue-go
```

--------------------------------

### TCP Client Quick Start

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Provides a quick start example for using the TCP client, including connecting, pushing, and acknowledging jobs over a persistent TCP connection.

```APIDOC
## TCP Client Quick Start

```go
package main

import (
    "fmt"
    "log"

    "github.com/rustqueue/rustqueue-go/rustqueue"
)

func main() {
    client := rustqueue.NewTcpClient("127.0.0.1", 6789)
    if err := client.Connect(); err != nil {
        log.Fatal(err)
    }
    defer client.Disconnect()

    // Push a job
    jobID, _ := client.Push("emails", "send-welcome", map[string]string{
        "to": "alice@example.com",
    }, nil)
    fmt.Printf("Pushed: %s\n", jobID)

    // Pull and ack
    jobs, _ := client.Pull("emails", 1)
    if len(jobs) > 0 {
        client.Ack(jobs[0].ID, nil)
    }
}
```
```

--------------------------------

### Install and Run RustQueue Server

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Installs the RustQueue CLI and starts the standalone server. This provides a REST API, TCP protocol, and web dashboard.

```bash
cargo install rustqueue
rustqueue serve
```

--------------------------------

### Install @rustqueue/client

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/node/README.md

Install the Node.js SDK using npm.

```bash
npm install @rustqueue/client
```

--------------------------------

### Start RustQueue Server with Docker

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Starts the RustQueue server using Docker Compose. Assumes Docker and Docker Compose are installed.

```bash
docker compose up -d
```

--------------------------------

### Install and Serve RustQueue

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Install RustQueue globally using cargo and start the standalone server. Alternatively, use Docker Compose for a managed deployment.

```bash
cargo install rustqueue && rustqueue serve
```

```bash
docker compose up -d
```

--------------------------------

### RustQueue "Hello World" Example

Source: https://github.com/ferax564/rustqueue/blob/main/docs/blog-examples.md

A complete, runnable example demonstrating the basic workflow of queuing, pulling, and acknowledging a background job with RustQueue. No external services are required.

```rust
use rustqueue::RustQueue;
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let rq = RustQueue::redb("./jobs.db")?.build()?;

    let id = rq.push("emails", "send-welcome",
        json!({"to": "user@example.com"}), None).await?;
    println!("Queued: {id}");

    let jobs = rq.pull("emails", 1).await?;
    println!("Processing: {}", jobs[0].name);
    rq.ack(jobs[0].id, None).await?;

    Ok(())
}
```

--------------------------------

### Run RustQueue Examples

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Command-line examples to run various RustQueue functionalities, such as basic operations, persistence, worker loops, and integration with Axum.

```bash
cargo run --example basic              # Push, pull, ack — 15 lines
cargo run --example persistent         # File-backed queue surviving restarts
cargo run --example worker             # Long-running worker loop
cargo run --example axum_background_jobs  # Background jobs in an Axum web app
```

--------------------------------

### Run Example: Basic Job Processing

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Compiles and runs the 'basic' example, which demonstrates the core functionality of pushing, pulling, and acknowledging jobs.

```bash
cargo run --example basic
```

--------------------------------

### HTTP Client Quick Start

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Initialize the HTTP client and perform basic job operations like pushing and pulling jobs.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/rustqueue/rustqueue-go/rustqueue"
)

func main() {
    client := rustqueue.NewClient("http://localhost:6790")
    ctx := context.Background()

    // Push a job
    jobID, err := client.Push(ctx, "emails", "send-welcome", map[string]string{
        "to": "alice@example.com",
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Pushed job: %s\n", jobID)

    // Pull and process
    jobs, err := client.Pull(ctx, "emails", 1)
    if err != nil {
        log.Fatal(err)
    }
    if len(jobs) > 0 {
        // Process the job...
        err = client.Ack(ctx, jobs[0].ID, map[string]bool{"sent": true})
        if err != nil {
            log.Fatal(err)
        }
    }
}
```

--------------------------------

### Commit Basic Example

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Commit message for adding the basic RustQueue example to the repository.

```git
git add examples/basic.rs
git commit -m "examples: add basic push/pull/ack example"
```

--------------------------------

### Run Example: Persistent Queue

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Compiles and runs the 'persistent' example, showcasing how jobs survive process restarts and crashes.

```bash
cargo run --example persistent
```

--------------------------------

### HTTP Client Quick Start

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Demonstrates the basic usage of the HTTP client to push, pull, and acknowledge jobs.

```APIDOC
## HTTP Client Quick Start

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/rustqueue/rustqueue-go/rustqueue"
)

func main() {
    client := rustqueue.NewClient("http://localhost:6790")
    ctx := context.Background()

    // Push a job
    jobID, err := client.Push(ctx, "emails", "send-welcome", map[string]string{
        "to": "alice@example.com",
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Pushed job: %s\n", jobID)

    // Pull and process
    jobs, err := client.Pull(ctx, "emails", 1)
    if err != nil {
        log.Fatal(err)
    }
    if len(jobs) > 0 {
        // Process the job...
        err = client.Ack(ctx, jobs[0].ID, map[string]bool{"sent": true})
        if err != nil {
            log.Fatal(err)
        }
    }
}
```
```

--------------------------------

### Clone and Run RustQueue Example

Source: https://github.com/ferax564/rustqueue/blob/main/dashboard/static/blog-crash-safe-email-queue.html

Instructions to clone the RustQueue repository, run the email notification example, and interact with the API to queue jobs and check stats.

```bash
# Clone and run
git clone https://github.com/ferax564/rustqueue.git
cd rustqueue
cargo run --example email_notifications

# In another terminal
curl -X POST http://localhost:3000/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","name":"You"}'

curl http://localhost:3000/stats
```

--------------------------------

### Full RustQueue Example

Source: https://github.com/ferax564/rustqueue/blob/main/dashboard/static/blog-background-jobs-without-redis.html

A complete example demonstrating how to initialize RustQueue, push a job, pull a job for processing, and acknowledge its completion. Jobs are persisted in './jobs.db'.

```rust
use rustqueue::RustQueue;
use serde_json::json!;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let rq = RustQueue::redb("./jobs.db")?.build()?;

    // Push a job
    let id = rq.push("emails", "send-welcome",
        json!({"to": "user@example.com"}), None).await?;
    println!("Queued: {id}");

    // Pull and process
    let jobs = rq.pull("emails", 1).await?;
    println!("Processing: {}", jobs[0].name);
    rq.ack(jobs[0].id, None).await?;

    Ok(())
}

```

--------------------------------

### Install RustQueue Python SDK

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/python/README.md

Install the RustQueue Python SDK using pip. Ensure you have Python 3.8 or later.

```bash
pip install rustqueue
```

--------------------------------

### Start RustQueue Server with Docker and Monitoring

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Starts the RustQueue server along with Prometheus and Grafana for monitoring using a specific Docker Compose file.

```bash
docker compose -f docker-compose.monitoring.yml up -d
```

--------------------------------

### Quick Start with TCP Client

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/node/README.md

Initialize the TCP client, connect to the server, and perform job operations. Remember to close the connection when done.

```typescript
import { RustQueueTcpClient } from "@rustqueue/client";

const rq = new RustQueueTcpClient("localhost", 6789);
await rq.connect();

const { id } = await rq.push("emails", "send-welcome", { to: "user@example.com" });
const [job] = await rq.pull("emails", 1);
await rq.ack(job.id);

q.close();
```

--------------------------------

### Run Example: Axum Background Jobs

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Compiles and runs the 'axum_background_jobs' example, illustrating how to integrate RustQueue for background job processing within an Axum web application.

```bash
cargo run --example axum_background_jobs
```

--------------------------------

### Build RustQueue Library

Source: https://github.com/ferax564/rustqueue/blob/main/CLAUDE.md

Initialize RustQueue as an embeddable library using the builder pattern. This example shows basic setup with a redb backend.

```rust
RustQueue::redb("./jobs.db")?.build()?
```

--------------------------------

### Run Example: Worker Loop

Source: https://github.com/ferax564/rustqueue/blob/main/README.md

Compiles and runs the 'worker' example, demonstrating a long-running worker process that continuously pulls and processes jobs.

```bash
cargo run --example worker
```

--------------------------------

### Quick Start with HTTP Client

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/node/README.md

Initialize the HTTP client and perform basic job operations like pushing, pulling, and acknowledging.

```typescript
import { RustQueueClient } from "@rustqueue/client";

const rq = new RustQueueClient("http://localhost:6790");

// Push a job
const { id } = await rq.push("emails", "send-welcome", { to: "user@example.com" });

// Pull and process
const [job] = await rq.pull("emails", 1);
console.log(`Processing: ${job.name}`);
await rq.ack(job.id);
```

--------------------------------

### Serve RustQueue

Source: https://github.com/ferax564/rustqueue/blob/main/docs/index.html

Start the RustQueue server with default configurations or custom settings via a TOML file or environment variables.

```bash
rustqueue serve
```

```bash
rustqueue serve --config rustqueue.toml
```

```bash
RUSTQUEUE_STORAGE_BACKEND=hybrid rustqueue serve
```

--------------------------------

### Install RustQueue via Cargo

Source: https://github.com/ferax564/rustqueue/blob/main/docs/index.html

Install the RustQueue CLI tool using Cargo, the Rust package manager. Alternatively, build from source or use Docker.

```bash
cargo install rustqueue
```

```bash
git clone https://github.com/ferax564/rustqueue.git
cd rustqueue
cargo build --release
```

```bash
docker compose up -d
```

--------------------------------

### Install Default Prometheus Recorder

Source: https://github.com/ferax564/rustqueue/blob/main/docs/orchestration-api.md

Integrate RustQueue with Prometheus by installing the default recorder. This allows for unified metrics collection.

```rust
rustqueue::MetricsRegistry::install_default_prometheus_if_unset()
```

--------------------------------

### Quick Start: Push and Process a Job

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/python/README.md

Initialize the RustQueue client and push a job to a queue. Then, pull and acknowledge the job. This demonstrates basic job enqueuing and processing.

```python
from rustqueue import RustQueueClient

rq = RustQueueClient("http://localhost:6790")

# Push a job
job_id = rq.push("emails", "send-welcome", {"to": "user@example.com"})

# Pull and process
jobs = rq.pull("emails", count=1)
print(f"Processing: {jobs[0]['name']}")
rq.ack(jobs[0]["id"])
```

--------------------------------

### Commit Axum Background Jobs Example - Bash

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Command to add and commit the Axum background jobs example file to version control.

```bash
git add examples/axum_background_jobs.rs
git commit -m "examples: add Axum background jobs — zero-infra web app demo"
```

--------------------------------

### Run RustQueue Server

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Start the RustQueue server locally for development or testing. Access the dashboard at http://localhost:6790/.

```bash
cargo run -- serve
```

--------------------------------

### Install External Global Recorder

Source: https://github.com/ferax564/rustqueue/blob/main/docs/orchestration-api.md

Install an externally provided global recorder for metrics. This enables platforms to unify metrics under a single recorder.

```rust
rustqueue::MetricsRegistry::install_external_recorder()
```

--------------------------------

### Compile Axum Background Jobs Example - Bash

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Command to compile the Axum background jobs example. Ensures the code is syntactically correct and all dependencies are met.

```bash
cargo build --example axum_background_jobs
```

--------------------------------

### Basic RustQueue Usage

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Provides the simplest possible example of using RustQueue, demonstrating how to push a job, pull it, and acknowledge its completion within a minimal set of lines.

```rust
use rustqueue::{Job, QueueManager};

#[tokio::main]
async fn main() {
    let mut queue = QueueManager::new().await.unwrap();

    // Push a job
    queue.push(Job::new("my_task", vec!["arg1", "arg2"])).await.unwrap();

    // Pull a job
    let job = queue.pull("my_task").await.unwrap();
    println!("Pulled job: {:?}", job);

    // Acknowledge the job
    queue.ack(job.id).await.unwrap();
}

```

--------------------------------

### Run RustQueue Server with Docker

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Commands to start the RustQueue server using Docker Compose, including an option for Prometheus and Grafana monitoring.

```bash
# Binary
cargo install rustqueue && rustqueue serve

# Docker
docker compose up -d

# Docker with Prometheus + Grafana
docker compose -f docker-compose.monitoring.yml up -d
```

--------------------------------

### Axum Background Jobs Example

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Demonstrates integrating RustQueue into an Axum web application to handle background email jobs. This example showcases how to turn 'add background jobs to your Axum app' into a minimal code change.

```rust
use axum::extract::{State, Path};
use axum::routing::get;
use axum::Router;
use rustqueue::axum_integration::{RqState, rq_layer};
use rustqueue::{Job, QueueManager};
use std::net::SocketAddr;
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    rq: Arc<QueueManager>,
}

async fn send_email(State(state): State<AppState>, Path(email)) -> String {
    let job = Job::new("send_email", vec![email.0]);
    state.rq.push(job).await.unwrap();
    "Email job queued!".to_string()
}

#[tokio::main]
async fn main() {
    let rq = Arc::new(QueueManager::new().await.unwrap());
    let app_state = AppState { rq: rq.clone() };

    let app = Router::new()
        .route("/send-email/:email", get(send_email))
        .with_state(app_state)
        .layer(rq_layer(rq)); // Add the RqState extractor and layer

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("Listening on {}", addr);
    axum::Server::bind(&addr).serve(app.into_make_service()).await.unwrap();
}

```

--------------------------------

### Run RustQueue Server

Source: https://github.com/ferax564/rustqueue/blob/main/docs/index.html

Starts the RustQueue server with default settings. It listens on HTTP port 6790 and TCP port 6789, using the redb storage backend.

```bash
$ rustqueue serve

INFO HTTP listening on 0.0.0.0:6790
INFO TCP listening on 0.0.0.0:6789
INFO Storage: redb (./data)
INFO Scheduler started (tick: 1000ms)
```

--------------------------------

### Basic Job Queue Implementation in Rust

Source: https://github.com/ferax564/rustqueue/blob/main/docs/blog/background-jobs-without-redis.html

A foundational example of a job queue using a simple in-memory Vec. Suitable for basic use cases or learning.

```rust
use std::sync::{Arc, Mutex};
use std::thread;

struct JobQueue<T> {
    jobs: Arc<Mutex<Vec<T>>>,
}

impl<T: Send + 'static> JobQueue<T> {
    fn new() -> Self {
        JobQueue { jobs: Arc::new(Mutex::new(Vec::new())) }
    }

    fn enqueue(&self, job: T) {
        let mut jobs = self.jobs.lock().unwrap();
        jobs.push(job);
    }

    fn dequeue(&self) -> Option<T> {
        let mut jobs = self.jobs.lock().unwrap();
        if jobs.is_empty() {
            None
        } else {
            Some(jobs.remove(0))
        }
    }
}

fn main() {
    let queue = JobQueue::new();

    // Enqueue some jobs
    queue.enqueue("Task 1");
    queue.enqueue("Task 2");

    // Simulate a worker thread
    let queue_clone = Arc::clone(&queue.jobs);
    let worker = thread::spawn(move || {
        loop {
            let job = queue_clone.lock().unwrap().remove(0);
            println!("Processing: {}", job);
            thread::sleep(std::time::Duration::from_secs(1));
        }
    });

    // Keep the main thread alive to allow the worker to run
    // In a real application, you'd have a more robust way to manage threads
    thread::sleep(std::time::Duration::from_secs(5));
    // worker.join().unwrap(); // This would block indefinitely in this example
}
```

--------------------------------

### Basic RustQueue Job Push/Pull

Source: https://github.com/ferax564/rustqueue/blob/main/CLAUDE.md

A simple example demonstrating how to push a job to the queue and then pull and acknowledge it. This uses the in-memory storage backend.

```rust
use rustqueue::{Job, RustQueue};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut queue = RustQueue::new().await?;

    // Push a job
    let job = Job::new("my_task", serde_json::json!({ "data": 123 }))?;
    queue.push(job).await?;

    // Pull and acknowledge a job
    if let Some(job) = queue.pull().await? {
        println!("Processing job: {:?}", job);
        queue.ack(job.id).await?;
    }

    Ok(())
}
```

--------------------------------

### Initialize RustQueue with redb

Source: https://github.com/ferax564/rustqueue/blob/main/dashboard/static/blog-background-jobs-without-redis.html

Initialize RustQueue using the redb embedded database. This setup persists jobs to disk and survives application crashes.

```rust
let rq = RustQueue::redb("./jobs.db")?.build()?;

```

--------------------------------

### RustQueue Server Deployment

Source: https://context7.com/ferax564/rustqueue/llms.txt

Commands for installing and running the RustQueue server locally or via Docker. Includes options for monitoring with Prometheus and Grafana.

```bash
# Install and start
car go install rustqueue
rustqueue serve

# Docker (HTTP :6790, TCP :6789, dashboard at /dashboard)
docker compose up -d

# Docker with Prometheus + Grafana monitoring
docker compose -f docker-compose.monitoring.yml up -d

# Prometheus metrics endpoint
curl http://localhost:6790/metrics

# Health check
curl http://localhost:6790/api/v1/health
# {"ok":true,"status":"ok","version":"0.2.0","uptime_seconds":42.1}
```

--------------------------------

### Persistent RustQueue with File Backend

Source: https://github.com/ferax564/rustqueue/blob/main/CLAUDE.md

Example of setting up RustQueue with a file-backed persistent storage using the redb backend. This ensures jobs survive application restarts.

```rust
use rustqueue::{Job, RustQueue};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Use redb for persistent storage
    let mut queue = RustQueue::redb("./jobs.db")?.build()?;

    // Push a job
    let job = Job::new("persistent_task", serde_json::json!({ "data": 456 }))?;
    queue.push(job).await?;

    // Pull and acknowledge a job
    if let Some(job) = queue.pull().await? {
        println!("Processing persistent job: {:?}", job);
        queue.ack(job.id).await?;
    }

    Ok(())
}
```

--------------------------------

### Run RustQueue as a Server

Source: https://github.com/ferax564/rustqueue/blob/main/dashboard/static/landing.html

This command starts the RustQueue engine as a standalone server, enabling language-agnostic access to your job queue. It uses the same data file as the embedded library.

```bash
rustqueue serve --storage ./jobs.db
```

--------------------------------

### RustQueue Growth Stages

Source: https://github.com/ferax564/rustqueue/blob/main/docs/blog-examples.md

Illustrates the evolution of using RustQueue, starting as an embedded library within an application, progressing to a standalone server, and finally supporting multi-language workers.

```rust
Day 1: Library in your app
─────────────────────────
let rq = RustQueue::redb("./jobs.db")?.build()?;
rq.push("emails", "welcome", data, None).await?;
```

```bash
Day 30: Same data, standalone server
─────────────────────────────────────
$ rustqueue serve --storage ./jobs.db
```

```javascript
Day 60: Multi-language workers
──────────────────────────────
// Node.js worker
const rq = new RustQueueClient("http://localhost:6790");
const [job] = await rq.pull("emails", 1);
await sendEmail(job.data.to);
await rq.ack(job.id);
```

```python
# Python analytics worker
rq = RustQueueClient("http://localhost:6790")
jobs = rq.pull("analytics", count=10)
for job in jobs:
    process(job["data"])
    rq.ack(job["id"])
```

--------------------------------

### TCP Client Quick Start

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Initialize the TCP client, connect to the server, and perform basic job operations like pushing and pulling jobs. Ensure to disconnect when done.

```go
package main

import (
    "fmt"
    "log"

    "github.com/rustqueue/rustqueue-go/rustqueue"
)

func main() {
    client := rustqueue.NewTcpClient("127.0.0.1", 6789)
    if err := client.Connect(); err != nil {
        log.Fatal(err)
    }
    defer client.Disconnect()

    // Push a job
    jobID, _ := client.Push("emails", "send-welcome", map[string]string{
        "to": "alice@example.com",
    }, nil)
    fmt.Printf("Pushed: %s\n", jobID)

    // Pull and ack
    jobs, _ := client.Pull("emails", 1)
    if len(jobs) > 0 {
        client.Ack(jobs[0].ID, nil)
    }
}
```

--------------------------------

### Install External Prometheus Recorder

Source: https://github.com/ferax564/rustqueue/blob/main/docs/orchestration-api.md

Use an externally created Prometheus recorder for metrics. This is useful for platforms that manage their own Prometheus setup.

```rust
rustqueue::MetricsRegistry::install_external_prometheus_recorder()
```

--------------------------------

### Get Queue Size

Source: https://github.com/ferax564/rustqueue/blob/main/docs/examples.html

Shows how to get the current number of elements in the queue. This can be used for monitoring or control flow.

```rust
use rustqueue::queue::Queue;

fn main() {
    let mut queue = Queue::new();
    assert_eq!(queue.len(), 0);

    queue.enqueue(1);
    queue.enqueue(2);
    assert_eq!(queue.len(), 2);
}
```

--------------------------------

### Commit Persistent Example

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Commit message for adding the persistent RustQueue example, highlighting its ability to survive process restarts.

```git
git add examples/persistent.rs
git commit -m "examples: add persistent queue example — survives restarts"
```

--------------------------------

### Client Initialization

Source: https://context7.com/ferax564/rustqueue/llms.txt

Demonstrates how to create a new RustQueue client with various configuration options.

```APIDOC
## Client Initialization

### Description
Initialize the RustQueue client with the base URL and optional configuration settings.

### Options
- `WithToken(token string)`: Set an authentication token.
- `WithTimeout(timeout time.Duration)`: Set a request timeout.
- `WithHTTPClient(client *http.Client)`: Provide a custom HTTP client.

### Example
```go
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithToken("secret"),
    rustqueue.WithTimeout(10*time.Second),
)
```
```

--------------------------------

### NewTcpClient and Connection

Source: https://context7.com/ferax564/rustqueue/llms.txt

Demonstrates how to create a new TCP client with various options and establish a connection.

```APIDOC
## Create TCP Client

### Description
Creates a new TCP client instance with optional configurations.

### Method Signature
`rustqueue.NewTcpClient(host string, port int, opts ...rustqueue.TcpClientOption) *rustqueue.TcpClient`

### Options
- `WithTcpToken(token string)`: Sets the TCP token for authentication.
- `WithAutoReconnect(reconnect bool)`: Enables or disables automatic reconnection.
- `WithMaxReconnectAttempts(attempts int)`: Sets the maximum number of reconnect attempts.
- `WithReconnectDelay(delayMs int)`: Sets the delay in milliseconds between reconnect attempts.

### Example Usage
```go
client := rustqueue.NewTcpClient("127.0.0.1", 6789,
    rustqueue.WithTcpToken("secret"),
    rustqueue.WithAutoReconnect(true),
    rustqueue.WithMaxReconnectAttempts(20),
    rustqueue.WithReconnectDelay(500),
)
if err := client.Connect(); err != nil {
    log.Fatal(err)
}
defer client.Disconnect()
```
```

--------------------------------

### Install RustQueue Standalone Server

Source: https://github.com/ferax564/rustqueue/blob/main/dashboard/static/landing.html

Install the RustQueue standalone server using cargo. This allows you to run RustQueue without integrating it directly into your Rust application.

```bash
# Or as a standalone server
cargo install rustqueue && rustqueue serve
```

--------------------------------

### RustQueue Builder and Storage Backends

Source: https://context7.com/ferax564/rustqueue/llms.txt

Demonstrates how to create a RustQueue instance using different storage backends like in-memory, persistent redb, and hybrid storage. It shows the use of builder entry points and the `.build()` method.

```APIDOC
## RustQueue Builder and Storage Backends

`RustQueue::memory()`, `RustQueue::redb(path)`, and `RustQueue::hybrid(path)` are builder entry points for creating a `RustQueue` instance. `.build()` finalizes construction. The builder accepts optional write-coalescing config, hybrid storage snapshot tuning, and an attached `WorkerRegistry` for plugin dispatch.

```rust
use rustqueue::{RustQueue, JobOptions};
use rustqueue::storage::{BufferedRedbConfig, HybridConfig};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // In-memory (tests / ephemeral workloads)
    let _mem = RustQueue::memory().build()?;

    // Persistent redb file — crash-safe, zero config
    let rq = RustQueue::redb("./jobs.db")?.build()?;

    // Hybrid: memory hot path + periodic redb snapshots (high throughput)
    let _hybrid = RustQueue::hybrid("./hybrid.db")?
        .with_hybrid_config(HybridConfig::default())
        .build()?;

    // With write coalescing for batched disk flushes
    let _coalesced = RustQueue::redb("./coalesced.db")?
        .with_write_coalescing(BufferedRedbConfig::default())
        .build()?;

    Ok(())
}
```
```

--------------------------------

### HTTP Client Configuration Options

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Configure the HTTP client with authentication tokens, custom timeouts, or a custom HTTP client instance.

```go
// With authentication
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithToken("my-secret-token"),
)

// With custom timeout
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithTimeout(10 * time.Second),
)

// With custom HTTP client
httpClient := &http.Client{Timeout: 5 * time.Second}
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithHTTPClient(httpClient),
)
```

--------------------------------

### Persistent Queue Example

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Illustrates setting up a file-backed job queue that persists its state across application restarts. This is useful for ensuring jobs are not lost even if the application crashes or is shut down.

```rust
use rustqueue::QueueManager;

#[tokio::main]
async fn main() {
    // QueueManager::new() defaults to a file-backed queue in ./rustqueue.db
    let mut queue = QueueManager::new().await.unwrap();

    // Push a job
    queue.push(rustqueue::Job::new("my_task", vec!["arg1", "arg2"])).await.unwrap();

    // Pull a job
    let job = queue.pull("my_task").await.unwrap();
    println!("Pulled job: {:?}", job);

    // Acknowledge the job
    queue.ack(job.id).await.unwrap();
}

```

--------------------------------

### RustQueue Builder Entry Points

Source: https://context7.com/ferax564/rustqueue/llms.txt

Demonstrates how to create a RustQueue instance using different storage backends: in-memory, persistent redb file, and hybrid storage. Includes options for write coalescing and attaching a WorkerRegistry.

```rust
use rustqueue::{RustQueue, JobOptions};
use rustqueue::storage::{BufferedRedbConfig, HybridConfig};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // In-memory (tests / ephemeral workloads)
    let _mem = RustQueue::memory().build()?;

    // Persistent redb file — crash-safe, zero config
    let rq = RustQueue::redb("./jobs.db")?.build()?;

    // Hybrid: memory hot path + periodic redb snapshots (high throughput)
    let _hybrid = RustQueue::hybrid("./hybrid.db")?
        .with_hybrid_config(HybridConfig::default())
        .build()?;

    // With write coalescing for batched disk flushes
    let _coalesced = RustQueue::redb("./coalesced.db")?
        .with_write_coalescing(BufferedRedbConfig::default())
        .build()?;

    Ok(())
}
```

--------------------------------

### New Crate-Level Doc Comment with Example

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

This is the new crate-level doc comment for RustQueue. It highlights the 'background jobs without infrastructure' angle and includes a runnable code example demonstrating basic usage.

```rust
!\n# RustQueue — Background jobs without infrastructure\n\nAdd persistent, crash-safe background job processing to any Rust application.\nNo Redis. No RabbitMQ. No external services.\n\n```no_run\nuse rustqueue::RustQueue;\nuse serde_json::json;\n\n# async fn example() -> anyhow::Result<()> {\nlet rq = RustQueue::redb("./jobs.db")?.build()?;\nlet id = rq.push("emails", "send-welcome", json!({"to": "a@b.com"}), None).await?;\nlet jobs = rq.pull("emails", 1).await?;\nrq.ack(jobs[0].id, None).await?;\n# Ok(())\n# }\n```\n\nJobs persist to an embedded ACID database. They survive crashes and restarts.\nWhen you outgrow embedded mode, run the same engine as a standalone server\nwith `rustqueue serve`.\n
```

--------------------------------

### Get Health Status

Source: https://context7.com/ferax564/rustqueue/llms.txt

Check the health and operational status of the RustQueue service.

```APIDOC
## Get Health Status

### Description
Retrieves the health status of the RustQueue service, including its version and uptime.

### Method
`Health(ctx context.Context) (*Health, error)`

### Response
- `*Health`:
  - `Status` (string): The current health status (e.g., "ok").
  - `Version` (string): The version of the RustQueue service.
  - `UptimeSeconds` (float64): The duration in seconds the service has been running.

### Example
```go
health, _ := client.Health(ctx)
```
```

--------------------------------

### Get Queue Statistics

Source: https://context7.com/ferax564/rustqueue/llms.txt

Retrieve statistics about the number of waiting and active jobs in a queue.

```APIDOC
## Get Queue Statistics

### Description
Fetches the current number of jobs waiting to be processed and jobs currently being processed in a specific queue.

### Method
`GetQueueStats(ctx context.Context, queue string) (*QueueStats, error)`

### Parameters
- `ctx` (context.Context): The request context.
- `queue` (string): The name of the queue.

### Response
- `*QueueStats`:
  - `Waiting` (int): The number of jobs waiting in the queue.
  - `Active` (int): The number of jobs currently being processed.

### Example
```go
stats, _ := client.GetQueueStats(ctx, "emails")
```
```

--------------------------------

### Get Dead-Letter Queue Jobs

Source: https://context7.com/ferax564/rustqueue/llms.txt

Inspect jobs that have failed repeatedly and been moved to the dead-letter queue.

```APIDOC
## Get Dead-Letter Queue Jobs

### Description
Retrieves jobs from the dead-letter queue (DLQ), which typically contains jobs that have failed persistently.

### Method
`GetDlqJobs(ctx context.Context, queue string, limit int) ([]Job, error)`

### Parameters
- `ctx` (context.Context): The request context.
- `queue` (string): The name of the queue to inspect.
- `limit` (int): The maximum number of DLQ jobs to retrieve.

### Response
- `[]Job`: A slice of job objects from the DLQ.

### Example
```go
dlqJobs, _ := client.GetDlqJobs(ctx, "emails", 50)
```
```

--------------------------------

### Get Job Details (HTTP)

Source: https://github.com/ferax564/rustqueue/blob/main/docs/orchestration-api.md

HTTP endpoint to retrieve the full details of a specific job.

```http
GET /api/v1/jobs/{id}
```

--------------------------------

### Configure TCP Client

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Instantiate a new TCP client with custom options like authentication token, auto-reconnect, and reconnect attempt limits.

```go
client := rustqueue.NewTcpClient("127.0.0.1", 6789,
    rustqueue.WithTcpToken("my-secret-token"),
    rustqueue.WithAutoReconnect(true),
    rustqueue.WithMaxReconnectAttempts(20),
    rustqueue.WithReconnectDelay(500), // base delay in ms (exponential backoff)
)

```

--------------------------------

### HTTP Client Health Check

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Perform a health check on the RustQueue server to get its status, version, and uptime.

```go
health, _ := client.Health(ctx)
fmt.Printf("Status: %s, Version: %s, Uptime: %.0fs\n",
    health.Status, health.Version, health.UptimeSeconds)
```

--------------------------------

### Queue Operations

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/python/README.md

Functions for interacting with queues, including listing queues, getting statistics, and accessing the dead-letter queue.

```APIDOC
## list_queues

### Description
List all available queues.

### Signature
`list_queues()`

## queue_stats

### Description
Get statistics for a specific queue.

### Signature
`queue_stats(queue: str)`

## dlq

### Description
List jobs that have been moved to the dead-letter queue.

### Signature
`dlq(queue: str, limit: int = 20)`
```

--------------------------------

### Basic RustQueue Example

Source: https://github.com/ferax564/rustqueue/blob/main/internal/superpowers/plans/2026-03-28-blue-ocean-repositioning.md

Demonstrates the simplest RustQueue usage: pushing a job, pulling it, and acknowledging its completion using the in-memory backend. This is suitable for trying out the library's core functionality.

```rust
//! Simplest RustQueue usage: push a job, pull it, acknowledge it.
//!
//! Run with: `cargo run --example basic`

use rustqueue::{RustQueue, JobOptions};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // In-memory backend — great for trying things out.
    // Switch to RustQueue::redb("./jobs.db")? for persistence.
    let rq = RustQueue::memory().build()?;

    // Push a job onto the "emails" queue
    let id = rq.push(
        "emails",
        "send-welcome",
        json!({"to": "user@example.com", "template": "welcome"}),
        None,
    ).await?;
    println!("Pushed job: {id}");

    // Pull one job from the queue
    let jobs = rq.pull("emails", 1).await?;
    let job = &jobs[0];
    println!("Processing: {} (data: {})", job.name, job.data);

    // Acknowledge completion
    rq.ack(job.id, None).await?;
    println!("Done!");

    Ok(())
}

```

--------------------------------

### Get Queue Statistics (Python)

Source: https://context7.com/ferax564/rustqueue/llms.txt

Fetches the current statistics for a specified queue, including waiting and active job counts.

```python
stats = client.get_queue_stats("emails")
print(f"Waiting: {stats['waiting']}, Active: {stats['active']}")
```

--------------------------------

### HTTP Client Configuration Options

Source: https://github.com/ferax564/rustqueue/blob/main/sdk/go/README.md

Shows how to configure the HTTP client with authentication tokens, custom timeouts, or a custom HTTP client.

```APIDOC
## HTTP Client Configuration

```go
// With authentication
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithToken("my-secret-token"),
)

// With custom timeout
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithTimeout(10 * time.Second),
)

// With custom HTTP client
httpClient := &http.Client{Timeout: 5 * time.Second}
client := rustqueue.NewClient("http://localhost:6790",
    rustqueue.WithHTTPClient(httpClient),
)
```
```

--------------------------------

### Get Flow Details

Source: https://github.com/ferax564/rustqueue/blob/main/docs/orchestration-api.md

Retrieves all jobs within a specified flow, along with summary counts categorized by their current state.

```APIDOC
## GET /api/v1/flows/{flow_id}

### Description
Returns all jobs in the flow with summary counts by state.

### Method
GET

### Endpoint
/api/v1/flows/{flow_id}
```

--------------------------------

### Get Job Details

Source: https://github.com/ferax564/rustqueue/blob/main/docs/orchestration-api.md

Retrieves the full details of a specific job, including its state, metadata, data, results, and logs.

```APIDOC
## GET /api/v1/jobs/{id}

### Description
Retrieves the complete job object, including all associated information such as `metadata`, `data`, `result`, `state`, `progress`, and `logs`.

### Method
GET

### Endpoint
`/api/v1/jobs/{id}`

### Response
#### Success Response (200)
- **job** (object) - The full job object.
  - Contains fields like `id`, `name`, `data`, `metadata`, `state`, `result`, `progress`, `logs`, etc.

### Response Example
```json
{
  "job": {
    "id": "<uuid-v7>",
    "name": "compile-project",
    "data": {"repo": "acme/app"},
    "metadata": {"workflow_id": "wf-1", "step_id": "build"},
    "state": "Completed",
    "result": {"exit_code": 0},
    "progress": 100,
    "logs": [{"timestamp": "...", "message": "Build successful."}]
  }
}
```
```

--------------------------------

### Build and Test RustQueue

Source: https://github.com/ferax564/rustqueue/blob/main/CONTRIBUTING.md

Commands to build, test, lint, and format the RustQueue project. Use `--features` to include specific backend tests.

```bash
cargo build                          # Debug build
cargo test                           # Run all tests (default features)
cargo test --features sqlite         # Include SQLite backend tests
cargo clippy                         # Lint
cargo fmt --check                    # Format check
```