Crate imap_codec

source ·
Expand description

IMAP Protocol Library

imap-codec provides complete and detailed parsing and construction of IMAP4rev1 commands and responses. It is based on imap-types and extends it with parsing support via nom.

Parsing

Parsing is implemented through the Decode trait. The main entry points for parsing are Greeting::decode(…) (to parse the first message from a server)), Command::decode(…) (to parse commands from a client), and Response::decode(…) (to parse responses or results from a server). Note, however, that certain message flows require other parsers as well. Every parser takes an input (&[u8]) and produces a remainder and a parsed value.

Serialization

Serialization is implemented via the Encode trait. See the imap-types documentation for the module layout and how to construct messages.

Example

use imap_codec::{
    codec::{Decode, Encode},
    command::Command,
};

let input = b"ABCD UID FETCH 1,2:* (BODY.PEEK[1.2.3.4.MIME]<42.1337>)\r\n";

let (_remainder, parsed) = Command::decode(input).unwrap();
println!("// Parsed:");
println!("{:#?}", parsed);

let serialized = parsed.encode_detached().unwrap();

let serialized = String::from_utf8(serialized).unwrap(); // Not every IMAP message is valid UTF-8.
println!("// Serialized:"); // We just ignore that, so that we can print the message.
println!("// {}", serialized);

Features

This crate uses the following features to enable IMAP extensions:

FeatureDescriptionEnabled by default
ext_compressThe IMAP COMPRESS Extension (RFC 4978)No (but may change)
ext_enableThe IMAP ENABLE Extension (RFC 5161)No (but may change)
ext_idleIMAP4 IDLE command (RFC 2177)No (but may change)
ext_literalIMAP4 Non-synchronizing Literals (RFC 2088, RFC 7888)No (but may change)
ext_login_referralsIMAP4 Login Referrals (RFC 2221)No (but may change)
ext_mailbox_referralsIMAP4 Mailbox Referrals (RFC 2193)No (but may change)
ext_quotaIMAP QUOTA Extension (RFC 9208)No (but may change)
ext_sasl_irIMAP Extension for SASL Initial Client Response (RFC 4959)No (but may change)
starttlsIMAP4rev1 (RFC 3501; section 6.2.1)No

Features prefixed with “ext_” are IMAP extensions and often require a more elaborate message flow. STARTTLS is not considered an extension but feature-gated because it should be avoided. For better performance and security, use “implicit TLS”, i.e., IMAP-over-TLS on port 993, and don’t use STARTTLS at all.

Furthermore, imap-codec uses the following features to facilitate interoperability:

FeatureDescriptionEnabled by default
arbitraryDerive Arbitrary implementations.No
serdeDerive serdes Serialize and Deserialize implementations.No
tokioProvide tokio support.No

When using “arbitrary”, all types defined in imap-codec implement the Arbitrary trait to ease testing. When the “serde” feature is used, all types implement Serde’s Serialize and Deserialize traits. The “tokio_util_compat” feature unlocks an implementation of tokio_util::codec. See the tokio client and tokio server demos.

Re-exports

Modules