[wip] doc for sharry module

src/cli.rs

@@ -159,7 +159,7 @@ impl Cli {
         let mut hasher = Blake2b::new().hash_length(16).to_state();
 
         hasher.update(self.get_uri().as_ref());
-        hasher.update(self.alias.as_ref());
+        hasher.update(self.alias.as_ref().as_bytes());
 
         for chk in sorted(&self.files) {
             hasher.update(chk.as_ref());

src/file/checked.rs

@@ -11,9 +11,10 @@ use super::{FileTrait, Uploading};
 
 /// Description of an existing, regular file
 ///
-/// - impl Clone for `clap` compatibility
+/// - impl `Clone` for `clap` compatibility
-/// - impl serde for appstate caching
+/// - impl `serde` for cachefile handling
-/// - impl PartialEq..Ord to handle multiple files given
+/// - impl `PartialEq..Ord` to handle multiple files given
+/// - impl `AsRef<[u8]>` for hashing with `blake2b_simd`
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Checked {
     /// canonical path to a regular file

src/sharry/ids.rs

@@ -4,18 +4,17 @@ use log::{debug, trace};
 use regex::Regex;
 use serde::{Deserialize, Serialize};
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+/// ID of a public Sharry alias
+///
+/// - impl `From<String>` and `Clone` as this is just a String
+/// - impl `serde` for cachefile handling
+/// - impl `AsRef<str>` for using in a `ureq` header and hashing support
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AliasID(String);
 
-impl fmt::Display for AliasID {
+impl AsRef<str> for AliasID {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    fn as_ref(&self) -> &str {
-        f.write_str(&self.0)
+        self.0.as_ref()
-    }
-}
-
-impl AsRef<[u8]> for AliasID {
-    fn as_ref(&self) -> &[u8] {
-        self.0.as_bytes()
     }
 }
 
@@ -25,7 +24,12 @@ impl From<String> for AliasID {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+/// ID of a Sharry share
+///
+/// - impl `From<String>` and `Clone` as this is just a String
+/// - impl `serde` for cachefile handling
+/// - impl `Display` for formatting compatibility
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ShareID(String);
 
 impl fmt::Display for ShareID {
@@ -40,7 +44,13 @@ impl From<String> for ShareID {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+/// ID of a file in a Sharry share
+///
+/// - impl `Clone` as this is just a String
+/// - impl `serde` for cachefile handling
+/// - impl `Display` for formatting compatibility
+/// - impl `TryFrom<String>` for extracting from matching a "PATCH" uri
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct FileID(String);
 
 impl fmt::Display for FileID {
@@ -93,6 +103,57 @@ impl TryFrom<String> for FileID {
 mod tests {
     use super::*;
 
+    #[test]
+    fn basic_traits_working() {
+        let inputs = vec![
+            "",
+            "abcd",
+            "12345",
+            "8woeurx09wp",
+            "6NHNiSVFhZF-dSGbX8iD8ib-Pdb7TbzpsvC-uBBSCyExxb",
+        ];
+
+        for input in inputs {
+            {
+                // check AliasID
+                let _ = AliasID(input.to_owned());
+                let aid = AliasID::from(input.to_owned()); // "From" trait
+                assert_eq!(
+                    aid.as_ref(),
+                    input,
+                    "`impl AsRef<str> for AliasID` expected: {:?}, got {:?}",
+                    input,
+                    aid.as_ref(),
+                );
+            }
+
+            {
+                // check ShareID
+                let _ = ShareID(input.to_owned());
+                let sid = ShareID::from(input.to_owned()); // "From" trait
+                assert_eq!(
+                    sid.to_string(),
+                    input,
+                    "`impl Display for ShareID` expected: {:?}, got {:?}",
+                    input,
+                    sid.to_string(),
+                );
+            }
+
+            {
+                // check FileID
+                let fid = FileID(input.to_owned());
+                assert_eq!(
+                    fid.to_string(),
+                    input,
+                    "`impl Display for FileID` expected: {:?}, got {:?}",
+                    fid.to_string(),
+                    input
+                );
+            }
+        }
+    }
+
     #[test]
     fn valid_urls_produce_expected_file_id() {
         // a handful of valid‐looking URLs
@@ -112,12 +173,11 @@ mod tests {
         ];
 
         for (good, expected_fid) in cases {
-            let s = good.to_string();
+            let s = good.to_owned();
             let file_id = FileID::try_from(s.clone()).expect("URL should parse successfully");
             assert_eq!(
                 file_id.0, expected_fid,
-                "Expected `{}` → FileID({}), got {:?}",
+                "Expected `{good}` → FileID({expected_fid}), got {file_id:?}",
-                good, expected_fid, file_id
             );
         }
     }
@@ -138,7 +198,7 @@ mod tests {
         ];
 
         for bad in bad_inputs {
-            let err = FileID::try_from(bad.to_string()).expect_err("URL should not parse");
+            let err = FileID::try_from(bad.to_owned()).expect_err("URL should not parse");
             // make sure it's the Mismatch variant, and that it contains the original input
             match err {
                 crate::Error::Mismatch { expected, actual } => {
@@ -146,7 +206,7 @@ mod tests {
                         expected, "<proto>://<base>/api/v2/alias/upload/<share>/files/tus/<file>",
                         "Error should output expected format"
                     );
-                    assert_eq!(actual, bad.to_string(), "Error should echo back the input");
+                    assert_eq!(actual, bad.to_owned(), "Error should echo back the input");
                 }
                 _ => panic!("Expected Error::Mismatch for input `{bad}` but got {err:?}"),
             }

src/sharry/json.rs

@@ -1,7 +1,7 @@
+#![allow(non_snake_case)]
 use serde::{Deserialize, Serialize};
 
 #[derive(Serialize, Debug)]
-#[allow(non_snake_case)]
 pub struct NewShareRequest {
     name: String,
     validity: u32,
@@ -39,3 +39,29 @@ pub struct NotifyShareResponse {
     pub success: bool,
     pub message: String,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn nsreq_new_sets_fields_correctly() {
+        let name = "myname";
+        let desc = "desc";
+        let views = 7;
+
+        let req = NewShareRequest::new(name, Some(desc), views);
+
+        assert_eq!(req.name, name);
+        assert_eq!(req.validity, 0);
+        assert_eq!(req.description.as_deref(), Some(desc));
+        assert_eq!(req.maxViews, views);
+        assert!(req.password.is_none());
+    }
+
+    #[test]
+    fn nsreq_new_allows_none_description() {
+        let req = NewShareRequest::new("whatever", None::<&str>, 0);
+        assert!(req.description.is_none());
+    }
+}

src/sharry/uri.rs

@@ -45,3 +45,35 @@ impl Uri {
         self.endpoint(format_args!("alias/upload/{share_id}/files/tus/{file_id}"))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn basic_tests() {
+        let cases = vec![
+            ("http", "example.com", "http://example.com"),
+            ("https", "my-host:8080", "https://my-host:8080"),
+            ("custom+scheme", "host", "custom+scheme://host"),
+        ];
+
+        for (protocol, base_url, display) in cases {
+            let uri = Uri::new(protocol, base_url);
+            assert_eq!(
+                uri.to_string(),
+                display,
+                "`impl Display for Uri` expected: {:?}, got {:?}",
+                display,
+                uri.to_string(),
+            );
+            assert_eq!(
+                uri.as_ref(),
+                display.as_bytes(),
+                "`impl AsRef<[u8]> for Uri` expected: {:?}, got {:?}",
+                display.as_bytes(),
+                uri.as_ref(),
+            );
+        }
+    }
+}