rusmes_proto/
lib.rs

1//! Core protocol types and traits for RusMES
2//!
3//! This crate defines the fundamental data types shared across every component of the
4//! RusMES mail server. It is intentionally free of network I/O and heavy dependencies
5//! so that it can be compiled quickly and linked into all other crates.
6//!
7//! # Key Features
8//!
9//! - **Validated address types** — [`MailAddress`], [`Domain`], and [`Username`] enforce
10//!   RFC constraints at construction time and expose infallible accessors.
11//! - **Mail state machine** — [`MailState`] models the lifecycle of a mail item as it
12//!   flows through the mailet processing pipeline (Root → Transport →
13//!   LocalDelivery / Error / Ghost / Custom).
14//! - **Mail envelope** — [`Mail`] wraps a [`MimeMessage`] with SMTP envelope data
15//!   (sender, recipients, remote IP/host), custom attributes for mailet communication,
16//!   and a split operation for fan-out delivery.
17//! - **MIME message** — [`MimeMessage`] provides parsed header access and body handling
18//!   for both in-memory (`Small`) and streaming (`Large`) messages, including multipart
19//!   parsing, base64 / quoted-printable decoding, and Content-Type inspection.
20//! - **Typed identifiers** — UUID-backed [`MailId`] and [`MessageId`] for unambiguous
21//!   tracking of mail items and messages throughout the system.
22//!
23//! # Module Overview
24//!
25//! | Module       | Contents                                              |
26//! |--------------|-------------------------------------------------------|
27//! | [`address`]  | `MailAddress`, `Domain`, `Username`                  |
28//! | [`error`]    | `MailError`, `Result` alias                          |
29//! | [`mail`]     | `Mail`, `MailId`, `MailState`, `AttributeValue`      |
30//! | [`message`]  | `MimeMessage`, `MessageId`, `HeaderMap`, `MessageBody`|
31//! | [`mime`]     | MIME parsing helpers, `ContentType`, `MimePart`      |
32//!
33//! # Brief Usage Example
34//!
35//! ```rust
36//! use rusmes_proto::{Domain, MailAddress, Mail, MailState};
37//! use rusmes_proto::message::{HeaderMap, MessageBody, MimeMessage};
38//! use bytes::Bytes;
39//!
40//! // Build a validated address
41//! let domain = Domain::new("example.com").expect("valid domain");
42//! let addr = MailAddress::new("alice", domain).expect("valid address");
43//! assert_eq!(addr.to_string(), "alice@example.com");
44//!
45//! // Create a mail envelope
46//! let headers = HeaderMap::new();
47//! let body = MessageBody::Small(Bytes::from("Hello, world!"));
48//! let msg = MimeMessage::new(headers, body);
49//! let mail = Mail::new(Some(addr), vec![], msg, None, None);
50//! assert_eq!(mail.state, MailState::Root);
51//! ```
52//!
53//! # Relevant Standards
54//!
55//! - Email address syntax: [RFC 5321 §4.1.2](https://www.rfc-editor.org/rfc/rfc5321#section-4.1.2),
56//!   [RFC 5322 §3.4](https://www.rfc-editor.org/rfc/rfc5322#section-3.4)
57//! - MIME: [RFC 2045](https://www.rfc-editor.org/rfc/rfc2045),
58//!   [RFC 2046](https://www.rfc-editor.org/rfc/rfc2046),
59//!   [RFC 2047](https://www.rfc-editor.org/rfc/rfc2047)
60//! - Domain names: [RFC 1035](https://www.rfc-editor.org/rfc/rfc1035),
61//!   [RFC 5891](https://www.rfc-editor.org/rfc/rfc5891) (IDNA)
62
63pub mod address;
64pub mod error;
65pub mod mail;
66pub mod message;
67pub mod mime;
68
69pub use address::{Domain, MailAddress, Username};
70pub use error::{MailError, Result};
71pub use mail::{AttributeValue, Mail, MailId, MailState};
72pub use message::{HeaderMap, MessageBody, MessageId, MimeMessage};
73pub use mime::{ContentTransferEncoding, ContentType, MimePart};
rusmes_proto/lib.rs

rusmes_proto/
lib.rs
