Skip to main content

matter_kit/tlv/
codec.rs

1//! Turning Rust values into TLV elements, and back (Core Appendix A).
2//!
3//! [`TlvWriter`] and [`TlvReader`] are the wire format. This is the layer above: two traits
4//! that say how one *type* is written and read, so a structure's fields compose rather than
5//! each being spelled out at every call site.
6//!
7//! It exists because the cluster library is generated. A hand-written cluster can afford to
8//! write its own encode and decode — `binding::Target` does — but 193 structures and 434
9//! command payloads cannot each be bespoke, and a nested structure or a `list[T]` field has to
10//! reach the same code the top level does.
11//!
12//! # Three things Matter distinguishes that Rust would not
13//!
14//! * **absent** — the field is not in the structure at all. `Option<T>` on the Rust side, and
15//!   decided by the *container*, which is why there is no blanket `FromTlv for Option<T>`:
16//!   absence is not something an element can be.
17//! * **null** — the field is present and its value is TLV null (§7.12's `X` quality).
18//!   [`Nullable<T>`], so `Option<Nullable<T>>` says "may be missing, and may be null" without
19//!   the two collapsing into one `None` that means neither.
20//! * **empty** — a list that is present with no members, which is different again from absent.
21//!
22//! # Lists stay on the wire
23//!
24//! [`TlvList`] holds the encoded members and decodes them one at a time. A device cannot
25//! allocate, and a fixed-capacity array sized for the largest list any cluster might carry
26//! would cost more than the whole rest of the structure — so a list is read where it lies, and
27//! a caller that needs one element does not pay for the other two hundred.
28
29use core::marker::PhantomData;
30
31use super::reader::{Element, TlvReader, Value};
32use super::types::{ContainerKind, Tag};
33use super::writer::TlvWriter;
34use crate::error::{Error, ErrorCode, Result, bail};
35
36/// A value that can be written as one TLV element.
37pub trait ToTlv {
38    /// Writes it under `tag`.
39    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()>;
40}
41
42/// A value that can be read from one TLV element.
43///
44/// `element` is what [`TlvReader::next_element`] just produced — its control octet and tag are
45/// already consumed, so an implementation reads the *value*, and for a container reads its
46/// members and the end-of-container that closes it.
47pub trait FromTlv<'a>: Sized {
48    /// Reads it.
49    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self>;
50}
51
52// --- Primitives ---------------------------------------------------------------------------
53
54impl ToTlv for bool {
55    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
56        w.bool(tag, *self)
57    }
58}
59
60impl FromTlv<'_> for bool {
61    fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
62        element.bool()
63    }
64}
65
66/// The unsigned types, which all narrow from TLV's `u64`.
67///
68/// A value too wide for the field is [`ErrorCode::TlvOutOfRange`] rather than a truncation:
69/// §7.19.2 answers an out-of-range value `CONSTRAINT_ERROR`, and silently keeping the low
70/// octets would turn a rejected command into an accepted one with different arguments.
71macro_rules! unsigned {
72    ($($ty:ty),+) => {$(
73        impl ToTlv for $ty {
74            fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
75                w.unsigned(tag, u64::from(*self))
76            }
77        }
78
79        impl FromTlv<'_> for $ty {
80            fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
81                Self::try_from(element.unsigned()?)
82                    .map_err(|_| Error::new(ErrorCode::TlvOutOfRange))
83            }
84        }
85    )+};
86}
87unsigned!(u8, u16, u32);
88
89impl ToTlv for u64 {
90    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
91        w.unsigned(tag, *self)
92    }
93}
94
95impl FromTlv<'_> for u64 {
96    fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
97        element.unsigned()
98    }
99}
100
101macro_rules! signed {
102    ($($ty:ty),+) => {$(
103        impl ToTlv for $ty {
104            fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
105                w.signed(tag, i64::from(*self))
106            }
107        }
108
109        impl FromTlv<'_> for $ty {
110            fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
111                Self::try_from(element.signed()?)
112                    .map_err(|_| Error::new(ErrorCode::TlvOutOfRange))
113            }
114        }
115    )+};
116}
117signed!(i8, i16, i32);
118
119impl ToTlv for i64 {
120    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
121        w.signed(tag, *self)
122    }
123}
124
125impl FromTlv<'_> for i64 {
126    fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
127        element.signed()
128    }
129}
130
131impl ToTlv for f32 {
132    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
133        w.float(tag, *self)
134    }
135}
136
137impl FromTlv<'_> for f32 {
138    fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
139        match element.value {
140            Value::Float(v) => Ok(v),
141            // A `single` field carrying a double is not a rounding decision this layer may
142            // make: §A.7.2 lets an encoder choose the narrower form, never the wider.
143            _ => Err(Error::new(ErrorCode::TlvWrongType)),
144        }
145    }
146}
147
148impl ToTlv for f64 {
149    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
150        w.double(tag, *self)
151    }
152}
153
154impl FromTlv<'_> for f64 {
155    fn from_tlv(_reader: &mut TlvReader<'_>, element: &Element<'_>) -> Result<Self> {
156        match element.value {
157            Value::Double(v) => Ok(v),
158            // Widening is lossless and §A.7.2 permits the narrower encoding, so a `double`
159            // field carrying a `single` is a conforming encoder being economical.
160            Value::Float(v) => Ok(f64::from(v)),
161            _ => Err(Error::new(ErrorCode::TlvWrongType)),
162        }
163    }
164}
165
166impl ToTlv for &str {
167    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
168        w.utf8(tag, self)
169    }
170}
171
172impl<'a> FromTlv<'a> for &'a str {
173    fn from_tlv(_reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
174        element.utf8()
175    }
176}
177
178impl ToTlv for &[u8] {
179    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
180        w.octets(tag, self)
181    }
182}
183
184impl<'a> FromTlv<'a> for &'a [u8] {
185    fn from_tlv(_reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
186        element.octets()
187    }
188}
189
190// --- The identifier newtypes ----------------------------------------------------------------
191
192/// The crate's identifier types, so a field typed `node-id` cannot be handed a `group-id`.
193///
194/// The specification distinguishes them and so does this: they are all integers on the wire,
195/// and the compiler is the only thing that will notice two of them swapped.
196macro_rules! newtype {
197    ($($ty:path => $inner:ty),+ $(,)?) => {$(
198        impl ToTlv for $ty {
199            fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
200                self.0.to_tlv(w, tag)
201            }
202        }
203
204        impl<'a> FromTlv<'a> for $ty {
205            fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
206                <$inner as FromTlv<'a>>::from_tlv(reader, element).map(Self)
207            }
208        }
209    )+};
210}
211newtype!(
212    crate::msg::NodeId => u64,
213    crate::msg::GroupId => u16,
214    crate::msg::VendorId => u16,
215    crate::msg::FabricIndex => u8,
216);
217
218// --- Null ------------------------------------------------------------------------------------
219
220/// A field that may be TLV null — §7.12's `X` quality.
221///
222/// Distinct from `Option<T>` on purpose. `Option<T>` is a field that may be *absent*, and a
223/// field can be both: `Option<Nullable<T>>` says "may be missing, and if present may be null",
224/// which is three states the specification really does distinguish. Collapsing them loses the
225/// difference between "the device does not implement this" and "the device implements it and
226/// has no value" — which is exactly the difference between §11.12.5.6's null
227/// `OffPremiseServicesReachableIPv4` and its absence.
228#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
229pub struct Nullable<T>(pub Option<T>);
230
231impl<T> Nullable<T> {
232    /// A value.
233    pub const fn some(value: T) -> Self {
234        Self(Some(value))
235    }
236
237    /// TLV null.
238    pub const fn null() -> Self {
239        Self(None)
240    }
241
242    /// Whether it is null.
243    pub const fn is_null(&self) -> bool {
244        self.0.is_none()
245    }
246}
247
248impl<T: ToTlv> ToTlv for Nullable<T> {
249    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
250        match &self.0 {
251            Some(value) => value.to_tlv(w, tag),
252            None => w.null(tag),
253        }
254    }
255}
256
257impl<'a, T: FromTlv<'a>> FromTlv<'a> for Nullable<T> {
258    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
259        if element.value.is_null() {
260            return Ok(Self(None));
261        }
262        T::from_tlv(reader, element).map(Self::some)
263    }
264}
265
266// --- Lists -----------------------------------------------------------------------------------
267
268/// A `list[T]` field, read where it lies.
269///
270/// Holds the encoded *members* — everything between the array's opening element and its
271/// end-of-container — and decodes them on demand. A device cannot allocate, and a
272/// fixed-capacity array sized for the largest list any cluster might carry would cost more
273/// than the whole rest of the structure; a caller that wants one entry should not pay for the
274/// other two hundred.
275///
276/// The trade is that a member's own errors surface during iteration rather than at decode, so
277/// [`TlvList::iter`] yields `Result`. That is honest: nothing has looked at member 47 yet.
278#[derive(Debug, Clone, Copy, PartialEq, Eq)]
279pub struct TlvList<'a, T> {
280    members: &'a [u8],
281    _entry: PhantomData<fn() -> T>,
282}
283
284impl<T> Default for TlvList<'_, T> {
285    /// An empty list, which is a different thing from an absent one.
286    fn default() -> Self {
287        Self {
288            members: &[],
289            _entry: PhantomData,
290        }
291    }
292}
293
294impl<'a, T> TlvList<'a, T> {
295    /// A list over already-encoded members.
296    #[must_use]
297    pub const fn from_members(members: &'a [u8]) -> Self {
298        Self {
299            members,
300            _entry: PhantomData,
301        }
302    }
303
304    /// The encoded members, for a caller forwarding the list without reading it.
305    #[must_use]
306    pub const fn members(&self) -> &'a [u8] {
307        self.members
308    }
309
310    /// Whether the list has no members.
311    #[must_use]
312    pub const fn is_empty(&self) -> bool {
313        self.members.is_empty()
314    }
315}
316
317impl<'a, T: FromTlv<'a>> TlvList<'a, T> {
318    /// The entries, decoded one at a time.
319    pub fn iter(&self) -> impl Iterator<Item = Result<T>> + 'a {
320        let mut reader = TlvReader::new_members(self.members, ContainerKind::Array);
321        core::iter::from_fn(move || match reader.next_element() {
322            Ok(None) => None,
323            Ok(Some(element)) if element.value == Value::EndOfContainer => None,
324            Ok(Some(element)) => Some(T::from_tlv(&mut reader, &element)),
325            Err(error) => Some(Err(error)),
326        })
327    }
328
329    /// How many entries it has, by walking it.
330    ///
331    /// Not `len`, because it is not free: the members are on the wire and counting them means
332    /// decoding their headers. A caller in a loop should iterate rather than ask twice.
333    pub fn count(&self) -> Result<usize> {
334        let mut n = 0usize;
335        for entry in self.iter() {
336            entry?;
337            n = n.saturating_add(1);
338        }
339        Ok(n)
340    }
341}
342
343impl<T> ToTlv for TlvList<'_, T> {
344    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
345        w.start_array(tag)?;
346        // Member by member through `raw_element`, which re-validates each against the array
347        // it is going into. Copying the span wholesale would be faster and would also let a
348        // list decoded in one context be spliced into another where its tags are illegal.
349        let mut reader = TlvReader::new_members(self.members, ContainerKind::Array);
350        loop {
351            let start = reader.position();
352            let Some(element) = reader.next_element()? else {
353                break;
354            };
355            if element.value == Value::EndOfContainer {
356                break;
357            }
358            reader.skip_value(&element)?;
359            w.raw_element(reader.slice_from(start)?)?;
360        }
361        w.end_container()
362    }
363}
364
365impl<'a, T> FromTlv<'a> for TlvList<'a, T> {
366    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
367        if element.value.container() != Some(ContainerKind::Array) {
368            bail!(TlvWrongType)
369        }
370        // The opening element is already consumed, so the members start here. Walking to the
371        // end-of-container rather than skipping to it is what makes the span exact: the
372        // terminator must be *outside* it, or a reader over the members would meet an
373        // end-of-container for a container it was never told it is inside.
374        let start = reader.position();
375        let end = loop {
376            let before = reader.position();
377            let Some(member) = reader.next_element()? else {
378                bail!(TlvTruncated)
379            };
380            if member.value == Value::EndOfContainer {
381                break before;
382            }
383            reader.skip_value(&member)?;
384        };
385        let members = reader
386            .slice_from(start)?
387            .get(..end.saturating_sub(start))
388            .ok_or(Error::new(ErrorCode::TlvTruncated))?;
389        Ok(Self::from_members(members))
390    }
391}
392
393#[cfg(test)]
394mod tests {
395    use super::*;
396
397    fn round_trip<'a, T>(value: &T, buf: &'a mut [u8]) -> &'a [u8]
398    where
399        T: ToTlv,
400    {
401        let mut w = TlvWriter::new(buf);
402        value.to_tlv(&mut w, Tag::Anonymous).expect("encode");
403        w.finish().expect("finish")
404    }
405
406    fn decode<'a, T: FromTlv<'a>>(bytes: &'a [u8]) -> Result<T> {
407        let mut reader = TlvReader::new(bytes);
408        let element = reader.next_element()?.expect("an element");
409        T::from_tlv(&mut reader, &element)
410    }
411
412    #[test]
413    fn the_primitives_round_trip() {
414        let mut buf = [0u8; 64];
415        assert!(decode::<bool>(round_trip(&true, &mut buf)).expect("bool"));
416        assert_eq!(
417            decode::<u16>(round_trip(&1234u16, &mut buf)).expect("u16"),
418            1234
419        );
420        assert_eq!(
421            decode::<i32>(round_trip(&-7i32, &mut buf)).expect("i32"),
422            -7
423        );
424        assert_eq!(
425            decode::<u64>(round_trip(&u64::MAX, &mut buf)).expect("u64"),
426            u64::MAX
427        );
428        let bytes = round_trip(&"hello", &mut buf);
429        assert_eq!(decode::<&str>(bytes).expect("str"), "hello");
430        let mut buf2 = [0u8; 64];
431        let bytes = round_trip(&&[1u8, 2, 3][..], &mut buf2);
432        assert_eq!(decode::<&[u8]>(bytes).expect("octets"), &[1, 2, 3]);
433    }
434
435    #[test]
436    fn a_value_too_wide_for_its_field_is_refused_rather_than_truncated() {
437        // §7.19.2 answers an out-of-range value `CONSTRAINT_ERROR`. Keeping the low octets
438        // would turn a rejected command into an accepted one with different arguments — a
439        // `MoveToLevel(300)` becoming `MoveToLevel(44)`.
440        let mut buf = [0u8; 32];
441        let wide = round_trip(&300u32, &mut buf);
442        assert_eq!(
443            decode::<u8>(wide).map_err(|e| e.code()),
444            Err(ErrorCode::TlvOutOfRange)
445        );
446        assert_eq!(decode::<u16>(wide).expect("fits"), 300);
447    }
448
449    #[test]
450    fn null_and_absent_are_different_things() {
451        // Three states, and a type that can only say two of them loses the one that matters:
452        // "the device implements this and has no value" versus "the device does not implement
453        // it" (§11.12.5.6's `OffPremiseServicesReachableIPv4` is exactly this).
454        let mut buf = [0u8; 32];
455        let bytes = round_trip(&Nullable::<u8>::null(), &mut buf);
456        let decoded: Nullable<u8> = decode(bytes).expect("null");
457        assert!(decoded.is_null());
458
459        let bytes = round_trip(&Nullable::some(9u8), &mut buf);
460        assert_eq!(
461            decode::<Nullable<u8>>(bytes).expect("value"),
462            Nullable::some(9)
463        );
464
465        // `Option<Nullable<T>>` is the full three-way answer; absence is the container's to
466        // report, which is why there is no `FromTlv for Option<T>`.
467        let present_and_null: Option<Nullable<u8>> = Some(Nullable::null());
468        assert!(present_and_null.is_some_and(|n| n.is_null()));
469    }
470
471    #[test]
472    fn a_list_is_read_where_it_lies() {
473        let mut buf = [0u8; 128];
474        let mut w = TlvWriter::new(&mut buf);
475        w.start_array(Tag::Anonymous).expect("array");
476        for value in 1..=5u16 {
477            w.unsigned(Tag::Anonymous, u64::from(value))
478                .expect("member");
479        }
480        w.end_container().expect("end");
481        let bytes = w.finish().expect("finish");
482
483        let list: TlvList<'_, u16> = decode(bytes).expect("list");
484        assert_eq!(list.count().expect("count"), 5);
485        let values: Result<heapless::Vec<u16, 8>> = list.iter().collect();
486        assert_eq!(values.expect("members").as_slice(), &[1, 2, 3, 4, 5]);
487
488        // An empty list is a list, and not the same as an absent one.
489        let mut buf = [0u8; 16];
490        let mut w = TlvWriter::new(&mut buf);
491        w.start_array(Tag::Anonymous).expect("array");
492        w.end_container().expect("end");
493        let bytes = w.finish().expect("finish");
494        let empty: TlvList<'_, u16> = decode(bytes).expect("list");
495        assert!(empty.is_empty());
496        assert_eq!(empty.count().expect("count"), 0);
497    }
498
499    #[test]
500    fn a_decoded_list_re_encodes_to_the_same_bytes() {
501        // What makes a list forwardable: a cluster that reads one and writes it back must
502        // produce what it was given, or a bridge changes the data it relays.
503        let mut buf = [0u8; 128];
504        let mut w = TlvWriter::new(&mut buf);
505        w.start_array(Tag::Anonymous).expect("array");
506        for value in [7u32, 70, 700, 7000] {
507            w.unsigned(Tag::Anonymous, u64::from(value))
508                .expect("member");
509        }
510        w.end_container().expect("end");
511        let original = w.finish().expect("finish").to_vec();
512
513        let list: TlvList<'_, u32> = decode(&original).expect("list");
514        let mut out = [0u8; 128];
515        let again = round_trip(&list, &mut out);
516        assert_eq!(again, original.as_slice());
517    }
518
519    #[test]
520    fn a_list_of_the_wrong_container_kind_is_refused() {
521        // A structure where an array belongs is not a list with different punctuation: its
522        // members carry tags, and reading them as anonymous entries would silently succeed
523        // for the first one and then drift.
524        let mut buf = [0u8; 64];
525        let mut w = TlvWriter::new(&mut buf);
526        w.start_structure(Tag::Anonymous).expect("structure");
527        w.unsigned(Tag::Context(0), 1).expect("member");
528        w.end_container().expect("end");
529        let bytes = w.finish().expect("finish");
530        assert_eq!(
531            decode::<TlvList<'_, u16>>(bytes).map_err(|e| e.code()),
532            Err(ErrorCode::TlvWrongType)
533        );
534    }
535
536    #[test]
537    fn a_member_that_does_not_decode_surfaces_at_that_member() {
538        // The trade a lazy list makes, stated: nothing has looked at member three yet, so its
539        // error arrives when something does rather than at decode time.
540        let mut buf = [0u8; 64];
541        let mut w = TlvWriter::new(&mut buf);
542        w.start_array(Tag::Anonymous).expect("array");
543        w.unsigned(Tag::Anonymous, 1).expect("member");
544        w.utf8(Tag::Anonymous, "not a number").expect("member");
545        w.end_container().expect("end");
546        let bytes = w.finish().expect("finish");
547
548        let list: TlvList<'_, u16> = decode(bytes).expect("the list itself is well formed");
549        let mut entries = list.iter();
550        assert_eq!(entries.next().expect("first").expect("a number"), 1);
551        assert!(entries.next().expect("second").is_err());
552    }
553}