mailrs_imap_proto/
lib.rs

1#![deny(missing_docs)]
2#![deny(rustdoc::broken_intra_doc_links)]
3
4//! IMAP protocol parser and response formatter.
5//!
6//! `mailrs-imap-proto` implements the wire-format pieces of [RFC 3501]
7//! (IMAP4rev1) — tagged command parsing, sequence-set arithmetic, and
8//! response line formatting. It does no I/O and owns no state; it's the
9//! protocol layer underneath an IMAP server you write yourself.
10//!
11//! This crate underpins the IMAP server in [mailrs], a Rust mail server,
12//! and is published independently so other Rust projects can reuse the
13//! parsing layer.
14//!
15//! # Quick start
16//!
17//! ```
18//! use mailrs_imap_proto::{parse_command, ImapCommand, format_capability};
19//!
20//! // parse a wire-format tagged command line
21//! let parsed = parse_command("a001 CAPABILITY").unwrap();
22//! assert_eq!(parsed.tag, "a001");
23//! assert_eq!(parsed.command, ImapCommand::Capability);
24//!
25//! // format the matching response
26//! let resp = format_capability(&["IMAP4rev1", "IDLE", "AUTH=PLAIN"]);
27//! assert_eq!(resp, "* CAPABILITY IMAP4rev1 IDLE AUTH=PLAIN\r\n");
28//! ```
29//!
30//! # What this crate does
31//!
32//! - **Parsing**: [`parse_command`] turns a tagged command line into a
33//!   [`TaggedCommand`] containing a typed [`ImapCommand`] enum. Covers
34//!   LOGIN / SELECT / FETCH / STORE / SEARCH / IDLE / APPEND / UID / etc.
35//! - **Sequence sets**: [`parse_sequence_set`] parses IMAP sequence-set
36//!   syntax (`"1"`, `"1:5"`, `"5:*"`, `"1,3,5:10"`) into a [`SequenceSet`]
37//!   enum; [`sequence_set_to_uids`] expands it to a concrete UID vec.
38//! - **Search**: [`parse_search_criteria`] converts an IMAP SEARCH key list
39//!   to typed [`SearchKey`] values.
40//! - **Response formatting**: [`format_ok`] / [`format_no`] / [`format_bad`]
41//!   for tagged responses; [`format_capability`] / [`format_list`] /
42//!   [`format_fetch`] / [`format_flags`] / [`format_exists`] /
43//!   [`format_recent`] / [`format_bye`] / [`format_quota`] /
44//!   [`format_quotaroot`] for untagged responses.
45//!
46//! # What this crate does NOT do
47//!
48//! - No I/O. No TCP, no TLS, no async runtime, no connection management.
49//! - No mailbox storage or message indexing.
50//! - No session state machine. Unlike `mailrs-smtp-proto`, IMAP's
51//!   per-connection state (selected mailbox, capability negotiation,
52//!   pending IDLE) is owned by the caller — this crate just gives typed
53//!   commands and formatted replies.
54//!
55//! [RFC 3501]: https://datatracker.ietf.org/doc/html/rfc3501
56//! [mailrs]: https://github.com/goliajp/mailrs
57
58/// IMAP4rev1 command parser + `ImapCommand` AST.
59pub mod command;
60pub mod response;
61/// Sequence-set parser + expansion (`1:10,12,*`).
62pub mod sequence;
63
64pub use command::{ImapCommand, ParseError, SearchKey, TaggedCommand, parse_command, parse_search_criteria};
65pub use response::*;
66pub use sequence::{SequenceSet, parse_sequence_set, sequence_set_to_uids};
mailrs_imap_proto/lib.rs

mailrs_imap_proto/
lib.rs
