matter_kit/im/status.rs
1//! Interaction model status codes (Core §8.10).
2//!
3//! One byte, sent back for every path of every action that did not simply succeed. The
4//! table is long and most of it is history: §8.10.1 marks a dozen values "reserved" with
5//! notes like "Deprecated: use FAILURE" or "ZCL OTA Upgrade cluster specific", left over
6//! from the Zigbee Cluster Library this interaction model grew out of.
7//!
8//! Those are kept as [`Status::Reserved`] rather than dropped. A peer that sends one is
9//! doing something wrong, but a *proxy* that could not represent it would have to invent a
10//! substitute, and a status code invented in the middle of a path is worse than one that is
11//! merely obsolete.
12
13/// A status code (§8.10.1).
14///
15/// `SUCCESS` and `FAILURE` are the two general outcomes; everything else says which check
16/// failed, and a client is expected to distinguish them — §8.10 exists so that "attribute
17/// does not exist" and "you may not read it" are different answers.
18#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
19#[non_exhaustive]
20pub enum Status {
21 /// `0x00` — "Operation was successful."
22 #[default]
23 Success,
24 /// `0x01` — "Operation was not successful."
25 Failure,
26 /// `0x7D` — "Subscription ID is not active."
27 InvalidSubscription,
28 /// `0x7E` — the sender lacks the privilege this action needs. Distinct from
29 /// [`Status::UnsupportedAttribute`] on purpose: which one is returned tells a client
30 /// whether the thing exists.
31 UnsupportedAccess,
32 /// `0x7F` — "The endpoint indicated is unsupported."
33 UnsupportedEndpoint,
34 /// `0x80` — "The action is malformed, has missing fields, or fields with invalid
35 /// values. Action not carried out."
36 InvalidAction,
37 /// `0x81` — "The indicated command ID is not supported on the cluster instance. Command
38 /// not carried out."
39 UnsupportedCommand,
40 /// `0x85` — "The cluster command is malformed, has missing fields, or fields with
41 /// invalid values. Command not carried out."
42 InvalidCommand,
43 /// `0x86` — "The indicated attribute ID, field ID or list entry does not exist for an
44 /// attribute path."
45 UnsupportedAttribute,
46 /// `0x87` — "Out of range error or set to a reserved value. Attribute keeps its old
47 /// value."
48 ConstraintError,
49 /// `0x88` — "Attempt to write a read-only attribute."
50 UnsupportedWrite,
51 /// `0x89` — "An action or operation failed due to insufficient available resources."
52 ResourceExhausted,
53 /// `0x8B` — "The indicated data field or entry could not be found."
54 NotFound,
55 /// `0x8C` — "Reports cannot be issued for this attribute."
56 UnreportableAttribute,
57 /// `0x8D` — "The data type indicated is undefined or invalid."
58 InvalidDataType,
59 /// `0x8F` — "Attempt to read a write-only attribute."
60 UnsupportedRead,
61 /// `0x92` — "Cluster instance data version did not match request path". What a
62 /// `DataVersionFilter` produces when the client's cached version is stale.
63 DataVersionMismatch,
64 /// `0x94` — "The transaction was aborted due to time being exceeded."
65 Timeout,
66 /// `0x9B` — "The node ID indicated is not supported."
67 UnsupportedNode,
68 /// `0x9C` — "The receiver is busy processing another action."
69 Busy,
70 /// `0x9D` — access is barred by an Access Restriction List (§6.6).
71 AccessRestricted,
72 /// `0xC3` — "The cluster indicated is not supported."
73 UnsupportedCluster,
74 /// `0xC5` — "Used by proxies to convey to clients the lack of an upstream
75 /// subscription."
76 NoUpstreamSubscription,
77 /// `0xC6` — "A Untimed Write or Untimed Invoke interaction was received for an
78 /// attribute or command requiring a Timed interaction."
79 NeedsTimedInteraction,
80 /// `0xC7` — "The indicated event ID is not supported."
81 UnsupportedEvent,
82 /// `0xC8` — "The receiver has insufficient resources to process all the paths in the
83 /// request."
84 PathsExhausted,
85 /// `0xC9` — a `TimedRequest` flag that disagrees with whether a Timed interaction is
86 /// actually in progress.
87 TimedRequestMismatch,
88 /// `0xCA` — "A request requiring a Fail-safe context was invoked without one."
89 FailsafeRequired,
90 /// `0xCB` — "The received request cannot be handled due to the current operational
91 /// state of the device."
92 InvalidInState,
93 /// `0xCC` — "A CommandDataIB is missing a response."
94 NoCommandResponse,
95 /// `0xCD` — the node requires updated Terms and Conditions acceptance.
96 TermsAndConditionsChanged,
97 /// `0xCE` — the node requires user maintenance before it can serve this request.
98 MaintenanceRequired,
99 /// `0xCF` — "The value for the data type was not accepted due to runtime validation
100 /// issues."
101 ///
102 /// Distinct from [`Status::ConstraintError`] on purpose: that one means the value was
103 /// outside the *schema's* range, this one that it was inside the schema and wrong for
104 /// the device's current state — a setpoint below the heating limit, say.
105 DynamicConstraintError,
106 /// `0xD0` — "Attempt to create an entity that already exists or create an entity with an
107 /// identifier that is already in use."
108 AlreadyExists,
109 /// `0xD1` — "Attempt to process on a transport type not valid for this element."
110 ///
111 /// §8.8.2.3 step b.iv: what a command with the Large Message quality (§7.7.5) answers
112 /// when it arrives over UDP rather than TCP.
113 InvalidTransportType,
114 /// A value §8.10.1 marks reserved, or one this revision does not know.
115 ///
116 /// Kept rather than folded into [`Status::Failure`]: a proxy that had to substitute a
117 /// code it could represent would be inventing an answer, and a status invented in the
118 /// middle of a path is worse than one that is merely obsolete.
119 Reserved(u8),
120}
121
122impl Status {
123 /// The code a peer sends.
124 #[must_use]
125 pub const fn value(self) -> u8 {
126 match self {
127 Self::Success => 0x00,
128 Self::Failure => 0x01,
129 Self::InvalidSubscription => 0x7D,
130 Self::UnsupportedAccess => 0x7E,
131 Self::UnsupportedEndpoint => 0x7F,
132 Self::InvalidAction => 0x80,
133 Self::UnsupportedCommand => 0x81,
134 Self::InvalidCommand => 0x85,
135 Self::UnsupportedAttribute => 0x86,
136 Self::ConstraintError => 0x87,
137 Self::UnsupportedWrite => 0x88,
138 Self::ResourceExhausted => 0x89,
139 Self::NotFound => 0x8B,
140 Self::UnreportableAttribute => 0x8C,
141 Self::InvalidDataType => 0x8D,
142 Self::UnsupportedRead => 0x8F,
143 Self::DataVersionMismatch => 0x92,
144 Self::Timeout => 0x94,
145 Self::UnsupportedNode => 0x9B,
146 Self::Busy => 0x9C,
147 Self::AccessRestricted => 0x9D,
148 Self::UnsupportedCluster => 0xC3,
149 Self::NoUpstreamSubscription => 0xC5,
150 Self::NeedsTimedInteraction => 0xC6,
151 Self::UnsupportedEvent => 0xC7,
152 Self::PathsExhausted => 0xC8,
153 Self::TimedRequestMismatch => 0xC9,
154 Self::FailsafeRequired => 0xCA,
155 Self::InvalidInState => 0xCB,
156 Self::NoCommandResponse => 0xCC,
157 Self::TermsAndConditionsChanged => 0xCD,
158 Self::MaintenanceRequired => 0xCE,
159 Self::DynamicConstraintError => 0xCF,
160 Self::AlreadyExists => 0xD0,
161 Self::InvalidTransportType => 0xD1,
162 Self::Reserved(v) => v,
163 }
164 }
165
166 /// The status a code names.
167 #[must_use]
168 pub const fn from_value(value: u8) -> Self {
169 match value {
170 0x00 => Self::Success,
171 0x01 => Self::Failure,
172 0x7D => Self::InvalidSubscription,
173 0x7E => Self::UnsupportedAccess,
174 0x7F => Self::UnsupportedEndpoint,
175 0x80 => Self::InvalidAction,
176 0x81 => Self::UnsupportedCommand,
177 0x85 => Self::InvalidCommand,
178 0x86 => Self::UnsupportedAttribute,
179 0x87 => Self::ConstraintError,
180 0x88 => Self::UnsupportedWrite,
181 0x89 => Self::ResourceExhausted,
182 0x8B => Self::NotFound,
183 0x8C => Self::UnreportableAttribute,
184 0x8D => Self::InvalidDataType,
185 0x8F => Self::UnsupportedRead,
186 0x92 => Self::DataVersionMismatch,
187 0x94 => Self::Timeout,
188 0x9B => Self::UnsupportedNode,
189 0x9C => Self::Busy,
190 0x9D => Self::AccessRestricted,
191 0xC3 => Self::UnsupportedCluster,
192 0xC5 => Self::NoUpstreamSubscription,
193 0xC6 => Self::NeedsTimedInteraction,
194 0xC7 => Self::UnsupportedEvent,
195 0xC8 => Self::PathsExhausted,
196 0xC9 => Self::TimedRequestMismatch,
197 0xCA => Self::FailsafeRequired,
198 0xCB => Self::InvalidInState,
199 0xCC => Self::NoCommandResponse,
200 0xCD => Self::TermsAndConditionsChanged,
201 0xCE => Self::MaintenanceRequired,
202 0xCF => Self::DynamicConstraintError,
203 0xD0 => Self::AlreadyExists,
204 0xD1 => Self::InvalidTransportType,
205 other => Self::Reserved(other),
206 }
207 }
208
209 /// Whether this is [`Status::Success`].
210 #[must_use]
211 pub const fn is_success(self) -> bool {
212 matches!(self, Self::Success)
213 }
214}
215
216impl core::fmt::Display for Status {
217 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
218 let name = match self {
219 Self::Success => "SUCCESS",
220 Self::Failure => "FAILURE",
221 Self::InvalidSubscription => "INVALID_SUBSCRIPTION",
222 Self::UnsupportedAccess => "UNSUPPORTED_ACCESS",
223 Self::UnsupportedEndpoint => "UNSUPPORTED_ENDPOINT",
224 Self::InvalidAction => "INVALID_ACTION",
225 Self::UnsupportedCommand => "UNSUPPORTED_COMMAND",
226 Self::InvalidCommand => "INVALID_COMMAND",
227 Self::UnsupportedAttribute => "UNSUPPORTED_ATTRIBUTE",
228 Self::ConstraintError => "CONSTRAINT_ERROR",
229 Self::UnsupportedWrite => "UNSUPPORTED_WRITE",
230 Self::ResourceExhausted => "RESOURCE_EXHAUSTED",
231 Self::NotFound => "NOT_FOUND",
232 Self::UnreportableAttribute => "UNREPORTABLE_ATTRIBUTE",
233 Self::InvalidDataType => "INVALID_DATA_TYPE",
234 Self::UnsupportedRead => "UNSUPPORTED_READ",
235 Self::DataVersionMismatch => "DATA_VERSION_MISMATCH",
236 Self::Timeout => "TIMEOUT",
237 Self::UnsupportedNode => "UNSUPPORTED_NODE",
238 Self::Busy => "BUSY",
239 Self::AccessRestricted => "ACCESS_RESTRICTED",
240 Self::UnsupportedCluster => "UNSUPPORTED_CLUSTER",
241 Self::NoUpstreamSubscription => "NO_UPSTREAM_SUBSCRIPTION",
242 Self::NeedsTimedInteraction => "NEEDS_TIMED_INTERACTION",
243 Self::UnsupportedEvent => "UNSUPPORTED_EVENT",
244 Self::PathsExhausted => "PATHS_EXHAUSTED",
245 Self::TimedRequestMismatch => "TIMED_REQUEST_MISMATCH",
246 Self::FailsafeRequired => "FAILSAFE_REQUIRED",
247 Self::InvalidInState => "INVALID_IN_STATE",
248 Self::NoCommandResponse => "NO_COMMAND_RESPONSE",
249 Self::TermsAndConditionsChanged => "TERMS_AND_CONDITIONS_CHANGED",
250 Self::MaintenanceRequired => "MAINTENANCE_REQUIRED",
251 Self::DynamicConstraintError => "DYNAMIC_CONSTRAINT_ERROR",
252 Self::AlreadyExists => "ALREADY_EXISTS",
253 Self::InvalidTransportType => "INVALID_TRANSPORT_TYPE",
254 Self::Reserved(_) => "reserved",
255 };
256 f.write_str(name)
257 }
258}
259
260#[cfg(test)]
261mod tests {
262 use super::*;
263
264 #[test]
265 fn every_code_round_trips() {
266 // Including the reserved ones: a proxy has to be able to pass on a status it does
267 // not understand without substituting one it does.
268 for value in 0..=u8::MAX {
269 assert_eq!(Status::from_value(value).value(), value, "{value:#04x}");
270 }
271 }
272
273 #[test]
274 fn the_codes_match_the_spec_table() {
275 // §8.10.1, spot-checked at the boundaries of each run of defined values.
276 let cases = [
277 (Status::Success, 0x00u8),
278 (Status::Failure, 0x01),
279 (Status::InvalidSubscription, 0x7D),
280 (Status::UnsupportedEndpoint, 0x7F),
281 (Status::InvalidAction, 0x80),
282 (Status::UnsupportedAttribute, 0x86),
283 (Status::UnsupportedRead, 0x8F),
284 (Status::DataVersionMismatch, 0x92),
285 (Status::AccessRestricted, 0x9D),
286 (Status::UnsupportedCluster, 0xC3),
287 (Status::NeedsTimedInteraction, 0xC6),
288 (Status::MaintenanceRequired, 0xCE),
289 (Status::DynamicConstraintError, 0xCF),
290 (Status::AlreadyExists, 0xD0),
291 (Status::InvalidTransportType, 0xD1),
292 ];
293 for (status, value) in cases {
294 assert_eq!(status.value(), value, "{status}");
295 assert_eq!(Status::from_value(value), status, "{value:#04x}");
296 }
297 }
298
299 #[test]
300 fn deprecated_codes_stay_reserved() {
301 // §8.10.1 marks these "Deprecated: use FAILURE" and the ZCL OTA range "reserved".
302 // Mapping them onto Failure would lose what the peer actually said.
303 for value in [0x82u8, 0x83, 0x84, 0x8A, 0x90, 0x95, 0x9A, 0xC0, 0xC4] {
304 assert_eq!(Status::from_value(value), Status::Reserved(value));
305 }
306 }
307
308 #[test]
309 fn the_table_ends_at_d1() {
310 // §8.10.1's last three codes were added after the ones before them and are easy to
311 // stop short of. Anything above 0xD1 is genuinely undefined.
312 assert_eq!(Status::from_value(0xD1), Status::InvalidTransportType);
313 assert_eq!(Status::from_value(0xD2), Status::Reserved(0xD2));
314 assert_eq!(Status::from_value(0xFF), Status::Reserved(0xFF));
315 }
316
317 #[test]
318 fn the_two_constraint_errors_are_distinct() {
319 // §8.10.1 gives them different codes because they mean different things: one is a
320 // value outside the schema's range, the other a value inside it and wrong for the
321 // device's current state. A client retries differently.
322 assert_ne!(Status::ConstraintError, Status::DynamicConstraintError);
323 assert_eq!(Status::ConstraintError.value(), 0x87);
324 assert_eq!(Status::DynamicConstraintError.value(), 0xCF);
325 }
326
327 #[test]
328 fn only_success_is_success() {
329 assert!(Status::Success.is_success());
330 assert!(!Status::Failure.is_success());
331 assert!(
332 !Status::Reserved(0).is_success(),
333 "0x00 is Success, not Reserved"
334 );
335 }
336}