actr_runtime_mailbox/
lib.rs

1//! # Actor-RTC Mailbox Layer
2//!
3//! Persistent mailbox layer for the Actor-RTC framework, backed by SQLite.
4//!
5//! ## Core Features
6//!
7//! - **Message Persistence**: Reliable message queue and mailbox storage
8//! - **Dead Letter Queue**: Poison message isolation and manual intervention
9//!
10//! ## Quick Start
11//!
12//! ```rust,no_run
13//! use actr_runtime_mailbox::prelude::*;
14//! use actr_protocol::{ActrId, Realm, ActrType};
15//! use actr_protocol::prost::Message as ProstMessage;
16//!
17//! #[tokio::main]
18//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
19//!     // Create SQLite mailbox storage
20//!     let mailbox = SqliteMailbox::new("./data/mailbox.db").await?;
21//!
22//!     // Create sender ActrId and serialize
23//!     let sender = ActrId {
24//!         realm: Realm { realm_id: 1 },
25//!         serial_number: 1000,
26//!         r#type: ActrType {
27//!             manufacturer: "example".to_string(),
28//!             name: "TestActor".to_string(),
29//!             version: "1.0.0".to_string(),
30//!         },
31//!     };
32//!     let mut from_bytes = Vec::new();
33//!     sender.encode(&mut from_bytes)?;
34//!
35//!     let message = b"Hello, World!".to_vec();
36//!
37//!     // Enqueue message (from is the sender's ActrId as Protobuf bytes)
38//!     let message_id = mailbox.enqueue(from_bytes, message, MessagePriority::Normal).await?;
39//!
40//!     // Dequeue messages
41//!     let messages = mailbox.dequeue().await?;
42//!     println!("Retrieved {} messages", messages.len());
43//!
44//!     // Acknowledge message
45//!     if let Some(msg) = messages.first() {
46//!         mailbox.ack(msg.id).await?;
47//!     }
48//!
49//!     Ok(())
50//! }
51//! ```
52
53pub mod error;
54pub mod mailbox;
55#[cfg(feature = "sqlite")]
56pub mod sqlite;
57
58// Dead Letter Queue modules
59pub mod dlq;
60#[cfg(feature = "sqlite")]
61pub mod sqlite_dlq;
62
63// Re-export core types
64pub use actr_protocol::{ActrError, ActrId};
65
66// Storage layer core interfaces
67pub use error::{StorageError, StorageResult};
68pub use mailbox::{
69    Mailbox, MailboxDepthObserver, MailboxStats, MessagePriority, MessageRecord, MessageStatus,
70};
71
72// DLQ core interfaces
73pub use dlq::{DeadLetterQueue, DlqQuery, DlqRecord, DlqStats};
74
75// Backend implementations (only available with sqlite feature)
76#[cfg(feature = "sqlite")]
77pub use sqlite::{SqliteConfig, SqliteMailbox};
78#[cfg(feature = "sqlite")]
79pub use sqlite_dlq::SqliteDeadLetterQueue;
80
81pub mod prelude {
82    //! Convenience imports for commonly used mailbox layer types and traits
83
84    pub use crate::error::{StorageError, StorageResult};
85    pub use crate::mailbox::{
86        Mailbox, MailboxDepthObserver, MailboxStats, MessagePriority, MessageRecord, MessageStatus,
87    };
88    #[cfg(feature = "sqlite")]
89    pub use crate::sqlite::{SqliteConfig, SqliteMailbox};
90
91    // Dead Letter Queue
92    pub use crate::dlq::{DeadLetterQueue, DlqQuery, DlqRecord, DlqStats};
93    #[cfg(feature = "sqlite")]
94    pub use crate::sqlite_dlq::SqliteDeadLetterQueue;
95
96    // Base types
97    pub use actr_protocol::{ActrError, ActrId};
98
99    // Async trait support
100    pub use async_trait::async_trait;
101
102    // Common utilities
103    pub use anyhow::{Context as AnyhowContext, Result as AnyhowResult};
104    pub use chrono::{DateTime, Utc};
105    pub use uuid::Uuid;
106}
actr_runtime_mailbox/lib.rs

actr_runtime_mailbox/
lib.rs
