MIME Parsing & Codecs

MIME Parsing & Codecs provide the core utilities for handling Multipurpose Internet Mail Extensions (MIME) within Mailiner. This system manages the transformation of raw email data into structured message parts and the serialization of message objects back into RFC 5322 compliant byte streams.

The module encompasses transfer encoding decoding (Base64, Quoted-Printable), charset conversion, parameter normalization (RFC 2231), and header folding. It enables the application to interpret complex message structures like multiparts and ensures that outgoing mail is properly formatted for compatibility across mail user agents.

Sources: crates/mailiner-mime/src/lib.rs:1-4, crates/mailiner-mime/src/writer/mod.rs:1-3

Message Parsing Architecture

The MessageParser converts IMAP BODYSTRUCTURE data into a flat list of MessagePart objects. It employs a registry of specific parsers mapped to MIME types, allowing for extensible handling of text, multiparts, images, and generic attachments.

The diagram shows how the MessageParser distributes data from a raw BODYSTRUCTURE to specialized sub-parsers to produce a unified list of message parts.

Key Parsing Components

• MessageParser: Coordinates the parsing process and maintains a registry of PartParser implementations.
• ParseContext: Carries metadata like the envelope ID and parser registry through the recursive parsing of nested structures.
• leaf_part: A utility function that constructs a MessagePart from a BodyPart, calculating sizes based on encoding and determining visibility.

Sources: crates/mailiner-mime/src/parser/mod.rs:24-35, crates/mailiner-mime/src/parser/mod.rs:133-145

Parameter Normalization

MIME parameters (e.g., filenames in headers) often require decoding from complex formats like RFC 2231 or RFC 2047 encoded-words. The normalize_params function processes raw key-value pairs into a cleaned map with uppercase keys and decoded values.

Normalization Capabilities

Sources: crates/mailiner-mime/src/params.rs:10-20, crates/mailiner-mime/src/params.rs:106-115

The flow represents the logic used to handle different parameter encoding schemes to ensure human-readable results.

Sources: crates/mailiner-mime/src/params.rs:21-65

Codecs and Transfer Encoding

The system implements low-level codecs to handle data transmission over 7-bit ASCII channels.

Base64 Codec

The Base64 implementation provides standard encoding and decoding with specific behaviors for MIME:

• Decoding: Strips whitespace (CR, LF, space, tab) before processing and handles missing padding by normalizing the input length.
• Encoding: Wraps output at 76 columns using CRLF as required by RFC 2045.

Sources: crates/mailiner-mime/src/codec/base64.rs:10-38

Header Encoding (RFC 2047)

For non-ASCII characters in headers, the system uses Quoted-Printable (Q) encoding. The encode_unstructured function determines if a string is pure ASCII; if not, it splits the string into encoded-words limited to 75 characters.

Sources: crates/mailiner-mime/src/writer/mod.rs:88-94, crates/mailiner-mime/src/writer/mod.rs:222-235

Message Writing and Serialization

The serialize_message function constructs a complete RFC 5322 message. It manages header formatting, boundary generation for multiparts, and recursive part writing.

Serialization Flow

The sequence illustrates the steps taken to transform a MimePart tree into a byte stream ready for transmission.

Sources: crates/mailiner-mime/src/writer/mod.rs:62-86, crates/mailiner-mime/src/writer/mod.rs:125-156

Writing Utilities

• generate_boundary: Creates unique MIME boundaries using a UUID prefixed with =_mlnr_.
• format_disposition: Formats Content-Disposition headers, supporting both standard filename and RFC 2231 filename* for non-ASCII names.
• format_mailbox: Formats email addresses, applying RFC 2047 encoding to display names when necessary while keeping the addr-spec intact.

Sources: crates/mailiner-mime/src/writer/mod.rs:104-123, crates/mailiner-mime/src/writer/mod.rs:188-204

Summary

MIME Parsing & Codecs act as the translation layer between the raw protocol bytes and the Mailiner application models. By handling the complexities of parameter reassembly, header folding, and recursive multipart structures, this system ensures high fidelity in message rendering and standards-compliant message generation.

Sources: crates/mailiner-mime/src/lib.rs:1-5