backbone_messaging/
lib.rs

1//! Backbone Messaging - Event-driven messaging infrastructure
2//!
3//! This crate provides a generic, type-safe event bus system for domain events
4//! following the Event-Driven Architecture and CQRS patterns.
5//!
6//! # Features
7//!
8//! - **Generic Event Bus**: Type-safe publish/subscribe for any event type
9//! - **Event Envelope**: Metadata wrapper with correlation/causation IDs
10//! - **Event Handlers**: Async trait-based event handling
11//! - **Event History**: Optional event persistence for replay
12//! - **Composite Events**: Support for aggregate event streams
13//! - **Integration Events**: Cross-bounded context communication (Phase 6)
14//!
15//! # Domain Events vs Integration Events
16//!
17//! | Aspect | Domain Event | Integration Event |
18//! |--------|--------------|-------------------|
19//! | Scope | Single bounded context | Cross-context |
20//! | Types | Can use domain types | Primitives only (JSON) |
21//! | Coupling | Internal | Loose coupling |
22//! | Bus | `EventBus<E>` (typed) | `IntegrationEventBus` (type-erased) |
23//!
24//! # Example - Domain Events
25//!
26//! ```rust,ignore
27//! use backbone_messaging::{EventBus, EventHandler, DomainEvent};
28//! use async_trait::async_trait;
29//!
30//! // Define your domain event
31//! #[derive(Clone, Debug)]
32//! struct UserCreated {
33//!     user_id: String,
34//!     email: String,
35//! }
36//!
37//! impl DomainEvent for UserCreated {
38//!     fn event_type(&self) -> &'static str { "UserCreated" }
39//!     fn aggregate_id(&self) -> &str { &self.user_id }
40//! }
41//!
42//! // Create and use the event bus
43//! let bus = EventBus::<UserCreated>::new();
44//! bus.publish(UserCreated { user_id: "123".into(), email: "test@example.com".into() }).await?;
45//! ```
46//!
47//! # Example - Integration Events (Cross-Module)
48//!
49//! ```rust,ignore
50//! use backbone_messaging::{IntegrationEventBus, IntegrationEvent, IntegrationEventHandler};
51//! use chrono::{DateTime, Utc};
52//! use serde::{Deserialize, Serialize};
53//!
54//! // Define an integration event (must be serializable)
55//! #[derive(Clone, Debug, Serialize, Deserialize)]
56//! struct UserCreatedIntegrationEvent {
57//!     user_id: String,
58//!     email: String,
59//!     occurred_at: DateTime<Utc>,
60//! }
61//!
62//! impl IntegrationEvent for UserCreatedIntegrationEvent {
63//!     fn event_type(&self) -> &'static str { "sapiens.user.created" }
64//!     fn source_context(&self) -> &'static str { "sapiens" }
65//!     fn aggregate_id(&self) -> &str { &self.user_id }
66//!     fn occurred_at(&self) -> DateTime<Utc> { self.occurred_at }
67//! }
68//!
69//! // Publish from Sapiens module
70//! let bus = IntegrationEventBus::new();
71//! bus.publish(UserCreatedIntegrationEvent { ... }).await?;
72//!
73//! // Subscribe in Postman module (using wildcard pattern)
74//! bus.register_handler(Arc::new(EmailHandler)).await; // patterns: ["sapiens.user.*"]
75//! ```
76
77// Domain Events (internal to bounded context)
78mod event;
79mod handler;
80mod bus;
81mod error;
82mod envelope;
83
84// Integration Events (cross-bounded context)
85mod integration;
86mod integration_bus;
87
88// Generic CRUD event infrastructure (Phase 0)
89pub mod crud_event;
90pub mod noop;
91pub mod subscriber;
92
93// Domain Event exports
94pub use event::DomainEvent;
95pub use handler::{EventHandler, LoggingHandler, CollectingHandler};
96pub use bus::{EventBus, EventBusConfig};
97pub use error::EventError;
98pub use envelope::{EventEnvelope, EventEnvelopeBuilder};
99
100// Integration Event exports
101pub use integration::{IntegrationEvent, IntegrationEventEnvelope};
102pub use integration_bus::{
103    IntegrationEventBus,
104    IntegrationBusConfig,
105    IntegrationEventHandler,
106    IntegrationLoggingHandler,
107    DeadLetterEntry,
108};
109
110// Generic CRUD event re-exports
111pub use crud_event::{CrudEvent, CrudEventPublisher, NoOpCrudEventPublisher};
112pub use noop::{NoOpPublisher, NoOpEventBus, Publisher};
113pub use subscriber::{GenericEventSubscriber, SubscriberCallback, SubscriberRegistry};
114
115/// Prelude module for convenient imports
116pub mod prelude {
117    // Domain events
118    pub use super::{
119        DomainEvent,
120        EventHandler,
121        EventBus,
122        EventBusConfig,
123        EventError,
124        EventEnvelope,
125        EventEnvelopeBuilder,
126        LoggingHandler,
127        CollectingHandler,
128    };
129
130    // Integration events
131    pub use super::{
132        IntegrationEvent,
133        IntegrationEventEnvelope,
134        IntegrationEventBus,
135        IntegrationBusConfig,
136        IntegrationEventHandler,
137        IntegrationLoggingHandler,
138        DeadLetterEntry,
139    };
140}
backbone_messaging/lib.rs

backbone_messaging/
lib.rs
