feat: add canonical_into_vec, canonical_into_writer, canonical_value

Signed-off-by: 0xZensh <txr1883@gmail.com>

Author: zensh

ciborium/src/value/canonical.rs

@@ -2,6 +2,7 @@
 
 use crate::value::Value;
 use alloc::vec::Vec;
+use ciborium_io::Write;
 use core::cmp::Ordering;
 use serde::{de, ser};
 
@@ -122,3 +123,63 @@ impl PartialOrd for CanonicalValue {
         Some(self.cmp(other))
     }
 }
+
+/// Recursively convert a Value to its canonical form as defined in RFC 8949 "core deterministic encoding requirements".
+pub fn canonical_value(value: Value) -> Value {
+    match value {
+        Value::Map(entries) => {
+            let mut canonical_entries: Vec<(Value, Value)> = entries
+                .into_iter()
+                .map(|(k, v)| (canonical_value(k), canonical_value(v)))
+                .collect();
+
+            // Sort entries based on the canonical comparison of their keys.
+            // cmp_value (defined in this file) implements RFC 8949 key sorting.
+            canonical_entries.sort_by(|(k1, _), (k2, _)| cmp_value(k1, k2));
+
+            Value::Map(canonical_entries)
+        }
+        Value::Array(elements) => {
+            let canonical_elements: Vec<Value> =
+                elements.into_iter().map(canonical_value).collect();
+            Value::Array(canonical_elements)
+        }
+        Value::Tag(tag, inner_value) => {
+            // The tag itself is a u64; its representation is handled by the serializer.
+            // The inner value must be in canonical form.
+            Value::Tag(tag, Box::new(canonical_value(*inner_value)))
+        }
+        // Other Value variants (Integer, Bytes, Text, Bool, Null, Float)
+        // are considered "canonical" in their structure.
+        _ => value,
+    }
+}
+
+/// Serializes an object as CBOR into a writer using RFC 8949 Deterministic Encoding.
+#[inline]
+pub fn canonical_into_writer<T: ?Sized + ser::Serialize, W: Write>(
+    value: &T,
+    writer: W,
+) -> Result<(), crate::ser::Error<W::Error>>
+where
+    W::Error: core::fmt::Debug,
+{
+    let value =
+        Value::serialized(value).map_err(|err| crate::ser::Error::Value(err.to_string()))?;
+
+    let cvalue = canonical_value(value);
+    crate::into_writer(&cvalue, writer)
+}
+
+/// Serializes an object as CBOR into a new Vec<u8> using RFC 8949 Deterministic Encoding.
+#[cfg(feature = "std")]
+#[inline]
+pub fn canonical_into_vec<T: ?Sized + ser::Serialize>(
+    value: &T,
+) -> Result<Vec<u8>, crate::ser::Error<<Vec<u8> as ciborium_io::Write>::Error>> {
+    let value =
+        Value::serialized(value).map_err(|err| crate::ser::Error::Value(err.to_string()))?;
+
+    let cvalue = canonical_value(value);
+    crate::into_vec(&cvalue)
+}

ciborium/src/value/mod.rs

@@ -9,7 +9,7 @@ mod de;
 mod error;
 mod ser;
 
-pub use canonical::CanonicalValue;
+pub use canonical::{canonical_into_vec, canonical_into_writer, canonical_value, CanonicalValue};
 pub use error::Error;
 pub use integer::Integer;
 

ciborium/tests/canonical.rs

@@ -4,8 +4,9 @@ extern crate std;
 
 use ciborium::cbor;
 use ciborium::tag::Required;
-use ciborium::value::CanonicalValue;
+use ciborium::value::{canonical_into_vec, canonical_value, CanonicalValue, Value};
 use rand::prelude::*;
+use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 
 macro_rules! cval {
@@ -109,3 +110,91 @@ fn tagged_option() {
     let output = ciborium::de::from_reader(&bytes[..]).unwrap();
     assert_eq!(opt, output);
 }
+
+#[test]
+fn canonical_value_example() {
+    let map = Value::Map(vec![
+        (val!(false), val!(2)),
+        (val!([-1]), val!(5)),
+        (val!(-1), val!(1)),
+        (val!(10), val!(0)),
+        (val!(100), val!(3)),
+        (val!([100]), val!(7)),
+        (val!("z"), val!(4)),
+        (val!("aa"), val!(6)),
+    ]);
+
+    let bytes = canonical_into_vec(&map).unwrap();
+    assert_eq!(
+        hex::encode(&bytes),
+        "a80a002001f402186403617a048120056261610681186407"
+    );
+
+    let canonical = canonical_value(map);
+    let bytes = ciborium::ser::into_vec(&canonical).unwrap();
+
+    assert_eq!(
+        hex::encode(&bytes),
+        "a80a002001f402186403617a048120056261610681186407"
+    );
+}
+
+#[test]
+fn canonical_value_nested_structures() {
+    // Create nested structure with unsorted maps
+    let nested = Value::Array(vec![
+        Value::Map(vec![(val!("b"), val!(2)), (val!("a"), val!(1))]),
+        Value::Tag(
+            1,
+            Box::new(Value::Map(vec![
+                (val!(100), val!("high")),
+                (val!(10), val!("low")),
+            ])),
+        ),
+    ]);
+
+    let canonical = canonical_value(nested);
+
+    if let Value::Array(elements) = canonical {
+        // Check first map is sorted
+        if let Value::Map(entries) = &elements[0] {
+            assert_eq!(entries[0].0, val!("a"));
+            assert_eq!(entries[1].0, val!("b"));
+        }
+
+        // Check tagged map is sorted
+        if let Value::Tag(_, inner) = &elements[1] {
+            if let Value::Map(entries) = inner.as_ref() {
+                assert_eq!(entries[0].0, val!(10));
+                assert_eq!(entries[1].0, val!(100));
+            }
+        }
+    } else {
+        panic!("Expected Array value");
+    }
+}
+
+#[test]
+fn canonical_value_struct() {
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    struct T1 {
+        a: u32,
+        b: u32,
+        c: u32,
+    }
+
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    struct T2 {
+        c: u32,
+        b: u32,
+        a: u32,
+    }
+
+    let t1 = T1 { a: 1, b: 2, c: 3 };
+    let t2 = T2 { c: 3, b: 2, a: 1 };
+
+    assert_eq!(
+        canonical_into_vec(&t1).unwrap(),
+        canonical_into_vec(&t2).unwrap()
+    );
+}