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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
//! Tolerant HTTP Problem representation preserving the complete raw object.
use http::{HeaderMap, StatusCode};
use serde_json::{Map, Value};
use crate::catalog::Code;
use super::{DecodeError, DecodeLimits, ProtocolIssue, decode_object, member};
/// Tolerantly decoded remote HTTP Problem with authoritative transport facts.
#[derive(Debug, Clone)]
pub struct ReceivedProblem {
transport_status: StatusCode,
headers: HeaderMap,
type_uri: Option<String>,
title: Option<String>,
detail: Option<String>,
instance: Option<String>,
code: Option<Code>,
body_status: Option<StatusCode>,
evidence: Option<Map<String, Value>>,
suggestions: Vec<String>,
raw: Map<String, Value>,
issues: Vec<ProtocolIssue>,
}
impl ReceivedProblem {
/// Decodes a remote Problem under explicit resource limits.
///
/// Decoding is tolerant and bounded: malformed JSON produces an error
/// rather than a panic, unknown members survive in [`raw`](Self::raw), and
/// disagreements are recorded as
/// [`protocol_issues`](Self::protocol_issues) instead of failing. Classify
/// against a local catalog to decide how to render:
///
/// ```
/// use recourse::{
/// catalog::{Catalog, CatalogSpec, CodeNumber},
/// client::{DecodeLimits, ProblemClassification, ReceivedProblem},
/// diagnostic::{DiagnosticType, NoEvidence},
/// http::{Fixed, HttpProblemType},
/// dependencies::http::{HeaderMap, StatusCode},
/// };
///
/// # enum ServiceCatalog {}
/// # impl CatalogSpec for ServiceCatalog {
/// # const NAME: &'static str = "example-service";
/// # const PREFIX: &'static str = "EXM";
/// # const TYPE_BASE: &'static str = "https://example.invalid/problems/";
/// # }
/// # enum ResourceMissing {}
/// # impl DiagnosticType for ResourceMissing {
/// # type Catalog = ServiceCatalog;
/// # type Evidence = NoEvidence;
/// # const NUMBER: CodeNumber = CodeNumber::new(1001);
/// # const TITLE: &'static str = "Resource missing";
/// # const DETAIL: &'static str = "The requested resource does not exist.";
/// # const SUGGESTIONS: &'static [&'static str] = &["Check the identifier."];
/// # const DOCS: &'static str = "Verify the identifier before retrying.";
/// # }
/// # impl HttpProblemType for ResourceMissing { type Policy = Fixed<404>; }
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let catalog = Catalog::<ServiceCatalog>::builder()
/// .problem::<ResourceMissing>()
/// .build()?;
/// // A newer server sends a code this build has never heard of.
/// let body = br#"{"code":"EXM-1999","title":"Future failure","vendor":"kept"}"#;
/// let received = ReceivedProblem::from_slice(
/// StatusCode::BAD_GATEWAY,
/// &HeaderMap::new(),
/// body,
/// DecodeLimits::default(),
/// )?;
///
/// assert!(matches!(catalog.classify(&received), ProblemClassification::Unknown));
/// assert_eq!(received.transport_status(), StatusCode::BAD_GATEWAY);
/// assert!(received.raw().contains_key("vendor"));
/// # Ok(())
/// # }
/// # assert!(example().is_ok());
/// ```
pub fn from_slice(
transport_status: StatusCode,
headers: &HeaderMap,
body: &[u8],
limits: DecodeLimits,
) -> Result<Self, DecodeError> {
let raw = decode_object(body, limits)?;
let mut issues = Vec::new();
let code = member::code(&raw, &mut issues);
let body_status = parse_status(&raw, &mut issues);
if let Some(body) = body_status.filter(|body| *body != transport_status) {
issues.push(ProtocolIssue::TransportStatusMismatch {
transport: transport_status,
body,
});
}
Ok(Self {
transport_status,
headers: headers.clone(),
type_uri: member::string(&raw, "type", &mut issues),
title: member::string(&raw, "title", &mut issues),
detail: member::string(&raw, "detail", &mut issues),
instance: member::string(&raw, "instance", &mut issues),
code,
body_status,
evidence: member::object(&raw, "evidence", &mut issues),
suggestions: member::string_array(&raw, "suggestions", &mut issues),
raw,
issues,
})
}
/// Authoritative actual HTTP response status.
pub const fn transport_status(&self) -> StatusCode {
self.transport_status
}
/// Complete validated HTTP response headers supplied by the transport.
pub const fn headers(&self) -> &HeaderMap {
&self.headers
}
/// String-valued RFC 9457 type member when present.
pub fn type_uri(&self) -> Option<&str> {
self.type_uri.as_deref()
}
/// Optional human-readable title.
pub fn title(&self) -> Option<&str> {
self.title.as_deref()
}
/// Optional human-readable detail.
pub fn detail(&self) -> Option<&str> {
self.detail.as_deref()
}
/// Optional occurrence URI-reference text.
pub fn instance(&self) -> Option<&str> {
self.instance.as_deref()
}
/// Canonical parsed diagnostic code when supplied correctly.
pub const fn code(&self) -> Option<&Code> {
self.code.as_ref()
}
/// Valid body status when supplied, even if it disagrees with transport.
pub const fn body_status(&self) -> Option<StatusCode> {
self.body_status
}
/// Object-valued public evidence when supplied correctly.
pub const fn evidence(&self) -> Option<&Map<String, Value>> {
self.evidence.as_ref()
}
/// String-valued suggestions retained in sender order.
pub fn suggestions(&self) -> &[String] {
&self.suggestions
}
/// Complete raw object, including unknown and wrong-typed members.
pub const fn raw(&self) -> &Map<String, Value> {
&self.raw
}
/// Nonfatal inconsistencies discovered during tolerant parsing.
pub fn protocol_issues(&self) -> &[ProtocolIssue] {
&self.issues
}
}
fn parse_status(raw: &Map<String, Value>, issues: &mut Vec<ProtocolIssue>) -> Option<StatusCode> {
let value = raw.get("status")?;
let Value::Number(number) = value else {
member::invalid_type(issues, "status", "integer");
return None;
};
let status = number
.as_u64()
.and_then(|value| u16::try_from(value).ok())
.and_then(|value| StatusCode::from_u16(value).ok());
if status.is_none() {
issues.push(ProtocolIssue::InvalidBodyStatus);
}
status
}