flippico-cache 0.5.0

use async_trait::async_trait;

use crate::types::queues::{
    BulkJob, BullMqError, EnqueueOptions, JobHandle, JobSnapshot, JobStateFilter, QueueChannel,
    QueueCounts,
};

/// Produce jobs into, and inspect the state of, BullMQ queues.
///
/// Unlike this crate's other capabilities this trait is `async`. A blocking
/// wrapper is not possible: `block_on` inside an existing Tokio runtime panics,
/// and the Worker built on this foundation needs a live runtime for lock
/// renewal and stalled-job recovery.
///
/// Queue channels are taken by reference so that repeated calls against a
/// `QueueChannel::Custom` do not force a clone of its `String` on every call.
#[async_trait]
pub trait BullMqProvider: Send + Sync {
    /// Enqueue a single job. `job_name` is BullMQ's job name, which workers
    /// may dispatch on; it is not the queue name.
    async fn enqueue(
        &self,
        queue: &QueueChannel,
        job_name: &str,
        payload: serde_json::Value,
        options: Option<EnqueueOptions>,
    ) -> Result<JobHandle, BullMqError>;

    /// Enqueue many jobs.
    ///
    /// **Not atomic.** Upstream issues one independent Lua call per job,
    /// concurrently, and returns the first error it finds. Jobs that already
    /// succeeded remain in Redis, and this call returns `Err` without their
    /// handles — so on failure, treat the queue as holding an unknown subset.
    /// Give jobs explicit `job_id`s if you need a retry to be idempotent.
    async fn enqueue_bulk(
        &self,
        queue: &QueueChannel,
        jobs: Vec<BulkJob>,
    ) -> Result<Vec<JobHandle>, BullMqError>;

    /// Job totals per state.
    async fn job_counts(&self, queue: &QueueChannel) -> Result<QueueCounts, BullMqError>;

    /// Fetch a single job by id, if it still exists.
    async fn get_job(
        &self,
        queue: &QueueChannel,
        job_id: &str,
    ) -> Result<Option<JobSnapshot>, BullMqError>;

    /// List jobs in a given state. `start` and `end` are inclusive indices.
    async fn list_jobs(
        &self,
        queue: &QueueChannel,
        state: JobStateFilter,
        start: i64,
        end: i64,
    ) -> Result<Vec<JobSnapshot>, BullMqError>;

    /// Stop the queue handing out new jobs.
    async fn pause(&self, queue: &QueueChannel) -> Result<(), BullMqError>;

    /// Resume a paused queue.
    async fn resume(&self, queue: &QueueChannel) -> Result<(), BullMqError>;

    /// Whether the queue is currently paused.
    async fn is_paused(&self, queue: &QueueChannel) -> Result<bool, BullMqError>;

    /// Permanently delete every key belonging to this queue.
    ///
    /// Destructive. Intended for tests and for tearing down a retired queue.
    async fn obliterate(&self, queue: &QueueChannel) -> Result<(), BullMqError>;
}