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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
//! One error type for the whole crate.
//!
//! Two things are true at once about a failure in a Matter stack: it has a *local* cause
//! that a developer needs (a truncated TLV element, a nonce that did not fit) and it may
//! have a *wire* meaning that a peer is owed (Core §8.10's `INVALID_ACTION`,
//! `RESOURCE_EXHAUSTED`, …). Splitting those into two types means every layer converts
//! between them and one of the conversions is always wrong, so [`Error`] carries both: an
//! [`ErrorCode`] always, and an interaction-model status when one applies.
//!
//! Resource exhaustion is a value here, never an abort — a device that runs out of
//! exchanges answers `BUSY` and stays on the network.
use core::fmt;
/// What went wrong, locally.
///
/// The set is closed by this crate rather than by the specification, so it is
/// `#[non_exhaustive]`: new codes appear as layers land, and a consumer matching
/// exhaustively should not break for that.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ErrorCode {
// --- Encoding -------------------------------------------------------------------
/// A TLV element ended before its declared length.
TlvTruncated,
/// A control octet named a reserved element type or an illegal tag control.
TlvInvalidControl,
/// A container was not terminated by an end-of-container element, or one appeared
/// where no container was open.
TlvContainerMismatch,
/// The element is not of the type the reader was asked for.
TlvWrongType,
/// A UTF-8 string element held bytes that are not valid UTF-8.
TlvInvalidUtf8,
/// A structure member was anonymous, an array member was tagged, or a tag repeated
/// inside a structure — Core §A.5.
TlvInvalidTag,
/// Container nesting went deeper than the reader's fixed depth budget.
TlvDepthExceeded,
/// The value does not fit the requested Rust type (a `u64` read as `u8`, say).
TlvOutOfRange,
/// A required element was absent.
TlvNotFound,
/// Two members of one structure carried the same tag — Core §A.5.1: "All member elements
/// within a structure SHALL have a unique tag as compared to the other members".
TlvDuplicateTag,
// --- Message layer --------------------------------------------------------------
/// The message is shorter than its own header says it is.
MessageTruncated,
/// The message header version is not one this node speaks — Core §4.4.1.1.
UnsupportedVersion,
/// A reserved `DSIZ` or session-type value — Core §4.4.1.1, §4.4.1.3.
MessageReserved,
/// The message counter is outside the replay window, or repeats one already seen.
DuplicateMessage,
/// Decryption or the integrity check failed.
IntegrityCheckFailed,
// --- Exchanges and sessions -----------------------------------------------------
/// No exchange matches the message, and none could be created for it.
NoExchange,
/// No session matches the message's session id.
NoSession,
/// A reliable message was retransmitted `MRP_MAX_TRANSMISSIONS` times without an
/// acknowledgement — Core §4.12.
MrpRetransmitExhausted,
// --- Capacity and lifecycle -----------------------------------------------------
/// A fixed-capacity table sized by [`Config`](crate::Config) is full.
NoSpace,
/// The operation would block on a resource that is busy right now.
Busy,
/// A buffer given to this crate is too small for what was asked of it.
BufferTooSmall,
/// The argument is outside the range the specification allows.
InvalidArgument,
/// The call is not legal in the current state.
InvalidState,
/// The entry is already present and the operation does not replace it — the fabric
/// conflict of §11.18's `AddNOC`, for one.
AlreadyExists,
/// An interaction model action is malformed and must be answered with a
/// `StatusResponse` carrying `INVALID_ACTION` rather than its usual response
/// (Core §8.10).
///
/// This is an *action*-level refusal, distinct from the per-path
/// [`Status`](crate::im::Status) a response carries: there is nothing well-formed enough
/// to report a path for.
InvalidAction,
/// A report does not fit in one message and must be chunked — Core §10.2.3.
///
/// Not a failure so much as the wrong method: the read is perfectly servable, just not
/// in a single message.
/// [`Server::serve_chunk`](crate::im::Server::serve_chunk) serves it as the series of
/// messages §10.2.3 calls for. This exists so the one-message convenience can *refuse*
/// rather than emit a `MoreChunkedMessages` it has no way to honour, which would leave
/// the client waiting for a continuation that never comes.
ReportWouldChunk,
// --- Certificates ---------------------------------------------------------------
/// A Matter certificate violates one of the §6.5 encoding rules: an element out of
/// order, a value out of range, a distinguished name the certificate's type forbids.
CertInvalid,
/// A certificate chain does not validate — a signature that does not verify, an issuer
/// that does not match, a path longer than a `path-len-constraint` allows.
CertPathInvalid,
/// A certificate is being used outside its `not-before`/`not-after` window.
CertExpired,
/// The operation is defined but this build does not implement it.
Unsupported,
/// A DER encoding is malformed: a truncated element, a length that is not in DER's
/// shortest form, or a structure that is not what its context requires.
DerMalformed,
// --- Commissioning ---------------------------------------------------------------
/// §6.2.3's Device Attestation Procedure did not pass: a signature that does not verify,
/// a nonce the device did not echo back, or a chain that does not reach a trusted PAA.
///
/// §5.5 step 10 makes this a *report*, not a verdict — "the Commissioner MAY choose to
/// either continue to the Commissioning, or terminate it, depending on
/// implementation-dependent policies" — so it reaches the caller rather than ending the
/// flow on its own.
AttestationFailed,
/// A commissioning command answered with an error: §11.10.5.1's `CommissioningErrorEnum`
/// or §11.18.5.1's `NodeOperationalCertStatusEnum`, neither of which is `OK`.
CommissioningFailed,
// --- Discovery ------------------------------------------------------------------
/// A DNS message ended inside a name, a record, or a header.
DnsTruncated,
/// A DNS message is malformed: a reserved label type, a compression pointer that does
/// not point strictly backwards, a name with more labels than a Matter record has.
DnsMalformed,
// --- Transports -----------------------------------------------------------------
/// A message on a stream transport announced a length past §4.15.2.3's Maximum Message
/// Size, or a length of zero.
///
/// Fatal to the connection either way. §4.5's length prefix is the *only* message
/// boundary a stream has, so a receiver that cannot hold the message has also lost its
/// place: everything after it would be read as a header. §4.15.2.3 says to close, and
/// [`tcp::too_large`](crate::transport::tcp::too_large) is the report to send first.
MessageTooLarge,
/// A BDX transfer ended in failure, and the §11.22.3.2 status code said why.
///
/// This is the code for a caller that had to widen a
/// [`bdx::StatusCode`](crate::bdx::StatusCode) into the crate's own error type; the
/// [`bdx`](crate::bdx) module's own API keeps the status code, because it is what has to
/// be sent back to the peer.
BdxAborted,
/// A BTP packet is malformed, or breaks one of §4.19.4.5's reassembly rules: an Ending
/// segment with no Beginning, a Beginning while another SDU is in flight, a reassembled
/// length that does not match the Message Length it was promised.
///
/// Every one of these closes the BTP session. The protocol has no way to resynchronise,
/// so continuing would mean reassembling two messages into one.
BtpMalformed,
/// A BTP sequence number did not increment by one, or an acknowledgement named a packet
/// that was never sent or was already acknowledged — §4.19.4.6, §4.19.4.8. Also closes
/// the session.
BtpSequence,
/// A BTP acknowledgement did not arrive within `BTP_ACK_TIMEOUT` (§4.19.4.8). The timer
/// doubles as BTP's keep-alive, so this is also how a peer notices a remote stack that
/// has stopped answering.
BtpTimeout,
/// The platform reported a failure.
Platform,
}
impl ErrorCode {
/// A short, stable, human-readable name — the one that appears in logs.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::TlvTruncated => "tlv: truncated element",
Self::TlvInvalidControl => "tlv: reserved or invalid control octet",
Self::TlvContainerMismatch => "tlv: unbalanced container",
Self::TlvWrongType => "tlv: wrong element type",
Self::TlvInvalidUtf8 => "tlv: invalid utf-8 in string element",
Self::TlvInvalidTag => "tlv: tag not allowed in this container",
Self::TlvDepthExceeded => "tlv: nesting too deep",
Self::TlvOutOfRange => "tlv: value out of range for target type",
Self::TlvNotFound => "tlv: element not found",
Self::TlvDuplicateTag => "tlv: duplicate tag in a structure",
Self::MessageTruncated => "msg: truncated",
Self::UnsupportedVersion => "msg: unsupported version",
Self::MessageReserved => "msg: reserved field value",
Self::DuplicateMessage => "msg: duplicate or replayed counter",
Self::IntegrityCheckFailed => "msg: integrity check failed",
Self::NoExchange => "exchange: no matching exchange",
Self::NoSession => "session: no matching session",
Self::MrpRetransmitExhausted => "mrp: retransmissions exhausted",
Self::NoSpace => "no space",
Self::Busy => "busy",
Self::BufferTooSmall => "buffer too small",
Self::InvalidArgument => "invalid argument",
Self::AlreadyExists => "entry already exists",
Self::InvalidAction => "interaction model: invalid action",
Self::ReportWouldChunk => "report does not fit one message",
Self::AttestationFailed => "attestation: §6.2.3's procedure did not pass",
Self::CommissioningFailed => "commissioning: the device answered with an error",
Self::CertInvalid => "cert: violates the §6.5 encoding rules",
Self::CertPathInvalid => "cert: chain does not validate",
Self::CertExpired => "cert: outside its validity window",
Self::Unsupported => "unsupported",
Self::DerMalformed => "der: malformed encoding",
Self::DnsTruncated => "dns: truncated message",
Self::DnsMalformed => "dns: malformed message",
Self::MessageTooLarge => "transport: message past the stream's maximum size",
Self::BdxAborted => "bdx: transfer aborted",
Self::BtpMalformed => "btp: malformed packet or reassembly",
Self::BtpSequence => "btp: sequence or acknowledgement out of order",
Self::BtpTimeout => "btp: acknowledgement timeout",
Self::InvalidState => "invalid state",
Self::Platform => "platform error",
}
}
}
/// A failure, with its local cause and — when the specification gives it one — the status
/// code a peer is owed.
///
/// The interaction-model status is filled in by the `im` module once that layer exists; the
/// field is here from the start so that lower layers can already answer, for example,
/// `RESOURCE_EXHAUSTED` for [`ErrorCode::NoSpace`] without a second error type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Error {
code: ErrorCode,
}
impl Error {
/// Builds an error from its local cause.
#[must_use]
pub const fn new(code: ErrorCode) -> Self {
Self { code }
}
/// The local cause.
#[must_use]
pub const fn code(self) -> ErrorCode {
self.code
}
}
impl From<ErrorCode> for Error {
fn from(code: ErrorCode) -> Self {
Self::new(code)
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.code.as_str())
}
}
impl fmt::Display for ErrorCode {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[cfg(feature = "std")]
impl std::error::Error for Error {}
/// The crate's result type.
pub type Result<T, E = Error> = core::result::Result<T, E>;
/// Builds an [`Err`] from an [`ErrorCode`] without the `Error::new` ceremony.
macro_rules! bail {
($code:ident) => {
return Err($crate::error::Error::new($crate::error::ErrorCode::$code))
};
}
pub(crate) use bail;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn display_is_the_code_name() {
let e = Error::new(ErrorCode::TlvTruncated);
#[cfg(feature = "std")]
assert_eq!(std::format!("{e}"), "tlv: truncated element");
assert_eq!(e.code(), ErrorCode::TlvTruncated);
}
#[test]
fn every_code_has_a_name() {
// A code whose name is empty is a code somebody added without a message.
for code in [
ErrorCode::TlvTruncated,
ErrorCode::NoSpace,
ErrorCode::Busy,
ErrorCode::Platform,
] {
assert!(!code.as_str().is_empty());
}
}
}