jsonx-lib 0.5.2

Strict RFC 8259 JSON: a borrowing parser, a pull reader, and a deterministic writer, with budgets checked before allocation and no recursion. No dependencies, no_std.
Documentation

The model

The ways in, simplest first:

  • parse, from_str, and to_string: one call each, default budgets, duplicate keys refused.
  • Parser: the same with your own Limits, DuplicateKeys policy, and Numbers option, defined once as a const.
  • Reader: the document as a stream of Events, with read_raw to keep a value as its exact source text, read_value to build one part, decode to read one part as a type, and find_pointer to go straight to one value. StreamReader is the same reader fed in chunks as input arrives. Both read sequences of documents (NDJSON) on request.
  • Typed values: FromJson reads your type from a reader and ToJson writes it through a typed writer, with no tree in between. You implement them by hand (or let json_struct! do it for a plain struct): no derive, no reflection. Errors say what, at which byte, and where (a JSON Pointer path).
  • Writer: a push writer, checked as it goes, into a String, an io::Write, or a fmt::Write, in any Format (indent width, HTML-safe, ASCII-only).

A parsed Value borrows from its input; Number keeps exact text with lazy conversion; Object keeps members in document order; RawValue keeps a validated value as text; json! builds values in code.

What it guarantees, and how each guarantee is checked:

Guarantee How it is held
The RFC 8259 grammar; everything outside it refused at the first byte that cannot continue a valid text. Lone surrogate escapes, and (by default) repeated keys, are refused by choice. Property tests run random token soup and mutated documents through the crate and an independent strict reference parser written from the RFC grammar: verdict, value, and exact error offset agree. 234 JSONTestSuite-style cases written as data (73 accept, 127 refuse, 34 implementation-defined) pin the kind and offset of every refusal.
Every way of reading agrees: parse, events, raw slices, the incremental reader at any chunking, typed reads. Properties compare the incremental reader with the complete one for every mix of calls and chunk boundaries, and every reading path's duplicate-key refusals with parse's.
Duplicate keys cannot smuggle a second value. Refused by default on every reading path, compared after unescaping, in O(n log n); the documented JSON-RPC Reader loop sees the error at the object's }. Every policy is checked against a naive reference.
Written output parses back to the same value, in every format (for objects without repeated keys: the writers do not check keys for repeats). Round-trip properties over arbitrary documents, compact, pretty, indented, HTML-safe, and ASCII-only, checked by both parsers; typed output matches the Value output it stands for.
No string can change the structure of the output. Arbitrary strings (rich in quotes, backslashes, control characters, U+2028/U+2029) written as values and keys always read back, under the reference parser, as exactly themselves.
Budgets refuse before allocating; one read call (parse, read_value, decode), tree or typed value, holds at most about max_memory (64 MiB by default). A counting allocator measures peak heap: an 8 MiB string over a 1 KiB budget is refused with under 1 KiB allocated; over-size input with none; five hostile document shapes (flat, nested, pairs, members, escapes) stay within max_memory under the defaults.
No stack overflow, no panic. A million levels of nesting parse, write, transcode, clone, compare, and drop on a thread with a 256 KiB stack. Five cargo-fuzz targets cover every reading entry point with these oracles (no counterexample in about 4.0 M runs of the smoke pass), and the same checks run on arbitrary bytes in cargo test on every platform.

Installation

[dependencies]
jsonx-lib = "0.5"

Without the standard library:

[dependencies]
jsonx-lib = { version = "0.5", default-features = false }

Quick start

use jsonx_lib::{json, parse, to_string};

let doc = parse(r#"{"name": "jsonx", "version": [0, 5, 0], "stable": false}"#)?;
assert_eq!(doc["name"], "jsonx");
assert_eq!(doc["version"][1].as_u64(), Some(5));
assert!(doc["license"].is_null()); // indexing never panics

let reply = json!({ "ok": true, "items": [1, 2, 3] });
assert_eq!(to_string(&reply), r#"{"ok":true,"items":[1,2,3]}"#);

let err = parse(r#"{"a": [1, 2,]}"#).unwrap_err();
assert_eq!(err.to_string(), "trailing comma before `}` or `]` at byte 12");
# Ok::<(), jsonx_lib::Error>(())

Your own types, no serde

use std::borrow::Cow;
use jsonx_lib::{json_struct, DecodeError, FromJson, Reader, ToJson, ValueWriter, Written};

// A plain struct: one line writes both impls.
struct Position { line: u32, character: u32 }
json_struct!(Position { line, character });

// Or by hand, for full control.
struct Location<'a> { uri: Cow<'a, str>, position: Position }

impl<'de> FromJson<'de> for Location<'de> {
    fn from_json(reader: &mut Reader<'de>) -> Result<Self, DecodeError> {
        let (mut uri, mut position) = (None, None);
        let mut object = reader.read_object()?;
        while let Some(key) = object.next_key()? {
            match &*key {
                "uri" => object.field(&mut uri)?,
                "position" => object.field(&mut position)?,
                _ => {} // unknown members are skipped, still validated
            }
        }
        Ok(Location { uri: object.required(uri, "uri")?, position: object.required(position, "position")? })
    }
}

impl ToJson for Location<'_> {
    fn to_json(&self, out: ValueWriter<'_>) -> Written {
        out.object(|o| {
            o.member("uri", &self.uri);
            o.member("position", &self.position);
        })
    }
}

let text = r#"{"uri": "file:///a.rs", "position": {"line": 3, "character": 14}}"#;
let loc: Location = jsonx_lib::from_str(text)?;
assert!(matches!(loc.uri, Cow::Borrowed(_))); // borrowed from `text`
assert_eq!(jsonx_lib::to_string(&loc), r#"{"uri":"file:///a.rs","position":{"line":3,"character":14}}"#);

let bad = r#"{"uri": "x", "position": {"line": "3", "character": 0}}"#;
let err = jsonx_lib::from_str::<Location>(bad).err().map(|e| e.to_string());
assert_eq!(err.as_deref(), Some("expected u32, found string at byte 34 (at /position/line)"));
# Ok::<(), DecodeError>(())

Budgets and duplicate keys

use jsonx_lib::{DuplicateKeys, ErrorKind, Limits, Parser};

const WIRE: Parser = Parser::new()
    .limits(Limits::new().with_max_input_bytes(1 << 20).with_max_depth(32).with_max_memory(4 << 20))
    .duplicate_keys(DuplicateKeys::Error);

let err = WIRE.parse(&"[".repeat(1_000_000)).unwrap_err();
assert_eq!((err.kind(), err.offset()), (ErrorKind::DepthLimitExceeded, 32));

let err = WIRE.parse(r#"{"role": "user", "role": "admin"}"#).unwrap_err();
assert_eq!(err.kind(), ErrorKind::DuplicateKey);

Reading a message without building a tree

use jsonx_lib::{Event, Reader};

let message = r#"{"jsonrpc": "2.0", "id": 4, "method": "hover", "params": {"line": 3}}"#;
let mut reader = Reader::new(message);
let (mut method, mut params) = (None, None);
assert_eq!(reader.next_event()?, Some(Event::StartObject));
while let Some(Event::Key(key)) = reader.next_event()? {
    match &*key {
        "method" => method = reader.read_value()?,
        "params" => params = reader.read_raw()?, // exact text, validated, not decoded
        _ => { let _skipped = reader.read_raw()?; }
    }
}
reader.finish()?;
assert_eq!(method.as_ref().and_then(|m| m.as_str()), Some("hover"));
assert_eq!(params, Some(r#"{"line": 3}"#));

// A repeated member never reaches the end of that loop: the reader refuses
// the object at its `}`, as `parse` does.
let mut reader = Reader::new(r#"{"method": "initialize", "method": "shutdown"}"#);
reader.next_event()?;
while let Ok(Some(Event::Key(_))) = reader.next_event() {
    reader.read_raw()?;
}
assert!(reader.finish().is_err());
# Ok::<(), jsonx_lib::Error>(())

Input as it arrives, output as it goes

use jsonx_lib::{Step, StreamReader, Writer};

// NDJSON from a socket, fed in whatever pieces arrive.
let mut stream = StreamReader::new().documents();
let mut out = String::new();
let mut writer = Writer::new(&mut out);
writer.begin_array()?;
for chunk in [&b"{\"id\": 1, \"ok\": tr"[..], b"ue}\n{\"id\": 2, \"ok\": false}\n"] {
    stream.feed(chunk)?;
    while let Step::Ready(Some(record)) = stream.read_value()? {
        writer.value(&record["id"])?;
    }
}
stream.end_input();
writer.end_array()?;
writer.finish()?;
assert_eq!(out, "[1,2]");
# Ok::<(), Box<dyn std::error::Error>>(())

Performance

Measured against 0.2.0 on the same machine (Windows x86_64, Rust 1.99), with paired samples so load hits both versions alike; time is 0.5's over 0.2's, 10th to 90th percentile:

Input parse Reader events (duplicate keys refused)
An LSP request's params (~110 bytes) 0.80-0.93, 5 allocations (0.2: 7) 0.77-0.81, no allocation
A whole LSP request (~175 bytes) 0.82-0.97 0.72-0.97
A 1 MiB LSP document 0.80-1.02 0.87-1.18

On the 1 MiB benchmark document (cargo bench --bench bench): parse about 220 MiB/s, events about 510 MiB/s, read_raw about 610 MiB/s, to_string about 1.05 GiB/s, typed decoding into structs about 300 MiB/s, and the incremental reader about 395 MiB/s. Typed decoding of a small request takes 2.3 to 2.6 times as long as serde_json's derive (median about 2.5 times) and allocates nothing. Method and every number: the release notes.

0.5.1 made writing faster without changing a byte of output: typed structs in 0.56 of 0.5.0's time, pretty output in 0.72, floats in about a third; metrics-lib's JSON snapshot is written in about 0.75 of serde_json's time. The 0.5.1 release notes.

Documentation

Contributing

See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.