From e928b0355747f05959fbb41f924f41fac4287e3f Mon Sep 17 00:00:00 2001 From: bsbds <69835502+bsbds@users.noreply.github.com> Date: Mon, 10 Jul 2023 18:53:13 +0800 Subject: [PATCH] docs: update docs of auth client Signed-off-by: bsbds <69835502+bsbds@users.noreply.github.com> --- xline-client/src/clients/auth.rs | 43 +++++++++++----------- xline-client/src/types/auth.rs | 63 ++++++++++++++++++++++---------- 2 files changed, 65 insertions(+), 41 deletions(-) diff --git a/xline-client/src/clients/auth.rs b/xline-client/src/clients/auth.rs index 76985bda7..51ae5b1a3 100644 --- a/xline-client/src/clients/auth.rs +++ b/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>, /// The auth RPC client, only communicate with one server at a time auth_client: xlineapi::AuthClient>, - /// Auth token + /// The auth token token: Option, } 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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, diff --git a/xline-client/src/types/auth.rs b/xline-client/src/types/auth.rs index b055bcd8f..4d6b996fe 100644 --- a/xline-client/src/types/auth.rs +++ b/xline-client/src/types/auth.rs @@ -9,7 +9,9 @@ pub struct AuthenticateRequest { } impl AuthenticateRequest { - /// New `AuthenticateRequest` + /// Creates a new `AuthenticateRequest`. + /// `name` is the name of the user to authenticate, + /// `password` is the password of the user. #[inline] pub fn new(name: impl Into, password: impl Into) -> Self { Self { @@ -36,7 +38,8 @@ pub struct AuthUserAddRequest { } impl AuthUserAddRequest { - /// New `AuthUserAddRequest` + /// Creates a new `AuthUserAddRequest`. + /// `name` is the name of the user to add. #[inline] pub fn new(name: impl Into) -> Self { Self { @@ -47,7 +50,7 @@ impl AuthUserAddRequest { } } - /// Set password. + /// Sets the password. #[inline] #[must_use] pub fn with_pwd(mut self, password: impl Into) -> Self { @@ -55,7 +58,7 @@ impl AuthUserAddRequest { self } - /// Set no password. + /// If set, Xline will add the user without password, password set with `with_pwd` will be ignored. #[inline] #[must_use] pub const fn with_no_pwd(mut self) -> Self { @@ -79,7 +82,8 @@ pub struct AuthUserGetRequest { } impl AuthUserGetRequest { - /// New `AuthUserGetRequest` + /// Creates a new `AuthUserGetRequest`. + /// `name` is the name of the user to get #[inline] pub fn new(name: impl Into) -> Self { Self { @@ -103,7 +107,8 @@ pub struct AuthUserDeleteRequest { } impl AuthUserDeleteRequest { - /// New `AuthUserDeleteRequest` + /// Creates a new `AuthUserDeleteRequest`. + /// `name` is the name of the user to delete. #[inline] pub fn new(name: impl Into) -> Self { Self { @@ -127,7 +132,9 @@ pub struct AuthUserChangePasswordRequest { } impl AuthUserChangePasswordRequest { - /// New `AuthUserChangePasswordRequest` + /// Creates a new `AuthUserChangePasswordRequest`. + /// `name` is the name of the user to change password, + /// `password` is the new password of the user. #[inline] pub fn new(name: impl Into, password: impl Into) -> Self { Self { @@ -155,7 +162,9 @@ pub struct AuthUserGrantRoleRequest { } impl AuthUserGrantRoleRequest { - /// New `AuthUserGrantRoleRequest` + /// Creates a new `AuthUserGrantRoleRequest` + /// `name` is the name of the user to grant role, + /// `role` is the role name to grant. #[inline] pub fn new(name: impl Into, role: impl Into) -> Self { Self { @@ -182,7 +191,9 @@ pub struct AuthUserRevokeRoleRequest { } impl AuthUserRevokeRoleRequest { - /// New `AuthUserRevokeRoleRequest` + /// Creates a new `AuthUserRevokeRoleRequest` + /// `name` is the name of the user to revoke role, + /// `role` is the role name to revoke. #[inline] pub fn new(name: impl Into, role: impl Into) -> Self { Self { @@ -209,7 +220,8 @@ pub struct AuthRoleAddRequest { } impl AuthRoleAddRequest { - /// New `AuthRoleAddRequest` + /// Creates a new `AuthRoleAddRequest` + /// `role` is the name of the role to add. #[inline] pub fn new(role: impl Into) -> Self { Self { @@ -233,7 +245,8 @@ pub struct AuthRoleGetRequest { } impl AuthRoleGetRequest { - /// New `AuthRoleGetRequest` + /// Creates a new `AuthRoleGetRequest` + /// `role` is the name of the role to get. #[inline] pub fn new(role: impl Into) -> Self { Self { @@ -257,7 +270,8 @@ pub struct AuthRoleDeleteRequest { } impl AuthRoleDeleteRequest { - /// New `AuthRoleDeleteRequest` + /// Creates a new `AuthRoleDeleteRequest` + /// `role` is the name of the role to delete. #[inline] pub fn new(role: impl Into) -> Self { Self { @@ -281,7 +295,9 @@ pub struct AuthRoleGrantPermissionRequest { } impl AuthRoleGrantPermissionRequest { - /// New `AuthRoleGrantPermissionRequest` + /// Creates a new `AuthRoleGrantPermissionRequest` + /// `role` is the name of the role to grant permission, + /// `perm` is the permission name to grant. #[inline] pub fn new(role: impl Into, perm: Permission) -> Self { Self { @@ -308,7 +324,9 @@ pub struct AuthRoleRevokePermissionRequest { } impl AuthRoleRevokePermissionRequest { - /// Create a new `RoleRevokePermissionOption` from pb role revoke permission. + /// Creates a new `RoleRevokePermissionOption` from pb role revoke permission. + /// `role` is the name of the role to revoke permission, + /// `key` is the key to revoke from the role. #[inline] pub fn new(role: impl Into, key: impl Into>) -> Self { Self { @@ -320,7 +338,7 @@ impl AuthRoleRevokePermissionRequest { } } - /// Set `key` and `range_end` when with prefix + /// If set, Xline will return all keys with the matching prefix #[inline] #[must_use] pub fn with_prefix(mut self) -> Self { @@ -333,7 +351,7 @@ impl AuthRoleRevokePermissionRequest { self } - /// Set `key` and `range_end` when with from key + /// If set, Xline will return all keys that are equal or greater than the given key #[inline] #[must_use] pub fn with_from_key(mut self) -> Self { @@ -344,7 +362,8 @@ impl AuthRoleRevokePermissionRequest { self } - /// Set `range_end` + /// `range_end` is the upper bound on the requested range \[key,` range_en`d). + /// If `range_end` is '\0', the range is all keys >= key. #[inline] #[must_use] pub fn with_range_end(mut self, range_end: impl Into>) -> Self { @@ -369,6 +388,8 @@ pub struct Permission { impl Permission { /// Creates a permission with operation type and key + /// `perm_type` is the permission type, + /// `key` is the key to grant with the permission. #[inline] #[must_use] pub fn new(perm_type: PermissionType, key: impl Into>) -> Self { @@ -380,7 +401,8 @@ impl Permission { }, } } - /// Set `key` and `range_end` when with prefix + + /// If set, Xline will return all keys with the matching prefix #[inline] #[must_use] pub fn with_prefix(mut self) -> Self { @@ -393,7 +415,7 @@ impl Permission { self } - /// Set `key` and `range_end` when with from key + /// If set, Xline will return all keys that are equal or greater than the given key #[inline] #[must_use] pub fn with_from_key(mut self) -> Self { @@ -404,7 +426,8 @@ impl Permission { self } - /// Set `range_end` + /// `range_end` is the upper bound on the requested range \[key,` range_en`d). + /// If `range_end` is '\0', the range is all keys >= key. #[inline] #[must_use] pub fn with_range_end(mut self, range_end: impl Into>) -> Self {