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

etcd_client/
lib.rs
