io-m2dir 0.2.0

M2dir client library for Rust
Documentation

I/O m2dir Documentation Matrix Mastodon

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

Table of contents

Features

  • 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, blocking client: a ready-made 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.

Specification coverage

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

Usage

The whole API is documented on docs.rs, including runnable snippets for every coroutine and the client.

Examples

The tests demonstrate real usage, and each coroutine module carries a runnable snippet in its documentation.

Have also a look at real-world projects built on top of this library:

AI disclosure

This project is developed with AI assistance. This section documents how, so users and downstream packagers can make informed decisions.

  • Tools: Claude Code (Anthropic), invoked locally with a persistent project-scoped memory and a small set of repo-specific rules.
  • Used for: Refactors, mechanical multi-file edits, boilerplate (feature gates, error enums, derive macros, trait impls), test scaffolding, doc polish, exploratory design conversations.
  • Not used for: Engineering, critical code, git manipulation (commit, merge, rebase…), real-world tests.
  • Verification: Every AI-assisted change is read, compiled, tested, and formatted before commit. Behavioural correctness is verified against the relevant RFC or upstream spec, not assumed from the model output. Tests are never adjusted to fit AI-generated code; the code is adjusted to fit correct behaviour.
  • Limitations: AI models occasionally produce code that compiles and passes tests but is subtly wrong. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.
  • Last reviewed: 16/07/2026

License

This project is licensed under either of:

at your option.

Social

Contributing

Contributions are welcome: start with CONTRIBUTING.md, which opens with the Pimalaya-wide guides to read first.

Sponsoring

nlnet

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

If you appreciate the project, feel free to donate using one of the following providers:

GitHub Ko-fi Buy Me a Coffee Liberapay thanks.dev PayPal