rusmes_imap/
lib.rs

1//! IMAP protocol implementation for RusMES
2//!
3//! This crate provides a full-featured, RFC-compliant IMAP server implementation
4//! built on Tokio for asynchronous I/O.
5//!
6//! # RFC Compliance
7//!
8//! - **RFC 9051** (IMAP4rev2) / **RFC 3501** (IMAP4rev1): Core IMAP protocol
9//! - **RFC 7162** (CONDSTORE / QRESYNC): Efficient mailbox synchronization with
10//!   `MODSEQ` tracking, `CHANGEDSINCE`/`UNCHANGEDSINCE` modifiers, and VANISHED responses
11//! - **RFC 6154** (SPECIAL-USE): `\Drafts`, `\Sent`, `\Trash`, `\Junk`, etc.
12//! - **RFC 4315** (UIDPLUS): `APPENDUID` and `COPYUID` response codes
13//! - **RFC 6851** (MOVE): `MOVE` command and `COPYUID` response for moves
14//! - **RFC 2177** (IDLE): Server-push idle notification
15//! - **RFC 2342** (NAMESPACE): Personal, shared, and other-users namespaces
16//! - **RFC 2449** (CAPABILITY): Capability advertisement
17//!
18//! # Supported Commands
19//!
20//! ## Not Authenticated State
21//! - `CAPABILITY` — List server capabilities
22//! - `NOOP` — No-operation (keep-alive)
23//! - `LOGOUT` — Disconnect
24//! - `LOGIN user password` — Plain-text authentication
25//! - `AUTHENTICATE mechanism` — SASL authentication (PLAIN, LOGIN, CRAM-MD5,
26//!   SCRAM-SHA-256, XOAUTH2)
27//!
28//! ## Authenticated State
29//! - `SELECT mailbox` — Open mailbox read-write
30//! - `EXAMINE mailbox` — Open mailbox read-only
31//! - `CREATE mailbox` — Create new mailbox (with optional `SPECIAL-USE` flag)
32//! - `DELETE mailbox` — Delete a mailbox
33//! - `RENAME old new` — Rename a mailbox
34//! - `SUBSCRIBE mailbox` — Subscribe to a mailbox
35//! - `UNSUBSCRIBE mailbox` — Unsubscribe from a mailbox
36//! - `LIST reference mailbox` — List mailboxes matching a pattern
37//! - `LSUB reference mailbox` — List subscribed mailboxes matching a pattern
38//! - `NAMESPACE` — Query server namespaces
39//! - `APPEND mailbox ...` — Append a message to a mailbox
40//!
41//! ## Selected State
42//! - `FETCH sequence items` — Retrieve message data
43//! - `STORE sequence flags` — Modify message flags
44//! - `SEARCH criteria` — Search for messages
45//! - `COPY sequence mailbox` — Copy messages to another mailbox
46//! - `MOVE sequence mailbox` — Move messages to another mailbox
47//! - `EXPUNGE` — Permanently delete messages with `\Deleted` flag
48//! - `CLOSE` — Implicit expunge and deselect
49//! - `IDLE` — Enter server-push idle mode (RFC 2177)
50//! - `UID FETCH/STORE/SEARCH/COPY/MOVE/EXPUNGE` — UID-based variants
51//!
52//! # Modules
53//!
54//! - [`authenticate`]: SASL multi-step authentication (PLAIN, LOGIN, CRAM-MD5,
55//!   SCRAM-SHA-256, XOAUTH2)
56//! - [`command`]: IMAP command enumeration and types
57//! - [`condstore`]: CONDSTORE extension — `MODSEQ`, `CHANGEDSINCE`, `UNCHANGEDSINCE`
58//! - [`config`]: Server configuration (`ImapConfig`)
59//! - [`handler`]: Command dispatcher (`HandlerContext`, `handle_command`)
60//! - [`handler_auth`]: LOGIN and LOGOUT handlers
61//! - [`handler_mailbox`]: Mailbox-level command handlers
62//! - [`handler_message`]: Message-level command handlers (FETCH, STORE, etc.)
63//! - [`mailbox_watcher`]: Watches for mailbox changes to support IDLE push notifications
64//! - [`parser`]: IMAP command-line parser including APPEND literal handling
65//! - [`qresync`]: QRESYNC extension — UID range sets, vanished responses
66//! - [`response`]: IMAP response formatting (tagged OK/NO/BAD, untagged `*`)
67//! - [`server`]: Async TCP listener accepting IMAP connections
68//! - [`session`]: Per-connection state machine (NotAuthenticated → Authenticated →
69//!   Selected ↔ Idle → Logout)
70//! - [`special_use`]: `SPECIAL-USE` mailbox attributes (RFC 6154)
71//!
72//! # Security
73//!
74//! All random challenge material (CRAM-MD5, SCRAM nonces) is generated via
75//! `getrandom` for cryptographic-quality entropy. In production deployments,
76//! TLS should be enabled to protect LOGIN/PLAIN credentials in transit.
77
78pub mod authenticate;
79pub mod command;
80pub mod condstore;
81pub mod config;
82pub mod handler;
83pub mod handler_auth;
84pub mod handler_mailbox;
85pub mod handler_message;
86pub mod mailbox_watcher;
87pub mod parser;
88pub mod qresync;
89pub mod response;
90pub mod server;
91pub mod session;
92pub mod special_use;
93
94pub use authenticate::{
95    create_default_sasl_server, handle_authenticate, handle_authenticate_continue,
96    parse_authenticate_args, AuthenticateContext, AuthenticateState,
97};
98pub use command::{ImapCommand, StoreMode};
99pub use condstore::{
100    ChangedSince, CondStoreError, CondStoreResponse, CondStoreState, CondStoreStatus,
101    UnchangedSince,
102};
103pub use config::ImapConfig;
104pub use handler::{handle_command, HandlerContext};
105pub use mailbox_watcher::{MailboxChanges, MailboxWatcher};
106pub use parser::{has_literal, parse_append_command, parse_command, LiteralType};
107pub use qresync::{
108    QResyncError, QResyncLogic, QResyncParams, QResyncState, SeqMatchData, UidRange, UidSet,
109    VanishedResponse,
110};
111pub use response::ImapResponse;
112pub use server::ImapServer;
113pub use session::{ImapSession, ImapState, MailboxSnapshot};
114pub use special_use::{
115    format_capability_response, format_list_extended, parse_create_special_use,
116    suggest_special_use, validate_special_use_flags, SpecialUse, SpecialUseError, SpecialUseFlags,
117    LIST_EXTENDED_CAPABILITY, SPECIAL_USE_CAPABILITY,
118};
rusmes_imap/lib.rs

rusmes_imap/
lib.rs
