Skip to main content

s2_kit/schema/
mod.rs

1//! The shape of S2 JSON, as data.
2//!
3//! [`TYPES`] is generated from the official schema files by
4//! `cargo xtask gen-schema-table`: every object type, its properties in schema order,
5//! which of them are required, and the bounds on every array. Two things use it.
6//!
7//! * **Lenient decoding.** A proxy or analyzer has to forward a message it would refuse
8//!   to send, so [`prune_unknown`] strips properties the schema does not define and
9//!   reports them, instead of failing the whole message.
10//! * **Cardinality rules.** `maxItems` is on more than forty arrays; transcribing those
11//!   numbers into the validator by hand would be forty chances to get one wrong.
12//!
13//! The full schema files are vendored under `schema/s2-json/` and used by the tests,
14//! which check the hand-written Rust types against them in both directions. They are not
15//! embedded in the library: a table of names and bounds is a few kilobytes, and the
16//! schemas are three hundred.
17
18mod table;
19
20use alloc::string::String;
21use alloc::vec::Vec;
22
23pub use table::TYPES;
24
25/// The `minItems` and `maxItems` an array property carries.
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub struct ArrayBounds {
28    /// The fewest elements the schema allows.
29    pub min: Option<u64>,
30    /// The most elements the schema allows.
31    pub max: Option<u64>,
32}
33
34impl ArrayBounds {
35    /// Whether `len` satisfies both bounds.
36    #[must_use]
37    pub const fn accepts(self, len: u64) -> bool {
38        let above = match self.min {
39            Some(m) => len >= m,
40            None => true,
41        };
42        let below = match self.max {
43            Some(m) => len <= m,
44            None => true,
45        };
46        above && below
47    }
48}
49
50/// What a property holds.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum Kind {
53    /// A number, string, boolean or enumeration.
54    Scalar,
55    /// Another object type, named here so a walk can recurse into it.
56    Object(&'static str),
57    /// An array of scalars.
58    ScalarArray(ArrayBounds),
59    /// An array of another object type.
60    ObjectArray(&'static str, ArrayBounds),
61}
62
63impl Kind {
64    /// The array bounds, if this property is an array.
65    #[must_use]
66    pub const fn bounds(self) -> Option<ArrayBounds> {
67        match self {
68            Kind::ScalarArray(b) | Kind::ObjectArray(_, b) => Some(b),
69            Kind::Scalar | Kind::Object(_) => None,
70        }
71    }
72}
73
74/// One property of an S2 object type.
75#[derive(Debug, Clone, Copy, PartialEq, Eq)]
76pub struct Property {
77    /// The name as it appears on the wire, misspellings included.
78    pub name: &'static str,
79    /// Whether the schema lists it in `required`.
80    pub required: bool,
81    /// What it holds.
82    pub kind: Kind,
83}
84
85/// One S2 object type.
86#[derive(Debug, Clone, Copy, PartialEq, Eq)]
87pub struct TypeSpec {
88    /// The schema file's name: `FRBC.Instruction`, `NumberRange`.
89    pub name: &'static str,
90    /// The `message_type` constant, for the 36 types that are messages.
91    pub message_type: Option<&'static str>,
92    /// Its properties, in schema order.
93    pub properties: &'static [Property],
94}
95
96impl TypeSpec {
97    /// The named property, if the type has one.
98    #[must_use]
99    pub fn property(&self, name: &str) -> Option<&'static Property> {
100        self.properties.iter().find(|p| p.name == name)
101    }
102}
103
104/// The specification for a type, by schema name.
105#[must_use]
106pub fn type_spec(name: &str) -> Option<&'static TypeSpec> {
107    TYPES
108        .binary_search_by(|t| t.name.cmp(name))
109        .ok()
110        .and_then(|i| TYPES.get(i))
111}
112
113/// The specification for a message, by its `message_type`.
114#[must_use]
115pub fn message_spec(message_type: &str) -> Option<&'static TypeSpec> {
116    TYPES.iter().find(|t| t.message_type == Some(message_type))
117}
118
119/// Every message type the vendored schemas define.
120pub fn message_types() -> impl Iterator<Item = &'static str> {
121    TYPES.iter().filter_map(|t| t.message_type)
122}
123
124/// How deep [`prune_unknown`] will walk.
125///
126/// The schema's own deepest path is
127/// `PPBC.PowerProfileDefinition → container → sequence → element → value`, five levels.
128/// Twice that is room for a schema that grows and a bound that does not depend on a value
129/// a peer chose: the walk is driven by the *schema*, but the value decides how many array
130/// elements each level has, and a recursion whose depth nothing states is a recursion
131/// nobody has checked.
132pub const MAX_PRUNE_DEPTH: usize = 16;
133
134/// Removes properties the schema does not define, recursively, reporting each.
135///
136/// This is what `Strictness::Lenient` does before decoding. It is deliberately *not* a
137/// validator: it removes what the types cannot represent and leaves everything else —
138/// including values that are out of range — for [`crate::validate`] to judge and report.
139///
140/// Returns the number of properties removed. Each is named in `removed` as a JSON
141/// pointer, so a proxy can tell its operator exactly what it dropped. Below
142/// [`MAX_PRUNE_DEPTH`] nothing is pruned and nothing is reported: the typed decode that
143/// follows refuses the message anyway, so the only thing a deeper walk buys is a deeper
144/// stack.
145pub fn prune_unknown(
146    value: &mut serde_json::Value,
147    type_name: &str,
148    removed: &mut Vec<String>,
149) -> usize {
150    prune_at(value, type_name, "", removed, MAX_PRUNE_DEPTH)
151}
152
153fn prune_at(
154    value: &mut serde_json::Value,
155    type_name: &str,
156    path: &str,
157    removed: &mut Vec<String>,
158    depth: usize,
159) -> usize {
160    let Some(depth) = depth.checked_sub(1) else {
161        return 0;
162    };
163    let Some(spec) = type_spec(type_name) else {
164        return 0;
165    };
166    let Some(object) = value.as_object_mut() else {
167        return 0;
168    };
169
170    let mut count = 0;
171    let unknown: Vec<String> = object
172        .keys()
173        .filter(|k| k.as_str() != "message_type" && spec.property(k).is_none())
174        .cloned()
175        .collect();
176    for key in unknown {
177        removed.push(alloc::format!("{path}/{key}"));
178        object.remove(&key);
179        count += 1;
180    }
181
182    for property in spec.properties {
183        let Some(child) = object.get_mut(property.name) else {
184            continue;
185        };
186        let child_path = alloc::format!("{path}/{}", property.name);
187        match property.kind {
188            Kind::Object(inner) => {
189                count += prune_at(child, inner, &child_path, removed, depth);
190            }
191            Kind::ObjectArray(inner, _) => {
192                if let Some(items) = child.as_array_mut() {
193                    for (i, item) in items.iter_mut().enumerate() {
194                        let item_path = alloc::format!("{child_path}/{i}");
195                        count += prune_at(item, inner, &item_path, removed, depth);
196                    }
197                }
198            }
199            Kind::Scalar | Kind::ScalarArray(_) => {}
200        }
201    }
202    count
203}
204
205#[cfg(test)]
206mod tests {
207    use super::*;
208    use crate::message::MessageKind;
209    use alloc::string::ToString;
210
211    #[test]
212    fn the_table_covers_every_message_the_crate_claims() {
213        // The generated table comes from the vendored schema directory; MessageKind is
214        // hand-written. If they disagree, one of them is wrong — which is the whole
215        // point of generating the table rather than trusting the enum.
216        let mut from_schema: Vec<&str> = message_types().collect();
217        from_schema.sort_unstable();
218        let mut from_rust: Vec<&str> = MessageKind::ALL.iter().map(|k| k.as_str()).collect();
219        from_rust.sort_unstable();
220        assert_eq!(from_schema, from_rust);
221    }
222
223    #[test]
224    fn types_are_sorted_so_lookup_can_binary_search() {
225        for pair in TYPES.windows(2) {
226            if let [a, b] = pair {
227                assert!(a.name < b.name, "{} should sort before {}", a.name, b.name);
228            }
229        }
230        assert!(type_spec("FRBC.Instruction").is_some());
231        assert!(type_spec("NumberRange").is_some());
232        assert!(type_spec("Nope").is_none());
233    }
234
235    #[test]
236    fn array_bounds_came_from_the_schema() {
237        let forecast = type_spec("PowerForecast").unwrap();
238        let elements = forecast.property("elements").unwrap();
239        assert_eq!(
240            elements.kind,
241            Kind::ObjectArray(
242                "PowerForecastElement",
243                ArrayBounds {
244                    min: Some(1),
245                    max: Some(288)
246                }
247            )
248        );
249        let details = type_spec("ResourceManagerDetails").unwrap();
250        assert_eq!(
251            details.property("roles").unwrap().kind.bounds(),
252            Some(ArrayBounds {
253                min: Some(1),
254                max: Some(3)
255            })
256        );
257        // And `PEBC.PowerConstraints` really does demand at least two limit ranges.
258        let constraints = type_spec("PEBC.PowerConstraints").unwrap();
259        assert_eq!(
260            constraints
261                .property("allowed_limit_ranges")
262                .unwrap()
263                .kind
264                .bounds()
265                .unwrap()
266                .min,
267            Some(2)
268        );
269    }
270
271    #[test]
272    fn required_flags_came_from_the_schema() {
273        let details = type_spec("ResourceManagerDetails").unwrap();
274        assert!(details.property("resource_id").unwrap().required);
275        assert!(!details.property("name").unwrap().required);
276        assert!(!details.property("currency").unwrap().required);
277    }
278
279    #[test]
280    fn pruning_removes_only_what_the_schema_does_not_define() {
281        let mut value: serde_json::Value = serde_json::from_str(
282            r#"{
283                "message_type": "FRBC.ActuatorStatus",
284                "message_id": "m1",
285                "actuator_id": "a1",
286                "active_operation_mode_id": "om1",
287                "operation_mode_factor": 0.5,
288                "vendor_extension": {"anything": 1}
289            }"#,
290        )
291        .unwrap();
292        let mut removed = Vec::new();
293        let n = prune_unknown(&mut value, "FRBC.ActuatorStatus", &mut removed);
294        assert_eq!(n, 1);
295        assert_eq!(removed, alloc::vec!["/vendor_extension".to_string()]);
296        assert!(value.get("vendor_extension").is_none());
297        assert!(value.get("operation_mode_factor").is_some());
298        assert!(value.get("message_type").is_some(), "the tag must survive");
299    }
300
301    #[test]
302    fn pruning_stops_at_a_depth_a_peer_did_not_choose() {
303        // The schema's deepest real path is five levels, so the cap never fires on a
304        // legitimate message — this asserts it exists rather than that it bites.
305        const { assert!(MAX_PRUNE_DEPTH > 8) };
306
307        // A nested value as deep as the schema allows is still pruned all the way down.
308        let mut value: serde_json::Value = serde_json::from_str(
309            r#"{
310                "message_type": "PPBC.PowerProfileDefinition",
311                "message_id": "m1", "id": "p1",
312                "start_time": "2024-01-01T00:00:00Z",
313                "end_time": "2024-01-02T00:00:00Z",
314                "power_sequences_containers": [
315                  {"id": "c1", "power_sequences": [
316                    {"id": "s1", "elements": [
317                      {"duration": 900000, "power_values": [
318                        {"value_expected": 1.0,
319                         "commodity_quantity": "ELECTRIC.POWER.L1",
320                         "surprise": 1}]}],
321                     "is_interruptible": false, "abnormal_condition_only": false}]}]
322            }"#,
323        )
324        .unwrap();
325        let mut removed = Vec::new();
326        assert_eq!(
327            prune_unknown(&mut value, "PPBC.PowerProfileDefinition", &mut removed),
328            1
329        );
330        assert_eq!(
331            removed,
332            alloc::vec![
333                "/power_sequences_containers/0/power_sequences/0/elements/0/power_values/0/surprise"
334                    .to_string()
335            ]
336        );
337    }
338
339    #[test]
340    fn pruning_reaches_into_nested_objects_and_arrays() {
341        let mut value: serde_json::Value = serde_json::from_str(
342            r#"{
343                "message_type": "FRBC.SystemDescription",
344                "message_id": "m1",
345                "valid_from": "2019-08-24T14:15:22Z",
346                "actuators": [
347                  {"id": "a1", "supported_commodities": ["ELECTRICITY"],
348                   "operation_modes": [
349                     {"id": "om1", "elements": [], "abnormal_condition_only": false,
350                      "surprise": 1}
351                   ],
352                   "transitions": [], "timers": [], "mystery": true}
353                ],
354                "storage": {"provides_leakage_behaviour": false,
355                            "provides_fill_level_target_profile": false,
356                            "provides_usage_forecast": false,
357                            "fill_level_range": {"start_of_range": 0, "end_of_range": 100,
358                                                 "hidden": 2}}
359            }"#,
360        )
361        .unwrap();
362        let mut removed = Vec::new();
363        let n = prune_unknown(&mut value, "FRBC.SystemDescription", &mut removed);
364        assert_eq!(n, 3, "{removed:?}");
365        removed.sort();
366        assert_eq!(
367            removed,
368            alloc::vec![
369                "/actuators/0/mystery".to_string(),
370                "/actuators/0/operation_modes/0/surprise".to_string(),
371                "/storage/fill_level_range/hidden".to_string(),
372            ]
373        );
374    }
375}