docs/examples: add simple example and update README

Author: Heiko Seeberger

README.md

@@ -1,6 +1,58 @@
 # Pub-Sub-Client #
 
-Rust library to access Google Cloud Pub/Sub.
+Rust library to access Google Cloud Pub/Sub. Currently only pulling from a subscription as well as acknowledging pulled messages is supported.
+
+Messages can either be pulled as raw or, if the payload is JSON data, deserialized into domain messages (structs or enums) via [Serde](https://serde.rs/) and [Serde JSON](https://docs.serde.rs/serde_json). Both raw `ReceivedMessages` and `MessageEnvelopes` holding deserialized messages, expose metadata like message ID, acknowledge ID, attributes, etc.
+
+Aside from straight forward deserialization it is also possible to first transform the pulled JSON values before deserizlizing into domain messages which allows for generally adjusting the JSON structure as well as schema evolution.
+
+## Usage
+
+Typically we want to deserialize into a domain message:
+
+``` rust
+#[derive(Debug, Deserialize)]
+struct Message {
+    text: String,
+}
+```
+
+First create a `PubSubClient`, giving the path to a service account key file and the duration to refresh access tokens before they expire:
+
+``` rust
+let pub_sub_client = PubSubClient::new(
+    "secrets/cryptic-hawk-336616-e228f9680cbc.json",
+    Duration::from_secs(30),
+)?;
+```
+
+Things could go wrong, e.g. if the service account key file does not exist or is malformed, hence a `Result` is returned.
+
+Next we call `pull` to get at most the given `42` messages from the given `SUBSCRIPTION`; we do not use a request timeout here for simplicity:
+
+``` rust
+let envelopes = pub_sub_client
+    .pull::<Message>(SUBSCRIPTION, 42, None)
+    .await?;
+```
+
+Of course pulling which happens via HTTP could fail, hence we get back another `Result`.
+
+Finally we handle the pulled messages; for simplicity we only deal with the happy path here, i.e. when the deserialization was successful:
+
+``` rust
+for envelope in envelopes {
+    let envelope = envelope?;
+    println!("Message text: {}", envelope.message.text);
+
+    pub_sub_client
+        .acknowledge(SUBSCRIPTION, vec![&envelope.ack_id], None)
+        .await?;
+    println!("Successfully acknowledged");
+}
+```
+
+For successfully deserialized messages we call `acknowledge` with the acknowledge ID taken from the envelope.
 
 ## Contribution policy ##
 

examples/simple.rs

@@ -0,0 +1,44 @@
+use pub_sub_client::{Error, PubSubClient};
+use serde::Deserialize;
+use std::error::Error as _;
+use std::time::Duration;
+
+const SUBSCRIPTION: &str = "test";
+
+#[derive(Debug, Deserialize)]
+struct Message {
+    text: String,
+}
+
+#[tokio::main]
+async fn main() {
+    if let Err(e) = run().await {
+        eprintln!("ERRORx: {}", e);
+        if let Some(e) = e.source() {
+            eprintln!("SOURCE: {}", e);
+        }
+    }
+}
+
+async fn run() -> Result<(), Error> {
+    let pub_sub_client = PubSubClient::new(
+        "secrets/cryptic-hawk-336616-e228f9680cbc.json",
+        Duration::from_secs(30),
+    )?;
+
+    let envelopes = pub_sub_client
+        .pull::<Message>(SUBSCRIPTION, 42, None)
+        .await?;
+
+    for envelope in envelopes {
+        let envelope = envelope?;
+        println!("Message text: {}", envelope.message.text);
+
+        pub_sub_client
+            .acknowledge(SUBSCRIPTION, vec![&envelope.ack_id], None)
+            .await?;
+        println!("Successfully acknowledged");
+    }
+
+    Ok(())
+}

examples/transform_versioned.rs

@@ -1,5 +1,5 @@
 use anyhow::anyhow;
-use pub_sub_client::{Error, MessageEnvelope, PubSubClient, ReceivedMessage};
+use pub_sub_client::{Error, PubSubClient, ReceivedMessage};
 use serde::Deserialize;
 use serde_json::{json, Value};
 use std::error::Error as _;
@@ -30,8 +30,13 @@ async fn run() -> Result<(), Error> {
         Duration::from_secs(30),
     )?;
 
-    let msg_envelopes: Vec<Result<MessageEnvelope<Message>, Error>> = pub_sub_client
-        .pull_with_transform(SUBSCRIPTION, 42, Some(Duration::from_secs(45)), transform)
+    let msg_envelopes = pub_sub_client
+        .pull_with_transform::<Message, _>(
+            SUBSCRIPTION,
+            42,
+            Some(Duration::from_secs(45)),
+            transform,
+        )
         .await?;
 
     for msg_envelope in msg_envelopes {