github: add GitHub API function to submit pull request reviews (#343)

* feat: add GitHub API function to approve pull requests

* nit: update type to be consistent with sibling functions

* chore: simplify approve error handling/body parsing

* feat: expand functionality to submit review

Author: nvsriram

runtime/plaid-stl/src/github/pull_request.rs

@@ -161,6 +161,122 @@ pub fn pull_request_request_reviewers(
     Ok(())
 }
 
+/// The review action to submit as part of a pull request review.
+///
+/// GitHub requires a non-empty `body` alongside `RequestChanges` and `Comment`;
+/// it is optional for `Approve`.
+#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
+pub enum PullRequestReviewEvent {
+    /// Approve the pull request.
+    #[serde(rename = "APPROVE")]
+    Approve,
+    /// Request changes on the pull request. Requires a `body`.
+    #[serde(rename = "REQUEST_CHANGES")]
+    RequestChanges,
+    /// Leave a review comment without approving or requesting changes. Requires a `body`.
+    #[serde(rename = "COMMENT")]
+    Comment,
+}
+
+/// Request to submit a review on a pull request.
+#[derive(Serialize, Deserialize)]
+pub struct SubmitPullRequestReviewRequest {
+    /// The account owner of the repository. The name is not case sensitive.
+    pub owner: String,
+    /// The name of the repository without the `.git` extension. The name is not case sensitive.
+    pub repo: String,
+    /// The number of the pull request to review.
+    pub number: u32,
+    /// The review action to submit.
+    pub event: PullRequestReviewEvent,
+    /// A comment to leave alongside the review. Required unless `event` is `Approve`.
+    pub body: Option<String>,
+}
+
+/// Submits a review on a pull request.
+///
+/// See the [GitHub API docs](https://docs.github.com/en/rest/pulls/reviews?apiVersion=2022-11-28#create-a-review-for-a-pull-request)
+/// for more details.
+///
+/// ## Arguments
+/// * `client_id` - Selects which configured GitHub client to use (supports multiple clients).
+/// * `owner` - The account or organization that owns the repository.
+/// * `repo` - The name of the repository.
+/// * `number` - The number of the pull request to review.
+/// * `event` - The review action to submit.
+/// * `body` - A comment to leave alongside the review. Required unless `event` is `Approve`.
+///
+/// ## Returns
+/// * `Ok(())` if the review was successfully submitted, or
+/// * `Err(PlaidFunctionError)` if the request fails.
+pub fn submit_pull_request_review(
+    client_id: impl Display,
+    owner: impl Display,
+    repo: impl Display,
+    number: u32,
+    event: PullRequestReviewEvent,
+    body: Option<impl Display>,
+) -> Result<(), PlaidFunctionError> {
+    extern "C" {
+        new_host_function!(github, submit_pull_request_review);
+    }
+
+    let request = SubmitPullRequestReviewRequest {
+        owner: owner.to_string(),
+        repo: repo.to_string(),
+        number,
+        event,
+        body: body.map(|b| b.to_string()),
+    };
+
+    let wrapped = GithubApiWrapper {
+        client_id: client_id.to_string(),
+        params: request,
+    };
+    let request = serde_json::to_string(&wrapped).unwrap();
+
+    let res = unsafe {
+        github_submit_pull_request_review(request.as_bytes().as_ptr(), request.as_bytes().len())
+    };
+
+    // There was an error with the Plaid system. Maybe the API is not
+    // configured.
+    if res < 0 {
+        return Err(res.into());
+    }
+
+    Ok(())
+}
+
+/// Approves a pull request by submitting an `APPROVE` review on it.
+///
+/// ## Arguments
+/// * `client_id` - Selects which configured GitHub client to use (supports multiple clients).
+/// * `owner` - The account or organization that owns the repository.
+/// * `repo` - The name of the repository.
+/// * `number` - The number of the pull request to approve.
+/// * `body` - An optional comment to leave alongside the approval.
+///
+/// ## Returns
+/// * `Ok(())` if the review was successfully submitted, or
+/// * `Err(PlaidFunctionError)` if the request fails.
+pub fn approve_pull_request(
+    client_id: impl Display,
+    owner: impl Display,
+    repo: impl Display,
+    number: u32,
+    body: Option<impl Display>,
+) -> Result<(), PlaidFunctionError> {
+    submit_pull_request_review(
+        client_id,
+        owner,
+        repo,
+        number,
+        PullRequestReviewEvent::Approve,
+        body,
+    )
+}
+
 /// Request to fetch pull requests from a repository.
 ///
 /// Represents the top-level parameters needed to query pull requests

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

@@ -1,6 +1,7 @@
 use plaid_stl::github::{
     AddLabelsRequest, CreatePullRequestRequest, GetPullRequestOptions, GetPullRequestRequest,
-    GithubApiWrapper, PullRequestRequestReviewers,
+    GithubApiWrapper, PullRequestRequestReviewers, PullRequestReviewEvent,
+    SubmitPullRequestReviewRequest,
 };
 use serde::Serialize;
 use serde_json::json;
@@ -73,6 +74,54 @@ impl Github {
         }
     }
 
+    /// Submits a review on a pull request.
+    pub async fn submit_pull_request_review(
+        &self,
+        params: &str,
+        module: Arc<PlaidModule>,
+    ) -> Result<u32, ApiError> {
+        #[derive(Serialize)]
+        struct SubmitReview {
+            event: PullRequestReviewEvent,
+            #[serde(skip_serializing_if = "Option::is_none")]
+            body: Option<String>,
+        }
+
+        let request: GithubApiWrapper<SubmitPullRequestReviewRequest> =
+            serde_json::from_str(params).map_err(|_| ApiError::BadRequest)?;
+
+        let owner = self.validate_org(&request.params.owner)?;
+        let repo = self.validate_repository_name(&request.params.repo)?;
+        let number = request.params.number;
+        let event = request.params.event;
+        self.validate_review_body(event, request.params.body.as_deref())?;
+
+        info!("Submitting {event:?} review on pull request [{owner}/{repo}/{number}] on behalf of {module}");
+
+        let address = format!("/repos/{owner}/{repo}/pulls/{number}/reviews");
+        let request_body = SubmitReview {
+            event,
+            body: request.params.body,
+        };
+
+        match self
+            .make_generic_post_request(&request.client_id, address, request_body, module)
+            .await
+        {
+            Ok((status, Ok(_))) => {
+                if status == 200 {
+                    Ok(0)
+                } else {
+                    Err(ApiError::GitHubError(GitHubError::UnexpectedStatusCode(
+                        status,
+                    )))
+                }
+            }
+            Ok((_, Err(e))) => Err(e),
+            Err(e) => Err(e),
+        }
+    }
+
     /// Creates a pull request in a specified repository.
     pub async fn create_pull_request(
         &self,

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

@@ -1,5 +1,7 @@
 use std::collections::HashMap;
 
+use plaid_stl::github::PullRequestReviewEvent;
+
 use crate::apis::ApiError;
 
 use super::{GitHubError, Github};
@@ -108,4 +110,21 @@ impl Github {
         // Repo IDs are positive integers
         self.validate_pint(repo_id)
     }
+
+    /// Ensure a pull request review has a body when GitHub requires one.
+    /// A non-empty `body` is mandatory for `RequestChanges` and `Comment`;
+    /// it is optional for `Approve`.
+    pub fn validate_review_body(
+        &self,
+        event: PullRequestReviewEvent,
+        body: Option<&str>,
+    ) -> Result<(), ApiError> {
+        match (event, body) {
+            (PullRequestReviewEvent::Approve, _) => Ok(()),
+            (_, Some(body)) if !body.is_empty() => Ok(()),
+            (_, _) => Err(ApiError::GitHubError(GitHubError::InvalidInput(format!(
+                "a non-empty body is required for review event {event:?}"
+            )))),
+        }
+    }
 }

runtime/plaid/src/functions/api.rs

@@ -436,6 +436,7 @@ impl_new_function!(
     pull_request_request_reviewers,
     DISALLOW_IN_TEST_MODE
 );
+impl_new_function!(github, submit_pull_request_review, DISALLOW_IN_TEST_MODE);
 impl_new_function_with_error_buffer!(github, get_weekly_commit_count, ALLOW_IN_TEST_MODE);
 impl_new_function_with_error_buffer!(github, get_reference, ALLOW_IN_TEST_MODE);
 impl_new_function!(github, create_reference, DISALLOW_IN_TEST_MODE);
@@ -891,6 +892,7 @@ define_api_functions! {
         "github_delete_deploy_key"                         => github_delete_deploy_key,
         "github_create_deploy_key"                         => github_create_deploy_key,
         "github_pull_request_request_reviewers"            => github_pull_request_request_reviewers,
+        "github_submit_pull_request_review"                => github_submit_pull_request_review,
         "github_require_signed_commits"                    => github_require_signed_commits,
         "github_get_weekly_commit_count"                   => github_get_weekly_commit_count,
         "github_add_repo_to_team"                          => github_add_repo_to_team,