background worker

crates/domain/src/events.rs

@@ -1,6 +1,10 @@
+use async_trait::async_trait;
 use chrono::NaiveDateTime;
 
-use crate::value_objects::{ExternalMetadataId, MovieId, Rating, ReviewId, UserId};
+use crate::{
+    errors::DomainError,
+    value_objects::{ExternalMetadataId, MovieId, Rating, ReviewId, UserId},
+};
 
 #[derive(Clone, Debug)]
 pub enum DomainEvent {
@@ -23,3 +27,28 @@ pub enum DomainEvent {
         external_metadata_id: ExternalMetadataId,
     },
 }
+
+#[async_trait]
+pub trait AckHandle: Send + Sync {
+    async fn ack(&self) -> Result<(), DomainError>;
+    async fn nack(&self) -> Result<(), DomainError>;
+}
+
+pub struct EventEnvelope {
+    pub event: DomainEvent,
+    ack: Box<dyn AckHandle>,
+}
+
+impl EventEnvelope {
+    pub fn new(event: DomainEvent, ack: Box<dyn AckHandle>) -> Self {
+        Self { event, ack }
+    }
+
+    pub async fn ack(self) -> Result<(), DomainError> {
+        self.ack.ack().await
+    }
+
+    pub async fn nack(self) -> Result<(), DomainError> {
+        self.ack.nack().await
+    }
+}

crates/domain/src/ports.rs

@@ -3,7 +3,7 @@ use chrono::{DateTime, Utc};
 
 use crate::{
     errors::DomainError,
-    events::DomainEvent,
+    events::{DomainEvent, EventEnvelope},
     models::{
         DiaryEntry, DiaryFilter, ExportFormat, FeedEntry, Movie, Review, ReviewHistory, User,
         UserStats, UserSummary, UserTrends,
@@ -174,9 +174,10 @@ pub trait EventPublisher: Send + Sync {
 }
 
 pub trait EventConsumer: Send + Sync {
-    /// Returns a stream of domain events. Implementations decide whether this
-    /// is push-based (NATS) or poll-based (DB queue) — callers don't care.
-    fn consume(&self) -> futures::stream::BoxStream<'_, Result<DomainEvent, DomainError>>;
+    /// Returns a stream of event envelopes. Each envelope carries a domain event
+    /// and an ack handle — callers ack after successful dispatch, nack on failure.
+    /// Implementations decide transport (NATS, DB queue, in-memory channel).
+    fn consume(&self) -> futures::stream::BoxStream<'_, Result<EventEnvelope, DomainError>>;
 }
 
 #[async_trait]