mime-tree

RFC 5322 / MIME parser that produces a walkable, byte-range-indexed part tree. Given raw message bytes, it returns a ParsedMessage with the full MIME structure, RFC 8621-compatible body views, and on-demand body decoding.

Why this crate exists

Most MIME parsers either give back owned strings (losing the original byte positions needed for S/MIME signature verification) or expose the underlying parsing library's types in their API (locking callers to that dependency). mime-tree gives you (offset, length) byte ranges into your original &[u8] buffer — so you can feed the exact bytes of a signed part directly to a cryptographic verifier without copying or re-encoding. The parsed result is fully owned, lifetime-free, and Serialize + Deserialize, so it round-trips through any store or message bus.

For S/MIME sign/verify/encrypt/decrypt, see the companion crate smime-tree.

Quick example

use mime_tree::{parse, decode_body_value};

let raw: &[u8] = b"From: alice@example.com\r\n\
                   Content-Type: text/plain; charset=utf-8\r\n\
                   \r\n\
                   Hello, world!\r\n";

let msg = parse(raw).expect("parse failed");

// Walk the text_body part IDs to find plain-text parts.
for id in &msg.text_body {
    let part = msg.part_index.find_by_id(id).unwrap();
    let decoded = decode_body_value(raw, part, None).unwrap();
    println!("{}", decoded.value);
}

Key types

ParsedMessage

The result of parse(). All fields are owned; no lifetime parameters.

ParsedMessage implements Serialize + Deserialize — store it however you like.

ParsedPart

A single node in the MIME tree.

Byte ranges use u32 so the serialized representation is identical on 32-bit and 64-bit hosts. MIME messages are bounded well within 4 GiB.

DecodedBodyValue

Returned by decode_body_value().

Decoding body content

decode_body_value slices the raw bytes using a part's body_range, applies transfer-encoding decode (Base64, Quoted-Printable, etc.), and charset-converts the result to UTF-8 via encoding_rs. Decoding is on-demand — parse time is fast.

// Decode with a 64 KiB cap (pass None for unlimited).
let decoded = decode_body_value(raw, &part, Some(65_536))?;
if decoded.is_truncated {
    // body was larger than max_bytes
}

Design invariants

• No JMAP dependency. General-purpose MIME parser; no jmap-mail-types.
• No S/MIME crypto. application/pkcs7-mime and application/pkcs7-signature parts are treated as opaque binary leaves. Use smime-tree for S/MIME processing.
• Best-effort parsing. Malformed input yields a partial result plus warnings; only truly unparsable input (empty bytes, no headers) returns Err.
• No async. Synchronous only.
• Byte ranges, not stored bytes. The crate never retains the raw message bytes.

Specification references

License

Licensed under either of MIT or Apache-2.0 at your option.