imap_codec/lib.rs
1//! # IMAP protocol library
2//!
3//! imap-codec provides complete and detailed parsing and construction of [IMAP4rev1] commands and responses.
4//! It is based on [imap-types] and extends it with parsing support using [nom].
5//!
6//! The main codecs are
7//! [`GreetingCodec`](crate::GreetingCodec) (to parse the first message from a server),
8//! [`CommandCodec`](crate::CommandCodec) (to parse commands from a client), and
9//! [`ResponseCodec`](crate::ResponseCodec) (to parse responses or results from a server).
10//!
11//! Note that IMAP traces are not guaranteed to be UTF-8.
12//! Thus, be careful when using code like `from_utf8(...)`.
13//!
14//! ## Decoding
15//!
16//! Decoding is provided through the [`Decoder`](`crate::decode::Decoder`) trait.
17//! Every parser takes an input (`&[u8]`) and produces a remainder and a parsed value.
18//!
19//! **Note:** Decoding IMAP traces is more elaborate than it seems on a first glance.
20//! Please consult the [`decode`](`crate::decode`) module documentation to learn how to handle real-world decoding.
21//!
22//! ### Example
23//!
24//! ```rust
25//! # use imap_codec::{
26//! # decode::Decoder,
27//! # imap_types::{
28//! # core::Text,
29//! # response::{Code, Greeting, GreetingKind},
30//! # },
31//! # GreetingCodec,
32//! # };
33//! let (remaining, greeting) = GreetingCodec::default()
34//! .decode(b"* OK [ALERT] Hello, World!\r\n<remaining>")
35//! .unwrap();
36//!
37//! assert_eq!(
38//! greeting,
39//! Greeting {
40//! kind: GreetingKind::Ok,
41//! code: Some(Code::Alert),
42//! text: Text::try_from("Hello, World!").unwrap(),
43//! }
44//! );
45//! assert_eq!(remaining, &b"<remaining>"[..])
46//! ```
47//!
48//! ## Encoding
49//!
50//! Encoding is provided through the [`Encoder`](`crate::encode::Encoder`) trait.
51//!
52//! **Note:** Encoding IMAP traces is more elaborate than it seems on a first glance.
53//! Please consult the [`encode`](`crate::encode`) module documentation to learn how to handle real-world encoding.
54//!
55//! ### Example
56//!
57//! ```rust
58//! # use imap_codec::{
59//! # encode::Encoder,
60//! # imap_types::{
61//! # core::Text,
62//! # response::{Code, Greeting, GreetingKind},
63//! # },
64//! # GreetingCodec,
65//! # };
66//! let greeting = Greeting {
67//! kind: GreetingKind::Ok,
68//! code: Some(Code::Alert),
69//! text: Text::try_from("Hello, World!").unwrap(),
70//! };
71//!
72//! let bytes = GreetingCodec::default().encode(&greeting).dump();
73//!
74//! assert_eq!(bytes, &b"* OK [ALERT] Hello, World!\r\n"[..]);
75//! ```
76//!
77//! ## Features
78//!
79//! imap-codec forwards many features to imap-types. See [imap-types features] for a comprehensive list.
80//!
81//! In addition, imap-codec defines the following features:
82//!
83//! | Feature | Description | Enabled by default |
84//! |-----------------------|--------------------------------|--------------------|
85//! | quirk_crlf_relaxed | Make `\r` in `\r\n` optional. | No |
86//! | quirk_rectify_numbers | Rectify (invalid) numbers. | No |
87//! | quirk_missing_text | Rectify missing `text` element.| No |
88//!
89//! ## Quirks
90//!
91//! Features starting with `quirk_` are used to cope with existing interoperability issues.
92//! Unfortunately, we already observed some standard violations, such as, negative numbers, and missing syntax elements.
93//! Our policy is as follows: If we see an interoperability issue, we file an issue in the corresponding implementation.
94//! If, for any reason, the issue cannot be fixed, *and* the implementation is "important enough", e.g., because a user of
95//! imap-codec can't otherwise access their emails, we may add a `quirk_` feature to quickly resolve the problem.
96//! Of course, imap-codec should never violate the IMAP standard itself. So, we need to do this carefully.
97//!
98//! [imap-types]: https://docs.rs/imap-types/latest/imap_types
99//! [imap-types features]: https://docs.rs/imap-types/latest/imap_types/#features
100//! [IMAP4rev1]: https://tools.ietf.org/html/rfc3501
101//! [parse_command]: https://github.com/duesee/imap-codec/blob/main/examples/parse_command.rs
102
103#![forbid(unsafe_code)]
104#![deny(missing_debug_implementations)]
105#![cfg_attr(docsrs, feature(doc_cfg))]
106
107mod auth;
108mod body;
109mod codec;
110mod command;
111mod core;
112mod datetime;
113mod envelope;
114mod extensions;
115mod fetch;
116mod flag;
117mod mailbox;
118mod response;
119mod search;
120mod sequence;
121mod status;
122#[cfg(test)]
123mod testing;
124
125pub use codec::*;
126// Re-export.
127pub use imap_types;