Crate imap_codec

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:

Feature	Description	Enabled by default
ext_compress	The IMAP COMPRESS Extension (RFC 4978)	No (but may change)
ext_enable	The IMAP ENABLE Extension (RFC 5161)	No (but may change)
ext_idle	IMAP4 IDLE command (RFC 2177)	No (but may change)
ext_literal	IMAP4 Non-synchronizing Literals (RFC 2088, RFC 7888)	No (but may change)
ext_login_referrals	IMAP4 Login Referrals (RFC 2221)	No (but may change)
ext_mailbox_referrals	IMAP4 Mailbox Referrals (RFC 2193)	No (but may change)
ext_quota	IMAP QUOTA Extension (RFC 9208)	No (but may change)
ext_sasl_ir	IMAP Extension for SASL Initial Client Response (RFC 4959)	No (but may change)
starttls	IMAP4rev1 (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:

Feature	Description	Enabled by default
arbitrary	Derive Arbitrary implementations.	No
serde	Derive serdes Serialize and Deserialize implementations.	No
tokio	Provide 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

• pub use imap_types;
• pub use nom;

Modules

• codec
• command
  Types used in commands
• core
  Core Data Types
• message
  Types used in commands and responses
• response
  Types used in responses
• state
  State and Flow Diagram
• utils