Add doc comments

runtime/plaid/src/apis/aws/kms.rs

@@ -10,6 +10,7 @@ use aws_sdk_kms::{
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
+/// A request to sign a given message with a KMS key.
 #[derive(Deserialize)]
 struct SignRequestRequest {
     /// To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN.

runtime/plaid/src/apis/aws/mod.rs

@@ -6,11 +6,13 @@ pub mod kms;
 /// The entire configuration of AWS APIs implemented in Plaid
 #[derive(Deserialize)]
 pub struct AwsConfig {
+    /// Configuration for the KMS API
     pub kms: KmsConfig,
 }
 
 /// Contains all AWS services that Plaid implements APIs for
 pub struct Aws {
+    /// AWS Key Management Service
     pub kms: Kms,
 }
 

runtime/plaid/src/apis/general/logback.rs

@@ -7,7 +7,7 @@ impl General {
     /// Send a log from a module back into the logging system into a particular
     /// type. You need to be very careful when allowing modules to use this
     /// because it can be used to trigger other rules with greater access than
-    /// it has.
+    /// the calling module has.
     pub fn log_back(&self, type_: &str, log: &[u8], module: &str, delay: u64, logbacks_allowed: LogbacksAllowed) -> bool {
         let msg = Message::new(
             type_.to_string(),

runtime/plaid/src/apis/general/mod.rs

@@ -16,6 +16,7 @@ use super::default_timeout_seconds;
 
 #[derive(Deserialize)]
 pub struct GeneralConfig {
+    /// Configuration for network requests
     network: network::Config,
     /// The number of seconds until an external API request times out.
     /// If no value is provided, the result of `default_timeout_seconds()` will be used.
@@ -24,10 +25,15 @@ pub struct GeneralConfig {
 }
 
 pub struct General {
+    /// General Plaid configuration
     config: GeneralConfig,
+    /// Client to make requests with
     client: Client,
+    /// Sender object for messages
     log_sender: Sender<Message>,
+    /// Sender object for messages that must be processed with a delay
     delayed_log_sender: Sender<DelayedMessage>,
+    /// Secure random generator
     system_random: SystemRandom,
 }
 

runtime/plaid/src/apis/general/network.rs

@@ -12,6 +12,7 @@ pub struct Config {
     web_requests: HashMap<String, Request>,
 }
 
+/// Request to make a web request
 #[derive(Deserialize)]
 struct MakeRequestRequest {
     /// Body of the request
@@ -25,6 +26,8 @@ struct MakeRequestRequest {
     headers: Option<HashMap<String, String>>
 }
 
+/// This struct represents a web request and contains information about what the request is about (e.g., verb and URI),
+/// how it should be processed, and which modules are allowed to make it.
 #[derive(Deserialize)]
 pub struct Request {
     /// HTTP verb
@@ -43,6 +46,7 @@ pub struct Request {
     headers: HashMap<String, String>,
 }
 
+/// Data returned by a request.
 #[derive(Serialize)]
 struct ReturnData {
     code: Option<u16>,
@@ -79,6 +83,7 @@ impl General {
         }
     }
 
+    /// Make a named web request on behalf of a given `module`. The request's details are encoded in `params`.
     pub async fn make_named_request(&self, params: &str, module: &str) -> Result<String, ApiError> {
         // Parse the information needed to make the request
         let request: MakeRequestRequest = serde_json::from_str(params).map_err(|_| ApiError::BadRequest)?;

runtime/plaid/src/apis/github/copilot.rs

@@ -5,8 +5,8 @@ use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
 impl Github {
-    // List all seats in the Copilot subscription for an organization
-    // See https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28#list-all-copilot-seat-assignments-for-an-organization for more details
+    /// List all seats in the Copilot subscription for an organization
+    /// See https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28#list-all-copilot-seat-assignments-for-an-organization for more details
     pub async fn list_seats_in_org_copilot(&self, params: &str, module: &str) -> Result<String, ApiError> {
         let request: HashMap<&str, &str> =
             serde_json::from_str(params).map_err(|_| ApiError::BadRequest)?;
@@ -36,8 +36,8 @@ impl Github {
         }
     }
 
-    // Add users to the Copilot subscription for an organization
-    // See https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28#add-users-to-the-copilot-subscription-for-an-organization for more details
+    /// Add users to the Copilot subscription for an organization
+    /// See https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28#add-users-to-the-copilot-subscription-for-an-organization for more details
     pub async fn add_users_to_org_copilot(&self, params: &str, module: &str) -> Result<String, ApiError> {
         #[derive(Deserialize, Serialize)]
         struct Request {
@@ -72,8 +72,8 @@ impl Github {
         }
     }
 
-    // Remove users from the Copilot subscription for an organization
-    // See https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28#remove-users-from-the-copilot-subscription-for-an-organization for more details
+    /// Remove users from the Copilot subscription for an organization
+    /// See https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28#remove-users-from-the-copilot-subscription-for-an-organization for more details
     pub async fn remove_users_from_org_copilot(&self, params: &str, module: &str) -> Result<String, ApiError> {
         #[derive(Deserialize, Serialize)]
         struct Request {

runtime/plaid/src/apis/github/environments.rs

@@ -6,19 +6,27 @@ use crate::apis::{github::GitHubError, ApiError};
 
 use super::Github;
 
+/// Policy that determines which branches can deploy.
+/// Exactly one of the fields must be set to `true`.
 #[derive(Serialize)]
 struct DeploymentBranchPolicy {
+    /// Only branches with branch protection rules can deploy.
     protected_branches: bool,
+    /// Only branches that match the specified name patterns can deploy.
     custom_branch_policies: bool,
 }
 
+/// Represents someone who can review a deployment job
 #[derive(Serialize)]
 struct Reviewer {
+    /// The type of reviewer (user or team)
     #[serde(rename = "type")]
     type_: String,
+    /// The ID of the reviewer
     id: u64,
 }
 
+/// Payload sent to the GitHub REST API to create a new deployment environment.
 /// See https://docs.github.com/en/rest/deployments/environments?apiVersion=2022-11-28#create-or-update-an-environment for details
 #[derive(Serialize)]
 struct CreateEnvironmentPayload {
@@ -32,10 +40,13 @@ struct CreateEnvironmentPayload {
     deployment_branch_policy: DeploymentBranchPolicy,
 }
 
+/// Payload sent to the GitHub REST API to create a new deployment branch policy.
 #[derive(Serialize)]
 struct CreateDeploymentBranchPolicyPayload {
+    /// The name pattern that branches or tags must match in order to deploy to the environment.
     name: String,
     #[serde(rename = "type")]
+    /// Whether this rule targets a branch or tag.
     type_: String,
 }
 

runtime/plaid/src/apis/github/graphql.rs

@@ -6,33 +6,46 @@ use crate::apis::{github::GitHubError, ApiError};
 
 use super::Github;
 
+/// A GraphQL query ready to be executed.
 #[derive(Serialize)]
 struct GraphQLQuery {
+    /// The query to be executed.
     query: String,
+    /// Variables to be interpolated in the query.
     variables: HashMap<String, String>,
 }
 
+/// A request to execute a GraphQL query.
 #[derive(Deserialize)]
 struct Request {
+    /// The name of the query to be executed (must match some query in the config).
     query_name: String,
+    /// Variables to be interpolated in the query.
     variables: HashMap<String, String>,
 }
 
+/// An advanced GraphQL query ready to be executed, where variables are generic JSON values.
 #[derive(Serialize)]
 struct AdvancedGraphQLQuery {
+    /// The query to be executed.
     query: String,
+    /// Variables to be interpolated in the query.
     variables: HashMap<String, serde_json::Value>,
 }
 
+/// A request to execute an advanced GraphQL query.
 #[derive(Deserialize)]
 struct AdvancedRequest {
+    /// The name of the query to be executed (must match some query in the config).
     query_name: String,
+    /// Variables to be interpolated in the query.
     variables: HashMap<String, serde_json::Value>,
 }
 
 const GITHUB_GQL_API: &str = "/graphql";
 
 impl Github {
+    /// Execute a GraphQL query by calling the GitHub API.
     async fn make_gql_request<T: Serialize>(
         &self,
         query: T,
@@ -64,6 +77,7 @@ impl Github {
         }
     }
 
+    /// Execute a GraphQL query specified by `request`, on behalf of `module`.
     pub async fn make_graphql_query(
         &self,
         request: &str,
@@ -81,13 +95,14 @@ impl Github {
         };
 
         let query = GraphQLQuery {
-            query: query,
+            query,
             variables: request.variables,
         };
 
         self.make_gql_request(query, module).await
     }
 
+    /// Execute an advanced GraphQL query specified by `request`, on behalf of `module`.
     pub async fn make_advanced_graphql_query(
         &self,
         request: &str,

runtime/plaid/src/apis/github/mod.rs

@@ -52,12 +52,17 @@ pub struct GithubConfig {
     graphql_queries: HashMap<String, String>,
 }
 
+/// Represents the configured GitHub API
 pub struct Github {
+    /// Configuration for Plaid's GitHub API
     config: GithubConfig,
+    /// Client to make requests with
     client: Octocrab,
+    /// Validators used to check parameters passed by modules
     validators: HashMap<&'static str, regex::Regex>,
 }
 
+/// All the errors that can be encountered while executing GitHub calls
 #[derive(Debug)]
 pub enum GitHubError {
     GraphQLUnserializable,

runtime/plaid/src/apis/github/pats.rs

@@ -7,6 +7,7 @@ use crate::apis::{github::GitHubError, ApiError};
 use super::Github;
 
 impl Github {
+    /// Fetch a list of all FPAT requests for a GitHub organization.
     pub async fn list_fpat_requests_for_org(
         &self,
         params: &str,
@@ -35,6 +36,7 @@ impl Github {
         }
     }
 
+    /// List the repositories a fine-grained personal access token request is requesting access to.
     pub async fn get_repos_for_fpat(&self, params: &str, module: &str) -> Result<String, ApiError> {
         let request: HashMap<&str, &str> =
             serde_json::from_str(params).map_err(|_| ApiError::BadRequest)?;
@@ -64,6 +66,7 @@ impl Github {
         }
     }
 
+    /// Approves or denies multiple pending requests to access organization resources via a fine-grained personal access token.
     pub async fn review_fpat_requests_for_org(
         &self,
         params: &str,

runtime/plaid/src/apis/github/secrets.rs

@@ -63,15 +63,15 @@ impl Github {
             .ok_or(ApiError::GitHubError(GitHubError::InvalidInput(
                 "Invalid response while fetching public key from GitHub".to_string(),
             )))?
-            .to_string()
-            .replace("\"", "");
+            .as_str()
+            .ok_or(ApiError::GitHubError(GitHubError::BadResponse))?;
         let key_id = res
             .get("key_id")
             .ok_or(ApiError::GitHubError(GitHubError::InvalidInput(
                 "Invalid response while fetching public key from GitHub".to_string(),
             )))?
-            .to_string()
-            .replace("\"", "");
+            .as_str()
+            .ok_or(ApiError::GitHubError(GitHubError::BadResponse))?;
 
         // 2. Encrypt the secret under the pub key
 
@@ -106,7 +106,7 @@ impl Github {
         };
         let body = UploadEnvironmentSecretPayload {
             encrypted_value: ciphertext,
-            key_id,
+            key_id: key_id.to_string(),
         };
 
         match self

runtime/plaid/src/apis/github/teams.rs

@@ -6,6 +6,7 @@ use super::Github;
 use crate::apis::{github::GitHubError, ApiError};
 
 impl Github {
+    /// Remove a user from a GitHub team.
     pub async fn remove_user_from_team(&self, params: &str, module: &str) -> Result<u32, ApiError> {
         let request: HashMap<&str, &str> =
             serde_json::from_str(params).map_err(|_| ApiError::BadRequest)?;
@@ -36,6 +37,7 @@ impl Github {
         }
     }
 
+    /// Add a user to a GitHub team.
     pub async fn add_user_to_team(&self, params: &str, module: &str) -> Result<u32, ApiError> {
         let request: HashMap<&str, &str> =
             serde_json::from_str(params).map_err(|_| ApiError::BadRequest)?;

runtime/plaid/src/apis/github/validators.rs

@@ -4,8 +4,7 @@ use crate::apis::ApiError;
 
 use super::{GitHubError, Github};
 
-// new_regex_validator!("REPOSITORY_NAME", "^[\w\-\.]+$");
-
+/// Macro that compiles a regex validator and inserts it into a list of available validators.
 macro_rules! define_regex_validator {
     ($validators:expr,$validator:tt,$regex: tt) => {
         $validators.insert(
@@ -16,6 +15,7 @@ macro_rules! define_regex_validator {
     };
 }
 
+/// Macro that creates a function which uses a given validator to validate an input.
 macro_rules! create_regex_validator_func {
     ($validator:ident) => {
         paste::item! {
@@ -37,6 +37,7 @@ macro_rules! create_regex_validator_func {
     }
 }
 
+/// Initialize all available validators.
 pub fn create_validators() -> HashMap<&'static str, regex::Regex> {
     let mut validators = HashMap::new();
 

runtime/plaid/src/apis/mod.rs

@@ -35,6 +35,7 @@ use crate::{data::DelayedMessage, executor::Message};
 
 use self::rustica::{Rustica, RusticaConfig};
 
+/// All the APIs that Plaid can use
 pub struct Api {
     pub runtime: Runtime,
     #[cfg(feature = "aws")]
@@ -51,8 +52,9 @@ pub struct Api {
     pub web: Option<Web>,
 }
 
+/// Configurations for all the APIs Plaid can use
 #[derive(Deserialize)]
-pub struct Apis {
+pub struct ApiConfigs {
     #[cfg(feature = "aws")]
     pub aws: Option<AwsConfig>,
     pub general: Option<GeneralConfig>,
@@ -91,7 +93,7 @@ pub enum ApiError {
 
 impl Api {
     pub async fn new(
-        config: Apis,
+        config: ApiConfigs,
         log_sender: Sender<Message>,
         delayed_log_sender: Sender<DelayedMessage>,
     ) -> Self {