feat(cat-gateway): Add OpenAPI Examples and enforce error

catalyst-gateway/Justfile

@@ -77,5 +77,11 @@ lint-generated-schema:
 lint-generated-schema-local:
     spectral lint --ruleset "./tests/openapi-v3.0-lints/.spectral.yml" "cat-gateway-api.json"
 
+# temp
+new-lint-generated-schema-local:
+    cargo b -r
+    ./target/release/cat-gateway docs cat-gateway-api.json
+    spectral lint --ruleset "./tests/openapi-v3.0-lints/.spectral.yml" "cat-gateway-api.json"
+
 # Do the minimal work needed to test the schema generated by cat-gateway
 quick-schema-lint: generate-openapi-schema lint-generated-schema

catalyst-gateway/bin/Cargo.toml

@@ -76,7 +76,7 @@ poem-openapi = { version = "5.1.5", features = [
     "url",
     "chrono",
 ] }
-uuid = { version = "1.11.0", features = ["v4", "v7", "serde"] }
+uuid = { version = "1.12.1", features = ["v4", "v7", "serde"] }
 ulid = { version = "1.1.3", features = ["serde", "uuid"] }
 blake2b_simd = "1.0.2"
 url = "2.5.3"
@@ -99,6 +99,8 @@ mime = "0.3.17"
 stats_alloc = "0.1.10"
 memory-stats = "1.0.0"
 minicbor = "0.25.1"
+derive_more = { version = "2.0.1", default-features = false, features = ["from", "from_str", "into"] }
+orx-pseudo-default = "=1.4.0"
 
 [dev-dependencies]
 proptest = "1.5.0"

catalyst-gateway/bin/src/db/index/tests/scylla_queries.rs

@@ -65,7 +65,7 @@ async fn test_get_invalid_registration_w_stake_addr() {
 
     let mut row_stream = GetInvalidRegistrationQuery::execute(
         &session,
-        GetInvalidRegistrationParams::new(vec![], SlotNo::from(u64::MAX)),
+        GetInvalidRegistrationParams::new(vec![], SlotNo::default()),
     )
     .await
     .unwrap();

catalyst-gateway/bin/src/service/api/cardano/cip36/filter.rs

@@ -207,14 +207,14 @@ async fn get_all_registrations_from_stake_pub_key(
         };
 
         let cip36 = Cip36Details {
-            slot_no: SlotNo::from(slot_no),
+            slot_no: SlotNo::try_from(slot_no)?,
             stake_pub_key: Some(Ed25519HexEncodedPublicKey::try_from(row.stake_address)?),
             vote_pub_key: Some(Ed25519HexEncodedPublicKey::try_from(row.vote_key)?),
             nonce: Some(Nonce::from(nonce)),
             txn: Some(TxnIndex::try_from(row.txn)?),
             payment_address: Some(Cip19ShelleyAddress::try_from(row.payment_address)?),
-            is_payable: row.is_payable,
-            cip15: !row.cip36,
+            is_payable: row.is_payable.into(),
+            cip15: (!row.cip36).into(),
             errors: vec![],
         };
 
@@ -252,7 +252,7 @@ async fn get_invalid_registrations(
     let slot_no = if let Some(slot_no) = slot_no {
         slot_no
     } else {
-        SlotNo::from(0)
+        SlotNo::default()
     };
 
     let mut invalid_registrations_iter = GetInvalidRegistrationQuery::execute(
@@ -271,8 +271,8 @@ async fn get_invalid_registrations(
             nonce: None,
             txn: None,
             payment_address: Some(Cip19ShelleyAddress::try_from(row.payment_address)?),
-            is_payable: row.is_payable,
-            cip15: !row.cip36,
+            is_payable: row.is_payable.into(),
+            cip15: (!row.cip36).into(),
             errors: row
                 .error_report
                 .iter()
@@ -420,7 +420,7 @@ pub async fn snapshot(session: Arc<CassandraSession>, slot_no: Option<SlotNo>) -
 
     AllRegistration::With(Cip36Registration::Ok(poem_openapi::payload::Json(
         Cip36RegistrationList {
-            slot: slot_no.unwrap_or(SlotNo::from(0)),
+            slot: slot_no.unwrap_or_default(),
             voting_key: all_registrations_after_filtering,
             invalid: all_invalids_after_filtering.into_iter().flatten().collect(),
             page: None,

catalyst-gateway/bin/src/service/api/cardano/cip36/response.rs

@@ -48,7 +48,9 @@ pub(crate) struct Cip36RegistrationList {
 impl Example for Cip36RegistrationList {
     fn example() -> Self {
         Self {
-            slot: (common::types::cardano::slot_no::EXAMPLE + 635).into(),
+            slot: (common::types::cardano::slot_no::EXAMPLE + 635)
+                .try_into()
+                .unwrap_or_default(),
             voting_key: vec![Cip36RegistrationsForVotingPublicKey::example()],
             invalid: vec![Cip36Details::invalid_example()],
             page: Some(common::objects::generic::pagination::CurrentPage::example()),
@@ -101,11 +103,11 @@ pub(crate) struct Cip36Details {
     #[oai(skip_serializing_if_is_none)]
     pub payment_address: Option<common::types::cardano::cip19_shelley_address::Cip19ShelleyAddress>,
     /// If the payment address is a script, then it can not be payed rewards.
-    #[oai(default = "is_payable_default")]
-    pub is_payable: bool,
+    #[oai(default = "common::types::cardano::boolean::IsPayable::default")]
+    pub is_payable: common::types::cardano::boolean::IsPayable,
     /// If this field is set, then the registration was in CIP15 format.
-    #[oai(default = "cip15_default")]
-    pub cip15: bool,
+    #[oai(default = "common::types::cardano::boolean::IsCip15::default")]
+    pub cip15: common::types::cardano::boolean::IsCip15,
     /// If there are errors with this registration, they are listed here.
     /// This field is *NEVER* returned for a valid registration.
     #[oai(
@@ -116,16 +118,6 @@ pub(crate) struct Cip36Details {
     pub errors: Vec<common::types::generic::error_msg::ErrorMessage>,
 }
 
-/// Is the payment address payable by catalyst.
-fn is_payable_default() -> bool {
-    true
-}
-
-/// Is the registration using CIP15 format.
-fn cip15_default() -> bool {
-    false
-}
-
 impl Example for Cip36Details {
     /// Example of a valid registration
     fn example() -> Self {
@@ -142,8 +134,8 @@ impl Example for Cip36Details {
             payment_address: Some(
                 common::types::cardano::cip19_shelley_address::Cip19ShelleyAddress::example(),
             ),
-            is_payable: true,
-            cip15: false,
+            is_payable: common::types::cardano::boolean::IsPayable::example(),
+            cip15: common::types::cardano::boolean::IsCip15::example(),
             errors: Vec::<common::types::generic::error_msg::ErrorMessage>::new(),
         }
     }
@@ -153,16 +145,18 @@ impl Cip36Details {
     /// Example of an invalid registration
     fn invalid_example() -> Self {
         Self {
-            slot_no: (common::types::cardano::slot_no::EXAMPLE + 135).into(),
+            slot_no: (common::types::cardano::slot_no::EXAMPLE + 135)
+                .try_into()
+                .unwrap_or_default(),
             stake_pub_key: None,
             vote_pub_key: Some(
                 common::types::generic::ed25519_public_key::Ed25519HexEncodedPublicKey::example(),
             ),
             nonce: Some((common::types::cardano::nonce::EXAMPLE + 97).into()),
             txn: Some(common::types::cardano::txn_index::TxnIndex::example()),
             payment_address: None,
-            is_payable: false,
-            cip15: true,
+            is_payable: common::types::cardano::boolean::IsPayable::example(),
+            cip15: common::types::cardano::boolean::IsCip15::example(),
             errors: vec!["Stake Public Key is required".into()],
         }
     }

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

@@ -3,16 +3,18 @@ use poem_openapi::{
     param::{Path, Query},
     OpenApi,
 };
-use types::DateTime;
 
 use crate::service::{
     common::{
         auth::none_or_rbac::NoneOrRBAC,
-        objects::cardano::network::Network,
+        objects::cardano::{
+            hash::{Hash128, Hash256},
+            network::Network,
+        },
         tags::ApiTags,
         types::{
             cardano::cip19_stake_address::Cip19StakeAddress,
-            generic::ed25519_public_key::Ed25519HexEncodedPublicKey,
+            generic::{api_date_time::ApiDateTime, ed25519_public_key::Ed25519HexEncodedPublicKey},
         },
     },
     utilities::middleware::schema_validation::schema_version_validation,
@@ -44,7 +46,7 @@ impl Api {
         &self,
         /// The date-time for which the slot number should be calculated.
         /// If omitted current date time is used.
-        date_time: Query<Option<DateTime>>,
+        date_time: Query<Option<ApiDateTime>>,
         /// Cardano network type.
         /// If omitted `mainnet` network type is defined.
         /// As `preprod` and `preview` network types in the stake address encoded as a
@@ -54,7 +56,7 @@ impl Api {
         /// No Authorization required, but Token permitted.
         _auth: NoneOrRBAC,
     ) -> date_time_to_slot_number_get::AllResponses {
-        date_time_to_slot_number_get::endpoint(date_time.0, network.0).await
+        date_time_to_slot_number_get::endpoint(date_time.0.map(Into::into), network.0).await
     }
 
     #[oai(
@@ -84,14 +86,12 @@ impl Api {
     ///
     /// This endpoint returns the registrations for a given chain root.
     async fn rbac_registrations_get(
-        &self,
-        /// Chain root to get the registrations for.
-        #[oai(validator(max_length = 66, min_length = 64, pattern = "0x[0-9a-f]{64}"))]
-        Path(chain_root): Path<String>,
+        &self, /// Chain root to get the registrations for.
+        Path(chain_root): Path<Hash256>,
         /// No Authorization required, but Token permitted.
         _auth: NoneOrRBAC,
     ) -> rbac::registrations_get::AllResponses {
-        rbac::registrations_get::endpoint(chain_root).await
+        rbac::registrations_get::endpoint(chain_root.to_string()).await
     }
 
     #[oai(
@@ -103,14 +103,12 @@ impl Api {
     ///
     /// This endpoint returns the RBAC certificate chain root for a given role 0 key.
     async fn rbac_role0_key_chain_root(
-        &self,
-        /// Role0 key to get the chain root for.
-        #[oai(validator(min_length = 34, max_length = 34, pattern = "0x[0-9a-f]{32}"))]
-        Path(role0_key): Path<String>,
+        &self, /// Role0 key to get the chain root for.
+        Path(role0_key): Path<Hash128>,
         /// No Authorization required, but Token permitted.
         _auth: NoneOrRBAC,
     ) -> rbac::role0_chain_root_get::AllResponses {
-        rbac::role0_chain_root_get::endpoint(role0_key).await
+        rbac::role0_chain_root_get::endpoint(role0_key.to_string()).await
     }
 }
 

catalyst-gateway/bin/src/service/api/cardano/rbac/chain_root_get.rs

@@ -2,7 +2,7 @@
 use anyhow::anyhow;
 use der_parser::asn1_rs::ToDer;
 use futures::StreamExt;
-use poem_openapi::{payload::Json, ApiResponse, Object};
+use poem_openapi::{payload::Json, types::Example, ApiResponse, Object};
 use tracing::error;
 
 use crate::{
@@ -11,6 +11,7 @@ use crate::{
         session::CassandraSession,
     },
     service::common::{
+        objects::cardano::hash::Hash256,
         responses::WithErrorResponses,
         types::{
             cardano::cip19_stake_address::Cip19StakeAddress, headers::retry_after::RetryAfterOption,
@@ -20,10 +21,10 @@ use crate::{
 
 /// GET RBAC chain root response.
 #[derive(Object)]
-pub(crate) struct Response {
+#[oai(example = true)]
+pub(crate) struct ChainRootGetResponse {
     /// RBAC certificate chain root.
-    #[oai(validator(max_length = 66, min_length = 64, pattern = "0x[0-9a-f]{64}"))]
-    chain_root: String,
+    chain_root: Hash256,
 }
 
 /// Endpoint responses.
@@ -33,7 +34,7 @@ pub(crate) enum Responses {
     ///
     /// Success returns the chain root hash.
     #[oai(status = 200)]
-    Ok(Json<Response>),
+    Ok(Json<ChainRootGetResponse>),
     /// ## Not Found
     ///
     /// No chain root found for the given stake address.
@@ -72,8 +73,8 @@ pub(crate) async fn endpoint(stake_address: Cip19StakeAddress) -> AllResponses {
                     },
                 };
 
-                let res = Response {
-                    chain_root: format!("0x{}", hex::encode(row.chain_root)),
+                let res = ChainRootGetResponse {
+                    chain_root: Hash256::from(row.chain_root),
                 };
 
                 Responses::Ok(Json(res)).into()
@@ -88,3 +89,11 @@ pub(crate) async fn endpoint(stake_address: Cip19StakeAddress) -> AllResponses {
         },
     }
 }
+
+impl Example for ChainRootGetResponse {
+    fn example() -> Self {
+        Self {
+            chain_root: Hash256::example(),
+        }
+    }
+}

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

@@ -1,7 +1,7 @@
 //! Implementation of the GET `/rbac/registrations` endpoint.
 use anyhow::anyhow;
 use futures::StreamExt;
-use poem_openapi::{payload::Json, ApiResponse, Object};
+use poem_openapi::{payload::Json, types::Example, ApiResponse, Object};
 use tracing::error;
 
 use crate::{
@@ -12,20 +12,22 @@ use crate::{
         session::CassandraSession,
     },
     service::common::{
-        objects::cardano::hash::Hash, responses::WithErrorResponses,
+        objects::cardano::hash::Hash256, responses::WithErrorResponses,
         types::headers::retry_after::RetryAfterOption,
     },
 };
 
 /// GET RBAC registrations by chain root response list item.
 #[derive(Object)]
+#[oai(example = true)]
 pub(crate) struct RbacRegistration {
     /// Registration transaction hash.
-    tx_hash: Hash,
+    tx_hash: Hash256,
 }
 
 /// GET RBAC registrations by chain root response.
 #[derive(Object)]
+#[oai(example = true)]
 pub(crate) struct RbacRegistrationsResponse {
     /// Registrations by RBAC chain root.
     #[oai(validator(max_items = "100000"))]
@@ -99,3 +101,19 @@ pub(crate) async fn endpoint(chain_root: String) -> AllResponses {
 
     Responses::Ok(Json(RbacRegistrationsResponse { registrations })).into()
 }
+
+impl Example for RbacRegistration {
+    fn example() -> Self {
+        Self {
+            tx_hash: Hash256::example(),
+        }
+    }
+}
+
+impl Example for RbacRegistrationsResponse {
+    fn example() -> Self {
+        Self {
+            registrations: vec![RbacRegistration::example()],
+        }
+    }
+}