etcd-client

An etcd v3 API client for Rust. It provides asynchronous client backed by tokio and tonic.

Features

etcd API v3
asynchronous

Supported APIs

KV
Watch
Lease
Auth
Maintenance
Cluster
Lock
Election
Namespace

Usage

Add this to your Cargo.toml:

[dependencies]
etcd-client = "0.16"
tokio = { version = "1.0", features = ["full"] }

To get started using etcd-client:

use etcd_client::{Client, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let mut client = Client::connect(["localhost:2379"], None).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()?);
    }

    Ok(())
}

Upgrade from pre 0.17 to 0.18

Since 0.18, the WatchClient API has changed to support watch stream error handling precisely.

The WatchClient is not a high level watcher, it is just a watch API stub. So it should be only responsible for sending requests and receiving responses. Let the high level watcher decide what to do if received an unexpected response.

- WatchClient::watch(key: impl Into<Vec<u8>>, options: Option<WatchOptions>) -> Result<(WatchResponse, Watcher, WatchStream)>
+ WatchClient::watch(key: impl Into<Vec<u8>>, options: Option<WatchOptions>) -> Result<WatchStream>

The new WatchStream is different from the old version. It represents underlying bidirectional watch stream (HTTP 2 stream). So it can be used to send requests and receive responses and events.

It's the user's responsibility to check the received response is a response or an event, if it is created successfully or not, or if it is a cancel response.

See watch.rs for example.

Examples

Examples can be found in examples.

Feature Flags

tls: Enables the rustls-based TLS connection. Not enabled by default.
tls-roots: Adds system trust roots to rustls-based TLS connection using the rustls-native-certs crate. Not enabled by default.
pub-response-field: Exposes structs used to create regular etcd-client responses including internal protobuf representations. Useful for mocking. Not enabled by default.
tls-openssl: Enables the openssl-based TLS connections. This would make your binary dynamically link to libssl.
tls-openssl-vendored: Like tls-openssl, however compile openssl from source code and statically link to it.
build-server: Builds a server variant of the etcd protobuf and re-exports it under the same proto package as the pub-response-field feature does.
raw-channel: Allows the caller to construct the underlying Tonic channel used by the client.

Test

We test this library with etcd 3.5.

Note that we use a fixed etcd server URI (localhost:2379) to connect to etcd server.

Rust version requirements

The minimum supported version is 1.80. The current etcd-client version is not guaranteed to build on Rust versions earlier than the minimum supported version.

License

Dual-licensed to be compatible with the Rust project.

Licensed under the Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0 or the MIT license http://opensource.org/licenses/MIT, at your option. This file may not be copied, modified, or distributed except according to those terms.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in etcd-client by you, shall be licensed as Apache-2.0 and MIT, without any additional terms or conditions.

etcd-client 0.18.0