Crate ferro_queue 

Ferro Queue

Background job queue system for the Ferro framework.

Provides a Laravel-inspired queue system backed by the application database:

• SQLite (BEGIN IMMEDIATE) and Postgres (FOR UPDATE SKIP LOCKED) atomic claim
• Job delays, retries with full-jitter exponential backoff, and idempotency keys
• Multiple named queues processed in priority order
• Panic-isolated worker loop with SIGTERM graceful shutdown
• Tenant-scoped job execution

Example

use ferro_queue::{Job, Queue, QueueConfig, WorkerLoop, WorkerConfig, Queueable};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct SendEmail {
    to: String,
    subject: String,
}

#[async_trait::async_trait]
impl Job for SendEmail {
    async fn handle(&self) -> Result<(), ferro_queue::Error> {
        println!("Sending email to {}: {}", self.to, self.subject);
        Ok(())
    }
}

// Initialise the queue at application start (once):
// Queue::init(db_connection).await?;

// Dispatch a job (sync mode by default; set QUEUE_CONNECTION=db for background):
SendEmail { to: "user@example.com".into(), subject: "Hello".into() }
    .dispatch()
    .await?;

// Dispatch with delay
SendEmail { to: "user@example.com".into(), subject: "Reminder".into() }
    .delay(std::time::Duration::from_secs(60))
    .on_queue("emails")
    .dispatch()
    .await?;

Structs

CreateJobsTable

Migration that creates the jobs table and its indexes.

FailedJobInfo

A failed job with the error message.

JobInfo

Summary of a single job for introspection.

JobPayload

Serialized job payload stored in the queue.

JobRow

A row read from the jobs table during a claim operation.

PendingDispatch

A pending job dispatch.

Queue

Global handle to the queue’s database connection.

QueueConfig

Queue system configuration.

QueueStats

Aggregate stats across all queues.

SingleQueueStats

Per-queue pending/delayed counts.

WorkerConfig

Worker configuration.

WorkerLoop

DB-backed queue worker.

Enums

Error

Errors that can occur in the queue system.

JobState

Job status for introspection queries.

Traits

Job

A job that can be executed by a queue worker.

Queueable

Trait for types that can be dispatched to a queue.

TenantScopeProvider

Injects tenant scope around job execution.

Functions

claim

Atomically claim one pending job from queue.

delete_job

Delete a successfully-completed job row (D-04 delete-on-success).

dispatch

Dispatch a job using the global queue.

dispatch_later

Dispatch a job with a delay.

dispatch_to

Dispatch a job to a specific queue.

enqueue

Insert a new job into the queue.

fail_job

Park a job as failed with an error message, recording the failure time.

get_delayed_jobs

Return up to limit delayed (not-yet-eligible) jobs in queue.

get_failed_jobs

Return up to limit failed jobs (across all queues).

get_pending_jobs

Return up to limit pending (immediately eligible) jobs in queue.

get_stats

Return aggregate pending/delayed counts per queue and the total failed count.

reap_startup_claims

Park leftover claimed rows on queues as failed at worker startup.

reaper

Re-queue claimed rows that have been held longer than visibility_timeout.

register_tenant_capture_hook

Register the tenant capture hook.

release_job

Reset a job to pending, bump its attempt count, and set a new available_at (used by the worker after a retryable failure).

requeue_claimed_by

Reset all jobs claimed by worker_id back to pending (D-10 shutdown re-queue — called by the worker loop before the process exits).

Type Aliases

Worker

Type alias for API continuity with callers that use the old Worker name.

Attribute Macros

async_trait

Re-export async_trait for convenience