etcd-client

OR

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

Features

• etcd API v3
• asynchronous

Supported APIs

• [x] KV
• [x] Watch
• [x] Lease
• [x] Auth
• [x] Maintenance
• [x] Cluster
• [x] Lock
• [x] Election
• [x] 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.