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 using nom.

The main codecs are GreetingCodec (to parse the first message from a server), CommandCodec (to parse commands from a client), and ResponseCodec (to parse responses or results from a server).

Note that IMAP traces are not guaranteed to be UTF-8. Thus, be careful when using code like from_utf8(...).

Decoding

Decoding is provided through the Decoder trait. Every parser takes an input (&[u8]) and produces a remainder and a parsed value.

Note: Decoding IMAP traces is more elaborate than it seems on a first glance. Please consult the decode module documentation to learn how to handle real-world decoding.

Example

let (remaining, greeting) = GreetingCodec::default()
    .decode(b"* OK [ALERT] Hello, World!\r\n<remaining>")
    .unwrap();

assert_eq!(
    greeting,
    Greeting {
        kind: GreetingKind::Ok,
        code: Some(Code::Alert),
        text: Text::try_from("Hello, World!").unwrap(),
    }
);
assert_eq!(remaining, &b"<remaining>"[..])

Encoding

Encoding is provided through the Encoder trait.

Note: Encoding IMAP traces is more elaborate than it seems on a first glance. Please consult the encode module documentation to learn how to handle real-world encoding.

Example

let greeting = Greeting {
    kind: GreetingKind::Ok,
    code: Some(Code::Alert),
    text: Text::try_from("Hello, World!").unwrap(),
};

let bytes = GreetingCodec::default().encode(&greeting).dump();

assert_eq!(bytes, &b"* OK [ALERT] Hello, World!\r\n"[..]);

Features

imap-codec forwards many features to imap-types. See imap-types features for a comprehensive list.

In addition, imap-codec defines the following features:

FeatureDescriptionEnabled by default
quirk_crlf_relaxedMake \r in \r\n optional.No
quirk_rectify_numbersRectify (invalid) numbers.No
quirk_missing_textRectify missing text element.No

Quirks

Features starting with quirk_ are used to cope with existing interoperability issues. Unfortunately, we already observed some standard violations, such as, negative numbers, and missing syntax elements. Our policy is as follows: If we see an interoperability issue, we file an issue in the corresponding implementation. If, for any reason, the issue cannot be fixed, and the implementation is “important enough”, e.g., because a user of imap-codec can’t otherwise access their emails, we may add a quirk_ feature to quickly resolve the problem. Of course, imap-codec should never violate the IMAP standard itself. So, we need to do this carefully.

Re-exports

Modules

Structs