Skip to main content

jev_client/validate/
document.rs

1//! A request as it was written: the JSON value, plus the duplicate keys a plain parse would hide.
2
3use std::fmt;
4
5use serde::de::{DeserializeSeed, Deserializer, MapAccess, SeqAccess, Visitor};
6use serde::{Deserialize, Serialize};
7use serde_json::{Map, Number, Value};
8
9use crate::request::Request;
10
11/// A request document, parsed for validation rather than for sending.
12///
13/// Validation works on the raw document, not on a typed [`Request`], for two reasons. A typed parse
14/// stops at the first problem and reports it without saying which question it is in; and any
15/// ordinary parse silently keeps the last of two identical keys, so a repeated question id could
16/// never be reported. A `Document` keeps the whole value whatever its shape, and remembers every
17/// duplicate key it saw.
18///
19/// It implements [`Deserialize`] and does its work in a single pass, asking only that the format
20/// be self-describing. [`Document::from_json_str`] covers JSON; a caller reading another such
21/// format, YAML for instance, deserialises a `Document` with that format's own deserializer.
22///
23/// ```
24/// use jev_client::validate::Document;
25///
26/// let document = Document::from_json_str(r#"{"state": "s", "state": "again"}"#).unwrap();
27/// assert_eq!(document.value()["state"], "again");
28/// assert_eq!(document.duplicate_keys().len(), 1);
29/// ```
30#[derive(Clone, Debug, PartialEq)]
31pub struct Document {
32    value: Value,
33    duplicates: Vec<DuplicateKey>,
34}
35
36/// A key that appeared more than once in one object. Only its last value survives.
37#[derive(Clone, Debug, PartialEq, Eq)]
38pub struct DuplicateKey {
39    /// JSON Pointer to the object holding the key (`""` for the root).
40    pub object: String,
41    /// The repeated key.
42    pub key: String,
43}
44
45impl Document {
46    /// Parses JSON text.
47    ///
48    /// # Errors
49    ///
50    /// Fails only when the text is not JSON at all. A well-formed document of the wrong shape
51    /// parses, and validation then explains what is wrong with it.
52    pub fn from_json_str(text: &str) -> Result<Self, serde_json::Error> {
53        let mut deserializer = serde_json::Deserializer::from_str(text);
54        let document = Self::deserialize(&mut deserializer)?;
55        deserializer.end()?;
56        Ok(document)
57    }
58
59    /// Wraps a value that has already been parsed. Duplicate keys, if there were any, are already
60    /// lost and cannot be reported.
61    #[must_use]
62    pub const fn from_value(value: Value) -> Self {
63        Self {
64            value,
65            duplicates: Vec::new(),
66        }
67    }
68
69    /// The document as a JSON value.
70    #[must_use]
71    pub const fn value(&self) -> &Value {
72        &self.value
73    }
74
75    /// Mutable access to the value, for a caller that fills in defaults (such as the model) before
76    /// validating.
77    pub const fn value_mut(&mut self) -> &mut Value {
78        &mut self.value
79    }
80
81    /// Every key that was repeated within one object, in document order.
82    #[must_use]
83    pub fn duplicate_keys(&self) -> &[DuplicateKey] {
84        &self.duplicates
85    }
86
87    /// Converts the document into a typed request, once validation has passed.
88    ///
89    /// # Errors
90    ///
91    /// Fails when the document does not have the shape of a request, which validation reports in
92    /// more useful terms.
93    pub fn into_request(self) -> Result<Request, serde_json::Error> {
94        serde_json::from_value(self.value)
95    }
96}
97
98impl From<&Request> for Document {
99    /// A typed request cannot hold duplicate keys, so the document has none. A request that
100    /// somehow fails to serialise becomes `null`, which validation rejects.
101    fn from(request: &Request) -> Self {
102        Self::from_value(serde_json::to_value(request).unwrap_or(Value::Null))
103    }
104}
105
106impl Serialize for Document {
107    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
108        self.value.serialize(serializer)
109    }
110}
111
112impl<'de> Deserialize<'de> for Document {
113    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
114        let mut tracker = Tracker::default();
115        let value = Node(&mut tracker).deserialize(deserializer)?;
116        Ok(Self {
117            value,
118            duplicates: tracker.duplicates,
119        })
120    }
121}
122
123/// Appends `token` to a JSON Pointer, escaping it as RFC 6901 requires.
124pub(crate) fn push_pointer(pointer: &mut String, token: &str) {
125    pointer.push('/');
126    for character in token.chars() {
127        match character {
128            '~' => pointer.push_str("~0"),
129            '/' => pointer.push_str("~1"),
130            other => pointer.push(other),
131        }
132    }
133}
134
135/// `base` extended by one token.
136pub(crate) fn child_pointer(base: &str, token: &str) -> String {
137    let mut pointer = base.to_owned();
138    push_pointer(&mut pointer, token);
139    pointer
140}
141
142#[derive(Default)]
143struct Tracker {
144    path: Vec<String>,
145    duplicates: Vec<DuplicateKey>,
146}
147
148impl Tracker {
149    fn pointer(&self) -> String {
150        let mut pointer = String::new();
151        for token in &self.path {
152            push_pointer(&mut pointer, token);
153        }
154        pointer
155    }
156}
157
158/// Builds a [`Value`] for one node of the document, recording duplicate keys on the way.
159struct Node<'a>(&'a mut Tracker);
160
161impl<'de> DeserializeSeed<'de> for Node<'_> {
162    type Value = Value;
163
164    fn deserialize<D: Deserializer<'de>>(self, deserializer: D) -> Result<Value, D::Error> {
165        deserializer.deserialize_any(self)
166    }
167}
168
169impl<'de> Visitor<'de> for Node<'_> {
170    type Value = Value;
171
172    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
173        formatter.write_str("any JSON value")
174    }
175
176    fn visit_bool<E>(self, value: bool) -> Result<Value, E> {
177        Ok(Value::Bool(value))
178    }
179
180    fn visit_i64<E>(self, value: i64) -> Result<Value, E> {
181        Ok(Value::Number(value.into()))
182    }
183
184    fn visit_u64<E>(self, value: u64) -> Result<Value, E> {
185        Ok(Value::Number(value.into()))
186    }
187
188    fn visit_f64<E>(self, value: f64) -> Result<Value, E> {
189        Ok(Number::from_f64(value).map_or(Value::Null, Value::Number))
190    }
191
192    fn visit_str<E>(self, value: &str) -> Result<Value, E> {
193        Ok(Value::String(value.to_owned()))
194    }
195
196    fn visit_string<E>(self, value: String) -> Result<Value, E> {
197        Ok(Value::String(value))
198    }
199
200    fn visit_unit<E>(self) -> Result<Value, E> {
201        Ok(Value::Null)
202    }
203
204    fn visit_none<E>(self) -> Result<Value, E> {
205        Ok(Value::Null)
206    }
207
208    fn visit_some<D: Deserializer<'de>>(self, deserializer: D) -> Result<Value, D::Error> {
209        deserializer.deserialize_any(self)
210    }
211
212    fn visit_seq<A: SeqAccess<'de>>(self, mut access: A) -> Result<Value, A::Error> {
213        let mut items = Vec::new();
214        loop {
215            self.0.path.push(items.len().to_string());
216            let item = access.next_element_seed(Node(&mut *self.0));
217            self.0.path.pop();
218            match item? {
219                Some(item) => items.push(item),
220                None => return Ok(Value::Array(items)),
221            }
222        }
223    }
224
225    fn visit_map<A: MapAccess<'de>>(self, mut access: A) -> Result<Value, A::Error> {
226        let mut map = Map::new();
227        while let Some(key) = access.next_key::<Key>()? {
228            let Key(key) = key;
229            if map.contains_key(&key) {
230                let object = self.0.pointer();
231                self.0.duplicates.push(DuplicateKey {
232                    object,
233                    key: key.clone(),
234                });
235            }
236            self.0.path.push(key.clone());
237            let value = access.next_value_seed(Node(&mut *self.0));
238            self.0.path.pop();
239            // Like `serde_json`, the last value wins, so the document matches what would be sent.
240            map.insert(key, value?);
241        }
242        Ok(Value::Object(map))
243    }
244}
245
246/// A map key. JSON keys are strings; YAML allows scalars, which are read as their text.
247struct Key(String);
248
249impl<'de> Deserialize<'de> for Key {
250    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
251        struct KeyVisitor;
252
253        impl Visitor<'_> for KeyVisitor {
254            type Value = Key;
255
256            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
257                formatter.write_str("a string, number or boolean key")
258            }
259
260            fn visit_str<E>(self, value: &str) -> Result<Key, E> {
261                Ok(Key(value.to_owned()))
262            }
263
264            fn visit_bool<E>(self, value: bool) -> Result<Key, E> {
265                Ok(Key(value.to_string()))
266            }
267
268            fn visit_i64<E>(self, value: i64) -> Result<Key, E> {
269                Ok(Key(value.to_string()))
270            }
271
272            fn visit_u64<E>(self, value: u64) -> Result<Key, E> {
273                Ok(Key(value.to_string()))
274            }
275
276            fn visit_f64<E: serde::de::Error>(self, value: f64) -> Result<Key, E> {
277                Err(E::custom(format_args!(
278                    "a floating-point key ({value}) is not supported"
279                )))
280            }
281        }
282
283        deserializer.deserialize_any(KeyVisitor)
284    }
285}
286
287#[cfg(test)]
288mod tests {
289    use serde_json::json;
290
291    use super::{Document, DuplicateKey, child_pointer};
292    use crate::{Noul, Request};
293
294    #[test]
295    fn keeps_the_whole_value_in_document_order() {
296        let text = r#"{"z": 1, "a": [true, null, 2.5, "s"], "m": {"k": -3}}"#;
297
298        let document = Document::from_json_str(text).unwrap();
299
300        assert_eq!(
301            document.value(),
302            &json!({ "z": 1, "a": [true, null, 2.5, "s"], "m": { "k": -3 } })
303        );
304        assert_eq!(
305            serde_json::to_string(&document).unwrap(),
306            r#"{"z":1,"a":[true,null,2.5,"s"],"m":{"k":-3}}"#
307        );
308        assert!(document.duplicate_keys().is_empty());
309    }
310
311    #[test]
312    fn records_every_duplicate_key_with_the_pointer_of_its_object() {
313        let text = r#"{
314            "questions": {
315                "q": {"type": "noul"},
316                "a/b": {"criteria": {"x": 1, "x": 2, "x": 3}},
317                "q": {"type": "choice"}
318            },
319            "state": [{"k": 1, "k": 2}]
320        }"#;
321
322        let document = Document::from_json_str(text).unwrap();
323
324        let duplicate = |object: &str, key: &str| DuplicateKey {
325            object: object.into(),
326            key: key.into(),
327        };
328        assert_eq!(
329            document.duplicate_keys(),
330            [
331                duplicate("/questions/a~1b/criteria", "x"),
332                duplicate("/questions/a~1b/criteria", "x"),
333                duplicate("/questions", "q"),
334                duplicate("/state/0", "k"),
335            ]
336        );
337        assert_eq!(
338            document.value()["questions"]["q"]["type"],
339            "choice",
340            "the last value wins"
341        );
342    }
343
344    #[test]
345    fn only_text_that_is_not_json_fails_to_parse() {
346        assert!(Document::from_json_str("").is_err());
347        assert!(Document::from_json_str("{").is_err());
348        assert!(Document::from_json_str("{} trailing").is_err());
349
350        for wrong_shape in ["[]", "null", "42", r#""text""#, r#"{"questions": 7}"#] {
351            assert!(
352                Document::from_json_str(wrong_shape).is_ok(),
353                "{wrong_shape}"
354            );
355        }
356    }
357
358    #[test]
359    fn a_typed_request_round_trips_through_a_document() {
360        let request = Request::new("s", "jev-latest").question("q", Noul::new("?"));
361
362        let document = Document::from(&request);
363
364        assert!(document.duplicate_keys().is_empty());
365        assert_eq!(document.clone().into_request().unwrap(), request);
366        assert!(
367            Document::from_value(json!({ "state": "s" }))
368                .into_request()
369                .is_err()
370        );
371    }
372
373    #[test]
374    fn the_value_can_be_completed_before_validation() {
375        let mut document = Document::from_json_str(r#"{"state": "s", "questions": {}}"#).unwrap();
376
377        document.value_mut()["model"] = json!("jev-latest");
378
379        assert_eq!(document.value()["model"], "jev-latest");
380    }
381
382    #[test]
383    fn deserialises_from_any_self_describing_source_not_only_json_text() {
384        use serde::Deserialize;
385
386        let source = json!({ "state": { "n": 1.5, "flag": true }, "questions": {} });
387
388        let document = Document::deserialize(source.clone()).unwrap();
389
390        assert_eq!(document.value(), &source);
391    }
392
393    #[test]
394    fn pointers_escape_slashes_and_tildes() {
395        assert_eq!(child_pointer("", "a"), "/a");
396        assert_eq!(child_pointer("/questions", "a/b~c"), "/questions/a~1b~0c");
397    }
398}