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 StreamExt;
# async ;
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 (requiresprotoc).nightly-async-iterator-- enable [AsyncIterator][std::async_iter::AsyncIterator] implementations for streaming types (requires nightly Rust).