mailrs-rfc2231

RFC 2231 MIME parameter encoder + decoder. Handles non-ASCII parameter values in Content-Type / Content-Disposition:

Content-Disposition: attachment; filename*=UTF-8''%E6%97%A5%E6%9C%AC.pdf
                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                          this — encode + decode

Companion to mailrs-rfc2047 (which handles =?charset?(B|Q)?…?= in header values like Subject / From). Together they cover the full MIME header encoding surface a typical SMTP server needs.

Quickstart

use mailrs_rfc2231::{encode_param, decode_param_value};

// Encode (outbound): UTF-8 source → wire format
let header_line = format!(
    "Content-Disposition: attachment; {}",
    encode_param("filename", "日本.pdf"),
);
// → "Content-Disposition: attachment; filename*=UTF-8''%E6%97%A5%E6%9C%AC.pdf"

// Decode (inbound): wire format → UTF-8
let v = decode_param_value("UTF-8''%E6%97%A5%E6%9C%AC.pdf");
assert_eq!(v.as_deref(), Some("日本.pdf"));

// Legacy quoted form is also accepted on decode.
assert_eq!(decode_param_value("\"test.pdf\"").as_deref(), Some("test.pdf"));

What this crate does

• encode_param(name, value) — emits name="value" for pure ASCII, name*=UTF-8''<percent-encoded> for non-ASCII. UPPERCASE hex (RFC-canonical).
• decode_param_value(s) — accepts the three real-world shapes:
  • legacy quoted: "some value" (strips quotes, unescapes backslashes)
  • legacy unquoted bareword: attachment
  • RFC 2231 extended: charset'lang'percent-encoded (charset resolved via encoding_rs, language tag discarded)
• Lenient percent-decode: %X<non-hex> and lone % are passed through, not rejected.

What this crate does not

• Continuation parameters (filename*0=…; filename*1=… per RFC 2231 §3). Rare in practice; can be added in 1.x without breaking compat if needed.
• Header-line parsing — you give it just the parameter value, not the full Content-Type: …; foo=…; bar=… line. Use mailrs-rfc5322 (or your favorite header parser) to split the line first.
• MIME-tree parsing — this only does parameter values, not the whole MIME structure. Use mail-parser or focused MIME crate.

When to reach for this

Performance

Measured (criterion, M-series Mac, release, 100-sample median):

Reproduce: cargo bench -p mailrs-rfc2231 --bench params. Workspace PERFORMANCE.md carries the same table.

License

Apache-2.0 OR MIT.