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
//! The client's error type.
//!
//! Mirrors [`algo_ops::AlgoError`] in shape: a `kind` plus the operation and a message, carrying a
//! plain-typed classification across the boundary (no `reqwest` types) so a consumer built against a
//! different HTTP-stack version can match on the failure without a version bump.
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum SidewinderErrorKind {
/// The node could not be reached (connection refused, DNS failure, timeout).
HostUnreachable,
/// A transient error that exhausted all retries.
TransientFailure,
/// The request was rejected for a missing or invalid bearer token (HTTP 401).
Unauthorized,
/// The node was reached over mutual TLS and **refused this client's identity** at the handshake:
/// the account is not a permitted client on that node (not opted in to the membership application,
/// its client permission bit is not set, or the node has not yet polled a newly set bit). Not a
/// network fault, so it is never retried by the client — retrying cannot change the answer until
/// the account's on-chain membership does.
IdentityRefused,
/// The node has no record of the requested resource (HTTP 404).
NotFound,
/// The request was malformed and the node rejected it (HTTP 400).
BadRequest,
/// The node returned an unexpected HTTP status.
UnexpectedStatus,
/// The node's response body could not be decoded (bad JSON, bad base64, unknown enum).
MalformedResponse,
/// A transaction could not be built or encoded from the values supplied (caught client-side,
/// before any request is sent) — for example a field that is not the required 32 bytes.
InvalidTransaction,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SidewinderError {
pub kind: SidewinderErrorKind,
pub operation: String,
/// The HTTP status, when the failure carried one.
pub status: Option<u16>,
pub message: String,
}
impl std::fmt::Display for SidewinderError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self.status {
Some(status) => write!(
f,
"SidewinderError ({:?}): operation '{}' failed (HTTP {}): {}",
self.kind, self.operation, status, self.message
),
None => write!(
f,
"SidewinderError ({:?}): operation '{}' failed: {}",
self.kind, self.operation, self.message
),
}
}
}
impl std::error::Error for SidewinderError {}
impl SidewinderError {
pub fn unreachable(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::HostUnreachable,
operation: operation.to_string(),
status: None,
message: message.to_string(),
}
}
pub fn transient(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::TransientFailure,
operation: operation.to_string(),
status: None,
message: message.to_string(),
}
}
pub fn unauthorized(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::Unauthorized,
operation: operation.to_string(),
status: Some(401),
message: message.to_string(),
}
}
/// The node refused this client's identity at the mutual-TLS handshake (see
/// [`SidewinderErrorKind::IdentityRefused`]).
pub fn identity_refused(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::IdentityRefused,
operation: operation.to_string(),
status: None,
message: message.to_string(),
}
}
pub fn not_found(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::NotFound,
operation: operation.to_string(),
status: Some(404),
message: message.to_string(),
}
}
pub fn bad_request(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::BadRequest,
operation: operation.to_string(),
status: Some(400),
message: message.to_string(),
}
}
pub fn unexpected_status(operation: &str, status: u16, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::UnexpectedStatus,
operation: operation.to_string(),
status: Some(status),
message: message.to_string(),
}
}
pub fn malformed_response(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::MalformedResponse,
operation: operation.to_string(),
status: None,
message: message.to_string(),
}
}
/// A locally-detected failure to build or encode a transaction (no request was sent).
pub fn invalid_transaction(operation: &str, message: &str) -> Self {
Self {
kind: SidewinderErrorKind::InvalidTransaction,
operation: operation.to_string(),
status: None,
message: message.to_string(),
}
}
/// True when a `reqwest` error string looks like an unreachable host rather than a served
/// HTTP response, so [`crate::SidewinderClient`] can retry it. Mirrors the algo_ops heuristic.
///
/// The client checks for a refused identity first (a typed check on the error's cause chain, not
/// this string heuristic), so a node that answered "no" is not mistaken for one that never answered.
pub fn looks_unreachable(message: &str) -> bool {
let s = message.to_lowercase();
s.contains("tcp connect error")
|| s.contains("connection refused")
|| s.contains("connection reset")
|| s.contains("timed out")
|| s.contains("timeout")
|| s.contains("dns error")
|| s.contains("host unreachable")
|| s.contains("error sending request")
}
}