Merge pull request #49 from EventStore/snippets

API structure and naming alignment with other clients.

Author: YoEight

Cargo.toml

@@ -42,13 +42,34 @@ webpki = "0.21"
 base64 = "0.13"
 nom = "6"
 thiserror = "1"
+async-trait = "0.1"
 
 [build-dependencies]
 tonic-build = { version = "0.4", features = ["prost"] }
 
 [[test]]
 name = "integration"
 
+[[example]]
+name = "appending_events"
+crate-type = ["staticlib"]
+
+[[example]]
+name = "quickstart"
+crate-type = ["staticlib"]
+
+[[example]]
+name = "reading_events"
+crate-type = ["staticlib"]
+
+[[example]]
+name = "server_side_filtering"
+crate-type = ["staticlib"]
+
+[[example]]
+name = "subscribing_to_stream"
+crate-type = ["staticlib"]
+
 [dev-dependencies]
 serde = { version = "1.0", features = ["derive"] }
 pretty_env_logger = "0.4"

docker-compose.yml

@@ -27,7 +27,7 @@ services:
       - volumes-provisioner
 
   node1.eventstore: &template
-    image: eventstore/eventstore:20.6.1-buster-slim
+    image: eventstore/eventstore:20.10.0-buster-slim
     container_name: node1.eventstore
     env_file:
       - vars.env

examples/appending_events.rs

@@ -0,0 +1,154 @@
+use eventstore::{
+    AppendToStreamOptions, Client, Credentials, EventData, ExpectedRevision, ReadStreamOptions,
+    Single, StreamPosition,
+};
+use futures::TryStreamExt;
+use serde::{Deserialize, Serialize};
+use std::error::Error;
+use uuid::Uuid;
+
+#[derive(Serialize, Deserialize)]
+struct TestEvent {
+    pub id: String,
+    pub important_data: String,
+}
+
+type Result<A> = std::result::Result<A, Box<dyn Error>>;
+
+pub async fn append_to_stream(client: &Client) -> Result<()> {
+    // region append-to-stream
+
+    let data = TestEvent {
+        id: "1".to_string(),
+        important_data: "some value".to_string(),
+    };
+
+    let event = EventData::json("some-event", &data)?.id(Uuid::new_v4());
+    let options = AppendToStreamOptions::default().expected_revision(ExpectedRevision::NoStream);
+
+    let _ = client
+        .append_to_stream("some-stream", &options, event)
+        .await?;
+
+    // endregion append-to-stream
+
+    Ok(())
+}
+
+pub async fn append_with_same_id(client: &Client) -> Result<()> {
+    // region append-duplicate-event
+
+    let data = TestEvent {
+        id: "1".to_string(),
+        important_data: "some value".to_string(),
+    };
+
+    let event = EventData::json("some-event", &data)?.id(Uuid::new_v4());
+    let options = AppendToStreamOptions::default();
+
+    let _ = client
+        .append_to_stream("same-event-stream", &options, event.clone())
+        .await?;
+
+    let _ = client
+        .append_to_stream("same-event-stream", &options, event)
+        .await?;
+
+    // endregion append-duplicate-event
+
+    Ok(())
+}
+
+pub async fn append_with_no_stream(client: &Client) -> Result<()> {
+    // region append-with-no-stream
+
+    let data = TestEvent {
+        id: "1".to_string(),
+        important_data: "some value".to_string(),
+    };
+
+    let event = EventData::json("some-event", &data)?.id(Uuid::new_v4());
+    let options = AppendToStreamOptions::default().expected_revision(ExpectedRevision::NoStream);
+
+    let _ = client
+        .append_to_stream("same-event-stream", &options, event)
+        .await?;
+
+    let data = TestEvent {
+        id: "2".to_string(),
+        important_data: "some other value".to_string(),
+    };
+
+    let event = EventData::json("some-event", &data)?.id(Uuid::new_v4());
+
+    let _ = client
+        .append_to_stream("same-event-stream", &options, event)
+        .await?;
+
+    // endregion append-with-no-stream
+
+    Ok(())
+}
+
+pub async fn append_with_concurrency_check(client: Client) -> Result<()> {
+    // region append-with-concurrency-check
+
+    let options = ReadStreamOptions::default().position(StreamPosition::End);
+
+    let last_event = client
+        .read_stream("concurrency-stream", &options, Single)
+        .await?
+        .ok()
+        .expect("we expect the stream to at least exist.")
+        .expect("we expect the stream to have at least one event.");
+
+    let data = TestEvent {
+        id: "1".to_string(),
+        important_data: "clientOne".to_string(),
+    };
+
+    let event = EventData::json("some-event", data)?.id(Uuid::new_v4());
+    let options = AppendToStreamOptions::default().expected_revision(ExpectedRevision::Exact(
+        last_event.get_original_event().revision,
+    ));
+
+    let _ = client
+        .append_to_stream("concurrency-stream", &options, event)
+        .await?;
+
+    let data = TestEvent {
+        id: "2".to_string(),
+        important_data: "clientTwo".to_string(),
+    };
+
+    let event = EventData::json("some-event", &data)?.id(Uuid::new_v4());
+
+    let _ = client
+        .append_to_stream("concurrency-stream", &options, event)
+        .await?;
+
+    // endregion append-with-concurrency-check
+
+    Ok(())
+}
+
+pub async fn append_overriding_user_credentials(client: &Client) -> Result<()> {
+    let data = TestEvent {
+        id: "1".to_string(),
+        important_data: "clientOne".to_string(),
+    };
+
+    let event = EventData::json("some-event", data)?.id(Uuid::new_v4());
+
+    // region overriding-user-credentials
+    let options =
+        AppendToStreamOptions::default().authenticated(Credentials::new("admin", "changeit"));
+
+    let _ = client
+        .append_to_stream("some-stream", &options, event)
+        .await?;
+
+    // endregion overriding-user-credentials
+
+    Ok(())
+}

examples/quickstart.rs

@@ -0,0 +1,62 @@
+use eventstore::{
+    AppendToStreamOptions, Client, Credentials, EventData, ExpectedRevision, ReadResult,
+    ReadStreamOptions,
+};
+use futures::TryStreamExt;
+use serde::{Deserialize, Serialize};
+use std::error::Error;
+use uuid::Uuid;
+
+#[derive(Serialize, Deserialize)]
+struct TestEvent {
+    pub id: String,
+    pub important_data: String,
+}
+
+type Result<A> = std::result::Result<A, Box<dyn Error>>;
+
+pub async fn run() -> Result<()> {
+    // region createClient
+    let settings = "{connectionString}".parse()?;
+    let client = Client::create(settings).await?;
+    // endregion createClient
+
+    // region createEvent
+    let event = TestEvent {
+        id: Uuid::new_v4().to_string(),
+        important_data: "I wrote my first event!".to_string(),
+    };
+
+    let event_data = EventData::json("TestEvent", event)?.id(Uuid::new_v4());
+    // endregion createEvent
+
+    let main_event_data = event_data.clone();
+
+    // region appendEvents
+    client
+        .append_to_stream("some-stream", &Default::default(), event_data)
+        .await?;
+    // endregion appendEvents
+
+    let event_data = main_event_data.clone();
+    let options =
+        AppendToStreamOptions::default().authenticated(Credentials::new("admin", "changeit"));
+
+    // region overriding-user-credentials
+    client
+        .append_to_stream("some-stream", &options, event_data)
+        .await?;
+    // endregion overriding-user-credentials
+
+    // region readStream
+    let result = client
+        .read_stream("some-stream", &Default::default(), 10)
+        .await?;
+
+    if let ReadResult::Ok(events) = result {
+        // Doing something productive with the events.
+    }
+    // endregion readStream
+
+    Ok(())
+}