book_stream.c File Reference

Strict callback-driven validation of a RABOOK1 flat blob. More...

#include "book_stream.h"
#include <string.h>
#include "book_internal.h"
#include "book_stream_internal.h"
#include "ra8_attributes.h"

Include dependency graph for book_stream.c:

Go to the source code of this file.

Functions
ra8_err_t	priv_book_stream_validate_metadata (const stream_validate_t *ctx)
	Validate metadata string references and the optional cover index.
static ra8_err_t	internal_validate_chapters (const stream_validate_t *ctx)
	Validate every chapter string and root-node index.
static ra8_err_t	internal_forward_link (uint32_t link, uint32_t current, uint32_t count)
	Validate one optional forward node link.
static ra8_err_t	internal_mark_forward_link (const stream_validate_t *ctx, uint32_t link, uint32_t current)
	Record one unique incoming node reference in the caller bitset.
ra8_err_t	priv_book_stream_validate_element (const stream_validate_t *ctx, const uint8_t *rec, uint32_t *attr_cursor)
	Validate one element node and its canonical attribute span.
ra8_err_t	priv_book_stream_validate_text (const stream_validate_t *ctx, const uint8_t *rec)
	Validate one text node's element-only fields and string reference.
static ra8_err_t	internal_validate_one_node (const stream_validate_t *ctx, const uint8_t *rec, uint32_t *attr_cursor, uint32_t index)
	Validate one node record's fields and mark its forward links.
static ra8_err_t	internal_validate_nodes (const stream_validate_t *ctx)
	Validate every DOM node and exact attribute ownership.
static ra8_err_t	internal_validate_attrs (const stream_validate_t *ctx)
	Validate every attribute name/value string reference.
ra8_err_t	priv_book_stream_validate_styles (const stream_validate_t *ctx)
	Validate every stylesheet source and optional chapter scope.
static ra8_err_t	internal_validate_raster (const uint8_t *rec)
	Validate one raster image's dimensions, depth, and exact byte count.
static ra8_err_t	internal_validate_svg (const uint8_t *rec)
	Validate one SVG image's zero extent/depth and raw-storage length.
static ra8_err_t	internal_validate_images (const stream_validate_t *ctx)
	Validate every image descriptor and exact gap-free pool tiling.
static ra8_err_t	internal_validate_crc (const stream_validate_t *ctx)
	Hash every body byte through the caller transfer buffer.
static ra8_err_t	internal_validate_body (stream_validate_t *ctx)
	Run the strict passes after public argument validation.
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 callback-driven validation of a RABOOK1 flat blob.

Coordinates canonical wire-header validation with every semantic table, DOM edge, image extent, and body-integrity pass. Bounded caller scratch supplies both transfer storage and the DOM ownership map, so validation neither maps the source nor allocates memory.

Copyright

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

Since

Version 0.1.0

Definition in file book_stream.c.

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().

internal_forward_link()

ra8_err_t internal_forward_link ( uint32_t link, uint32_t current, uint32_t count )

static

Validate one optional forward node link.

Treats nil as absent and otherwise requires the target to be both in range and greater than the owner, which excludes cycles.

Parameters

[in]	link	Candidate node index or nil.
[in]	current	Index of the owning node.
[in]	count	Total node count.

Returns

k_ra8_ok for nil or a strictly forward in-range link.

Return values

k_ra8_ok	The link is nil or a valid forward target.
k_ra8_err_invalid_arg	The target is backward, self, or out of range.

Precondition

current is less than count.

count is the validated node-table record count.

Postcondition

No state is modified.

Success proves a non-nil link cannot introduce a backward cycle.

Note

Pure and thread-safe.

Since

Version 0.1.0

Definition at line 139 of file book_stream.c.

References k_book_nil, k_ra8_err_invalid_arg, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_mark_forward_link().

internal_mark_forward_link()

ra8_err_t internal_mark_forward_link ( const stream_validate_t * ctx, uint32_t link, uint32_t current )

static

Record one unique incoming node reference in the caller bitset.

Validates forward-link geometry before testing and setting the corresponding ownership bit; duplicate parents fail closed.

Parameters

[in]	ctx	Validation state whose scratch holds ownership bits.
[in]	link	Candidate node index or nil.
[in]	current	Index of the linking node.

Returns

k_ra8_ok for nil or one unique strictly-forward reference.

Return values

k_ra8_ok	The link is nil or was newly marked.
k_ra8_err_invalid_arg	The link is invalid or already owned.

Precondition

Ownership scratch was cleared and sized for node_count bits.

current names an existing node in ctx->hdr.

Postcondition

Success on a non-nil link marks exactly one target bit.

Nil success leaves the ownership map unchanged.

Note

Not thread-safe; mutates caller scratch only.

Since

Version 0.1.0

Definition at line 169 of file book_stream.c.

References stream_validate_t::hdr, internal_forward_link(), k_book_nil, k_ra8_err_invalid_arg, k_ra8_ok, book_header_t::node_count, and stream_validate_t::scratch.

Referenced by internal_validate_one_node().

internal_validate_attrs()

ra8_err_t internal_validate_attrs ( const stream_validate_t * ctx )

static

Validate every attribute name/value string reference.

Reads each fixed-size attribute record, requires a non-empty name, and accepts an empty or non-empty value at a valid boundary.

Parameters

[in]

ctx

Validation state.

Returns

Attribute-table validation status.

Return values

k_ra8_ok	Every attribute string reference is valid.
k_ra8_err_invalid_arg	A name or value offset is not a string boundary.

Precondition

Node validation proved exact attribute ownership.

Header layout bounds every attribute record in the source.

Postcondition

No state is modified.

Success makes every attribute record safe for string lookup.

Note

Iteration is bounded by attr_count.

Since

Version 0.1.0

Definition at line 361 of file book_stream.c.

References book_header_t::attr_count, book_header_t::attr_off, stream_validate_t::hdr, internal_book_stream_le32(), k_book_sizeof_attr, k_ra8_ok, priv_book_stream_nonempty_string_ref(), priv_book_stream_read(), priv_book_stream_string_ref(), and RA8_INTERNAL.

Referenced by internal_validate_body().

internal_validate_body()

ra8_err_t internal_validate_body ( stream_validate_t * ctx )

static

Run the strict passes after public argument validation.

Decodes the header, validates canonical layout and each semantic table in dependency order, then verifies the body CRC last.

Parameters

[in,out]

ctx

Initialized validation state.

Returns

First strict validation error, or k_ra8_ok.

Return values

k_ra8_ok	Every structural, semantic, and integrity pass succeeded.
k_ra8_err_invalid_arg	A decoded semantic invariant failed.
k_ra8_err_invalid_size	A source, table, pool, or scratch extent failed.

Precondition

All pointers and scratch capacity are valid.

ctx->source_size is at least the fixed wire-header length.

Postcondition

Success leaves ctx->hdr fully decoded and validated.

Failure is returned immediately without publishing an output header.

Note

Not thread-safe with respect to the callback source.

Since

Version 0.1.0

Definition at line 595 of file book_stream.c.

References stream_validate_t::hdr, internal_validate_attrs(), internal_validate_chapters(), internal_validate_crc(), internal_validate_images(), internal_validate_nodes(), k_ra8_ok, memset(), book_header_t::node_count, priv_book_stream_read_validate_header(), priv_book_stream_validate_metadata(), priv_book_stream_validate_string_envelope(), priv_book_stream_validate_styles(), RA8_INTERNAL, and stream_validate_t::scratch.

Referenced by book_validate_stream_strict().

internal_validate_chapters()

ra8_err_t internal_validate_chapters ( const stream_validate_t * ctx )

static

Validate every chapter string and root-node index.

Requires canonical title/id strings, an element root with no sibling, and unique ownership of every chapter root in the scratch bitset.

Parameters

[in]

ctx

Validation state.

Returns

Chapter-table validation status.

Return values

k_ra8_ok	Every chapter record and root is valid and unique.
k_ra8_err_invalid_arg	A reference, root kind, or ownership rule fails.

Precondition

Header layout and string envelope are valid.

The node ownership scratch bitset is zeroed and sufficiently large.

Postcondition

No source bytes or decoded header state are modified.

Success marks each chapter root exactly once in caller scratch.

Note

Iteration is bounded by chapter_count.

Since

Version 0.1.0

Definition at line 75 of file book_stream.c.

References book_header_t::chapter_count, book_header_t::chapter_off, stream_validate_t::hdr, internal_book_stream_le32(), k_book_nil, k_book_node_element, k_book_sizeof_chapter, k_book_sizeof_node, k_ra8_err_invalid_arg, k_ra8_ok, k_stream_node_kind, k_stream_node_next_sibling, book_header_t::node_count, book_header_t::node_off, priv_book_stream_nonempty_string_ref(), priv_book_stream_read(), priv_book_stream_string_ref(), RA8_INTERNAL, and stream_validate_t::scratch.

Referenced by internal_validate_body().

internal_validate_crc()

ra8_err_t internal_validate_crc ( const stream_validate_t * ctx )

static

Hash every body byte through the caller transfer buffer.

Reads the body in scratch-sized exact spans and extends the shared CRC convention without retaining the complete source.

Parameters

[in]

ctx

Validation state.

Returns

Full-body CRC validation status.

Return values

k_ra8_ok	The computed body CRC equals the header value.
k_ra8_err_range_check_failed	The computed CRC differs.

Precondition

Header layout is valid and scratch capacity is non-zero.

ctx contains a usable exact-read callback and writable scratch.

Postcondition

No source bytes or decoded header state are modified.

Success proves every body byte contributed exactly once in wire order.

Note

Iteration is bounded by total_size and scratch_cap.

Since

Version 0.1.0

Definition at line 558 of file book_stream.c.

References book_header_t::crc32_val, stream_validate_t::hdr, k_book_sizeof_header, k_ra8_err_range_check_failed, k_ra8_ok, priv_book_crc32_extend(), priv_book_stream_read(), RA8_INTERNAL, stream_validate_t::scratch, stream_validate_t::scratch_cap, and book_header_t::total_size.

Referenced by internal_validate_body().

internal_validate_images()

ra8_err_t internal_validate_images ( const stream_validate_t * ctx )

static

Validate every image descriptor and exact gap-free pool tiling.

Validates IDs and format semantics, then advances a pool cursor that rejects gaps, overlap, and trailing unowned image bytes.

Parameters

[in]

ctx

Validation state.

Returns

Image-table validation status.

Return values

k_ra8_ok	Every image is valid and exactly tiles the pool.
k_ra8_err_invalid_arg	An ID, reserved field, or format rule fails.
k_ra8_err_invalid_size	Image byte geometry or pool tiling is invalid.

Precondition

Header layout and string envelope are valid.

Every image record and the image pool lie within the validated source.

Postcondition

No state is modified.

Success proves each pool byte belongs to exactly one image in order.

Note

Iteration is bounded by image_count.

Since

Version 0.1.0

Definition at line 502 of file book_stream.c.

References stream_validate_t::hdr, book_header_t::image_count, book_header_t::image_off, book_header_t::image_pool_size, internal_book_stream_le16(), internal_book_stream_le32(), internal_validate_raster(), internal_validate_svg(), k_book_image_gray4, k_book_image_svg, k_book_sizeof_image, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_stream_image_data_off, k_stream_image_data_size, k_stream_image_format, k_stream_image_id, k_stream_image_reserved, priv_book_stream_nonempty_string_ref(), priv_book_stream_read(), and RA8_INTERNAL.

Referenced by internal_validate_body().

internal_validate_nodes()

ra8_err_t internal_validate_nodes ( const stream_validate_t * ctx )

static

Validate every DOM node and exact attribute ownership.

Walks nodes once, validates kind-specific fields, marks unique forward edges, and finally requires every node and attribute owned.

Parameters

[in]

ctx

Validation state.

Returns

Node-table validation status.

Return values

k_ra8_ok	All nodes, links, and attribute spans are canonical.
k_ra8_err_invalid_arg	A node, link, ownership, or span rule fails.

Precondition

Header layout and string envelope are valid.

Chapter validation has already marked each root in scratch.

Postcondition

No source bytes or decoded header state are modified.

Success leaves every node ownership bit set exactly once.

Note

Forward links make cycles impossible without recursion or a visited set.

Since

Version 0.1.0

Definition at line 315 of file book_stream.c.

References book_header_t::attr_count, stream_validate_t::hdr, internal_validate_one_node(), k_book_sizeof_node, k_ra8_err_invalid_arg, k_ra8_ok, k_stream_node_reserved, book_header_t::node_count, book_header_t::node_off, priv_book_stream_read(), RA8_INTERNAL, and stream_validate_t::scratch.

Referenced by internal_validate_body().

internal_validate_one_node()

ra8_err_t internal_validate_one_node ( const stream_validate_t * ctx, const uint8_t * rec, uint32_t * attr_cursor, uint32_t index )

static

Validate one node record's fields and mark its forward links.

Dispatches to the kind-specific validator (element or text), then marks the node's child and sibling links so the caller's ownership-coverage pass can prove every node was reached exactly once.

Parameters

[in]	ctx	Validation state.
[in]	rec	Decoded fixed-size node record.
[in,out]	attr_cursor	Running attribute-ownership cursor.
[in]	index	Node index within the table, for forward-link marking.

Returns

Node validation status.

Return values

k_ra8_ok	The node, its links, and its attribute span are canonical.
k_ra8_err_invalid_arg	A kind, link, or attribute-span rule fails.

Precondition

rec was read from a valid node-table offset.

attr_cursor reflects every prior node's attribute ownership.

Postcondition

Success advances *attr_cursor past this node's owned attributes.

Success marks this node's forward child/sibling links in scratch.

Note

Not thread-safe with respect to the source callback.

Since

Version 0.1.0

Definition at line 273 of file book_stream.c.

References internal_book_stream_le32(), internal_mark_forward_link(), k_book_node_element, k_book_node_text, k_ra8_err_invalid_arg, k_ra8_ok, k_stream_node_first_child, k_stream_node_kind, k_stream_node_next_sibling, priv_book_stream_validate_element(), priv_book_stream_validate_text(), and RA8_INTERNAL.

Referenced by internal_validate_nodes().

internal_validate_raster()

ra8_err_t internal_validate_raster ( const uint8_t * rec )

static

Validate one raster image's dimensions, depth, and exact byte count.

Requires non-zero dimensions, a supported gray depth, and exact packed-pixel data and raw lengths computed with 64-bit arithmetic.

Parameters

[in]

rec

Image descriptor wire bytes.

Returns

Raster semantic validation status.

Return values

k_ra8_ok	Raster geometry and byte lengths are exact.
k_ra8_err_invalid_arg	Dimensions or pixel format are unsupported.
k_ra8_err_invalid_size	A computed or stored pixel extent is invalid.

Precondition

rec names the raster format.

rec addresses one complete image wire record.

Postcondition

No state is modified.

Success proves the raster payload size from its dimensions and depth.

Note

Pure and thread-safe.

Since

Version 0.1.0

Definition at line 437 of file book_stream.c.

References internal_book_stream_le16(), internal_book_stream_le32(), k_book_pixfmt_gray4, k_book_pixfmt_gray8, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_stream_image_data_size, k_stream_image_height, k_stream_image_pixfmt, k_stream_image_raw_size, k_stream_image_width, and RA8_INTERNAL.

Referenced by internal_validate_images().

internal_validate_svg()

ra8_err_t internal_validate_svg ( const uint8_t * rec )

static

Validate one SVG image's zero extent/depth and raw-storage length.

Enforces the SVG sentinel geometry and requires a non-empty stored source whose encoded and raw byte lengths are identical.

Parameters

[in]

rec

Image descriptor wire bytes.

Returns

SVG semantic validation status.

Return values

k_ra8_ok	SVG sentinel fields and storage length are canonical.
k_ra8_err_invalid_arg	A sentinel field or byte length is invalid.

Precondition

rec names the SVG format.

rec addresses one complete image wire record.

Postcondition

No state is modified.

Success proves the SVG source occupies a non-empty exact payload span.

Note

Pure and thread-safe.

Since

Version 0.1.0

Definition at line 472 of file book_stream.c.

References internal_book_stream_le16(), internal_book_stream_le32(), k_book_pixfmt_gray4, k_ra8_err_invalid_arg, k_ra8_ok, k_stream_image_data_size, k_stream_image_height, k_stream_image_pixfmt, k_stream_image_raw_size, k_stream_image_width, and RA8_INTERNAL.

Referenced by internal_validate_images().

priv_book_stream_validate_element()

ra8_err_t priv_book_stream_validate_element	(	const stream_validate_t *	ctx,
		const uint8_t *	rec,
		uint32_t *	attr_cursor )

Validate one element node and its canonical attribute span.

Private test seam for first-attribute and remaining-count guards.

Parameters

[in]	ctx	Validation state with canonical strings and attributes.
[in]	rec	One complete element-node wire record.
[in,out]	attr_cursor	Next unowned attribute index.

Returns

Element validation status.

Return values

k_ra8_ok	The element and attribute span are canonical.
k_ra8_err_invalid_arg	One element invariant is invalid.

Precondition

All pointers are valid for their documented extents.

attr_cursor does not exceed the attribute count.

Postcondition

Success consumes exactly the element's attribute span.

Failure does not advance beyond the advertised count.

Note

Private MC/DC seam; mutates only attr_cursor.

Since

Version 0.1.0

Definition at line 201 of file book_stream.c.

References book_header_t::attr_count, stream_validate_t::hdr, internal_book_stream_le16(), internal_book_stream_le32(), k_book_nil, k_ra8_err_invalid_arg, k_ra8_ok, k_stream_node_attr_count, k_stream_node_first_attr, k_stream_node_name, k_stream_node_text, priv_book_stream_nonempty_string_ref(), and RA8_PRIV.

Referenced by internal_validate_one_node().

priv_book_stream_validate_metadata()

ra8_err_t priv_book_stream_validate_metadata

(

const stream_validate_t *

ctx

)

Validate metadata string references and the optional cover index.

Private test seam for the nil-cover and image-count bounds policy.

Parameters

[in]

ctx

Validation state with a checked string envelope.

Returns

Metadata validation status.

Return values

k_ra8_ok	All references are valid.
k_ra8_err_invalid_arg	A string or cover reference is invalid.

Precondition

Header string offsets and image count are decoded.

The string pool has valid boundary sentinels.

Postcondition

No state is modified.

Success proves every metadata reference safe.

Note

Private MC/DC seam; uses only caller-owned state.

Since

Version 0.1.0

Definition at line 38 of file book_stream.c.

References book_header_t::author_off, book_header_t::cover_image_index, stream_validate_t::hdr, book_header_t::identifier_off, book_header_t::image_count, k_book_nil, k_ra8_err_invalid_arg, k_ra8_ok, book_header_t::language_off, priv_book_stream_string_ref(), RA8_PRIV, and book_header_t::title_off.

Referenced by internal_validate_body().

priv_book_stream_validate_styles()

ra8_err_t priv_book_stream_validate_styles

(

const stream_validate_t *

ctx

)

Validate every stylesheet source and optional chapter scope.

Private test seam for read status, nil scope, and chapter bounds.

Parameters

[in]

ctx

Validation state with canonical stylesheet geometry.

Returns

Stylesheet-table validation status.

Return values

k_ra8_ok	Every source and optional scope is valid.
k_ra8_err_invalid_arg	One source or scope is invalid.

Precondition

ctx and its callback are valid.

Header layout bounds every stylesheet record.

Postcondition

No state is modified.

Success proves each stylesheet reference safe.

Note

Private MC/DC seam; iteration is stylesheet-count bounded.

Since

Version 0.1.0

Definition at line 398 of file book_stream.c.

References book_header_t::chapter_count, stream_validate_t::hdr, internal_book_stream_le32(), k_book_nil, k_book_sizeof_stylesheet, k_ra8_err_invalid_arg, k_ra8_ok, priv_book_stream_read(), priv_book_stream_string_ref(), RA8_PRIV, book_header_t::stylesheet_count, and book_header_t::stylesheet_off.

Referenced by internal_validate_body().

priv_book_stream_validate_text()

ra8_err_t priv_book_stream_validate_text	(	const stream_validate_t *	ctx,
		const uint8_t *	rec )

Validate one text node's element-only fields and string reference.

Private test seam for the four-condition text-node invariant.

Parameters

[in]	ctx	Validation state with a checked string envelope.
[in]	rec	One complete text-node wire record.

Returns

Text-node validation status.

Return values

k_ra8_ok	All element-only fields are empty or nil.
k_ra8_err_invalid_arg	One field or string reference is invalid.

Precondition

Both pointers address their documented extents.

rec has the text node kind.

Postcondition

No state is modified.

Success proves the text node owns no children or attributes.

Note

Private MC/DC seam; uses only caller-owned state.

Since

Version 0.1.0

Definition at line 242 of file book_stream.c.

References internal_book_stream_le16(), internal_book_stream_le32(), k_book_nil, k_ra8_err_invalid_arg, k_stream_node_attr_count, k_stream_node_first_attr, k_stream_node_first_child, k_stream_node_name, k_stream_node_text, priv_book_stream_string_ref(), and RA8_PRIV.

Referenced by internal_validate_one_node().