imap_rs/lib.rs
1//! `imap-rs`: a modern, high-performance, security-first IMAP client for Rust.
2//!
3//! This is the umbrella crate. It re-exports the three workspace crates and a
4//! handful of convenience entry points, so most users need only one dependency:
5//!
6//! ```toml
7//! [dependencies]
8//! imap-rs = "0.2"
9//! ```
10//!
11//! # Quick start
12//!
13//! ```no_run
14//! use imap_rs::connect_tls;
15//! use imap_rs::credentials::Password;
16//!
17//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
18//! // TCP + TLS handshake (both with timeouts), then CAPABILITY inside TLS.
19//! let session = connect_tls("imap.example.com", 993).await?;
20//! // `login` only exists on a TLS session — enforced at compile time.
21//! let auth = session.login("user", Password::new("pass")).await?;
22//! let mut inbox = auth.select("INBOX").await?;
23//! for msg in inbox.fetch("1:*", "BODY[]").await? {
24//! println!("seq={} uid={:?}", msg.seq, msg.uid);
25//! }
26//! # Ok(()) }
27//! ```
28//!
29//! # Highlights
30//!
31//! - **Security-first**: `rustls`-only TLS, [`zeroize`]d credentials,
32//! `#![forbid(unsafe_code)]`, and a fuzzed, bounds-checked parser.
33//! - **Compile-time-correct sessions**: illegal protocol transitions do not
34//! compile (see [`Session`]).
35//! - **Zero-copy parser** with a small dependency tree.
36//!
37//! # Crate layout
38//!
39//! The implementation is split across three crates, re-exported here:
40//!
41//! - [`core`] — protocol types and the zero-copy parser (no I/O).
42//! - [`client`] — the async, type-state session and command dispatcher.
43//! - [`tls`] — `rustls`-based transport ([`connect_tls`], [`connect_starttls`]).
44//!
45//! [`zeroize`]: https://crates.io/crates/zeroize
46
47#![forbid(unsafe_code)]
48
49/// Protocol types, AST, and zero-copy parser.
50pub use imap_core as core;
51
52/// Async session management and IMAP state machine.
53pub use imap_client as client;
54
55/// High-level secure connection wrappers using `rustls`.
56pub use imap_tls as tls;
57
58// Ergonomic top-level re-exports for common usage
59pub use imap_client::Session;
60pub use imap_tls::{connect_starttls, connect_tls};
61
62/// Secret credential wrappers (`Password` and `OAuthToken`) re-exported from
63/// `imap_client::credentials`.
64pub mod credentials {
65 pub use imap_client::credentials::{OAuthToken, Password};
66}