Add images of json_documents: save() and load()

An image is a document stored so that loading it needs no parsing: save() writes the node index, the text and the decoded strings; the static load() reads an image written by save(). load() takes a pointer and size, a borrowed vector, or an owned rvalue vector; the nodes are copied so they are aligned and can be edited, while the text and decoded strings stay in the image. image_check controls how much load() trusts the input: full checks structure, bounds, strings and numbers, the parser's own guarantees; bounds checks structure and bounds only; none skips all checks, for images from a trusted source. Layout is little-endian only ("NJVI" header, nodes, text, decoded strings), following the idea of zero-copy formats such as FlatBuffers and YaFF; the check follows FlatBuffers' Verifier. New errors: parse_error.116 for a malformed image or a failed check, type_error.320 for a discarded document or a big-endian target. A dedicated fuzzer and 6,000 seeded corruptions, checked under ASan/UBSan, found and fixed two gaps: unchecked reserved header fields, and unbounded null/boolean offsets that could make dump() throw std::length_error. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-13 01:47:11 +00:00 · 2026-10-07 16:42:51 +02:00
1 parent c6ee5a64be
commit 73ceb71c95
@@ -0,0 +1,169 @@
+# <small>nlohmann::basic_json_document::</small>load
+
+```cpp
+// (1)
+static basic_json_document load(const std::uint8_t* image, std::size_t size,
+                                 const image_check check = image_check::full);
+
+// (2)
+static basic_json_document load(const std::vector<std::uint8_t>& image,
+                                 const image_check check = image_check::full);
+
+// (3)
+static basic_json_document load(std::vector<std::uint8_t>&& image,
+                                 const image_check check = image_check::full);
+```
+
+1. Reads an image [`save()`](save.md) wrote, from a pointer and a byte count. The image is **borrowed**: `image`
+   must stay alive and unchanged for as long as the returned document, and any view taken from it, is used.
+2. Reads an image from a `#!cpp std::vector`. Also **borrowed** -- equivalent to overload 1 called with
+   `#!cpp image.data()` and `#!cpp image.size()`.
+3. Reads an image, keeping the vector instead of copying it: `image` is moved into the document (no copy), which
+   then owns it for as long as it needs the text and the decoded strings. [`owns_source()`](owns_source.md) is
+   `#!cpp true` afterward.
+
+In every overload, the node index is copied into storage the document itself owns -- so that it is properly aligned,
+and, for an [editable](index.md#edits) document, can be edited -- while the text and the decoded strings stay in
+`image`. The hash indexes [large objects](../../features/json_view.md) use for lookup are rebuilt, exactly as after
+parsing.
+
+## Parameters
+
+`image` (in)
+:   the image [`save()`](save.md) wrote (overloads 1 and 2), or one to take ownership of (overload 3)
+
+`size` (in)
+:   the number of bytes at `image` (overload 1)
+
+`check` (in)
+:   how thoroughly to validate `image` before trusting it; see [`image_check`](#image_check) below (optional,
+    `#!cpp image_check::full` by default)
+
+## Return value
+
+The document read from the image.
+
+## Exception safety
+
+Overloads 1 and 2 give the strong guarantee: `image` is only read, never written, so a thrown exception leaves the
+caller's buffer untouched.
+
+Overload 3 moves `image` into the document *before* validating it, so that a good image is kept without a copy. If
+loading then fails, the partially built document -- and the vector now inside it -- is discarded along with the
+exception, and `image` itself is left **empty**, not restored to what was passed in. Move a copy in instead, or
+validate with overload 2 first, if the original vector must survive a failed load.
+
+## Exceptions
+
+On a big-endian target, throws [`type_error.320`](../../home/exceptions.md#jsonexceptiontype_error320) -- the same
+exception [`save()`](save.md#exceptions) throws there, since the image format is little-endian only.
+
+Otherwise throws [`parse_error.116`](../../home/exceptions.md#jsonexceptionparse_error116) if `image` is not one
+`save()` could have written, or fails the requested `check`:
+
+| message               | when                                                                                                |
+|------------------------|------------------------------------------------------------------------------------------------------|
+| `too short`            | `image` is `#!cpp nullptr`, or `size` is smaller than the 64-byte header                             |
+| `unknown format`       | the header's magic bytes or version do not match, or a reserved header field is not zero             |
+| `sizes out of range`   | the node count, text size, or decoded-string size the header describes does not fit `size`, or the `#!cpp '\0'` after the text or after the decoded strings is missing |
+| `the check failed`     | `check` is not `#!cpp image_check::none`, and the image fails it -- see [`image_check`](#image_check) |
+
+!!! failure "Example messages"
+
+    ```
+    [json.exception.parse_error.116] parse error: invalid json_document image: too short
+    ```
+    ```
+    [json.exception.parse_error.116] parse error: invalid json_document image: unknown format
+    ```
+    ```
+    [json.exception.parse_error.116] parse error: invalid json_document image: sizes out of range
+    ```
+    ```
+    [json.exception.parse_error.116] parse error: invalid json_document image: the check failed
+    ```
+
+## Complexity
+
+Linear in the number of nodes, which are always copied into the document. With `#!cpp check == image_check::full`,
+additionally linear in the combined length of the text and the decoded strings; `#!cpp image_check::bounds` and
+`#!cpp image_check::none` do not read them.
+
+## Notes
+
+**The `image_check` modes.**
+
+```cpp
+using image_check = detail::view::image_check;
+
+enum class image_check
+{
+    full,
+    bounds,
+    none
+};
+```
+
+How thoroughly `load()` validates `image` before trusting it.
+
+| value    | checks                                                                                                    | guarantees |
+|----------|--------------------------------------------------------------------------------------------------------------|------------|
+| `full`   | everything the parser itself guarantees: structure and bounds; that every string is valid UTF-8 (and, for a string still in the source text, that it contains no quote, backslash, or control character); and that every number token is well-formed and matches the value stored for it | reading and serializing a checked image is safe and always produces valid JSON, exactly as for a parsed document |
+| `bounds` | structure and bounds only -- that every offset and count in the node index stays inside the image            | reading and serializing stay memory-safe, but a crafted image can hold strings that are not valid UTF-8 or that serialize to invalid JSON ([`dump()`](../basic_json_view/dump.md) writes them unchanged or throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316)), and numbers whose values differ from their text |
+| `none`   | nothing                                                                                                       | images from a trusted source only -- reading a damaged image is undefined behavior |
+
+`full` is the default and the right choice for an image from anything you do not fully control -- a file, a cache
+shared with other processes, a peer on the network. `bounds` skips scanning the text and the decoded strings, so it
+fits a cache your own process just wrote and reads straight back, where damage would mean a bug or a hardware fault
+rather than adversarial input; it still cannot crash or read out of bounds. `none` skips validation entirely and
+should only be used for an image you trust as much as your own memory.
+
+**Lifetime.** Overloads 1 and 2 borrow `image`: it must stay alive and byte-for-byte unchanged for as long as the
+returned document, and any [view](../basic_json_view/index.md) taken from it, is used -- exactly like a document
+[`parse()`](parse.md) borrowed its input for. Overload 3 avoids this by keeping the vector itself; see
+[`owns_source`](owns_source.md).
+
+!!! warning "Experimental"
+
+    The image format is versioned but not yet stable, and may change in an incompatible way before it is declared
+    stable; `load()` already rejects an image written by a different format version with `parse_error.116`
+    ("unknown format"). Use images to cache a document within one build of the library, or to hand one to another
+    process running the *same* build on the *same* (little-endian) machine -- not as a long-term storage format.
+
+**What `image_check::bounds` does not guarantee.** A bounds-checked image can never make `load()`,
+[`root()`](root.md), element access, or [`materialize()`](../basic_json_view/materialize.md) read outside the image,
+so those stay safe on a damaged one. It does *not* guarantee that the image describes valid JSON: a string
+that a `full` check would have rejected can make [`dump()`](../basic_json_view/dump.md) write invalid UTF-8 or invalid
+JSON, or throw `type_error.316`, and a number can read back with a value that does not match how it is spelled.
+Reserve `bounds` for images you already trust to be well-formed, and use it only to skip the extra scan.
+
+## Examples
+
+??? example "Caching a document, ownership, and a rejected image"
+
+    The example below saves a parsed document as an image, checks that `load()` reproduces the original
+    [`dump()`](../basic_json_view/dump.md) without parsing, and shows the difference between
+    `load(std::move(image))` (owned) and `load(image)` (borrowed). It then damages one byte of the image and shows
+    `image_check::full` rejecting it with `parse_error.116`, while `image_check::bounds` -- meant for a cache the
+    process already trusts -- still reads it without going out of bounds.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__load.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__load.output"
+    ```
+
+## See also
+
+- [save](save.md) - write the document as an image
+- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
+- [parse](parse.md) - deserialize from JSON text instead of an image
+- [Images](../../features/json_view.md#images) - why and when to use images
+
+## Version history
+
+- Added in version 3.13.0.