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"](../README.md#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:

```rust
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>`:

```rust
/// 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:

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