feat(cat-gateway): Update the response of the document/index endpoint (#3717)

* Update the response of the document/index endpoint

* Fix clippy

* Add example attribute

* Fix lint

* Try to make field optional

* Try

* try

* Expand test slightly

* Rename Catalyst ID list to CollaboratorsList

---------

Co-authored-by: Alex Pozhylenkov <[email protected]>

Author: stanislav-tkach

catalyst-gateway/bin/src/service/api/documents/mod.rs

@@ -90,7 +90,7 @@ impl DocumentApi {
         }
     }
 
-    /// Post A Signed Document Index Query for Newer Versions of v0.04.
+    /// Post A Signed Document Index Query (v2).
     ///
     /// Produces a summary of signed documents that meet the criteria
     /// defined in the request body for new signed document versions of v0.04.

catalyst-gateway/bin/src/service/api/documents/post_document_index_query/v2/response.rs

@@ -12,11 +12,10 @@ use crate::{
         self,
         types::{
             array_types::impl_array_types,
+            cardano::collaborators_list::CollaboratorsList,
             document::{
-                doc_ref_v2::{DocumentReferenceListV2, DocumentReferenceV2},
-                doc_type::DocumentType,
-                id::DocumentId,
-                ver::DocumentVer,
+                doc_chain::DocumentChainDocumented, doc_ref_v2::DocumentReferenceListV2,
+                doc_type::DocumentType, id::DocumentId, ver::DocumentVer,
             },
         },
     },
@@ -155,6 +154,8 @@ pub(crate) struct IndexedDocumentVersionV2 {
     /// Document Type that matches the filter
     #[oai(rename = "type")]
     pub doc_type: DocumentType,
+    /// A unique document identifier that matches the filter.
+    pub id: DocumentId,
     /// Document Reference that matches the filter
     #[oai(rename = "ref", skip_serializing_if_is_none)]
     pub doc_ref: Option<DocumentReferenceListV2>,
@@ -167,43 +168,31 @@ pub(crate) struct IndexedDocumentVersionV2 {
     /// Document Parameter Reference that matches the filter
     #[oai(rename = "doc_parameters", skip_serializing_if_is_none)]
     pub parameters: Option<DocumentReferenceListV2>,
+    /// A list of collaborators who can participate in drafting and submitting a document
+    /// that matches the filter.
+    #[oai(skip_serializing_if_is_none)]
+    pub collaborators: Option<CollaboratorsList>,
+    /// A link to a previous document in a chained sequence that matches the filter.
+    #[oai(skip_serializing_if_is_none)]
+    pub chain: Option<DocumentChainDocumented>,
 }
 
 impl Example for IndexedDocumentVersionV2 {
     fn example() -> Self {
         Self {
             ver: Example::example(),
             doc_type: Example::example(),
+            id: Example::example(),
             doc_ref: Some(Example::example()),
             reply: None,
             template: None,
             parameters: None,
+            collaborators: Some(Example::example()),
+            chain: Some(Example::example()),
         }
     }
 }
 
-/// Document Reference for filtered Documents.
-#[derive(NewType, Debug, Clone, From, Into)]
-#[oai(
-    from_multipart = false,
-    from_parameter = false,
-    to_header = false,
-    example = true
-)]
-pub(crate) struct FilteredDocumentReferenceV2(DocumentReferenceV2);
-
-impl From<catalyst_signed_doc::DocumentRef> for FilteredDocumentReferenceV2 {
-    fn from(value: catalyst_signed_doc::DocumentRef) -> Self {
-        Self(value.into())
-    }
-}
-
-impl Example for FilteredDocumentReferenceV2 {
-    fn example() -> Self {
-        Self(Example::example())
-    }
-}
-
 // List of Indexed Document Version Documented
 impl_array_types!(
     IndexedDocumentVersionDocumentedListV2,
@@ -256,6 +245,8 @@ impl TryFrom<SignedDocBody> for IndexedDocumentVersionDocumentedV2 {
         let mut reply = None;
         let mut template = None;
         let mut parameters = None;
+        let mut collaborators = None;
+        let mut chain = None;
         if let Some(json_meta) = doc.metadata() {
             let meta = catalyst_signed_doc::Metadata::from_json(json_meta.clone())?;
 
@@ -264,17 +255,31 @@ impl TryFrom<SignedDocBody> for IndexedDocumentVersionDocumentedV2 {
             reply = meta.reply().cloned().map(Into::into);
             template = meta.template().cloned().map(Into::into);
             parameters = meta.parameters().cloned().map(Into::into);
+            if !meta.collaborators().is_empty() {
+                collaborators = Some(
+                    meta.collaborators()
+                        .iter()
+                        .cloned()
+                        .map(Into::into)
+                        .collect::<Vec<_>>()
+                        .into(),
+                );
+            }
+            chain = meta.chain().map(Into::into);
         }
 
         if let Some(doc_type) = doc_type {
             Ok(IndexedDocumentVersionDocumentedV2(
                 IndexedDocumentVersionV2 {
                     ver: DocumentVer::new_unchecked(doc.ver().to_string()),
                     doc_type: DocumentType::new_unchecked(doc_type.to_string()),
+                    id: DocumentId::new_unchecked(doc.id().to_string()),
                     doc_ref,
                     reply,
                     template,
                     parameters,
+                    collaborators,
+                    chain,
                 },
             ))
         } else {

catalyst-gateway/bin/src/service/common/types/cardano/collaborators_list.rs

@@ -0,0 +1,27 @@
+//! Implement newtype of `RegistrationList`
+
+use poem_openapi::{
+    registry::MetaSchema,
+    types::{Example, ToJSON},
+};
+
+use crate::service::common::types::{
+    array_types::impl_array_types, cardano::catalyst_id::CatalystId,
+};
+
+impl_array_types!(
+    CollaboratorsList,
+    CatalystId,
+    Some(MetaSchema {
+        example: Self::example().to_json(),
+        max_items: Some(100),
+        items: Some(Box::new(CatalystId::schema_ref())),
+        ..MetaSchema::ANY
+    })
+);
+
+impl Example for CollaboratorsList {
+    fn example() -> Self {
+        Self(vec![Example::example()])
+    }
+}

catalyst-gateway/bin/src/service/common/types/cardano/mod.rs

@@ -6,6 +6,7 @@ pub(crate) mod asset_value;
 pub(crate) mod catalyst_id;
 pub(crate) mod cip19_shelley_address;
 pub(crate) mod cip19_stake_address;
+pub(crate) mod collaborators_list;
 pub(crate) mod hash28;
 pub(crate) mod nonce;
 pub(crate) mod query;

catalyst-gateway/bin/src/service/common/types/document/doc_chain.rs

@@ -0,0 +1,53 @@
+//! A reference to the previous signed document in a sequence.
+
+use catalyst_signed_doc::Chain;
+use poem_openapi::types::Example;
+use poem_openapi_derive::{NewType, Object};
+
+use crate::service::common::types::document::{
+    doc_height::DocumentHeight, doc_ref_v2::FilteredDocumentReferenceV2,
+};
+
+/// A reference to the previous signed document in a sequence.
+#[derive(Object, Debug, Clone)]
+#[oai(example)]
+pub struct DocumentChain {
+    /// A consecutive sequence number of the current document in the chain.
+    height: DocumentHeight,
+    /// A reference to a single signed document.
+    document_ref: Option<FilteredDocumentReferenceV2>,
+}
+
+/// A reference to the previous signed document in a sequence.
+#[derive(NewType, Debug, Clone)]
+#[oai(
+    from_multipart = false,
+    from_parameter = false,
+    to_header = false,
+    example = true
+)]
+pub(crate) struct DocumentChainDocumented(DocumentChain);
+
+impl Example for DocumentChain {
+    fn example() -> Self {
+        Self {
+            height: DocumentHeight::example(),
+            document_ref: Some(FilteredDocumentReferenceV2::example()),
+        }
+    }
+}
+
+impl From<&Chain> for DocumentChainDocumented {
+    fn from(chain: &Chain) -> Self {
+        DocumentChainDocumented(DocumentChain {
+            height: chain.height().into(),
+            document_ref: chain.document_ref().cloned().map(Into::into),
+        })
+    }
+}
+
+impl Example for DocumentChainDocumented {
+    fn example() -> Self {
+        Self(DocumentChain::example())
+    }
+}

catalyst-gateway/bin/src/service/common/types/document/doc_height.rs

@@ -0,0 +1,84 @@
+//! A consecutive sequence number of the current document in the chain.
+
+use std::sync::LazyLock;
+
+use poem_openapi::{
+    registry::{MetaSchema, MetaSchemaRef},
+    types::{Example, ParseError, ParseFromJSON, ParseResult, ToJSON, Type},
+};
+use serde_json::Value;
+
+/// A title.
+const TITLE: &str = "A document height";
+/// A description.
+const DESCRIPTION: &str = "A consecutive sequence number of the current document in the chain.";
+
+/// Schema.
+#[allow(clippy::cast_precision_loss)]
+static SCHEMA: LazyLock<MetaSchema> = LazyLock::new(|| {
+    MetaSchema {
+        title: Some(TITLE.to_owned()),
+        description: Some(DESCRIPTION),
+        example: DocumentHeight::example().to_json(),
+        maximum: Some(f64::from(i32::MAX)),
+        minimum: Some(f64::from(i32::MIN)),
+        ..MetaSchema::ANY
+    }
+});
+
+/// A consecutive sequence number of the current document in the chain.
+#[derive(Debug, Eq, PartialEq, Hash, Clone, Copy, PartialOrd, Ord, Default)]
+pub(crate) struct DocumentHeight(i32);
+
+impl Type for DocumentHeight {
+    type RawElementValueType = Self;
+    type RawValueType = Self;
+
+    const IS_REQUIRED: bool = true;
+
+    fn name() -> std::borrow::Cow<'static, str> {
+        "DocumentHeight".into()
+    }
+
+    fn schema_ref() -> MetaSchemaRef {
+        let schema_ref =
+            MetaSchemaRef::Inline(Box::new(MetaSchema::new_with_format("integer", "i32")));
+        schema_ref.merge(SCHEMA.clone())
+    }
+
+    fn as_raw_value(&self) -> Option<&Self::RawValueType> {
+        Some(self)
+    }
+
+    fn raw_element_iter<'a>(
+        &'a self
+    ) -> Box<dyn Iterator<Item = &'a Self::RawElementValueType> + 'a> {
+        Box::new(self.as_raw_value().into_iter())
+    }
+}
+
+impl From<i32> for DocumentHeight {
+    fn from(val: i32) -> Self {
+        Self(val)
+    }
+}
+
+impl Example for DocumentHeight {
+    fn example() -> Self {
+        Self(0)
+    }
+}
+
+impl ParseFromJSON for DocumentHeight {
+    fn parse_from_json(value: Option<Value>) -> ParseResult<Self> {
+        i32::parse_from_json(value)
+            .map_err(ParseError::propagate)
+            .map(Into::into)
+    }
+}
+
+impl ToJSON for DocumentHeight {
+    fn to_json(&self) -> Option<Value> {
+        Some(self.0.into())
+    }
+}

catalyst-gateway/bin/src/service/common/types/document/doc_ref_v2.rs

@@ -3,16 +3,17 @@
 //! A Reference is used by the `ref` metadata, and any other reference to another
 //! document.
 
+use derive_more::{From, Into};
 use poem_openapi::{
-    Object,
+    NewType, Object,
     types::{Example, ToJSON},
 };
 
 use super::{id::DocumentId, locator::DocumentLocator, ver::DocumentVer};
 use crate::service::common::types::array_types::impl_array_types;
 
 #[derive(Object, Debug, Clone, PartialEq)]
-#[oai(example = true)]
+#[oai(example)]
 /// A Reference to another Signed Document
 pub(crate) struct DocumentReferenceV2 {
     /// Document ID Reference
@@ -78,3 +79,25 @@ impl From<catalyst_signed_doc::DocumentRefs> for DocumentReferenceListV2 {
         Self(doc_refs)
     }
 }
+
+/// Document Reference for filtered Documents.
+#[derive(NewType, Debug, Clone, From, Into)]
+#[oai(
+    from_multipart = false,
+    from_parameter = false,
+    to_header = false,
+    example = true
+)]
+pub(crate) struct FilteredDocumentReferenceV2(DocumentReferenceV2);
+
+impl From<catalyst_signed_doc::DocumentRef> for FilteredDocumentReferenceV2 {
+    fn from(value: catalyst_signed_doc::DocumentRef) -> Self {
+        Self(value.into())
+    }
+}
+
+impl Example for FilteredDocumentReferenceV2 {
+    fn example() -> Self {
+        Self(Example::example())
+    }
+}

catalyst-gateway/bin/src/service/common/types/document/mod.rs

@@ -1,5 +1,7 @@
 //! Signed Document Types
 
+pub(crate) mod doc_chain;
+pub(crate) mod doc_height;
 pub(crate) mod doc_ref_v2;
 pub(crate) mod doc_type;
 pub(crate) mod id;

catalyst-gateway/tests/api_tests/integration/signed_doc/test_signed_doc.py

@@ -24,7 +24,12 @@ def test_document_put_and_get_endpoints(proposal_doc_factory, rbac_chain_factory
     resp = document_v2.post(filter={"id": {"eq": proposal_doc_id}})
     assert (
         resp.status_code == 200
-    ), f"Failed to post document: {resp.status_code} - {resp.text}"
+    ), f"Failed to post document (id = eq): {resp.status_code} - {resp.text}"
+
+    resp = document_v2.post(filter={"id": {"in": [proposal_doc_id]}})
+    assert (
+        resp.status_code == 200
+    ), f"Failed to post document (id = in): {resp.status_code} - {resp.text}"
 
     # Put document with different ver
     new_doc = proposal_doc.copy()