Add saslprep integration tests

Added some comments and did some minor reformatting to make it easier to
compare the saslprep implementation point-by-point with the RFC.  Reviewed
the implementation against the RFC and found no errors or omissions.

Reviewed `tables.rs` against the stringprep RFC and found no error
or omissions.

Author: Eric Sessoms

src/lib.rs

@@ -14,15 +14,18 @@ use unicode_normalization::UnicodeNormalization;
 
 pub mod tables;
 
+/// Describes why a string failed stringprep normalization.
 #[derive(Debug)]
-enum ErrorCause {
+pub enum ErrorCause {
+    /// Contains stringprep prohibited characters.
     ProhibitedCharacter(char),
+    /// Violates stringprep rules for bidirectional text.
     ProhibitedBidirectionalText,
 }
 
 /// An error performing the stringprep algorithm.
 #[derive(Debug)]
-pub struct Error(ErrorCause);
+pub struct Error(pub ErrorCause);
 
 impl fmt::Display for Error {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
@@ -51,6 +54,7 @@ pub fn saslprep<'a>(s: &'a str) -> Result<Cow<'a, str>, Error> {
         return Ok(Cow::Borrowed(s));
     }
 
+    // 2.1 Mapping
     let mapped = s.chars()
         .map(|c| if tables::non_ascii_space_character(c) {
                  ' '
@@ -59,50 +63,79 @@ pub fn saslprep<'a>(s: &'a str) -> Result<Cow<'a, str>, Error> {
              })
         .filter(|&c| !tables::commonly_mapped_to_nothing(c));
 
+    // 2.2 Normalization
     let normalized = mapped.nfkc().collect::<String>();
 
+    // 2.3 Prohibited Output
     let prohibited = normalized
         .chars()
         .filter(|&c| {
-            tables::non_ascii_space_character(c) || tables::ascii_control_character(c) ||
-            tables::non_ascii_control_character(c) || tables::private_use(c) ||
-            tables::non_character_code_point(c) ||
-            tables::surrogate_code(c) || tables::inappropriate_for_plain_text(c) ||
-            tables::inappropriate_for_canonical_representation(c) ||
-            tables::change_display_properties_or_deprecated(c) ||
-            tables::tagging_character(c)
+            tables::non_ascii_space_character(c) /* C.1.2 */ ||
+            tables::ascii_control_character(c) /* C.2.1 */ ||
+            tables::non_ascii_control_character(c) /* C.2.2 */ ||
+            tables::private_use(c) /* C.3 */ ||
+            tables::non_character_code_point(c) /* C.4 */ ||
+            tables::surrogate_code(c) /* C.5 */ ||
+            tables::inappropriate_for_plain_text(c) /* C.6 */ ||
+            tables::inappropriate_for_canonical_representation(c) /* C.7 */ ||
+            tables::change_display_properties_or_deprecated(c) /* C.8 */ ||
+            tables::tagging_character(c) /* C.9 */
         })
         .next();
     if let Some(c) = prohibited {
         return Err(Error(ErrorCause::ProhibitedCharacter(c)));
     }
 
+    // RFC3454, 6. Bidirectional Characters
     if normalized.contains(tables::bidi_r_or_al) {
+        // 2) If a string contains any RandALCat character, the string
+        // MUST NOT contain any LCat character.
         if normalized.contains(tables::bidi_l) {
             return Err(Error(ErrorCause::ProhibitedBidirectionalText));
         }
 
+        // 3) If a string contains any RandALCat character, a RandALCat
+        // character MUST be the first character of the string, and a
+        // RandALCat character MUST be the last character of the string.
         if !tables::bidi_r_or_al(normalized.chars().next().unwrap()) ||
            !tables::bidi_r_or_al(normalized.chars().next_back().unwrap()) {
             return Err(Error(ErrorCause::ProhibitedBidirectionalText));
         }
     }
 
+    // 2.5 Unassigned Code Points
+    // TODO: Reject unassigned code points.
+
     Ok(Cow::Owned(normalized))
 }
 
 #[cfg(test)]
 mod test {
     use super::*;
 
+    // RFC4013, 3. Examples
     #[test]
     fn saslprep_examples() {
         assert_eq!(saslprep("I\u{00AD}X").unwrap(), "IX");
         assert_eq!(saslprep("user").unwrap(), "user");
         assert_eq!(saslprep("USER").unwrap(), "USER");
         assert_eq!(saslprep("\u{00AA}").unwrap(), "a");
         assert_eq!(saslprep("\u{2168}").unwrap(), "IX");
-        assert!(saslprep("\u{0007}").is_err());
-        assert!(saslprep("\u{0627}\u{0031}").is_err());
+        assert_prohibited_character(saslprep("\u{0007}"));
+        assert_prohibited_bidirectional_text(saslprep("\u{0627}\u{0031}"));
+    }
+
+    fn assert_prohibited_character<T>(result: Result<T, Error>) {
+        match result {
+            Err(Error(ErrorCause::ProhibitedCharacter(_))) => (),
+            _ => assert!(false)
+        }
+    }
+
+    fn assert_prohibited_bidirectional_text<T>(result: Result<T, Error>) {
+        match result {
+            Err(Error(ErrorCause::ProhibitedBidirectionalText)) => (),
+            _ => assert!(false)
+        }
     }
 }

tests/saslprep_tests.rs

@@ -0,0 +1,87 @@
+// Integration tests from https://github.com/reklatsmasters/saslprep (MIT License)
+extern crate stringprep;
+
+use stringprep::{Error, ErrorCause, saslprep};
+
+fn assert_prohibited_character<T>(result: Result<T, Error>) {
+    match result {
+        Err(Error(ErrorCause::ProhibitedCharacter(_))) => (),
+        _ => assert!(false)
+    }
+}
+
+fn assert_prohibited_bidirectional_text<T>(result: Result<T, Error>) {
+    match result {
+        Err(Error(ErrorCause::ProhibitedBidirectionalText)) => (),
+        _ => assert!(false)
+    }
+}
+
+#[test]
+fn should_work_with_latin_letters() {
+    assert_eq!(saslprep("user").unwrap(), "user");
+}
+
+#[test]
+fn should_preserve_case() {
+    assert_eq!(saslprep("USER").unwrap(), "USER");
+}
+
+#[test]
+fn should_remove_mapped_to_nothing() {
+    assert_eq!(saslprep("I\u{00AD}X").unwrap(), "IX");
+}
+
+#[test]
+fn should_replace_non_ascii_space() {
+    assert_eq!(saslprep("a\u{00A0}b").unwrap(), "a\u{0020}b");
+}
+
+#[test]
+fn should_normalize_as_nfkc() {
+    assert_eq!(saslprep("\u{00AA}").unwrap(), "a");
+    assert_eq!(saslprep("\u{2168}").unwrap(), "IX");
+}
+
+#[test]
+fn should_not_allow_prohibited_characters() {
+    // C.2.1 ASCII control characters
+    assert_prohibited_character(saslprep("a\u{007F}b"));
+
+    // C.2.2 Non-ASCII control characters
+    assert_prohibited_character(saslprep("a\u{06DD}b"));
+
+    // C.3 Private use
+    assert_prohibited_character(saslprep("a\u{E000}b"));
+
+    // C.4 Non-character code points
+    assert_prohibited_character(saslprep("a\u{1FFFE}b"));
+
+    // C.5 Surrogate codes
+    // forbidden by rust
+
+    // C.6 Inappropriate for plain text
+    assert_prohibited_character(saslprep("a\u{FFF9}b"));
+
+    // C.7 Inappropriate for canonical representation
+    assert_prohibited_character(saslprep("a\u{2FF0}b"));
+
+    // C.8 Change display properties or are deprecated
+    assert_prohibited_character(saslprep("a\u{200E}b"));
+
+    // C.9 Tagging characters
+    assert_prohibited_character(saslprep("a\u{E0001}b"));
+}
+
+#[test]
+fn randalcat_should_be_first_and_last() {
+    assert_eq!(saslprep("\u{0627}\u{0031}\u{0628}").unwrap(), "\u{0627}\u{0031}\u{0628}");
+    assert_prohibited_bidirectional_text(saslprep("\u{0627}\u{0031}"));
+}
+
+#[ignore]
+#[should_panic]
+#[test]
+fn should_handle_unassigned_code_points() {
+    saslprep("a\u{0487}").unwrap();
+}