Expand description
§etcdrs
An async Rust client for etcd, built on tonic and tokio.
§Design
§Operations as Objects
Every etcd operation (Get, Put, Delete,
List, Watch) is a standalone struct with a fluent
builder API. Operations can be awaited directly for one-shot use, or composed into atomic
Transactions without changing how they are built:
use futures::StreamExt;
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 resolves to a ListView, which
into_stream turns into a Stream. Without a
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 makes PutResponse::previous() available;
calling .keys_only() on a 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 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,
LeaseDriver, and 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 supports username/password
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, 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– enableAsyncIteratorimplementations for streaming types (requires nightly Rust).
Re-exports§
pub use client::AuthDisableResponse;pub use client::AuthEnableResponse;pub use client::AuthError;pub use client::AuthErrorKind;pub use client::AuthStatusResponse;pub use client::AuthenticateResponse;pub use client::BuildError;pub use client::Client;pub use client::ClusterError;pub use client::ClusterErrorKind;pub use client::CompactError;pub use client::CompactErrorKind;pub use client::DeleteError;pub use client::DeleteErrorKind;pub use client::GetError;pub use client::GetErrorKind;pub use client::GrantLeaseError;pub use client::GrantLeaseErrorKind;pub use client::KeepAliveError;pub use client::KeepAliveErrorKind;pub use client::LeaseTimeToLiveError;pub use client::LeaseTimeToLiveErrorKind;pub use client::LeasesError;pub use client::LeasesErrorKind;pub use client::Member;pub use client::MemberAdd;pub use client::MemberAddResponse;pub use client::MemberList;pub use client::MemberListResponse;pub use client::MemberPromoteResponse;pub use client::MemberRemoveResponse;pub use client::MemberUpdateResponse;pub use client::Permission;pub use client::PermissionType;pub use client::PutError;pub use client::PutErrorKind;pub use client::RetryPolicy;pub use client::RevokeLeaseError;pub use client::RevokeLeaseErrorKind;pub use client::RoleAddResponse;pub use client::RoleDeleteResponse;pub use client::RoleError;pub use client::RoleErrorKind;pub use client::RoleGetResponse;pub use client::RoleGrantPermissionResponse;pub use client::RoleListResponse;pub use client::RoleRevokePermissionResponse;pub use client::TransactionError;pub use client::TransactionErrorKind;pub use client::UserAddResponse;pub use client::UserChangePasswordResponse;pub use client::UserDeleteResponse;pub use client::UserError;pub use client::UserErrorKind;pub use client::UserGetResponse;pub use client::UserGrantRoleResponse;pub use client::UserListResponse;pub use client::UserRevokeRoleResponse;pub use client::WatchError;pub use client::WatchErrorKind;pub use client::WatchId;pub use record::KeyWithMetadata;pub use record::Metadata;pub use record::Record;
Modules§
- client
- Core client operations.
- driver
- Driver traits used to execute operations.
- record
- Key-value record types.
Structs§
- Cluster
Id - Cluster
Response Header - Metadata returned with cluster management RPC responses.
- LeaseId
- Member
Id - Prefix
- Specifies a prefix query in
AsRange. - Response
Header - Global metadata returned with every etcd API response.
- Revision
- Term
- Version
- A monotonically increasing version number.
Enums§
- Target
Range - A decoded view of an etcd range request’s
(key, range_end)bytes.
Traits§
- AsRange
- Convert the source into a range query.
- Operation
Error - A trait implemented by all operation-specific error types.