Skip to main content

matter_model/
json.rs

1//! JSON <-> Matter TLV.
2//!
3//! Decoding never needs a schema (TLV carries its types); with one, structure
4//! fields get their names. Encoding needs the schema for what JSON cannot say:
5//! whether a number is signed, whether a string is text or octets (hex in
6//! JSON), and which tag a named field has. Without one it falls back to the
7//! JSON type (non-negative integers unsigned, objects keyed by tag number).
8//!
9//! Both directions are bounded by [`MAX_DEPTH`] and allocate only for the
10//! output, so neither can be driven into unbounded recursion by a peer.
11
12use rs_matter_tlv::{TLVElement, TLVTag, TLVValue, TLVWrite};
13use rs_matter_utils::storage::WriteBuf;
14use serde_json::{Map, Number, Value};
15
16use crate::schema::{Field, Shape, StructDef, Type};
17
18/// The deepest nesting either direction accepts. Matter data is a handful of
19/// levels deep at most (a list of structures holding a list).
20pub const MAX_DEPTH: usize = 16;
21
22/// Why a conversion failed.
23#[derive(Debug, thiserror::Error, PartialEq, Eq)]
24pub enum ConvertError {
25    /// The TLV is malformed, or the writer ran out of room.
26    #[error("TLV: {0}")]
27    Tlv(String),
28    /// The value is nested deeper than [`MAX_DEPTH`].
29    #[error("nested deeper than {MAX_DEPTH} levels")]
30    TooDeep,
31    /// The JSON value does not fit the expected type.
32    #[error("{path}: expected {expected}, got {got}")]
33    Mismatch {
34        /// Where in the value, e.g. `.level` or `[2]`.
35        path: String,
36        /// What the schema wanted.
37        expected: &'static str,
38        /// What the JSON had.
39        got: String,
40    },
41    /// A structure field the schema does not have.
42    #[error("{path}: no field `{field}` in {structure}")]
43    UnknownField {
44        /// Where in the value.
45        path: String,
46        /// The field asked for.
47        field: String,
48        /// The structure's name.
49        structure: &'static str,
50    },
51    /// A required field is missing.
52    #[error("{path}: missing field `{field}`")]
53    MissingField {
54        /// Where in the value.
55        path: String,
56        /// The field left out.
57        field: &'static str,
58    },
59}
60
61fn tlv_err<E: core::fmt::Debug>(e: E) -> ConvertError {
62    ConvertError::Tlv(format!("{e:?}"))
63}
64
65/// Decode a TLV element to JSON, naming structure fields from `shape` where
66/// it has them.
67///
68/// Integers are JSON numbers (exact up to 64 bits), octet strings lowercase
69/// hex, structures objects keyed by field name (or tag number for a field the
70/// schema does not know), lists and arrays JSON arrays.
71pub fn to_json(el: &TLVElement<'_>, shape: Shape) -> Result<Value, ConvertError> {
72    decode(el, shape, 0)
73}
74
75fn decode(el: &TLVElement<'_>, shape: Shape, depth: usize) -> Result<Value, ConvertError> {
76    if depth > MAX_DEPTH {
77        return Err(ConvertError::TooDeep);
78    }
79
80    Ok(match el.value().map_err(tlv_err)? {
81        TLVValue::S8(v) => v.into(),
82        TLVValue::S16(v) => v.into(),
83        TLVValue::S32(v) => v.into(),
84        TLVValue::S64(v) => v.into(),
85        TLVValue::U8(v) => v.into(),
86        TLVValue::U16(v) => v.into(),
87        TLVValue::U32(v) => v.into(),
88        TLVValue::U64(v) => v.into(),
89        TLVValue::False => false.into(),
90        TLVValue::True => true.into(),
91        TLVValue::F32(v) => Number::from_f64(v.into()).map_or(Value::Null, Value::Number),
92        TLVValue::F64(v) => Number::from_f64(v).map_or(Value::Null, Value::Number),
93        TLVValue::Utf8l(s) | TLVValue::Utf16l(s) | TLVValue::Utf32l(s) | TLVValue::Utf64l(s) => {
94            s.into()
95        }
96        TLVValue::Str8l(b) | TLVValue::Str16l(b) | TLVValue::Str32l(b) | TLVValue::Str64l(b) => {
97            hex::encode(b).into()
98        }
99        TLVValue::Null => Value::Null,
100        TLVValue::Array | TLVValue::List if shape.list => {
101            let elem = Shape {
102                ty: shape.ty,
103                list: false,
104            };
105            let mut out = Vec::new();
106            for child in el.container().map_err(tlv_err)?.iter() {
107                out.push(decode(&child.map_err(tlv_err)?, elem, depth + 1)?);
108            }
109            Value::Array(out)
110        }
111        TLVValue::Struct => {
112            let def = match shape.ty {
113                Some(Type::Struct(def)) => Some(def),
114                _ => None,
115            };
116            decode_struct(el, def, depth)?
117        }
118        TLVValue::Array | TLVValue::List => {
119            let mut out = Vec::new();
120            for child in el.container().map_err(tlv_err)?.iter() {
121                out.push(decode(&child.map_err(tlv_err)?, Shape::ANY, depth + 1)?);
122            }
123            Value::Array(out)
124        }
125        TLVValue::EndCnt => return Err(ConvertError::Tlv("unexpected end of container".into())),
126    })
127}
128
129fn decode_struct(
130    el: &TLVElement<'_>,
131    def: Option<&'static StructDef>,
132    depth: usize,
133) -> Result<Value, ConvertError> {
134    let mut out = Map::new();
135    for child in el.container().map_err(tlv_err)?.iter() {
136        let child = child.map_err(tlv_err)?;
137        let (key, shape) = match child.tag().map_err(tlv_err)? {
138            TLVTag::Context(tag) => match def.and_then(|d| d.field(tag)) {
139                Some(field) => (field.name.to_string(), field.shape()),
140                None => (tag.to_string(), Shape::ANY),
141            },
142            other => (format!("{other:?}"), Shape::ANY),
143        };
144        out.insert(key, decode(&child, shape, depth + 1)?);
145    }
146    Ok(Value::Object(out))
147}
148
149/// Encode a JSON value as TLV under `tag`, as `shape` says it should be.
150///
151/// Enumeration values may be given by name; octet strings are hex; structure
152/// fields by name or by tag number. Integers are written in the smallest TLV
153/// width that holds them, which every Matter reader accepts.
154pub fn from_json<W: TLVWrite>(
155    w: &mut W,
156    tag: &TLVTag,
157    shape: Shape,
158    value: &Value,
159) -> Result<(), ConvertError> {
160    encode(w, tag, shape, value, &mut String::new(), 0)
161}
162
163/// Encode a JSON value as one anonymous TLV element, as [`from_json`] does,
164/// into a new buffer of at most `max_len` bytes.
165pub fn encode_to_vec(shape: Shape, value: &Value, max_len: usize) -> Result<Vec<u8>, ConvertError> {
166    let mut buf = vec![0u8; max_len];
167    let mut wb = WriteBuf::new(&mut buf);
168    from_json(&mut wb, &TLVTag::Anonymous, shape, value)?;
169    let len = wb.get_tail();
170    buf.truncate(len);
171    Ok(buf)
172}
173
174fn kind(v: &Value) -> String {
175    match v {
176        Value::Null => "null".into(),
177        Value::Bool(_) => "a boolean".into(),
178        Value::Number(n) => format!("the number {n}"),
179        Value::String(_) => "a string".into(),
180        Value::Array(_) => "an array".into(),
181        Value::Object(_) => "an object".into(),
182    }
183}
184
185fn mismatch(path: &str, expected: &'static str, got: &Value) -> ConvertError {
186    ConvertError::Mismatch {
187        path: if path.is_empty() {
188            ".".into()
189        } else {
190            path.into()
191        },
192        expected,
193        got: kind(got),
194    }
195}
196
197fn encode<W: TLVWrite>(
198    w: &mut W,
199    tag: &TLVTag,
200    shape: Shape,
201    value: &Value,
202    path: &mut String,
203    depth: usize,
204) -> Result<(), ConvertError> {
205    if depth > MAX_DEPTH {
206        return Err(ConvertError::TooDeep);
207    }
208
209    if value.is_null() {
210        return w.null(tag).map_err(tlv_err);
211    }
212
213    if shape.list {
214        let Value::Array(items) = value else {
215            return Err(mismatch(path, "a list", value));
216        };
217        w.start_array(tag).map_err(tlv_err)?;
218        let elem = Shape {
219            ty: shape.ty,
220            list: false,
221        };
222        for (i, item) in items.iter().enumerate() {
223            let len = path.len();
224            path.push_str(&format!("[{i}]"));
225            encode(w, &TLVTag::Anonymous, elem, item, path, depth + 1)?;
226            path.truncate(len);
227        }
228        return w.end_container().map_err(tlv_err);
229    }
230
231    match shape.ty {
232        Some(Type::Bool) => match value {
233            Value::Bool(b) => w.bool(tag, *b).map_err(tlv_err),
234            _ => Err(mismatch(path, "a boolean", value)),
235        },
236        Some(Type::Uint | Type::Bitmap(_)) => match value.as_u64() {
237            Some(v) => w.u64(tag, v).map_err(tlv_err),
238            None => Err(mismatch(path, "an unsigned integer", value)),
239        },
240        Some(Type::Enum(def)) => {
241            let v = match value {
242                Value::String(name) => def.value_of(name),
243                _ => value.as_u64(),
244            };
245            match v {
246                Some(v) => w.u64(tag, v).map_err(tlv_err),
247                None => Err(mismatch(path, "an enumeration value or name", value)),
248            }
249        }
250        Some(Type::Int) => match value.as_i64() {
251            Some(v) => w.i64(tag, v).map_err(tlv_err),
252            None => Err(mismatch(path, "an integer", value)),
253        },
254        Some(Type::Float) => match value.as_f64() {
255            Some(v) => w.f32(tag, v as f32).map_err(tlv_err),
256            None => Err(mismatch(path, "a number", value)),
257        },
258        Some(Type::Double) => match value.as_f64() {
259            Some(v) => w.f64(tag, v).map_err(tlv_err),
260            None => Err(mismatch(path, "a number", value)),
261        },
262        Some(Type::String) => match value {
263            Value::String(s) => w.utf8(tag, s).map_err(tlv_err),
264            _ => Err(mismatch(path, "a string", value)),
265        },
266        Some(Type::Octets) => match value.as_str().map(hex::decode) {
267            Some(Ok(bytes)) => w.str(tag, &bytes).map_err(tlv_err),
268            _ => Err(mismatch(path, "a hex string", value)),
269        },
270        Some(Type::Struct(def)) => match value {
271            Value::Object(map) => encode_struct(w, tag, Some(def), map, path, depth),
272            _ => Err(mismatch(path, "an object", value)),
273        },
274        Some(Type::Unknown(_)) | None => encode_untyped(w, tag, value, path, depth),
275    }
276}
277
278fn encode_struct<W: TLVWrite>(
279    w: &mut W,
280    tag: &TLVTag,
281    def: Option<&'static StructDef>,
282    map: &Map<String, Value>,
283    path: &mut String,
284    depth: usize,
285) -> Result<(), ConvertError> {
286    // Resolve every key first, so fields go out in tag order and an unknown
287    // name is reported before anything is written.
288    let mut fields: Vec<(u8, Option<&'static Field>, &Value)> = Vec::with_capacity(map.len());
289    for (key, value) in map {
290        let field = def.and_then(|d| d.field_by_name(key));
291        let tag = match (field, key.parse::<u8>()) {
292            (Some(f), _) => f.tag,
293            (None, Ok(n)) => n,
294            (None, Err(_)) => {
295                return Err(ConvertError::UnknownField {
296                    path: if path.is_empty() {
297                        ".".into()
298                    } else {
299                        path.clone()
300                    },
301                    field: key.clone(),
302                    structure: def.map_or("a structure without a schema", |d| d.name),
303                })
304            }
305        };
306        let field = field.or_else(|| def.and_then(|d| d.field(tag)));
307        fields.push((tag, field, value));
308    }
309
310    // A required field left out is an error, unless it can be null: then it
311    // goes out as null, which is what leaving it out means to a person.
312    static NULL: Value = Value::Null;
313    if let Some(def) = def {
314        for f in def.fields.iter().filter(|f| !f.optional) {
315            if !fields.iter().any(|(tag, _, _)| *tag == f.tag) {
316                if !f.nullable {
317                    return Err(ConvertError::MissingField {
318                        path: if path.is_empty() {
319                            ".".into()
320                        } else {
321                            path.clone()
322                        },
323                        field: f.name,
324                    });
325                }
326                fields.push((f.tag, Some(f), &NULL));
327            }
328        }
329    }
330
331    fields.sort_by_key(|(tag, _, _)| *tag);
332
333    w.start_struct(tag).map_err(tlv_err)?;
334    for (field_tag, field, value) in fields {
335        let len = path.len();
336        match field {
337            Some(f) => path.push_str(&format!(".{}", f.name)),
338            None => path.push_str(&format!(".{field_tag}")),
339        }
340        let shape = field.map_or(Shape::ANY, Field::shape);
341        encode(
342            w,
343            &TLVTag::Context(field_tag),
344            shape,
345            value,
346            path,
347            depth + 1,
348        )?;
349        path.truncate(len);
350    }
351    w.end_container().map_err(tlv_err)
352}
353
354fn encode_untyped<W: TLVWrite>(
355    w: &mut W,
356    tag: &TLVTag,
357    value: &Value,
358    path: &mut String,
359    depth: usize,
360) -> Result<(), ConvertError> {
361    match value {
362        Value::Null => w.null(tag).map_err(tlv_err),
363        Value::Bool(b) => w.bool(tag, *b).map_err(tlv_err),
364        Value::Number(n) => {
365            if let Some(v) = n.as_u64() {
366                w.u64(tag, v).map_err(tlv_err)
367            } else if let Some(v) = n.as_i64() {
368                w.i64(tag, v).map_err(tlv_err)
369            } else {
370                w.f64(tag, n.as_f64().unwrap_or_default()).map_err(tlv_err)
371            }
372        }
373        Value::String(s) => w.utf8(tag, s).map_err(tlv_err),
374        Value::Array(items) => {
375            w.start_array(tag).map_err(tlv_err)?;
376            for (i, item) in items.iter().enumerate() {
377                let len = path.len();
378                path.push_str(&format!("[{i}]"));
379                encode(w, &TLVTag::Anonymous, Shape::ANY, item, path, depth + 1)?;
380                path.truncate(len);
381            }
382            w.end_container().map_err(tlv_err)
383        }
384        Value::Object(map) => encode_struct(w, tag, None, map, path, depth),
385    }
386}
387
388#[cfg(test)]
389mod tests {
390    use super::*;
391    use serde_json::json;
392
393    fn roundtrip(shape: Shape, v: Value) -> Value {
394        let bytes = encode_to_vec(shape, &v, 1024).unwrap();
395        to_json(&TLVElement::new(&bytes), shape).unwrap()
396    }
397
398    #[test]
399    fn primitives() {
400        assert_eq!(roundtrip(Shape::of(Type::Uint), json!(300)), json!(300));
401        assert_eq!(roundtrip(Shape::of(Type::Int), json!(-5)), json!(-5));
402        assert_eq!(roundtrip(Shape::of(Type::Bool), json!(true)), json!(true));
403        assert_eq!(roundtrip(Shape::of(Type::String), json!("hé")), json!("hé"));
404        assert_eq!(
405            roundtrip(Shape::of(Type::Octets), json!("00ff10")),
406            json!("00ff10")
407        );
408        assert_eq!(roundtrip(Shape::of(Type::Double), json!(1.5)), json!(1.5));
409        assert_eq!(
410            roundtrip(Shape::of(Type::Uint), json!(u64::MAX)),
411            json!(u64::MAX)
412        );
413        assert_eq!(roundtrip(Shape::of(Type::Uint), Value::Null), Value::Null);
414    }
415
416    #[test]
417    fn structures_by_name() {
418        let level = crate::cluster_by_name("LevelControl").unwrap();
419        let req = level
420            .command_by_name("MoveToLevel")
421            .unwrap()
422            .request
423            .unwrap();
424        let v = json!({"level": 128, "options_mask": 0, "OptionsOverride": 0});
425        let out = roundtrip(req.shape(), v);
426        assert_eq!(
427            out,
428            json!({"level": 128, "transitionTime": null, "optionsMask": 0, "optionsOverride": 0})
429        );
430    }
431
432    #[test]
433    fn errors_name_the_place() {
434        let level = crate::cluster_by_name("LevelControl").unwrap();
435        let req = level
436            .command_by_name("MoveToLevel")
437            .unwrap()
438            .request
439            .unwrap();
440        let mut buf = [0u8; 256];
441        let mut wb = WriteBuf::new(&mut buf);
442        let err = from_json(
443            &mut wb,
444            &TLVTag::Anonymous,
445            req.shape(),
446            &json!({"level": "high", "optionsMask": 0, "optionsOverride": 0, "transitionTime": 0}),
447        )
448        .unwrap_err();
449        assert!(
450            matches!(err, ConvertError::Mismatch { ref path, .. } if path == ".level"),
451            "{err}"
452        );
453        let err = from_json(
454            &mut wb,
455            &TLVTag::Anonymous,
456            req.shape(),
457            &json!({"bogus": 1}),
458        )
459        .unwrap_err();
460        assert!(matches!(err, ConvertError::UnknownField { .. }), "{err}");
461        let err = from_json(&mut wb, &TLVTag::Anonymous, req.shape(), &json!({})).unwrap_err();
462        assert!(
463            matches!(err, ConvertError::MissingField { field: "level", .. }),
464            "{err}"
465        );
466    }
467
468    #[test]
469    fn enums_by_name() {
470        let ocw = crate::cluster_by_name("AdministratorCommissioning").unwrap();
471        let attr = ocw.attribute_by_name("WindowStatus").unwrap();
472        let Type::Enum(def) = attr.ty else {
473            panic!("not an enum")
474        };
475        let mut buf = [0u8; 16];
476        let mut wb = WriteBuf::new(&mut buf);
477        let name = def.name_of(1).unwrap();
478        from_json(&mut wb, &TLVTag::Anonymous, attr.shape(), &json!(name)).unwrap();
479        let len = wb.get_tail();
480        assert_eq!(
481            to_json(&TLVElement::new(&buf[..len]), attr.shape()).unwrap(),
482            json!(1)
483        );
484    }
485
486    #[test]
487    fn lists_of_structures_decode_with_names() {
488        let descriptor = crate::cluster(0x001D).unwrap();
489        let dtl = descriptor.attribute_by_name("DeviceTypeList").unwrap();
490        let out = roundtrip(dtl.shape(), json!([{"deviceType": 256, "revision": 3}]));
491        assert_eq!(out, json!([{"deviceType": 256, "revision": 3}]));
492    }
493
494    #[test]
495    fn untyped_and_too_deep() {
496        assert_eq!(
497            roundtrip(Shape::ANY, json!({"1": [1, -2, "x", true], "0": null})),
498            json!({"0": null, "1": [1, -2, "x", true]})
499        );
500        let mut deep = json!(1);
501        for _ in 0..(MAX_DEPTH + 2) {
502            deep = json!([deep]);
503        }
504        let mut buf = [0u8; 256];
505        let mut wb = WriteBuf::new(&mut buf);
506        assert_eq!(
507            from_json(&mut wb, &TLVTag::Anonymous, Shape::ANY, &deep),
508            Err(ConvertError::TooDeep)
509        );
510    }
511
512    #[test]
513    fn malformed_tlv_is_an_error() {
514        for bytes in [
515            &[0x15u8][..],
516            &[0x0c, 0x05, b'a'],
517            &[0xff],
518            &[0x36, 0x15, 0x15],
519        ] {
520            let _ = to_json(&TLVElement::new(bytes), Shape::ANY);
521        }
522    }
523}