Merge pull request #4 from EspressoSystems/feat/serde-with

Provide serialization functions for use with serde macros, rather than introducing a new type

Author: jbearer

Cargo.toml

@@ -7,12 +7,11 @@ license = "MIT"
 edition = "2021"
 
 [dependencies]
-ark-serialize = { version = "0.4", features = ["derive"] }
 base64 = "0.22"
-derive_more = "0.99"
 serde = "1.0"
 
 [dev-dependencies]
 bincode = "1.3"
 rand = "0.8"
+serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"

README.md

@@ -2,17 +2,17 @@
 
 _Binary blobs with intelligent serialization._
 
-This crate provides the `Base64Bytes` type. This type behaves like a `Vec<u8>` in almost all cases
-except serialization. Where `Vec<u8>` always serializes as an array of bytes, `Base64Bytes` tries to
-make an intelligent decision about how to serialize based on the serialization format.
+Where `Vec<u8>` always serializes as an array of bytes, this crate provides serialization functions
+which try to make an intelligent decision about how to serialize a byte vector based on the
+serialization format.
 
 For binary formats like [`bincode`](https://crates.io/crates/bincode), the array-of-bytes
 serialization works great: it is compact and introduces very little overhead. But for human-readable
 types such as [`json`](https://crates.io/crates/serde_json), it's far from ideal. The text encoding
 of an array introduces substantial overhead, and the resulting array of opaque bytes isn't
 particularly readable anyways.
 
-`Base64Bytes` uses the [`is_human_readable`](https://docs.rs/serde/latest/serde/trait.Serializer.html#method.is_human_readable)
+`base64-bytes` uses the [`is_human_readable`](https://docs.rs/serde/latest/serde/trait.Serializer.html#method.is_human_readable)
 property of a serializer to distinguish these cases. For binary formats, it uses the default
 `Vec<u8>` serialization. For human-readable formats, it uses a much more compact and conventional
 base 64 encoding.

src/lib.rs

@@ -1,194 +1,114 @@
 //! Intelligent serialization for binary blobs.
+//!
+//! Where `Vec<u8>` always serializes as an array of bytes, this crate provides serialization
+//! functions which try to make an intelligent decision about how to serialize a byte vector based
+//! on the serialization format.
+//!
+//! For binary formats like [`bincode`](https://docs.rs/bincode/latest/bincode/), the array-of-bytes
+//! serialization works great: it is compact and introduces very little overhead. But for
+//! human-readable types such as [`serde_json`](https://docs.rs/serde_json/latest/serde_json/), it's
+//! far from ideal. The text encoding of an array introduces substantial overhead, and the resulting
+//! array of opaque bytes isn't particularly readable anyways.
+//!
+//! `base64-bytes` uses the [`is_human_readable`](serde::Serializer::is_human_readable) property of
+//! a serializer to distinguish these cases. For binary formats, it uses the default `Vec<u8>`
+//! serialization. For human-readable formats, it uses a much more compact and conventional base 64
+//! encoding.
+//!
+//! # Usage
+//!
+//! The interface consists of [`serialize`] and [`deserialize`] functions. While these _can_ be
+//! called directly, they are intended to be used with serde's
+//! [field attributes](https://serde.rs/field-attrs.html) controlling serialization, like:
+//!
+//! ```
+//! use serde::{Deserialize, Serialize};
+//!
+//! #[derive(Deserialize, Serialize)]
+//! struct SomeType {
+//!     #[serde(
+//!         serialize_with = "base64_bytes::serialize",
+//!         deserialize_with = "base64_bytes::deserialize",
+//!     )]
+//!     bytes: Vec<u8>,
+//! }
+//! ```
+//!
+//! Or, as a shorthand:
+//!
+//! ```
+//! use serde::{Deserialize, Serialize};
+//!
+//! #[derive(Deserialize, Serialize)]
+//! struct SomeType {
+//!     #[serde(with = "base64_bytes")]
+//!     bytes: Vec<u8>,
+//! }
+//! ```
+//!
 
-use ark_serialize::{CanonicalDeserialize, CanonicalSerialize};
 use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
-use derive_more::{From, Into};
 use serde::{
     de::{Deserialize, Deserializer, Error},
     ser::{Serialize, Serializer},
 };
-use std::{
-    ops::{Deref, DerefMut},
-    slice::SliceIndex,
-};
-
-/// An unstructured byte array with smart serialization.
-///
-/// [`Base64Bytes`] mostly acts as a simple byte array, `Vec<u8>`. It can easily be converted to and
-/// from a `Vec<u8>`, and it implements many of the same traits as [`Vec`]. In fact internally it
-/// merely wraps a `Vec<u8>`.
-///
-/// The only difference is in how it serializes. `Vec<u8>` serializes very efficiently using
-/// `bincode`, but using `serde_json`, it serializes as a JSON array of integers, which is
-/// unconventional and inefficient. It is better, in JSON, to serialize binary data as a
-/// base64-encoded string. [`Base64Bytes`] uses the
-/// [`is_human_readable`](Serializer::is_human_readable) property of a [`Serializer`] to detect
-/// whether we are serializing for a compact binary format (like `bincode`) or a human-readable
-/// format (like JSON). In the former cases, it serializes directly as an array of bytes. In the
-/// latter case, it serializes as a string using base 64.
-#[derive(
-    Clone,
-    Debug,
-    Default,
-    PartialEq,
-    Eq,
-    Hash,
-    PartialOrd,
-    Ord,
-    From,
-    Into,
-    CanonicalSerialize,
-    CanonicalDeserialize,
-)]
-pub struct Base64Bytes(Vec<u8>);
-
-impl Base64Bytes {
-    pub fn get<I>(&self, index: I) -> Option<&I::Output>
-    where
-        I: SliceIndex<[u8]>,
-    {
-        self.0.get(index)
-    }
-}
-
-impl Serialize for Base64Bytes {
-    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
-        if s.is_human_readable() {
-            BASE64.encode(self).serialize(s)
-        } else {
-            self.0.serialize(s)
-        }
-    }
-}
-
-impl<'a> Deserialize<'a> for Base64Bytes {
-    fn deserialize<D: Deserializer<'a>>(d: D) -> Result<Self, D::Error> {
-        if d.is_human_readable() {
-            Ok(Self(BASE64.decode(String::deserialize(d)?).map_err(
-                |err| D::Error::custom(format!("invalid base64: {err}")),
-            )?))
-        } else {
-            Ok(Self(Vec::deserialize(d)?))
-        }
-    }
-}
-
-impl From<&[u8]> for Base64Bytes {
-    fn from(bytes: &[u8]) -> Self {
-        Self(bytes.into())
-    }
-}
-
-impl<const N: usize> From<[u8; N]> for Base64Bytes {
-    fn from(bytes: [u8; N]) -> Self {
-        Self(bytes.into())
-    }
-}
-
-impl<const N: usize> From<&[u8; N]> for Base64Bytes {
-    fn from(bytes: &[u8; N]) -> Self {
-        Self(bytes.into())
-    }
-}
-
-impl FromIterator<u8> for Base64Bytes {
-    fn from_iter<I: IntoIterator<Item = u8>>(iter: I) -> Self {
-        Self(iter.into_iter().collect())
-    }
-}
 
-impl AsRef<[u8]> for Base64Bytes {
-    fn as_ref(&self) -> &[u8] {
-        self.0.as_ref()
+/// Serialize a byte vector.
+pub fn serialize<S: Serializer, T: AsRef<[u8]>>(v: &T, s: S) -> Result<S::Ok, S::Error> {
+    if s.is_human_readable() {
+        BASE64.encode(v).serialize(s)
+    } else {
+        v.as_ref().serialize(s)
     }
 }
 
-impl AsMut<[u8]> for Base64Bytes {
-    fn as_mut(&mut self) -> &mut [u8] {
-        self.0.as_mut()
-    }
-}
-
-impl Deref for Base64Bytes {
-    type Target = [u8];
-
-    fn deref(&self) -> &[u8] {
-        self.as_ref()
-    }
-}
-
-impl DerefMut for Base64Bytes {
-    fn deref_mut(&mut self) -> &mut [u8] {
-        self.as_mut()
-    }
-}
-
-impl PartialEq<[u8]> for Base64Bytes {
-    fn eq(&self, other: &[u8]) -> bool {
-        self.as_ref() == other
-    }
-}
-
-impl<const N: usize> PartialEq<[u8; N]> for Base64Bytes {
-    fn eq(&self, other: &[u8; N]) -> bool {
-        self.as_ref() == other
-    }
-}
-
-impl PartialEq<Vec<u8>> for Base64Bytes {
-    fn eq(&self, other: &Vec<u8>) -> bool {
-        self.0 == *other
-    }
-}
-
-impl<T> Extend<T> for Base64Bytes
-where
-    Vec<u8>: Extend<T>,
-{
-    fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
-        self.0.extend(iter);
-    }
-}
-
-/// Create a [`Base64Bytes`] blob from elements.
-///
-/// This macro works exactly like the standard `vec![...]` macro.
-#[macro_export]
-macro_rules! base64_bytes {
-    [$($elem:expr),* $(,)?] => {
-        $crate::Base64Bytes::from(vec![$($elem),*])
-    };
-    [$elem:expr; $size:expr] => {
-        $crate::Base64Bytes::from(vec![$elem; $size])
+/// Deserialize a byte vector.
+pub fn deserialize<'a, D: Deserializer<'a>>(d: D) -> Result<Vec<u8>, D::Error> {
+    if d.is_human_readable() {
+        Ok(BASE64
+            .decode(String::deserialize(d)?)
+            .map_err(|err| D::Error::custom(format!("invalid base64: {err}")))?)
+    } else {
+        Ok(Vec::deserialize(d)?)
     }
 }
 
 #[cfg(test)]
 mod test {
-    use super::*;
+    use crate::BASE64;
+    use base64::Engine;
     use rand::RngCore;
+    use serde::{Deserialize, Serialize};
+
+    #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
+    struct Test {
+        #[serde(with = "crate")]
+        bytes: Vec<u8>,
+    }
 
     #[test]
     fn test_bytes_serde() {
         let mut rng = rand::thread_rng();
 
         for len in [0, 1, 10, 1000] {
-            let mut bytes = base64_bytes![0; len];
-            rng.fill_bytes(&mut bytes);
+            let mut t = Test {
+                bytes: vec![0; len],
+            };
+            rng.fill_bytes(&mut t.bytes);
 
             // The binary serialization should be highly efficient: just the length followed by the
             // raw bytes.
-            let binary = bincode::serialize(&bytes).unwrap();
+            let binary = bincode::serialize(&t).unwrap();
             assert_eq!(binary[..8], (len as u64).to_le_bytes());
-            assert_eq!(bytes, binary[8..]);
+            assert_eq!(t.bytes, binary[8..]);
             // Check deserialization.
-            assert_eq!(bytes, bincode::deserialize::<Base64Bytes>(&binary).unwrap());
+            assert_eq!(t, bincode::deserialize::<Test>(&binary).unwrap());
 
             // The JSON serialization should return a base 64 string.
-            let json = serde_json::to_value(&bytes).unwrap();
-            assert_eq!(json.as_str().unwrap(), BASE64.encode(&bytes));
+            let json = serde_json::to_value(&t).unwrap();
+            assert_eq!(json["bytes"].as_str().unwrap(), BASE64.encode(&t.bytes));
             // Check deserialization.
-            assert_eq!(bytes, serde_json::from_value::<Base64Bytes>(json).unwrap());
+            assert_eq!(t, serde_json::from_value::<Test>(json).unwrap());
         }
     }
 }