finish documenting read api

2024-04-27 21:01:53 -07:00
parent afbf28668b
commit 31bcbf36dd
13 changed files with 149 additions and 23 deletions
--- a/bin/core/src/api/read/server.rs
+++ b/bin/core/src/api/read/server.rs
@@ -281,7 +281,7 @@ impl Resolve<GetHistoricalServerStats, User> for State {
    &self,
    GetHistoricalServerStats {
      server,
-      interval,
+      granularity,
      page,
    }: GetHistoricalServerStats,
    user: User,
@@ -292,17 +292,17 @@ impl Resolve<GetHistoricalServerStats, User> for State {
      PermissionLevel::Read,
    )
    .await?;
-    let interval =
-      get_timelength_in_ms(interval.to_string().parse().unwrap())
+    let granularity =
+      get_timelength_in_ms(granularity.to_string().parse().unwrap())
        as i64;
    let mut ts_vec = Vec::<i64>::new();
    let curr_ts = unix_timestamp_ms() as i64;
    let mut curr_ts = curr_ts
-      - curr_ts % interval
-      - interval * STATS_PER_PAGE * page as i64;
+      - curr_ts % granularity
+      - granularity * STATS_PER_PAGE * page as i64;
    for _ in 0..STATS_PER_PAGE {
      ts_vec.push(curr_ts);
-      curr_ts -= interval;
+      curr_ts -= granularity;
    }

    let stats = find_collect(
--- a/client/core/rs/src/api/read/deployment.rs
+++ b/client/core/rs/src/api/read/deployment.rs
@@ -114,6 +114,8 @@ pub type GetLogResponse = Log;

 /// Search the deployment log's tail using `grep`. All lines go to stdout.
 /// Response: [Log].
+///
+/// Note. This call will hit the underlying server directly for most up to date log.
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -139,6 +141,10 @@ pub type SearchLogResponse = Log;

 //

+/// Get the deployment container's stats using `docker stats`.
+/// Response: [DockerContainerStats].
+///
+/// Note. This call will hit the underlying server directly for most up to date stats.
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -156,6 +162,8 @@ pub type GetDeploymentStatsResponse = DockerContainerStats;

 //

+/// Get current action state for the deployment.
+/// Response: [DeploymentActionState].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -173,6 +181,8 @@ pub type GetDeploymentActionStateResponse = DeploymentActionState;

 //

+/// Gets a summary of data relating to all deployments.
+/// Response: [GetDeploymentsSummaryResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -181,6 +191,7 @@ pub type GetDeploymentActionStateResponse = DeploymentActionState;
 #[response(GetDeploymentsSummaryResponse)]
 pub struct GetDeploymentsSummary {}

+/// Response for [GetDeploymentsSummary].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 pub struct GetDeploymentsSummaryResponse {
--- a/client/core/rs/src/api/read/mod.rs
+++ b/client/core/rs/src/api/read/mod.rs
@@ -41,6 +41,8 @@ pub trait MonitorReadRequest: HasResponse {}

 //

+/// Get the version of the core api.
+/// Response: [GetVersionResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -49,14 +51,18 @@ pub trait MonitorReadRequest: HasResponse {}
 #[response(GetVersionResponse)]
 pub struct GetVersion {}

+/// Response for [GetVersion].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetVersionResponse {
+  /// The version of the core api.
  pub version: String,
 }

 //

+/// Get info about the core api.
+/// Response: [GetCoreInfoResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -65,10 +71,14 @@ pub struct GetVersionResponse {
 #[response(GetCoreInfoResponse)]
 pub struct GetCoreInfo {}

+/// Response for [GetCoreInfo].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetCoreInfoResponse {
+  /// The title assigned to this core api.
  pub title: String,
+  /// The monitoring interval of this core api.
  pub monitoring_interval: Timelength,
+  /// The github webhook base url to use with github webhooks.
  pub github_webhook_base_url: String,
 }
--- a/client/core/rs/src/api/read/permission.rs
+++ b/client/core/rs/src/api/read/permission.rs
@@ -53,6 +53,7 @@ pub type GetPermissionLevelResponse = PermissionLevel;
 #[empty_traits(MonitorReadRequest)]
 #[response(ListUserTargetPermissionsResponse)]
 pub struct ListUserTargetPermissions {
+  /// Specify either a user or a user group.
  pub user_target: UserTarget,
 }

--- a/client/core/rs/src/api/read/procedure.rs
+++ b/client/core/rs/src/api/read/procedure.rs
@@ -11,6 +11,7 @@ use super::MonitorReadRequest;

 //

+/// Get a specific procedure. Response: [Procedure].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -28,6 +29,7 @@ pub type GetProcedureResponse = Procedure;

 //

+/// List procedures matching optional query. Response: [ListProceduresResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Default, Request, EmptyTraits,
@@ -35,6 +37,7 @@ pub type GetProcedureResponse = Procedure;
 #[empty_traits(MonitorReadRequest)]
 #[response(ListProceduresResponse)]
 pub struct ListProcedures {
+  /// optional structured query to filter procedures.
  #[serde(default)]
  pub query: ProcedureQuery,
 }
@@ -44,22 +47,7 @@ pub type ListProceduresResponse = Vec<ProcedureListItem>;

 //

-#[typeshare]
-#[derive(
-  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
-)]
-#[empty_traits(MonitorReadRequest)]
-#[response(GetProceduresSummaryResponse)]
-pub struct GetProceduresSummary {}
-
-#[typeshare]
-#[derive(Serialize, Deserialize, Debug, Clone)]
-pub struct GetProceduresSummaryResponse {
-  pub total: u32,
-}
-
-//
-
+/// Get current action state for the procedure. Response: [ProcedureActionState].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -76,3 +64,22 @@ pub struct GetProcedureActionState {
 pub type GetProcedureActionStateResponse = ProcedureActionState;

 //
+
+/// Gets a summary of data relating to all procedures.
+/// Response: [GetProceduresSummaryResponse].
+#[typeshare]
+#[derive(
+  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
+)]
+#[empty_traits(MonitorReadRequest)]
+#[response(GetProceduresSummaryResponse)]
+pub struct GetProceduresSummary {}
+
+/// Response for [GetProceduresSummary].
+#[typeshare]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct GetProceduresSummaryResponse {
+  pub total: u32,
+}
+
+//
--- a/client/core/rs/src/api/read/repo.rs
+++ b/client/core/rs/src/api/read/repo.rs
@@ -11,6 +11,7 @@ use super::MonitorReadRequest;

 //

+/// Get a specific repo. Response: [Repo].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -28,6 +29,7 @@ pub type GetRepoResponse = Repo;

 //

+/// List repos matching optional query. Response: [ListReposResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Default, Request, EmptyTraits,
@@ -35,6 +37,7 @@ pub type GetRepoResponse = Repo;
 #[empty_traits(MonitorReadRequest)]
 #[response(Vec<RepoListItem>)]
 pub struct ListRepos {
+  /// optional structured query to filter repos.
  #[serde(default)]
  pub query: RepoQuery,
 }
@@ -44,6 +47,7 @@ pub type ListReposResponse = Vec<RepoListItem>;

 //

+/// Get current action state for the repo. Response: [RepoActionState].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -61,6 +65,8 @@ pub type GetRepoActionStateResponse = RepoActionState;

 //

+/// Gets a summary of data relating to all builds.
+/// Response: [GetBuildsSummaryResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -69,6 +75,7 @@ pub type GetRepoActionStateResponse = RepoActionState;
 #[response(GetReposSummaryResponse)]
 pub struct GetReposSummary {}

+/// Response for [GetReposSummary]
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetReposSummaryResponse {
--- a/client/core/rs/src/api/read/search.rs
+++ b/client/core/rs/src/api/read/search.rs
@@ -14,6 +14,7 @@ use super::MonitorReadRequest;

 //

+/// Find resources matching a common query. Response: [FindResourcesResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Default, Request, EmptyTraits,
@@ -21,18 +22,26 @@ use super::MonitorReadRequest;
 #[empty_traits(MonitorReadRequest)]
 #[response(FindResourcesResponse)]
 pub struct FindResources {
+  /// The mongo query as JSON
  #[serde(default)]
  pub query: MongoDocument,
+  /// The resource variants to include in the response.
  #[serde(default)]
  pub resources: Vec<ResourceTargetVariant>,
 }

+/// Response for [FindResources].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 pub struct FindResourcesResponse {
+  /// The matching servers.
  pub servers: Vec<ServerListItem>,
+  /// The matching deployments.
  pub deployments: Vec<DeploymentListItem>,
+  /// The matching builds.
  pub builds: Vec<BuildListItem>,
+  /// The matching repos.
  pub repos: Vec<RepoListItem>,
+  /// The matching procedures.
  pub procedures: Vec<ProcedureListItem>,
 }
--- a/client/core/rs/src/api/read/server.rs
+++ b/client/core/rs/src/api/read/server.rs
@@ -22,6 +22,7 @@ use super::MonitorReadRequest;

 //

+/// Get a specific server. Response: [Server].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -39,6 +40,7 @@ pub type GetServerResponse = Server;

 //

+/// List servers matching optional query. Response: [ListServersResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Default, Request, EmptyTraits,
@@ -46,6 +48,7 @@ pub type GetServerResponse = Server;
 #[empty_traits(MonitorReadRequest)]
 #[response(ListServersResponse)]
 pub struct ListServers {
+  /// optional structured query to filter servers.
  #[serde(default)]
  pub query: ServerQuery,
 }
@@ -55,6 +58,7 @@ pub type ListServersResponse = Vec<ServerListItem>;

 //

+/// Get the status of the target server. Response: [GetServerStatusResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -67,14 +71,17 @@ pub struct GetServerStatus {
  pub server: String,
 }

+/// The status for [GetServerStatus].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetServerStatusResponse {
+  /// The server status.
  pub status: ServerStatus,
 }

 //

+/// Get current action state for the servers. Response: [ServerActionState].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -92,6 +99,8 @@ pub type GetServerActionStateResponse = ServerActionState;

 //

+/// Get the version of the monitor periphery agent on the target server.
+/// Response: [GetPeripheryVersionResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -104,14 +113,17 @@ pub struct GetPeripheryVersion {
  pub server: String,
 }

+/// Response for [GetPeripheryVersion].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetPeripheryVersionResponse {
+  /// The version of periphery.
  pub version: String,
 }

 //

+/// Get the docker networks on the server. Response: [GetDockerNetworksResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -129,6 +141,8 @@ pub type GetDockerNetworksResponse = Vec<DockerNetwork>;

 //

+/// Get the docker images locally cached on the target server.
+/// Response: [GetDockerImagesResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -146,6 +160,8 @@ pub type GetDockerImagesResponse = Vec<ImageSummary>;

 //

+/// Get all docker containers on the target server.
+/// Response: [GetDockerContainersResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -163,6 +179,8 @@ pub type GetDockerContainersResponse = Vec<ContainerSummary>;

 //

+/// Get the system information of the target server.
+/// Response: [SystemInformation].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -180,6 +198,11 @@ pub type GetSystemInformationResponse = SystemInformation;

 //

+/// Get the system stats on the target server. Response: [SystemStats].
+///
+/// Note. This does not hit the server directly. The stats come from an
+/// in memory cache on the core, which hits the server periodically
+/// to keep it up to date.
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -197,6 +220,12 @@ pub type GetSystemStatsResponse = SystemStats;

 //

+/// Get the processes running on the target server.
+/// Response: [GetSystemProcessesResponse].
+///
+/// Note. This does not hit the server directly. The procedures come from an
+/// in memory cache on the core, which hits the server periodically
+/// to keep it up to date.
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -214,6 +243,8 @@ pub type GetSystemProcessesResponse = Vec<SystemProcess>;

 //

+/// Paginated endpoint serving historical (timeseries) server stats for graphing.
+/// Response: [GetHistoricalServerStatsResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -224,20 +255,28 @@ pub struct GetHistoricalServerStats {
  /// Id or name
  #[serde(alias = "id", alias = "name")]
  pub server: String,
-  pub interval: Timelength,
+  /// The granularity of the data.
+  pub granularity: Timelength,
+  /// Page of historical data. Default is 0, which is the most recent data.
+  /// Use with the `next_page` field of the response.
  #[serde(default)]
  pub page: u32,
 }

+/// Response to [GetHistoricalServerStats].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetHistoricalServerStatsResponse {
+  /// The timeseries page of data.
  pub stats: Vec<SystemStatsRecord>,
+  /// If there is a next page of data, pass this to `page` to get it.
  pub next_page: Option<u32>,
 }

 //

+/// Gets a summary of data relating to all servers.
+/// Response: [GetServersSummaryResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -246,17 +285,25 @@ pub struct GetHistoricalServerStatsResponse {
 #[response(GetServersSummaryResponse)]
 pub struct GetServersSummary {}

+/// Response for [GetServersSummary].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 pub struct GetServersSummaryResponse {
+  /// The total number of servers.
  pub total: I64,
+  /// The number of healthy (`status: OK`) servers.
  pub healthy: I64,
+  /// The number of unhealthy servers.
  pub unhealthy: I64,
+  /// The number of disabled servers.
  pub disabled: I64,
 }

 //

+/// Get the usernames for the available github / docker accounts
+/// on the target server.
+/// Response: [GetAvailableAccountsResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -269,15 +316,20 @@ pub struct GetAvailableAccounts {
  pub server: String,
 }

+/// Response for [GetAvailableAccounts].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetAvailableAccountsResponse {
+  /// The github usernames
  pub github: Vec<String>,
+  /// The docker usernames.
  pub docker: Vec<String>,
 }

 //

+/// Get the keys for available secrets on the target server.
+/// Response: [GetAvailableSecretsResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
--- a/client/core/rs/src/api/read/tag.rs
+++ b/client/core/rs/src/api/read/tag.rs
@@ -9,6 +9,7 @@ use super::MonitorReadRequest;

 //

+/// Get data for a specific tag. Response [Tag].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -26,6 +27,8 @@ pub type GetTagResponse = Tag;

 //

+/// List data for tags matching optional mongo query.
+/// Response: [ListTagsResponse].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Default, Request, EmptyTraits,
--- a/client/core/rs/src/api/read/toml.rs
+++ b/client/core/rs/src/api/read/toml.rs
@@ -7,6 +7,7 @@ use crate::entities::update::ResourceTarget;

 use super::MonitorReadRequest;

+/// Response containing pretty formatted toml contents.
 #[typeshare]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TomlResponse {
@@ -15,6 +16,9 @@ pub struct TomlResponse {

 //

+/// Get pretty formatted monrun sync toml for all resources
+/// which the user has permissions to view.
+/// Response: [TomlResponse].
 #[typeshare]
 #[derive(
  Debug, Clone, Default, Serialize, Deserialize, Request, EmptyTraits,
@@ -28,6 +32,8 @@ pub type ExportAllResourcesToTomlResponse = TomlResponse;

 //

+/// Get pretty formatted monrun sync toml for specific resources and user groups.
+/// Response: [TomlResponse].
 #[typeshare]
 #[derive(
  Debug, Clone, Default, Serialize, Deserialize, Request, EmptyTraits,
--- a/client/core/rs/src/api/read/update.rs
+++ b/client/core/rs/src/api/read/update.rs
@@ -10,6 +10,8 @@ use crate::entities::{

 use super::MonitorReadRequest;

+/// Get all data for the target update.
+/// Response: [Update].
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -25,6 +27,8 @@ pub type GetUpdateResponse = Update;

 //

+/// Paginated endpoint for updates matching optional query.
+/// More recent updates will be returned first.
 #[typeshare]
 #[derive(
  Serialize, Deserialize, Debug, Clone, Request, EmptyTraits,
@@ -32,14 +36,20 @@ pub type GetUpdateResponse = Update;
 #[empty_traits(MonitorReadRequest)]
 #[response(ListUpdatesResponse)]
 pub struct ListUpdates {
+  /// An optional mongo query to filter the updates.
  pub query: Option<MongoDocument>,
+  /// Page of updates. Default is 0, which is the most recent data.
+  /// Use with the `next_page` field of the response.
  #[serde(default)]
  pub page: u32,
 }

+/// Response for [ListUpdates].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct ListUpdatesResponse {
+  /// The page of updates, sorted by timestamp descending.
  pub updates: Vec<UpdateListItem>,
+  /// If there is a next page of data, pass this to `page` to get it.
  pub next_page: Option<u32>,
 }
--- a/client/core/rs/src/api/read/user.rs
+++ b/client/core/rs/src/api/read/user.rs
@@ -33,6 +33,7 @@ pub type ListApiKeysResponse = Vec<ApiKey>;
 #[empty_traits(MonitorReadRequest)]
 #[response(ListApiKeysForServiceUserResponse)]
 pub struct ListApiKeysForServiceUser {
+  /// The id of the user.
  pub user_id: String,
 }

@@ -66,11 +67,14 @@ pub type ListUsersResponse = Vec<User>;
 #[empty_traits(MonitorReadRequest)]
 #[response(GetUsernameResponse)]
 pub struct GetUsername {
+  /// The id of the user.
  pub user_id: String,
 }

+/// Response for [GetUsername].
 #[typeshare]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GetUsernameResponse {
+  /// The username of the user.
  pub username: String,
 }
--- a/client/core/rs/src/api/read/user_group.rs
+++ b/client/core/rs/src/api/read/user_group.rs
@@ -7,6 +7,8 @@ use crate::entities::user_group::UserGroup;

 use super::MonitorReadRequest;

+/// Get a specific user group by name or id.
+/// Response: [UserGroup].
 #[typeshare]
 #[derive(
  Debug, Clone, Serialize, Deserialize, Request, EmptyTraits,
@@ -23,6 +25,10 @@ pub type GetUserGroupResponse = UserGroup;

 //

+/// List all user groups which user can see. Response: [ListUserGroupsResponse].
+/// 
+/// Admins can see all user groups,
+/// and users can see user groups to which they belong.
 #[typeshare]
 #[derive(
  Debug, Clone, Default, Serialize, Deserialize, Request, EmptyTraits,