100 lines
3.2 KiB
Markdown
100 lines
3.2 KiB
Markdown
# 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 seven 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 when upgrading connection.
|
|
|
|
- An expected error response, defined by the OpenAPI document
|
|
with a 4xx or 5xx status code
|
|
|
|
- An expected status code that encountered an error reading the body
|
|
or the payload deserialization failed
|
|
(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),
|
|
InvalidUpgrade(reqwest::Error),
|
|
ErrorResponse(ResponseValue<E>),
|
|
ResponseBodyError(reqwest::Error),
|
|
InvalidResponsePayload(bytes::Bytes, reqwest::Error),
|
|
UnexpectedResponse(reqwest::Response),
|
|
}
|
|
```
|