Skip to content

Commit

Permalink
docs: update docs of auth client
Browse files Browse the repository at this point in the history 
Signed-off-by: bsbds <[email protected]>
  • Loading branch information
@bsbds
bsbds committed Jul 11, 2023
1 parent ea79b38 commit e928b03
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 41 deletions.
43 changes: 22 additions & 21 deletions xline-client/src/clients/auth.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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() {
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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() {
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down
63 changes: 43 additions & 20 deletions xline-client/src/types/auth.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<String>, password: impl Into<String>) -> Self {
Self {
Expand All @@ -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<String>) -> Self {
Self {
Expand All @@ -47,15 +50,15 @@ impl AuthUserAddRequest {
}
}

/// Set password.
/// Sets the password.
#[inline]
#[must_use]
pub fn with_pwd(mut self, password: impl Into<String>) -> Self {
self.inner.password = password.into();
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 {
Expand All @@ -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<String>) -> Self {
Self {
Expand All @@ -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<String>) -> Self {
Self {
Expand All @@ -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<String>, password: impl Into<String>) -> Self {
Self {
Expand Down Expand Up @@ -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<String>, role: impl Into<String>) -> Self {
Self {
Expand All @@ -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<String>, role: impl Into<String>) -> Self {
Self {
Expand All @@ -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<String>) -> Self {
Self {
Expand All @@ -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<String>) -> Self {
Self {
Expand All @@ -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<String>) -> Self {
Self {
Expand All @@ -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<String>, perm: Permission) -> Self {
Self {
Expand All @@ -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<String>, key: impl Into<Vec<u8>>) -> Self {
Self {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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<Vec<u8>>) -> Self {
Expand All @@ -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<Vec<u8>>) -> Self {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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<Vec<u8>>) -> Self {
Expand Down

0 comments on commit e928b03

Please sign in to comment.