doc: update xline client document

xline-client/examples/kv.rs

@@ -1,7 +1,7 @@
 use xline_client::{
     error::ClientError as Error,
     types::kv::{
-        CompactionRequest, Compare, DeleteRangeRequest, PutRequest, RangeRequest, Txn, TxnOp,
+        CompactionRequest, Compare, DeleteRangeRequest, PutRequest, RangeRequest, TxnOp, TxnRequest,
     },
     Client, ClientOptions,
 };
@@ -49,7 +49,7 @@ async fn main() -> Result<(), Error> {
     }
 
     // txn
-    let txn_req = Txn::new()
+    let txn_req = TxnRequest::new()
         .when(&[Compare::value("key2", CompareResult::Equal, "value2")][..])
         .and_then(
             &[TxnOp::put(

xline-client/src/clients/auth.rs

@@ -31,18 +31,18 @@ use crate::{
 /// Client for Auth operations.
 #[derive(Clone, Debug)]
 pub struct AuthClient {
-    /// Name of the AuthClient
+    /// Name of the AuthClient, which will be used in CURP propose id generation
     name: String,
     /// The client running the CURP protocol, communicate with all servers.
     curp_client: Arc<CurpClient<Command>>,
     /// The auth RPC client, only communicate with one server at a time
     auth_client: xlineapi::AuthClient<AuthService<Channel>>,
-    /// Auth token
+    /// The auth token
     token: Option<String>,
 }
 
 impl AuthClient {
-    /// New `AuthClient`
+    /// Creates a new `AuthClient`
     #[inline]
     pub fn new(
         name: String,
@@ -65,7 +65,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn auth_enable(&self) -> Result<AuthEnableResponse> {
         self.handle_req(xlineapi::AuthEnableRequest {}, false).await
@@ -75,28 +75,28 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn auth_disable(&self) -> Result<AuthDisableResponse> {
         self.handle_req(xlineapi::AuthDisableRequest {}, false)
             .await
     }
 
-    /// Get auth status.
+    /// Gets authentication status.
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn auth_status(&self) -> Result<AuthStatusResponse> {
         self.handle_req(xlineapi::AuthStatusRequest {}, true).await
     }
 
-    /// Get token through authenticate
+    /// Process an authentication request, and return the auth token
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn authenticate(
         &mut self,
@@ -113,7 +113,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_add(&self, mut request: AuthUserAddRequest) -> Result<AuthUserAddResponse> {
         if request.inner.name.is_empty() {
@@ -139,7 +139,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_get(&self, request: AuthUserGetRequest) -> Result<AuthUserGetResponse> {
         self.handle_req(request.inner, true).await
@@ -149,7 +149,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_list(&self) -> Result<AuthUserListResponse> {
         self.handle_req(xlineapi::AuthUserListRequest {}, true)
@@ -160,7 +160,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_delete(
         &self,
@@ -173,7 +173,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_change_password(
         &self,
@@ -192,7 +192,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_grant_role(
         &self,
@@ -205,7 +205,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn user_revoke_role(
         &self,
@@ -218,7 +218,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn role_add(&self, request: AuthRoleAddRequest) -> Result<AuthRoleAddResponse> {
         if request.inner.name.is_empty() {
@@ -231,7 +231,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn role_get(&self, request: AuthRoleGetRequest) -> Result<AuthRoleGetResponse> {
         self.handle_req(request.inner, true).await
@@ -241,7 +241,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn role_list(&self) -> Result<AuthRoleListResponse> {
         self.handle_req(xlineapi::AuthRoleListRequest {}, true)
@@ -252,7 +252,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn role_delete(
         &self,
@@ -265,7 +265,7 @@ impl AuthClient {
     ///
     /// # Errors
     ///
-    /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn role_grant_permission(
         &self,
@@ -284,6 +284,7 @@ impl AuthClient {
     /// # Errors
     ///
     /// If request fails to send
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn role_revoke_permission(
         &self,

xline-client/src/clients/kv.rs

@@ -10,36 +10,40 @@ use xlineapi::{
 
 use crate::{
     error::Result,
-    types::kv::{CompactionRequest, DeleteRangeRequest, PutRequest, RangeRequest, Txn},
+    types::kv::{CompactionRequest, DeleteRangeRequest, PutRequest, RangeRequest, TxnRequest},
 };
 
 /// Client for KV operations.
 #[derive(Clone, Debug)]
 pub struct KvClient {
-    /// Name of the KvClient
+    /// Name of the kv client, which will be used in CURP propose id generation
     name: String,
     /// The client running the CURP protocol, communicate with all servers.
     curp_client: Arc<CurpClient<Command>>,
-    /// Auth token
+    /// The auth token
     token: Option<String>,
 }
 
 impl KvClient {
     /// New `KvClient`
     #[inline]
-    pub fn new(name: String, curp_client: Arc<CurpClient<Command>>, token: Option<String>) -> Self {
+    pub(crate) fn new(
+        name: String,
+        curp_client: Arc<CurpClient<Command>>,
+        token: Option<String>,
+    ) -> Self {
         Self {
             name,
             curp_client,
             token,
         }
     }
 
-    /// Send `PutRequest` by `CurpClient`
+    /// Put a key-value into the store
     ///
     /// # Errors
     ///
-    /// If `CurpClient` failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn put(&self, request: PutRequest) -> Result<PutResponse> {
         let key_ranges = vec![KeyRange::new_one_key(request.key())];
@@ -53,11 +57,11 @@ impl KvClient {
         Ok(cmd_res.decode().into())
     }
 
-    /// Send `RangeRequest` by `CurpClient`
+    /// Get a range of keys from the store
     ///
     /// # Errors
     ///
-    /// If `CurpClient` failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn range(&self, request: RangeRequest) -> Result<RangeResponse> {
         let key_ranges = vec![KeyRange::new(request.key(), request.range_end())];
@@ -71,11 +75,11 @@ impl KvClient {
         Ok(cmd_res.decode().into())
     }
 
-    /// Send `DeleteRangeRequest` by `CurpClient`
+    /// Delete a range of keys from the store
     ///
     /// # Errors
     ///
-    /// If `CurpClient` failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn delete(&self, request: DeleteRangeRequest) -> Result<DeleteRangeResponse> {
         let key_ranges = vec![KeyRange::new(request.key(), request.range_end())];
@@ -89,22 +93,22 @@ impl KvClient {
         Ok(cmd_res.decode().into())
     }
 
-    /// Send `TxnRequest` by `CurpClient`
+    /// Creates a transaction, which can provide serializable writes
     ///
     /// # Errors
     ///
-    /// If `CurpClient` failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
-    pub async fn txn(&self, txn: Txn) -> Result<TxnResponse> {
-        let key_ranges = txn
-            .req
+    pub async fn txn(&self, request: TxnRequest) -> Result<TxnResponse> {
+        let key_ranges = request
+            .inner
             .compare
             .iter()
             .map(|cmp| KeyRange::new(cmp.key.as_slice(), cmp.range_end.as_slice()))
             .collect();
         let propose_id = self.generate_propose_id();
         let request = RequestWithToken::new_with_token(
-            xlineapi::TxnRequest::from(txn).into(),
+            xlineapi::TxnRequest::from(request).into(),
             self.token.clone(),
         );
         let cmd = Command::new(key_ranges, request, propose_id);

xline-client/src/clients/lease.rs

@@ -23,7 +23,7 @@ use crate::{
 /// Client for Lease operations.
 #[derive(Clone, Debug)]
 pub struct LeaseClient {
-    /// Name of the LeaseClient
+    /// Name of the LeaseClient, which will be used in CURP propose id generation
     name: String,
     /// The client running the CURP protocol, communicate with all servers.
     curp_client: Arc<CurpClient<Command>>,
@@ -36,7 +36,7 @@ pub struct LeaseClient {
 }
 
 impl LeaseClient {
-    /// New `LeaseClient`
+    /// Creates a new `LeaseClient`
     #[inline]
     pub fn new(
         name: String,
@@ -57,11 +57,13 @@ impl LeaseClient {
         }
     }
 
-    /// Send `LeaseGrantRequest` by `CurpClient`
+    /// Creates a lease which expires if the server does not receive a keepAlive
+    /// within a given time to live period. All keys attached to the lease will be expired and
+    /// deleted if the lease expires. Each expired key generates a delete event in the event history.
     ///
     /// # Errors
     ///
-    /// If `CurpClient` failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn grant(&self, mut request: LeaseGrantRequest) -> Result<LeaseGrantResponse> {
         let propose_id = self.generate_propose_id();
@@ -77,22 +79,23 @@ impl LeaseClient {
         Ok(cmd_res.decode().into())
     }
 
-    /// Send `LeaseRevokeRequest` by `CurpClient`
+    /// Revokes a lease. All keys attached to the lease will expire and be deleted.
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn revoke(&mut self, request: LeaseRevokeRequest) -> Result<LeaseRevokeResponse> {
         let res = self.lease_client.lease_revoke(request.inner).await?;
         Ok(res.into_inner())
     }
 
-    /// Send `LeaseKeepAliveRequest` by `CurpClient`
+    /// Keeps the lease alive by streaming keep alive requests from the client
+    /// to the server and streaming keep alive responses from the server to the client.
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn keep_alive(
         &mut self,
@@ -122,11 +125,11 @@ impl LeaseClient {
         Ok((LeaseKeeper::new(id, sender), stream))
     }
 
-    /// Send `LeaseTimeToLiveRequest` by `CurpClient`
+    /// Retrieves lease information.
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn time_to_live(
         &mut self,
@@ -143,7 +146,7 @@ impl LeaseClient {
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn leases(&self) -> Result<LeaseLeasesResponse> {
         let propose_id = self.generate_propose_id();