nats adapter

crates/adapters/nats/src/config.rs

@@ -0,0 +1,101 @@
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum NatsMode {
+    Core,
+    JetStream,
+}
+
+#[derive(Debug, Clone)]
+pub struct NatsConfig {
+    pub url: String,
+    pub mode: NatsMode,
+    pub subject_prefix: String,
+    pub stream_name: String,
+    pub consumer_name: String,
+}
+
+impl NatsConfig {
+    pub fn from_env() -> anyhow::Result<Self> {
+        let url = std::env::var("NATS_URL")
+            .map_err(|_| anyhow::anyhow!("NATS_URL is not set"))?;
+
+        let mode = match std::env::var("NATS_MODE")
+            .unwrap_or_else(|_| "jetstream".to_string())
+            .as_str()
+        {
+            "core"      => NatsMode::Core,
+            "jetstream" => NatsMode::JetStream,
+            other       => anyhow::bail!("unknown NATS_MODE: {other}"),
+        };
+
+        let subject_prefix = std::env::var("NATS_SUBJECT_PREFIX")
+            .unwrap_or_else(|_| "movies-diary.events".to_string());
+        let stream_name = std::env::var("NATS_STREAM_NAME")
+            .unwrap_or_else(|_| "MOVIES_DIARY_EVENTS".to_string());
+        let consumer_name = std::env::var("NATS_CONSUMER_NAME")
+            .unwrap_or_else(|_| "worker".to_string());
+
+        Ok(Self { url, mode, subject_prefix, stream_name, consumer_name })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn errors_without_nats_url() {
+        unsafe { std::env::remove_var("NATS_URL"); }
+        assert!(NatsConfig::from_env().is_err());
+    }
+
+    #[test]
+    fn defaults_with_only_url() {
+        unsafe {
+            std::env::set_var("NATS_URL", "nats://localhost:4222");
+            std::env::remove_var("NATS_MODE");
+            std::env::remove_var("NATS_SUBJECT_PREFIX");
+            std::env::remove_var("NATS_STREAM_NAME");
+            std::env::remove_var("NATS_CONSUMER_NAME");
+        }
+
+        let cfg = NatsConfig::from_env().unwrap();
+        assert_eq!(cfg.url, "nats://localhost:4222");
+        assert_eq!(cfg.mode, NatsMode::JetStream);
+        assert_eq!(cfg.subject_prefix, "movies-diary.events");
+        assert_eq!(cfg.stream_name, "MOVIES_DIARY_EVENTS");
+        assert_eq!(cfg.consumer_name, "worker");
+
+        unsafe { std::env::remove_var("NATS_URL"); }
+    }
+
+    #[test]
+    fn core_mode_parsed() {
+        unsafe {
+            std::env::set_var("NATS_URL", "nats://test:4222");
+            std::env::set_var("NATS_MODE", "core");
+        }
+
+        let cfg = NatsConfig::from_env().unwrap();
+        assert_eq!(cfg.mode, NatsMode::Core);
+
+        unsafe {
+            std::env::remove_var("NATS_URL");
+            std::env::remove_var("NATS_MODE");
+        }
+    }
+
+    #[test]
+    fn invalid_mode_errors() {
+        unsafe {
+            std::env::set_var("NATS_URL", "nats://test:4222");
+            std::env::set_var("NATS_MODE", "kafka");
+        }
+
+        assert!(NatsConfig::from_env().is_err());
+
+        unsafe {
+            std::env::remove_var("NATS_URL");
+            std::env::remove_var("NATS_MODE");
+        }
+    }
+}

crates/adapters/nats/src/consumer.rs

@@ -0,0 +1,213 @@
+use async_nats::{
+    Client,
+    jetstream::{self, consumer::pull, message::AckKind, stream::Config as StreamConfig},
+};
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::{AckHandle, DomainEvent, EventEnvelope},
+    ports::EventConsumer,
+};
+use futures::{
+    StreamExt,
+    stream::{self, BoxStream},
+};
+use std::sync::Arc;
+use tokio::sync::{Mutex, mpsc};
+
+use crate::{config::NatsConfig, payload::NatsEventPayload, subject::consumer_subject_filter};
+
+// ── JetStream ack handle ─────────────────────────────────────────────────────
+
+struct NatsJetStreamAckHandle {
+    message: async_nats::jetstream::Message,
+}
+
+#[async_trait]
+impl AckHandle for NatsJetStreamAckHandle {
+    async fn ack(&self) -> Result<(), DomainError> {
+        tracing::debug!(
+            "acknowledging message with sequence {}",
+            self.message.info().unwrap().stream_sequence
+        );
+
+        self.message
+            .ack()
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+
+    async fn nack(&self) -> Result<(), DomainError> {
+        tracing::debug!(
+            "negatively acknowledging message with sequence {}",
+            self.message.info().unwrap().stream_sequence
+        );
+
+        self.message
+            .ack_with(AckKind::Nak(None))
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+}
+
+// ── Core NATS ack handle (no-op) ─────────────────────────────────────────────
+
+struct NoopAck;
+
+#[async_trait]
+impl AckHandle for NoopAck {
+    async fn ack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+    async fn nack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+}
+
+// ── Envelope construction helpers ────────────────────────────────────────────
+
+fn decode_js(msg: async_nats::jetstream::Message) -> Result<EventEnvelope, DomainError> {
+    let payload: NatsEventPayload = serde_json::from_slice(&msg.payload)
+        .map_err(|e| DomainError::InfrastructureError(format!("deserialize: {e}")))?;
+    let event = DomainEvent::try_from(payload)?;
+    Ok(EventEnvelope::new(
+        event,
+        Box::new(NatsJetStreamAckHandle { message: msg }),
+    ))
+}
+
+fn decode_core(msg: async_nats::Message) -> Result<EventEnvelope, DomainError> {
+    let payload: NatsEventPayload = serde_json::from_slice(&msg.payload)
+        .map_err(|e| DomainError::InfrastructureError(format!("deserialize: {e}")))?;
+    let event = DomainEvent::try_from(payload)?;
+    Ok(EventEnvelope::new(event, Box::new(NoopAck)))
+}
+
+// ── Channel-bridge shared by both consumers ──────────────────────────────────
+
+type EnvelopeRx = Arc<Mutex<mpsc::Receiver<Result<EventEnvelope, DomainError>>>>;
+
+fn consume_from_rx(rx: EnvelopeRx) -> BoxStream<'static, Result<EventEnvelope, DomainError>> {
+    Box::pin(stream::unfold(rx, |rx| async move {
+        let item = rx.lock().await.recv().await?;
+        Some((item, rx))
+    }))
+}
+
+// ── JetStream consumer ────────────────────────────────────────────────────────
+
+pub struct NatsJetStreamConsumer {
+    rx: EnvelopeRx,
+}
+
+impl NatsJetStreamConsumer {
+    pub async fn create(cfg: &NatsConfig, client: Client) -> anyhow::Result<Self> {
+        let js = jetstream::new(client);
+
+        let stream = js
+            .get_or_create_stream(StreamConfig {
+                name: cfg.stream_name.clone(),
+                subjects: vec![consumer_subject_filter(&cfg.subject_prefix)],
+                max_messages: 100_000,
+                ..Default::default()
+            })
+            .await?;
+
+        let subject_filter = consumer_subject_filter(&cfg.subject_prefix);
+        let consumer = stream
+            .get_or_create_consumer(
+                cfg.consumer_name.as_str(),
+                pull::Config {
+                    durable_name: Some(cfg.consumer_name.clone()),
+                    filter_subject: subject_filter,
+                    ..Default::default()
+                },
+            )
+            .await?;
+
+        let (tx, rx) = mpsc::channel(128);
+
+        tokio::spawn(async move {
+            loop {
+                let mut messages = match consumer.messages().await {
+                    Err(e) => {
+                        tracing::error!("failed to fetch messages: {}", e);
+
+                        let _ = tx
+                            .send(Err(DomainError::InfrastructureError(e.to_string())))
+                            .await;
+                        return;
+                    }
+                    Ok(m) => m,
+                };
+                while let Some(result) = messages.next().await {
+                    let envelope = result
+                        .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+                        .and_then(decode_js);
+
+                    if tx.send(envelope).await.is_err() {
+                        tracing::info!("consumer channel closed, stopping message processing");
+                        return;
+                    }
+
+                    tracing::debug!("message sent to consumer channel");
+                }
+                // messages() stream ended (fetch expired in strict mode) — restart
+            }
+        });
+
+        Ok(Self {
+            rx: Arc::new(Mutex::new(rx)),
+        })
+    }
+}
+
+impl EventConsumer for NatsJetStreamConsumer {
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
+        consume_from_rx(Arc::clone(&self.rx))
+    }
+}
+
+// ── Core NATS consumer ────────────────────────────────────────────────────────
+
+pub struct NatsCoreConsumer {
+    rx: EnvelopeRx,
+}
+
+impl NatsCoreConsumer {
+    pub async fn create(cfg: &NatsConfig, client: Client) -> anyhow::Result<Self> {
+        let subject = consumer_subject_filter(&cfg.subject_prefix);
+        let mut subscriber = client.subscribe(subject).await?;
+
+        let (tx, rx) = mpsc::channel(128);
+
+        tokio::spawn(async move {
+            while let Some(msg) = subscriber.next().await {
+                let envelope = decode_core(msg);
+
+                tracing::debug!("message received and decoded, sending to consumer channel");
+
+                if tx.send(envelope).await.is_err() {
+                    tracing::info!("consumer channel closed, stopping message processing");
+                    break;
+                }
+            }
+        });
+
+        Ok(Self {
+            rx: Arc::new(Mutex::new(rx)),
+        })
+    }
+}
+
+impl EventConsumer for NatsCoreConsumer {
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
+        consume_from_rx(Arc::clone(&self.rx))
+    }
+}
+
+fn _assert_send_sync() {
+    fn check<T: Send + Sync>() {}
+    check::<NatsJetStreamConsumer>();
+    check::<NatsCoreConsumer>();
+}

crates/adapters/nats/src/lib.rs

@@ -0,0 +1,52 @@
+mod config;
+mod consumer;
+mod payload;
+mod publisher;
+mod subject;
+
+pub use config::{NatsConfig, NatsMode};
+pub use consumer::{NatsCoreConsumer, NatsJetStreamConsumer};
+pub use publisher::NatsEventPublisher;
+
+use std::sync::Arc;
+
+use domain::ports::{EventConsumer, EventPublisher};
+
+pub async fn create_publisher(cfg: NatsConfig) -> anyhow::Result<Arc<dyn EventPublisher>> {
+    let client = async_nats::connect(&cfg.url).await?;
+    let publisher: Arc<dyn EventPublisher> = match cfg.mode {
+        NatsMode::Core => Arc::new(NatsEventPublisher::new_core(client, cfg.subject_prefix)),
+        NatsMode::JetStream => Arc::new(NatsEventPublisher::new_jetstream(
+            client,
+            cfg.subject_prefix,
+        )),
+    };
+
+    tracing::info!("NATS publisher created (mode: {:?})", cfg.mode);
+    Ok(publisher)
+}
+
+pub async fn create_channel(
+    cfg: NatsConfig,
+) -> anyhow::Result<(Arc<dyn EventPublisher>, Arc<dyn EventConsumer>)> {
+    let client = async_nats::connect(&cfg.url).await?;
+
+    let publisher: Arc<dyn EventPublisher> = match cfg.mode {
+        NatsMode::Core => Arc::new(NatsEventPublisher::new_core(
+            client.clone(),
+            cfg.subject_prefix.clone(),
+        )),
+        NatsMode::JetStream => Arc::new(NatsEventPublisher::new_jetstream(
+            client.clone(),
+            cfg.subject_prefix.clone(),
+        )),
+    };
+
+    let consumer: Arc<dyn EventConsumer> = match cfg.mode {
+        NatsMode::Core => Arc::new(NatsCoreConsumer::create(&cfg, client).await?),
+        NatsMode::JetStream => Arc::new(NatsJetStreamConsumer::create(&cfg, client).await?),
+    };
+
+    tracing::info!("NATS channel created (mode: {:?})", cfg.mode);
+    Ok((publisher, consumer))
+}

crates/adapters/nats/src/payload.rs

@@ -0,0 +1,172 @@
+use chrono::NaiveDateTime;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    value_objects::{ExternalMetadataId, MovieId, Rating, ReviewId, UserId},
+};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+#[derive(Debug, Serialize, Deserialize, PartialEq)]
+#[serde(tag = "type", content = "data")]
+pub enum NatsEventPayload {
+    ReviewLogged {
+        review_id: String,
+        movie_id: String,
+        user_id: String,
+        rating: u8,
+        watched_at: i64,
+    },
+    ReviewUpdated {
+        review_id: String,
+        movie_id: String,
+        user_id: String,
+        rating: u8,
+        watched_at: i64,
+    },
+    MovieDiscovered {
+        movie_id: String,
+        external_metadata_id: String,
+    },
+}
+
+fn parse_uuid(s: &str, field: &str) -> Result<Uuid, DomainError> {
+    Uuid::parse_str(s)
+        .map_err(|e| DomainError::InfrastructureError(format!("{field}: {e}")))
+}
+
+fn parse_ts(ts: i64) -> Result<NaiveDateTime, DomainError> {
+    chrono::DateTime::from_timestamp(ts, 0)
+        .map(|dt| dt.naive_utc())
+        .ok_or_else(|| DomainError::InfrastructureError(format!("invalid timestamp: {ts}")))
+}
+
+impl From<&DomainEvent> for NatsEventPayload {
+    fn from(event: &DomainEvent) -> Self {
+        match event {
+            DomainEvent::ReviewLogged { review_id, movie_id, user_id, rating, watched_at } => {
+                NatsEventPayload::ReviewLogged {
+                    review_id: review_id.value().to_string(),
+                    movie_id: movie_id.value().to_string(),
+                    user_id: user_id.value().to_string(),
+                    rating: rating.value(),
+                    watched_at: watched_at.and_utc().timestamp(),
+                }
+            }
+            DomainEvent::ReviewUpdated { review_id, movie_id, user_id, rating, watched_at } => {
+                NatsEventPayload::ReviewUpdated {
+                    review_id: review_id.value().to_string(),
+                    movie_id: movie_id.value().to_string(),
+                    user_id: user_id.value().to_string(),
+                    rating: rating.value(),
+                    watched_at: watched_at.and_utc().timestamp(),
+                }
+            }
+            DomainEvent::MovieDiscovered { movie_id, external_metadata_id } => {
+                NatsEventPayload::MovieDiscovered {
+                    movie_id: movie_id.value().to_string(),
+                    external_metadata_id: external_metadata_id.value().to_owned(),
+                }
+            }
+        }
+    }
+}
+
+impl TryFrom<NatsEventPayload> for DomainEvent {
+    type Error = DomainError;
+    fn try_from(payload: NatsEventPayload) -> Result<Self, DomainError> {
+        match payload {
+            NatsEventPayload::ReviewLogged { review_id, movie_id, user_id, rating, watched_at } => {
+                Ok(DomainEvent::ReviewLogged {
+                    review_id: ReviewId::from_uuid(parse_uuid(&review_id, "review_id")?),
+                    movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                    user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                    rating: Rating::new(rating)?,
+                    watched_at: parse_ts(watched_at)?,
+                })
+            }
+            NatsEventPayload::ReviewUpdated { review_id, movie_id, user_id, rating, watched_at } => {
+                Ok(DomainEvent::ReviewUpdated {
+                    review_id: ReviewId::from_uuid(parse_uuid(&review_id, "review_id")?),
+                    movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                    user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                    rating: Rating::new(rating)?,
+                    watched_at: parse_ts(watched_at)?,
+                })
+            }
+            NatsEventPayload::MovieDiscovered { movie_id, external_metadata_id } => {
+                Ok(DomainEvent::MovieDiscovered {
+                    movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                    external_metadata_id: ExternalMetadataId::new(external_metadata_id)?,
+                })
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fixed_dt() -> NaiveDateTime {
+        chrono::DateTime::from_timestamp(1_700_000_000, 0).unwrap().naive_utc()
+    }
+
+    fn review_logged() -> DomainEvent {
+        DomainEvent::ReviewLogged {
+            review_id: ReviewId::from_uuid(Uuid::new_v4()),
+            movie_id: MovieId::from_uuid(Uuid::new_v4()),
+            user_id: UserId::from_uuid(Uuid::new_v4()),
+            rating: Rating::new(4).unwrap(),
+            watched_at: fixed_dt(),
+        }
+    }
+
+    fn review_updated() -> DomainEvent {
+        DomainEvent::ReviewUpdated {
+            review_id: ReviewId::from_uuid(Uuid::new_v4()),
+            movie_id: MovieId::from_uuid(Uuid::new_v4()),
+            user_id: UserId::from_uuid(Uuid::new_v4()),
+            rating: Rating::new(3).unwrap(),
+            watched_at: fixed_dt(),
+        }
+    }
+
+    fn movie_discovered() -> DomainEvent {
+        DomainEvent::MovieDiscovered {
+            movie_id: MovieId::from_uuid(Uuid::new_v4()),
+            external_metadata_id: ExternalMetadataId::new("tt1234567".into()).unwrap(),
+        }
+    }
+
+    fn round_trip(event: DomainEvent) {
+        let payload = NatsEventPayload::from(&event);
+        let json = serde_json::to_string(&payload).expect("serialize");
+        let back: NatsEventPayload = serde_json::from_str(&json).expect("deserialize");
+        let recovered = DomainEvent::try_from(back).expect("try_from");
+        assert_eq!(NatsEventPayload::from(&event), NatsEventPayload::from(&recovered));
+    }
+
+    #[test]
+    fn round_trip_review_logged() {
+        round_trip(review_logged());
+    }
+
+    #[test]
+    fn round_trip_review_updated() {
+        round_trip(review_updated());
+    }
+
+    #[test]
+    fn round_trip_movie_discovered() {
+        round_trip(movie_discovered());
+    }
+
+    #[test]
+    fn serialized_format_is_tagged() {
+        let payload = NatsEventPayload::from(&movie_discovered());
+        let json = serde_json::to_string(&payload).unwrap();
+        assert!(json.contains(r#""type":"MovieDiscovered""#));
+        assert!(json.contains(r#""data":"#));
+    }
+}

crates/adapters/nats/src/publisher.rs

@@ -0,0 +1,54 @@
+use async_nats::{jetstream, Client};
+use async_trait::async_trait;
+use domain::{errors::DomainError, events::DomainEvent, ports::EventPublisher};
+
+use crate::{payload::NatsEventPayload, subject::event_to_subject};
+
+enum PublisherMode {
+    Core(Client),
+    JetStream(jetstream::Context),
+}
+
+pub struct NatsEventPublisher {
+    mode: PublisherMode,
+    subject_prefix: String,
+}
+
+impl NatsEventPublisher {
+    pub fn new_core(client: Client, subject_prefix: String) -> Self {
+        Self { mode: PublisherMode::Core(client), subject_prefix }
+    }
+
+    pub fn new_jetstream(client: Client, subject_prefix: String) -> Self {
+        Self { mode: PublisherMode::JetStream(jetstream::new(client)), subject_prefix }
+    }
+}
+
+#[async_trait]
+impl EventPublisher for NatsEventPublisher {
+    async fn publish(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        let subject = event_to_subject(&self.subject_prefix, event);
+        let payload = serde_json::to_vec(&NatsEventPayload::from(event))
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+
+        match &self.mode {
+            PublisherMode::Core(client) => client
+                .publish(subject, payload.into())
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+
+            PublisherMode::JetStream(js) => js
+                .publish(subject, payload.into())
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+                .await
+                .map(|_| ())
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+        }
+    }
+}
+
+fn _assert_send_sync() {
+    fn check<T: Send + Sync>() {}
+    check::<NatsEventPublisher>();
+}

crates/adapters/nats/src/subject.rs

@@ -0,0 +1,76 @@
+use domain::events::DomainEvent;
+
+pub fn event_to_subject(prefix: &str, event: &DomainEvent) -> String {
+    let suffix = match event {
+        DomainEvent::ReviewLogged { .. }    => "review.logged",
+        DomainEvent::ReviewUpdated { .. }   => "review.updated",
+        DomainEvent::MovieDiscovered { .. } => "movie.discovered",
+    };
+    format!("{prefix}.{suffix}")
+}
+
+pub fn consumer_subject_filter(prefix: &str) -> String {
+    format!("{prefix}.>")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::NaiveDateTime;
+    use domain::value_objects::{ExternalMetadataId, MovieId, Rating, ReviewId, UserId};
+    use uuid::Uuid;
+
+    fn dt() -> NaiveDateTime {
+        chrono::DateTime::from_timestamp(1_700_000_000, 0).unwrap().naive_utc()
+    }
+
+    #[test]
+    fn review_logged_subject() {
+        let event = DomainEvent::ReviewLogged {
+            review_id: ReviewId::from_uuid(Uuid::new_v4()),
+            movie_id: MovieId::from_uuid(Uuid::new_v4()),
+            user_id: UserId::from_uuid(Uuid::new_v4()),
+            rating: Rating::new(3).unwrap(),
+            watched_at: dt(),
+        };
+        assert_eq!(
+            event_to_subject("movies-diary.events", &event),
+            "movies-diary.events.review.logged"
+        );
+    }
+
+    #[test]
+    fn review_updated_subject() {
+        let event = DomainEvent::ReviewUpdated {
+            review_id: ReviewId::from_uuid(Uuid::new_v4()),
+            movie_id: MovieId::from_uuid(Uuid::new_v4()),
+            user_id: UserId::from_uuid(Uuid::new_v4()),
+            rating: Rating::new(5).unwrap(),
+            watched_at: dt(),
+        };
+        assert_eq!(
+            event_to_subject("movies-diary.events", &event),
+            "movies-diary.events.review.updated"
+        );
+    }
+
+    #[test]
+    fn movie_discovered_subject() {
+        let event = DomainEvent::MovieDiscovered {
+            movie_id: MovieId::from_uuid(Uuid::new_v4()),
+            external_metadata_id: ExternalMetadataId::new("tt0000001".into()).unwrap(),
+        };
+        assert_eq!(
+            event_to_subject("movies-diary.events", &event),
+            "movies-diary.events.movie.discovered"
+        );
+    }
+
+    #[test]
+    fn consumer_subject_filter_appends_wildcard() {
+        assert_eq!(
+            consumer_subject_filter("movies-diary.events"),
+            "movies-diary.events.>"
+        );
+    }
+}