progenitor/docs/progenitor-client.md

Progenitor Client

The progenitor-client crate contains types that are exported by generated clients as well as functions that are used internally by generated clients. Depending on how progenitor is being used, the crate will be included in different ways (see "Using Progenitor").

• For macro consumers, it comes from the progenitor dependency.

• For builder consumers, it must be specified under [dependencies] (while progenitor is under [build-dependencies]).

• For statically generated consumers, the code is emitted into src/progenitor_client.rs.

The two types that progenitor-client exports are Error<E> and ResponseValue<T>. A typical generated method will use these types in its signature:

impl Client {
    pub async fn operation_name<'a>(
        &'a self,
        // parameters ...
    ) -> Result<
        ResponseValue<types::SuccessResponseType>,
        Error<types::ErrorResponseType>>
    {
        // ...
    }

ResponseValue<T>

OpenAPI documents defines the types that an operation returns. Generated methods wrap these types in ResponseValue<T> for two reasons: there is additional information that may be included in a response such as the specific status code and headers, and that information cannot simply be included in the response type because that type may be used in other context (e.g. as a body parameter).

These are the relevant implementations for ResponseValue<T>:

/// Success value returned by generated client methods.
pub struct ResponseValue<T> { .. }

impl<T> ResponseValue<T> {
    pub fn status(&self) -> &reqwest::StatusCode { .. }
    pub fn headers(&self) -> &reqwest::header::HeaderMap { .. }
    pub fn into_inner(self) -> T { .. }
}
impl<T> std::ops::Deref for ResponseValue<T> {
    type Target = T;
    ..
}
impl<T> std::ops::DerefMut for ResponseValue<T> { .. }

impl<T: std::fmt::Debug> std::fmt::Debug for ResponseValue<T> { .. }

It can be used as the type T in most instances and extracted as a T using into_inner().

Error<E>

There are five sub-categories of error covered by the error type variants:

• A request that did not conform to API requirements. This can occur when required builder or body parameters were not specified, and the error message will denote the specific failure.

• A communication error

• An expected error response, defined by the OpenAPI document with a 4xx or 5xx status code

• An expected status code (whose payload didn't deserialize as expected (this could be viewed as a sub-type of communication error), but it is separately identified as there's more information; note that this covers both success and error status codes

• An unexpected status code in the response

These errors are covered by the variants of the Error<E> type:

pub enum Error<E = ()> {
    InvalidRequest(String),
    CommunicationError(reqwest::Error),
    ErrorResponse(ResponseValue<E>),
    InvalidResponsePayload(reqwest::Error),
    UnexpectedResponse(reqwest::Response),
}