book_stream.h File Reference

Strict, zero-allocation validation of a streamed RABOOK1 flat blob. More...

#include <stdint.h>
#include "book.h"
#include "ra8_err.h"

Include dependency graph for book_stream.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef ra8_err_t(*	book_stream_read_fn) (void *ctx, uint64_t offset, uint8_t *dst, uint32_t len)
	Exact random-read callback over an inflated RABOOK1 flat blob.

Functions
ra8_err_t	book_validate_stream_strict (book_stream_read_fn read, void *read_ctx, uint64_t source_size, uint8_t *scratch, uint32_t scratch_cap, book_header_t *out_header)
	Strictly validate one callback-backed RABOOK1 flat blob.

Detailed Description

Strict, zero-allocation validation of a streamed RABOOK1 flat blob.

The resident book_validate API preserves the original v1 compatibility contract. This interface is the fail-closed ingestion gate for newly downloaded or externally supplied books: it validates the canonical wire layout and every reference through a random-read callback while hashing the complete body through a bounded caller-owned transfer buffer.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

Version 0.1.0

Definition in file book_stream.h.

Typedef Documentation

book_stream_read_fn

typedef ra8_err_t(* book_stream_read_fn) (void *ctx, uint64_t offset, uint8_t *dst, uint32_t len)

Exact random-read callback over an inflated RABOOK1 flat blob.

Parameters

[in]	ctx	Opaque source context supplied to the validator.
[in]	offset	Byte offset from the beginning of the flat blob.
[out]	dst	Destination for exactly len bytes.
[in]	len	Exact byte count requested.

Returns

k_ra8_ok on a complete read, otherwise a source error.

Precondition

The callback either fills all len bytes or returns an error.

Since

Version 0.1.0

Definition at line 38 of file book_stream.h.

Function Documentation

book_validate_stream_strict()

ra8_err_t book_validate_stream_strict ( book_stream_read_fn read, void * read_ctx, uint64_t source_size, uint8_t * scratch, uint32_t scratch_cap, book_header_t * out_header )

nodiscard

Strictly validate one callback-backed RABOOK1 flat blob.

Requires the source length and header total to agree exactly, then enforces the canonical contiguous table/pool layout, known version and flags, string-boundary references, table indices, forward-only DOM links, exact attribute ownership, known image representations, and a gap-free image pool. Finally it reads every body byte through scratch and verifies the stored CRC-32. All wire integers are decoded little-endian, so validation does not depend on host alignment or byte order.

Parameters

[in]	read	Exact random-read callback over the inflated flat blob.
[in]	read_ctx	Opaque context passed to read.
[in]	source_size	Exact readable source length in bytes.
[out]	scratch	Caller-owned transfer and node-ownership workspace.
[in]	scratch_cap	Capacity of scratch; must be at least one byte and at least ceil(node_count/8) bytes.
[out]	out_header	Receives the decoded host-order header on success.

Returns

Validation status.

Return values

k_ra8_ok	The complete flat blob is canonical and intact.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_size	A length, layout, or extent is inconsistent.
k_ra8_err_invalid_arg	A semantic field or reference is invalid.
k_ra8_err_range_check_failed	The full body CRC does not match.
k_ra8_err_*	A callback error, returned verbatim.

Precondition

The source is immutable for the duration of validation.

scratch does not alias mutable source state used by read.

Postcondition

On success out_header describes the fully validated source.

On failure out_header is zeroed and must not be consumed.

Note

No dynamic allocation or recursion is used.

Since

Version 0.1.0

Definition at line 630 of file book_stream.c.

References stream_validate_t::hdr, internal_validate_body(), k_book_sizeof_header, k_ra8_err_invalid_size, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by book_chunked_validate_strict().