RFC2045-Compliant MIME Encoder/Decoder for Crystal

This is a complete implementation of RFC2045-compliant MIME encoding and decoding functionality in Crystal. It supports Base64 and Quoted-Printable transfer encodings, proper header handling, and MIME message parsing.

Features

Base64 Encoding/Decoding

• Full RFC2045 compliance with proper line folding (76 characters max per line)
• Handles both string and binary data
• Proper padding with '=' characters
• Error handling for invalid input

Quoted-Printable Encoding/Decoding

• Encodes non-printable characters as =XX hex sequences
• Handles soft line breaks for long lines
• Preserves text formatting while ensuring 7-bit safety
• Proper CRLF line ending handling

MIME Header Support

• RFC2047 encoded-word support for international characters
• Content-Type header parsing with parameters
• Content-Transfer-Encoding header parsing
• Header value encoding/decoding with proper charset handling

MIME Message Handling

• Complete MIME message creation and parsing
• Support for all standard transfer encodings (7bit, 8bit, binary, base64, quoted-printable)
• Proper header/body separation
• Header continuation line support

Usage

Basic Base64 Operations

require "./mime"

# Encode string to Base64
text = "Hello, World!"
encoded = MIME::Base64.encode(text)
puts encoded  # SGVsbG8sIFdvcmxkIQ==

# Decode Base64 to bytes
decoded_bytes = MIME::Base64.decode(encoded)
decoded_text = String.new(decoded_bytes)
puts decoded_text  # Hello, World!

# Encode binary data
binary_data = Bytes[0, 1, 2, 255, 254, 253]
encoded_binary = MIME::Base64.encode(binary_data)

Quoted-Printable Operations

# Encode text with special characters
text = "Hello=World\nSpecial chars: café"
encoded = MIME::QuotedPrintable.encode(text)
puts encoded

# Decode quoted-printable
decoded = MIME::QuotedPrintable.decode(encoded)
puts decoded

MIME Message Creation

# Create a new MIME message
message = MIME::Message.new
message.headers["From"] = "sender@example.com"
message.headers["To"] = "recipient@example.com"
message.headers["Subject"] = "Test Message"
message.content_type = "text/plain; charset=UTF-8"
message.transfer_encoding = MIME::Encoding::Base64

# Set and encode the body
body_text = "This is the message body"
message.body = message.encode_body(body_text)

# Generate the complete MIME message
mime_string = message.to_s
puts mime_string

MIME Message Parsing

# Parse a MIME message from string
mime_data = "From: test@example.com\r\n" +
           "Content-Type: text/plain\r\n" +
           "Content-Transfer-Encoding: base64\r\n" +
           "\r\n" +
           "SGVsbG8sIFdvcmxkIQ=="

parsed = MIME::Message.parse(mime_data)
puts parsed.headers["From"]  # test@example.com
puts parsed.decode_body      # Hello, World!

Header Encoding/Decoding

# Encode header with non-ASCII characters
header = "Message with unicode: café"
encoded_header = MIME::Header.encode_header_value(header)
puts encoded_header  # =?UTF-8?B?...?=

# Decode RFC2047 encoded header
decoded_header = MIME::Header.decode_header_value(encoded_header)
puts decoded_header  # Message with unicode: café

# Parse Content-Type header
content_type = "text/html; charset=UTF-8; boundary=xyz"
media_type, params = MIME::Header.parse_content_type(content_type)
puts media_type      # text/html
puts params["charset"]  # UTF-8

Running the Tests

crystal mime_spec.cr

The test suite demonstrates all the functionality and validates the implementation against various test cases.

RFC2045 Compliance

This implementation follows RFC2045 specifications including:

• Line Length Limits: Base64 output is limited to 76 characters per line
• Character Set: Uses the standard Base64 alphabet (A-Z, a-z, 0-9, +, /)
• Padding: Proper use of '=' padding characters
• Quoted-Printable: Correct encoding of non-printable characters
• Soft Line Breaks: Proper handling of quoted-printable soft line breaks
• Header Encoding: RFC2047 encoded-word format for international characters
• MIME Structure: Proper header/body separation and formatting

Error Handling

The implementation includes comprehensive error handling:

• Invalid Base64 characters or length
• Malformed quoted-printable sequences
• Unknown transfer encodings
• Invalid MIME message structure

All errors are raised as MIME::Error exceptions with descriptive messages.

Dependencies

This implementation uses only Crystal's standard library and has no external dependencies.