feat(cat-gateway): Add document put endpoint

input-output-hk · Jan 7, 2025 · fd95bac · fd95bac
1 parent 6970364
commit fd95bac
Show file tree

Hide file tree

Showing 6 changed files with 113 additions and 3 deletions.
diff --git a/catalyst-gateway/bin/src/service/api/documents/get_document.rs b/catalyst-gateway/bin/src/service/api/documents/get_document.rs
@@ -1,5 +1,6 @@
-//! Implementation of the GET `/sync_state` endpoint
+//! Implementation of the GET `/document` endpoint
 
+use poem::Body;
 use poem_openapi::ApiResponse;
 
 use crate::service::common::{responses::WithErrorResponses, types::payload::cbor::Cbor};
@@ -10,7 +11,7 @@ use crate::service::common::{responses::WithErrorResponses, types::payload::cbor
 pub(crate) enum Responses {
     /// The Document that was requested.
     #[oai(status = 200)]
-    Ok(Cbor<Vec<u8>>),
+    Ok(Cbor<Body>),
     /// The document could not be found.
     #[oai(status = 404)]
     NotFound,

diff --git a/catalyst-gateway/bin/src/service/api/documents/mod.rs b/catalyst-gateway/bin/src/service/api/documents/mod.rs
@@ -1,17 +1,26 @@
 //! Signed Documents API endpoints
 
 use anyhow::anyhow;
+use poem::{error::ReadBodyError, Body};
 use poem_openapi::{
     param::{Path, Query},
+    payload::Json,
     OpenApi,
 };
+use put_document::MAXIMUM_DOCUMENT_SIZE;
 
 use crate::service::{
-    common::{auth::none_or_rbac::NoneOrRBAC, tags::ApiTags, types::generic::uuidv7::UUIDv7},
+    common::{
+        auth::{none_or_rbac::NoneOrRBAC, rbac::scheme::CatalystRBACSecurityScheme},
+        objects::document::bad_put_request::PutDocumentBadRequest,
+        tags::ApiTags,
+        types::{generic::uuidv7::UUIDv7, payload::cbor::Cbor},
+    },
     utilities::middleware::schema_validation::schema_version_validation,
 };
 
 mod get_document;
+mod put_document;
 
 /// Cardano Follower API Endpoints
 pub(crate) struct DocumentApi;
@@ -47,4 +56,32 @@ impl DocumentApi {
         };
         get_document::endpoint(doc_id, ver_id).await
     }
+
+    /// Put A Signed Document.
+    ///
+    /// This endpoint returns OK if the document is valid, able to be put by the
+    /// submitter, and if it already exists, is identical to the existing document.
+    #[oai(
+        path = "/draft/document",
+        method = "put",
+        operation_id = "putDocument",
+        transform = "schema_version_validation"
+    )]
+    async fn put_document(
+        &self, /// The document to PUT
+        document: Cbor<Body>,
+        /// Authorization required.
+        _auth: CatalystRBACSecurityScheme,
+    ) -> put_document::AllResponses {
+        match document.0.into_bytes_limit(MAXIMUM_DOCUMENT_SIZE).await {
+            Ok(document) => put_document::endpoint(document).await,
+            Err(ReadBodyError::PayloadTooLarge) => put_document::Responses::PayloadTooLarge.into(),
+            Err(_err) => {
+                put_document::Responses::BadRequest(Json(PutDocumentBadRequest::new(
+                    "Failed to read document from the request",
+                )))
+                .into()
+            },
+        }
+    }
 }
diff --git a/catalyst-gateway/bin/src/service/api/documents/put_document.rs b/catalyst-gateway/bin/src/service/api/documents/put_document.rs
@@ -0,0 +1,40 @@
+//! Implementation of the PUT `/document` endpoint
+
+use bytes::Bytes;
+use poem_openapi::{payload::Json, ApiResponse};
+
+use crate::service::common::{
+    objects::document::bad_put_request::PutDocumentBadRequest, responses::WithErrorResponses,
+};
+
+/// Maximum size of a Signed Document (1MB)
+pub(crate) const MAXIMUM_DOCUMENT_SIZE: usize = 1_048_576;
+
+/// Endpoint responses.
+#[derive(ApiResponse)]
+#[allow(dead_code)]
+pub(crate) enum Responses {
+    /// The Document was stored OK for the first time.
+    #[oai(status = 201)]
+    Created,
+    /// The Document was already stored, and has not changed.
+    #[oai(status = 204)]
+    NoContent,
+    /// Error Response
+    #[oai(status = 400)]
+    BadRequest(Json<PutDocumentBadRequest>),
+    /// Payload Too Large
+    #[oai(status = 413)]
+    PayloadTooLarge,
+}
+
+/// All responses.
+pub(crate) type AllResponses = WithErrorResponses<Responses>;
+
+/// # PUT `/document`
+#[allow(clippy::unused_async, clippy::no_effect_underscore_binding)]
+pub(crate) async fn endpoint(document: Bytes) -> AllResponses {
+    let _doc = document;
+
+    Responses::BadRequest(Json(PutDocumentBadRequest::new("unimplemented"))).into()
+}
diff --git a/catalyst-gateway/bin/src/service/common/objects/document/bad_put_request.rs b/catalyst-gateway/bin/src/service/common/objects/document/bad_put_request.rs
@@ -0,0 +1,28 @@
+//! Bad Document PUT request.
+
+use poem_openapi::{types::Example, Object};
+
+/// Configuration Data Validation Error.
+#[derive(Object, Default)]
+#[oai(example = true)]
+pub(crate) struct PutDocumentBadRequest {
+    /// Error messages.
+    #[oai(validator(max_length = "100", pattern = "^[0-9a-zA-Z].*$"))]
+    error: String,
+    // TODO: Add optional verbose error fields for documents that fail validation.
+}
+
+impl PutDocumentBadRequest {
+    /// Create a new instance of `ConfigBadRequest`.
+    pub(crate) fn new(error: &str) -> Self {
+        Self {
+            error: error.to_owned(),
+        }
+    }
+}
+
+impl Example for PutDocumentBadRequest {
+    fn example() -> Self {
+        PutDocumentBadRequest::new("Missing Document in request body")
+    }
+}
diff --git a/catalyst-gateway/bin/src/service/common/objects/document/mod.rs b/catalyst-gateway/bin/src/service/common/objects/document/mod.rs
@@ -0,0 +1,3 @@
+//! Signed Document Endpoint Objects
+
+pub(crate) mod bad_put_request;
diff --git a/catalyst-gateway/bin/src/service/common/objects/mod.rs b/catalyst-gateway/bin/src/service/common/objects/mod.rs
@@ -2,5 +2,6 @@
 
 pub(crate) mod cardano;
 pub(crate) mod config;
+pub(crate) mod document;
 pub(crate) mod generic;
 pub(crate) mod legacy;
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		//! Signed Document Endpoint Objects

		pub(crate) mod bad_put_request;