M2dir client library for Rust
This library is composed of 2 feature-gated layers:
- Low-level I/O-free coroutines: no_std-compatible state machines containing the whole m2dir logic, usable anywhere
- Mid-level std client: a standard, blocking client backed by the local filesystem
- I/O-free coroutines: state machines with no filesystem call, no async runtime and no forced I/O model; run them from any blocking, async or test harness.
- Atomic message delivery: a message is written to a temporary file first, then atomically renamed into place, so a reader never sees a half-written entry.
- Sidecar flag metadata: per-message flags live in a separate metadata file next to each entry, added, removed or replaced independently of the message itself.
- Self-contained format primitives: the spec's custom base64, hashing, percent-encoding and pseudo-random naming are computed in-crate, with no external base64, random or percent dependency dragged into the core.
- Standard client: a blocking client backed by the local filesystem, exposing one method per coroutine, with a parallel bulk read for large mailboxes.
Tip
I/O m2dir is written in Rust and uses cargo features to gate the standard client. The default feature set is declared in Cargo.toml or on docs.rs.
This library implements the m2dir mail storage format as I/O-agnostic coroutines, covering the full lifecycle of a store:
| Area | What is covered |
|---|---|
| Store lifecycle | Initialise a store, then create, list and remove mailbox directories, including nested ones |
| Message delivery | Write a message through the atomic temporary-file-then-rename protocol, deriving the filename from the message date, a content checksum and a random nonce |
| Message access | List every message, read one back with checksum validation, and remove it together with its metadata |
| Flags | Add, remove or replace the per-message flag set stored in the metadata sidecar, deleting the sidecar when the set becomes empty |
See documentation at docs.rs.
See complete examples at ./tests.
Have also a look at real-world projects built on top of this library:
- Himalaya CLI: CLI to manage emails
- Himalaya TUI: TUI to manage emails
- Neverest: CLI to synchronize emails
This project is licensed under either of:
- Chat on Matrix
- News on Mastodon or RSS
- Mail at pimalaya.org@posteo.net
Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:
- 2022 → 2023: NGI Assure
- 2023 → 2024: NGI Zero Entrust
- 2024 → 2026: NGI Zero Core
- 2026 → 2027: NGI Zero Commons Fund
This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider sponsoring its development:
