Add KV example.

Author: davidli2010

README.md

@@ -21,13 +21,32 @@ It provides asynchronous client backed by [tokio](https://github.com/tokio-rs/to
 - [ ] Election
 - [ ] Lock
 
+## Usage
+
+```Rust
+use ectdv3::*;
+
+let mut client = Client::connect(["localhost:2379"]).await?;
+// put kv
+client.put("foo", "bar", None).await?;
+// get kv
+let resp = client.get("foo", None).await?;
+if let Some(kv) = resp.kvs().first() {
+    println!("Get kv: {{{}: {}}}", kv.key_str()?, kv.value_str()?);
+}
+```
+
+## Examples
+
+Examples can be found in [`examples`](./examples).
+
 ## Test
 
 We test this library using etcd 3.4.
 
 Notes that we use a fixed `etcd` server URI (localhost:2379) to connect to etcd server.
 
-## Rust Version
+## Rust version requirements
 
 `etcdv3` works on rust `1.39` and above as it requires support for the `async_await`
 feature.

examples/kv.rs

@@ -0,0 +1,117 @@
+//! KV example.
+
+use etcdv3::*;
+
+#[derive(Debug)]
+struct KV {
+    key: String,
+    value: String,
+}
+
+impl KV {
+    #[inline]
+    pub fn new(key: impl Into<String>, value: impl Into<String>) -> Self {
+        KV {
+            key: key.into(),
+            value: value.into(),
+        }
+    }
+
+    #[inline]
+    pub fn key(&self) -> &str {
+        &self.key
+    }
+
+    #[inline]
+    pub fn value(&self) -> &str {
+        &self.value
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let mut client = Client::connect(["localhost:2379"]).await?;
+
+    let alice = KV::new("Alice", "15");
+    let bob = KV::new("Bob", "20");
+    let chris = KV::new("Chris", "16");
+
+    // put kv
+    let resp = client.put(alice.key(), alice.value(), None).await?;
+    println!("put kv: {:?}", alice);
+    let revison = resp.header().unwrap().revision();
+    client.put(bob.key(), bob.value(), None).await?;
+    println!("put kv: {:?}", bob);
+    client.put(chris.key(), chris.value(), None).await?;
+    println!("put kv: {:?}", chris);
+    println!();
+
+    // get bob
+    let resp = client.get(bob.key(), None).await?;
+    if let Some(kv) = resp.kvs().first() {
+        println!("Get kv: {{{}: {}}}", kv.key_str()?, kv.value_str()?);
+        println!();
+    }
+
+    // get all key-value pairs
+    println!("Get all users:");
+    let resp = client
+        .get("", Some(GetOptions::new().with_from_key()))
+        .await?;
+    for kv in resp.kvs() {
+        println!("\t{{{}: {}}}", kv.key_str()?, kv.value_str()?);
+    }
+    println!();
+
+    // delete chris
+    let resp = client
+        .delete(chris.key(), Some(DeleteOptions::new().with_prev_key()))
+        .await?;
+    if let Some(kv) = resp.prev_kvs().first() {
+        println!("Delete kv: {{{}: {}}}", kv.key_str()?, kv.value_str()?);
+        println!();
+    }
+
+    // transaction
+    let resp = client.get(alice.key(), None).await?;
+    if let Some(kv) = resp.kvs().first() {
+        println!(
+            "Before transaction: {{{}: {}}}",
+            kv.key_str()?,
+            kv.value_str()?
+        );
+    }
+    let txn = Txn::new()
+        .when(vec![Compare::value(
+            alice.key(),
+            CompareOp::Equal,
+            alice.value(),
+        )])
+        .and_then(vec![TxnOp::put(
+            alice.key(),
+            "18",
+            Some(PutOptions::new().with_ignore_lease()),
+        )]);
+    println!("transaction: {:?}", txn);
+    let resp = client.txn(txn).await?;
+    for op_resp in resp.op_responses() {
+        println!("transaction resp: {:?}", op_resp);
+    }
+    let resp = client.get(alice.key(), None).await?;
+    if let Some(kv) = resp.kvs().first() {
+        println!(
+            "After transaction: {{{}: {}}}",
+            kv.key_str()?,
+            kv.value_str()?
+        );
+    }
+    println!();
+
+    // compact
+    client
+        .compact(revison, Some(CompactionOptions::new().with_physical()))
+        .await?;
+    println!("Compact to revision {}.", revison);
+
+    Ok(())
+}

src/client.rs

@@ -117,7 +117,12 @@ impl Client {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{get_client, Compare, CompareOp, EventType, TxnOp, TxnOpResponse};
+    use crate::{Compare, CompareOp, EventType, TxnOp, TxnOpResponse};
+
+    /// Get client for testing.
+    async fn get_client() -> Result<Client> {
+        Client::connect(["localhost:2379"]).await
+    }
 
     #[tokio::test]
     async fn test_put() -> Result<()> {

src/error.rs

@@ -1,6 +1,7 @@
 //! Etcd Client Error handling.
 
 use std::fmt::{Display, Formatter};
+use std::str::Utf8Error;
 
 pub type Result<T> = std::result::Result<T, Error>;
 
@@ -24,6 +25,9 @@ pub enum Error {
 
     /// Watch error
     WatchError(String),
+
+    /// Utf8Error
+    Utf8Error(Utf8Error),
 }
 
 impl Display for Error {
@@ -36,6 +40,7 @@ impl Display for Error {
             Error::TransportError(e) => write!(f, "transport error: {}", e),
             Error::GRPCStatus(e) => write!(f, "grep request error: {}", e),
             Error::WatchError(e) => write!(f, "watch error: {}", e),
+            Error::Utf8Error(e) => write!(f, "utf8 error: {}", e),
         }
     }
 }
@@ -69,3 +74,10 @@ impl From<tonic::Status> for Error {
         Error::GRPCStatus(e)
     }
 }
+
+impl From<Utf8Error> for Error {
+    #[inline]
+    fn from(e: Utf8Error) -> Self {
+        Error::Utf8Error(e)
+    }
+}

src/lib.rs

@@ -15,10 +15,3 @@ pub use crate::rpc::watch::{
     Event, EventType, WatchFilterType, WatchOptions, WatchResponse, WatchStream, Watcher,
 };
 pub use crate::rpc::{KeyValue, ResponseHeader};
-
-/// Get client for testing.
-#[doc(hidden)]
-#[cfg(test)]
-pub async fn get_client() -> crate::error::Result<Client> {
-    Client::connect(["localhost:2379"]).await
-}

src/rpc/mod.rs

@@ -11,6 +11,7 @@ pub mod lock;
 pub mod maintenance;
 pub mod watch;
 
+use crate::error::Result;
 use pb::etcdserverpb::ResponseHeader as PbResponseHeader;
 use pb::mvccpb::KeyValue as PbKeyValue;
 
@@ -79,12 +80,46 @@ impl KeyValue {
         &self.0.key
     }
 
+    /// The key in string. An empty key is not allowed.
+    #[inline]
+    pub fn key_str(&self) -> Result<&str> {
+        std::str::from_utf8(self.key()).map_err(From::from)
+    }
+
+    /// The key in string. An empty key is not allowed.
+    ///
+    /// # Safety
+    /// This function is unsafe because it does not check that the bytes of the key are valid UTF-8.
+    /// If this constraint is violated, undefined behavior results,
+    /// as the rest of Rust assumes that [`&str`]s are valid UTF-8.
+    #[inline]
+    pub unsafe fn key_str_unchecked(&self) -> &str {
+        std::str::from_utf8_unchecked(self.key())
+    }
+
     /// The value held by the key, in bytes.
     #[inline]
     pub fn value(&self) -> &[u8] {
         &self.0.value
     }
 
+    /// The value held by the key, in string.
+    #[inline]
+    pub fn value_str(&self) -> Result<&str> {
+        std::str::from_utf8(self.value()).map_err(From::from)
+    }
+
+    /// The value held by the key, in bytes.
+    ///
+    /// # Safety
+    /// This function is unsafe because it does not check that the bytes of the value are valid UTF-8.
+    /// If this constraint is violated, undefined behavior results,
+    /// as the rest of Rust assumes that [`&str`]s are valid UTF-8.
+    #[inline]
+    pub unsafe fn value_str_unchecked(&self) -> &str {
+        std::str::from_utf8_unchecked(self.value())
+    }
+
     /// The revision of last creation on this key.
     #[inline]
     pub const fn create_revision(&self) -> i64 {