Skip to main content

tycho_common/
serde_primitives.rs

1use std::{collections::HashMap, fmt, hash::Hash, marker::PhantomData};
2
3use hex::FromHexError;
4use serde::{de, Deserialize, Deserializer};
5
6use crate::Bytes;
7
8/// Decodes a hex string with an optional `0x` prefix. An odd number of digits has an implied
9/// leading zero.
10fn decode_hex_with_prefix(val: &str) -> Result<Vec<u8>, FromHexError> {
11    let digits = val
12        .strip_prefix("0x")
13        .unwrap_or(val)
14        .as_bytes();
15    let mut out = vec![0u8; digits.len().div_ceil(2)];
16    if digits.len().is_multiple_of(2) {
17        hex::decode_to_slice(digits, &mut out)?;
18    } else if let (Some((first, rest)), Some((first_out, rest_out))) =
19        (digits.split_first(), out.split_first_mut())
20    {
21        hex::decode_to_slice([b'0', *first], std::slice::from_mut(first_out))?;
22        hex::decode_to_slice(rest, rest_out)?;
23    }
24    Ok(out)
25}
26
27/// Bytes decoded from a hex string. The string is decoded where the deserializer holds it, without
28/// copying it into a `String` first.
29struct HexValue(Vec<u8>);
30
31impl<'de> Deserialize<'de> for HexValue {
32    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
33    where
34        D: Deserializer<'de>,
35    {
36        struct HexVisitor;
37
38        impl de::Visitor<'_> for HexVisitor {
39            type Value = HexValue;
40
41            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
42                formatter.write_str("a hex string")
43            }
44
45            fn visit_str<E: de::Error>(self, v: &str) -> Result<HexValue, E> {
46                decode_hex_with_prefix(v)
47                    .map(HexValue)
48                    .map_err(|e| E::custom(e.to_string()))
49            }
50        }
51
52        deserializer.deserialize_str(HexVisitor)
53    }
54}
55
56impl From<HexValue> for Bytes {
57    fn from(value: HexValue) -> Self {
58        Bytes::from(value.0)
59    }
60}
61
62/// Deserializes a map straight into its final types: each entry is read as `(KR, VR)` and
63/// converted, with no intermediate map.
64fn deserialize_map<'de, D, KR, VR, K, V>(d: D) -> Result<HashMap<K, V>, D::Error>
65where
66    D: Deserializer<'de>,
67    KR: Deserialize<'de> + Into<K>,
68    VR: Deserialize<'de> + Into<V>,
69    K: Eq + Hash,
70{
71    struct MapVisitor<KR, VR, K, V>(PhantomData<(KR, VR, K, V)>);
72
73    impl<'de, KR, VR, K, V> de::Visitor<'de> for MapVisitor<KR, VR, K, V>
74    where
75        KR: Deserialize<'de> + Into<K>,
76        VR: Deserialize<'de> + Into<V>,
77        K: Eq + Hash,
78    {
79        type Value = HashMap<K, V>;
80
81        fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
82            formatter.write_str("a map")
83        }
84
85        fn visit_map<A: de::MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
86            let mut entries = HashMap::with_capacity(map.size_hint().unwrap_or(0));
87            while let Some((key, value)) = map.next_entry::<KR, VR>()? {
88                entries.insert(key.into(), value.into());
89            }
90            Ok(entries)
91        }
92    }
93
94    d.deserialize_map(MapVisitor::<KR, VR, K, V>(PhantomData))
95}
96
97/// A buffer for writing bytes as `0x`-prefixed lowercase hex.
98///
99/// Reusing one buffer for many values allocates only when a value is longer than every value
100/// before it.
101#[derive(Default)]
102struct HexBuffer(Vec<u8>);
103
104impl HexBuffer {
105    /// Returns `bytes` as `0x` followed by two lowercase hex digits per byte. Empty input gives
106    /// `"0x"`. The string borrows the buffer and is valid until the next call.
107    ///
108    /// # Errors
109    ///
110    /// Returns a serializer error if the hex string length overflows `usize`.
111    fn encode<E: serde::ser::Error>(&mut self, bytes: &[u8]) -> Result<&str, E> {
112        let hex_len = bytes
113            .len()
114            .checked_mul(2)
115            .and_then(|digits| digits.checked_add(2))
116            .ok_or_else(|| {
117                E::custom(format!("cannot hex encode {} bytes: length overflows", bytes.len()))
118            })?;
119        self.0.clear();
120        self.0.extend_from_slice(b"0x");
121        self.0.resize(hex_len, 0);
122        let digits = self
123            .0
124            .get_mut(2..)
125            .ok_or_else(|| E::custom("hex buffer is shorter than its prefix"))?;
126        hex::encode_to_slice(bytes, digits).map_err(E::custom)?;
127        std::str::from_utf8(&self.0).map_err(E::custom)
128    }
129}
130
131/// serde functions for handling bytes as hex strings, such as [bytes::Bytes]
132pub mod hex_bytes {
133    use serde::{Deserialize, Deserializer, Serializer};
134
135    use super::{HexBuffer, HexValue};
136
137    /// Serialize a byte vec as a hex string with 0x prefix
138    pub fn serialize<S, T>(x: T, s: S) -> Result<S::Ok, S::Error>
139    where
140        S: Serializer,
141        T: AsRef<[u8]>,
142    {
143        s.serialize_str(HexBuffer::default().encode(x.as_ref())?)
144    }
145
146    /// Deserialize a hex string into a byte vec
147    /// Accepts a hex string with optional 0x prefix
148    pub fn deserialize<'de, T, D>(d: D) -> Result<T, D::Error>
149    where
150        D: Deserializer<'de>,
151        T: From<Vec<u8>>,
152    {
153        HexValue::deserialize(d).map(|value| value.0.into())
154    }
155}
156
157/// serde functions for handling Option of bytes
158pub mod hex_bytes_option {
159    use serde::{Deserialize, Deserializer, Serializer};
160
161    use super::{HexBuffer, HexValue};
162
163    /// Serialize a byte vec as a Some hex string with 0x prefix
164    #[expect(clippy::ref_option, reason = "serde's serialize_with passes the field by reference")]
165    pub fn serialize<S, T>(x: &Option<T>, s: S) -> Result<S::Ok, S::Error>
166    where
167        S: Serializer,
168        T: AsRef<[u8]>,
169    {
170        if let Some(x) = x {
171            s.serialize_str(HexBuffer::default().encode(x.as_ref())?)
172        } else {
173            s.serialize_none()
174        }
175    }
176
177    /// Deserialize a hex string into a byte vec or None
178    /// Accepts a hex string with optional 0x prefix
179    pub fn deserialize<'de, T, D>(d: D) -> Result<Option<T>, D::Error>
180    where
181        D: Deserializer<'de>,
182        T: From<Vec<u8>>,
183    {
184        let value: Option<HexValue> = Option::deserialize(d)?;
185        Ok(value.map(|value| value.0.into()))
186    }
187}
188
189/// serde functions for handling HashMap with a bytes key
190pub mod hex_hashmap_key {
191    use std::collections::HashMap;
192
193    use serde::{ser::SerializeMap, Deserialize, Deserializer, Serialize, Serializer};
194
195    use super::{deserialize_map, HexBuffer, HexValue};
196    use crate::Bytes;
197
198    pub fn serialize<S, V>(x: &HashMap<Bytes, V>, s: S) -> Result<S::Ok, S::Error>
199    where
200        S: Serializer,
201        V: Serialize,
202    {
203        let mut key_hex = HexBuffer::default();
204        let mut map = s.serialize_map(Some(x.len()))?;
205        for (k, v) in x.iter() {
206            map.serialize_entry(key_hex.encode(k)?, v)?;
207        }
208        map.end()
209    }
210
211    pub fn deserialize<'de, V, D>(d: D) -> Result<HashMap<Bytes, V>, D::Error>
212    where
213        D: Deserializer<'de>,
214        V: Deserialize<'de>,
215    {
216        deserialize_map::<D, HexValue, V, Bytes, V>(d)
217    }
218}
219
220/// serde functions for handling Vec of Bytes as hex strings
221pub mod hex_bytes_vec {
222    use serde::{ser::SerializeSeq, Deserialize, Deserializer, Serializer};
223
224    use super::{HexBuffer, HexValue};
225
226    /// Serialize Vec<Vec<u8>> as a list of hex strings with 0x prefix
227    pub fn serialize<S>(list: &[Vec<u8>], s: S) -> Result<S::Ok, S::Error>
228    where
229        S: Serializer,
230    {
231        let mut hex = HexBuffer::default();
232        let mut seq = s.serialize_seq(Some(list.len()))?;
233        for x in list {
234            seq.serialize_element(hex.encode(x)?)?;
235        }
236        seq.end()
237    }
238
239    /// Deserialize a list of hex strings into Vec<Vec<u8>>
240    pub fn deserialize<'de, D>(d: D) -> Result<Vec<Vec<u8>>, D::Error>
241    where
242        D: Deserializer<'de>,
243    {
244        let values = Vec::<HexValue>::deserialize(d)?;
245        Ok(values
246            .into_iter()
247            .map(|value| value.0)
248            .collect())
249    }
250}
251
252/// The length of an iterator when it is known, as a map serializer wants it.
253fn exact_len<I: Iterator>(iter: &I) -> Option<usize> {
254    match iter.size_hint() {
255        (low, Some(high)) if low == high => Some(low),
256        _ => None,
257    }
258}
259
260/// serde functions for handling HashMap with bytes value
261pub mod hex_hashmap_value {
262    use std::collections::HashMap;
263
264    use serde::{ser::SerializeMap, Deserialize, Deserializer, Serialize, Serializer};
265
266    use super::{deserialize_map, HexBuffer, HexValue};
267    use crate::Bytes;
268
269    pub fn serialize<S, K>(x: &HashMap<K, Bytes>, s: S) -> Result<S::Ok, S::Error>
270    where
271        S: Serializer,
272        K: Serialize,
273    {
274        serialize_iter(x, s)
275    }
276
277    /// Writes the pairs as one map. Needs no `HashMap`, so a caller can write borrowed pairs.
278    /// With an iterator whose length is not exact, the map length is `None`, which formats that
279    /// need a length reject.
280    pub fn serialize_iter<'a, S, K, I>(pairs: I, s: S) -> Result<S::Ok, S::Error>
281    where
282        S: Serializer,
283        K: Serialize + 'a,
284        I: IntoIterator<Item = (&'a K, &'a Bytes)>,
285    {
286        let pairs = pairs.into_iter();
287        let mut value_hex = HexBuffer::default();
288        let mut map = s.serialize_map(super::exact_len(&pairs))?;
289        for (k, v) in pairs {
290            map.serialize_entry(k, value_hex.encode(v)?)?;
291        }
292        map.end()
293    }
294
295    pub fn deserialize<'de, K, D>(d: D) -> Result<HashMap<K, Bytes>, D::Error>
296    where
297        D: Deserializer<'de>,
298        K: Deserialize<'de> + Eq + std::hash::Hash, // HashMap key trait bounds
299    {
300        deserialize_map::<D, K, HexValue, K, Bytes>(d)
301    }
302}
303
304/// serde functions for handling HashMap with a bytes key and value
305pub mod hex_hashmap_key_value {
306    use std::collections::HashMap;
307
308    use serde::{ser::SerializeMap, Deserializer, Serializer};
309
310    use super::{deserialize_map, HexBuffer, HexValue};
311    use crate::Bytes;
312
313    pub fn serialize<S>(x: &HashMap<Bytes, Bytes>, s: S) -> Result<S::Ok, S::Error>
314    where
315        S: Serializer,
316    {
317        serialize_iter(x, s)
318    }
319
320    /// Writes the pairs as one map. Needs no `HashMap`, so a caller can write borrowed pairs.
321    /// With an iterator whose length is not exact, the map length is `None`, which formats that
322    /// need a length reject.
323    pub fn serialize_iter<'a, S, I>(pairs: I, s: S) -> Result<S::Ok, S::Error>
324    where
325        S: Serializer,
326        I: IntoIterator<Item = (&'a Bytes, &'a Bytes)>,
327    {
328        let pairs = pairs.into_iter();
329        let (mut key_hex, mut value_hex) = (HexBuffer::default(), HexBuffer::default());
330        let mut map = s.serialize_map(super::exact_len(&pairs))?;
331        for (k, v) in pairs {
332            map.serialize_entry(key_hex.encode(k)?, value_hex.encode(v)?)?;
333        }
334        map.end()
335    }
336
337    pub fn deserialize<'de, D>(d: D) -> Result<HashMap<Bytes, Bytes>, D::Error>
338    where
339        D: Deserializer<'de>,
340    {
341        deserialize_map::<D, HexValue, HexValue, Bytes, Bytes>(d)
342    }
343}
344
345#[cfg(test)]
346mod tests {
347    use std::collections::HashMap;
348
349    use serde::{Deserialize, Serialize};
350
351    use super::*;
352    use crate::Bytes;
353
354    #[derive(Debug, Serialize, Deserialize)]
355    struct TestStruct {
356        #[serde(with = "hex_bytes")]
357        bytes: Vec<u8>,
358
359        #[serde(with = "hex_bytes_option")]
360        bytes_option: Option<Vec<u8>>,
361
362        #[serde(with = "hex_bytes_vec")]
363        bytes_vec: Vec<Vec<u8>>,
364    }
365
366    #[derive(Serialize)]
367    struct IterMaps {
368        #[serde(serialize_with = "key_value_via_iter")]
369        key_value: HashMap<Bytes, Bytes>,
370        #[serde(serialize_with = "value_via_iter")]
371        value: HashMap<String, Bytes>,
372    }
373
374    #[derive(Serialize)]
375    struct DirectMaps {
376        #[serde(with = "hex_hashmap_key_value")]
377        key_value: HashMap<Bytes, Bytes>,
378        #[serde(with = "hex_hashmap_value")]
379        value: HashMap<String, Bytes>,
380    }
381
382    fn key_value_via_iter<S: serde::Serializer>(
383        x: &HashMap<Bytes, Bytes>,
384        s: S,
385    ) -> Result<S::Ok, S::Error> {
386        hex_hashmap_key_value::serialize_iter(x.iter().filter(|_| true), s)
387    }
388
389    fn value_via_iter<S: serde::Serializer>(
390        x: &HashMap<String, Bytes>,
391        s: S,
392    ) -> Result<S::Ok, S::Error> {
393        hex_hashmap_value::serialize_iter(x.iter().filter(|_| true), s)
394    }
395
396    #[test]
397    fn hex_hashmap_serialize_iter_matches_serialize() {
398        let key_value = HashMap::from([(Bytes::from(vec![1, 2]), Bytes::from(vec![0xAB]))]);
399        let value = HashMap::from([("a".to_string(), Bytes::from(vec![0xFF, 0x00]))]);
400
401        let direct = serde_json::to_string(&DirectMaps {
402            key_value: key_value.clone(),
403            value: value.clone(),
404        })
405        .unwrap();
406        let via_iter = serde_json::to_string(&IterMaps { key_value, value }).unwrap();
407
408        assert_eq!(via_iter, direct);
409        assert_eq!(direct, r#"{"key_value":{"0x0102":"0xab"},"value":{"a":"0xff00"}}"#);
410    }
411
412    #[test]
413    fn hex_bytes_serialize_deserialize() {
414        let test_struct = TestStruct {
415            bytes: vec![0u8; 10],
416            bytes_option: Some(vec![0u8; 10]),
417            bytes_vec: vec![vec![0, 1, 2, 3], vec![0xFF, 0xAB]],
418        };
419
420        // Serialize to JSON
421        let serialized = serde_json::to_string(&test_struct).unwrap();
422        assert_eq!(
423            serialized,
424            "{\"bytes\":\"0x00000000000000000000\",\"bytes_option\":\"0x00000000000000000000\",\"bytes_vec\":[\"0x00010203\",\"0xffab\"]}"
425        );
426
427        // Deserialize from JSON
428        let deserialized: TestStruct = serde_json::from_str(&serialized).unwrap();
429        assert_eq!(deserialized.bytes, vec![0u8; 10]);
430        assert_eq!(deserialized.bytes_option, Some(vec![0u8; 10]));
431        assert_eq!(deserialized.bytes_vec, vec![vec![0, 1, 2, 3], vec![0xFF, 0xAB]]);
432    }
433
434    #[test]
435    fn hex_bytes_option_none() {
436        let test_struct =
437            TestStruct { bytes: vec![0u8; 10], bytes_option: None, bytes_vec: vec![] };
438
439        // Serialize to JSON
440        let serialized = serde_json::to_string(&test_struct).unwrap();
441        assert_eq!(
442            serialized,
443            "{\"bytes\":\"0x00000000000000000000\",\"bytes_option\":null,\"bytes_vec\":[]}"
444        );
445
446        // Deserialize from JSON
447        let deserialized: TestStruct = serde_json::from_str(&serialized).unwrap();
448        assert_eq!(deserialized.bytes, vec![0u8; 10]);
449        assert_eq!(deserialized.bytes_option, None);
450    }
451
452    /// Serializers that format every value with `format!`: the expected output for the ones above.
453    mod reference {
454        use std::collections::HashMap;
455
456        use serde::{ser::SerializeMap, Serialize, Serializer};
457
458        use crate::Bytes;
459
460        pub fn hex(x: &[u8]) -> String {
461            format!("0x{}", hex::encode(x))
462        }
463
464        pub fn hex_bytes<S: Serializer>(x: &[u8], s: S) -> Result<S::Ok, S::Error> {
465            s.serialize_str(&hex(x))
466        }
467
468        #[expect(clippy::ref_option, reason = "serde's `serialize_with` passes `&Option<Vec<u8>>`")]
469        pub fn hex_bytes_option<S: Serializer>(
470            x: &Option<Vec<u8>>,
471            s: S,
472        ) -> Result<S::Ok, S::Error> {
473            match x {
474                Some(x) => s.serialize_str(&hex(x)),
475                None => s.serialize_none(),
476            }
477        }
478
479        pub fn hex_bytes_vec<S: Serializer>(list: &[Vec<u8>], s: S) -> Result<S::Ok, S::Error> {
480            list.iter()
481                .map(|x| hex(x))
482                .collect::<Vec<_>>()
483                .serialize(s)
484        }
485
486        pub fn hex_hashmap_key<S: Serializer>(
487            x: &HashMap<Bytes, Bytes>,
488            s: S,
489        ) -> Result<S::Ok, S::Error> {
490            let mut map = s.serialize_map(Some(x.len()))?;
491            for (k, v) in x.iter() {
492                map.serialize_entry(&format!("{k:#x}"), v)?;
493            }
494            map.end()
495        }
496
497        pub fn hex_hashmap_value<S: Serializer>(
498            x: &HashMap<Bytes, Bytes>,
499            s: S,
500        ) -> Result<S::Ok, S::Error> {
501            let mut map = s.serialize_map(Some(x.len()))?;
502            for (k, v) in x.iter() {
503                map.serialize_entry(k, &format!("{v:#x}"))?;
504            }
505            map.end()
506        }
507
508        pub fn hex_hashmap_key_value<S: Serializer>(
509            x: &HashMap<Bytes, Bytes>,
510            s: S,
511        ) -> Result<S::Ok, S::Error> {
512            let mut map = s.serialize_map(Some(x.len()))?;
513            for (k, v) in x.iter() {
514                map.serialize_entry(&format!("{k:#x}"), &format!("{v:#x}"))?;
515            }
516            map.end()
517        }
518
519        /// Decodes by copying the digits and prepending a zero to an odd count.
520        pub fn decode(val: &str) -> Result<Vec<u8>, hex::FromHexError> {
521            let mut digits: String = val
522                .strip_prefix("0x")
523                .unwrap_or(val)
524                .into();
525            if !digits.len().is_multiple_of(2) {
526                digits.insert(0, '0');
527            }
528            hex::decode(&digits)
529        }
530    }
531
532    #[derive(Serialize)]
533    struct CurrentBytes<'a> {
534        #[serde(with = "hex_bytes")]
535        bytes: &'a Vec<u8>,
536        #[serde(with = "hex_bytes_option")]
537        bytes_option: &'a Option<Vec<u8>>,
538        #[serde(with = "hex_bytes_vec")]
539        bytes_vec: &'a Vec<Vec<u8>>,
540    }
541
542    #[derive(Serialize)]
543    struct ReferenceBytes<'a> {
544        #[serde(serialize_with = "reference::hex_bytes")]
545        bytes: &'a Vec<u8>,
546        #[serde(serialize_with = "reference::hex_bytes_option")]
547        bytes_option: &'a Option<Vec<u8>>,
548        #[serde(serialize_with = "reference::hex_bytes_vec")]
549        bytes_vec: &'a Vec<Vec<u8>>,
550    }
551
552    #[derive(Serialize)]
553    struct CurrentMaps<'a> {
554        #[serde(with = "hex_hashmap_key")]
555        key: &'a HashMap<Bytes, Bytes>,
556        #[serde(with = "hex_hashmap_value")]
557        value: &'a HashMap<Bytes, Bytes>,
558        #[serde(with = "hex_hashmap_key_value")]
559        key_value: &'a HashMap<Bytes, Bytes>,
560    }
561
562    #[derive(Serialize)]
563    struct ReferenceMaps<'a> {
564        #[serde(serialize_with = "reference::hex_hashmap_key")]
565        key: &'a HashMap<Bytes, Bytes>,
566        #[serde(serialize_with = "reference::hex_hashmap_value")]
567        value: &'a HashMap<Bytes, Bytes>,
568        #[serde(serialize_with = "reference::hex_hashmap_key_value")]
569        key_value: &'a HashMap<Bytes, Bytes>,
570    }
571
572    /// Empty, single bytes, leading zeros, a full word, and values longer than any slot: the
573    /// largest contract code, odd lengths and 128 KiB.
574    fn hex_cases() -> Vec<Vec<u8>> {
575        let long = |len: usize| {
576            (0..len)
577                .map(|i| u8::try_from(i * 31 % 256).unwrap())
578                .collect()
579        };
580        vec![
581            vec![],
582            vec![0],
583            vec![0x0a],
584            vec![0xff],
585            vec![0, 0, 1],
586            vec![0xff; 32],
587            (0..32).collect(),
588            long(33),
589            long(24_576),
590            long(24_577),
591            long((1 << 17) + 3),
592        ]
593    }
594
595    #[test]
596    fn hex_bytes_serializers_write_the_same_json_as_formatting_each_value() {
597        let cases = hex_cases();
598        for value in &cases {
599            let option = Some(value.clone());
600            let current = CurrentBytes { bytes: value, bytes_option: &option, bytes_vec: &cases };
601            let reference =
602                ReferenceBytes { bytes: value, bytes_option: &option, bytes_vec: &cases };
603
604            assert!(
605                serde_json::to_vec(&current).unwrap() == serde_json::to_vec(&reference).unwrap(),
606                "output differs for a {}-byte value",
607                value.len()
608            );
609        }
610    }
611
612    #[test]
613    fn hex_hashmap_serializers_write_the_same_json_as_formatting_each_entry() {
614        let cases = hex_cases();
615        // Each key is a case followed by its index and a value prefix, so that keys are distinct
616        // and short and long keys sit next to short and long values.
617        let mut map = HashMap::new();
618        for (i, key) in cases.iter().enumerate() {
619            for value in &cases {
620                let mut key = key.clone();
621                key.push(u8::try_from(i).unwrap());
622                key.extend_from_slice(&value[..value.len().min(40)]);
623                map.insert(Bytes::from(key), Bytes::from(value.clone()));
624            }
625        }
626
627        let current = CurrentMaps { key: &map, value: &map, key_value: &map };
628        let reference = ReferenceMaps { key: &map, value: &map, key_value: &map };
629
630        assert!(serde_json::to_vec(&current).unwrap() == serde_json::to_vec(&reference).unwrap());
631    }
632
633    #[test]
634    fn hex_serializers_round_trip_long_values() {
635        let test_struct = TestStruct {
636            bytes: hex_cases().pop().unwrap(),
637            bytes_option: Some(vec![]),
638            bytes_vec: hex_cases(),
639        };
640
641        let serialized = serde_json::to_string(&test_struct).unwrap();
642        let deserialized: TestStruct = serde_json::from_str(&serialized).unwrap();
643
644        assert_eq!(deserialized.bytes, test_struct.bytes);
645        assert_eq!(deserialized.bytes_option, Some(vec![]));
646        assert_eq!(deserialized.bytes_vec, test_struct.bytes_vec);
647    }
648
649    /// Every case as lowercase and uppercase digits, with and without the prefix, and with an odd
650    /// number of digits where the first one is a zero.
651    fn hex_strings() -> Vec<String> {
652        let mut strings = vec![];
653        for value in hex_cases() {
654            let digits = hex::encode(&value);
655            for digits in [digits.clone(), digits.to_uppercase()] {
656                strings.push(format!("0x{digits}"));
657                strings.push(digits.clone());
658                if let Some(odd) = digits.strip_prefix('0') {
659                    strings.push(format!("0x{odd}"));
660                    strings.push(odd.to_string());
661                }
662            }
663        }
664        strings
665    }
666
667    #[test]
668    fn decode_hex_with_prefix_reads_the_same_bytes_as_the_reference_decoder() {
669        for string in hex_strings() {
670            assert_eq!(
671                decode_hex_with_prefix(&string).unwrap(),
672                reference::decode(&string).unwrap(),
673                "differs for {}",
674                &string[..string.len().min(20)]
675            );
676        }
677    }
678
679    #[test]
680    fn decode_hex_with_prefix_rejects_what_the_reference_decoder_rejects() {
681        for string in ["0xzz", "0x1g", "0xg", "g", "0x0x", "é", "0xé", "0x0é", "é0", "0x é", "0x-1"]
682        {
683            assert!(reference::decode(string).is_err(), "reference accepts {string}");
684            assert!(decode_hex_with_prefix(string).is_err(), "accepts {string}");
685        }
686    }
687
688    #[derive(Debug, PartialEq, Deserialize)]
689    struct DecodedMaps {
690        #[serde(with = "hex_hashmap_key")]
691        key: HashMap<Bytes, u64>,
692        #[serde(with = "hex_hashmap_value")]
693        value: HashMap<String, Bytes>,
694        #[serde(with = "hex_hashmap_key_value")]
695        key_value: HashMap<Bytes, Bytes>,
696    }
697
698    #[test]
699    fn hex_deserializers_read_borrowed_escaped_and_owned_strings() {
700        // "\u0030x0a" is "0x0a" with an escaped first character: the deserializer can't lend it
701        // from the input.
702        let json = r#"{
703            "key": {"0x0a": 1, "\u0030x0b": 2},
704            "value": {"a": "0x0c", "b": "\u0030x0d"},
705            "key_value": {"0x01": "0x0002", "3": "0xff", "\u0030x04": "0x"}
706        }"#;
707        let expected = DecodedMaps {
708            key: HashMap::from([(Bytes::from(vec![0x0a]), 1), (Bytes::from(vec![0x0b]), 2)]),
709            value: HashMap::from([
710                ("a".to_string(), Bytes::from(vec![0x0c])),
711                ("b".to_string(), Bytes::from(vec![0x0d])),
712            ]),
713            key_value: HashMap::from([
714                (Bytes::from(vec![0x01]), Bytes::from(vec![0x00, 0x02])),
715                (Bytes::from(vec![0x03]), Bytes::from(vec![0xff])),
716                (Bytes::from(vec![0x04]), Bytes::from(vec![])),
717            ]),
718        };
719
720        let from_str: DecodedMaps = serde_json::from_str(json).unwrap();
721        let from_reader: DecodedMaps = serde_json::from_reader(json.as_bytes()).unwrap();
722        let value: serde_json::Value = serde_json::from_str(json).unwrap();
723        let from_value: DecodedMaps = serde_json::from_value(value).unwrap();
724
725        assert_eq!(from_str, expected);
726        assert_eq!(from_reader, expected);
727        assert_eq!(from_value, expected);
728    }
729
730    #[test]
731    fn hex_deserializers_reject_invalid_hex_and_non_strings() {
732        let invalid = [
733            r#"{"key": {"0xzz": 1}, "value": {}, "key_value": {}}"#,
734            r#"{"key": {}, "value": {"a": "0x1g"}, "key_value": {}}"#,
735            r#"{"key": {}, "value": {}, "key_value": {"0x01": "é"}}"#,
736            r#"{"key": {}, "value": {"a": 1}, "key_value": {}}"#,
737        ];
738        for json in invalid {
739            assert!(serde_json::from_str::<DecodedMaps>(json).is_err(), "accepts {json}");
740        }
741        assert!(serde_json::from_str::<TestStruct>(
742            r#"{"bytes": 1, "bytes_option": null, "bytes_vec": []}"#
743        )
744        .is_err());
745    }
746}