qubit-json 0.12.4

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

// =============================================================================
//    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)
}