etcd_client/
lib.rs

1//! An [etcd](https://github.com/etcd-io/etcd) v3 API client for Rust.
2//! It provides asynchronous client backed by [tokio](https://github.com/tokio-rs/tokio) and [tonic](https://github.com/hyperium/tonic).
3//!
4//! # Supported APIs
5//!
6//! - KV
7//! - Watch
8//! - Lease
9//! - Auth
10//! - Maintenance
11//! - Cluster
12//! - Lock
13//! - Election
14//!
15//! # Usage
16//!
17//! Add this to your `Cargo.toml`:
18//!
19//! ```toml
20//! [dependencies]
21//! etcd-client = "0.16"
22//! tokio = { version = "1.0", features = ["full"] }
23//! ```
24//!
25//! To get started using `etcd-client`:
26//!
27//! ```rust
28//! use etcd_client::{Client, Error};
29//!
30//! #[tokio::main]
31//! async fn main() -> Result<(), Error> {
32//!     let mut client = Client::connect(["localhost:2379"], None).await?;
33//!     // put kv
34//!     client.put("foo", "bar", None).await?;
35//!     // get kv
36//!     let resp = client.get("foo", None).await?;
37//!     if let Some(kv) = resp.kvs().first() {
38//!         println!("Get kv: {{{}: {}}}", kv.key_str()?, kv.value_str()?);
39//!     }
40//!
41//!     Ok(())
42//! }
43//! ```
44//!
45//! # Examples
46//!
47//! Examples can be found in [`etcd-client/examples`](https://github.com/etcdv3/etcd-client/tree/master/examples).
48//!
49//! # Feature Flags
50//!
51//! - `tls`: Enables the `rustls`-based TLS connection. Not enabled by default.
52//! - `tls-roots`: Adds system trust roots to `rustls`-based TLS connection using the `rustls-native-certs` crate. Not enabled by default.
53//! - `pub-response-field`: Exposes structs used to create regular `etcd-client` responses including internal protobuf representations. Useful for mocking. Not enabled by default.
54//! - `tls-openssl`: Enables the `openssl`-based TLS connections. This would make your binary dynamically link to `libssl`.
55//! - `tls-openssl-vendored`: Like `tls-openssl`, however compile openssl from source code and statically link to it.
56//! - `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.
57//! - `raw-channel`: Allows the caller to construct the underlying Tonic channel used by the client.
58
59#![cfg_attr(docsrs, feature(doc_cfg))]
60
61mod channel;
62mod client;
63mod error;
64mod intercept;
65mod lock;
66mod namespace;
67mod openssl_tls;
68mod rpc;
69mod vec;
70
71pub use crate::channel::{BalancedChannelBuilder, Channel};
72pub use crate::client::{Client, ConnectOptions};
73pub use crate::error::Error;
74pub use crate::namespace::{KvClientPrefix, LeaseClientPrefix};
75pub use crate::rpc::auth::{
76    AuthClient, AuthDisableResponse, AuthEnableResponse, AuthenticateResponse, Permission,
77    PermissionType, RoleAddResponse, RoleDeleteResponse, RoleGetResponse,
78    RoleGrantPermissionResponse, RoleListResponse, RoleRevokePermissionOptions,
79    RoleRevokePermissionResponse, UserAddOptions, UserAddResponse, UserChangePasswordResponse,
80    UserDeleteResponse, UserGetResponse, UserGrantRoleResponse, UserListResponse,
81    UserRevokeRoleResponse,
82};
83pub use crate::rpc::cluster::{
84    ClusterClient, Member, MemberAddOptions, MemberAddResponse, MemberListResponse,
85    MemberPromoteResponse, MemberRemoveResponse, MemberUpdateResponse,
86};
87pub use crate::rpc::election::{
88    CampaignResponse, ElectionClient, LeaderKey, LeaderResponse, ObserveStream, ProclaimOptions,
89    ProclaimResponse, ResignOptions, ResignResponse,
90};
91pub use crate::rpc::kv::{
92    CompactionOptions, CompactionResponse, Compare, CompareOp, DeleteOptions, DeleteResponse,
93    GetOptions, GetResponse, KvClient, PutOptions, PutResponse, SortOrder, SortTarget, Txn, TxnOp,
94    TxnOpResponse, TxnResponse,
95};
96pub use crate::rpc::lease::{
97    LeaseClient, LeaseGrantOptions, LeaseGrantResponse, LeaseKeepAliveResponse,
98    LeaseKeepAliveStream, LeaseKeeper, LeaseLeasesResponse, LeaseRevokeResponse, LeaseStatus,
99    LeaseTimeToLiveOptions, LeaseTimeToLiveResponse,
100};
101pub use crate::rpc::lock::{LockClient, LockOptions, LockResponse, UnlockResponse};
102pub use crate::rpc::maintenance::{
103    AlarmAction, AlarmMember, AlarmOptions, AlarmResponse, AlarmType, DefragmentResponse,
104    HashKvResponse, HashResponse, MaintenanceClient, MoveLeaderResponse, SnapshotResponse,
105    SnapshotStreaming, StatusResponse,
106};
107pub use crate::rpc::watch::{
108    Event, EventType, WatchClient, WatchFilterType, WatchOptions, WatchResponse, WatchStream,
109};
110pub use crate::rpc::{KeyValue, ResponseHeader};
111
112#[cfg(feature = "tls")]
113#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
114pub use tonic::transport::{Certificate, ClientTlsConfig as TlsOptions, Identity};
115
116#[cfg(feature = "tls-openssl")]
117#[cfg_attr(docsrs, doc(cfg(feature = "tls-openssl")))]
118pub use crate::openssl_tls::{OpenSslClientConfig, OpenSslResult, SslConnectorBuilder};
119
120/// Exposes internal protobuf representations used to create regular public response types.
121#[cfg(feature = "pub-response-field")]
122#[cfg_attr(docsrs, doc(cfg(feature = "pub-response-field")))]
123pub mod proto {
124    pub use crate::rpc::pb::etcdserverpb::compare::{
125        CompareTarget as PbCompareTarget, TargetUnion as PbTargetUnion,
126    };
127    pub use crate::rpc::pb::etcdserverpb::AlarmMember as PbAlarmMember;
128    pub use crate::rpc::pb::etcdserverpb::{
129        request_op::Request as PbTxnOpRequest, response_op::Response as PbTxnOpResponse,
130        AlarmResponse as PbAlarmResponse, AuthDisableResponse as PbAuthDisableResponse,
131        AuthEnableResponse as PbAuthEnableResponse, AuthRoleAddResponse as PbAuthRoleAddResponse,
132        AuthRoleDeleteResponse as PbAuthRoleDeleteResponse,
133        AuthRoleGetResponse as PbAuthRoleGetResponse,
134        AuthRoleGrantPermissionResponse as PbAuthRoleGrantPermissionResponse,
135        AuthRoleListResponse as PbAuthRoleListResponse,
136        AuthRoleRevokePermissionResponse as PbAuthRoleRevokePermissionResponse,
137        AuthUserAddResponse as PbAuthUserAddResponse,
138        AuthUserChangePasswordResponse as PbAuthUserChangePasswordResponse,
139        AuthUserDeleteResponse as PbAuthUserDeleteResponse,
140        AuthUserGetResponse as PbAuthUserGetResponse,
141        AuthUserGrantRoleResponse as PbAuthUserGrantRoleResponse,
142        AuthUserListResponse as PbAuthUserListResponse,
143        AuthUserRevokeRoleResponse as PbAuthUserRevokeRoleResponse,
144        AuthenticateResponse as PbAuthenticateResponse, CompactionResponse as PbCompactionResponse,
145        Compare as PbCompare, DefragmentResponse as PbDefragmentResponse,
146        DeleteRangeResponse as PbDeleteResponse, HashKvResponse as PbHashKvResponse,
147        HashResponse as PbHashResponse, LeaseGrantResponse as PbLeaseGrantResponse,
148        LeaseKeepAliveResponse as PbLeaseKeepAliveResponse,
149        LeaseLeasesResponse as PbLeaseLeasesResponse, LeaseRevokeResponse as PbLeaseRevokeResponse,
150        LeaseStatus as PbLeaseStatus, LeaseTimeToLiveResponse as PbLeaseTimeToLiveResponse,
151        Member as PbMember, MemberAddResponse as PbMemberAddResponse,
152        MemberListResponse as PbMemberListResponse,
153        MemberPromoteResponse as PbMemberPromoteResponse,
154        MemberRemoveResponse as PbMemberRemoveResponse,
155        MemberUpdateResponse as PbMemberUpdateResponse, MoveLeaderResponse as PbMoveLeaderResponse,
156        PutResponse as PbPutResponse, RangeResponse as PbRangeResponse,
157        RequestOp as PbTxnRequestOp, ResponseHeader as PbResponseHeader,
158        ResponseOp as PbResponseOp, SnapshotResponse as PbSnapshotResponse,
159        StatusResponse as PbStatusResponse, TxnRequest as PbTxnRequest,
160        TxnResponse as PbTxnResponse, WatchResponse as PbWatchResponse,
161    };
162    pub use crate::rpc::pb::mvccpb::Event as PbEvent;
163    pub use crate::rpc::pb::mvccpb::KeyValue as PbKeyValue;
164    pub use crate::rpc::pb::v3electionpb::{
165        CampaignResponse as PbCampaignResponse, LeaderKey as PbLeaderKey,
166        LeaderResponse as PbLeaderResponse, ProclaimResponse as PbProclaimResponse,
167        ResignResponse as PbResignResponse,
168    };
169    pub use crate::rpc::pb::v3lockpb::{
170        LockResponse as PbLockResponse, UnlockResponse as PbUnlockResponse,
171    };
172
173    #[cfg(feature = "build-server")]
174    pub use crate::rpc::pb::etcdserverpb::{
175        auth_server::{Auth as PbAuthService, AuthServer as PbAuthServer},
176        cluster_server::{Cluster as PbClusterService, ClusterServer as PbClusterServer},
177        kv_server::{Kv as PbKvService, KvServer as PbKvServer},
178        lease_server::{Lease as PbLeaseService, LeaseServer as PbLeaseServer},
179        maintenance_server::{
180            Maintenance as PbMaintenanceService, MaintenanceServer as PbMaintenanceServer,
181        },
182        watch_server::{Watch as PbWatchService, WatchServer as PbWatchServer},
183    };
184
185    #[cfg(feature = "build-server")]
186    pub use crate::rpc::pb::etcdserverpb::{
187        AlarmRequest as PbAlarmRequest, AuthDisableRequest as PbAuthDisableRequest,
188        AuthEnableRequest as PbAuthEnableRequest, AuthRoleAddRequest as PbAuthRoleAddRequest,
189        AuthRoleDeleteRequest as PbAuthRoleDeleteRequest,
190        AuthRoleGetRequest as PbAuthRoleGetRequest,
191        AuthRoleGrantPermissionRequest as PbAuthRoleGrantPermissionRequest,
192        AuthRoleListRequest as PbAuthRoleListRequest,
193        AuthRoleRevokePermissionRequest as PbAuthRoleRevokePermissionRequest,
194        AuthUserAddRequest as PbAuthUserAddRequest,
195        AuthUserChangePasswordRequest as PbAuthUserChangePasswordRequest,
196        AuthUserDeleteRequest as PbAuthUserDeleteRequest,
197        AuthUserGetRequest as PbAuthUserGetRequest,
198        AuthUserGrantRoleRequest as PbAuthUserGrantRoleRequest,
199        AuthUserListRequest as PbAuthUserListRequest,
200        AuthUserRevokeRoleRequest as PbAuthUserRevokeRoleRequest,
201        AuthenticateRequest as PbAuthenticateRequest, CompactionRequest as PbCompactionRequest,
202        DefragmentRequest as PbDefragmentRequest, DeleteRangeRequest as PbDeleteRequest,
203        HashKvRequest as PbHashKvRequest, HashRequest as PbHashRequest,
204        LeaseGrantRequest as PbLeaseGrantRequest, LeaseKeepAliveRequest as PbLeaseKeepAliveRequest,
205        LeaseLeasesRequest as PbLeaseLeasesRequest, LeaseRevokeRequest as PbLeaseRevokeRequest,
206        LeaseTimeToLiveRequest as PbLeaseTimeToLiveRequest, MemberAddRequest as PbMemberAddRequest,
207        MemberListRequest as PbMemberListRequest, MemberPromoteRequest as PbMemberPromoteRequest,
208        MemberRemoveRequest as PbMemberRemoveRequest, MemberUpdateRequest as PbMemberUpdateRequest,
209        MoveLeaderRequest as PbMoveLeaderRequest, PutRequest as PbPutRequest,
210        RangeRequest as PbRangeRequest, SnapshotRequest as PbSnapshotRequest,
211        StatusRequest as PbStatusRequest, WatchRequest as PbWatchRequest,
212    };
213}
etcd_client/lib.rs

etcd_client/
lib.rs
