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, WatchRequestSender,
109    WatchResponse, WatchResponseStream, WatchStream,
110};
111pub use crate::rpc::{KeyValue, ResponseHeader};
112
113#[cfg(feature = "tls")]
114#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
115pub use tonic::transport::{Certificate, ClientTlsConfig as TlsOptions, Identity};
116
117#[cfg(feature = "tls-openssl")]
118#[cfg_attr(docsrs, doc(cfg(feature = "tls-openssl")))]
119pub use crate::openssl_tls::{OpenSslClientConfig, OpenSslResult, SslConnectorBuilder};
120
121/// Exposes internal protobuf representations used to create regular public response types.
122#[cfg(feature = "pub-response-field")]
123#[cfg_attr(docsrs, doc(cfg(feature = "pub-response-field")))]
124pub mod proto {
125    pub use crate::rpc::pb::etcdserverpb::compare::{
126        CompareTarget as PbCompareTarget, TargetUnion as PbTargetUnion,
127    };
128    pub use crate::rpc::pb::etcdserverpb::AlarmMember as PbAlarmMember;
129    pub use crate::rpc::pb::etcdserverpb::{
130        request_op::Request as PbTxnOpRequest, response_op::Response as PbTxnOpResponse,
131        AlarmResponse as PbAlarmResponse, AuthDisableResponse as PbAuthDisableResponse,
132        AuthEnableResponse as PbAuthEnableResponse, AuthRoleAddResponse as PbAuthRoleAddResponse,
133        AuthRoleDeleteResponse as PbAuthRoleDeleteResponse,
134        AuthRoleGetResponse as PbAuthRoleGetResponse,
135        AuthRoleGrantPermissionResponse as PbAuthRoleGrantPermissionResponse,
136        AuthRoleListResponse as PbAuthRoleListResponse,
137        AuthRoleRevokePermissionResponse as PbAuthRoleRevokePermissionResponse,
138        AuthUserAddResponse as PbAuthUserAddResponse,
139        AuthUserChangePasswordResponse as PbAuthUserChangePasswordResponse,
140        AuthUserDeleteResponse as PbAuthUserDeleteResponse,
141        AuthUserGetResponse as PbAuthUserGetResponse,
142        AuthUserGrantRoleResponse as PbAuthUserGrantRoleResponse,
143        AuthUserListResponse as PbAuthUserListResponse,
144        AuthUserRevokeRoleResponse as PbAuthUserRevokeRoleResponse,
145        AuthenticateResponse as PbAuthenticateResponse, CompactionResponse as PbCompactionResponse,
146        Compare as PbCompare, DefragmentResponse as PbDefragmentResponse,
147        DeleteRangeResponse as PbDeleteResponse, HashKvResponse as PbHashKvResponse,
148        HashResponse as PbHashResponse, LeaseGrantResponse as PbLeaseGrantResponse,
149        LeaseKeepAliveResponse as PbLeaseKeepAliveResponse,
150        LeaseLeasesResponse as PbLeaseLeasesResponse, LeaseRevokeResponse as PbLeaseRevokeResponse,
151        LeaseStatus as PbLeaseStatus, LeaseTimeToLiveResponse as PbLeaseTimeToLiveResponse,
152        Member as PbMember, MemberAddResponse as PbMemberAddResponse,
153        MemberListResponse as PbMemberListResponse,
154        MemberPromoteResponse as PbMemberPromoteResponse,
155        MemberRemoveResponse as PbMemberRemoveResponse,
156        MemberUpdateResponse as PbMemberUpdateResponse, MoveLeaderResponse as PbMoveLeaderResponse,
157        PutResponse as PbPutResponse, RangeResponse as PbRangeResponse,
158        RequestOp as PbTxnRequestOp, ResponseHeader as PbResponseHeader,
159        ResponseOp as PbResponseOp, SnapshotResponse as PbSnapshotResponse,
160        StatusResponse as PbStatusResponse, TxnRequest as PbTxnRequest,
161        TxnResponse as PbTxnResponse, WatchResponse as PbWatchResponse,
162    };
163    pub use crate::rpc::pb::mvccpb::Event as PbEvent;
164    pub use crate::rpc::pb::mvccpb::KeyValue as PbKeyValue;
165    pub use crate::rpc::pb::v3electionpb::{
166        CampaignResponse as PbCampaignResponse, LeaderKey as PbLeaderKey,
167        LeaderResponse as PbLeaderResponse, ProclaimResponse as PbProclaimResponse,
168        ResignResponse as PbResignResponse,
169    };
170    pub use crate::rpc::pb::v3lockpb::{
171        LockResponse as PbLockResponse, UnlockResponse as PbUnlockResponse,
172    };
173
174    #[cfg(feature = "build-server")]
175    pub use crate::rpc::pb::etcdserverpb::{
176        auth_server::{Auth as PbAuthService, AuthServer as PbAuthServer},
177        cluster_server::{Cluster as PbClusterService, ClusterServer as PbClusterServer},
178        kv_server::{Kv as PbKvService, KvServer as PbKvServer},
179        lease_server::{Lease as PbLeaseService, LeaseServer as PbLeaseServer},
180        maintenance_server::{
181            Maintenance as PbMaintenanceService, MaintenanceServer as PbMaintenanceServer,
182        },
183        watch_server::{Watch as PbWatchService, WatchServer as PbWatchServer},
184    };
185
186    #[cfg(feature = "build-server")]
187    pub use crate::rpc::pb::etcdserverpb::{
188        AlarmRequest as PbAlarmRequest, AuthDisableRequest as PbAuthDisableRequest,
189        AuthEnableRequest as PbAuthEnableRequest, AuthRoleAddRequest as PbAuthRoleAddRequest,
190        AuthRoleDeleteRequest as PbAuthRoleDeleteRequest,
191        AuthRoleGetRequest as PbAuthRoleGetRequest,
192        AuthRoleGrantPermissionRequest as PbAuthRoleGrantPermissionRequest,
193        AuthRoleListRequest as PbAuthRoleListRequest,
194        AuthRoleRevokePermissionRequest as PbAuthRoleRevokePermissionRequest,
195        AuthUserAddRequest as PbAuthUserAddRequest,
196        AuthUserChangePasswordRequest as PbAuthUserChangePasswordRequest,
197        AuthUserDeleteRequest as PbAuthUserDeleteRequest,
198        AuthUserGetRequest as PbAuthUserGetRequest,
199        AuthUserGrantRoleRequest as PbAuthUserGrantRoleRequest,
200        AuthUserListRequest as PbAuthUserListRequest,
201        AuthUserRevokeRoleRequest as PbAuthUserRevokeRoleRequest,
202        AuthenticateRequest as PbAuthenticateRequest, CompactionRequest as PbCompactionRequest,
203        DefragmentRequest as PbDefragmentRequest, DeleteRangeRequest as PbDeleteRequest,
204        HashKvRequest as PbHashKvRequest, HashRequest as PbHashRequest,
205        LeaseGrantRequest as PbLeaseGrantRequest, LeaseKeepAliveRequest as PbLeaseKeepAliveRequest,
206        LeaseLeasesRequest as PbLeaseLeasesRequest, LeaseRevokeRequest as PbLeaseRevokeRequest,
207        LeaseTimeToLiveRequest as PbLeaseTimeToLiveRequest, MemberAddRequest as PbMemberAddRequest,
208        MemberListRequest as PbMemberListRequest, MemberPromoteRequest as PbMemberPromoteRequest,
209        MemberRemoveRequest as PbMemberRemoveRequest, MemberUpdateRequest as PbMemberUpdateRequest,
210        MoveLeaderRequest as PbMoveLeaderRequest, PutRequest as PbPutRequest,
211        RangeRequest as PbRangeRequest, SnapshotRequest as PbSnapshotRequest,
212        StatusRequest as PbStatusRequest, WatchRequest as PbWatchRequest,
213    };
214
215    #[cfg(feature = "build-server")]
216    pub use crate::rpc::pb::etcdserverpb::watch_request::RequestUnion as PbWatchRequestUnion;
217}
etcd_client/lib.rs

etcd_client/
lib.rs
