feat(client): rework write events based on forward looking learnings in #8

Signed-off-by: Raphael Höser <[email protected]>

Author: Snapstromegon

src/client.rs

@@ -20,7 +20,9 @@
 mod client_request;
 mod precondition;
 
-use client_request::{ClientRequest, PingRequest, VerifyApiTokenRequest, WriteEvents};
+use client_request::{
+    ClientRequest, OneShotRequest, PingRequest, VerifyApiTokenRequest, WriteEventsRequest,
+};
 
 pub use precondition::Precondition;
 use reqwest;
@@ -77,9 +79,14 @@ impl Client {
 
     /// Utility function to request an endpoint of the API.
     ///
+    /// This function will return a [`reqwest::RequestBuilder`] which can be used to send the request.
+    ///
     /// # Errors
     /// This function will return an error if the request fails or if the URL is invalid.
-    async fn request<R: ClientRequest>(&self, endpoint: R) -> Result<R::Response, ClientError> {
+    fn build_request<R: ClientRequest>(
+        &self,
+        endpoint: &R,
+    ) -> Result<reqwest::RequestBuilder, ClientError> {
         let url = self
             .base_url
             .join(endpoint.url_path())
@@ -98,15 +105,27 @@ impl Client {
         } else {
             request
         };
+        Ok(request)
+    }
 
-        let response = request.send().await?;
+    /// Utility function to request an endpoint of the API as a oneshot.
+    ///
+    /// This means, that the response is not streamed, but returned as a single value.
+    ///
+    /// # Errors
+    /// This function will return an error if the request fails or if the URL is invalid.
+    async fn request_oneshot<R: OneShotRequest>(
+        &self,
+        endpoint: R,
+    ) -> Result<R::Response, ClientError> {
+        let response = self.build_request(&endpoint)?.send().await?;
 
         if response.status().is_success() {
             let result = response.json().await?;
             endpoint.validate_response(&result)?;
             Ok(result)
         } else {
-            Err(ClientError::DBError(
+            Err(ClientError::DBApiError(
                 response.status(),
                 response.text().await.unwrap_or_default(),
             ))
@@ -130,7 +149,7 @@ impl Client {
     /// # Errors
     /// This function will return an error if the request fails or if the URL is invalid.
     pub async fn ping(&self) -> Result<(), ClientError> {
-        let _ = self.request(PingRequest).await?;
+        let _ = self.request_oneshot(PingRequest).await?;
         Ok(())
     }
 
@@ -151,7 +170,7 @@ impl Client {
     /// # Errors
     /// This function will return an error if the request fails or if the URL is invalid.
     pub async fn verify_api_token(&self) -> Result<(), ClientError> {
-        let _ = self.request(VerifyApiTokenRequest).await?;
+        let _ = self.request_oneshot(VerifyApiTokenRequest).await?;
         Ok(())
     }
 
@@ -186,7 +205,7 @@ impl Client {
         events: Vec<EventCandidate>,
         preconditions: Vec<Precondition>,
     ) -> Result<Vec<Event>, ClientError> {
-        self.request(WriteEvents {
+        self.request_oneshot(WriteEventsRequest {
             events,
             preconditions,
         })

src/client/client_request.rs

@@ -1,20 +1,21 @@
 //! This is a purely internal module to represent client requests to the database.
 
-use reqwest::Method;
-use serde::Serialize;
+mod ping;
+mod verify_api_token;
+mod write_events;
 
-use crate::{
-    error::ClientError,
-    event::{Event, EventCandidate, ManagementEvent},
-};
+pub use ping::PingRequest;
+pub use verify_api_token::VerifyApiTokenRequest;
+pub use write_events::WriteEventsRequest;
 
-use super::precondition::Precondition;
+use crate::error::ClientError;
+use reqwest::Method;
+use serde::{Serialize, de::DeserializeOwned};
 
 /// Represents a request to the database client
 pub trait ClientRequest {
     const URL_PATH: &'static str;
     const METHOD: Method;
-    type Response: serde::de::DeserializeOwned;
 
     /// Returns the URL path for the request
     fn url_path(&self) -> &'static str {
@@ -28,59 +29,16 @@ pub trait ClientRequest {
 
     /// Returns the body for the request
     fn body(&self) -> Option<Result<impl Serialize, ClientError>> {
-        None::<Result<(), ClientError>>
+        None::<Result<(), _>>
     }
+}
+
+/// Represents a request to the database that expects a single response
+pub trait OneShotRequest: ClientRequest {
+    type Response: DeserializeOwned;
 
     /// Validate the response from the database
     fn validate_response(&self, _response: &Self::Response) -> Result<(), ClientError> {
         Ok(())
     }
 }
-
-/// Ping the Database instance
-#[derive(Debug, Clone, Copy)]
-pub struct PingRequest;
-
-impl ClientRequest for PingRequest {
-    const URL_PATH: &'static str = "/api/v1/ping";
-    const METHOD: Method = Method::GET;
-    type Response = ManagementEvent;
-
-    fn validate_response(&self, response: &Self::Response) -> Result<(), ClientError> {
-        (response.ty() == "io.eventsourcingdb.api.ping-received")
-            .then_some(())
-            .ok_or(ClientError::PingFailed)
-    }
-}
-
-/// Verify the API token
-#[derive(Debug, Clone, Copy)]
-pub struct VerifyApiTokenRequest;
-
-impl ClientRequest for VerifyApiTokenRequest {
-    const URL_PATH: &'static str = "/api/v1/verify-api-token";
-    const METHOD: Method = Method::POST;
-    type Response = ManagementEvent;
-
-    fn validate_response(&self, response: &Self::Response) -> Result<(), ClientError> {
-        (response.ty() == "io.eventsourcingdb.api.api-token-verified")
-            .then_some(())
-            .ok_or(ClientError::APITokenInvalid)
-    }
-}
-
-#[derive(Debug, Serialize)]
-pub struct WriteEvents {
-    pub events: Vec<EventCandidate>,
-    pub preconditions: Vec<Precondition>,
-}
-
-impl ClientRequest for WriteEvents {
-    const URL_PATH: &'static str = "/api/v1/write-events";
-    const METHOD: Method = Method::POST;
-    type Response = Vec<Event>;
-
-    fn body(&self) -> Option<Result<impl Serialize, ClientError>> {
-        Some(Ok(self))
-    }
-}

src/client/client_request/ping.rs

@@ -0,0 +1,24 @@
+use reqwest::Method;
+
+use crate::{error::ClientError, event::ManagementEvent};
+
+use super::{ClientRequest, OneShotRequest};
+
+/// Ping the Database instance
+#[derive(Debug, Clone, Copy)]
+pub struct PingRequest;
+
+impl ClientRequest for PingRequest {
+    const URL_PATH: &'static str = "/api/v1/ping";
+    const METHOD: Method = Method::GET;
+}
+
+impl OneShotRequest for PingRequest {
+    type Response = ManagementEvent;
+
+    fn validate_response(&self, response: &Self::Response) -> Result<(), ClientError> {
+        (response.ty() == "io.eventsourcingdb.api.ping-received")
+            .then_some(())
+            .ok_or(ClientError::PingFailed)
+    }
+}

src/client/client_request/verify_api_token.rs

@@ -0,0 +1,24 @@
+use reqwest::Method;
+
+use crate::{error::ClientError, event::ManagementEvent};
+
+use super::{ClientRequest, OneShotRequest};
+
+/// Verify the API token
+#[derive(Debug, Clone, Copy)]
+pub struct VerifyApiTokenRequest;
+
+impl ClientRequest for VerifyApiTokenRequest {
+    const URL_PATH: &'static str = "/api/v1/verify-api-token";
+    const METHOD: Method = Method::POST;
+}
+
+impl OneShotRequest for VerifyApiTokenRequest {
+    type Response = ManagementEvent;
+
+    fn validate_response(&self, response: &Self::Response) -> Result<(), ClientError> {
+        (response.ty() == "io.eventsourcingdb.api.api-token-verified")
+            .then_some(())
+            .ok_or(ClientError::APITokenInvalid)
+    }
+}

src/client/client_request/write_events.rs

@@ -0,0 +1,26 @@
+use super::{ClientRequest, OneShotRequest};
+use crate::{
+    client::Precondition,
+    error::ClientError,
+    event::{Event, EventCandidate},
+};
+use reqwest::Method;
+use serde::Serialize;
+
+#[derive(Debug, Serialize)]
+pub struct WriteEventsRequest {
+    pub events: Vec<EventCandidate>,
+    pub preconditions: Vec<Precondition>,
+}
+
+impl ClientRequest for WriteEventsRequest {
+    const URL_PATH: &'static str = "/api/v1/write-events";
+    const METHOD: Method = Method::POST;
+
+    fn body(&self) -> Option<Result<impl Serialize, ClientError>> {
+        Some(Ok(self))
+    }
+}
+impl OneShotRequest for WriteEventsRequest {
+    type Response = Vec<Event>;
+}

src/error.rs

@@ -26,7 +26,7 @@ pub enum ClientError {
     SerdeJsonError(#[from] serde_json::Error),
     /// The DB returned an error+
     #[error("The DB returned an error: {0}")]
-    DBError(StatusCode, String),
+    DBApiError(StatusCode, String),
     /// There was a problem with the `cloudevents` message
     #[cfg(feature = "cloudevents")]
     #[error("The CloudEvents message is invalid: {0}")]