parse_net/mail/
phrase.rs

1//! The text of a `phrase` (RFC 5322 section 3.2.5), such as a display name,
2//! with its RFC 2047 encoded words decoded (section 5).
3
4use super::words::{self, Text};
5use crate::{
6    class,
7    error::{ErrorKind, ParseError, Result, err},
8    limits::Limits,
9    scan::{control_kind, is_control},
10    text::{comment_end_folded, parse_quoted},
11};
12
13/// Whether `b` belongs to an atom of a phrase: `atext`, the `.` of
14/// `obs-phrase`, or RFC 6532 UTF-8.
15fn is_word_byte(b: u8) -> bool {
16    WORD.get(usize::from(b)).copied().unwrap_or(false)
17}
18
19/// [`is_word_byte`] for every byte: one lookup instead of the class tests.
20// Built at compile time; `b` runs over 0..256, the array's own bounds.
21#[allow(clippy::indexing_slicing)]
22const WORD: [bool; 256] = {
23    let mut t = [false; 256];
24    let mut b = 0usize;
25    while b < 256 {
26        t[b] = class::is_atext(b as u8) || b == b'.' as usize || b >= 0x80;
27        b += 1;
28    }
29    t
30};
31
32/// The last word written.
33#[derive(Clone, Copy, PartialEq, Eq)]
34enum Last {
35    None,
36    Text,
37    Encoded,
38}
39
40/// Walks the phrase `v`, emitting its text.
41fn walk(v: &[u8], limits: &Limits, emit: &mut impl FnMut(&[u8])) -> Result<()> {
42    let mut text = Text::new();
43    let (mut i, mut words) = (0usize, 0usize);
44    let mut last = Last::None;
45    // A comment since the last word: two encoded words with a comment between
46    // them are not adjacent (RFC 2047 section 6.2), so a space separates them.
47    let mut commented = false;
48    while let Some(&b) = v.get(i) {
49        let n = words::ws_len(v, i);
50        if n > 0 {
51            i += n;
52            continue;
53        }
54        if b == b'(' {
55            i = comment_end_folded(v, i, limits)?.0;
56            commented = true;
57            continue;
58        }
59        if b == b'"' {
60            let (q, used) = parse_quoted(v.get(i..).unwrap_or(&[])).map_err(|e| e.shifted(i))?;
61            if last != Last::None {
62                emit(b" ");
63            }
64            // The content with its quoted pairs unescaped; a word inside a
65            // quoted string is not decoded (RFC 2047 section 5).
66            let raw = q.raw();
67            if raw.is_ascii() {
68                // `qdtext` and `quoted-pair` hold no control but HTAB in
69                // ASCII, so the runs between escapes go out as they are.
70                let mut rest = raw;
71                while let Some(p) = rest.iter().position(|&c| c == b'\\') {
72                    emit(rest.get(..p).unwrap_or(&[]));
73                    emit(rest.get(p + 1..p + 2).unwrap_or(&[]));
74                    rest = rest.get(p + 2..).unwrap_or(&[]);
75                }
76                emit(rest);
77            } else {
78                let mut k = 0usize;
79                while let Some(&c) = raw.get(k) {
80                    if c == b'\\' {
81                        k += 1;
82                    }
83                    let c = raw.get(k).copied().unwrap_or(c);
84                    text.check(c, i + 1 + k)?;
85                    emit(&[c]);
86                    k += 1;
87                }
88                if !text.is_complete() {
89                    return err(ErrorKind::InvalidUtf8, i + used - 1);
90                }
91            }
92            last = Last::Text;
93            commented = false;
94            i += used;
95            continue;
96        }
97        if !is_word_byte(b) {
98            let kind = if is_control(b) {
99                control_kind(b)
100            } else {
101                ErrorKind::InvalidByte
102            };
103            return Err(ParseError::new(kind, i));
104        }
105        let rest = v.get(i..).unwrap_or(&[]);
106        let end = i + rest
107            .iter()
108            .position(|&c| !is_word_byte(c))
109            .unwrap_or(rest.len());
110        // An encoded word is a whole atom between whitespace; next to a
111        // special or a comment it is text.
112        let alone = end == v.len() || words::ws_len(v, end) > 0;
113        let encoded = if alone && rest.starts_with(b"=?") {
114            words::shape(v.get(..end).unwrap_or(&[]), i)?
115        } else {
116            None
117        };
118        if let Some(e) = encoded {
119            words += 1;
120            if words > usize::from(limits.encoded_words) {
121                return err(ErrorKind::TooManyMembers, i);
122            }
123            if last == Last::Text || (last == Last::Encoded && commented) {
124                emit(b" ");
125            }
126            words::decode_word(&e, i, emit)?;
127            last = Last::Encoded;
128        } else {
129            if last != Last::None {
130                emit(b" ");
131            }
132            let atom = v.get(i..end).unwrap_or(&[]);
133            // An ASCII atom is `atext` and dots, all printable.
134            if !atom.is_ascii() {
135                for (k, &c) in atom.iter().enumerate() {
136                    text.check(c, i + k)?;
137                }
138                if !text.is_complete() {
139                    return err(ErrorKind::InvalidUtf8, end);
140                }
141            }
142            emit(atom);
143            last = Last::Text;
144        }
145        commented = false;
146        i = end;
147    }
148    if last == Last::None {
149        return err(ErrorKind::Empty, 0);
150    }
151    Ok(())
152}
153
154/// Decodes a `phrase` (RFC 5322 section 3.2.5), such as the display name
155/// [`parse_mailbox`](super::parse_mailbox) returns raw, into `out` and returns
156/// its text: comments are dropped, quoted strings lose their quotes and
157/// their quoted pairs are unescaped, and the words are joined by one space.
158/// RFC 2047 encoded words are decoded where section 5 allows them in a
159/// phrase: a whole atom between whitespace, never inside a quoted string;
160/// two encoded words with only whitespace between them are joined with none
161/// (section 6.2). Encoded words are read as
162/// [`decode_words`](super::decode_words) reads them, and every byte of the
163/// text meets its rules: UTF-8, no control character but HTAB.
164///
165/// # Errors
166///
167/// [`ErrorKind::Empty`] for a phrase with no word (empty, or only comments
168/// and whitespace); [`ErrorKind::InvalidByte`] for a special such as `,` or
169/// `<` outside a quoted string or comment; a control kind for a control
170/// byte, other than HTAB and the CRLF of a fold; [`ErrorKind::Control`] for
171/// a C1 character; [`ErrorKind::InvalidUtf8`];
172/// [`ErrorKind::UnterminatedQuote`]; [`ErrorKind::UnbalancedComment`],
173/// [`ErrorKind::CommentTooDeep`]; the encoded-word errors of
174/// [`decode_words`](super::decode_words), [`ErrorKind::TooManyMembers`]
175/// beyond `max_encoded_words` among them; [`ErrorKind::BufferTooSmall`].
176/// Nothing is written on error.
177///
178/// # Examples
179///
180/// ```
181/// use parse_net::{mail, Limits};
182///
183/// let m = mail::parse_mailbox(b"\"Doe, Jane\" (Sales) <jane@example.com>", &Limits::DEFAULT)?;
184/// let mut buf = [0u8; 64];
185/// let name = mail::decode_phrase(m.display_name.unwrap_or_default(), &Limits::DEFAULT, &mut buf)?;
186/// assert_eq!(name, "Doe, Jane");
187///
188/// let name = mail::decode_phrase(b"=?UTF-8?Q?Ren=C3=A9e?= \"O'Neil\"", &Limits::DEFAULT, &mut buf)?;
189/// assert_eq!(name, "Ren\u{e9}e O'Neil");
190/// # Ok::<(), parse_net::ParseError>(())
191/// ```
192pub fn decode_phrase<'b>(value: &[u8], limits: &Limits, out: &'b mut [u8]) -> Result<&'b str> {
193    let mut len = 0usize;
194    walk(value, limits, &mut |b: &[u8]| len += b.len())?;
195    let Some(dst) = out.get_mut(..len) else {
196        return err(ErrorKind::BufferTooSmall, 0);
197    };
198    let mut n = 0usize;
199    walk(value, limits, &mut |b: &[u8]| {
200        if let Some(d) = dst.get_mut(n..n + b.len()) {
201            d.copy_from_slice(b);
202        }
203        n += b.len();
204    })?;
205    // The first walk checked the text; this is the safe conversion.
206    core::str::from_utf8(dst).map_err(|e| ParseError::new(ErrorKind::InvalidUtf8, e.valid_up_to()))
207}
208
209#[cfg(test)]
210mod tests {
211    use super::*;
212    use std::{string::String, vec, vec::Vec};
213
214    fn dec(v: &[u8]) -> Result<String> {
215        let mut buf = vec![0u8; 1024];
216        decode_phrase(v, &Limits::DEFAULT, &mut buf).map(String::from)
217    }
218
219    fn fails(v: &[u8]) -> (ErrorKind, usize) {
220        let e = dec(v).unwrap_err();
221        (e.kind(), e.offset())
222    }
223
224    #[test]
225    fn test_decode_phrase_words() {
226        assert_eq!(dec(b"Jane Doe").unwrap(), "Jane Doe");
227        assert_eq!(dec(b"  Jane \t  Doe  ").unwrap(), "Jane Doe");
228        assert_eq!(dec(b"Jane\r\n Doe").unwrap(), "Jane Doe");
229        assert_eq!(dec(b"John Q. Public").unwrap(), "John Q. Public");
230        assert_eq!(dec(b"\"Doe, John\"").unwrap(), "Doe, John");
231        assert_eq!(dec(b"\"a \\\"q\\\" \\\\ b\"").unwrap(), "a \"q\" \\ b");
232        assert_eq!(dec(b"Jane\"Q\"Doe").unwrap(), "Jane Q Doe");
233        assert_eq!(dec(b"\"  spaced  \" x").unwrap(), "  spaced   x");
234        assert_eq!(dec(b"\"\"").unwrap(), "");
235        assert_eq!(dec(b"John (the (nested) one) Doe").unwrap(), "John Doe");
236        assert_eq!(dec(b"(lead)John(trail)").unwrap(), "John");
237        assert_eq!(
238            dec("J\u{f6}rg M\u{fc}ller".as_bytes()).unwrap(),
239            "J\u{f6}rg M\u{fc}ller"
240        );
241        assert_eq!(
242            dec("\"\u{e9}t\u{e9}\"".as_bytes()).unwrap(),
243            "\u{e9}t\u{e9}"
244        );
245        assert_eq!(dec(b"\"tab\there\"").unwrap(), "tab\there");
246    }
247
248    #[test]
249    fn test_decode_phrase_encoded_words() {
250        assert_eq!(
251            dec(b"=?UTF-8?Q?Caf=C3=A9?= Owner").unwrap(),
252            "Caf\u{e9} Owner"
253        );
254        assert_eq!(
255            dec(b"Owner =?utf-8?q?Caf=C3=A9?=").unwrap(),
256            "Owner Caf\u{e9}"
257        );
258        assert_eq!(dec(b"=?UTF-8?Q?a?= =?UTF-8?Q?b?=").unwrap(), "ab");
259        assert_eq!(dec(b"=?UTF-8?Q?a?=\r\n =?UTF-8?Q?b?=").unwrap(), "ab");
260        assert_eq!(dec(b"=?UTF-8?Q?a?= (c) =?UTF-8?Q?b?=").unwrap(), "a b");
261        assert_eq!(dec(b"=?UTF-8?Q?a_b?=").unwrap(), "a b");
262        assert_eq!(
263            dec(b"=?ISO-8859-1?Q?Andr=E9?= Pirard").unwrap(),
264            "Andr\u{e9} Pirard"
265        );
266        assert_eq!(
267            dec(b"=?UTF-8?B?5Lya6K2w44Gu44GK55+l44KJ44Gb?=").unwrap(),
268            "\u{4f1a}\u{8b70}\u{306e}\u{304a}\u{77e5}\u{3089}\u{305b}"
269        );
270        // Inside a quoted string, or next to a special, it is text.
271        assert_eq!(dec(b"\"=?UTF-8?Q?a?=\"").unwrap(), "=?UTF-8?Q?a?=");
272        assert_eq!(dec(b"=?UTF-8?Q?a?=(c)").unwrap(), "=?UTF-8?Q?a?=");
273        assert_eq!(dec(b"=?UTF-8?Q?a?=\"b\"").unwrap(), "=?UTF-8?Q?a?= b");
274        // Not the shape of an encoded word: text.
275        assert_eq!(dec(b"=?x").unwrap(), "=?x");
276        assert_eq!(dec(b"a=?UTF-8?Q?b?=").unwrap(), "a=?UTF-8?Q?b?=");
277    }
278
279    #[test]
280    fn test_decode_phrase_errors() {
281        assert_eq!(fails(b""), (ErrorKind::Empty, 0));
282        assert_eq!(fails(b"   "), (ErrorKind::Empty, 0));
283        assert_eq!(fails(b"(only a comment)"), (ErrorKind::Empty, 0));
284        assert_eq!(fails(b"Doe, John"), (ErrorKind::InvalidByte, 3));
285        assert_eq!(fails(b"a <b>"), (ErrorKind::InvalidByte, 2));
286        assert_eq!(fails(b"a@b"), (ErrorKind::InvalidByte, 1));
287        assert_eq!(fails(b"a\x01b").0, ErrorKind::Control);
288        assert_eq!(fails(b"a\rb").0, ErrorKind::BareCr);
289        assert_eq!(fails(b"a\nb").0, ErrorKind::LineFeed);
290        assert_eq!(fails(b"a\0b").0, ErrorKind::Nul);
291        assert_eq!(fails(b"\"open"), (ErrorKind::UnterminatedQuote, 5));
292        assert_eq!(fails(b"a (open").0, ErrorKind::UnbalancedComment);
293        assert_eq!(fails(b"a \xff"), (ErrorKind::InvalidUtf8, 2));
294        assert_eq!(fails(b"a \xc3 b"), (ErrorKind::InvalidUtf8, 3));
295        assert_eq!(fails(b"\"\xc3\" b"), (ErrorKind::InvalidUtf8, 2));
296        assert_eq!(fails(b"a\xc2\x85b"), (ErrorKind::Control, 2));
297        assert_eq!(fails(b"\"\\\xc2\\\x85\"").0, ErrorKind::Control);
298        assert_eq!(fails(b"=?KOI8-R?Q?a?=").0, ErrorKind::UnsupportedCharset);
299        assert_eq!(fails(b"x =?UTF-8?Q?=0D?=").0, ErrorKind::ControlInDecoded);
300        assert_eq!(fails(b"=?UTF-8?B?YQ=?=").0, ErrorKind::InvalidEncodedWord);
301        let l = Limits::DEFAULT.max_encoded_words(1);
302        let mut buf = [0u8; 16];
303        assert_eq!(
304            decode_phrase(b"=?UTF-8?Q?a?= =?UTF-8?Q?b?=", &l, &mut buf)
305                .unwrap_err()
306                .kind(),
307            ErrorKind::TooManyMembers
308        );
309        // Nothing is written when the buffer is short.
310        let mut small = [b'#'; 4];
311        assert_eq!(
312            decode_phrase(b"Jane Doe", &Limits::DEFAULT, &mut small)
313                .unwrap_err()
314                .kind(),
315            ErrorKind::BufferTooSmall
316        );
317        assert_eq!(small, [b'#'; 4]);
318    }
319
320    /// A reader with no shortcuts: words made only of atoms, quoted
321    /// strings, whitespace, and comments without nesting, so the expected
322    /// text is the words joined by one space.
323    fn reference(words: &[(bool, String)]) -> String {
324        let mut out = String::new();
325        for (k, (_, w)) in words.iter().enumerate() {
326            if k > 0 {
327                out.push(' ');
328            }
329            out.push_str(w);
330        }
331        out
332    }
333
334    proptest::proptest! {
335        #[test]
336        fn decode_phrase_matches_reference(
337            words in proptest::collection::vec(
338                (proptest::bool::ANY, "[ -~\u{e9}\u{4f1a}]{0,8}", "[a-zA-Z0-9!#$%&'*+/=?^_`{|}~.\u{e9}-]{1,8}"),
339                1..6,
340            ),
341            gaps in proptest::collection::vec(0usize..4, 6),
342        ) {
343            let mut raw = Vec::new();
344            let mut expect = Vec::new();
345            for (k, (quoted, q, atom)) in words.iter().enumerate() {
346                if k > 0 {
347                    match gaps.get(k).copied().unwrap_or(0) {
348                        0 => raw.push(b' '),
349                        1 => raw.extend_from_slice(b"\t "),
350                        2 => raw.extend_from_slice(b" (note) "),
351                        _ => raw.extend_from_slice(b"\r\n "),
352                    }
353                }
354                if *quoted {
355                    raw.push(b'"');
356                    for c in q.bytes() {
357                        if c == b'"' || c == b'\\' {
358                            raw.push(b'\\');
359                        }
360                        raw.push(c);
361                    }
362                    raw.push(b'"');
363                    expect.push((true, q.clone()));
364                } else {
365                    raw.extend_from_slice(atom.as_bytes());
366                    expect.push((false, atom.clone()));
367                }
368            }
369            // Atoms that happen to look like encoded words decode: keep
370            // to the plain case here.
371            proptest::prop_assume!(!expect.iter().any(|(q, w)| !q && w.starts_with("=?")));
372            proptest::prop_assert_eq!(dec(&raw).unwrap(), reference(&expect));
373        }
374
375        #[test]
376        fn decode_phrase_never_panics(v in proptest::collection::vec(proptest::num::u8::ANY, 0..64)) {
377            let mut buf = [0u8; 256];
378            if let Ok(s) = decode_phrase(&v, &Limits::DEFAULT, &mut buf) {
379                proptest::prop_assert!(!s.chars().any(|c| c.is_control() && c != '\t'));
380            }
381        }
382    }
383}
parse_net/mail/phrase.rs

parse_net/mail/
phrase.rs
