cc_lb_plugin_api/
errors.rs

1//! Error types shared across plugin boundaries.
2
3use thiserror::Error;
4
5use crate::types::CredentialStrategy;
6
7/// Routing failures returned by [`crate::RouterPlugin`].
8#[derive(Debug, Error)]
9pub enum RouteError {
10    /// No route matched the request and principal.
11    #[error("no route matched: {reason}")]
12    NoRoute {
13        /// Redacted mismatch reason.
14        reason: String,
15    },
16    /// The chosen upstream is unavailable or invalid.
17    #[error("upstream unavailable: {reason}")]
18    UpstreamUnavailable {
19        /// Redacted upstream reason.
20        reason: String,
21    },
22    /// Router plugin runtime failed.
23    #[error("router runtime error: {reason}")]
24    Runtime {
25        /// Redacted runtime failure reason.
26        reason: String,
27    },
28}
29
30/// Request shaping failures returned by [`crate::UpstreamDialect`].
31#[derive(Debug, Error)]
32pub enum DialectError {
33    /// The request path or method is unsupported by the dialect.
34    #[error("unsupported request: {reason}")]
35    UnsupportedRequest {
36        /// Redacted unsupported-request reason.
37        reason: String,
38    },
39    /// The selected upstream does not match the dialect.
40    #[error("upstream mismatch: {reason}")]
41    UpstreamMismatch {
42        /// Redacted mismatch reason.
43        reason: String,
44    },
45    /// URL construction failed.
46    #[error("invalid upstream url: {source}")]
47    InvalidUrl {
48        /// URL parser error.
49        #[from]
50        source: url::ParseError,
51    },
52}
53
54/// Signing failures returned by [`crate::Signer`] and [`crate::SignerFactory`].
55#[derive(Debug, Error)]
56pub enum SignerError {
57    /// No credentials are configured for the selected upstream.
58    #[error("missing credentials: {reason}")]
59    MissingCredentials {
60        /// Redacted credential reason.
61        reason: String,
62    },
63    /// Credentials exist but cannot be used.
64    #[error("invalid credentials: {reason}")]
65    InvalidCredentials {
66        /// Redacted credential reason.
67        reason: String,
68    },
69    /// Signing failed.
70    #[error("signing failed: {reason}")]
71    SigningFailed {
72        /// Redacted signing failure reason.
73        reason: String,
74    },
75    /// Credential storage is temporarily unavailable.
76    #[error("credential storage unavailable: {reason}")]
77    StorageUnavailable {
78        /// Redacted storage failure reason.
79        reason: String,
80    },
81    /// OAuth access token is expired or within the signer refresh skew window.
82    #[error("expired token: {reason}")]
83    ExpiredToken {
84        /// Redacted expiry reason.
85        reason: String,
86    },
87    /// The factory was asked to build a signer for the wrong strategy.
88    #[error("wrong signer strategy: {strategy:?}")]
89    WrongStrategy {
90        /// Selected auth strategy.
91        strategy: CredentialStrategy,
92    },
93}
94
95/// Upstream failures observed after a request has been relayed.
96#[derive(Debug, Error)]
97pub enum UpstreamError {
98    /// Upstream returned an unauthorized response.
99    #[error("upstream unauthorized with status {status}")]
100    Unauthorized {
101        /// HTTP status returned by the upstream.
102        status: http::StatusCode,
103        /// Redacted upstream response body, when available.
104        body: Option<bytes::Bytes>,
105    },
106    /// Upstream returned a retryable response.
107    #[error("upstream retryable status {status}")]
108    Retryable {
109        /// HTTP status returned by the upstream.
110        status: http::StatusCode,
111        /// Redacted upstream response body, when available.
112        body: Option<bytes::Bytes>,
113    },
114    /// Upstream returned a non-retryable response.
115    #[error("upstream failed with status {status}")]
116    Failed {
117        /// HTTP status returned by the upstream.
118        status: http::StatusCode,
119        /// Redacted upstream response body, when available.
120        body: Option<bytes::Bytes>,
121    },
122}
123
124/// Observability hook failures returned by [`crate::ObservabilityHook`].
125#[derive(Debug, Error)]
126pub enum ObservabilityError {
127    /// The bounded observability queue is full.
128    #[error("observability queue full")]
129    QueueFull,
130    /// The observability hook dropped the event.
131    #[error("observability event dropped: {reason}")]
132    Dropped {
133        /// Redacted drop reason.
134        reason: String,
135    },
136}
137
138/// Plugin runtime failures returned by [`crate::PluginRuntime`].
139#[derive(Debug, Error)]
140pub enum RuntimeError {
141    /// Plugin manifest cannot be loaded or parsed.
142    #[error("invalid plugin manifest: {reason}")]
143    InvalidManifest {
144        /// Redacted manifest failure reason.
145        reason: String,
146    },
147    /// Plugin artifact cannot be loaded.
148    #[error("plugin load failed: {reason}")]
149    LoadFailed {
150        /// Redacted load failure reason.
151        reason: String,
152    },
153    /// Plugin instantiation failed.
154    #[error("plugin instantiation failed: {reason}")]
155    InstantiateFailed {
156        /// Redacted instantiation failure reason.
157        reason: String,
158    },
159}
cc_lb_plugin_api/errors.rs

cc_lb_plugin_api/
errors.rs
