feat(cat-gateway): Update filtering options for the 'v2/document/index' endpoint (#3653)

* Update filtering options for the 'v2/document/index' endpoint

* Rename 'EqOrRangedUuid' to 'UuidSelector'

* DocumentIdList and VerIdList types

* Implement PartialEq

* Return an error if Id or Ver selector lists are empty

* Bump api version

* Revert error changes

* Handle empty Id/Ver In selector

* Fix tests

---------

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

Author: stanislav-tkach

catalyst-gateway/bin/src/db/event/common/eq_or_ranged_uuid.rs

@@ -1,8 +1,8 @@
 //! `EqOrRangedUuid` query conditional stmt object.
 
-/// Search either by a singe UUID, or a Range of UUIDs
+/// Search either by a singe UUID, a range of UUIDs or a list of UUIDs.
 #[derive(Clone, Debug, PartialEq)]
-pub(crate) enum EqOrRangedUuid {
+pub(crate) enum UuidSelector {
     /// Search by the exact UUID
     Eq(uuid::Uuid),
     /// Search in this UUID's range
@@ -12,9 +12,11 @@ pub(crate) enum EqOrRangedUuid {
         /// Maximum UUID to find (inclusive)
         max: uuid::Uuid,
     },
+    /// Search UUIDs in the given list.
+    In(Vec<uuid::Uuid>),
 }
 
-impl EqOrRangedUuid {
+impl UuidSelector {
     /// Return a sql conditional statement by the provided `table_field`
     pub(crate) fn conditional_stmt(
         &self,
@@ -25,6 +27,13 @@ impl EqOrRangedUuid {
             Self::Range { min, max } => {
                 format!("{table_field} >= '{min}' AND {table_field} <= '{max}'")
             },
+            Self::In(ids) => {
+                itertools::intersperse(
+                    ids.iter().map(|id| format!("{table_field} = '{id}'")),
+                    " OR ".to_string(),
+                )
+                .collect()
+            },
         }
     }
 }

catalyst-gateway/bin/src/db/event/signed_docs/doc_ref.rs

@@ -2,15 +2,15 @@
 
 use std::fmt::Write;
 
-use crate::db::event::common::eq_or_ranged_uuid::EqOrRangedUuid;
+use crate::db::event::common::eq_or_ranged_uuid::UuidSelector;
 
 /// Document Reference filtering struct.
 #[derive(Clone, Debug)]
 pub(crate) struct DocumentRef {
     /// Document id filtering
-    pub(crate) id: Option<EqOrRangedUuid>,
+    pub(crate) id: Option<UuidSelector>,
     /// Document ver filtering
-    pub(crate) ver: Option<EqOrRangedUuid>,
+    pub(crate) ver: Option<UuidSelector>,
 }
 
 impl DocumentRef {

catalyst-gateway/bin/src/db/event/signed_docs/query_filter.rs

@@ -3,7 +3,7 @@
 use std::fmt::Display;
 
 use super::DocumentRef;
-use crate::db::event::common::eq_or_ranged_uuid::EqOrRangedUuid;
+use crate::db::event::common::eq_or_ranged_uuid::UuidSelector;
 
 /// A `select_signed_docs` query filtering argument.
 /// If all fields would be `None` the query will search for all entries from the db.
@@ -12,9 +12,9 @@ pub(crate) struct DocsQueryFilter {
     /// `type` field. Empty list if unspecified.
     doc_type: Vec<uuid::Uuid>,
     /// `id` field. `None` if unspecified.
-    id: Option<EqOrRangedUuid>,
+    id: Option<UuidSelector>,
     /// `ver` field. `None` if unspecified.
-    ver: Option<EqOrRangedUuid>,
+    ver: Option<UuidSelector>,
     /// `metadata->'ref'` field. Empty list if unspecified.
     doc_ref: Vec<DocumentRef>,
     /// `metadata->'template'` field. Empty list if unspecified.
@@ -95,7 +95,7 @@ impl DocsQueryFilter {
     /// Set the `id` field filter condition
     pub fn with_id(
         self,
-        id: EqOrRangedUuid,
+        id: UuidSelector,
     ) -> Self {
         DocsQueryFilter {
             id: Some(id),
@@ -106,7 +106,7 @@ impl DocsQueryFilter {
     /// Set the `ver` field filter condition
     pub fn with_ver(
         self,
-        ver: EqOrRangedUuid,
+        ver: UuidSelector,
     ) -> Self {
         DocsQueryFilter {
             ver: Some(ver),

catalyst-gateway/bin/src/db/event/signed_docs/tests/filter_by_field.rs

@@ -12,7 +12,7 @@ macro_rules! filter_by_field {
 
             // With id
             let filter = DocsQueryFilter::all().$with_method(DocumentRef {
-                id: Some(EqOrRangedUuid::Eq(id)),
+                id: Some(UuidSelector::Eq(id)),
                 ver: None,
             });
             let mut res_docs = SignedDocBody::retrieve(&filter, &QueryLimits::ALL)
@@ -24,7 +24,7 @@ macro_rules! filter_by_field {
             // With ver
             let filter = DocsQueryFilter::all().$with_method(DocumentRef {
                 id: None,
-                ver: Some(EqOrRangedUuid::Eq(ver)),
+                ver: Some(UuidSelector::Eq(ver)),
             });
             let mut res_docs = SignedDocBody::retrieve(&filter, &QueryLimits::ALL)
                 .await
@@ -34,8 +34,8 @@ macro_rules! filter_by_field {
 
             // With both id and ver
             let filter = DocsQueryFilter::all().$with_method(DocumentRef {
-                id: Some(EqOrRangedUuid::Eq(id)),
-                ver: Some(EqOrRangedUuid::Eq(ver)),
+                id: Some(UuidSelector::Eq(id)),
+                ver: Some(UuidSelector::Eq(ver)),
             });
             let mut res_docs = SignedDocBody::retrieve(&filter, &QueryLimits::ALL)
                 .await

catalyst-gateway/bin/src/db/event/signed_docs/tests/mod.rs

@@ -6,7 +6,7 @@ use futures::TryStreamExt;
 
 use super::*;
 use crate::db::event::{
-    common::{eq_or_ranged_uuid::EqOrRangedUuid, query_limits::QueryLimits},
+    common::{eq_or_ranged_uuid::UuidSelector, query_limits::QueryLimits},
     establish_connection_pool,
 };
 
@@ -122,15 +122,15 @@ async fn retrieve_full_signed_doc(doc: &FullSignedDoc) {
 }
 
 async fn filter_by_id(doc: &FullSignedDoc) {
-    let filter = DocsQueryFilter::all().with_id(EqOrRangedUuid::Eq(*doc.id()));
+    let filter = DocsQueryFilter::all().with_id(UuidSelector::Eq(*doc.id()));
     let mut res_docs = SignedDocBody::retrieve(&filter, &QueryLimits::ALL)
         .await
         .unwrap();
     let res_doc = res_docs.try_next().await.unwrap().unwrap();
     assert_eq!(doc.body(), &res_doc);
     assert!(res_docs.try_next().await.unwrap().is_none());
 
-    let filter = DocsQueryFilter::all().with_id(EqOrRangedUuid::Range {
+    let filter = DocsQueryFilter::all().with_id(UuidSelector::Range {
         min: *doc.id(),
         max: *doc.id(),
     });
@@ -143,15 +143,15 @@ async fn filter_by_id(doc: &FullSignedDoc) {
 }
 
 async fn filter_by_ver(doc: &FullSignedDoc) {
-    let filter = DocsQueryFilter::all().with_ver(EqOrRangedUuid::Eq(*doc.ver()));
+    let filter = DocsQueryFilter::all().with_ver(UuidSelector::Eq(*doc.ver()));
     let mut res_docs = SignedDocBody::retrieve(&filter, &QueryLimits::ALL)
         .await
         .unwrap();
     let res_doc = res_docs.try_next().await.unwrap().unwrap();
     assert_eq!(doc.body(), &res_doc);
     assert!(res_docs.try_next().await.unwrap().is_none());
 
-    let filter = DocsQueryFilter::all().with_ver(EqOrRangedUuid::Range {
+    let filter = DocsQueryFilter::all().with_ver(UuidSelector::Range {
         min: *doc.ver(),
         max: *doc.ver(),
     });
@@ -165,8 +165,8 @@ async fn filter_by_ver(doc: &FullSignedDoc) {
 
 async fn filter_by_id_and_ver(doc: &FullSignedDoc) {
     let filter = DocsQueryFilter::all()
-        .with_id(EqOrRangedUuid::Eq(*doc.id()))
-        .with_ver(EqOrRangedUuid::Eq(*doc.ver()));
+        .with_id(UuidSelector::Eq(*doc.id()))
+        .with_ver(UuidSelector::Eq(*doc.ver()));
     let mut res_docs = SignedDocBody::retrieve(&filter, &QueryLimits::ALL)
         .await
         .unwrap();

catalyst-gateway/bin/src/service/api/cardano/rbac/registrations_get/v2/key_data.rs

@@ -51,7 +51,7 @@ pub struct KeyData {
 
 impl KeyData {
     /// Creates a new `KeyData` instance.
-    pub fn new(
+    pub(crate) fn new(
         is_persistent: bool,
         time: DateTime,
         slot: SlotNo,

catalyst-gateway/bin/src/service/api/cardano/rbac/registrations_get/v2/payment_data.rs

@@ -26,7 +26,7 @@ pub struct PaymentData {
 
 impl PaymentData {
     /// Creates a new `PaymentData` instance.
-    pub fn new(
+    pub(crate) fn new(
         is_persistent: bool,
         time: DateTime,
         slot: SlotNo,

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

@@ -39,7 +39,7 @@ pub(crate) enum Responses {
     ///
     /// The Index of documents which match the query filter.
     #[oai(status = 200)]
-    Ok(Json<response::DocumentIndexListDocumentedV2>),
+    Ok(Json<DocumentIndexListDocumentedV2>),
     /// ## Not Found
     ///
     /// No documents were found which match the query filter.

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

@@ -10,8 +10,8 @@ use crate::{
     service::common::types::{
         array_types::impl_array_types,
         document::{
-            doc_type::DocumentType, id::EqOrRangedIdDocumented,
-            id_and_ver_ref::IdAndVerRefDocumented, ver::EqOrRangedVerDocumented,
+            doc_type::DocumentType, id::IdSelectorDocumented,
+            id_and_ver_ref::IdAndVerRefDocumented, ver::VerSelectorDocumented,
         },
     },
 };
@@ -38,13 +38,13 @@ pub(crate) struct DocumentIndexQueryFilterV2 {
     /// Either an absolute single Document ID or a range of
     /// [Document IDs](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#id)
     #[oai(skip_serializing_if_is_none)]
-    id: Option<EqOrRangedIdDocumentedList>,
+    id: Option<IdSelectorDocumented>,
     /// ## Document Version
     ///
     /// Either an absolute single Document Version or a range of
     /// [Document Versions](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#ver)
     #[oai(skip_serializing_if_is_none)]
-    ver: Option<EqOrRangedVerDocumentedList>,
+    ver: Option<VerSelectorDocumented>,
     /// ## Document Reference
     ///
     /// A [reference](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/meta/#ref-document-reference)
@@ -146,23 +146,6 @@ impl Example for DocumentIndexQueryFilterV2 {
     }
 }
 
-impl_array_types!(
-    EqOrRangedIdDocumentedList,
-    EqOrRangedIdDocumented,
-    Some(poem_openapi::registry::MetaSchema {
-        example: Self::example().to_json(),
-        max_items: Some(10),
-        items: Some(Box::new(EqOrRangedIdDocumented::schema_ref())),
-        ..poem_openapi::registry::MetaSchema::ANY
-    })
-);
-
-impl Example for EqOrRangedIdDocumentedList {
-    fn example() -> Self {
-        Self(vec![EqOrRangedIdDocumented::example()])
-    }
-}
-
 impl_array_types!(
     DocumentTypeList,
     DocumentType,
@@ -180,23 +163,6 @@ impl Example for DocumentTypeList {
     }
 }
 
-impl_array_types!(
-    EqOrRangedVerDocumentedList,
-    EqOrRangedVerDocumented,
-    Some(poem_openapi::registry::MetaSchema {
-        example: Self::example().to_json(),
-        max_items: Some(10),
-        items: Some(Box::new(EqOrRangedVerDocumented::schema_ref())),
-        ..poem_openapi::registry::MetaSchema::ANY
-    })
-);
-
-impl Example for EqOrRangedVerDocumentedList {
-    fn example() -> Self {
-        Self(vec![EqOrRangedVerDocumented::example()])
-    }
-}
-
 impl_array_types!(
     IdAndVerRefDocumentedList,
     IdAndVerRefDocumented,
@@ -247,26 +213,14 @@ impl TryFrom<DocumentIndexQueryFilterV2> for DocsQueryFilter {
                     .collect::<Result<Vec<_>, _>>()?,
             );
         }
-        if let Some(ids) = value.id {
-            let ids = ids
-                .0
-                .into_iter()
-                .map(TryInto::try_into)
-                .collect::<Result<Vec<_>, _>>()?;
-
-            for id in ids {
+        if let Some(id) = value.id {
+            if let Some(id) = id.try_into()? {
                 db_filter = db_filter.with_id(id);
             }
         }
-        if let Some(versions) = value.ver {
-            let versions = versions
-                .0
-                .into_iter()
-                .map(TryInto::try_into)
-                .collect::<Result<Vec<_>, _>>()?;
-
-            for ver in versions {
-                db_filter = db_filter.with_ver(ver);
+        if let Some(version) = value.ver {
+            if let Some(version) = version.try_into()? {
+                db_filter = db_filter.with_ver(version);
             }
         }
         if let Some(doc_refs) = value.doc_ref {

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

@@ -23,7 +23,7 @@ pub(crate) mod health;
 const API_TITLE: &str = "Catalyst Gateway";
 
 /// The version of the API
-const API_VERSION: &str = "0.7.0";
+const API_VERSION: &str = "0.8.0";
 
 /// Get the contact details for inquiring about the API
 fn get_api_contact() -> ContactObject {