feat(rust/signed-doc): add new type DocType

rust/signed_doc/Cargo.toml

@@ -27,7 +27,8 @@ jsonschema = "0.28.3"
 jsonpath-rust = "0.7.5"
 futures = "0.3.31"
 ed25519-bip32 = "0.4.1" # used by the `mk_signed_doc` cli tool
-
+tracing = "0.1.40"
+thiserror = "2.0.11"
 
 [dev-dependencies]
 base64-url = "3.0.0"

rust/signed_doc/src/decode_context.rs

@@ -0,0 +1,24 @@
+//! Context used to pass in decoder for additional information.
+
+use catalyst_types::problem_report::ProblemReport;
+
+/// Compatibility policy
+#[allow(dead_code)]
+pub(crate) enum CompatibilityPolicy {
+    /// Silently allow obsoleted type conversions or non deterministic encoding.
+    Accept,
+    /// Allow but log Warnings for all obsoleted type conversions or non deterministic
+    /// encoding.
+    Warn,
+    /// Fail and update problem report when an obsolete type is encountered or the data is
+    /// not deterministically encoded.
+    Fail,
+}
+
+/// A context use to pass to decoder.
+pub(crate) struct DecodeContext<'r> {
+    /// Compatibility policy.
+    pub compatibility_policy: CompatibilityPolicy,
+    /// Problem report.
+    pub report: &'r mut ProblemReport,
+}

rust/signed_doc/src/doc_types/mod.rs

@@ -51,3 +51,5 @@ pub const PRIVATE_VOTE_TX_V2_UUID_TYPE: Uuid =
 /// Immutable ledger block `UuidV4` type.
 pub const IMMUTABLE_LEDGER_BLOCK_UUID_TYPE: Uuid =
     Uuid::from_u128(0xD9E7_E6CE_2401_4D7D_9492_F4F7_C642_41C3);
+/// Submission Action `UuidV4` type.
+pub const SUBMISSION_ACTION: Uuid = Uuid::from_u128(0x7892_7329_CFD9_4EA1_9C71_0E01_9B12_6A65);

rust/signed_doc/src/lib.rs

@@ -2,6 +2,7 @@
 
 mod builder;
 mod content;
+mod decode_context;
 pub mod doc_types;
 mod metadata;
 pub mod providers;
@@ -22,7 +23,9 @@ pub use catalyst_types::{
 };
 pub use content::Content;
 use coset::{CborSerializable, Header, TaggedCborSerializable};
-pub use metadata::{ContentEncoding, ContentType, DocumentRef, ExtraFields, Metadata, Section};
+pub use metadata::{
+    ContentEncoding, ContentType, DocType, DocumentRef, ExtraFields, Metadata, Section,
+};
 use minicbor::{decode, encode, Decode, Decoder, Encode};
 pub use signature::{CatalystId, Signatures};
 

rust/signed_doc/src/metadata/doc_type.rs

@@ -0,0 +1,333 @@
+//! Document Type.
+
+use std::fmt::{Display, Formatter};
+
+use catalyst_types::{
+    problem_report::ProblemReport,
+    uuid::{CborContext, Uuid, UuidV4},
+};
+use minicbor::{Decode, Decoder, Encode};
+use tracing::warn;
+
+use crate::{
+    decode_context::{CompatibilityPolicy, DecodeContext},
+    doc_types::{
+        COMMENT_DOCUMENT_UUID_TYPE, PROPOSAL_ACTION_DOCUMENT_UUID_TYPE,
+        PROPOSAL_DOCUMENT_UUID_TYPE, SUBMISSION_ACTION,
+    },
+};
+
+/// List of `UUIDv4` document type.
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct DocType(Vec<UuidV4>);
+
+/// `DocType` Errors.
+#[derive(Debug, Clone, thiserror::Error)]
+pub enum DocTypeError {
+    /// Invalid UUID.
+    #[error("Invalid UUID: {0}")]
+    InvalidUuid(Uuid),
+    /// `DocType` cannot be empty.
+    #[error("DocType cannot be empty")]
+    Empty,
+}
+
+impl DocType {
+    /// Get a list of `UUIDv4` document types.
+    #[must_use]
+    pub fn doc_types(&self) -> &Vec<UuidV4> {
+        &self.0
+    }
+}
+
+impl From<UuidV4> for DocType {
+    fn from(value: UuidV4) -> Self {
+        DocType(vec![value])
+    }
+}
+
+impl TryFrom<Uuid> for DocType {
+    type Error = DocTypeError;
+
+    fn try_from(value: Uuid) -> Result<Self, Self::Error> {
+        let uuid_v4 = UuidV4::try_from(value).map_err(|_| DocTypeError::InvalidUuid(value))?;
+        Ok(DocType(vec![uuid_v4]))
+    }
+}
+
+impl TryFrom<Vec<Uuid>> for DocType {
+    type Error = DocTypeError;
+
+    fn try_from(value: Vec<Uuid>) -> Result<Self, Self::Error> {
+        if value.is_empty() {
+            return Err(DocTypeError::Empty);
+        }
+
+        let converted = value
+            .into_iter()
+            .map(|u| UuidV4::try_from(u).map_err(|_| DocTypeError::InvalidUuid(u)))
+            .collect::<Result<Vec<UuidV4>, DocTypeError>>()?;
+
+        DocType::try_from(converted)
+    }
+}
+
+impl TryFrom<Vec<UuidV4>> for DocType {
+    type Error = DocTypeError;
+
+    fn try_from(value: Vec<UuidV4>) -> Result<Self, Self::Error> {
+        if value.is_empty() {
+            return Err(DocTypeError::Empty);
+        }
+        Ok(DocType(value))
+    }
+}
+
+impl Display for DocType {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(
+            f,
+            "[{}]",
+            self.0
+                .iter()
+                .map(UuidV4::to_string)
+                .collect::<Vec<_>>()
+                .join(", ")
+        )
+    }
+}
+
+// ; Document Type
+// document_type = [ 1* uuid_v4 ]
+// ; UUIDv4
+// uuid_v4 = #6.37(bytes .size 16)
+impl Decode<'_, DecodeContext<'_>> for DocType {
+    fn decode(
+        d: &mut Decoder, decode_context: &mut DecodeContext,
+    ) -> Result<Self, minicbor::decode::Error> {
+        const CONTEXT: &str = "DocType decoding";
+        let parse_uuid = |d: &mut Decoder| UuidV4::decode(d, &mut CborContext::Tagged);
+
+        match d.datatype()? {
+            minicbor::data::Type::Array => {
+                let len = d.array()?.ok_or_else(|| {
+                    decode_context
+                        .report
+                        .other("Unable to decode array length", CONTEXT);
+                    minicbor::decode::Error::message(format!(
+                        "{CONTEXT}: Unable to decode array length"
+                    ))
+                })?;
+
+                if len == 0 {
+                    decode_context.report.invalid_value(
+                        "array length",
+                        "0",
+                        "must contain at least one UUIDv4",
+                        CONTEXT,
+                    );
+                    return Err(minicbor::decode::Error::message(format!(
+                        "{CONTEXT}: empty array"
+                    )));
+                }
+
+                (0..len)
+                    .map(|_| parse_uuid(d))
+                    .collect::<Result<Vec<_>, _>>()
+                    .map(Self)
+                    .map_err(|e| {
+                        decode_context
+                            .report
+                            .other(&format!("Invalid UUIDv4 in array: {e}"), CONTEXT);
+                        minicbor::decode::Error::message(format!(
+                            "{CONTEXT}: Invalid UUIDv4 in array: {e}"
+                        ))
+                    })
+            },
+            minicbor::data::Type::Tag => {
+                // Handle single tagged UUID
+                match decode_context.compatibility_policy {
+                    CompatibilityPolicy::Accept | CompatibilityPolicy::Warn => {
+                        if matches!(
+                            decode_context.compatibility_policy,
+                            CompatibilityPolicy::Warn
+                        ) {
+                            warn!("{CONTEXT}: Conversion of document type single UUID to type DocType");
+                        }
+
+                        let uuid = parse_uuid(d).map_err(|e| {
+                            let msg = format!("Cannot decode single UUIDv4: {e}");
+                            decode_context.report.invalid_value(
+                                "Decode single UUIDv4",
+                                &e.to_string(),
+                                &msg,
+                                CONTEXT,
+                            );
+                            minicbor::decode::Error::message(format!("{CONTEXT}: {msg}"))
+                        })?;
+
+                        let ids = map_doc_type(uuid.into()).map_err(|e| {
+                            decode_context.report.other(&e.to_string(), CONTEXT);
+                            minicbor::decode::Error::message(format!("{CONTEXT}: {e}"))
+                        })?;
+
+                        let doc_type = ids.to_vec().try_into().map_err(|e: DocTypeError| {
+                            decode_context.report.other(&e.to_string(), CONTEXT);
+                            minicbor::decode::Error::message(format!("{CONTEXT}: {e}"))
+                        })?;
+
+                        Ok(doc_type)
+                    },
+
+                    CompatibilityPolicy::Fail => {
+                        let msg = "Conversion of document type single UUID to type DocType is not allowed";
+                        decode_context.report.other(msg, CONTEXT);
+                        Err(minicbor::decode::Error::message(format!(
+                            "{CONTEXT}: {msg}"
+                        )))
+                    },
+                }
+            },
+            other => {
+                decode_context.report.invalid_value(
+                    "decoding type",
+                    &format!("{other:?}"),
+                    "array or tag cbor",
+                    CONTEXT,
+                );
+                Err(minicbor::decode::Error::message(format!(
+                    "{CONTEXT}: expected array of UUIDor tagged UUIDv4, got {other:?}",
+                )))
+            },
+        }
+    }
+}
+
+/// Map single UUID doc type to new list of doc types
+/// <https://github.com/input-output-hk/catalyst-libs/blob/main/docs/src/architecture/08_concepts/signed_doc/types.md#document-types>
+fn map_doc_type(uuid: Uuid) -> anyhow::Result<&'static [Uuid]> {
+    const PROPOSAL_DOC: &[Uuid] = &[PROPOSAL_DOCUMENT_UUID_TYPE];
+    const PROPOSAL_COMMENT_DOC: &[Uuid] =
+        &[COMMENT_DOCUMENT_UUID_TYPE, PROPOSAL_DOCUMENT_UUID_TYPE];
+    const PROPOSAL_ACTION_DOC: &[Uuid] = &[
+        PROPOSAL_ACTION_DOCUMENT_UUID_TYPE,
+        PROPOSAL_DOCUMENT_UUID_TYPE,
+        SUBMISSION_ACTION,
+    ];
+
+    match uuid {
+        id if id == PROPOSAL_DOCUMENT_UUID_TYPE => Ok(PROPOSAL_DOC),
+        id if id == COMMENT_DOCUMENT_UUID_TYPE => Ok(PROPOSAL_COMMENT_DOC),
+        id if id == PROPOSAL_ACTION_DOCUMENT_UUID_TYPE => Ok(PROPOSAL_ACTION_DOC),
+        _ => anyhow::bail!("Unknown document type: {uuid}"),
+    }
+}
+
+impl Encode<ProblemReport> for DocType {
+    fn encode<W: minicbor::encode::Write>(
+        &self, e: &mut minicbor::Encoder<W>, report: &mut ProblemReport,
+    ) -> Result<(), minicbor::encode::Error<W::Error>> {
+        const CONTEXT: &str = "DocType encoding";
+        if self.0.is_empty() {
+            report.invalid_value("DocType", "empty", "DocType cannot be empty", CONTEXT);
+            return Err(minicbor::encode::Error::message(format!(
+                "{CONTEXT}: DocType cannot be empty"
+            )));
+        }
+
+        e.array(self.0.len().try_into().map_err(|_| {
+            report.other("Unable to encode array length", CONTEXT);
+            minicbor::encode::Error::message(format!("{CONTEXT}, unable to encode array length"))
+        })?)?;
+
+        for id in &self.0 {
+            id.encode(e, &mut CborContext::Tagged).map_err(|_| {
+                report.other("Failed to encode UUIDv4", CONTEXT);
+                minicbor::encode::Error::message(format!("{CONTEXT}: UUIDv4 encoding failed"))
+            })?;
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+
+    use minicbor::Encoder;
+
+    use super::*;
+
+    // <https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/>
+    // Proposal Submission Action = 37(h'5e60e623ad024a1ba1ac406db978ee48') should map to
+    // [37(h'5e60e623ad024a1ba1ac406db978ee48'), 37(h'7808d2bad51140af84e8c0d1625fdfdc'),
+    // 37(h'78927329cfd94ea19c710e019b126a65')]
+    const PSA: &str = "D825505E60E623AD024A1BA1AC406DB978EE48";
+
+    #[test]
+    fn test_empty_doc_type() {
+        assert!(<DocType as TryFrom<Vec<UuidV4>>>::try_from(vec![]).is_err());
+
+        let mut report = ProblemReport::new("Test empty doc type");
+        let mut decoded_context = DecodeContext {
+            compatibility_policy: CompatibilityPolicy::Accept,
+            report: &mut report,
+        };
+        let mut decoder = Decoder::new(&[]);
+        assert!(DocType::decode(&mut decoder, &mut decoded_context).is_err());
+    }
+
+    #[test]
+    fn test_single_uuid_doc_type_fail_policy() {
+        let mut report = ProblemReport::new("Test single uuid doc type - fail");
+        let data = hex::decode(PSA).unwrap();
+        let decoder = Decoder::new(&data);
+        let mut decoded_context = DecodeContext {
+            compatibility_policy: CompatibilityPolicy::Fail,
+            report: &mut report,
+        };
+        assert!(DocType::decode(&mut decoder.clone(), &mut decoded_context).is_err());
+    }
+
+    #[test]
+    fn test_single_uuid_doc_type_warn_policy() {
+        let mut report = ProblemReport::new("Test single uuid doc type - warn");
+        let data = hex::decode(PSA).unwrap();
+        let decoder = Decoder::new(&data);
+        let mut decoded_context = DecodeContext {
+            compatibility_policy: CompatibilityPolicy::Warn,
+            report: &mut report,
+        };
+        let decoded_doc_type = DocType::decode(&mut decoder.clone(), &mut decoded_context).unwrap();
+        assert_eq!(decoded_doc_type.doc_types().len(), 3);
+    }
+
+    #[test]
+    fn test_single_uuid_doc_type_accept_policy() {
+        let mut report = ProblemReport::new("Test single uuid doc type - accept");
+        let data = hex::decode(PSA).unwrap();
+        let decoder = Decoder::new(&data);
+        let mut decoded_context = DecodeContext {
+            compatibility_policy: CompatibilityPolicy::Accept,
+            report: &mut report,
+        };
+        let decoded_doc_type = DocType::decode(&mut decoder.clone(), &mut decoded_context).unwrap();
+        assert_eq!(decoded_doc_type.doc_types().len(), 3);
+    }
+
+    #[test]
+    fn test_multi_uuid_doc_type() {
+        let uuidv4 = UuidV4::new();
+        let mut report = ProblemReport::new("Test multi uuid doc type");
+        let doc_type_list: DocType = vec![uuidv4, uuidv4].try_into().unwrap();
+        let mut buffer = Vec::new();
+        let mut encoder = Encoder::new(&mut buffer);
+        doc_type_list.encode(&mut encoder, &mut report).unwrap();
+        let mut decoder = Decoder::new(&buffer);
+        let mut decoded_context = DecodeContext {
+            compatibility_policy: CompatibilityPolicy::Accept,
+            report: &mut report.clone(),
+        };
+        let decoded_doc_type = DocType::decode(&mut decoder, &mut decoded_context).unwrap();
+        assert_eq!(decoded_doc_type, doc_type_list);
+    }
+}