Skip to main content

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}