Trait RestApiClient 

pub trait RestApiClient {
    // Required methods
    fn start_log_group(name: &str);
    fn end_log_group();
    fn make_headers() -> Result<HeaderMap<HeaderValue>, RestClientError>;
    fn is_pr_event(&self) -> bool;
    fn post_thread_comment(
        &self,
        options: ThreadCommentOptions,
    ) -> impl Future<Output = Result<(), RestClientError>>;
    fn write_output_variables(
        vars: &[OutputVariable],
    ) -> Result<(), RestClientError>;

    // Provided methods
    fn get_list_of_changed_files(
        &self,
        file_filter: &FileFilter,
        lines_changed_only: &LinesChangedOnly,
    ) -> impl Future<Output = Result<HashMap<String, FileDiffLines>, RestClientError>> { ... }
    fn append_step_summary(comment: &str) -> Result<(), RestClientError> { ... }
    fn make_api_request(
        client: &Client,
        url: impl IntoUrl,
        method: Method,
        data: Option<String>,
        headers: Option<HeaderMap>,
    ) -> Result<Request, RestClientError> { ... }
    fn try_next_page(headers: &HeaderMap) -> Option<Url> { ... }
    fn log_response(
        response: Response,
        context: &str,
    ) -> impl Future<Output = ()> + Send { ... }
}

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

Required Methods

fn start_log_group(name: &str)

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

fn end_log_group()

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

fn make_headers() -> Result<HeaderMap<HeaderValue>, RestClientError>

A convenience method to create the headers attached to all REST API calls.

If an authentication token is provided (via environment variable), this method shall include the relative information.

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 post_thread_comment( &self, options: ThreadCommentOptions, ) -> impl Future<Output = Result<(), RestClientError>>

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 write_output_variables( 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 get_list_of_changed_files( &self, file_filter: &FileFilter, lines_changed_only: &LinesChangedOnly, ) -> impl Future<Output = Result<HashMap<String, FileDiffLines>, RestClientError>>

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 append_step_summary(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 make_api_request( client: &Client, url: impl IntoUrl, 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 send_api_request().

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

fn try_next_page(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( response: Response, context: &str, ) -> impl Future<Output = ()> + Send

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl RestApiClient for GithubApiClient

Available on crate feature github only.