carbonfr_sdk/error.rs
1//! Erreurs typées du SDK (`CarbonFrError`) et corps **Problem Details**
2//! (RFC 9457, ADR-0021) renvoyé par l'API sur toute réponse en erreur.
3//!
4//! `CarbonFrError` et [`ProblemDetails`] sont `#[non_exhaustive]` — premier
5//! usage de cet attribut dans tout le dépôt (ADR-0031 décision 6) : un ajout
6//! de variante/champ dans une version mineure ultérieure ne doit jamais casser
7//! un `match` externe.
8
9use std::time::Duration;
10
11use serde::Deserialize;
12
13/// Corps **Problem Details** (RFC 9457) porté par [`CarbonFrError::Api`].
14///
15/// Champs privés + accesseurs (plutôt que publics comme les DTO de `core`,
16/// ADR-0030 §3) : `#[non_exhaustive]` sur une struct à champs publics
17/// interdirait la construction par littéral qu'il protège, donc les deux
18/// doctrines ne se combinent pas — ici on choisit l'ouverture par accesseurs.
19/// `code` est l'ancrage machine **stable** à matcher en priorité (`detail` est
20/// un message humain, jamais stable) — voir [`CarbonFrError::code`].
21#[derive(Debug, Clone, Default, Deserialize)]
22#[non_exhaustive]
23pub struct ProblemDetails {
24 #[serde(rename = "type", default)]
25 problem_type: Option<String>,
26 #[serde(default)]
27 title: Option<String>,
28 #[serde(default)]
29 status: Option<u16>,
30 #[serde(default)]
31 detail: Option<String>,
32 #[serde(default)]
33 code: Option<String>,
34}
35
36impl ProblemDetails {
37 /// URI du type de problème (RFC 9457 §4.2.1) — `about:blank` aujourd'hui
38 /// sur toute l'API (`status` + `code` suffisent).
39 pub fn problem_type(&self) -> Option<&str> {
40 self.problem_type.as_deref()
41 }
42
43 /// Résumé court, stable par [`code`](Self::code).
44 pub fn title(&self) -> Option<&str> {
45 self.title.as_deref()
46 }
47
48 /// Code de statut HTTP, répété dans le corps (RFC 9457 §3.1.2).
49 pub fn status(&self) -> Option<u16> {
50 self.status
51 }
52
53 /// Message lisible spécifique à l'occurrence — **jamais** un ancrage
54 /// machine (utiliser [`code`](Self::code) pour ça).
55 pub fn detail(&self) -> Option<&str> {
56 self.detail.as_deref()
57 }
58
59 /// Extension carbon-fr : ancrage machine **stable** (`no_data`,
60 /// `bad_request`, `unauthorized`, `unavailable`, `internal`,
61 /// `rate_limited`…), catalogue extensible côté serveur.
62 pub fn code(&self) -> Option<&str> {
63 self.code.as_deref()
64 }
65
66 /// Construit un [`ProblemDetails`] de repli quand le corps de la réponse
67 /// n'est pas un JSON `application/problem+json` exploitable (panne en
68 /// amont de l'API, proxy, corps vide…) : `detail` porte alors le corps
69 /// brut (tronqué), pour ne rien perdre de diagnostiquable.
70 pub(crate) fn fallback(status: u16, raw_body: &str) -> Self {
71 const MAX_LEN: usize = 500;
72 let detail = if raw_body.is_empty() {
73 None
74 } else {
75 Some(raw_body.chars().take(MAX_LEN).collect())
76 };
77 Self {
78 problem_type: None,
79 title: None,
80 status: Some(status),
81 detail,
82 code: None,
83 }
84 }
85}
86
87impl std::fmt::Display for ProblemDetails {
88 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
89 let message = self
90 .detail
91 .as_deref()
92 .or(self.title.as_deref())
93 .unwrap_or("erreur sans détail");
94 f.write_str(message)
95 }
96}
97
98/// Erreur du SDK carbon-fr.
99///
100/// `#[non_exhaustive]` (ADR-0031 décision 6) : toujours terminer un `match`
101/// externe par un bras `_` (ou `..` sur les variantes à champs).
102#[derive(Debug, thiserror::Error)]
103#[non_exhaustive]
104pub enum CarbonFrError {
105 /// Échec de transport (connexion, TLS, DNS, timeout REST — cf.
106 /// [`CarbonFrBuilder::timeout`](crate::CarbonFrBuilder::timeout)…). La clé
107 /// API circule **uniquement** en en-tête `Authorization` (jamais dans
108 /// l'URL/la query string, cf. `CarbonFr::request`) : le message affiché
109 /// par `reqwest::Error` (qui peut inclure l'URL de la requête) ne
110 /// contient donc jamais de secret.
111 #[error("erreur de transport : {0}")]
112 Transport(#[from] reqwest::Error),
113
114 /// Réponse en erreur de l'API (RFC 9457, ADR-0021). `status` répète le
115 /// code HTTP ; `problem.code()` est l'ancrage machine à privilégier
116 /// (raccourci : [`CarbonFrError::code`]).
117 #[error("erreur API carbon-fr ({status}) : {problem}")]
118 #[non_exhaustive]
119 Api {
120 status: u16,
121 problem: ProblemDetails,
122 },
123
124 /// Échec de désérialisation d'un corps de réponse JSON, ou d'un flux SSE
125 /// mal formé (trame hors grammaire WHATWG). Message auto-contenu
126 /// (`String`) plutôt qu'un type tiers (`serde_json::Error` /
127 /// `eventsource_stream::EventStreamError`) : évite d'exposer un type hors
128 /// de notre contrôle dans une variante publique `#[non_exhaustive]`.
129 #[error("échec de décodage de la réponse : {0}")]
130 Decode(String),
131
132 /// Configuration du client invalide (URL de base, provider TLS…) —
133 /// [`CarbonFrBuilder::build`](crate::CarbonFrBuilder::build) échoue
134 /// toujours par `Result`, jamais par panique ni repli silencieux sur un
135 /// client par défaut.
136 #[error("configuration du client invalide : {0}")]
137 Config(String),
138
139 /// Le délai de connexion (`CarbonFrBuilder::connect_timeout`) ou, pour le
140 /// flux SSE, le délai de lecture entre deux messages
141 /// (`StreamConfig::idle_timeout`) a été dépassé. Sur le flux, avec
142 /// reconnexion activée (par défaut), cette erreur ne sort jamais du
143 /// flux : elle déclenche une reconnexion silencieuse — voir
144 /// `IntensityStream`.
145 #[error("délai dépassé ({0:?})")]
146 Timeout(Duration),
147}
148
149impl CarbonFrError {
150 /// Ancrage machine stable (RFC 9457 `code`) si cette erreur est une
151 /// [`CarbonFrError::Api`] — `None` pour toute autre variante. À matcher
152 /// en priorité sur `detail`/le message d'affichage (ADR-0031 décision 6).
153 pub fn code(&self) -> Option<&str> {
154 match self {
155 CarbonFrError::Api { problem, .. } => problem.code(),
156 _ => None,
157 }
158 }
159
160 /// Code de statut HTTP si cette erreur est une [`CarbonFrError::Api`].
161 pub fn status(&self) -> Option<u16> {
162 match self {
163 CarbonFrError::Api { status, .. } => Some(*status),
164 _ => None,
165 }
166 }
167}