Merge pull request #5 from nyris/feature/serde

Add serde support

Author: sunsided

.github/workflows/rust.yml

@@ -19,6 +19,6 @@ jobs:
     - name: Build
       run: cargo build --verbose
     - name: Run tests
-      run: cargo test --verbose
+      run: cargo test --verbose --features=serde
     - name: Run doctests
-      run: cargo test --doc --verbose
+      run: cargo test --doc --verbose --features=serde

CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- Added a `FromStr` implementation, allowing for `parse::<ShortGuid>("...")`.
+- Added `from_slice` to construct from a `&[u8]`.
+- Added support for Serde.
+
 ## 0.4.0 - 2023-06-24
 
 ### Added

Cargo.toml

@@ -9,19 +9,31 @@ authors = ["Markus Mayer <[email protected]>"]
 readme = "README.md"
 rust-version = "1.67.1"
 
-[dependencies]
-arbitrary = { version = "1.3.0", optional = true }
-base64 = "0.21.2"
-uuid = "1.3.4"
-
 [features]
 default = ["random"]
 arbitrary = ["uuid/arbitrary", "arbitrary/derive"]
 random = ["uuid/v4"]
+serde = ["dep:serde", "uuid/serde"]
+
+[[example]]
+name = "shortguid"
+path = "examples/shortguid.rs"
+
+[[test]]
+name = "serde"
+path = "tests/serde.rs"
+required-features = ["serde"]
+
+[dependencies]
+arbitrary = { version = "1.3.0", optional = true }
+base64 = "0.21.2"
+serde = { version = "1.0.164", optional = true }
+uuid = "1.3.4"
 
 [dev-dependencies]
 hex = "0.4.3"
 clap = "4.3.8"
+serde_test = "1.0.164"
 
 [package.metadata.docs.rs]
 all-features = true

LICENSE.md

@@ -285,4 +285,37 @@ the rights granted in Article 2 of this Licence and protect the covered Source
 Code from exclusive appropriation.
 
 All other changes or additions to this Appendix require the production of a new
-EUPL version.
+EUPL version.
+
+---
+
+# MIT
+
+The serde related code is licensed under an MIT license shown below.
+
+Copyright (c) 2014 The Rust Project Developers
+Copyright (c) 2018 Ashley Mannix, Christopher Armstrong, Dylan DPC, Hunar Roop Kahlon
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

fuzz/Cargo.lock

@@ -15,10 +15,14 @@
 // the `docsrs` configuration attribute is defined
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
+#[cfg(feature = "serde")]
+mod serde;
+
 use base64::{DecodeError, Engine};
 use std::borrow::Borrow;
 use std::error::Error;
 use std::fmt::{Debug, Display, Formatter};
+use std::str::FromStr;
 use uuid::Uuid;
 
 /// A short, URL-safe UUID representation.
@@ -77,15 +81,22 @@ impl ShortGuid {
         Ok(Self(uuid))
     }
 
+    /// Creates a [`ShortGuid`] using the supplied bytes.
+    #[inline]
+    pub fn from_slice<B: AsRef<[u8]>>(bytes: B) -> Result<Self, ParseError> {
+        let uuid = Uuid::from_slice(bytes.as_ref()).map_err(|e| ParseError::InvalidSlice(e))?;
+        Ok(Self(uuid))
+    }
+
     /// Constructs a [`ShortGuid`] instance based on a byte slice.
     ///
     /// ## Notes
     /// This will clone the underlying data. If you wish to return a
     /// transparent reference around the provided slice, use [`ShortGuid::from_bytes_ref`]
     /// instead.
     #[inline]
-    pub fn from_bytes(bytes: &[u8; 16]) -> Self {
-        Self(Uuid::from_bytes_ref(bytes).clone())
+    pub fn from_bytes<B: Borrow<[u8; 16]>>(bytes: B) -> Self {
+        Self(Uuid::from_bytes_ref(bytes.borrow()).clone())
     }
 
     /// Returns a slice of 16 octets containing the value.
@@ -373,6 +384,8 @@ pub enum ParseError {
     /// The provided input had an invalid format.
     /// The contained value is the underlying decoding error.
     InvalidFormat(DecodeError),
+    /// The provided slice input was invalid.
+    InvalidSlice(uuid::Error),
 }
 
 impl From<DecodeError> for ParseError {
@@ -395,10 +408,19 @@ impl Display for ParseError {
                 "Invalid ID length; expected 22 characters, but got {len}"
             ),
             ParseError::InvalidFormat(err) => write!(f, "Invalid ID format: {err}"),
+            ParseError::InvalidSlice(err) => write!(f, "Invalid slice: {err}"),
         }
     }
 }
 
+impl FromStr for ShortGuid {
+    type Err = ParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        ShortGuid::try_parse(s)
+    }
+}
+
 impl Error for ParseError {}
 
 #[cfg(test)]

src/lib.rs

@@ -0,0 +1,91 @@
+// The original serde code is taken from the uuid crate at https://github.com/uuid-rs/uuid,
+// licensed under an MIT or Apache-2.0 license and copyrighted as follows:
+//
+// Copyright (c) 2014 The Rust Project Developers
+// Copyright (c) 2018 Ashley Mannix, Christopher Armstrong, Dylan DPC, Hunar Roop Kahlon
+// Copyright (c) 2023 Markus Mayer
+//
+// SPDX-License-Identifier: EUPL-1.2 or MIT or Apache-2.0
+
+use crate::{ParseError, ShortGuid};
+use std::fmt::Formatter;
+use uuid::Uuid;
+
+#[cfg(feature = "serde")]
+impl serde::Serialize for ShortGuid {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        if serializer.is_human_readable() {
+            serializer.serialize_str(Self::encode(self.0).as_str())
+        } else {
+            serializer.serialize_bytes(self.as_bytes())
+        }
+    }
+}
+
+#[cfg(feature = "serde")]
+impl<'de> serde::Deserialize<'de> for ShortGuid {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        fn de_error<E: serde::de::Error>(e: ParseError) -> E {
+            E::custom(format_args!("ShortGuid parsing failed: {}", e))
+        }
+
+        if deserializer.is_human_readable() {
+            struct ShortGuidVisitor;
+
+            impl<'vi> serde::de::Visitor<'vi> for ShortGuidVisitor {
+                type Value = ShortGuid;
+
+                fn expecting(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
+                    write!(formatter, "a ShortGuid string")
+                }
+
+                fn visit_str<E: serde::de::Error>(self, value: &str) -> Result<ShortGuid, E> {
+                    value.parse::<ShortGuid>().map_err(de_error)
+                }
+
+                fn visit_bytes<E: serde::de::Error>(self, value: &[u8]) -> Result<ShortGuid, E> {
+                    ShortGuid::from_slice(value).map_err(de_error)
+                }
+
+                fn visit_seq<A>(self, mut seq: A) -> Result<ShortGuid, A::Error>
+                where
+                    A: serde::de::SeqAccess<'vi>,
+                {
+                    use serde::de::Error;
+                    #[rustfmt::skip]
+                        let bytes: [u8; 16] = [
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                        match seq.next_element()? { Some(e) => e, None => return Err(Error::invalid_length(16, &self)) },
+                    ];
+
+                    Ok(ShortGuid::from_bytes(&bytes))
+                }
+            }
+
+            deserializer.deserialize_str(ShortGuidVisitor)
+        } else {
+            let uuid = Uuid::deserialize(deserializer)?;
+            Ok(ShortGuid::from(uuid))
+        }
+    }
+}

src/serde.rs

@@ -0,0 +1,81 @@
+// The original test code is taken from the uuid crate at https://github.com/uuid-rs/uuid,
+// licensed under an MIT or Apache-2.0 license and copyrighted as follows:
+//
+// Copyright (c) 2014 The Rust Project Developers
+// Copyright (c) 2018 Ashley Mannix, Christopher Armstrong, Dylan DPC, Hunar Roop Kahlon
+// Copyright (c) 2023 Markus Mayer
+//
+// SPDX-License-Identifier: EUPL-1.2 or MIT or Apache-2.0
+
+use serde_test::{Compact, Configure, Readable, Token};
+use shortguid::ShortGuid;
+
+#[test]
+fn test_serialize_readable_string() {
+    let uuid_str = "f9168c5e-ceb2-4faa-b6bf-329bf39fa1e4";
+    let shortguid_str = "-RaMXs6yT6q2vzKb85-h5A";
+    let u = ShortGuid::try_parse(uuid_str).unwrap();
+    serde_test::assert_tokens(&u.readable(), &[Token::Str(shortguid_str)]);
+}
+
+#[test]
+fn test_deserialize_readable_compact() {
+    let uuid_bytes = b"F9168C5E-CEB2-4F";
+    let u = ShortGuid::from_slice(uuid_bytes).unwrap();
+
+    serde_test::assert_de_tokens(
+        &u.readable(),
+        &[
+            Token::Tuple { len: 16 },
+            Token::U8(uuid_bytes[0]),
+            Token::U8(uuid_bytes[1]),
+            Token::U8(uuid_bytes[2]),
+            Token::U8(uuid_bytes[3]),
+            Token::U8(uuid_bytes[4]),
+            Token::U8(uuid_bytes[5]),
+            Token::U8(uuid_bytes[6]),
+            Token::U8(uuid_bytes[7]),
+            Token::U8(uuid_bytes[8]),
+            Token::U8(uuid_bytes[9]),
+            Token::U8(uuid_bytes[10]),
+            Token::U8(uuid_bytes[11]),
+            Token::U8(uuid_bytes[12]),
+            Token::U8(uuid_bytes[13]),
+            Token::U8(uuid_bytes[14]),
+            Token::U8(uuid_bytes[15]),
+            Token::TupleEnd,
+        ],
+    );
+}
+
+#[test]
+fn test_deserialize_readable_bytes() {
+    let uuid_bytes = b"F9168C5E-CEB2-4F";
+    let u = ShortGuid::from_slice(uuid_bytes).unwrap();
+    serde_test::assert_de_tokens(&u.readable(), &[Token::Bytes(uuid_bytes)]);
+}
+
+#[test]
+fn test_serialize_non_human_readable() {
+    let uuid_bytes = b"F9168C5E-CEB2-4F";
+    let u = ShortGuid::from_slice(uuid_bytes).unwrap();
+    serde_test::assert_tokens(
+        &u.compact(),
+        &[Token::Bytes(&[
+            70, 57, 49, 54, 56, 67, 53, 69, 45, 67, 69, 66, 50, 45, 52, 70,
+        ])],
+    );
+}
+
+#[test]
+fn test_de_failure() {
+    serde_test::assert_de_tokens_error::<Readable<ShortGuid>>(
+        &[Token::Str("hello_world")],
+        "ShortGuid parsing failed: Invalid ID length; expected 22 characters, but got 11",
+    );
+
+    serde_test::assert_de_tokens_error::<Compact<ShortGuid>>(
+        &[Token::Bytes(b"hello_world")],
+        "UUID parsing failed: invalid length: expected 16 bytes, found 11",
+    );
+}