pubhubs/misc/
serde_ext.rs

1//! Tools for (de)serialization
2use serde::{
3    Deserialize, Deserializer, Serialize, Serializer, de::IntoDeserializer as _, ser::Error as _,
4};
5
6use core::fmt;
7use std::marker::PhantomData;
8
9/// A deprecated field that is ignored on read and re-emitted as a fixed placeholder on write.
10///
11/// On deserialize it consumes and discards any value (via [`serde::de::IgnoredAny`], so it also
12/// works under `#[serde(deny_unknown_fields)]`).  On serialize it writes `T::default()` through
13/// `T`'s own [`Serialize`].
14///
15/// Use this for a wire field that newer code no longer reads but that must still be *present* (and
16/// valid-looking) for older peers.  A field that may simply be *omitted* instead wants a
17/// `#[serde(default, skip_serializing)]` over a [`serde::de::IgnoredAny`] — no placeholder type
18/// needed.
19///
20/// `T` only selects which placeholder to emit; no `T` is stored — the field is just a marker.
21pub struct Placeholder<T>(PhantomData<T>);
22
23// Implemented by hand rather than derived: `#[derive(Clone)]` &c. would generate
24// `impl<T: Clone> Clone for Placeholder<T>`, tying each trait to whether `T` has it.  But `T` is
25// only a phantom marker (never stored), so `Placeholder<T>` should carry these traits
26// unconditionally — independent of which placeholder type `T` is.
27impl<T> Default for Placeholder<T> {
28    fn default() -> Self {
29        Self(PhantomData)
30    }
31}
32impl<T> Clone for Placeholder<T> {
33    fn clone(&self) -> Self {
34        *self
35    }
36}
37impl<T> Copy for Placeholder<T> {}
38impl<T> fmt::Debug for Placeholder<T> {
39    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
40        f.write_str("Placeholder")
41    }
42}
43impl<T> PartialEq for Placeholder<T> {
44    fn eq(&self, _: &Self) -> bool {
45        true
46    }
47}
48impl<T> Eq for Placeholder<T> {}
49
50impl<T: Default + Serialize> Serialize for Placeholder<T> {
51    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
52        T::default().serialize(serializer)
53    }
54}
55
56impl<'de, T> Deserialize<'de> for Placeholder<T> {
57    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
58        serde::de::IgnoredAny::deserialize(deserializer)?;
59        Ok(Self(PhantomData))
60    }
61}
62
63/// Deserializes an empty (json) object to a type `T`.  Panics if this is not possible.
64pub fn default_object<T: serde::de::DeserializeOwned>() -> T {
65    serde_json::from_value(serde_json::Value::Object(Default::default())).unwrap()
66}
67
68pub mod bytes_wrapper {
69    use super::*;
70
71    /// Wraps a type `T` that uses the byte array serde data type for serialization so
72    /// that the serde string data type is used instead,
73    /// according to [BytesEncoding] `O::Encoding`.
74    ///
75    /// Due to the generic (de)serialize implementation, the standard types
76    /// `Vec<u8>`, `&[u8]`, `[u8,N]`, ... use the sequence serde data type instead of byte array.
77    ///
78    /// Use [serde_bytes::Bytes], [serde_bytes::ByteBuf], and [ByteArray] instead.
79    /// (Or use [`ChangeVisitorType`] to change the visitor type to [`VisitorType::ByteSequence`].)
80    ///
81    /// We primarily use this to encode keys as hex or base64 strings in JSON instead of arrays.
82    pub struct BytesWrapper<T, O> {
83        inner: T,
84        phantom: PhantomData<O>,
85    }
86
87    // Implement some traits that are not derived correctly due to the presence of `O`.
88    impl<T: Copy, O> Copy for BytesWrapper<T, O> {}
89
90    impl<T: Clone, O> Clone for BytesWrapper<T, O> {
91        fn clone(&self) -> Self {
92            Self {
93                inner: self.inner.clone(),
94                phantom: PhantomData,
95            }
96        }
97    }
98
99    impl<T: fmt::Debug, O> fmt::Debug for BytesWrapper<T, O> {
100        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
101            self.inner.fmt(f)
102        }
103    }
104
105    impl<T: PartialEq, O> PartialEq for BytesWrapper<T, O> {
106        fn eq(&self, other: &Self) -> bool {
107            self.inner.eq(&other.inner)
108        }
109    }
110
111    impl<T: Eq, O> Eq for BytesWrapper<T, O> {}
112
113    impl<T: std::hash::Hash, O> std::hash::Hash for BytesWrapper<T, O> {
114        fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
115            self.inner.hash(state)
116        }
117
118        // NOTE: we can't implement the provided mehtod `hash_slice` by forwarding
119        // it to T::hash_slice, because we cannot create a `&[T]` from a `&[Self]`
120        // without copying.
121    }
122
123    impl<T: PartialOrd, O> PartialOrd for BytesWrapper<T, O> {
124        fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
125            self.inner.partial_cmp(&other.inner)
126        }
127
128        fn lt(&self, other: &Self) -> bool {
129            self.inner.lt(&other.inner)
130        }
131
132        fn le(&self, other: &Self) -> bool {
133            self.inner.le(&other.inner)
134        }
135
136        fn gt(&self, other: &Self) -> bool {
137            self.inner.gt(&other.inner)
138        }
139
140        fn ge(&self, other: &Self) -> bool {
141            self.inner.ge(&other.inner)
142        }
143    }
144
145    impl<T: Ord, O> Ord for BytesWrapper<T, O> {
146        fn cmp(&self, other: &Self) -> std::cmp::Ordering {
147            self.inner.cmp(&other.inner)
148        }
149
150        // NOTE: we can't more efficiently implement `max`, `min` and `clamp` by forwarding to the
151        // implementations on `T`.
152    }
153
154    impl<T: Default, O> Default for BytesWrapper<T, O> {
155        fn default() -> Self {
156            Self {
157                inner: T::default(),
158                phantom: PhantomData,
159            }
160        }
161    }
162
163    impl<T: zeroize::Zeroize, O> zeroize::Zeroize for BytesWrapper<T, O> {
164        fn zeroize(&mut self) {
165            self.inner.zeroize()
166        }
167    }
168
169    /// Determines how exactly [`BytesWrapper`] should wrap the underlying type.
170    pub trait Options {
171        /// How this type is encoded (e.g. base16, base64, etc.)
172        type Encoding;
173
174        /// During deserialization, how should the byte array be visited?
175        const VISITOR_TYPE: VisitorType = VisitorType::default();
176    }
177
178    impl<E> Options for (E,)
179    where
180        E: BytesEncoding,
181    {
182        type Encoding = E;
183    }
184
185    /// Changes the [`VisitorType`] of the given [`Options`] to `VT`.
186    pub struct ChangeVisitorType<O, const VT: isize> {
187        phantom_o: PhantomData<O>,
188    }
189
190    impl<O, const VT: isize> Options for ChangeVisitorType<O, VT>
191    where
192        O: Options,
193    {
194        type Encoding = O::Encoding;
195
196        const VISITOR_TYPE: VisitorType = match VT {
197            VT_OWNED_BYTE_ARRAY => VisitorType::OwnedByteArray,
198            VT_BORROWED_BYTE_ARRAY => VisitorType::BorrowedByteArray,
199            VT_TRANSIENT_BYTE_ARRAY => VisitorType::TransientByteArray,
200            VT_BYTE_SEQUENCE => VisitorType::ByteSequence,
201            _ => panic!("Unknown visitor type"),
202        };
203    }
204
205    impl<T, O> From<T> for BytesWrapper<T, O> {
206        fn from(inner: T) -> Self {
207            Self {
208                inner,
209                phantom: PhantomData,
210            }
211        }
212    }
213
214    impl<T, O> BytesWrapper<T, O> {
215        /// Returns the wrapped object.
216        ///
217        /// Note:  We cannot implement `Into<T>` for [BytesWrapper], because it would clash
218        /// with the implementation of `Into<T>` when `T` implements `From<BytesWrapper>`.
219        pub fn into_inner(self) -> T {
220            self.inner
221        }
222
223        pub fn new(inner: T) -> Self {
224            inner.into()
225        }
226    }
227
228    impl<O> BytesWrapper<serde_bytes::ByteBuf, O> {
229        /// Wraps a copy of the given bytes (e.g. for the [`B64`] byte-blob type).
230        pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Self {
231            serde_bytes::ByteBuf::from(bytes.as_ref().to_vec()).into()
232        }
233    }
234
235    const VT_OWNED_BYTE_ARRAY: isize = 0;
236    const VT_BORROWED_BYTE_ARRAY: isize = 1;
237    const VT_TRANSIENT_BYTE_ARRAY: isize = 2;
238    const VT_BYTE_SEQUENCE: isize = 3;
239
240    /// Enumerates the ways in which a sequence of bytes may be visited during deserialization.
241    #[repr(isize)]
242    pub enum VisitorType {
243        /// [serde::de::Visitor::visit_byte_buf], default
244        OwnedByteArray = VT_OWNED_BYTE_ARRAY,
245
246        /// [serde::de::Visitor::visit_borrowed_bytes]
247        BorrowedByteArray = VT_BORROWED_BYTE_ARRAY,
248
249        /// [serde::de::Visitor::visit_bytes]
250        TransientByteArray = VT_TRANSIENT_BYTE_ARRAY,
251
252        /// [serde::de::Visitor::visit_seq]
253        ByteSequence = VT_BYTE_SEQUENCE,
254    }
255
256    impl VisitorType {
257        const fn default() -> Self {
258            VisitorType::OwnedByteArray
259        }
260    }
261
262    /// Trait for specifying the encoding of bytes as strings, like hex or base64.
263    pub trait BytesEncoding {
264        type Error: std::error::Error;
265
266        /// Encodes `src` into `dst`, returning the slice of `dst` that was written.
267        ///
268        /// The caller must ensure that `len(dst) >= encoded_len(src).unwrap()`.
269        fn encode<'a>(src: &[u8], dst: &'a mut str) -> Result<&'a str, Self::Error>;
270
271        /// Decodes `src` into `dst`, returning the slice of `dst` that was written.
272        ///
273        /// The caller must ensure that `len(dst) >= decoded_len(src).unwrap()`.
274        fn decode<'a>(src: &str, dst: &'a mut [u8]) -> Result<&'a [u8], Self::Error>;
275
276        /// See [Self::encode].
277        fn encoded_len(bytes: &[u8]) -> Result<usize, Self::Error>;
278
279        /// See [Self::decode].
280        fn decoded_len(bytes: &str) -> Result<usize, Self::Error>;
281    }
282
283    /// Hex [BytesEncoding].
284    pub struct B16Encoding<
285        const ENCODE_LOWER_CASE: bool = { true },
286        const DECODE_MIXED_CASE: bool = { true },
287    > {}
288
289    /// Wrapper around `T` implementing (de)serialization using hex-encoding.
290    pub type B16<
291        T = serde_bytes::ByteBuf,
292        const ENCODE_LOWER_CASE: bool = true,
293        const DECODE_MIXED_CASE: bool = true,
294    > = BytesWrapper<T, (B16Encoding<ENCODE_LOWER_CASE, DECODE_MIXED_CASE>,)>;
295
296    impl<const ELC: bool, const DMC: bool> BytesEncoding for B16Encoding<ELC, DMC> {
297        type Error = base16ct::Error;
298
299        fn encode<'a>(src: &[u8], dst: &'a mut str) -> Result<&'a str, Self::Error> {
300            let dst: &'a mut [u8] = unsafe { dst.as_bytes_mut() };
301            // SAFETY: hex characters are valid utf8
302
303            if ELC {
304                base16ct::lower::encode_str(src, dst)
305            } else {
306                base16ct::upper::encode_str(src, dst)
307            }
308        }
309
310        fn decode<'a>(src: &str, dst: &'a mut [u8]) -> Result<&'a [u8], Self::Error> {
311            let src: &[u8] = src.as_bytes();
312
313            if DMC {
314                base16ct::mixed::decode(src, dst)
315            } else if ELC {
316                base16ct::lower::decode(src, dst)
317            } else {
318                base16ct::upper::decode(src, dst)
319            }
320        }
321
322        fn encoded_len(bytes: &[u8]) -> Result<usize, Self::Error> {
323            if bytes.len() >= usize::MAX / 2 {
324                Err(base16ct::Error::InvalidLength)
325            } else {
326                Ok(base16ct::encoded_len(bytes))
327            }
328        }
329
330        fn decoded_len(bytes: &str) -> Result<usize, Self::Error> {
331            base16ct::decoded_len(bytes.as_bytes())
332        }
333    }
334
335    /// Base64 [BytesEncoding]
336    pub struct B64Encoding<Enc: base64ct::Encoding> {
337        phantom: PhantomData<Enc>,
338    }
339
340    /// Wrapper around `T` implementing (de)serialization using [base64ct::Base64].
341    pub type B64<T = serde_bytes::ByteBuf> = BytesWrapper<T, (B64Encoding<base64ct::Base64>,)>;
342
343    /// Wrapper around `T` implementing (de)serialization using [base64ct::Base64UrlUnpadded].
344    pub type B64UU<T = serde_bytes::ByteBuf> =
345        BytesWrapper<T, (B64Encoding<base64ct::Base64UrlUnpadded>,)>;
346
347    impl<Enc: base64ct::Encoding> BytesEncoding for B64Encoding<Enc> {
348        type Error = base64ct::Error;
349
350        fn encode<'a>(src: &[u8], dst: &'a mut str) -> Result<&'a str, Self::Error> {
351            // SAFETY: all the base64ct alphabets are valid utf-8
352            Enc::encode(src, unsafe { dst.as_bytes_mut() }).map_err(Into::into)
353        }
354
355        fn decode<'a>(src: &str, dst: &'a mut [u8]) -> Result<&'a [u8], Self::Error> {
356            Enc::decode(src, dst)
357        }
358
359        fn encoded_len(bytes: &[u8]) -> Result<usize, Self::Error> {
360            if bytes.len() >= usize::MAX / 4 {
361                Err(base64ct::Error::InvalidLength)
362            } else {
363                Ok(Enc::encoded_len(bytes))
364            }
365        }
366
367        fn decoded_len(bytes: &str) -> Result<usize, Self::Error> {
368            // NOTE: base64ct provides no `decoded_len` function, so we overestimate
369            // the decoded length as the original length
370            Ok(bytes.len())
371        }
372    }
373
374    impl<T, O> std::ops::Deref for BytesWrapper<T, O> {
375        type Target = T;
376
377        fn deref(&self) -> &Self::Target {
378            &self.inner
379        }
380    }
381
382    impl<T, O> std::ops::DerefMut for BytesWrapper<T, O> {
383        fn deref_mut(&mut self) -> &mut Self::Target {
384            &mut self.inner
385        }
386    }
387
388    /// Contains implementation details for [`EncodingSerializer`].
389    mod encoding_serializer {
390        use super::*;
391
392        macro_rules! expected_bytes {
393            ($got : tt) => {
394                Err(Self::Error::custom(ExpectedBytesError {
395                    got: stringify!($got),
396                }))
397            };
398        }
399
400        macro_rules! serialize_primitives {
401            ($($f: ident: $t:ty,)*) => {
402                $(
403                    fn $f(self, _v:$t) -> Result<Self::Ok, Self::Error> {
404                        expected_bytes!($t)
405                    }
406                )*
407            }
408        }
409
410        /// Serializes a byte array by encoding it according to [BytesEncoding] `E` and passing
411        /// the resulting string to the [Serializer] `S`.
412        pub(super) struct EncodingSerializer<S, E> {
413            s: S,
414            phantom: PhantomData<E>,
415        }
416
417        impl<S, E> EncodingSerializer<S, E>
418        where
419            S: Serializer,
420            E: BytesEncoding,
421        {
422            pub(super) fn new(s: S) -> Self {
423                Self {
424                    s,
425                    phantom: PhantomData,
426                }
427            }
428        }
429
430        impl<S, E> Serializer for EncodingSerializer<S, E>
431        where
432            S: Serializer,
433            E: BytesEncoding,
434        {
435            type Ok = S::Ok;
436            type Error = S::Error;
437            type SerializeSeq = serde::ser::Impossible<S::Ok, Self::Error>;
438            type SerializeTuple = encoding_serializer::SerializeTuple<S, E>;
439            type SerializeTupleStruct = serde::ser::Impossible<S::Ok, Self::Error>;
440            type SerializeTupleVariant = serde::ser::Impossible<S::Ok, Self::Error>;
441            type SerializeMap = serde::ser::Impossible<S::Ok, Self::Error>;
442            type SerializeStruct = serde::ser::Impossible<S::Ok, Self::Error>;
443            type SerializeStructVariant = serde::ser::Impossible<S::Ok, Self::Error>;
444
445            fn serialize_bytes(self, v: &[u8]) -> Result<Self::Ok, Self::Error> {
446                let encoded_len: usize = match E::encoded_len(v) {
447                    Ok(encoded_len) => encoded_len,
448                    Err(err) => return Err(S::Error::custom(err)),
449                };
450
451                let mut string = unsafe { String::from_utf8_unchecked(vec![0; encoded_len]) };
452                // SAFETY: only zeroes is valid utf8
453
454                let substr: &str = match E::encode(v, &mut string) {
455                    Ok(substr) => substr,
456                    Err(err) => return Err(S::Error::custom(err)),
457                };
458
459                self.s.serialize_str(substr)
460            }
461
462            fn serialize_tuple(self, len: usize) -> Result<Self::SerializeTuple, Self::Error> {
463                Ok(encoding_serializer::SerializeTuple::<S, E>::new(self, len))
464            }
465
466            serialize_primitives! {
467                serialize_bool: bool,
468                serialize_i8: i8,
469                serialize_i16: i16,
470                serialize_i32: i32,
471                serialize_i64: i64,
472                serialize_i128: i128,
473                serialize_u8: u8,
474                serialize_u16: u16,
475                serialize_u32: u32,
476                serialize_u64: u64,
477                serialize_u128: u128,
478                serialize_f32: f32,
479                serialize_f64: f64,
480                serialize_char: char,
481                serialize_str: &str,
482                serialize_unit_struct: &'static str,
483            }
484
485            fn serialize_none(self) -> Result<Self::Ok, Self::Error> {
486                expected_bytes!("none")
487            }
488
489            fn serialize_some<T>(self, _value: &T) -> Result<Self::Ok, Self::Error>
490            where
491                T: Serialize + ?Sized,
492            {
493                expected_bytes!("some")
494            }
495
496            fn serialize_unit(self) -> Result<Self::Ok, Self::Error> {
497                expected_bytes!("unit")
498            }
499
500            fn serialize_unit_variant(
501                self,
502                _name: &'static str,
503                _variant_index: u32,
504                _variant: &'static str,
505            ) -> Result<Self::Ok, Self::Error> {
506                expected_bytes!("unit variant")
507            }
508
509            fn serialize_newtype_struct<T>(
510                self,
511                _name: &'static str,
512                _value: &T,
513            ) -> Result<Self::Ok, Self::Error>
514            where
515                T: Serialize + ?Sized,
516            {
517                expected_bytes!("newtype struct")
518            }
519
520            fn serialize_newtype_variant<T>(
521                self,
522                _name: &'static str,
523                _variant_index: u32,
524                _variant: &'static str,
525                _value: &T,
526            ) -> Result<Self::Ok, Self::Error>
527            where
528                T: Serialize + ?Sized,
529            {
530                expected_bytes!("newtype variant")
531            }
532
533            fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error> {
534                expected_bytes!("seq")
535            }
536
537            fn serialize_tuple_struct(
538                self,
539                _name: &'static str,
540                _len: usize,
541            ) -> Result<Self::SerializeTupleStruct, Self::Error> {
542                expected_bytes!("tuple struct")
543            }
544
545            fn serialize_tuple_variant(
546                self,
547                _name: &'static str,
548                _variant_index: u32,
549                _variant: &'static str,
550                _len: usize,
551            ) -> Result<Self::SerializeTupleVariant, Self::Error> {
552                expected_bytes!("tuple variant")
553            }
554
555            fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeMap, Self::Error> {
556                expected_bytes!("map")
557            }
558
559            fn serialize_struct(
560                self,
561                _name: &'static str,
562                _len: usize,
563            ) -> Result<Self::SerializeStruct, Self::Error> {
564                expected_bytes!("struct")
565            }
566
567            fn serialize_struct_variant(
568                self,
569                _name: &'static str,
570                _variant_index: u32,
571                _variant: &'static str,
572                _len: usize,
573            ) -> Result<Self::SerializeStructVariant, Self::Error> {
574                expected_bytes!("struct variant")
575            }
576        }
577
578        #[derive(thiserror::Error, Debug)]
579        #[error(
580            "to use a bytes encoding (like base64) for the serialization of a type, that type must serialize to bytes, but got {got}"
581        )]
582        struct ExpectedBytesError {
583            got: &'static str,
584        }
585
586        pub(super) struct SerializeTuple<S, E> {
587            inner: Vec<u8>,
588            encoding_serializer: EncodingSerializer<S, E>,
589            expected_len: usize,
590        }
591
592        impl<S, E> SerializeTuple<S, E> {
593            fn new(encoding_serializer: EncodingSerializer<S, E>, expected_len: usize) -> Self
594            where
595                S: Serializer,
596                E: BytesEncoding,
597            {
598                Self {
599                    encoding_serializer,
600                    expected_len,
601                    inner: Vec::<u8>::with_capacity(expected_len),
602                }
603            }
604        }
605
606        impl<S: Serializer, E: BytesEncoding> serde::ser::SerializeTuple for SerializeTuple<S, E> {
607            type Ok = S::Ok;
608            type Error = S::Error;
609
610            fn serialize_element<T: Serialize + ?Sized>(
611                &mut self,
612                value: &T,
613            ) -> Result<(), Self::Error> {
614                if self.inner.len() == self.expected_len {
615                    return Err(Self::Error::custom(
616                        "improper use of serializer: serializing more tuple elements than announced",
617                    ));
618                }
619
620                // TODO, maybe: proper `ByteSerializer` implementation to replace this hack
621                let byte =
622                    u8::deserialize(value.serialize(serde_json::value::Serializer).map_err(
623                        |err| {
624                            Self::Error::custom(format!(
625                                "failed to serialize to byte (hackingly via serde_json): {err}"
626                            ))
627                        },
628                    )?)
629                    .map_err(|err| {
630                        Self::Error::custom(format!(
631                            "failed to serialize to byte (hackingly via serde_json): {err}"
632                        ))
633                    })?;
634                self.inner.push(byte);
635
636                Ok(())
637            }
638
639            fn end(self) -> Result<Self::Ok, Self::Error> {
640                if self.inner.len() != self.expected_len {
641                    return Err(Self::Error::custom(
642                        "improper use of serializer: serialized less tuple elements than announced",
643                    ));
644                }
645
646                self.encoding_serializer.serialize_bytes(&self.inner)
647            }
648        }
649    }
650
651    use encoding_serializer::EncodingSerializer;
652
653    impl<T, O: Options> Serialize for BytesWrapper<T, O>
654    where
655        T: Serialize,
656        O::Encoding: BytesEncoding,
657    {
658        fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
659            self.inner
660                .serialize(EncodingSerializer::<_, O::Encoding>::new(s))
661        }
662    }
663
664    impl<T, O: Options> core::str::FromStr for BytesWrapper<T, O>
665    where
666        T: for<'de> Deserialize<'de>,
667        O::Encoding: BytesEncoding,
668    {
669        type Err = serde::de::value::Error;
670
671        fn from_str(s: &str) -> Result<Self, Self::Err> {
672            Self::deserialize(s.into_deserializer())
673        }
674    }
675
676    impl<T, O: Options> std::fmt::Display for BytesWrapper<T, O>
677    where
678        T: Serialize,
679        O::Encoding: BytesEncoding,
680    {
681        fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
682            self.serialize(f)
683        }
684    }
685
686    /// Extracts a `O::Value` from the given [Deserializer] by extracting a string,
687    /// decoding this to a byte array according to [BytesEncoding] `O::Encoding`,
688    /// and finally passing this byte array to the [Deserialize] implementation of `T`.
689    struct EncodedBytesVisitor<T, O> {
690        phantom_t: PhantomData<T>,
691        phantom_o: PhantomData<O>,
692    }
693
694    impl<T, O: Options> EncodedBytesVisitor<T, O>
695    where
696        T: serde::de::DeserializeOwned,
697        O::Encoding: BytesEncoding,
698    {
699        fn new() -> Self {
700            Self {
701                phantom_t: PhantomData,
702                phantom_o: PhantomData,
703            }
704        }
705    }
706
707    impl<T, O: Options> serde::de::Visitor<'_> for EncodedBytesVisitor<T, O>
708    where
709        T: serde::de::DeserializeOwned,
710        O::Encoding: BytesEncoding,
711    {
712        type Value = T;
713
714        fn expecting(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
715            write!(f, "str")
716        }
717
718        fn visit_str<Error: serde::de::Error>(self, v: &str) -> Result<Self::Value, Error> {
719            let decoded_len: usize = match O::Encoding::decoded_len(v) {
720                Ok(decoded_len) => decoded_len,
721                Err(err) => return Err(Error::custom(err)), // TODO: better err?
722            };
723
724            let mut buf = vec![0; decoded_len];
725
726            let slice: &[u8] = match O::Encoding::decode(v, &mut buf) {
727                Ok(slice) => slice,
728                Err(err) => return Err(Error::custom(err)), // TODO: better err?
729            };
730
731            let slice_len = slice.len();
732            let slice_ptr = slice.as_ptr();
733
734            // truncate buf to the size used by decode, but first check that slice
735            // is indeed a slice into buf starting at index 0
736            assert_eq!(buf.as_ptr(), slice_ptr);
737            buf.truncate(slice_len);
738
739            match O::VISITOR_TYPE {
740                VisitorType::OwnedByteArray => T::deserialize(ByteBufDeserializer::new(buf)),
741                VisitorType::BorrowedByteArray => {
742                    T::deserialize(serde::de::value::BorrowedBytesDeserializer::new(&buf))
743                }
744                VisitorType::TransientByteArray => {
745                    T::deserialize(serde::de::value::BytesDeserializer::new(&buf))
746                }
747                VisitorType::ByteSequence => {
748                    T::deserialize(serde::de::value::SeqDeserializer::new(buf.into_iter()))
749                }
750            }
751        }
752    }
753
754    /// A [Deserializer] owning a `Vec<u8>` that always calls [serde::de::Visitor::visit_byte_buf].
755    #[derive(Clone)]
756    pub struct ByteBufDeserializer<E> {
757        value: Vec<u8>,
758        marker: PhantomData<E>,
759    }
760
761    impl<E> ByteBufDeserializer<E> {
762        pub fn new(value: Vec<u8>) -> Self {
763            Self {
764                value,
765                marker: PhantomData,
766            }
767        }
768    }
769
770    impl<'de, E> serde::de::Deserializer<'de> for ByteBufDeserializer<E>
771    where
772        E: serde::de::Error,
773    {
774        type Error = E;
775
776        fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
777        where
778            V: serde::de::Visitor<'de>,
779        {
780            visitor.visit_byte_buf(self.value)
781        }
782
783        serde::forward_to_deserialize_any! {
784            bool i8 i16 i32 i64 i128 u8 u16 u32 u64 u128 f32 f64 char str string
785            bytes byte_buf option unit unit_struct newtype_struct seq tuple
786            tuple_struct map struct identifier ignored_any enum
787        }
788    }
789
790    impl<E> core::fmt::Debug for ByteBufDeserializer<E> {
791        fn fmt(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
792            formatter
793                .debug_struct("ByteBufDeserializer")
794                .field("value", &self.value)
795                .finish()
796        }
797    }
798
799    impl<'de, T, O: Options> Deserialize<'de> for BytesWrapper<T, O>
800    where
801        T: for<'de2> Deserialize<'de2>,
802        O::Encoding: BytesEncoding,
803    {
804        fn deserialize<D>(d: D) -> Result<Self, D::Error>
805        where
806            D: Deserializer<'de>,
807        {
808            Ok(d.deserialize_str(EncodedBytesVisitor::<T, O>::new())?
809                .into())
810        }
811    }
812
813    #[cfg(test)]
814    mod tests {
815        use super::*;
816
817        #[test]
818        fn serialize_bytes_wrapper() {
819            assert_eq!(
820                &serde_json::to_string(&B64UU::<_>::from(serde_bytes::ByteBuf::from([0; 32])))
821                    .unwrap(),
822                "\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\""
823            );
824        }
825
826        #[test]
827        fn byte_array_deserialization() {
828            assert_eq!(
829                ByteArray::<4>::deserialize(serde::de::value::BytesDeserializer::<
830                    serde::de::value::Error,
831                >::new(b"test"))
832                .unwrap()
833                .inner,
834                *b"test"
835            );
836
837            assert_eq!(
838                ByteArray::<4>::deserialize(serde::de::value::BorrowedBytesDeserializer::<
839                    serde::de::value::Error,
840                >::new(b"test"))
841                .unwrap()
842                .inner,
843                *b"test"
844            );
845
846            assert_eq!(
847                ByteArray::<4>::deserialize(ByteBufDeserializer::<serde::de::value::Error>::new(
848                    b"test".to_vec()
849                ))
850                .unwrap()
851                .inner,
852                *b"test"
853            );
854        }
855
856        #[test]
857        fn ed25519_dalek_bug() {
858            let bytes = base16ct::lower::decode_vec(
859                "66b1419fae979516fb3807dda1b05026b2570a7ab2190254e524af4f0934ddd2",
860            )
861            .unwrap();
862
863            let d =
864                serde::de::value::BorrowedBytesDeserializer::<serde::de::value::Error>::new(&bytes);
865            ed25519_dalek::VerifyingKey::deserialize(d).unwrap(); // works
866
867            let d = serde::de::value::BytesDeserializer::<serde::de::value::Error>::new(&bytes);
868            ed25519_dalek::VerifyingKey::deserialize(d).unwrap();
869            // This *used to* err, but now works after
870            // https://github.com/dalek-cryptography/curve25519-dalek/pull/602 is released.
871
872            let d = serde::de::value::SeqDeserializer::<_, serde::de::value::Error>::new(
873                [0u8; 32].into_iter(),
874            );
875            curve25519_dalek::scalar::Scalar::deserialize(d).unwrap(); // works
876
877            let d = serde::de::value::BytesDeserializer::<serde::de::value::Error>::new(&[0u8; 32]);
878            curve25519_dalek::scalar::Scalar::deserialize(d).unwrap_err();
879            // This errs, but since `Scalar`s, unlike `{Signing,Verifying}Key`s, are serialized as
880            // byte sequences instead of byte arrays, this will probably not change anytime soon.
881        }
882    }
883}
884
885pub use bytes_wrapper::BytesWrapper;
886
887/// Wrapper around `[u8, N]` that (de)serializes using the byte buffer (instead of sequence) data type.
888#[derive(Copy, Debug, Clone, PartialEq, Eq, Hash)]
889pub struct ByteArray<const N: usize> {
890    inner: [u8; N],
891}
892
893impl<const N: usize> std::ops::Deref for ByteArray<N> {
894    type Target = [u8; N];
895
896    fn deref(&self) -> &Self::Target {
897        &self.inner
898    }
899}
900
901impl<const N: usize> From<[u8; N]> for ByteArray<N> {
902    fn from(inner: [u8; N]) -> Self {
903        Self { inner }
904    }
905}
906
907impl<const N: usize> From<ByteArray<N>> for [u8; N] {
908    fn from(val: ByteArray<N>) -> Self {
909        val.inner
910    }
911}
912
913// Manual (not derived): `[u8; N]: Default` only holds for `N` up to 32 in std, so a `derive` would
914// not apply for a general `const N`.  `[0u8; N]` works for any `N`.
915impl<const N: usize> Default for ByteArray<N> {
916    fn default() -> Self {
917        Self { inner: [0u8; N] }
918    }
919}
920
921impl<const N: usize> zeroize::Zeroize for ByteArray<N> {
922    fn zeroize(&mut self) {
923        self.inner.zeroize()
924    }
925}
926
927impl<const N: usize> Serialize for ByteArray<N> {
928    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
929        s.serialize_bytes(&self.inner)
930    }
931}
932
933/// Extracts a [ByteArray] from a [serde::Deserializer].
934struct ByteArrayVisitor<const N: usize> {}
935
936impl<const N: usize> serde::de::Visitor<'_> for ByteArrayVisitor<N> {
937    type Value = [u8; N];
938
939    fn expecting(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
940        write!(f, "a byte array of length {N}")
941    }
942
943    fn visit_byte_buf<E>(self, v: Vec<u8>) -> Result<Self::Value, E>
944    where
945        E: serde::de::Error,
946    {
947        <[u8; N]>::try_from(v).map_err(|v| E::invalid_length(v.len(), &self))
948    }
949
950    fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
951    where
952        E: serde::de::Error,
953    {
954        <[u8; N]>::try_from(v).map_err(|_| E::invalid_length(v.len(), &self))
955    }
956}
957
958impl<'de, const N: usize> Deserialize<'de> for ByteArray<N> {
959    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
960        Ok(d.deserialize_byte_buf(ByteArrayVisitor::<N> {})?.into())
961    }
962}
pubhubs/misc/serde_ext.rs

pubhubs/misc/
serde_ext.rs
