Skip to main content

uqa_core/
json.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Borrowed JSON events share one grammar without choosing a numeric or object representation.
8
9use crate::{
10    memory::{Budgeted, BudgetedSmallVec, MemoryBudget, MemoryError, ProductionControl},
11    CancellationToken, QueryCancelled,
12};
13
14mod lexical;
15mod string;
16
17pub use string::{decode_json_string, decode_json_string_with_control};
18
19#[derive(Debug, thiserror::Error)]
20pub enum JsonReadError {
21    #[error("invalid JSON text")]
22    InvalidJson,
23    #[error(transparent)]
24    Memory(#[from] MemoryError),
25    #[error(transparent)]
26    Cancelled(#[from] QueryCancelled),
27    /// Valid JSON whose recognized tagged value carrier violates its format.
28    #[error("malformed {kind} value: {reason}")]
29    Malformed { kind: &'static str, reason: String },
30}
31
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub enum JsonToken<'a> {
34    Null,
35    Bool(bool),
36    Number(&'a str),
37    /// The validated token includes its quotes and escapes.
38    String(&'a [u8]),
39    Key(&'a [u8]),
40    StartArray,
41    EndArray,
42    StartObject,
43    EndObject,
44}
45
46#[derive(Debug, PartialEq, Eq)]
47pub struct JsonEvent<'a> {
48    pub token: JsonToken<'a>,
49    /// Byte offsets in the original text, including quotes or a container delimiter.
50    pub range: std::ops::Range<usize>,
51}
52
53/// The structural token expected when a reader rejects malformed input. Consumers choose their own diagnostic wording.
54#[derive(Clone, Copy, Debug, PartialEq, Eq)]
55pub enum JsonExpected {
56    Value,
57    End,
58    ArrayValueOrEnd,
59    ArraySeparator,
60    ObjectKeyOrEnd,
61    ObjectSeparator,
62    Key,
63    Colon,
64}
65
66#[derive(Clone, Copy)]
67enum Frame {
68    ArrayFirst,
69    ArrayValue,
70    ArrayAfter,
71    ObjectFirst,
72    ObjectKey,
73    ObjectValue,
74    ObjectAfter,
75}
76
77/// Open containers. A bounded stack keeps ordinary nesting inline and charges only deeper nesting.
78enum Stack {
79    Unbounded(Vec<Frame>),
80    Bounded(BudgetedSmallVec<[Frame; 16]>),
81}
82
83impl Stack {
84    fn frames(&mut self) -> &mut [Frame] {
85        match self {
86            Self::Unbounded(values) => values,
87            Self::Bounded(values) => values,
88        }
89    }
90
91    fn push(&mut self, frame: Frame) -> Result<(), JsonReadError> {
92        match self {
93            Self::Unbounded(values) => values.push(frame),
94            Self::Bounded(values) => values.push(frame)?,
95        }
96        Ok(())
97    }
98
99    fn pop(&mut self) {
100        match self {
101            Self::Unbounded(values) => {
102                values.pop();
103            }
104            Self::Bounded(values) => {
105                values.pop();
106            }
107        }
108    }
109}
110
111/// Iterative structural decoding charges its nesting stack before allocation. Event payloads borrow the input; consumers own and charge their chosen value representation separately.
112pub struct JsonReader<'a, 'c> {
113    input: &'a [u8],
114    position: usize,
115    stack: Stack,
116    cancellation: Option<&'c CancellationToken>,
117    production: Option<ProductionControl<'c>>,
118    root_started: bool,
119    expected: JsonExpected,
120    depth_limit: Option<usize>,
121    ignored_string_escapes: bool,
122    /// The input came from a `str`, so every token between ASCII delimiters is already valid UTF-8.
123    validated_utf8: bool,
124}
125
126impl<'a, 'c> JsonReader<'a, 'c> {
127    pub fn new(input: &'a str, memory: &MemoryBudget, cancellation: &'c CancellationToken) -> Self {
128        Self {
129            validated_utf8: true,
130            ..Self::from_slice(input.as_bytes(), memory, cancellation)
131        }
132    }
133
134    pub fn from_slice(
135        input: &'a [u8],
136        memory: &MemoryBudget,
137        cancellation: &'c CancellationToken,
138    ) -> Self {
139        Self {
140            input,
141            position: 0,
142            stack: Stack::Bounded(BudgetedSmallVec::new(memory)),
143            cancellation: Some(cancellation),
144            production: None,
145            root_started: false,
146            expected: JsonExpected::Value,
147            depth_limit: None,
148            ignored_string_escapes: false,
149            validated_utf8: false,
150        }
151    }
152
153    pub(crate) fn unbounded(input: &'a str) -> Self {
154        Self {
155            input: input.as_bytes(),
156            position: 0,
157            stack: Stack::Unbounded(Vec::new()),
158            cancellation: None,
159            production: None,
160            root_started: false,
161            expected: JsonExpected::Value,
162            depth_limit: None,
163            ignored_string_escapes: false,
164            validated_utf8: true,
165        }
166    }
167
168    /// Read the same borrowed grammar under an ordinary or controlled producer, preserving every active cancellation owner within token scans as well as between events.
169    pub fn with_control(input: &'a str, control: &ProductionControl<'c>) -> Self {
170        Self {
171            input: input.as_bytes(),
172            position: 0,
173            stack: control.budget().map_or_else(
174                || Stack::Unbounded(Vec::new()),
175                |budget| Stack::Bounded(BudgetedSmallVec::new(budget)),
176            ),
177            cancellation: None,
178            production: Some(*control),
179            root_started: false,
180            expected: JsonExpected::Value,
181            depth_limit: None,
182            ignored_string_escapes: false,
183            validated_utf8: true,
184        }
185    }
186
187    /// Limit open containers for formats whose previous decoder imposed a nesting limit.
188    #[must_use]
189    pub fn with_depth_limit(mut self, limit: usize) -> Self {
190        self.depth_limit = Some(limit);
191        self
192    }
193
194    /// Match serde's ignored-value byte validation when locating fields in a durable envelope: require four hexadecimal digits after each Unicode escape, without decoding UTF-8 or requiring surrogate pairs in discarded strings. Consumers must decode retained keys and string values with their ordinary strict decoder.
195    #[must_use]
196    pub fn with_ignored_string_escapes(mut self) -> Self {
197        self.ignored_string_escapes = true;
198        self
199    }
200
201    /// Borrow the failure position and expected structural token after `next_event` returns `InvalidJson`. No additional traversal or allocation is required.
202    pub const fn syntax_position(&self) -> (usize, JsonExpected) {
203        (self.position, self.expected)
204    }
205
206    pub fn next_event(&mut self) -> Result<Option<JsonEvent<'a>>, JsonReadError> {
207        self.check()?;
208        self.skip_whitespace()?;
209        let frame = self.stack.frames().last().copied();
210        self.expected = match frame {
211            None if self.root_started => JsonExpected::End,
212            None | Some(Frame::ArrayValue) => JsonExpected::Value,
213            Some(Frame::ArrayFirst) => JsonExpected::ArrayValueOrEnd,
214            Some(Frame::ArrayAfter) => JsonExpected::ArraySeparator,
215            Some(Frame::ObjectFirst) => JsonExpected::ObjectKeyOrEnd,
216            Some(Frame::ObjectKey) => JsonExpected::Key,
217            Some(Frame::ObjectValue) => JsonExpected::Colon,
218            Some(Frame::ObjectAfter) => JsonExpected::ObjectSeparator,
219        };
220        match frame {
221            None if self.root_started => {
222                return if self.position == self.input.len() {
223                    Ok(None)
224                } else {
225                    Err(JsonReadError::InvalidJson)
226                };
227            }
228            None => self.root_started = true,
229            Some(Frame::ArrayFirst) if self.peek() == Some(b']') => {
230                return self.close(JsonToken::EndArray)
231            }
232            Some(Frame::ObjectFirst) if self.peek() == Some(b'}') => {
233                return self.close(JsonToken::EndObject)
234            }
235            Some(Frame::ArrayAfter) => match self.peek() {
236                Some(b']') => return self.close(JsonToken::EndArray),
237                Some(b',') => {
238                    self.advance()?;
239                    self.skip_whitespace()?;
240                    self.replace(Frame::ArrayValue);
241                    self.expected = JsonExpected::Value;
242                }
243                _ => return Err(JsonReadError::InvalidJson),
244            },
245            Some(Frame::ObjectAfter) => match self.peek() {
246                Some(b'}') => return self.close(JsonToken::EndObject),
247                Some(b',') => {
248                    self.advance()?;
249                    self.skip_whitespace()?;
250                    self.replace(Frame::ObjectKey);
251                    self.expected = JsonExpected::Key;
252                }
253                _ => return Err(JsonReadError::InvalidJson),
254            },
255            _ => {}
256        }
257        match self.stack.frames().last().copied() {
258            Some(Frame::ObjectFirst | Frame::ObjectKey) => {
259                let start = self.position;
260                let key = self.string()?;
261                self.replace(Frame::ObjectValue);
262                return Ok(Some(self.event(start, JsonToken::Key(key))));
263            }
264            Some(Frame::ObjectValue) => {
265                self.consume(b':')?;
266                self.skip_whitespace()?;
267                self.replace(Frame::ObjectAfter);
268                self.expected = JsonExpected::Value;
269            }
270            Some(Frame::ArrayFirst | Frame::ArrayValue) => self.replace(Frame::ArrayAfter),
271            _ => {}
272        }
273        self.value().map(Some)
274    }
275
276    fn value(&mut self) -> Result<JsonEvent<'a>, JsonReadError> {
277        let start = self.position;
278        let token = match self.peek().ok_or(JsonReadError::InvalidJson)? {
279            b'n' => {
280                self.keyword(b"null")?;
281                JsonToken::Null
282            }
283            b't' => {
284                self.keyword(b"true")?;
285                JsonToken::Bool(true)
286            }
287            b'f' => {
288                self.keyword(b"false")?;
289                JsonToken::Bool(false)
290            }
291            b'"' => JsonToken::String(self.string()?),
292            b'-' | b'0'..=b'9' => JsonToken::Number(self.number()?),
293            b'[' | b'{' => {
294                if self
295                    .depth_limit
296                    .is_some_and(|limit| self.stack.frames().len() >= limit)
297                {
298                    return Err(JsonReadError::InvalidJson);
299                }
300                let array = self.peek() == Some(b'[');
301                self.stack.push(if array {
302                    Frame::ArrayFirst
303                } else {
304                    Frame::ObjectFirst
305                })?;
306                self.advance()?;
307                if array {
308                    JsonToken::StartArray
309                } else {
310                    JsonToken::StartObject
311                }
312            }
313            _ => return Err(JsonReadError::InvalidJson),
314        };
315        self.check()?;
316        Ok(self.event(start, token))
317    }
318
319    fn replace(&mut self, frame: Frame) {
320        *self.stack.frames().last_mut().expect("open JSON container") = frame;
321    }
322
323    fn close(&mut self, token: JsonToken<'a>) -> Result<Option<JsonEvent<'a>>, JsonReadError> {
324        let start = self.position;
325        self.advance()?;
326        self.stack.pop();
327        Ok(Some(self.event(start, token)))
328    }
329
330    fn event(&self, start: usize, token: JsonToken<'a>) -> JsonEvent<'a> {
331        JsonEvent {
332            token,
333            range: start..self.position,
334        }
335    }
336
337    fn check(&self) -> Result<(), JsonReadError> {
338        if let Some(cancellation) = self.cancellation {
339            cancellation.check()?;
340        }
341        if let Some(production) = self.production {
342            production.check_cancellation()?;
343        }
344        Ok(())
345    }
346}
347
348#[cfg(test)]
349mod tests;