qubit-json 0.12.2

Resource-aware infrastructure for lenient and strict JSON processing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Shared lexical admission and Serde materialization for JSON documents.

use qubit_budget::ResourceQuantity;
use qubit_budget::json::JsonDecodeAttempt;
use serde::de::DeserializeSeed;
use serde_json::Deserializer as JsonDeserializer;
use serde_json::Error;

use crate::lexical::JsonLexicalError;
use crate::lexical::JsonLexicalScanner;
use crate::lexical::JsonNumberModel;

/// Lexically validates and stages value accounting for one complete document.
///
/// # Parameters
///
/// * `attempt` - Decode attempt whose value transaction receives staged usage.
/// * `input` - Complete JSON document bytes to scan.
/// * `has_value_limits` - Whether value measurements can reject the document.
///
/// # Type Parameters
///
/// * `R` - Resource identity tracked by the decode attempt; it must be
///   cloneable.
/// * `Q` - Quantity representation used by value accounting.
///
/// # Returns
///
/// Returns `Ok(())` after the scanner admits the complete document and leaves
/// its successful value measurements staged in `attempt`.
///
/// # Errors
///
/// Returns a syntax failure or the first value-budget rejection reported by
/// the lexical scanner. All successful measurements remain staged in
/// `attempt` until its caller commits or drops the attempt.
pub(in crate::decode) fn admit_json_document<R, Q>(
    attempt: &mut JsonDecodeAttempt<'_, R, Q>,
    input: &[u8],
    has_value_limits: bool,
) -> Result<(), JsonLexicalError<R, Q>>
where
    R: Clone,
    Q: ResourceQuantity,
{
    JsonLexicalScanner::new(attempt.value_transaction_mut(), has_value_limits).scan(input)
}

/// Admits a JSON document using an explicitly selected number range contract.
///
/// # Parameters
///
/// * `attempt` - Decode attempt whose value transaction receives staged usage.
/// * `input` - Complete JSON document bytes to scan.
/// * `has_value_limits` - Whether value measurements can reject the document.
/// * `model` - Number range contract applied while scanning number tokens.
///
/// # Type Parameters
///
/// * `R` - Resource identity tracked by the decode attempt; it must be
///   cloneable.
/// * `Q` - Quantity representation used by value accounting.
///
/// # Returns
///
/// Returns `Ok(())` after the scanner admits the complete document and leaves
/// its successful value measurements staged in `attempt`.
///
/// # Errors
///
/// Returns a syntax failure or the first value-budget rejection reported by
/// the lexical scanner under the selected number model.
pub(in crate::decode) fn admit_json_document_with_number_model<R, Q>(
    attempt: &mut JsonDecodeAttempt<'_, R, Q>,
    input: &[u8],
    has_value_limits: bool,
    model: JsonNumberModel,
) -> Result<(), JsonLexicalError<R, Q>>
where
    R: Clone,
    Q: ResourceQuantity,
{
    JsonLexicalScanner::new(attempt.value_transaction_mut(), has_value_limits)
        .with_number_model(model)
        .scan(input)
}

/// Deserializes one complete JSON document through a caller-provided seed.
///
/// # Parameters
///
/// * `seed` - Serde seed that materializes the target value.
/// * `input` - Complete JSON document bytes borrowed for `'de`.
///
/// # Type Parameters
///
/// * `'de` - Lifetime for which the input bytes and deserialized borrows remain
///   valid.
/// * `S` - Seed that produces the requested value from the document.
///
/// # Returns
///
/// The value produced by `seed` after the deserializer confirms that no input
/// remains after the document.
///
/// # Errors
///
/// Returns [`Error`] when the seed rejects the target shape or the
/// deserializer does not consume one complete document.
///
/// # Panics
///
/// Panics raised by the seed's visitor propagate to the caller.
pub(in crate::decode) fn deserialize_json_document<'de, S>(
    seed: S,
    input: &'de [u8],
) -> Result<S::Value, Error>
where
    S: DeserializeSeed<'de>,
{
    let mut deserializer = JsonDeserializer::from_slice(input);
    let value = seed.deserialize(&mut deserializer)?;
    deserializer.end()?;
    Ok(value)
}