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 using the `ring` libcrypto provider.
52//!   Alias for `tls-ring`. Not enabled by default.
53//! - `tls-ring`: Enables the `rustls`-based TLS connection using the `ring` libcrypto provider.
54//!   Not enabled by default.
55//! - `tls-aws-lc`: Enables the `rustls`-based TLS connection using the `aws-lc-rs` libcrypto
56//!   provider. Not enabled by default.
57//! - `tls-roots`: Alias for `tls-native-roots`. Not enabled by default.
58//! - `tls-native-roots`: Adds system trust roots to `rustls`-based TLS connection using the `rustls-native-certs` crate. Not enabled by default.
59//! - `tls-webpki-roots`: Adds Mozilla's trust roots to `rustls`-based TLS connection using the `webpki-roots` crate. Not enabled by default.
60//! - `pub-response-field`: Exposes structs used to create regular `etcd-client` responses including internal protobuf representations. Useful for mocking. Not enabled by default.
61//! - `tls-openssl`: Enables the `openssl`-based TLS connections. This would make your binary dynamically link to `libssl`.
62//! - `tls-openssl-vendored`: Like `tls-openssl`, however compile openssl from source code and statically link to it.
63//! - `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.
64//! - `raw-channel`: Allows the caller to construct the underlying Tonic channel used by the client.
65
66#![cfg_attr(docsrs, feature(doc_cfg))]
67
68mod caller;
69mod channel;
70mod client;
71mod error;
72mod intercept;
73mod lock;
74mod namespace;
75mod openssl_tls;
76mod rpc;
77mod vec;
78
79pub use crate::channel::{BalancedChannelBuilder, Channel};
80pub use crate::client::{Client, ConnectOptions};
81pub use crate::error::Error;
82pub use crate::namespace::{KvClientPrefix, LeaseClientPrefix};
83pub use crate::rpc::auth::{
84    AuthClient, AuthDisableResponse, AuthEnableResponse, AuthenticateResponse, Permission,
85    PermissionType, RoleAddResponse, RoleDeleteResponse, RoleGetResponse,
86    RoleGrantPermissionResponse, RoleListResponse, RoleRevokePermissionOptions,
87    RoleRevokePermissionResponse, UserAddOptions, UserAddResponse, UserChangePasswordResponse,
88    UserDeleteResponse, UserGetResponse, UserGrantRoleResponse, UserListResponse,
89    UserRevokeRoleResponse,
90};
91pub use crate::rpc::cluster::{
92    ClusterClient, Member, MemberAddOptions, MemberAddResponse, MemberListResponse,
93    MemberPromoteResponse, MemberRemoveResponse, MemberUpdateResponse,
94};
95pub use crate::rpc::election::{
96    CampaignResponse, ElectionClient, LeaderKey, LeaderResponse, ObserveStream, ProclaimOptions,
97    ProclaimResponse, ResignOptions, ResignResponse,
98};
99pub use crate::rpc::kv::{
100    CompactionOptions, CompactionResponse, Compare, CompareOp, DeleteOptions, DeleteResponse,
101    GetOptions, GetResponse, KvClient, PutOptions, PutResponse, SortOrder, SortTarget, Txn, TxnOp,
102    TxnOpResponse, TxnResponse,
103};
104pub use crate::rpc::lease::{
105    LeaseClient, LeaseGrantOptions, LeaseGrantResponse, LeaseKeepAliveResponse,
106    LeaseKeepAliveStream, LeaseKeeper, LeaseLeasesResponse, LeaseRevokeResponse, LeaseStatus,
107    LeaseTimeToLiveOptions, LeaseTimeToLiveResponse,
108};
109pub use crate::rpc::lock::{LockClient, LockOptions, LockResponse, UnlockResponse};
110pub use crate::rpc::maintenance::{
111    AlarmAction, AlarmMember, AlarmOptions, AlarmResponse, AlarmType, DefragmentResponse,
112    HashKvResponse, HashResponse, MaintenanceClient, MoveLeaderResponse, SnapshotResponse,
113    SnapshotStreaming, StatusResponse,
114};
115pub use crate::rpc::watch::{
116    Event, EventType, WatchClient, WatchFilterType, WatchOptions, WatchRequestSender,
117    WatchResponse, WatchResponseStream, WatchStream,
118};
119pub use crate::rpc::{KeyValue, ResponseHeader};
120
121#[cfg(feature = "_tls")]
122#[cfg_attr(docsrs, doc(cfg(any(feature = "tls-ring", feature = "tls-aws-lc"))))]
123pub use tonic::transport::{Certificate, ClientTlsConfig as TlsOptions, Identity};
124
125#[cfg(feature = "tls-openssl")]
126#[cfg_attr(docsrs, doc(cfg(feature = "tls-openssl")))]
127pub use crate::openssl_tls::{OpenSslClientConfig, OpenSslResult, SslConnectorBuilder};
128
129/// Exposes internal protobuf representations used to create regular public response types.
130#[cfg(feature = "pub-response-field")]
131#[cfg_attr(docsrs, doc(cfg(feature = "pub-response-field")))]
132pub mod proto {
133    pub use crate::rpc::pb::etcdserverpb::compare::{
134        CompareTarget as PbCompareTarget, TargetUnion as PbTargetUnion,
135    };
136    pub use crate::rpc::pb::etcdserverpb::AlarmMember as PbAlarmMember;
137    pub use crate::rpc::pb::etcdserverpb::{
138        request_op::Request as PbTxnOpRequest, response_op::Response as PbTxnOpResponse,
139        AlarmResponse as PbAlarmResponse, AuthDisableResponse as PbAuthDisableResponse,
140        AuthEnableResponse as PbAuthEnableResponse, AuthRoleAddResponse as PbAuthRoleAddResponse,
141        AuthRoleDeleteResponse as PbAuthRoleDeleteResponse,
142        AuthRoleGetResponse as PbAuthRoleGetResponse,
143        AuthRoleGrantPermissionResponse as PbAuthRoleGrantPermissionResponse,
144        AuthRoleListResponse as PbAuthRoleListResponse,
145        AuthRoleRevokePermissionResponse as PbAuthRoleRevokePermissionResponse,
146        AuthUserAddResponse as PbAuthUserAddResponse,
147        AuthUserChangePasswordResponse as PbAuthUserChangePasswordResponse,
148        AuthUserDeleteResponse as PbAuthUserDeleteResponse,
149        AuthUserGetResponse as PbAuthUserGetResponse,
150        AuthUserGrantRoleResponse as PbAuthUserGrantRoleResponse,
151        AuthUserListResponse as PbAuthUserListResponse,
152        AuthUserRevokeRoleResponse as PbAuthUserRevokeRoleResponse,
153        AuthenticateResponse as PbAuthenticateResponse, CompactionResponse as PbCompactionResponse,
154        Compare as PbCompare, DefragmentResponse as PbDefragmentResponse,
155        DeleteRangeResponse as PbDeleteResponse, HashKvResponse as PbHashKvResponse,
156        HashResponse as PbHashResponse, LeaseGrantResponse as PbLeaseGrantResponse,
157        LeaseKeepAliveResponse as PbLeaseKeepAliveResponse,
158        LeaseLeasesResponse as PbLeaseLeasesResponse, LeaseRevokeResponse as PbLeaseRevokeResponse,
159        LeaseStatus as PbLeaseStatus, LeaseTimeToLiveResponse as PbLeaseTimeToLiveResponse,
160        Member as PbMember, MemberAddResponse as PbMemberAddResponse,
161        MemberListResponse as PbMemberListResponse,
162        MemberPromoteResponse as PbMemberPromoteResponse,
163        MemberRemoveResponse as PbMemberRemoveResponse,
164        MemberUpdateResponse as PbMemberUpdateResponse, MoveLeaderResponse as PbMoveLeaderResponse,
165        PutResponse as PbPutResponse, RangeResponse as PbRangeResponse,
166        RequestOp as PbTxnRequestOp, ResponseHeader as PbResponseHeader,
167        ResponseOp as PbResponseOp, SnapshotResponse as PbSnapshotResponse,
168        StatusResponse as PbStatusResponse, TxnRequest as PbTxnRequest,
169        TxnResponse as PbTxnResponse, WatchResponse as PbWatchResponse,
170    };
171    pub use crate::rpc::pb::mvccpb::Event as PbEvent;
172    pub use crate::rpc::pb::mvccpb::KeyValue as PbKeyValue;
173    pub use crate::rpc::pb::v3electionpb::{
174        CampaignResponse as PbCampaignResponse, LeaderKey as PbLeaderKey,
175        LeaderResponse as PbLeaderResponse, ProclaimResponse as PbProclaimResponse,
176        ResignResponse as PbResignResponse,
177    };
178    pub use crate::rpc::pb::v3lockpb::{
179        LockResponse as PbLockResponse, UnlockResponse as PbUnlockResponse,
180    };
181
182    #[cfg(feature = "build-server")]
183    pub use crate::rpc::pb::etcdserverpb::{
184        auth_server::{Auth as PbAuthService, AuthServer as PbAuthServer},
185        cluster_server::{Cluster as PbClusterService, ClusterServer as PbClusterServer},
186        kv_server::{Kv as PbKvService, KvServer as PbKvServer},
187        lease_server::{Lease as PbLeaseService, LeaseServer as PbLeaseServer},
188        maintenance_server::{
189            Maintenance as PbMaintenanceService, MaintenanceServer as PbMaintenanceServer,
190        },
191        watch_server::{Watch as PbWatchService, WatchServer as PbWatchServer},
192    };
193
194    #[cfg(feature = "build-server")]
195    pub use crate::rpc::pb::etcdserverpb::{
196        AlarmRequest as PbAlarmRequest, AuthDisableRequest as PbAuthDisableRequest,
197        AuthEnableRequest as PbAuthEnableRequest, AuthRoleAddRequest as PbAuthRoleAddRequest,
198        AuthRoleDeleteRequest as PbAuthRoleDeleteRequest,
199        AuthRoleGetRequest as PbAuthRoleGetRequest,
200        AuthRoleGrantPermissionRequest as PbAuthRoleGrantPermissionRequest,
201        AuthRoleListRequest as PbAuthRoleListRequest,
202        AuthRoleRevokePermissionRequest as PbAuthRoleRevokePermissionRequest,
203        AuthUserAddRequest as PbAuthUserAddRequest,
204        AuthUserChangePasswordRequest as PbAuthUserChangePasswordRequest,
205        AuthUserDeleteRequest as PbAuthUserDeleteRequest,
206        AuthUserGetRequest as PbAuthUserGetRequest,
207        AuthUserGrantRoleRequest as PbAuthUserGrantRoleRequest,
208        AuthUserListRequest as PbAuthUserListRequest,
209        AuthUserRevokeRoleRequest as PbAuthUserRevokeRoleRequest,
210        AuthenticateRequest as PbAuthenticateRequest, CompactionRequest as PbCompactionRequest,
211        DefragmentRequest as PbDefragmentRequest, DeleteRangeRequest as PbDeleteRequest,
212        HashKvRequest as PbHashKvRequest, HashRequest as PbHashRequest,
213        LeaseGrantRequest as PbLeaseGrantRequest, LeaseKeepAliveRequest as PbLeaseKeepAliveRequest,
214        LeaseLeasesRequest as PbLeaseLeasesRequest, LeaseRevokeRequest as PbLeaseRevokeRequest,
215        LeaseTimeToLiveRequest as PbLeaseTimeToLiveRequest, MemberAddRequest as PbMemberAddRequest,
216        MemberListRequest as PbMemberListRequest, MemberPromoteRequest as PbMemberPromoteRequest,
217        MemberRemoveRequest as PbMemberRemoveRequest, MemberUpdateRequest as PbMemberUpdateRequest,
218        MoveLeaderRequest as PbMoveLeaderRequest, PutRequest as PbPutRequest,
219        RangeRequest as PbRangeRequest, SnapshotRequest as PbSnapshotRequest,
220        StatusRequest as PbStatusRequest, WatchRequest as PbWatchRequest,
221    };
222
223    #[cfg(feature = "build-server")]
224    pub use crate::rpc::pb::etcdserverpb::watch_request::RequestUnion as PbWatchRequestUnion;
225}
etcd_client/lib.rs

etcd_client/
lib.rs
