rusmes_server/lib.rs
1//! RusMES server orchestration library
2//!
3//! This crate is the top-level runtime for the RusMES mail server. It brings together
4//! all protocol servers (SMTP, IMAP, POP3, JMAP), the mailet processing pipeline,
5//! storage backends, authentication, metrics collection, and connection management
6//! into a single, cohesive process.
7//!
8//! # Key Features
9//!
10//! - **Multi-protocol**: Simultaneously runs SMTP, IMAP, POP3, and JMAP servers.
11//! - **Mailet pipeline**: Configurable chain of mail-processing mailets (spam filtering,
12//! local delivery, remote delivery, DKIM/SPF/DMARC checking, etc.) driven by the
13//! [`rusmes_core`] processing engine.
14//! - **Graceful shutdown**: Responds to SIGTERM and SIGINT with clean shutdown of all
15//! protocol listeners.
16//! - **Hot configuration reload**: On SIGHUP the server re-reads `rusmes.toml` and
17//! applies changes to logging levels and rate-limit settings without restart.
18//! - **Pluggable authentication**: Supports file-based, LDAP, SQL, and OAuth2 backends
19//! via the [`rusmes_auth`] crate.
20//! - **Connection limiting**: Per-IP connection caps and idle-timeout enforcement via
21//! the `connection_limits` module.
22//! - **Structured session logging**: UUID-based session IDs attached to every log event
23//! for easy per-connection trace reconstruction (see [`session_logging`]).
24//!
25//! # Binary entry point
26//!
27//! The crate ships a `rusmes-server` binary whose `main` function:
28//! 1. Reads configuration from a TOML file (default `rusmes.toml`, overridden by the
29//! first CLI argument).
30//! 2. Initialises storage, metrics, authentication, and rate-limiting.
31//! 3. Spawns each enabled protocol server as an independent Tokio task.
32//! 4. Enters a `select!` loop waiting for OS signals or server task failures.
33//!
34//! # Brief Usage Example
35//!
36//! ```bash
37//! # Run the server with the default config path
38//! rusmes-server
39//!
40//! # Or with a custom config:
41//! rusmes-server /etc/rusmes/rusmes.toml
42//! ```
43//!
44//! # Relevant Standards
45//!
46//! - SMTP: [RFC 5321](https://www.rfc-editor.org/rfc/rfc5321), [RFC 6531](https://www.rfc-editor.org/rfc/rfc6531)
47//! - IMAP4rev2: [RFC 9051](https://www.rfc-editor.org/rfc/rfc9051)
48//! - POP3: [RFC 1939](https://www.rfc-editor.org/rfc/rfc1939)
49//! - JMAP: [RFC 8620](https://www.rfc-editor.org/rfc/rfc8620), [RFC 8621](https://www.rfc-editor.org/rfc/rfc8621)
50
51pub mod session_logging;