From d06b2abea40d8d3d953c3fc5094be8ce357b9f37 Mon Sep 17 00:00:00 2001 From: mbecker20 Date: Sun, 28 Apr 2024 01:04:36 -0700 Subject: [PATCH] doccos --- bin/core/src/api/execute/build.rs | 12 +++-- bin/core/src/api/write/build.rs | 10 ++++ bin/core/src/api/write/server.rs | 8 ++-- bin/core/src/cloud/aws.rs | 11 ++--- bin/core/src/config.rs | 3 +- client/core/rs/src/api/auth.rs | 53 ++++++++++++++++----- client/core/rs/src/api/mod.rs | 5 ++ client/core/rs/src/api/write/api_key.rs | 31 +++++++++--- client/core/rs/src/api/write/description.rs | 7 +-- client/core/rs/src/api/write/launch.rs | 29 ++++++++++- client/core/rs/src/api/write/permissions.rs | 18 +++++-- client/core/rs/src/api/write/procedure.rs | 18 +++++++ client/core/rs/src/api/write/server.rs | 14 ++++-- client/core/rs/src/api/write/tags.rs | 16 +++++-- client/core/rs/src/api/write/user.rs | 24 +++++++--- client/core/rs/src/api/write/user_group.rs | 15 +++--- 16 files changed, 211 insertions(+), 63 deletions(-) diff --git a/bin/core/src/api/execute/build.rs b/bin/core/src/api/execute/build.rs index e6457c035..58bdeec02 100644 --- a/bin/core/src/api/execute/build.rs +++ b/bin/core/src/api/execute/build.rs @@ -4,8 +4,9 @@ use anyhow::{anyhow, Context}; use async_trait::async_trait; use futures::future::join_all; use monitor_client::{ - api::execute::{ - CancelBuild, CancelBuildResponse, Deploy, RunBuild, + api::{ + execute::{CancelBuild, CancelBuildResponse, Deploy, RunBuild}, + write::LaunchAwsServerConfig, }, entities::{ all_logs_success, @@ -342,8 +343,11 @@ async fn get_aws_builder( build.name, build.config.version.to_string() ); - let Ec2Instance { instance_id, ip } = - launch_ec2_instance(&instance_name, &config).await?; + let Ec2Instance { instance_id, ip } = launch_ec2_instance( + &instance_name, + LaunchAwsServerConfig::from_builder_config(&config), + ) + .await?; info!("ec2 instance launched"); diff --git a/bin/core/src/api/write/build.rs b/bin/core/src/api/write/build.rs index 5fe6d8b7b..1eb1ca38f 100644 --- a/bin/core/src/api/write/build.rs +++ b/bin/core/src/api/write/build.rs @@ -39,6 +39,11 @@ impl Resolve for State { CreateBuild { name, mut config }: CreateBuild, user: User, ) -> anyhow::Result { + if !user.admin && !user.create_build_permissions { + return Err(anyhow!( + "User does not have create build permissions." + )); + } let name = to_monitor_name(&name); if ObjectId::from_str(&name).is_ok() { return Err(anyhow!("valid ObjectIds cannot be used as names")); @@ -102,6 +107,11 @@ impl Resolve for State { CopyBuild { name, id }: CopyBuild, user: User, ) -> anyhow::Result { + if !user.admin && !user.create_build_permissions { + return Err(anyhow!( + "User does not have create build permissions." + )); + } let name = to_monitor_name(&name); let Build { config, diff --git a/bin/core/src/api/write/server.rs b/bin/core/src/api/write/server.rs index ce377d9db..5ef67174c 100644 --- a/bin/core/src/api/write/server.rs +++ b/bin/core/src/api/write/server.rs @@ -286,11 +286,11 @@ impl Resolve for State { #[instrument(name = "CreateNetwork", skip(self, user))] async fn resolve( &self, - CreateNetwork { server_id, name }: CreateNetwork, + CreateNetwork { server, name }: CreateNetwork, user: User, ) -> anyhow::Result { let server = Server::get_resource_check_permissions( - &server_id, + &server, &user, PermissionLevel::Write, ) @@ -324,11 +324,11 @@ impl Resolve for State { #[instrument(name = "DeleteNetwork", skip(self, user))] async fn resolve( &self, - DeleteNetwork { server_id, name }: DeleteNetwork, + DeleteNetwork { server, name }: DeleteNetwork, user: User, ) -> anyhow::Result { let server = Server::get_resource_check_permissions( - &server_id, + &server, &user, PermissionLevel::Write, ) diff --git a/bin/core/src/cloud/aws.rs b/bin/core/src/cloud/aws.rs index 593aad6a8..52502232f 100644 --- a/bin/core/src/cloud/aws.rs +++ b/bin/core/src/cloud/aws.rs @@ -52,13 +52,10 @@ async fn create_ec2_client(region: String) -> Client { } #[instrument] -pub async fn launch_ec2_instance( +pub async fn launch_ec2_instance( name: &str, - config: T, -) -> anyhow::Result -where - T: Into + std::fmt::Debug, -{ + config: LaunchAwsServerConfig, +) -> anyhow::Result { let LaunchAwsServerConfig { region, instance_type, @@ -69,7 +66,7 @@ where key_pair_name, assign_public_ip, use_public_ip, - } = config.into(); + } = config; let instance_type = handle_unknown_instance_type( InstanceType::from(instance_type.as_str()), )?; diff --git a/bin/core/src/config.rs b/bin/core/src/config.rs index 1551dac15..f304c686c 100644 --- a/bin/core/src/config.rs +++ b/bin/core/src/config.rs @@ -177,7 +177,8 @@ pub struct CoreConfig { #[serde(default = "default_title")] pub title: String, - /// The host to use with oauth redirect url, whatever host the user hits to access monitor. eg 'https://monitor.mogh.tech' + /// The host to use with oauth redirect url, whatever host + /// the user hits to access monitor. eg `https://monitor.mogh.tech` #[serde(default)] pub host: String, diff --git a/client/core/rs/src/api/auth.rs b/client/core/rs/src/api/auth.rs index 1f615cc8a..7dc99e3cd 100644 --- a/client/core/rs/src/api/auth.rs +++ b/client/core/rs/src/api/auth.rs @@ -7,8 +7,19 @@ use crate::entities::user::User; pub trait MonitorAuthRequest: HasResponse {} +/// JSON containing an authentication token. +#[typeshare] +#[derive(Serialize, Deserialize, Debug, Clone)] +pub struct JwtResponse { + /// A token the user can use to authenticate their requests. + pub jwt: String, +} + // +/// Non authenticated route to see the available options +/// users have to login to monitor, eg. local auth, github, google. +/// Response: [GetLoginOptionsResponse]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -17,16 +28,25 @@ pub trait MonitorAuthRequest: HasResponse {} #[response(GetLoginOptionsResponse)] pub struct GetLoginOptions {} +/// The response for [GetLoginOptions]. #[typeshare] #[derive(Serialize, Deserialize, Debug, Clone, Copy)] pub struct GetLoginOptionsResponse { + /// Whether local auth is enabled. pub local: bool, + /// Whether github login is enabled. pub github: bool, + /// Whether google login is enabled. pub google: bool, } // +/// Create a new local user account. Will fail if a user with the +/// given username already exists. +/// Response: [CreateLocalUserResponse]. +/// +/// Note. This method is only available if the core api has `local_auth` enabled. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -34,18 +54,23 @@ pub struct GetLoginOptionsResponse { #[empty_traits(MonitorAuthRequest)] #[response(CreateLocalUserResponse)] pub struct CreateLocalUser { + /// The username for the new user. pub username: String, + /// The password for the new user. + /// This cannot be retreived later. pub password: String, } +/// Response for [CreateLocalUser]. #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct CreateLocalUserResponse { - pub jwt: String, -} +pub type CreateLocalUserResponse = JwtResponse; // +/// Login as a local user. Will fail if the users credentials don't match +/// any local user. +/// +/// Note. This method is only available if the core api has `local_auth` enabled. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -53,18 +78,21 @@ pub struct CreateLocalUserResponse { #[empty_traits(MonitorAuthRequest)] #[response(LoginLocalUserResponse)] pub struct LoginLocalUser { + /// The user's username pub username: String, + /// The user's password pub password: String, } +/// The response for [LoginLocalUser] #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct LoginLocalUserResponse { - pub jwt: String, -} +pub type LoginLocalUserResponse = JwtResponse; // +/// Exchange a single use exchange token (safe for transport in url query) +/// for a jwt. +/// Response: [ExchangeForJwtResponse]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -72,17 +100,18 @@ pub struct LoginLocalUserResponse { #[empty_traits(MonitorAuthRequest)] #[response(ExchangeForJwtResponse)] pub struct ExchangeForJwt { + /// The 'exchange token' pub token: String, } +/// Response for [ExchangeForJwt]. #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct ExchangeForJwtResponse { - pub jwt: String, -} +pub type ExchangeForJwtResponse = JwtResponse; // +/// Get the user extracted from the request headers. +/// Response: [User]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, diff --git a/client/core/rs/src/api/mod.rs b/client/core/rs/src/api/mod.rs index 55f891e40..c364a4591 100644 --- a/client/core/rs/src/api/mod.rs +++ b/client/core/rs/src/api/mod.rs @@ -1,3 +1,8 @@ +//! # Monitor core API +//! +//! Monitor core exposes an HTTP api using standard JSON serialization. +//! + pub mod auth; pub mod execute; pub mod read; diff --git a/client/core/rs/src/api/write/api_key.rs b/client/core/rs/src/api/write/api_key.rs index 68128220f..1d940f9a1 100644 --- a/client/core/rs/src/api/write/api_key.rs +++ b/client/core/rs/src/api/write/api_key.rs @@ -3,12 +3,17 @@ use resolver_api::derive::Request; use serde::{Deserialize, Serialize}; use typeshare::typeshare; -use crate::entities::I64; +use crate::entities::{NoData, I64}; use super::MonitorWriteRequest; // +/// Create an api key for the calling user. +/// Response: [CreateApiKeyResponse]. +/// +/// Note. After the response is served, there will be no way +/// to get the secret later. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -16,12 +21,16 @@ use super::MonitorWriteRequest; #[empty_traits(MonitorWriteRequest)] #[response(CreateApiKeyResponse)] pub struct CreateApiKey { + /// The name for the api key. pub name: String, + /// A unix timestamp in millseconds specifying api key expire time. + /// Default is 0, which means no expiry. #[serde(default)] pub expires: I64, } +/// Response for [CreateApiKey]. #[typeshare] #[derive(Serialize, Deserialize, Debug, Clone)] pub struct CreateApiKeyResponse { @@ -29,12 +38,16 @@ pub struct CreateApiKeyResponse { pub key: String, /// X-API-SECRET + /// + /// Note. /// There is no way to get the secret again after it is distributed in this message pub secret: String, } // +/// Delete an api key for the calling user. +/// Response: [NoData] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -42,16 +55,17 @@ pub struct CreateApiKeyResponse { #[empty_traits(MonitorWriteRequest)] #[response(DeleteApiKeyResponse)] pub struct DeleteApiKey { + /// The key which the user intends to delete. pub key: String, } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct DeleteApiKeyResponse {} +pub type DeleteApiKeyResponse = NoData; // -/// ADMIN ONLY +/// Admin only method to create an api key for a service user. +/// Response: [CreateApiKeyResponse]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -61,7 +75,10 @@ pub struct DeleteApiKeyResponse {} pub struct CreateApiKeyForServiceUser { /// Must be service user pub user_id: String, + /// The name for the api key pub name: String, + /// A unix timestamp in millseconds specifying api key expire time. + /// Default is 0, which means no expiry. #[serde(default)] pub expires: I64, } @@ -71,7 +88,8 @@ pub type CreateApiKeyForServiceUserResponse = CreateApiKeyResponse; // -/// ADMIN ONLY +/// Admin only method to delete an api key for a service user. +/// Response: [NoData]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -83,5 +101,4 @@ pub struct DeleteApiKeyForServiceUser { } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct DeleteApiKeyForServiceUserResponse {} +pub type DeleteApiKeyForServiceUserResponse = NoData; diff --git a/client/core/rs/src/api/write/description.rs b/client/core/rs/src/api/write/description.rs index 063b6f4b0..b3dfadd5f 100644 --- a/client/core/rs/src/api/write/description.rs +++ b/client/core/rs/src/api/write/description.rs @@ -3,10 +3,12 @@ use resolver_api::derive::Request; use serde::{Deserialize, Serialize}; use typeshare::typeshare; -use crate::entities::update::ResourceTarget; +use crate::entities::{update::ResourceTarget, NoData}; use super::MonitorWriteRequest; +/// Update a resources description. +/// Response: [NoData]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -19,5 +21,4 @@ pub struct UpdateDescription { } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct UpdateDescriptionResponse {} +pub type UpdateDescriptionResponse = NoData; diff --git a/client/core/rs/src/api/write/launch.rs b/client/core/rs/src/api/write/launch.rs index 0f22f51ec..9deee7d0f 100644 --- a/client/core/rs/src/api/write/launch.rs +++ b/client/core/rs/src/api/write/launch.rs @@ -7,6 +7,8 @@ use crate::entities::{builder::AwsBuilderConfig, update::Update}; use super::MonitorWriteRequest; +/// Launch an EC2 instance with the specified config. +/// Response: [Update]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -14,43 +16,66 @@ use super::MonitorWriteRequest; #[empty_traits(MonitorWriteRequest)] #[response(Update)] pub struct LaunchServer { + /// The name of the created server. pub name: String, + /// The configuration used to launch the server. pub config: LaunchServerConfig, } +/// The cloud specific config. #[typeshare] #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(tag = "type", content = "params")] pub enum LaunchServerConfig { + /// Launch a server on AWS. Aws(LaunchAwsServerConfig), } +/// Aws EC2 instance config. #[typeshare] #[derive(Serialize, Deserialize, Debug, Clone)] pub struct LaunchAwsServerConfig { + /// The aws region to launch the server in, eg. us-east-1 pub region: String, + /// The instance type to launch, eg. c5.2xlarge pub instance_type: String, + /// Specify the EBS volumes to attach. pub volumes: Vec, + /// Specify the ami id to use. Must be set up to start the periphery binary on startup. pub ami_id: String, + /// The subnet to assign to the instance. pub subnet_id: String, + /// The security groups to give to the instance. pub security_group_ids: Vec, + /// The key pair name to give to the instance in case SSH access required. pub key_pair_name: String, + /// Assign a public ip to the instance. Depending on how your network is + /// setup, this may be required for the instance to reach the public internet. pub assign_public_ip: bool, + /// Use the instances public ip as the address for the server. + /// Could be used when build instances are created in another non-interconnected network to the core api. pub use_public_ip: bool, } +/// For information on AWS volumes, see +/// ``. #[typeshare] #[derive(Serialize, Deserialize, Debug, Clone)] pub struct AwsVolume { + /// The device name (for example, `/dev/sda1` or `xvdh`). pub device_name: String, + /// The size of the volume in GB pub size_gb: i32, + /// The type of volume, eg gp2, gp3, io1 pub volume_type: Option, + /// The iops of the volume, or AWS default. pub iops: Option, + /// The throughput of the volume, or AWS default. pub throughput: Option, } -impl From<&AwsBuilderConfig> for LaunchAwsServerConfig { - fn from(value: &AwsBuilderConfig) -> Self { +impl LaunchAwsServerConfig { + pub fn from_builder_config(value: &AwsBuilderConfig) -> Self { Self { region: value.region.clone(), instance_type: value.instance_type.clone(), diff --git a/client/core/rs/src/api/write/permissions.rs b/client/core/rs/src/api/write/permissions.rs index 882d84b84..4fa6ac6a8 100644 --- a/client/core/rs/src/api/write/permissions.rs +++ b/client/core/rs/src/api/write/permissions.rs @@ -6,10 +6,13 @@ use typeshare::typeshare; use crate::entities::{ permission::{PermissionLevel, UserTarget}, update::ResourceTarget, + NoData, }; use super::MonitorWriteRequest; +/// Update a user or user groups permission on a resource. +/// Response: [NoData]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -17,17 +20,21 @@ use super::MonitorWriteRequest; #[empty_traits(MonitorWriteRequest)] #[response(UpdatePermissionOnTargetResponse)] pub struct UpdatePermissionOnTarget { + /// Specify the user or user group. pub user_target: UserTarget, + /// Specify the target resource. pub resource_target: ResourceTarget, + /// Specify the permission level. pub permission: PermissionLevel, } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct UpdatePermissionOnTargetResponse {} +pub type UpdatePermissionOnTargetResponse = NoData; // +/// Update a user's "base" permissions, eg. "enabled". +/// Response: [NoData]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -35,12 +42,15 @@ pub struct UpdatePermissionOnTargetResponse {} #[empty_traits(MonitorWriteRequest)] #[response(UpdateUserBasePermissionsResponse)] pub struct UpdateUserBasePermissions { + /// The target user. pub user_id: String, + /// If specified, will update users enabled state. pub enabled: Option, + /// If specified, will update user's ability to create servers. pub create_servers: Option, + /// If specified, will update user's ability to create builds. pub create_builds: Option, } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct UpdateUserBasePermissionsResponse {} +pub type UpdateUserBasePermissionsResponse = NoData; diff --git a/client/core/rs/src/api/write/procedure.rs b/client/core/rs/src/api/write/procedure.rs index 4b9941760..b1330eb1e 100644 --- a/client/core/rs/src/api/write/procedure.rs +++ b/client/core/rs/src/api/write/procedure.rs @@ -11,6 +11,7 @@ use super::MonitorWriteRequest; // +/// Create a procedure. Response: [Procedure]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -18,7 +19,9 @@ use super::MonitorWriteRequest; #[empty_traits(MonitorWriteRequest)] #[response(CreateProcedureResponse)] pub struct CreateProcedure { + /// The name given to newly created build. pub name: String, + /// Optional partial config to initialize the procedure with. pub config: _PartialProcedureConfig, } @@ -27,6 +30,8 @@ pub type CreateProcedureResponse = Procedure; // +/// Creates a new procedure with given `name` and the configuration +/// of the procedure at the given `id`. Response: [Procedure]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -34,7 +39,9 @@ pub type CreateProcedureResponse = Procedure; #[empty_traits(MonitorWriteRequest)] #[response(CopyProcedureResponse)] pub struct CopyProcedure { + /// The name of the new procedure. pub name: String, + /// The id of the procedure to copy. pub id: String, } @@ -43,6 +50,8 @@ pub type CopyProcedureResponse = Procedure; // +/// Deletes the procedure at the given id, and returns the deleted procedure. +/// Response: [Procedure] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -50,6 +59,7 @@ pub type CopyProcedureResponse = Procedure; #[empty_traits(MonitorWriteRequest)] #[response(DeleteProcedureResponse)] pub struct DeleteProcedure { + /// The id of the procedure to delete. pub id: String, } @@ -58,6 +68,14 @@ pub type DeleteProcedureResponse = Procedure; // +/// Update the procedure at the given id, and return the updated procedure. +/// Response: [Procedure]. +/// +/// Note. This method updates only the fields which are set in the [_PartialProcedureConfig], +/// effectively merging diffs into the final document. +/// This is helpful when multiple users are using +/// the same resources concurrently by ensuring no unintentional +/// field changes occur from out of date local state. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, diff --git a/client/core/rs/src/api/write/server.rs b/client/core/rs/src/api/write/server.rs index 180511804..7cb734a32 100644 --- a/client/core/rs/src/api/write/server.rs +++ b/client/core/rs/src/api/write/server.rs @@ -45,7 +45,7 @@ pub struct DeleteServer { /// Update the server at the given id, and return the updated server. /// Response: [Server]. -/// +/// /// Note. This method updates only the fields which are set in the [_PartialServerConfig], /// effectively merging diffs into the final document. /// This is helpful when multiple users are using @@ -82,6 +82,8 @@ pub struct RenameServer { // +/// Create a docker network on the server. +/// Respone: [Update] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -89,12 +91,16 @@ pub struct RenameServer { #[empty_traits(MonitorWriteRequest)] #[response(Update)] pub struct CreateNetwork { - pub server_id: String, + /// Id or name + pub server: String, + /// The name of the network to create. pub name: String, } // +/// Delete a docker network. +/// Response: [Update] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -102,6 +108,8 @@ pub struct CreateNetwork { #[empty_traits(MonitorWriteRequest)] #[response(Update)] pub struct DeleteNetwork { - pub server_id: String, + /// Id or name. + pub server: String, + /// The name of the network to delete. pub name: String, } diff --git a/client/core/rs/src/api/write/tags.rs b/client/core/rs/src/api/write/tags.rs index 1a8c18ea4..3f7d0cade 100644 --- a/client/core/rs/src/api/write/tags.rs +++ b/client/core/rs/src/api/write/tags.rs @@ -3,12 +3,13 @@ use resolver_api::derive::Request; use serde::{Deserialize, Serialize}; use typeshare::typeshare; -use crate::entities::{tag::Tag, update::ResourceTarget}; +use crate::entities::{tag::Tag, update::ResourceTarget, NoData}; use super::MonitorWriteRequest; // +/// Create a tag. Response: [Tag]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -16,11 +17,15 @@ use super::MonitorWriteRequest; #[empty_traits(MonitorWriteRequest)] #[response(Tag)] pub struct CreateTag { + /// The name of the tag. pub name: String, } // +/// Delete a tag, and return the deleted tag. Response: [Tag]. +/// +/// Note. Will also remove this tag from all attached resources. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -28,11 +33,13 @@ pub struct CreateTag { #[empty_traits(MonitorWriteRequest)] #[response(Tag)] pub struct DeleteTag { + /// The id of the tag to delete. pub id: String, } // +/// Rename a tag at id. Response: [Tag]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -40,12 +47,16 @@ pub struct DeleteTag { #[empty_traits(MonitorWriteRequest)] #[response(Tag)] pub struct RenameTag { + /// The id of the tag to rename. pub id: String, + /// The new name of the tag. pub name: String, } // +/// Update the tags on a resource. +/// Response: [NoData] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -59,7 +70,6 @@ pub struct UpdateTagsOnResource { } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct UpdateTagsOnResourceResponse {} +pub type UpdateTagsOnResourceResponse = NoData; // diff --git a/client/core/rs/src/api/write/user.rs b/client/core/rs/src/api/write/user.rs index 3ed08ffcb..c3203c84c 100644 --- a/client/core/rs/src/api/write/user.rs +++ b/client/core/rs/src/api/write/user.rs @@ -3,12 +3,14 @@ use resolver_api::derive::Request; use serde::{Deserialize, Serialize}; use typeshare::typeshare; -use crate::entities::{update::ResourceTarget, user::User}; +use crate::entities::{update::ResourceTarget, user::User, NoData}; use super::MonitorWriteRequest; // +/// Push a resource to the front of the users 10 most recently viewed resources. +/// Response: [NoData]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -16,15 +18,18 @@ use super::MonitorWriteRequest; #[empty_traits(MonitorWriteRequest)] #[response(PushRecentlyViewedResponse)] pub struct PushRecentlyViewed { + /// The target to push. pub resource: ResourceTarget, } #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct PushRecentlyViewedResponse {} +pub type PushRecentlyViewedResponse = NoData; // +/// Set the time the user last opened the UI updates. +/// Used for unseen notification dot. +/// Response: [NoData] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -34,12 +39,12 @@ pub struct PushRecentlyViewedResponse {} pub struct SetLastSeenUpdate {} #[typeshare] -#[derive(Serialize, Deserialize, Debug, Clone)] -pub struct SetLastSeenUpdateResponse {} +pub type SetLastSeenUpdateResponse = NoData; // -/// ADMIN ONLY +/// **Admin only.** Create a service user. +/// Response: [User]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -47,7 +52,9 @@ pub struct SetLastSeenUpdateResponse {} #[empty_traits(MonitorWriteRequest)] #[response(CreateServiceUserResponse)] pub struct CreateServiceUser { + /// The username for the service user. pub username: String, + /// A description for the service user. pub description: String, } @@ -56,7 +63,8 @@ pub type CreateServiceUserResponse = User; // -/// ADMIN ONLY +/// **Admin only.** Update a service user's description. +/// Response: [User]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -64,7 +72,9 @@ pub type CreateServiceUserResponse = User; #[empty_traits(MonitorWriteRequest)] #[response(UpdateServiceUserDescriptionResponse)] pub struct UpdateServiceUserDescription { + /// The service user's username pub username: String, + /// A new description for the service user. pub description: String, } diff --git a/client/core/rs/src/api/write/user_group.rs b/client/core/rs/src/api/write/user_group.rs index e60ec10ee..39a28821a 100644 --- a/client/core/rs/src/api/write/user_group.rs +++ b/client/core/rs/src/api/write/user_group.rs @@ -7,7 +7,7 @@ use crate::entities::user_group::UserGroup; use super::MonitorWriteRequest; -/// **Admin only.** Response: [UserGroup] +/// **Admin only.** Create a user group. Response: [UserGroup] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -21,7 +21,7 @@ pub struct CreateUserGroup { // -/// **Admin only.** Response: [UserGroup] +/// **Admin only.** Rename a user group. Response: [UserGroup] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -37,7 +37,7 @@ pub struct RenameUserGroup { // -/// **Admin only.** Response: [UserGroup] +/// **Admin only.** Delete a user group. Response: [UserGroup] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -51,7 +51,7 @@ pub struct DeleteUserGroup { // -/// **Admin only.** Response: [UserGroup] +/// **Admin only.** Add a user to a user group. Response: [UserGroup] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -67,7 +67,7 @@ pub struct AddUserToUserGroup { // -/// **Admin only.** Response: [UserGroup] +/// **Admin only.** Remove a user from a user group. Response: [UserGroup] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -83,7 +83,8 @@ pub struct RemoveUserFromUserGroup { // -/// **Admin only.** Response: [UserGroup] +/// **Admin only.** Completely override the user in the group. +/// Response: [UserGroup] #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, @@ -91,6 +92,8 @@ pub struct RemoveUserFromUserGroup { #[empty_traits(MonitorWriteRequest)] #[response(UserGroup)] pub struct SetUsersInUserGroup { + /// Id or name. pub user_group: String, + /// The user ids or usernames to hard set as the group's users. pub users: Vec, }