evx 0.1.0

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

use std::collections::HashMap;

use async_trait::async_trait;
use fred::clients::RedisClient;
use fred::interfaces::StreamsInterface;
use fred::types::RedisValue;

use crate::error::EventError;
use crate::event::cloud::CloudEvent;
use crate::queue::{JobId, QueueBroker, QueuedJob};

#[derive(Clone)]
/// A durable [`crate::QueueBroker`] backed by Redis Streams.
pub struct RedisStreamQueue {
    client: RedisClient,
    prefix: String,
}

impl RedisStreamQueue {
    /// Creates a queue backend using the default `evx` key prefix.
    pub fn new(client: RedisClient) -> Self {
        Self {
            client,
            prefix: "evx".to_string(),
        }
    }

    /// Creates a queue backend using a custom key prefix.
    pub fn with_prefix(client: RedisClient, prefix: impl Into<String>) -> Self {
        Self {
            client,
            prefix: prefix.into(),
        }
    }

    fn queue_key(&self, queue: &str) -> String {
        format!("{}:queue:{queue}", self.prefix)
    }

    fn dlq_key(&self, queue: &str) -> String {
        format!("{}:dlq:{queue}", self.prefix)
    }

    async fn xadd_event(
        &self,
        key: String,
        event: CloudEvent,
        attempts: u32,
        error: Option<String>,
    ) -> Result<JobId, EventError> {
        let payload = event.to_json()?;
        let mut fields = vec![
            ("payload".to_string(), payload),
            ("attempts".to_string(), attempts.to_string()),
        ];
        if let Some(error) = error {
            fields.push(("error".to_string(), error));
        }

        let id: String = self
            .client
            .xadd(key, false, None::<()>, "*", fields)
            .await
            .map_err(|e| EventError::Publish(format!("redis xadd failed: {e}")))?;
        Ok(JobId(id))
    }

    async fn ensure_group(&self, key: &str, group: &str) -> Result<(), EventError> {
        let result: Result<String, _> = self.client.xgroup_create(key, group, "0", true).await;
        match result {
            Ok(_) => Ok(()),
            Err(error) if error.to_string().contains("BUSYGROUP") => Ok(()),
            Err(error) => Err(EventError::Subscription(format!(
                "redis xgroup create failed: {error}"
            ))),
        }
    }
}

#[async_trait]
impl QueueBroker for RedisStreamQueue {
    async fn enqueue(
        &self,
        queue: &str,
        event: CloudEvent,
        attempts: u32,
    ) -> Result<JobId, EventError> {
        self.xadd_event(self.queue_key(queue), event, attempts, None)
            .await
    }

    async fn read(
        &self,
        queue: &str,
        group: &str,
        consumer: &str,
        count: usize,
        block_ms: u64,
    ) -> Result<Vec<QueuedJob>, EventError> {
        let key = self.queue_key(queue);
        self.ensure_group(&key, group).await?;

        let response: RedisValue = self
            .client
            .xreadgroup(
                group,
                consumer,
                Some(count as u64),
                Some(block_ms),
                false,
                vec![key],
                vec![">"],
            )
            .await
            .map_err(|e| EventError::Publish(format!("redis xreadgroup failed: {e}")))?;

        parse_xread_response(response)
    }

    async fn claim_stale(
        &self,
        queue: &str,
        group: &str,
        consumer: &str,
        count: usize,
        min_idle_ms: u64,
    ) -> Result<Vec<QueuedJob>, EventError> {
        let key = self.queue_key(queue);
        self.ensure_group(&key, group).await?;

        let response: RedisValue = self
            .client
            .xautoclaim(
                key,
                group,
                consumer,
                min_idle_ms,
                "0-0",
                Some(count.max(1) as u64),
                false,
            )
            .await
            .map_err(|e| EventError::Subscription(format!("redis xautoclaim failed: {e}")))?;

        parse_xautoclaim_response(response)
    }

    async fn ack(&self, queue: &str, group: &str, id: &JobId) -> Result<(), EventError> {
        let _: i64 = self
            .client
            .xack(self.queue_key(queue), group, vec![id.0.clone()])
            .await
            .map_err(|e| EventError::Publish(format!("redis xack failed: {e}")))?;
        Ok(())
    }

    async fn dead_letter(
        &self,
        queue: &str,
        event: CloudEvent,
        attempts: u32,
        error: String,
    ) -> Result<JobId, EventError> {
        self.xadd_event(self.dlq_key(queue), event, attempts, Some(error))
            .await
    }
}

fn parse_xread_response(response: RedisValue) -> Result<Vec<QueuedJob>, EventError> {
    if matches!(response, RedisValue::Null) {
        return Ok(Vec::new());
    }

    let mut jobs = Vec::new();
    for entries in stream_entries(response) {
        for entry in entries.into_array() {
            let Some(job) = parse_entry(entry)? else {
                continue;
            };
            jobs.push(job);
        }
    }
    Ok(jobs)
}

fn parse_xautoclaim_response(response: RedisValue) -> Result<Vec<QueuedJob>, EventError> {
    if matches!(response, RedisValue::Null) {
        return Ok(Vec::new());
    }

    let mut parts = response.into_array();
    if parts.len() < 2 {
        tracing::warn!("xautoclaim response has unexpected shape");
        return Ok(Vec::new());
    }

    let entries = parts.swap_remove(1);
    entries
        .into_array()
        .into_iter()
        .filter_map(|entry| match parse_entry(entry) {
            Ok(Some(job)) => Some(Ok(job)),
            Ok(None) => None,
            Err(error) => Some(Err(error)),
        })
        .collect()
}

fn stream_entries(response: RedisValue) -> Vec<RedisValue> {
    match response {
        RedisValue::Null => Vec::new(),
        RedisValue::Map(map) => map.inner().into_values().collect(),
        RedisValue::Array(streams) => streams
            .into_iter()
            .filter_map(|stream| {
                let mut stream_parts = stream.into_array();
                if stream_parts.len() != 2 {
                    tracing::warn!("xreadgroup stream response has unexpected shape");
                    return None;
                }
                stream_parts.pop()
            })
            .collect(),
        _ => {
            tracing::warn!("xreadgroup response has unexpected shape");
            Vec::new()
        }
    }
}

fn parse_entry(entry: RedisValue) -> Result<Option<QueuedJob>, EventError> {
    let mut entry_parts = entry.into_array();
    if entry_parts.len() != 2 {
        tracing::warn!("xreadgroup entry response has unexpected shape");
        return Ok(None);
    }

    let fields = fields_from_value(entry_parts.pop().expect("entry fields checked above"));
    let Some(id) = entry_parts
        .pop()
        .expect("entry id checked above")
        .into_string()
    else {
        tracing::warn!("queued job missing stream id");
        return Ok(None);
    };

    let Some(payload) = string_field(&fields, "payload") else {
        tracing::warn!(id = %id, "queued job missing payload");
        return Ok(None);
    };
    let attempts = string_field(&fields, "attempts")
        .and_then(|v| v.parse::<u32>().ok())
        .unwrap_or(0);
    let event = CloudEvent::from_json(&payload)?;
    Ok(Some(QueuedJob {
        id: JobId(id),
        event,
        attempts,
    }))
}

fn fields_from_value(value: RedisValue) -> HashMap<String, RedisValue> {
    match value {
        RedisValue::Map(map) => map
            .inner()
            .into_iter()
            .filter_map(|(key, value)| key.into_string().map(|key| (key, value)))
            .collect(),
        RedisValue::Array(values) => {
            let mut fields = HashMap::with_capacity(values.len() / 2);
            let mut iter = values.into_iter();
            while let (Some(key), Some(value)) = (iter.next(), iter.next()) {
                if let Some(key) = key.into_string() {
                    fields.insert(key, value);
                }
            }
            fields
        }
        _ => HashMap::new(),
    }
}

fn string_field(fields: &HashMap<String, RedisValue>, key: &str) -> Option<String> {
    fields.get(key).and_then(RedisValue::as_string)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn stream_entries_value() -> RedisValue {
        RedisValue::Array(vec![RedisValue::Array(vec![
            RedisValue::from_static_str("1780209417079-0"),
            RedisValue::Array(vec![
                RedisValue::from_static_str("payload"),
                RedisValue::String(cloud_event_payload().into()),
                RedisValue::from_static_str("attempts"),
                RedisValue::from_static_str("2"),
            ]),
        ])])
    }

    fn cloud_event_payload() -> &'static str {
        r#"{"id":"1","source":"/test","specversion":"1.0","type":"com.test","data":{},"datacontenttype":"application/json","time":"2026-05-31T00:00:00Z","scope":"app","extensions":{}}"#
    }

    fn assert_parsed_test_job(response: RedisValue) {
        let jobs = parse_xread_response(response).unwrap();

        assert_eq!(jobs.len(), 1);
        assert_eq!(jobs[0].id.0, "1780209417079-0");
        assert_eq!(jobs[0].attempts, 2);
        assert_eq!(jobs[0].event.r#type, "com.test");
    }

    #[test]
    fn parses_resp2_xreadgroup_response_with_flat_field_values() {
        let response = RedisValue::Array(vec![RedisValue::Array(vec![
            RedisValue::from_static_str("evx:queue:test"),
            stream_entries_value(),
        ])]);

        assert_parsed_test_job(response);
    }

    #[test]
    fn parses_resp3_xreadgroup_map_response() {
        let map = RedisValue::Array(vec![
            RedisValue::from_static_str("evx:queue:test"),
            stream_entries_value(),
        ])
        .into_map()
        .unwrap();

        assert_parsed_test_job(RedisValue::Map(map));
    }

    #[test]
    fn parses_redis_7_xautoclaim_response() {
        let response = RedisValue::Array(vec![
            RedisValue::from_static_str("0-0"),
            stream_entries_value(),
            RedisValue::Array(Vec::new()),
        ]);

        let jobs = parse_xautoclaim_response(response).unwrap();
        assert_eq!(jobs.len(), 1);
        assert_eq!(jobs[0].id.0, "1780209417079-0");
        assert_eq!(jobs[0].attempts, 2);
    }
}