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, GetStreamResponse, KvClient, PutOptions, PutResponse, SortOrder,
102    SortTarget, Txn, TxnOp, 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    DowngradeInfo, DowngradeOptions, DowngradeResponse, HashKvResponse, HashResponse,
113    MaintenanceClient, MoveLeaderResponse, SnapshotResponse, 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, DowngradeInfo as PbDowngradeInfo,
156        DowngradeResponse as PbDowngradeResponse, HashKvResponse as PbHashKvResponse,
157        HashResponse as PbHashResponse, LeaseGrantResponse as PbLeaseGrantResponse,
158        LeaseKeepAliveResponse as PbLeaseKeepAliveResponse,
159        LeaseLeasesResponse as PbLeaseLeasesResponse, LeaseRevokeResponse as PbLeaseRevokeResponse,
160        LeaseStatus as PbLeaseStatus, LeaseTimeToLiveResponse as PbLeaseTimeToLiveResponse,
161        Member as PbMember, MemberAddResponse as PbMemberAddResponse,
162        MemberListResponse as PbMemberListResponse,
163        MemberPromoteResponse as PbMemberPromoteResponse,
164        MemberRemoveResponse as PbMemberRemoveResponse,
165        MemberUpdateResponse as PbMemberUpdateResponse, MoveLeaderResponse as PbMoveLeaderResponse,
166        PutResponse as PbPutResponse, RangeResponse as PbRangeResponse,
167        RangeStreamResponse as PbRangeStreamResponse, RequestOp as PbTxnRequestOp,
168        ResponseHeader as PbResponseHeader, ResponseOp as PbResponseOp,
169        SnapshotResponse as PbSnapshotResponse, StatusResponse as PbStatusResponse,
170        TxnRequest as PbTxnRequest, TxnResponse as PbTxnResponse, WatchResponse as PbWatchResponse,
171    };
172    pub use crate::rpc::pb::mvccpb::Event as PbEvent;
173    pub use crate::rpc::pb::mvccpb::KeyValue as PbKeyValue;
174    pub use crate::rpc::pb::v3electionpb::{
175        CampaignResponse as PbCampaignResponse, LeaderKey as PbLeaderKey,
176        LeaderResponse as PbLeaderResponse, ProclaimResponse as PbProclaimResponse,
177        ResignResponse as PbResignResponse,
178    };
179    pub use crate::rpc::pb::v3lockpb::{
180        LockResponse as PbLockResponse, UnlockResponse as PbUnlockResponse,
181    };
182
183    #[cfg(feature = "build-server")]
184    pub use crate::rpc::pb::etcdserverpb::{
185        auth_server::{Auth as PbAuthService, AuthServer as PbAuthServer},
186        cluster_server::{Cluster as PbClusterService, ClusterServer as PbClusterServer},
187        kv_server::{Kv as PbKvService, KvServer as PbKvServer},
188        lease_server::{Lease as PbLeaseService, LeaseServer as PbLeaseServer},
189        maintenance_server::{
190            Maintenance as PbMaintenanceService, MaintenanceServer as PbMaintenanceServer,
191        },
192        watch_server::{Watch as PbWatchService, WatchServer as PbWatchServer},
193    };
194
195    #[cfg(feature = "build-server")]
196    pub use crate::rpc::pb::etcdserverpb::{
197        AlarmRequest as PbAlarmRequest, AuthDisableRequest as PbAuthDisableRequest,
198        AuthEnableRequest as PbAuthEnableRequest, AuthRoleAddRequest as PbAuthRoleAddRequest,
199        AuthRoleDeleteRequest as PbAuthRoleDeleteRequest,
200        AuthRoleGetRequest as PbAuthRoleGetRequest,
201        AuthRoleGrantPermissionRequest as PbAuthRoleGrantPermissionRequest,
202        AuthRoleListRequest as PbAuthRoleListRequest,
203        AuthRoleRevokePermissionRequest as PbAuthRoleRevokePermissionRequest,
204        AuthUserAddRequest as PbAuthUserAddRequest,
205        AuthUserChangePasswordRequest as PbAuthUserChangePasswordRequest,
206        AuthUserDeleteRequest as PbAuthUserDeleteRequest,
207        AuthUserGetRequest as PbAuthUserGetRequest,
208        AuthUserGrantRoleRequest as PbAuthUserGrantRoleRequest,
209        AuthUserListRequest as PbAuthUserListRequest,
210        AuthUserRevokeRoleRequest as PbAuthUserRevokeRoleRequest,
211        AuthenticateRequest as PbAuthenticateRequest, CompactionRequest as PbCompactionRequest,
212        DefragmentRequest as PbDefragmentRequest, DeleteRangeRequest as PbDeleteRequest,
213        DowngradeRequest as PbDowngradeRequest, HashKvRequest as PbHashKvRequest,
214        HashRequest as PbHashRequest, LeaseGrantRequest as PbLeaseGrantRequest,
215        LeaseKeepAliveRequest as PbLeaseKeepAliveRequest,
216        LeaseLeasesRequest as PbLeaseLeasesRequest, LeaseRevokeRequest as PbLeaseRevokeRequest,
217        LeaseTimeToLiveRequest as PbLeaseTimeToLiveRequest, MemberAddRequest as PbMemberAddRequest,
218        MemberListRequest as PbMemberListRequest, MemberPromoteRequest as PbMemberPromoteRequest,
219        MemberRemoveRequest as PbMemberRemoveRequest, MemberUpdateRequest as PbMemberUpdateRequest,
220        MoveLeaderRequest as PbMoveLeaderRequest, PutRequest as PbPutRequest,
221        RangeRequest as PbRangeRequest, SnapshotRequest as PbSnapshotRequest,
222        StatusRequest as PbStatusRequest, WatchRequest as PbWatchRequest,
223    };
224
225    #[cfg(feature = "build-server")]
226    pub use crate::rpc::pb::etcdserverpb::watch_request::RequestUnion as PbWatchRequestUnion;
227}
etcd_client/lib.rs

etcd_client/
lib.rs
