etcdrs 0.1.2

An async etcd v3 client built on tonic and tokio, with composable operation builders and type-safe responses
Documentation

etcdrs

An async Rust client for etcd, built on tonic and tokio.

Design

Operations as Objects

Every etcd operation ([Get][client::Get], [Put][client::Put], [Delete][client::Delete], [List][client::List], [Watch][client::WatchBuilder]) is a standalone struct with a fluent builder API. Operations can be awaited directly for one-shot use, or composed into atomic [Transaction][client::Transaction]s without changing how they are built:

use futures::StreamExt;
# async {
let client = etcdrs::Client::new("http://localhost:2379").unwrap();

// Standalone
client.put("greeting/hello").value("world").await.unwrap();
let record = client.get("greeting/hello").await.unwrap();

// Ranged reads stream; a page limit is what makes later pages fetch as you consume them
let mut entries = client.list_prefix("greeting/").limit(100).await.unwrap().into_stream();
while let Some(entry) = entries.next().await {
    println!("{:?}", entry.unwrap());
}

// The same builders work inside a transaction
client.transaction()
    .when([etcdrs::client::TransactionCheck::present("greeting/hello")])
    .and_then([client.put("greeting/hello").value("updated").into()])
    .commit()
    .await
    .unwrap();
# };

A [List][client::List] resolves to a [ListView][client::ListView], which [into_stream][client::ListView::into_stream] turns into a Stream. Without a [limit][client::List::limit] etcd answers the whole range in one response, and the stream simply walks it; with one, each request returns a page and the stream fetches the next as you consume it, pinning the revision so a scan stays consistent across them. On a nightly toolchain with nightly-async-iterator, ListView also implements IntoAsyncIterator, so it can be driven with for await instead.

Type-Safe Responses

Builder methods change phantom type parameters, altering the response type at compile time. Calling .get_previous() on a [Put][client::Put] makes PutResponse::previous() available; calling .keys_only() on a [List][client::List] changes the stream item type to [KeyWithMetadata]; calling .count_only() yields a usize instead of a stream.

Cheap Client Cloning

[Client] wraps an [Arc][std::sync::Arc] internally. Cloning is cheap and all methods take &self, so a single client can be shared across tasks without additional synchronization.

Pluggable Backends

The [driver] module defines service-boundary traits like [KvDriver][driver::KvDriver], [LeaseDriver][driver::LeaseDriver], and [WatchDriver][driver::WatchDriver] that abstract how operations are executed. The default [Client] implements all drivers via gRPC. Custom types can wrap a client to build caching layers, mock clients, instrumentation, or proxies.

Authentication

[ClientBuilder][client::ClientBuilder] supports username/password [credentials][client::ClientBuilder::credentials]. The client authenticates when it first needs a token, sends the token with every request and stream, and authenticates again whenever etcd stops accepting it. One exception: once etcd has created a watch on a [Watcher][client::Watcher], the watcher keeps the token its stream opened with, so etcd refuses a watch added after that token stops working. Start a new Watcher for it.

Feature Flags

  • generate -- re-generate protobuf bindings from the etcd proto definitions (requires protoc).
  • nightly-async-iterator -- enable [AsyncIterator][std::async_iter::AsyncIterator] implementations for streaming types (requires nightly Rust).