byte-wrapper 0.2.1

// Copyright (c) The byte-wrapper Contributors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! The [`Base64Vec`] newtype wrapper.

use crate::{Base64Slice, base64_slice::QuotedBase64};
use alloc::{borrow::ToOwned, vec::Vec};
use base64::Engine;
use core::{borrow::Borrow, error, fmt, str::FromStr};

/// A byte vector that displays and parses as base64.
///
/// `Base64Vec` wraps `Vec<u8>`, providing [`Display`](fmt::Display)
/// and [`FromStr`] implementations that use base64 encoding.
///
/// With the **`serde`** feature enabled, it also implements
/// `Serialize` and `Deserialize` (base64 strings in human-readable
/// formats, raw bytes in binary formats), and can be used with
/// `#[serde(with = "Base64Vec")]` on `Vec<u8>` fields.
///
/// # Examples
///
/// ```
/// use byte_wrapper::Base64Vec;
///
/// let b = Base64Vec::new(vec![1, 2, 3]);
/// assert_eq!(b.to_string(), "AQID");
///
/// let parsed: Base64Vec = "AQID".parse().unwrap();
/// assert_eq!(parsed.as_bytes(), [1, 2, 3]);
/// ```
#[must_use]
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Base64Vec(pub Vec<u8>);

impl Base64Vec {
    /// Creates a new `Base64Vec` from a byte vector.
    #[inline]
    pub fn new(bytes: Vec<u8>) -> Self {
        Self(bytes)
    }

    /// Returns the inner byte vector.
    #[inline]
    #[must_use]
    pub fn into_inner(self) -> Vec<u8> {
        self.0
    }

    #[inline]
    fn as_base64_slice(&self) -> &Base64Slice {
        Base64Slice::new(&self.0)
    }
}

/// Error returned by [`Base64Vec::from_str`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParseBase64Error {
    /// An invalid byte was found at the given offset.
    InvalidByte {
        /// Byte offset of the invalid symbol.
        offset: usize,
        /// The invalid byte value.
        byte: u8,
    },
    /// The input length (in valid base64 symbols) is invalid.
    InvalidLength {
        /// The invalid length.
        length: usize,
    },
    /// The last non-padding symbol has nonzero trailing bits that
    /// would be discarded, indicating corrupted or truncated input.
    InvalidLastSymbol {
        /// Byte offset of the invalid symbol.
        offset: usize,
        /// The invalid byte value.
        byte: u8,
    },
    /// Padding was absent, incorrect, or otherwise not as expected.
    InvalidPadding,
}

impl fmt::Display for ParseBase64Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ParseBase64Error::InvalidByte { offset, byte } => {
                write!(f, "invalid base64 symbol {byte}, offset {offset}",)
            }
            ParseBase64Error::InvalidLength { length } => {
                write!(f, "invalid base64 input length: {length}",)
            }
            ParseBase64Error::InvalidLastSymbol { offset, byte } => {
                write!(
                    f,
                    "invalid base64 last symbol {byte}, \
                     offset {offset}",
                )
            }
            ParseBase64Error::InvalidPadding => {
                write!(f, "invalid base64 padding")
            }
        }
    }
}

impl error::Error for ParseBase64Error {}

fn from_decode_error(e: base64::DecodeError) -> ParseBase64Error {
    match e {
        base64::DecodeError::InvalidByte(offset, byte) => {
            ParseBase64Error::InvalidByte { offset, byte }
        }
        base64::DecodeError::InvalidLength(length) => {
            ParseBase64Error::InvalidLength { length }
        }
        base64::DecodeError::InvalidLastSymbol {
            offset,
            symbol,
            symbol_value: _,
        } => ParseBase64Error::InvalidLastSymbol { offset, byte: symbol },
        base64::DecodeError::InvalidPadding => ParseBase64Error::InvalidPadding,
    }
}

impl FromStr for Base64Vec {
    type Err = ParseBase64Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        base64::engine::general_purpose::STANDARD
            .decode(s)
            .map(Self)
            .map_err(from_decode_error)
    }
}

impl fmt::Debug for Base64Vec {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("Base64Vec").field(&QuotedBase64(&self.0)).finish()
    }
}

impl fmt::Display for Base64Vec {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self.as_base64_slice(), f)
    }
}

impl core::ops::Deref for Base64Vec {
    type Target = Base64Slice;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.as_base64_slice()
    }
}

impl Borrow<Base64Slice> for Base64Vec {
    #[inline]
    fn borrow(&self) -> &Base64Slice {
        self.as_base64_slice()
    }
}

impl ToOwned for Base64Slice {
    type Owned = Base64Vec;

    #[inline]
    fn to_owned(&self) -> Self::Owned {
        Base64Vec(self.as_bytes().to_vec())
    }
}

impl AsRef<Base64Slice> for Base64Vec {
    #[inline]
    fn as_ref(&self) -> &Base64Slice {
        self.as_base64_slice()
    }
}

impl AsRef<[u8]> for Base64Vec {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        &self.0
    }
}

impl AsMut<[u8]> for Base64Vec {
    #[inline]
    fn as_mut(&mut self) -> &mut [u8] {
        &mut self.0
    }
}

impl From<Vec<u8>> for Base64Vec {
    #[inline]
    fn from(bytes: Vec<u8>) -> Self {
        Self(bytes)
    }
}

impl From<Base64Vec> for Vec<u8> {
    #[inline]
    fn from(base64_vec: Base64Vec) -> Self {
        base64_vec.0
    }
}

impl PartialEq<Base64Slice> for Base64Vec {
    #[inline]
    fn eq(&self, other: &Base64Slice) -> bool {
        self.as_base64_slice() == other
    }
}

impl PartialEq<&Base64Slice> for Base64Vec {
    #[inline]
    fn eq(&self, other: &&Base64Slice) -> bool {
        self.as_base64_slice() == *other
    }
}

impl PartialEq<Base64Vec> for Base64Slice {
    #[inline]
    fn eq(&self, other: &Base64Vec) -> bool {
        self == other.as_base64_slice()
    }
}

impl PartialEq<Base64Vec> for &Base64Slice {
    #[inline]
    fn eq(&self, other: &Base64Vec) -> bool {
        *self == other.as_base64_slice()
    }
}

#[cfg(feature = "serde")]
mod serde_impls {
    use super::Base64Vec;
    use crate::Base64Slice;
    use alloc::vec::Vec;
    use base64::Engine;
    use core::fmt;
    use serde_core::{Deserializer, Serialize, Serializer, de::Visitor};

    /// Deserializes base64 strings (if human-readable) or byte
    /// arrays (if not) to `Vec<u8>`.
    fn deserialize_bytes<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
    where
        D: Deserializer<'de>,
    {
        use serde_core::de::Error;

        if deserializer.is_human_readable() {
            struct Base64Visitor;

            impl<'de2> Visitor<'de2> for Base64Visitor {
                type Value = Vec<u8>;

                fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                    write!(f, "a base64-encoded string")
                }

                fn visit_str<E>(self, data: &str) -> Result<Self::Value, E>
                where
                    E: Error,
                {
                    base64::engine::general_purpose::STANDARD
                        .decode(data)
                        .map_err(Error::custom)
                }
            }

            deserializer.deserialize_str(Base64Visitor)
        } else {
            crate::serde_util::deserialize_byte_buf(deserializer)
        }
    }

    impl Base64Vec {
        /// Serializes a byte vector as base64 if the format is
        /// human-readable, or as raw bytes otherwise.
        ///
        /// Intended for use with `#[serde(with = "Base64Vec")]`.
        ///
        /// # Examples
        ///
        /// ```
        /// use byte_wrapper::Base64Vec;
        /// use serde::{Deserialize, Serialize};
        ///
        /// #[derive(Serialize, Deserialize)]
        /// struct Blob {
        ///     #[serde(with = "Base64Vec")]
        ///     data: Vec<u8>,
        /// }
        ///
        /// let b = Blob { data: vec![1, 2, 3] };
        /// let json = serde_json::to_string(&b).unwrap();
        /// assert_eq!(json, r#"{"data":"AQID"}"#);
        /// ```
        #[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
        pub fn serialize<S>(
            bytes: &[u8],
            serializer: S,
        ) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            Base64Slice::new(bytes).serialize(serializer)
        }

        /// Deserializes a byte vector from base64 if the format is
        /// human-readable, or as raw bytes otherwise.
        ///
        /// Intended for use with `#[serde(with = "Base64Vec")]`.
        ///
        /// # Examples
        ///
        /// ```
        /// use byte_wrapper::Base64Vec;
        /// use serde::{Deserialize, Serialize};
        ///
        /// #[derive(Serialize, Deserialize)]
        /// struct Blob {
        ///     #[serde(with = "Base64Vec")]
        ///     data: Vec<u8>,
        /// }
        ///
        /// let b: Blob = serde_json::from_str(r#"{"data":"AQID"}"#).unwrap();
        /// assert_eq!(b.data, [1, 2, 3]);
        /// ```
        #[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
        pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserialize_bytes(deserializer)
        }
    }

    #[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
    impl serde_core::Serialize for Base64Vec {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            self.as_base64_slice().serialize(serializer)
        }
    }

    #[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
    impl<'de> serde_core::Deserialize<'de> for Base64Vec {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserialize_bytes(deserializer).map(Self)
        }
    }
}

#[cfg(feature = "schemars08")]
mod schemars_impls {
    use super::Base64Vec;
    use crate::{Base64Slice, schemars_util::x_rust_type_extension};
    use alloc::string::String;
    use schemars08::{
        JsonSchema,
        r#gen::SchemaGenerator,
        schema::{InstanceType, Schema, SchemaObject},
    };

    impl JsonSchema for Base64Vec {
        fn schema_name() -> String {
            "Base64Vec".into()
        }

        fn is_referenceable() -> bool {
            false
        }

        fn json_schema(_generator: &mut SchemaGenerator) -> Schema {
            let mut extensions = x_rust_type_extension("Base64Vec");
            extensions.insert("contentEncoding".into(), "base64".into());
            Schema::Object(SchemaObject {
                instance_type: Some(InstanceType::String.into()),
                format: Some("byte".into()),
                extensions,
                ..Default::default()
            })
        }
    }

    // Base64Slice shares Base64Vec's schema (including `x-rust-type` set to
    // `Base64Vec`) since generated code needs owned types. (This also covers
    // `Cow<'_, Base64Slice>`.)
    impl JsonSchema for Base64Slice {
        fn schema_name() -> String {
            Base64Vec::schema_name()
        }

        fn is_referenceable() -> bool {
            Base64Vec::is_referenceable()
        }

        fn json_schema(generator: &mut SchemaGenerator) -> Schema {
            Base64Vec::json_schema(generator)
        }
    }
}