Skip to main content

Crate etcdrs

Crate etcdrs 

Source
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 (requires protoc).
  • nightly-async-iterator – enable AsyncIterator implementations 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§

ClusterId
ClusterResponseHeader
Metadata returned with cluster management RPC responses.
LeaseId
MemberId
Prefix
Specifies a prefix query in AsRange.
ResponseHeader
Global metadata returned with every etcd API response.
Revision
Term
Version
A monotonically increasing version number.

Enums§

TargetRange
A decoded view of an etcd range request’s (key, range_end) bytes.

Traits§

AsRange
Convert the source into a range query.
OperationError
A trait implemented by all operation-specific error types.