11 个版本 (1 个稳定版)

2.0.0-alpha.3	2024年7月18日
2.0.0-alpha.1	2024年6月7日
1.0.0	2023年8月22日
0.10.0	2023年7月5日
0.6.0	2022年6月14日

#21 在邮件类别中

每月下载量 752
在 4 个 crate 中使用 (通过 imap-codec)

MIT/Apache 许可

390KB
6.5K SLoC

imap-types

%%{init: {'theme': 'neutral' } }%%
flowchart LR
    imap-types -.-> imap-codec
    imap-codec -.-> imap-next
    imap-next -.-> proxy
    imap-next -.-> imap-client
    
    style imap-types stroke-width:4px
    
    click imap-types href "https://github.com/duesee/imap-codec/tree/main/imap-types"
    click imap-codec href "https://github.com/duesee/imap-codec"
    click imap-next href "https://github.com/duesee/imap-next"
    click proxy href "https://github.com/duesee/imap-next/tree/main/proxy"
    click imap-client href "https://github.com/soywod/imap-client"

本 crate 为 IMAP4rev1 协议及其各种扩展提供了一套完整、设计良好的防误用类型。值得注意的是，它不提供解析器或序列化器，而是试图成为 Rust 中 IMAP 的“标准库”，适用于各种 crate。

如果您正在寻找解析器或序列化器，请访问 imap-codec。

特性

Rust 的类型系统用于强制正确性并使库具有防误用特性。无法构造违反 IMAP 规范的消息。
使用模糊测试（通过 cargo fuzz）和基于属性的测试来发现错误。该库经过模糊测试，永远不会生成无效消息。

使用 imap-types

为了确保正确性，imap-types 使用了诸如 AString、Atom、IString、Quoted 和 Literal 等类型。在构造消息时，imap-types 可以自动选择最佳表示形式。但是，始终可以手动选择特定的表示形式。

示例

自动构造

This ...

use imap_types::command::{Command, CommandBody};

let cmd = Command::new(
    "A1",
    CommandBody::login("alice", "password").unwrap()
).unwrap();

... 将生成 ...

A1 LOGIN alice password

但是 ...

use imap_types::command::{Command, CommandBody};

let cmd = Command::new(
    "A1",
    CommandBody::login("alice\"", b"\xCA\xFE".as_ref()).unwrap(),
).unwrap();

... 将生成 ...

A1 LOGIN "alice\"" {2}
\xCA\xFE

此外，构造 ...

use imap_types::command::{Command, CommandBody};

let cmd = Command::new(
    "A1",
    CommandBody::login("alice\x00", "password").unwrap(),
).unwrap();

... 将失败，因为 IMAP 不允许用户名（或密码）中存在 NULL 字节。

手动构造

您还可以使用 ...

use imap_types::{
    command::{Command, CommandBody},
    core::Literal,
};

let cmd = Command::new(
    "A1",
    CommandBody::login(Literal::try_from("alice").unwrap(), "password").unwrap(),
).unwrap();

... 生成 ...

A1 LOGIN {5}
alice password

... 即使 "alice" 可以用原子或引号字符串更简单地编码。

此外，当您确定输入正确时，您可以使用 Rust 文字和 unvalidated 构造函数

use imap_types::{
    command::{Command, CommandBody},
    core::{AString, Atom, Tag},
    secret::Secret,
};

// This could be provided by the email application.
struct TagGenerator;

impl TagGenerator {
    fn random() -> Tag<'static> {
        // Make this random :-)
        Tag::unvalidated("A1")
    }
}

let tag = TagGenerator::random();

let cmd = Command {
    tag,
    body: CommandBody::Login {
        username: AString::from(Atom::unvalidated("alice")),
        password: Secret::new(AString::from(Atom::unvalidated("password"))),
    },
};

在这种情况下，imap-codec 不会妨碍您。但是，它也不会保证您生成正确的消息。

许可

本 crate 在 Apache 2.0 和 MIT 许可证下双许可。

依赖项

~1.5–2.6MB
~47K SLoC