100% safe Rust

Author: mdecimus

Cargo.lock

@@ -1,7 +1,7 @@
 [package]
 name = "mail-parser"
 description = "Fast and robust e-mail parsing library for Rust"
-version = "0.1.1"
+version = "0.2.0"
 edition = "2018"
 authors = [ "Stalwart Labs <hello@stalw.art>"]
 license = "Apache-2.0 OR MIT"

Cargo.toml

@@ -24,20 +24,18 @@ HTML and plain text inline body parts is done automatically when the _alternativ
 
 Performance and memory safety were two important factors while designing _mail-parser_:
 
-- **Zero-copy parsing** is done in most cases (unless when decoding non-UTF8 text or when RFC2047/RFC2231 encoded parts are present). 
-  Practically all strings and u8 slices returned by this library are `Cow<str>` or `Cow<[u8]>` references to the input raw message.
-- Memory allocations are always avoided unless they are really necessary. In fact, all Base64 and Quoted-Printable parts are decoded in 
-  place re-using the input buffer. 
-- [Perfect hashing](https://en.wikipedia.org/wiki/Perfect_hash_function) is used for fast look-up of message header fields, character 
-  set names and aliases, HTML entities as well as month names while parsing _Date_ fields.
-- Although some `unsafe` code was used to obtain performance gains of about 10%, every function in the library has been 
-  [fuzzed](#testing-fuzzing--benchmarking) and also heavily [tested with MIRI](#testing-fuzzing--benchmarking).
-- Fully battle-tested with millions of real-world e-mail messages dating from 1995 until today.
+- **Zero-copy parsing**: Practically all strings returned by this library are `Cow<str>` references to the input raw message.
+- **High performance Base64 decoding** based on Chromium's decoder ([the fastest non-SIMD decoder](https://github.com/lemire/fastbase64)). 
+- **Fast** parsing of message header fields, character set names and HTML entities using [perfect hashing](https://en.wikipedia.org/wiki/Perfect_hash_function).
+- Written in **100% safe** Rust with no external dependencies.
+- Every function in the library has been [fuzzed](#testing-fuzzing--benchmarking) and 
+  meticulously [tested with MIRI](#testing-fuzzing--benchmarking).
+- Thoroughly **battle-tested** with millions of real-world e-mail messages dating from 1995 until today.
 
 ## Usage Example
 
 ```rust
-    let mut input = concat!(
+    let input = concat!(
         "From: Art Vandelay <art@vandelay.com> (Vandelay Industries)\n",
         "To: \"Colleagues\": \"James Smythe\" <james@vandelay.com>; Friends:\n",
         "    jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?= <john@example.com>;\n",
@@ -72,10 +70,9 @@ Performance and memory safety were two important factors while designing _mail-p
         "--giddyup--\n",
         "--festivus--\n",
     )
-    .as_bytes()
-    .to_vec();
+    .as_bytes();
 
-    let message = Message::parse(&mut input[..]);
+    let message = Message::parse(input);
 
     // Parses addresses (including comments), lists and groups
     assert_eq!(

README.md

@@ -17,7 +17,7 @@ use std::{fs, path::PathBuf};
 
 use test::Bencher;
 
-fn bench_all_samples(b: &mut Bencher, name: &str, fnc: fn(&mut [u8], &str)) {
+fn bench_all_samples(b: &mut Bencher, name: &str, fnc: fn(&[u8], &str)) {
     const SEPARATOR: &[u8] = "\n---- EXPECTED STRUCTURE ----\n".as_bytes();
 
     println!("Benchmarking {}...\n", name);
@@ -63,10 +63,7 @@ fn bench_all_samples(b: &mut Bencher, name: &str, fnc: fn(&mut [u8], &str)) {
 
     b.iter(|| {
         for test_msg in &test_data {
-            let input_str = String::from_utf8_lossy(&test_msg);
-            let mut input_bytes = test_msg.clone();
-
-            fnc(&mut input_bytes[..], &input_str);
+            fnc(test_msg, String::from_utf8_lossy(&test_msg).as_ref());
         }
     });
 }

benches/libraries.rs

@@ -1,7 +1,7 @@
 use mail_parser::{Addr, Address, BodyPart, Group, Message, MessagePart, MimeFieldGet};
 
 fn main() {
-    let mut input = concat!(
+    let input = concat!(
         "From: Art Vandelay <art@vandelay.com> (Vandelay Industries)\n",
         "To: \"Colleagues\": \"James Smythe\" <james@vandelay.com>; Friends:\n",
         "    jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?= <john@example.com>;\n",
@@ -36,10 +36,9 @@ fn main() {
         "--giddyup--\n",
         "--festivus--\n",
     )
-    .as_bytes()
-    .to_vec();
+    .as_bytes();
 
-    let message = Message::parse(&mut input[..]);
+    let message = Message::parse(input);
 
     // Parses addresses (including comments), lists and groups
     assert_eq!(

examples/email_to_json_and_yaml.rs

@@ -1,6 +1,5 @@
 #![no_main]
 use libfuzzer_sys::fuzz_target;
-use std::borrow::Cow;
 
 use mail_parser::{
     decoders::{
@@ -34,8 +33,7 @@ use mail_parser::{
 fuzz_target!(|data: &[u8]| {
     // Fuzz every parsing function
     for n_fuzz in 1..=24 {
-        let mut data = Vec::from(data);
-        let stream = MessageStream::new(&mut data);
+        let stream = MessageStream::new(&data);
 
         match n_fuzz {
             1 => {
@@ -116,16 +114,16 @@ fuzz_target!(|data: &[u8]| {
 
     // Fuzz HTML functions
     let mut html_str = String::with_capacity(data.len());
-    add_html_token(&mut html_str, data, false);
-    let html_str = String::from_utf8_lossy(data);
-    html_to_text(&html_str);
-    text_to_html(&html_str);
+    let str_data = String::from_utf8_lossy(data);
+    add_html_token(&mut html_str, str_data.as_ref().as_bytes(), false);
+    html_to_text(&str_data);
+    text_to_html(&str_data);
 
     // Fuzz decoding functions
     decode_hex(data);
     get_charset_decoder(data);
 
-    let decoders: &[for<'x> fn(&'x [u8]) -> Cow<'x, str>] = &[
+    let decoders: &[for<'x> fn(&'x [u8]) -> String] = &[
         decoder_utf7,
         decoder_utf16_le,
         decoder_utf16_be,
@@ -138,6 +136,5 @@ fuzz_target!(|data: &[u8]| {
     }
 
     // Fuzz the entire library
-    let mut data = Vec::from(data);
-    Message::parse(&mut data[..]);
+    Message::parse(&data[..]);
 });