relay_knowledge/api/contracts/
error.rs

1use serde::{Deserialize, Serialize};
2
3use super::ApiMetadata;
4
5/// Stable error categories used across interface adapters.
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum ErrorKind {
9    InvalidArgument,
10    StorageUnavailable,
11    QosRejected,
12    Timeout,
13    Internal,
14}
15
16/// API error shape suitable for JSON and streaming output.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18pub struct ApiError {
19    pub error_kind: ErrorKind,
20    pub message: String,
21    #[serde(skip_serializing_if = "Option::is_none")]
22    pub metadata: Option<ApiMetadata>,
23}
24
25impl ApiError {
26    /// Creates an invalid argument error.
27    pub fn invalid_argument(message: impl Into<String>) -> Self {
28        Self {
29            error_kind: ErrorKind::InvalidArgument,
30            message: message.into(),
31            metadata: None,
32        }
33    }
34
35    /// Creates a storage boundary error without exposing backend internals.
36    pub fn storage_unavailable(message: impl Into<String>) -> Self {
37        Self {
38            error_kind: ErrorKind::StorageUnavailable,
39            message: message.into(),
40            metadata: None,
41        }
42    }
43
44    /// Creates a QoS admission error for bounded overload responses.
45    pub fn qos_rejected(message: impl Into<String>) -> Self {
46        Self {
47            error_kind: ErrorKind::QosRejected,
48            message: message.into(),
49            metadata: None,
50        }
51    }
52
53    /// Creates a bounded-operation timeout error.
54    pub fn timeout(message: impl Into<String>) -> Self {
55        Self {
56            error_kind: ErrorKind::Timeout,
57            message: message.into(),
58            metadata: None,
59        }
60    }
61
62    /// Creates an internal consistency error that is not attributable to user input.
63    pub fn internal(message: impl Into<String>) -> Self {
64        Self {
65            error_kind: ErrorKind::Internal,
66            message: message.into(),
67            metadata: None,
68        }
69    }
70}
71
72#[cfg(test)]
73#[path = "error_tests.rs"]
74mod tests;
relay_knowledge/api/contracts/error.rs

relay_knowledge/api/contracts/
error.rs
