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");

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.

ParsedPart

A single node in the MIME tree.

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

TransferEncoding variants

Unknown CTE values fall back to Identity and add a warning to ParsedMessage::warnings.

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, UUencode, etc.), and charset-converts the result to UTF-8 via encoding_rs. Decoding is on-demand — parse time is O(message size) and does not decode any bodies.

// Decode with a 64 KiB preview 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
}
if decoded.is_encoding_problem {
    // transfer-decode or charset conversion hit an error; `value` may be partial
}

Inline UUencoded blocks

Some legacy messages — especially Usenet archives and mailing-list digests from the 1990s — embed UU-encoded files inside text/plain bodies with no Content-Transfer-Encoding header. Use scan_inline_uuencode to locate and decode those blocks:

use mime_tree::{parse, scan_inline_uuencode};

let raw: &[u8] = /* raw message bytes */;
let msg = parse(raw).unwrap();

for id in &msg.text_body {
    let part = msg.part_index.find_by_id(id).unwrap();
    for block in scan_inline_uuencode(raw, part) {
        if !block.is_encoding_problem {
            println!("found {} ({} bytes, mode {:o})",
                block.filename, block.data.len(), block.mode);
        }
    }
}

InlineUUBlock fields:

Inline yEnc blocks

Usenet binary posts from the 2000s onward typically use yEnc encoding with no Content-Transfer-Encoding header — the article body is simply text/plain with =ybegin/=yend framing embedded in it. Use scan_inline_yencode to locate and decode those blocks:

use mime_tree::{parse, scan_inline_yencode};

let raw: &[u8] = /* raw message bytes */;
let msg = parse(raw).unwrap();

for id in &msg.text_body {
    let part = msg.part_index.find_by_id(id).unwrap();
    for block in scan_inline_yencode(raw, part) {
        if !block.is_encoding_problem {
            println!("found {} ({} bytes)", block.filename, block.data.len());
        }
    }
}

A reasonable heuristic before calling: check whether the part's decoded text contains the byte sequence b"=ybegin ".

InlineYEncBlock fields:

For multi-part reassembly, pass each InlineYEncBlock's fields to yencoding_multi::Assembler.

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.