openkind-client 0.3.0

Async Rust client for the openkind / TypeSafe Jev SystemOne HTTP API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Error taxonomy and header parsing for the client, mirroring the TypeSafe
//! Python SDK exception hierarchy:
//!
//! | Rust                              | Python SDK                        | HTTP | Server `code`        |
//! |-----------------------------------|-----------------------------------|------|----------------------|
//! | [`ApiErrorKind::BadRequest`]      | `TypeSafeBadRequestError`         | 400  | `bad_json`           |
//! | [`ApiErrorKind::Authentication`]  | `TypeSafeAuthenticationError`     | 401  | `unauthorized`       |
//! | [`ApiErrorKind::NotFound`]        | `TypeSafeNotFoundError`           | 404  | `unknown_model`      |
//! | [`ApiErrorKind::PayloadTooLarge`] | —                                 | 413  | `payload_too_large`  |
//! | [`ApiErrorKind::UnprocessableEntity`] | `TypeSafeUnprocessableEntityError` | 422 | `invalid_body`   |
//! | [`ApiErrorKind::RateLimit`]       | `TypeSafeRateLimitError`          | 429  | `rate_limited`       |
//! | [`ApiErrorKind::Overloaded`]      | `TypeSafeAPIOverloadedError`      | 529  | `overloaded`         |
//! | [`ApiErrorKind::InternalServer`]  | `TypeSafeInternalServerError`     | 5xx  | `backend_error` / `internal_error` |
//!
//! 429/529 responses carry `retry-after-ms` (milliseconds, preferred) and
//! `Retry-After` (seconds, or an HTTP-date) headers; both are parsed into
//! [`ApiError::retry_after`] so [`crate::RetryPolicy`] can back off exactly
//! as long as the server asks.

use std::time::Duration;

mod api_error;
mod envelope;
mod retry_after;

#[cfg(test)]
mod tests;

pub use api_error::{ApiError, ApiErrorKind};
pub use retry_after::parse_retry_after;
pub(crate) use retry_after::parse_retry_after_with;
pub(crate) use retry_after::REQUEST_ID_HEADER;

/// All client failures. [`Error::Api`] wraps the unsuccessful-response case;
/// the other variants cover transport, timeout, decoding, response validation,
/// and configuration problems.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// The server responded with a non-success status. See [`ApiError`].
    ///
    /// (Boxed to keep `Result<T, Error>` small; deref coercion makes the
    /// inner [`ApiError`] fields directly accessible.)
    #[error("{0}")]
    Api(#[from] Box<ApiError>),

    /// The request could not reach, or the response could not be read from,
    /// the server.
    #[error("connection error: {0}")]
    Connection(#[source] Box<dyn std::error::Error + Send + Sync>),

    /// The request exceeded its per-attempt timeout.
    #[error("request timed out after {timeout:?}")]
    Timeout {
        /// The timeout that was in effect for the failed attempt.
        timeout: Duration,
    },

    /// A response body exceeded the client's fixed memory-safety limit.
    #[error("response body exceeded the {limit}-byte limit")]
    ResponseTooLarge {
        /// Maximum response-body size accepted by the client.
        limit: usize,
    },

    /// A 2xx response body could not be decoded as the expected type.
    #[error("failed to decode response body (status {status}): {source}")]
    Decode {
        /// HTTP status of the undecodable response.
        status: u16,
        /// The first 200 chars of the raw body, to aid debugging.
        body_excerpt: String,
        /// The underlying JSON error.
        #[source]
        source: serde_json::Error,
    },

    /// A 2xx response decoded but violated the submitted question contract.
    #[error("invalid response: {source}")]
    InvalidResponse {
        /// The violated request/response invariant. Response content is omitted.
        #[source]
        source: openkind_core::ValidationError,
    },

    /// The client was constructed with invalid settings (missing API key,
    /// bad base URL, non-positive timeout, ...).
    #[error("invalid client configuration: {0}")]
    Config(String),
}

impl Error {
    /// HTTP status, when the error originated from a server response.
    pub fn status(&self) -> Option<u16> {
        match self {
            Error::Api(api) => Some(api.status),
            _ => None,
        }
    }

    /// The server-requested retry delay, when present.
    pub fn retry_after(&self) -> Option<Duration> {
        match self {
            Error::Api(api) => api.retry_after,
            _ => None,
        }
    }

    /// The `x-typesafe-request-id` of the failed request, when present.
    pub fn request_id(&self) -> Option<&str> {
        match self {
            Error::Api(api) => api.request_id.as_deref(),
            _ => None,
        }
    }

    /// The error kind classification, when this is an API error.
    pub fn kind(&self) -> Option<ApiErrorKind> {
        match self {
            Error::Api(api) => Some(api.kind()),
            _ => None,
        }
    }
}