parse_net/mail/

words.rs

//! RFC 2047 encoded words in unstructured header text.

use super::b64;
use crate::{
    class,
    error::{ErrorKind, ParseError, Result, WriteError, err},
    limits::Limits,
    utf8::Utf8,
    write::{CountSink, Sink, reserve},
};

/// The longest encoded word (RFC 2047 section 2).
const WORD_LIMIT: usize = 75;
/// `=?UTF-8?Q?` and `?=`.
const OVERHEAD: usize = 12;

/// Whether `b` is written as itself inside a Q-encoded word in a header
/// (RFC 2047 section 5, rule 3).
const fn q_plain(b: u8) -> bool {
    b.is_ascii_alphanumeric() || matches!(b, b'!' | b'*' | b'+' | b'-' | b'/')
}

/// The Q-encoded length of every byte: 1 for a byte written as itself or
/// as `_` (a space), 3 for `=XX`. One lookup instead of the class tests.
// Built at compile time; `b` runs over 0..256, the array's own bounds.
#[allow(clippy::indexing_slicing)]
const Q_LEN: [u8; 256] = {
    let mut t = [3u8; 256];
    let mut b = 0usize;
    while b < 256 {
        if q_plain(b as u8) || b == b' ' as usize {
            t[b] = 1;
        }
        b += 1;
    }
    t
};

/// The Q-encoded length of one byte.
#[inline]
fn q_byte_len(b: u8) -> usize {
    usize::from(Q_LEN.get(usize::from(b)).copied().unwrap_or(3))
}

/// The length in bytes of the UTF-8 character that starts with `b`.
const fn utf8_width(b: u8) -> usize {
    match b {
        0x00..=0x7f => 1,
        0xc0..=0xdf => 2,
        0xe0..=0xef => 3,
        _ => 4,
    }
}

/// The payload of one encoded word, built on the stack: at most 75 bytes
/// less the 12 of `=?UTF-8?Q?` and `?=`.
struct Payload {
    buf: [u8; WORD_LIMIT - OVERHEAD],
    len: usize,
}

impl Payload {
    /// Appends the Q encoding of `ch` (one UTF-8 character); the caller has
    /// checked that it fits.
    fn push(&mut self, ch: &[u8]) {
        const HEX: &[u8; 16] = b"0123456789ABCDEF";
        for &b in ch {
            let len = self.len;
            if q_byte_len(b) == 1 {
                if let Some(d) = self.buf.get_mut(len) {
                    *d = if b == b' ' { b'_' } else { b };
                }
                self.len = len + 1;
            } else {
                let hi = HEX.get(usize::from(b >> 4)).copied().unwrap_or(b'0');
                let lo = HEX.get(usize::from(b & 0xf)).copied().unwrap_or(b'0');
                if let Some([x, y, z]) = self.buf.get_mut(len..len + 3) {
                    (*x, *y, *z) = (b'=', hi, lo);
                }
                self.len = len + 3;
            }
        }
    }

    fn as_bytes(&self) -> &[u8] {
        self.buf.get(..self.len).unwrap_or(&[])
    }
}

/// Whether `text` goes out as it is under the `B` encoder: printable ASCII
/// without `=?` whose line stays legal. `put_words` keeps its own copy of
/// this test: called from there, it cost the Q encoder 2% (callgrind).
#[inline]
fn goes_plain(text: &str, room_first_line: usize) -> bool {
    let bytes = text.as_bytes();
    let used = super::SOFT_LIMIT.saturating_sub(room_first_line);
    bytes.iter().all(|b| (0x20..=0x7e).contains(b))
        && !text.contains("=?")
        && used + bytes.len() <= super::HARD_LIMIT
}

fn put_words(
    text: &str,
    room_first_line: usize,
    out: &mut impl Sink,
) -> core::result::Result<(), WriteError> {
    let bytes = text.as_bytes();
    // Plain text goes out as it is while its line stays legal; past that it
    // is encoded, which breaks it into words.
    let used = super::SOFT_LIMIT.saturating_sub(room_first_line);
    if bytes.iter().all(|b| (0x20..=0x7e).contains(b))
        && !text.contains("=?")
        && used + bytes.len() <= super::HARD_LIMIT
    {
        out.put(bytes)?;
        return Ok(());
    }
    let mut limit = room_first_line.min(WORD_LIMIT);
    let mut word = Payload {
        buf: [0; WORD_LIMIT - OVERHEAD],
        len: 0,
    };
    let mut open = false;
    let mut i = 0usize;
    while let Some(&lead) = bytes.get(i) {
        let ch = bytes.get(i..i + utf8_width(lead)).unwrap_or(&[]);
        i += ch.len().max(1);
        let mut n = 0usize;
        for &b in ch {
            n += q_byte_len(b);
        }
        if open && OVERHEAD + word.len + n > limit {
            out.put(word.as_bytes())?;
            out.put(b"?=\r\n ")?;
            open = false;
            limit = WORD_LIMIT;
        }
        if !open {
            if OVERHEAD + n > limit {
                // Not even one character fits in the room left on the first
                // line: start on a new one.
                out.put(b"\r\n ")?;
                limit = WORD_LIMIT;
            }
            out.put(b"=?UTF-8?Q?")?;
            open = true;
            word.len = 0;
        }
        word.push(ch);
    }
    if open {
        out.put(word.as_bytes())?;
        out.put(b"?=")?;
    }
    Ok(())
}

/// Writes `text` for an unstructured header field: as it is when it is
/// printable ASCII without `=?` that fits in a 998-byte line, otherwise as
/// RFC 2047 `=?UTF-8?Q?...?=`
/// words of at most 75 bytes, split only between characters, separated by
/// CRLF SP. The first word fits in `room_first_line` (the columns left after
/// `Name: `); when not even one character fits there, the words start on a
/// new line.
///
/// # Errors
///
/// [`WriteError::Forbidden`] for a control character (C0, DEL, or C1);
/// [`WriteError::Full`] (nothing written when the sink reports its room).
///
/// # Examples
///
/// ```
/// use parse_net::{mail, SliceSink};
///
/// let mut buf = [0u8; 256];
/// let mut out = SliceSink::new(&mut buf);
/// mail::encode_words("Caf\u{e9} au lait", 64, &mut out).expect("room");
/// assert_eq!(out.written(), b"=?UTF-8?Q?Caf=C3=A9_au_lait?=");
/// ```
pub fn encode_words(
    text: &str,
    room_first_line: usize,
    out: &mut impl Sink,
) -> core::result::Result<(), WriteError> {
    if let Some((at, _)) = text.char_indices().find(|&(_, c)| c.is_control()) {
        return Err(WriteError::forbidden(at));
    }
    let mut count = CountSink::new();
    put_words(text, room_first_line, &mut count)?;
    reserve(out, count.count())?;
    put_words(text, room_first_line, out)
}

/// Writes one `=?UTF-8?B?...?=` word holding `chunk`, at most 45 bytes.
fn put_b_word(chunk: &[u8], out: &mut impl Sink) -> core::result::Result<(), WriteError> {
    let mut buf = [0u8; WORD_LIMIT - OVERHEAD];
    let n = b64::encode(chunk, &mut buf);
    out.put(b"=?UTF-8?B?")?;
    out.put(buf.get(..n).unwrap_or(&[]))?;
    out.put(b"?=")?;
    Ok(())
}

fn put_words_b(
    text: &str,
    room_first_line: usize,
    out: &mut impl Sink,
) -> core::result::Result<(), WriteError> {
    let bytes = text.as_bytes();
    if goes_plain(text, room_first_line) {
        out.put(bytes)?;
        return Ok(());
    }
    let mut limit = room_first_line.min(WORD_LIMIT);
    // The characters of the word being built: `bytes[start..start + len]`.
    let (mut start, mut len) = (0usize, 0usize);
    while let Some(&lead) = bytes.get(start + len) {
        let w = utf8_width(lead);
        if len > 0 && OVERHEAD + b64::encoded_len(len + w) > limit {
            put_b_word(bytes.get(start..start + len).unwrap_or(&[]), out)?;
            out.put(b"\r\n ")?;
            (start, len, limit) = (start + len, 0, WORD_LIMIT);
        }
        if len == 0 && OVERHEAD + b64::encoded_len(w) > limit {
            // Not even one character fits in the room left on the first
            // line: start on a new one.
            out.put(b"\r\n ")?;
            limit = WORD_LIMIT;
        }
        len += w;
    }
    if len > 0 {
        put_b_word(bytes.get(start..start + len).unwrap_or(&[]), out)?;
    }
    Ok(())
}

/// [`encode_words`] with the RFC 2047 `B` encoding: `=?UTF-8?B?...?=` words
/// of at most 75 bytes, split only between characters, separated by CRLF SP.
/// Text that goes out as it is under [`encode_words`] goes out as it is here.
/// `B` costs four bytes for every three, `Q` three for every byte it escapes,
/// so `B` is the shorter for text that is mostly not ASCII: a Japanese or
/// Chinese subject is about 40% shorter. [`decode_words`] reads both.
///
/// # Errors
///
/// [`WriteError::Forbidden`] for a control character (C0, DEL, or C1);
/// [`WriteError::Full`] (nothing written when the sink reports its room).
///
/// # Examples
///
/// ```
/// use parse_net::{mail, Limits, SliceSink};
///
/// let mut buf = [0u8; 256];
/// let mut out = SliceSink::new(&mut buf);
/// mail::encode_words_b("\u{4f1a}\u{8b70}\u{306e}\u{304a}\u{77e5}\u{3089}\u{305b}", 64, &mut out).expect("room");
/// assert_eq!(out.written(), b"=?UTF-8?B?5Lya6K2w44Gu44GK55+l44KJ44Gb?=");
///
/// let mut text = [0u8; 64];
/// let s = mail::decode_words(out.written(), &Limits::DEFAULT, &mut text)?;
/// assert_eq!(s, "\u{4f1a}\u{8b70}\u{306e}\u{304a}\u{77e5}\u{3089}\u{305b}");
/// # Ok::<(), parse_net::ParseError>(())
/// ```
pub fn encode_words_b(
    text: &str,
    room_first_line: usize,
    out: &mut impl Sink,
) -> core::result::Result<(), WriteError> {
    if let Some((at, _)) = text.char_indices().find(|&(_, c)| c.is_control()) {
        return Err(WriteError::forbidden(at));
    }
    let mut count = CountSink::new();
    put_words_b(text, room_first_line, &mut count)?;
    reserve(out, count.count())?;
    put_words_b(text, room_first_line, out)
}

/// The charsets decoded.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Charset {
    Utf8,
    Ascii,
    Latin1,
}

/// The parts of an encoded word.
pub(super) struct Encoded<'a> {
    charset: Charset,
    /// The `B` encoding.
    base64: bool,
    text: &'a [u8],
    /// The index after the closing `?=`.
    pub(super) end: usize,
}

/// An encoded word at `v[i..]`: `=?charset?enc?text?=`, standing alone.
/// `Ok(None)` when the bytes do not have that shape, or do not stand between
/// whitespace: they are then ordinary text, whatever charset they name. Each
/// scan stops at the first byte that cannot continue, so failed candidates
/// never add up to a second pass over the value.
pub(super) fn shape(v: &[u8], i: usize) -> Result<Option<Encoded<'_>>> {
    let rest = v.get(i + 2..).unwrap_or(&[]);
    let q1 = rest
        .iter()
        .position(|&b| !class::is_mime_token_char(b))
        .unwrap_or(rest.len());
    if q1 == 0 || rest.get(q1) != Some(&b'?') {
        return Ok(None);
    }
    let charset = rest.get(..q1).unwrap_or(&[]);
    let after = rest.get(q1 + 1..).unwrap_or(&[]);
    let (Some(&enc), Some(b'?')) = (after.first(), after.get(1)) else {
        return Ok(None);
    };
    let text_start = i + 2 + q1 + 3;
    let text_rest = v.get(text_start..).unwrap_or(&[]);
    let Some(end) = text_rest
        .iter()
        .position(|&b| matches!(b, b'?' | b' ' | b'\t'))
    else {
        return Ok(None);
    };
    if text_rest.get(end..end + 2) != Some(b"?=") {
        return Ok(None);
    }
    let text = text_rest.get(..end).unwrap_or(&[]);
    let after_word = text_start + end + 2;
    if after_word != v.len() && ws_len(v, after_word) == 0 {
        return Ok(None);
    }
    // RFC 2231 section 5: `charset*language`.
    let name = charset.split(|&b| b == b'*').next().unwrap_or(&[]);
    let cs = if name.eq_ignore_ascii_case(b"utf-8") {
        Charset::Utf8
    } else if name.eq_ignore_ascii_case(b"us-ascii") {
        Charset::Ascii
    } else if name.eq_ignore_ascii_case(b"iso-8859-1") {
        Charset::Latin1
    } else {
        return err(ErrorKind::UnsupportedCharset, i + 2);
    };
    let b = match enc {
        b'Q' | b'q' => false,
        b'B' | b'b' => true,
        _ => return err(ErrorKind::InvalidEncodedWord, i + 2 + q1 + 1),
    };
    Ok(Some(Encoded {
        charset: cs,
        base64: b,
        text,
        end: after_word,
    }))
}

/// The length of the whitespace unit at `v[i]`: SP, HTAB, or a `CRLF WSP`
/// fold; 0 for anything else.
pub(super) fn ws_len(v: &[u8], i: usize) -> usize {
    match (v.get(i), v.get(i + 1), v.get(i + 2)) {
        (Some(b' ' | b'\t'), _, _) => 1,
        (Some(b'\r'), Some(b'\n'), Some(b' ' | b'\t')) => 3,
        _ => 0,
    }
}

/// The text outside encoded words, checked as it is copied: UTF-8 (raw bytes
/// above 0x7F are RFC 6532 text), with no control character but HTAB.
pub(super) struct Text {
    utf8: Utf8,
    prev: u8,
}

impl Text {
    /// A checker at a character boundary.
    pub(super) const fn new() -> Self {
        Self {
            utf8: Utf8::new(),
            prev: 0,
        }
    }

    /// Whether the text so far ends on a character boundary.
    pub(super) const fn is_complete(&self) -> bool {
        self.utf8.is_complete()
    }

    pub(super) fn check(&mut self, b: u8, at: usize) -> Result<()> {
        if b != b'\t' && crate::scan::is_control(b) {
            return err(crate::scan::control_kind(b), at);
        }
        if self.prev == 0xc2 && (0x80..=0x9f).contains(&b) {
            return err(ErrorKind::Control, at);
        }
        if !self.utf8.push(b) {
            return err(ErrorKind::InvalidUtf8, at);
        }
        self.prev = b;
        Ok(())
    }

    /// Copies a whitespace run, leaving out the CRLF of its folds.
    fn run(&mut self, v: &[u8], s: usize, e: usize, emit: &mut impl FnMut(&[u8])) -> Result<()> {
        let mut i = s;
        while i < e {
            let n = ws_len(v, i);
            let at = i + n - 1;
            let wsp = v.get(at).copied().unwrap_or(b' ');
            self.check(wsp, at)?;
            emit(&[wsp]);
            i += n;
        }
        Ok(())
    }
}

/// The index of the `"` closing a quoted string whose body starts at `from`.
fn closing_quote(v: &[u8], from: usize) -> Option<usize> {
    let mut i = from;
    loop {
        match v.get(i)? {
            b'\\' => i += 2,
            b'"' => return Some(i),
            _ => i += 1,
        }
    }
}

/// The checks every decoded byte meets, whichever the encoding, then its
/// UTF-8 form emitted. `start` is the offset reported for it.
#[inline(always)]
fn put_decoded(
    cs: Charset,
    byte: u8,
    prev: &mut u8,
    utf8: &mut Utf8,
    start: usize,
    emit: &mut impl FnMut(&[u8]),
) -> Result<()> {
    // Every control character is refused, as in ext-values: C0 (HTAB
    // included), DEL, and C1 (U+0080 to U+009F: `C2 80` to `C2 9F` in
    // UTF-8, where 0xC2 is always a lead byte; bytes 0x80 to 0x9F in
    // ISO-8859-1).
    let c1 = match cs {
        Charset::Utf8 => *prev == 0xc2 && (0x80..=0x9f).contains(&byte),
        Charset::Latin1 => (0x80..=0x9f).contains(&byte),
        Charset::Ascii => false,
    };
    if byte < 0x20 || byte == 0x7f || c1 {
        return err(ErrorKind::ControlInDecoded, start);
    }
    *prev = byte;
    match cs {
        Charset::Utf8 => {
            if !utf8.push(byte) {
                return err(ErrorKind::InvalidUtf8, start);
            }
            emit(&[byte]);
        }
        Charset::Ascii if byte >= 0x80 => {
            return err(ErrorKind::InvalidEncodedWord, start);
        }
        Charset::Ascii => emit(&[byte]),
        Charset::Latin1 if byte >= 0x80 => emit(&[0xc0 | (byte >> 6), 0x80 | (byte & 0x3f)]),
        Charset::Latin1 => emit(&[byte]),
    }
    Ok(())
}

/// Decodes one B word's text, emitting UTF-8. The base64 is strict
/// (`b64::decode`); each byte is then checked as a Q word's is, and reported
/// at the group of four that holds it.
fn decode_b(cs: Charset, text: &[u8], at: usize, emit: &mut impl FnMut(&[u8])) -> Result<()> {
    let mut bytes = [0u8; b64::MAX_DECODED];
    let n =
        b64::decode(text, &mut bytes).or_else(|i| err(ErrorKind::InvalidEncodedWord, at + i))?;
    let decoded = bytes.get(..n).unwrap_or(&[]);
    // A word that passes every check goes out in one piece. The checks are
    // those of `put_decoded`, over the whole word at once: no C0 or DEL, no
    // C1 (`C2 80` to `C2 9F`), whole UTF-8 characters; ASCII for the other
    // charsets. Anything else takes the byte loop, which finds the error.
    let ascii_text = |d: &[u8]| d.iter().all(|&b| (0x20..0x7f).contains(&b));
    let clean = match cs {
        Charset::Utf8 => {
            decoded.iter().all(|&b| b >= 0x20 && b != 0x7f)
                && !decoded
                    .iter()
                    .zip(decoded.iter().skip(1))
                    .any(|(&a, &b)| a == 0xc2 && (0x80..=0x9f).contains(&b))
                && core::str::from_utf8(decoded).is_ok()
        }
        Charset::Ascii | Charset::Latin1 => ascii_text(decoded),
    };
    if clean {
        emit(decoded);
        return Ok(());
    }
    let mut utf8 = Utf8::new();
    let mut prev = 0u8;
    for (k, &byte) in decoded.iter().enumerate() {
        put_decoded(cs, byte, &mut prev, &mut utf8, at + k / 3 * 4, emit)?;
    }
    if !utf8.is_complete() {
        // Each encoded word holds whole characters (RFC 2047 section 5).
        return err(ErrorKind::InvalidUtf8, at + text.len());
    }
    Ok(())
}

/// Decodes one Q word's text, emitting UTF-8.
fn decode_q(cs: Charset, text: &[u8], at: usize, emit: &mut impl FnMut(&[u8])) -> Result<()> {
    let mut utf8 = Utf8::new();
    let (mut i, mut prev) = (0usize, 0u8);
    while let Some(&b) = text.get(i) {
        let start = at + i;
        // A run of bytes written as themselves goes out whole: printable
        // ASCII, which passes every check of `put_decoded` on a character
        // boundary.
        let plain = |c: u8| matches!(c, 0x21..=0x7e) && c != b'_' && c != b'=';
        if plain(b) {
            if !utf8.is_complete() {
                return err(ErrorKind::InvalidUtf8, start);
            }
            let run = text.get(i..).unwrap_or(&[]);
            let n = run.iter().position(|&c| !plain(c)).unwrap_or(run.len());
            emit(run.get(..n).unwrap_or(&[]));
            prev = run.get(n - 1).copied().unwrap_or(b);
            i += n;
            continue;
        }
        let byte = match b {
            b'_' => b' ',
            b'=' => {
                let hi = text.get(i + 1).copied().and_then(class::hex_value);
                let lo = text.get(i + 2).copied().and_then(class::hex_value);
                let (Some(hi), Some(lo)) = (hi, lo) else {
                    return err(ErrorKind::InvalidEncodedWord, start);
                };
                i += 2;
                (hi << 4) | lo
            }
            0x21..=0x7e => b,
            _ => return err(ErrorKind::InvalidEncodedWord, start),
        };
        i += 1;
        put_decoded(cs, byte, &mut prev, &mut utf8, start, emit)?;
    }
    if !utf8.is_complete() {
        // Each encoded word holds whole characters (RFC 2047 section 5).
        return err(ErrorKind::InvalidUtf8, at + text.len());
    }
    Ok(())
}

/// Decodes `e`, an encoded word that starts at `start` in the value.
pub(super) fn decode_word(
    e: &Encoded<'_>,
    start: usize,
    emit: &mut impl FnMut(&[u8]),
) -> Result<()> {
    decode_encoded(e.charset, e.base64, e.text, start, e.end, emit)
}

fn decode_encoded(
    cs: Charset,
    b64: bool,
    word: &[u8],
    start: usize,
    end: usize,
    emit: &mut impl FnMut(&[u8]),
) -> Result<()> {
    let at = end - 2 - word.len();
    if b64 {
        // A `B` word keeps to the 75-byte limit of section 2, which also
        // bounds what it decodes to (D-080).
        if end - start > WORD_LIMIT {
            return err(ErrorKind::InvalidEncodedWord, start);
        }
        decode_b(cs, word, at, emit)
    } else {
        decode_q(cs, word, at, emit)
    }
}

/// Walks `v`, emitting the decoded text. Whitespace includes folds, whose
/// CRLF is dropped, so the folded output of [`encode_words`] reads back. A
/// quoted string starts at a word boundary and needs its closing `"`: a lone
/// `"` (`5" disk`) is ordinary text. One pass: every scan ahead either
/// consumes what it read or stops at the first byte that rules it out.
fn walk(v: &[u8], limits: &Limits, emit: &mut impl FnMut(&[u8])) -> Result<()> {
    let mut text = Text::new();
    let (mut i, mut words) = (0usize, 0usize);
    let (mut boundary, mut after_word) = (true, false);
    let mut held: Option<(usize, usize)> = None;
    // Inside a quoted string while `i` is below this.
    let mut quoted_until = 0usize;
    // Cleared when no closing quote is left, so that scan is not repeated.
    let mut closes = true;
    while let Some(&b) = v.get(i) {
        if i < quoted_until {
            if ws_len(v, i) == 3 {
                i += 2;
                continue;
            }
            text.check(b, i)?;
            emit(&[b]);
            i += 1;
            continue;
        }
        if ws_len(v, i) > 0 {
            let start = i;
            while ws_len(v, i) > 0 {
                i += ws_len(v, i);
            }
            if after_word {
                held = Some((start, i));
            } else {
                text.run(v, start, i, emit)?;
            }
            boundary = true;
            continue;
        }
        if boundary && v.get(i..i + 2) == Some(b"=?") {
            if let Some(Encoded {
                charset: cs,
                base64: b64,
                text: word,
                end,
            }) = shape(v, i)?
            {
                if !text.utf8.is_complete() {
                    return err(ErrorKind::InvalidUtf8, i);
                }
                words += 1;
                if words > usize::from(limits.encoded_words) {
                    return err(ErrorKind::TooManyMembers, i);
                }
                // Whitespace between two encoded words is dropped
                // (RFC 2047 section 6.2).
                held = None;
                decode_encoded(cs, b64, word, i, end, emit)?;
                after_word = true;
                boundary = false;
                i = end;
                continue;
            }
        }
        if let Some((s, e)) = held.take() {
            text.run(v, s, e, emit)?;
        }
        after_word = false;
        if b == b'"' && boundary && closes {
            match closing_quote(v, i + 1) {
                Some(close) => quoted_until = close + 1,
                None => closes = false,
            }
        }
        boundary = false;
        text.check(b, i)?;
        emit(&[b]);
        i += 1;
    }
    if let Some((s, e)) = held {
        text.run(v, s, e, emit)?;
    }
    if !text.utf8.is_complete() {
        return err(ErrorKind::InvalidUtf8, v.len());
    }
    Ok(())
}

/// Decodes the RFC 2047 encoded words in unstructured header text into
/// `out` and returns the text. Text outside encoded words is copied;
/// whitespace between two adjacent encoded words is dropped (section 6.2);
/// `_` is a space in Q; an encoded word must stand alone between whitespace,
/// and words inside a quoted string are not decoded (section 5). Charsets:
/// UTF-8, US-ASCII, ISO-8859-1 (transcoded), with an optional RFC 2231
/// `*language`. `B` words are read strictly (D-080): whole groups of four,
/// `=` padding only at the end with zero bits under it, no whitespace inside,
/// and at most 75 bytes to a word. `CRLF WSP` folds count as whitespace, so
/// the output of [`encode_words`] and [`encode_words_b`] reads back as
/// written.
///
/// # Errors
///
/// [`ErrorKind::UnsupportedCharset`]; [`ErrorKind::InvalidEncodedWord`] (a
/// bad encoding letter, a broken `=XX`, a byte not allowed in a Q word, base64
/// that is not canonical, a `B` word longer than 75 bytes);
/// [`ErrorKind::ControlInDecoded`] for a decoded control
/// character (C0 including CR, LF, NUL, and HTAB; DEL; C1), as in ext-values;
/// a control kind for a control byte outside the words, other than HTAB and
/// the CRLF of a fold; [`ErrorKind::InvalidUtf8`] (a UTF-8 word that is not
/// whole characters, or text outside the words that is not UTF-8);
/// [`ErrorKind::TooManyMembers`]
/// beyond `max_encoded_words`; [`ErrorKind::BufferTooSmall`]. Nothing is
/// written on error.
///
/// # Examples
///
/// ```
/// use parse_net::{mail, Limits};
///
/// let mut buf = [0u8; 64];
/// let s = mail::decode_words(b"=?utf-8?q?Caf=C3=A9?= =?ISO-8859-1?Q?_cr=E8me?= now", &Limits::DEFAULT, &mut buf)?;
/// assert_eq!(s, "Caf\u{e9} cr\u{e8}me now");
/// # Ok::<(), parse_net::ParseError>(())
/// ```
pub fn decode_words<'b>(value: &[u8], limits: &Limits, out: &'b mut [u8]) -> Result<&'b str> {
    let mut len = 0usize;
    walk(value, limits, &mut |b: &[u8]| len += b.len())?;
    let Some(dst) = out.get_mut(..len) else {
        return err(ErrorKind::BufferTooSmall, 0);
    };
    let mut n = 0usize;
    walk(value, limits, &mut |b: &[u8]| {
        if let Some(d) = dst.get_mut(n..n + b.len()) {
            d.copy_from_slice(b);
        }
        n += b.len();
    })?;
    // The first walk checked the text; this is the safe conversion.
    core::str::from_utf8(dst).map_err(|e| ParseError::new(ErrorKind::InvalidUtf8, e.valid_up_to()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::{format, string::String, vec, vec::Vec};

    fn enc(text: &str, room: usize) -> String {
        let mut buf = vec![0u8; 2048];
        let mut out = crate::SliceSink::new(&mut buf);
        encode_words(text, room, &mut out).unwrap();
        String::from_utf8(out.written().to_vec()).unwrap()
    }

    fn dec(v: &[u8]) -> Result<String> {
        let mut buf = vec![0u8; 2048];
        decode_words(v, &Limits::DEFAULT, &mut buf).map(String::from)
    }

    #[test]
    fn test_encode_words_edge_cases() {
        assert_eq!(enc("plain ascii", 10), "plain ascii");
        assert_eq!(enc("a =?b", 70), "=?UTF-8?Q?a_=3D=3Fb?=");
        let long = "\u{e9}".repeat(40);
        let e = enc(&long, 75);
        for word in e.split("\r\n ") {
            assert!(word.len() <= 75 && word.starts_with("=?UTF-8?Q?") && word.ends_with("?="));
            // Each word holds whole characters, so it decodes on its own.
            assert!(dec(word.as_bytes()).is_ok());
        }
        assert_eq!(dec(e.replace("\r\n", "").as_bytes()).unwrap(), long);
        // An encoded word of exactly 75 bytes: 63 bytes of payload.
        let e = enc(&"\u{20ac}".repeat(7), 75);
        assert_eq!(e.len(), 12 + 63);
        assert!(!e.starts_with("\r\n "));
        assert!(enc("\u{e9}", 5).starts_with("\r\n =?UTF-8?Q?"));
        let mut buf = [0u8; 8];
        let mut out = crate::SliceSink::new(&mut buf);
        assert_eq!(
            encode_words("a\nb", 70, &mut out),
            Err(WriteError::Forbidden { at: 1 })
        );
        assert_eq!(
            encode_words("a\u{85}", 70, &mut out),
            Err(WriteError::Forbidden { at: 1 })
        );
        assert_eq!(
            encode_words("\u{e9}\u{e9}", 70, &mut out),
            Err(WriteError::Full)
        );
        assert!(out.is_empty());
    }

    #[test]
    fn test_decode_words_edge_cases() {
        assert_eq!(dec(b"=?utf-8?q?a_b?=").unwrap(), "a b");
        assert_eq!(dec(b"=?UTF-8?Q?a?=  \t =?UTF-8?Q?b?=").unwrap(), "ab");
        assert_eq!(dec(b"=?UTF-8?Q?a?= x =?UTF-8?Q?b?= ").unwrap(), "a x b ");
        assert_eq!(dec(b"\"=?UTF-8?Q?a?=\"").unwrap(), "\"=?UTF-8?Q?a?=\"");
        assert_eq!(dec(b"x=?UTF-8?Q?a?=").unwrap(), "x=?UTF-8?Q?a?=");
        assert_eq!(dec(b"=?UTF-8?Q?a?=x").unwrap(), "=?UTF-8?Q?a?=x");
        assert_eq!(dec(b"=?UTF-8*en?Q?a?=").unwrap(), "a");
        assert_eq!(dec(b"=? not a word").unwrap(), "=? not a word");
        assert_eq!(dec(b"=?US-ASCII?Q?ok?=").unwrap(), "ok");
        assert_eq!(
            dec(b"=?KOI8-R?Q?a?=").unwrap_err().kind(),
            ErrorKind::UnsupportedCharset
        );
        assert_eq!(
            dec(b"=?UTF-8?X?a?=").unwrap_err().kind(),
            ErrorKind::InvalidEncodedWord
        );
        assert_eq!(
            dec(b"=?UTF-8?Q?=4?=").unwrap_err().kind(),
            ErrorKind::InvalidEncodedWord
        );
        assert_eq!(dec(b"=?UTF-8?B?YQ==?=").unwrap(), "a");
        assert_eq!(
            dec(b"=?UTF-8?Q?=0D=0A?=").unwrap_err().kind(),
            ErrorKind::ControlInDecoded
        );
        assert_eq!(
            dec(b"=?UTF-8?Q?=C3?=").unwrap_err().kind(),
            ErrorKind::InvalidUtf8
        );
        assert_eq!(
            dec(b"=?US-ASCII?Q?=E9?=").unwrap_err().kind(),
            ErrorKind::InvalidEncodedWord
        );
        assert_eq!(dec(b"raw \xe9").unwrap_err().kind(), ErrorKind::InvalidUtf8);
        let l = Limits::DEFAULT.max_encoded_words(2);
        let mut buf = [0u8; 64];
        assert!(decode_words(b"=?UTF-8?Q?a?= =?UTF-8?Q?b?=", &l, &mut buf).is_ok());
        assert_eq!(
            decode_words(b"=?UTF-8?Q?a?= =?UTF-8?Q?b?= =?UTF-8?Q?c?=", &l, &mut buf)
                .unwrap_err()
                .kind(),
            ErrorKind::TooManyMembers
        );
        let mut small = [0u8; 2];
        assert_eq!(
            decode_words(b"abc", &Limits::DEFAULT, &mut small)
                .unwrap_err()
                .kind(),
            ErrorKind::BufferTooSmall
        );
        assert_eq!(small, [0, 0]);
    }

    fn enc_b(text: &str, room: usize) -> String {
        let mut buf = vec![0u8; 4096];
        let mut out = crate::SliceSink::new(&mut buf);
        encode_words_b(text, room, &mut out).unwrap();
        String::from_utf8(out.written().to_vec()).unwrap()
    }

    #[test]
    fn test_decode_b_words() {
        // RFC 2047 section 8, the first word of its `Subject` example (the
        // second is ISO-8859-2, not a charset read here).
        assert_eq!(
            dec(b"=?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=").unwrap(),
            "If you can read this yo"
        );
        assert_eq!(
            dec(b"=?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=\r\n =?ISO-8859-1?Q?u?=")
                .unwrap(),
            "If you can read this you"
        );
        assert_eq!(
            dec(b"=?utf-8?b?Q2Fmw6k=?= au lait").unwrap(),
            "Caf\u{e9} au lait"
        );
        assert_eq!(dec(b"=?ISO-8859-1?B?6Q==?=").unwrap(), "\u{e9}");
        assert_eq!(dec(b"=?UTF-8*ja?B?5Lya?=").unwrap(), "\u{4f1a}");
        assert_eq!(dec(b"=?UTF-8?B??=").unwrap(), "");
        // Strict base64, at the offset of the character refused.
        let at = |v: &[u8]| {
            let e = dec(v).unwrap_err();
            (e.kind(), e.offset())
        };
        assert_eq!(at(b"=?UTF-8?B?YQ=?="), (ErrorKind::InvalidEncodedWord, 10));
        assert_eq!(at(b"=?UTF-8?B?YR==?="), (ErrorKind::InvalidEncodedWord, 11));
        assert_eq!(
            at(b"=?UTF-8?B?YQ==YQ==?="),
            (ErrorKind::InvalidEncodedWord, 12)
        );
        assert_eq!(at(b"=?UTF-8?B?Y-Q=?="), (ErrorKind::InvalidEncodedWord, 11));
        assert_eq!(
            at(b"=?UTF-8?B?YWJj\x80?="),
            (ErrorKind::InvalidEncodedWord, 14)
        );
        // Whitespace ends the candidate: it is ordinary text, as in Q.
        assert_eq!(dec(b"=?UTF-8?B?YW Jj?=").unwrap(), "=?UTF-8?B?YW Jj?=");
        // Decoded bytes meet the Q rules, reported at their group of four.
        assert_eq!(at(b"=?UTF-8?B?YQ0K?="), (ErrorKind::ControlInDecoded, 10));
        assert_eq!(
            at(b"=?UTF-8?B?YWJjGw==?="),
            (ErrorKind::ControlInDecoded, 14)
        );
        assert_eq!(at(b"=?UTF-8?B?woU=?="), (ErrorKind::ControlInDecoded, 10));
        assert_eq!(at(b"=?ISO-8859-1?B?hQ==?=").0, ErrorKind::ControlInDecoded);
        assert_eq!(dec(b"=?UTF-8?B?w6k=?=x").unwrap(), "=?UTF-8?B?w6k=?=x");
        assert_eq!(at(b"=?UTF-8?B?ww==?=").0, ErrorKind::InvalidUtf8);
        assert_eq!(at(b"=?US-ASCII?B?6Q==?=").0, ErrorKind::InvalidEncodedWord);
        // 75 bytes to a word: 64 base64 characters fit after `=?a?B?`.
        let word = |n: usize| format!("=?UTF-8?B?{}?=", "QUFB".repeat(n));
        assert_eq!(dec(word(15).as_bytes()).unwrap(), "A".repeat(45));
        let long = format!("=?UTF-8?B?{}QQ==?=", "QUFB".repeat(15));
        assert_eq!(long.len(), 76);
        assert_eq!(at(long.as_bytes()), (ErrorKind::InvalidEncodedWord, 0));
        assert_eq!(at(word(16).as_bytes()), (ErrorKind::InvalidEncodedWord, 0));
    }

    #[test]
    fn test_encode_words_b_edge_cases() {
        assert_eq!(enc_b("plain ascii", 10), "plain ascii");
        assert_eq!(enc_b("a =?b", 70), "=?UTF-8?B?YSA9P2I=?=");
        assert_eq!(enc_b("Caf\u{e9}", 70), "=?UTF-8?B?Q2Fmw6k=?=");
        // Every word is at most 75 bytes, holds whole characters, and reads
        // back on its own; the words together read back as the text.
        let text = "\u{4f1a}\u{8b70}".repeat(30);
        let e = enc_b(&text, 75);
        for w in e.split("\r\n ") {
            assert!(
                w.len() <= 75 && w.starts_with("=?UTF-8?B?") && w.ends_with("?="),
                "{w}"
            );
            assert!(dec(w.as_bytes()).is_ok());
        }
        assert_eq!(dec(e.as_bytes()).unwrap(), text);
        // 45 bytes fill a word: 60 base64 characters, 72 bytes in all, as
        // 63 is not a multiple of four.
        let e = enc_b(&"\u{20ac}".repeat(15), 75);
        assert_eq!(e.len(), 72);
        let e = enc_b(&"\u{20ac}".repeat(16), 75);
        assert_eq!(e.split("\r\n ").map(str::len).collect::<Vec<_>>(), [72, 16]);
        // The first word fits the room left on the line, or starts a new one.
        assert!(enc_b("\u{e9}", 16).starts_with("=?UTF-8?B?"));
        assert!(enc_b("\u{e9}", 15).starts_with("\r\n =?UTF-8?B?"));
        assert!(
            enc_b(&"\u{e9}".repeat(20), 20)
                .split("\r\n ")
                .next()
                .unwrap()
                .len()
                <= 20
        );
        // Mostly-CJK text: B is shorter than Q.
        let subject = "\u{4f1a}\u{8b70}\u{306e}\u{304a}\u{77e5}\u{3089}\u{305b}";
        assert!(enc_b(subject, 64).len() * 10 < enc(subject, 64).len() * 7);
        let mut buf = [0u8; 8];
        let mut out = crate::SliceSink::new(&mut buf);
        assert_eq!(
            encode_words_b("a\u{1b}", 70, &mut out),
            Err(WriteError::Forbidden { at: 1 })
        );
        assert_eq!(
            encode_words_b("\u{e9}\u{e9}", 70, &mut out),
            Err(WriteError::Full)
        );
        assert!(out.is_empty());
    }

    proptest::proptest! {
        #[test]
        fn test_encode_words_b_round_trips(text in "[^\\p{Cc}]{0,120}", room in 0usize..80) {
            let e = enc_b(&text, room);
            for (i, w) in e.split("\r\n ").enumerate() {
                if w.starts_with("=?") {
                    proptest::prop_assert!(w.len() <= if i == 0 { room.min(75) } else { 75 }, "{w}");
                }
            }
            // A fold before the first word follows `Name:` in the field, where
            // a reader drops it with the whitespace after the colon.
            let value = |s: &str| String::from(s.strip_prefix("\r\n ").unwrap_or(s));
            proptest::prop_assert_eq!(&dec(value(&e).as_bytes()).unwrap(), &text);
            // Q and B read back the same.
            proptest::prop_assert_eq!(dec(value(&enc(&text, room)).as_bytes()).unwrap(), text);
        }
    }
}