Merge branch 'main' into metadata-and-discovery

Author: Snapstromegon

Cargo.lock

@@ -25,6 +25,7 @@ tokio-util = { version = "0.7.15", features = ["io"] }
 tokio-stream = { version = "0.1.17", features = ["io-util"] }
 futures = "0.3.31"
 tokio = { version = "1.44.2", features = ["io-util"] }
+typed-builder = "0.21.0"
 
 [dev-dependencies]
 eventsourcingdb-client-rust = { path = ".", features = ["testcontainer"] }

Cargo.toml

@@ -8,7 +8,7 @@ This is a work in progress and not yet ready for production use.
 Based on the [compliance criteria](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/) the SDK covers these criteria:
 
 - 🚀 [Essentials](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/#essentials)
-- ❌ [Writing Events](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/#writing-events)
+- 🚀 [Writing Events](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/#writing-events)
 - ❌ [Reading Events](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/#reading-events)
 - ❌ [Using EventQL](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/#using-eventql)
 - ❌ [Observing Events](https://docs.eventsourcingdb.io/client-sdks/compliance-criteria/#observing-events)

README.md

@@ -18,18 +18,23 @@
 //! If this works, it means that the client is correctly configured and you can use it to make requests to the DB.
 
 mod client_request;
+mod precondition;
 
 use client_request::{
     ClientRequest, ListEventTypesRequest, ListSubjectsRequest, OneShotRequest, PingRequest,
-    RegisterEventSchemaRequest, StreamingRequest, VerifyApiTokenRequest,
+    RegisterEventSchemaRequest, StreamingRequest, VerifyApiTokenRequest, WriteEventsRequest,
     list_event_types::EventType,
 };
 
 use futures::Stream;
+pub use precondition::Precondition;
 use reqwest;
 use url::Url;
 
-use crate::{error::ClientError, event::ManagementEvent};
+use crate::{
+    error::ClientError,
+    event::{Event, EventCandidate, ManagementEvent},
+};
 
 /// Client for an [EventsourcingDB](https://www.eventsourcingdb.io/) instance.
 #[derive(Debug)]
@@ -79,6 +84,8 @@ impl Client {
     ///
     /// This function will return a [`reqwest::RequestBuilder`] which can be used to send the request.
     ///
+    /// 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.
     fn build_request<R: ClientRequest>(
@@ -233,4 +240,42 @@ impl Client {
         let response = self.request_streaming(ListEventTypesRequest).await?;
         Ok(response)
     }
+
+    /// Writes events to the DB instance.
+    ///
+    /// ```
+    /// use eventsourcingdb_client_rust::event::EventCandidate;
+    /// # use serde_json::json;
+    /// # tokio_test::block_on(async {
+    /// # let container = eventsourcingdb_client_rust::container::Container::start_default().await.unwrap();
+    /// let db_url = "http://localhost:3000/";
+    /// let api_token = "secrettoken";
+    /// # let db_url = container.get_base_url().await.unwrap();
+    /// # let api_token = container.get_api_token();
+    /// let client = eventsourcingdb_client_rust::client::Client::new(db_url, api_token);
+    /// let candidates = vec![
+    ///     EventCandidate::builder()
+    ///        .source("https://www.eventsourcingdb.io".to_string())
+    ///        .data(json!({"value": 1}))
+    ///        .subject("/test".to_string())
+    ///        .r#type("io.eventsourcingdb.test".to_string())
+    ///        .build()
+    /// ];
+    /// let written_events = client.write_events(candidates, vec![]).await.expect("Failed to write events");
+    /// # })
+    /// ```
+    ///
+    /// # Errors
+    /// This function will return an error if the request fails or if the URL is invalid.
+    pub async fn write_events(
+        &self,
+        events: Vec<EventCandidate>,
+        preconditions: Vec<Precondition>,
+    ) -> Result<Vec<Event>, ClientError> {
+        self.request_oneshot(WriteEventsRequest {
+            events,
+            preconditions,
+        })
+        .await
+    }
 }

src/client.rs

@@ -5,12 +5,14 @@ mod list_subjects;
 mod ping;
 mod register_event_schema;
 mod verify_api_token;
+mod write_events;
 
 pub use list_event_types::ListEventTypesRequest;
 pub use list_subjects::ListSubjectsRequest;
 pub use ping::PingRequest;
 pub use register_event_schema::RegisterEventSchemaRequest;
 pub use verify_api_token::VerifyApiTokenRequest;
+pub use write_events::WriteEventsRequest;
 
 use crate::error::ClientError;
 use futures::{Stream, stream::TryStreamExt};

src/client/client_request.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/client/client_request/write_events.rs

@@ -0,0 +1,22 @@
+use serde::Serialize;
+
+/// Enum for different preconditions that can be used when writing events
+#[derive(Debug, Serialize)]
+#[serde(tag = "type", content = "payload")]
+pub enum Precondition {
+    /// Check if the subject with the given path has no other events
+    #[serde(rename = "isSubjectPristine")]
+    IsSubjectPristine {
+        /// The subject to check
+        subject: String,
+    },
+    /// Check if the subject with the given path has no other events
+    #[serde(rename = "isSubjectOnEventId")]
+    IsSubjectOnEventId {
+        /// The subject to check
+        subject: String,
+        /// The event ID to check against
+        #[serde(rename = "eventId")]
+        event_id: String,
+    },
+}

src/client/precondition.rs

@@ -30,12 +30,12 @@ pub enum ClientError {
     /// There was a problem with the JSON serialization
     #[error("The JSON serialization failed: {0}")]
     SerdeJsonError(#[from] serde_json::Error),
-    /// The DB returned an error
-    #[error("The DB returned an error: {0}")]
-    DBApiError(StatusCode, String),
     /// The DB returned an error in the response
     #[error("The DB returned an error in the response: {0}")]
     DBError(String),
+    /// The DB returned an error
+    #[error("The DB returned an error: {0}")]
+    DBApiError(StatusCode, String),
     // check if this can hold a validation error in the future
     /// The passed jsonschema is invalid
     #[error("The passed jsonschema is invalid")]
@@ -59,3 +59,12 @@ pub enum ContainerError {
     #[error("URL parsing error: {0}")]
     URLParseError(#[from] url::ParseError),
 }
+
+/// Error type for the event
+#[derive(Debug, thiserror::Error)]
+pub enum EventError {
+    /// The passed cloudevent is invalid
+    #[cfg(feature = "cloudevents")]
+    #[error("The passed cloudevent is invalid")]
+    InvalidCloudevent,
+}

src/error.rs

@@ -1,5 +1,14 @@
 //! This module holds all event types that are send between the client and the database.
 
-mod management_event;
+mod event_types;
+mod trace_info;
 
-pub use management_event::ManagementEvent;
+// Reexport relevant types to flatten the module graph for consumers and
+// keep private encapsulation of implementation details.
+pub use event_types::event::Event;
+pub use event_types::event_candidate::EventCandidate;
+pub use event_types::management_event::ManagementEvent;
+pub use trace_info::TraceInfo;
+
+#[cfg(feature="cloudevents")]
+use crate::error::EventError;

src/event.rs

@@ -0,0 +1,5 @@
+//! This module holds all possible event types this sdk works with.
+
+pub mod event;
+pub mod event_candidate;
+pub mod management_event;