Skip to main content

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}