rusmes_storage/lib.rs
1//! Storage abstraction layer for RusMES
2//!
3//! This crate provides a unified storage interface for the RusMES mail server, covering
4//! mailbox management, message delivery, metadata tracking, and quota enforcement.
5//!
6//! # Architecture
7//!
8//! The storage layer is composed of three orthogonal trait abstractions:
9//!
10//! - [`MailboxStore`] — Create, rename, delete, subscribe, and list mailboxes per user.
11//! - [`MessageStore`] — Append, retrieve, copy, flag, search, and delete messages.
12//! - [`MetadataStore`] — Manage per-user quotas and per-mailbox counters (exists/recent/unseen).
13//!
14//! These three stores are obtained from a single [`StorageBackend`] factory, which bundles
15//! them together and can be shared across protocol handlers (IMAP, JMAP, POP3, SMTP).
16//!
17//! # Backends
18//!
19//! | Backend | Module | Notes |
20//! |---------|--------|-------|
21//! | Filesystem / Maildir | [`backends::filesystem`] | Atomic delivery via `tmp/` → `new/` rename; flag encoding in filenames |
22//! | AmateRS distributed KV | [`backends::amaters`] | Mock implementation with circuit-breaker and exponential-backoff retry logic |
23//! | PostgreSQL | [`backends::postgres`] | Full connection pool via `sqlx`, full-text search, migrations |
24//!
25//! # Example — Filesystem backend
26//!
27//! ```rust,no_run
28//! use rusmes_storage::{StorageBackend, MailboxStore, MailboxPath};
29//! use rusmes_storage::backends::filesystem::FilesystemBackend;
30//!
31//! # async fn example() -> anyhow::Result<()> {
32//! let backend = FilesystemBackend::new("/var/mail/rusmes");
33//! let mb_store = backend.mailbox_store();
34//!
35//! let user: rusmes_proto::Username = "alice@example.com".parse()?;
36//! let path = MailboxPath::new(user, vec!["INBOX".to_string()]);
37//! let id = mb_store.create_mailbox(&path).await?;
38//!
39//! let mailbox = mb_store.get_mailbox(&id).await?;
40//! println!("Created: {:?}", mailbox);
41//! # Ok(())
42//! # }
43//! ```
44//!
45//! # ModSeq (Modification Sequence Numbers)
46//!
47//! [`ModSeqGenerator`] produces monotonically increasing sequence numbers suitable for
48//! IMAP CONDSTORE / QRESYNC extensions. Both mailbox-level and message-level ModSeq
49//! values are tracked via [`MailboxModSeq`] and [`MessageModSeq`] wrappers.
50//!
51//! # Metrics
52//!
53//! [`StorageMetrics`] records per-operation histograms for timing storage calls from
54//! higher-level protocol handlers, enabling Prometheus-compatible export.
55
56pub mod backends;
57pub mod metrics;
58pub mod modseq;
59mod traits;
60mod types;
61
62pub use metrics::{Histogram, MetricsSummary, StorageMetrics, StorageTimer};
63pub use modseq::{MailboxModSeq, MessageModSeq, ModSeq, ModSeqGenerator};
64pub use traits::{MailboxStore, MessageStore, MetadataStore, StorageBackend};
65pub use types::{
66 Mailbox, MailboxCounters, MailboxId, MailboxPath, MessageFlags, MessageMetadata, Quota,
67 SearchCriteria, SpecialUseAttributes,
68};