Trait JobQueue 

pub trait JobQueue:
    Send
    + Sync
    + Clone {
    // Required methods
    fn create_job(
        &self,
        request: CreateJobRequest,
    ) -> impl Future<Output = Result<HarvestJob, AppError>> + Send;
    fn claim_job(
        &self,
        worker_id: &str,
    ) -> impl Future<Output = Result<Option<HarvestJob>, AppError>> + Send;
    fn complete_job(
        &self,
        job_id: Uuid,
        stats: SyncStats,
    ) -> impl Future<Output = Result<(), AppError>> + Send;
    fn fail_job(
        &self,
        job_id: Uuid,
        error: &str,
        next_retry_at: Option<DateTime<Utc>>,
    ) -> impl Future<Output = Result<(), AppError>> + Send;
    fn cancel_job(
        &self,
        job_id: Uuid,
        stats: Option<SyncStats>,
    ) -> impl Future<Output = Result<(), AppError>> + Send;
    fn get_job(
        &self,
        job_id: Uuid,
    ) -> impl Future<Output = Result<Option<HarvestJob>, AppError>> + Send;
    fn list_jobs(
        &self,
        status: Option<JobStatus>,
        limit: usize,
    ) -> impl Future<Output = Result<Vec<HarvestJob>, AppError>> + Send;
    fn release_job(
        &self,
        job_id: Uuid,
    ) -> impl Future<Output = Result<(), AppError>> + Send;
    fn release_worker_jobs(
        &self,
        worker_id: &str,
    ) -> impl Future<Output = Result<u64, AppError>> + Send;
    fn count_by_status(
        &self,
        status: JobStatus,
    ) -> impl Future<Output = Result<i64, AppError>> + Send;
}

Trait for job queue persistence operations.

This abstraction enables different storage backends (PostgreSQL, in-memory for tests) and facilitates dependency injection in the worker service.

Implementation Notes

Implementations should ensure:

• Atomic job claiming with SELECT FOR UPDATE SKIP LOCKED semantics
• Proper handling of retry scheduling
• Safe concurrent access from multiple workers

Required Methods

fn create_job( &self, request: CreateJobRequest, ) -> impl Future<Output = Result<HarvestJob, AppError>> + Send

Create a new job in the queue.

Returns the created job with generated ID and timestamps.

fn claim_job( &self, worker_id: &str, ) -> impl Future<Output = Result<Option<HarvestJob>, AppError>> + Send

Claim the next available pending job for processing.

Uses SELECT FOR UPDATE SKIP LOCKED semantics for safe concurrent claiming. Jobs are claimed in order of:

1. Non-retry jobs first (next_retry_at IS NULL)
2. Then retry-ready jobs (next_retry_at <= NOW)
3. Oldest first within each category

Returns None if no jobs are available.

fn complete_job( &self, job_id: Uuid, stats: SyncStats, ) -> impl Future<Output = Result<(), AppError>> + Send

Mark a job as completed with final statistics.

fn fail_job( &self, job_id: Uuid, error: &str, next_retry_at: Option<DateTime<Utc>>, ) -> impl Future<Output = Result<(), AppError>> + Send

Mark a job as failed with error message.

If next_retry_at is provided, the job is reset to pending for retry. Otherwise, the job is marked as permanently failed.

fn cancel_job( &self, job_id: Uuid, stats: Option<SyncStats>, ) -> impl Future<Output = Result<(), AppError>> + Send

Mark a job as cancelled.

Optionally saves partial sync statistics.

fn get_job( &self, job_id: Uuid, ) -> impl Future<Output = Result<Option<HarvestJob>, AppError>> + Send

Get a job by ID.

fn list_jobs( &self, status: Option<JobStatus>, limit: usize, ) -> impl Future<Output = Result<Vec<HarvestJob>, AppError>> + Send

List jobs with optional status filter.

Results are ordered by creation time (newest first).

fn release_job( &self, job_id: Uuid, ) -> impl Future<Output = Result<(), AppError>> + Send

Release a job back to pending state.

Used when a worker needs to give up a job (e.g., during shutdown). Only affects jobs in ‘running’ status.

fn release_worker_jobs( &self, worker_id: &str, ) -> impl Future<Output = Result<u64, AppError>> + Send

Release all jobs claimed by a specific worker.

Used for graceful shutdown to return all claimed jobs to the queue. Returns the number of jobs released.

fn count_by_status( &self, status: JobStatus, ) -> impl Future<Output = Result<i64, AppError>> + Send

Get count of jobs by status.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors