evx 0.1.0

A type-safe event bus for domain events, CQRS, Redis Pub/Sub, and durable work queues
Documentation
//! Durable work-queue abstractions and optional backend implementations.

use async_trait::async_trait;

use crate::error::EventError;
use crate::event::cloud::CloudEvent;

#[cfg(feature = "redis")]
pub mod redis_stream;

#[derive(Debug, Clone, PartialEq, Eq)]
/// Backend-specific identifier assigned to an enqueued job.
pub struct JobId(
    /// Raw identifier returned by the queue backend.
    pub String,
);

#[derive(Debug, Clone)]
/// Delivery, concurrency, retry, and recovery policy for a queued command.
pub struct QueuePolicy {
    /// Logical queue name.
    pub queue: &'static str,
    /// Consumer group that shares work from the queue.
    pub consumer_group: &'static str,
    /// Maximum number of handler attempts before dead-lettering.
    pub max_attempts: u32,
    /// Maximum number of jobs concurrently handled by one worker.
    pub max_in_flight: usize,
    /// Maximum duration a queue read blocks while waiting for new work.
    pub block_ms: u64,
    /// Minimum pending idle duration before another consumer may claim a job.
    pub claim_idle_ms: u64,
}

impl QueuePolicy {
    /// Creates a policy with three attempts, eight in-flight jobs, a one-second
    /// blocking read, and a five-minute stale-claim threshold.
    pub fn new(queue: &'static str, consumer_group: &'static str) -> Self {
        Self {
            queue,
            consumer_group,
            max_attempts: 3,
            max_in_flight: 8,
            block_ms: 1000,
            claim_idle_ms: 300_000,
        }
    }
}

#[derive(Debug, Clone)]
/// A serialized job delivered by a [`QueueBroker`].
pub struct QueuedJob {
    /// Backend-assigned job identifier.
    pub id: JobId,
    /// Message envelope stored in the queue.
    pub event: CloudEvent,
    /// Number of handler failures recorded by Evx.
    pub attempts: u32,
}

#[async_trait]
/// Durable queue transport used by [`crate::EventBus::enqueue`] and
/// [`crate::EventBus::work`].
pub trait QueueBroker: Send + Sync {
    /// Appends an event to a logical queue.
    async fn enqueue(
        &self,
        queue: &str,
        event: CloudEvent,
        attempts: u32,
    ) -> Result<JobId, EventError>;

    /// Reads new jobs for a consumer group.
    async fn read(
        &self,
        queue: &str,
        group: &str,
        consumer: &str,
        count: usize,
        block_ms: u64,
    ) -> Result<Vec<QueuedJob>, EventError>;

    /// Claims jobs left pending longer than `min_idle_ms` by another consumer.
    async fn claim_stale(
        &self,
        queue: &str,
        group: &str,
        consumer: &str,
        count: usize,
        min_idle_ms: u64,
    ) -> Result<Vec<QueuedJob>, EventError>;

    /// Acknowledges successful handling of a job.
    async fn ack(&self, queue: &str, group: &str, id: &JobId) -> Result<(), EventError>;

    /// Moves a permanently failed event to the queue's dead-letter store.
    async fn dead_letter(
        &self,
        queue: &str,
        event: CloudEvent,
        attempts: u32,
        error: String,
    ) -> Result<JobId, EventError>;
}