Trait RestApiClient 

pub trait RestApiClient {
    // Required methods
    fn is_pr_event(&self) -> bool;
    fn set_user_agent(
        &mut self,
        user_agent: &str,
    ) -> Result<(), RestClientError>;
    fn get_list_of_changed_files<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        file_filter: &'life1 FileFilter,
        lines_changed_only: &'life2 LinesChangedOnly,
        base_diff: Option<String>,
        ignore_index: bool,
    ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, FileDiffLines>, RestClientError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn post_thread_comment<'life0, 'async_trait>(
        &'life0 self,
        options: ThreadCommentOptions,
    ) -> Pin<Box<dyn Future<Output = Result<(), RestClientError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn cull_pr_reviews<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        options: &'life1 mut ReviewOptions,
    ) -> Pin<Box<dyn Future<Output = Result<(), RestClientError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn post_pr_review<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        options: &'life1 ReviewOptions,
    ) -> Pin<Box<dyn Future<Output = Result<(), RestClientError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn write_output_variables(
        &self,
        vars: &[OutputVariable],
    ) -> Result<(), RestClientError>;

    // Provided methods
    fn start_log_group(&self, name: &str) { ... }
    fn end_log_group(&self, name: &str) { ... }
    fn is_debug_enabled(&self) -> bool { ... }
    fn event_name(&self) -> Option<String> { ... }
    fn append_step_summary(&self, comment: &str) -> Result<(), RestClientError> { ... }
    fn write_file_annotations(
        &self,
        annotations: &[FileAnnotation],
    ) -> Result<(), RestClientError> { ... }
    fn make_api_request(
        &self,
        client: &Client,
        url: Url,
        method: Method,
        data: Option<String>,
        headers: Option<HeaderMap>,
    ) -> Result<Request, RestClientError> { ... }
    fn send_api_request<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        client: &'life1 Client,
        request: Request,
        rate_limit_headers: &'life2 RestApiRateLimitHeaders,
    ) -> Pin<Box<dyn Future<Output = Result<Response, RestClientError>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn try_next_page(&self, headers: &HeaderMap) -> Option<Url> { ... }
    fn log_response<'life0, 'life1, 'async_trait>(
        &'life0 self,
        response: Response,
        context: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}

A custom trait that templates necessary functionality with a Git server’s REST API.

Required Methods

fn is_pr_event(&self) -> bool

Is the current CI event trigger a Pull Request?

This will not check if a push event’s instigating commit is part of any PR.

fn set_user_agent(&mut self, user_agent: &str) -> Result<(), RestClientError>

Set the user agent for the underlying HTTP request client.

By default the user agent is set to this lib’s name and version. See USER_AGENT for the default value.

fn get_list_of_changed_files<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, file_filter: &'life1 FileFilter, lines_changed_only: &'life2 LinesChangedOnly, base_diff: Option<String>, ignore_index: bool, ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, FileDiffLines>, RestClientError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Available on crate feature file-changes only.

A way to get the list of changed files in the context of the CI event.

This method will parse diff blobs and return a list of changed files.

The default implementation uses git diff to get the list of changed files. So, the default implementation requires git installed and a non-shallow checkout.

Other implementations use the Git server’s REST API to get the list of changed files.

fn post_thread_comment<'life0, 'async_trait>( &'life0 self, options: ThreadCommentOptions, ) -> Pin<Box<dyn Future<Output = Result<(), RestClientError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

A way to post feedback to the Git server’s GUI.

The given ThreadCommentOptions::comment should be compliant with the Git server’s requirements (ie. the comment length is within acceptable limits).

fn cull_pr_reviews<'life0, 'life1, 'async_trait>( &'life0 mut self, options: &'life1 mut ReviewOptions, ) -> Pin<Box<dyn Future<Output = Result<(), RestClientError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve outdated PR review comments and remove duplicate/reused comments.

This should be used before Self::post_pr_review() to avoid posting duplicates of existing comments. The ReviewOptions::comments will be modified to only include comments that should be posted for the current PR review. After calling this function, the ReviewOptions::summary can be made to reflect the actual review being posted.

The ReviewOptions::marker is used to identify comments from this software. The ReviewOptions::delete_review_comments flag will delete outdated review comments. The ReviewOptions::delete_review_comments flag does not apply to review summary comments nor threads of discussion within a review. A review summary comment will only be hidden/collapsed when all comments in the corresponding review are resolved.

This function does nothing for non-PR events.

fn post_pr_review<'life0, 'life1, 'async_trait>( &'life0 mut self, options: &'life1 ReviewOptions, ) -> Pin<Box<dyn Future<Output = Result<(), RestClientError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Post a PR review based on the given options.

This is expected to be used after calling Self::cull_pr_reviews() to avoid posting duplicates of existing comments. Once the duplicates are filtered out, the ReviewOptions::summary can be made to reflect the actual review being posted.

This function does nothing for non-PR events.

fn write_output_variables( &self, vars: &[OutputVariable], ) -> Result<(), RestClientError>

Sets the given vars as output variables.

These variables are designed to be consumed by other steps in the CI workflow.

Provided Methods

fn start_log_group(&self, name: &str)

This prints a line to indicate the beginning of a related group of log statements.

fn end_log_group(&self, name: &str)

This prints a line to indicate the ending of a related group of log statements.

fn is_debug_enabled(&self) -> bool

Is debug mode enabled?

Typically, A CI platform will have a way to enable debug level logs for a job or workflow. This method should be implemented to reflect the supported CI platform’s implementation.

fn event_name(&self) -> Option<String>

Get the name of the current CI event.

This will return None if the event name is not known for the CI platform.

fn append_step_summary(&self, comment: &str) -> Result<(), RestClientError>

Appends a given comment to the CI workflow’s summary page.

This is the least obtrusive and recommended for push events. Not all Git servers natively support this type of feedback. GitHub and Gitea are known to support this. For all other git servers, this is a non-op returning Ok

fn write_file_annotations( &self, annotations: &[FileAnnotation], ) -> Result<(), RestClientError>

Sets the given annotations as file annotations.

Not all Git servers support this on their free tiers, namely GitLab.

fn make_api_request( &self, client: &Client, url: Url, method: Method, data: Option<String>, headers: Option<HeaderMap>, ) -> Result<Request, RestClientError>

Construct a HTTP request to be sent.

The idea here is that this method is called before Self::send_api_request().

let request = Self::make_api_request(
    &self.client,
    Url::parse("https://example.com").unwrap(),
    Method::GET,
    None,
    None,
).unwrap();
let response = send_api_request(&self.client, request, &self.rest_api_headers);
match response.await {
    Ok(res) => todo!(handle response),
    Err(e) => todo!(handle failure),
}

fn send_api_request<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, client: &'life1 Client, request: Request, rate_limit_headers: &'life2 RestApiRateLimitHeaders, ) -> Pin<Box<dyn Future<Output = Result<Response, RestClientError>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

A convenience function to send HTTP requests and respect a REST API rate limits.

This method respects both primary and secondary rate limits. In the event where the secondary rate limits is reached, this function will wait for a time interval (if specified by the server) and retry afterward.

fn try_next_page(&self, headers: &HeaderMap) -> Option<Url>

Gets the URL for the next page from the headers in a paginated response.

Returns None if current response is the last page.

fn log_response<'life0, 'life1, 'async_trait>( &'life0 self, response: Response, context: &'life1 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

A helper function to log the response of an API request with context.

This also dumps the response body as text if possible.

Implementors

impl RestApiClient for GithubApiClient

Available on crate feature github only.

impl RestApiClient for LocalClient