Private wire geometry for strict RABOOK1 stream validation. More...

#include "book_stream.h"
#include "ra8_attributes.h"

Include dependency graph for book_stream_internal.h:

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

Data Structures
struct	stream_validate_t
	Immutable validation state shared by the bounded table passes. More...

Enumerations
enum	stream_header_off_t : uint8_t { k_stream_hdr_version = 8U , k_stream_hdr_total = 12U , k_stream_hdr_flags = 16U , k_stream_hdr_title = 20U , k_stream_hdr_author = 24U , k_stream_hdr_language = 28U , k_stream_hdr_identifier = 32U , k_stream_hdr_cover = 36U , k_stream_hdr_chapter_count = 40U , k_stream_hdr_chapter_off = 44U , k_stream_hdr_node_count = 48U , k_stream_hdr_node_off = 52U , k_stream_hdr_attr_count = 56U , k_stream_hdr_attr_off = 60U , k_stream_hdr_style_count = 64U , k_stream_hdr_style_off = 68U , k_stream_hdr_image_count = 72U , k_stream_hdr_image_off = 76U , k_stream_hdr_string_off = 80U , k_stream_hdr_string_size = 84U , k_stream_hdr_pool_off = 88U , k_stream_hdr_pool_size = 92U , k_stream_hdr_crc = 96U }
	Wire offsets inside the fixed 100-byte RABOOK1 header. More...
enum	stream_node_off_t : uint8_t { k_stream_node_kind = 0U , k_stream_node_reserved = 1U , k_stream_node_attr_count = 2U , k_stream_node_name = 4U , k_stream_node_text = 8U , k_stream_node_first_attr = 12U , k_stream_node_first_child = 16U , k_stream_node_next_sibling = 20U }
	Wire offsets inside a 24-byte DOM node record. More...
enum	stream_image_off_t : uint8_t { k_stream_image_id = 0U , k_stream_image_width = 4U , k_stream_image_height = 6U , k_stream_image_format = 8U , k_stream_image_pixfmt = 9U , k_stream_image_reserved = 10U , k_stream_image_data_off = 12U , k_stream_image_data_size = 16U , k_stream_image_raw_size = 20U }
	Wire offsets inside a 24-byte image descriptor. More...
enum	stream_bit_t : uint8_t { k_stream_bits_per_byte = 8U , k_stream_mark_round = 7U , k_stream_le_shift_3 = 24U }
	Bit geometry shared by wire decoding and the node ownership map. More...

Functions
static uint16_t	internal_book_stream_le16 (const uint8_t *p)
	Decode one little-endian 16-bit field from unaligned bytes.
static uint32_t	internal_book_stream_le32 (const uint8_t *p)
	Decode one little-endian 32-bit field from unaligned bytes.
ra8_err_t	priv_book_stream_read_validate_header (stream_validate_t *ctx)
	Read, decode, and validate the canonical stream header and layout.
ra8_err_t	priv_book_stream_string_ref (const stream_validate_t *ctx, uint32_t off)
	Require a referenced offset to name an interned-string boundary.
ra8_err_t	priv_book_stream_nonempty_string_ref (const stream_validate_t *ctx, uint32_t off)
	Require a string reference to name a non-empty interned string.
ra8_err_t	priv_book_stream_read (const stream_validate_t ctx, uint64_t off, uint8_t dst, uint32_t len)
	Read one exact, bounded source span.
ra8_err_t	priv_book_stream_validate_string_envelope (const stream_validate_t *ctx)
	Validate the string pool's leading and trailing NUL sentinels.
ra8_err_t	priv_book_stream_validate_metadata (const stream_validate_t *ctx)
	Validate metadata string references and the optional cover index.
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.
ra8_err_t	priv_book_stream_validate_styles (const stream_validate_t *ctx)
	Validate every stylesheet source and optional chapter scope.

Detailed Description

Private wire geometry for strict RABOOK1 stream validation.

Centralizes fixed wire offsets, bit geometry, and the bounded caller-owned validation state used only by the stream validator implementation.

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

Since: Version 0.1.0

Definition in file book_stream_internal.h.

Enumeration Type Documentation

◆ stream_bit_t

enum stream_bit_t : uint8_t

Bit geometry shared by wire decoding and the node ownership map.

Enumerator
k_stream_bits_per_byte	Bits represented by one byte.
k_stream_mark_round	Ceiling-division numerator bias.
k_stream_le_shift_3	Shift of byte three in a uint32.

Definition at line 71 of file book_stream_internal.h.

◆ stream_header_off_t

enum stream_header_off_t : uint8_t

Wire offsets inside the fixed 100-byte RABOOK1 header.

Enumerator
k_stream_hdr_version	Format-version field byte offset.
k_stream_hdr_total	Total-size field byte offset.
k_stream_hdr_flags	Feature-flags field byte offset.
k_stream_hdr_title	Title string-offset field.
k_stream_hdr_author	Author string-offset field.
k_stream_hdr_language	Language string-offset field.
k_stream_hdr_identifier	Identifier string-offset field.
k_stream_hdr_cover	Cover-image index field.
k_stream_hdr_chapter_count	Chapter-table count field.
k_stream_hdr_chapter_off	Chapter-table byte offset.
k_stream_hdr_node_count	DOM-node table count field.
k_stream_hdr_node_off	DOM-node table byte offset.
k_stream_hdr_attr_count	Attribute-table count field.
k_stream_hdr_attr_off	Attribute-table byte offset.
k_stream_hdr_style_count	Stylesheet-table count field.
k_stream_hdr_style_off	Stylesheet-table byte offset.
k_stream_hdr_image_count	Image-table count field.
k_stream_hdr_image_off	Image-table byte offset.
k_stream_hdr_string_off	Interned-string pool offset.
k_stream_hdr_string_size	Interned-string pool size.
k_stream_hdr_pool_off	Image-payload pool offset.
k_stream_hdr_pool_size	Image-payload pool size.
k_stream_hdr_crc	Body CRC-32 field byte offset.

Definition at line 19 of file book_stream_internal.h.

◆ stream_image_off_t

enum stream_image_off_t : uint8_t

Wire offsets inside a 24-byte image descriptor.

Enumerator
k_stream_image_id	Image-id string offset.
k_stream_image_width	Raster-width field offset.
k_stream_image_height	Raster-height field offset.
k_stream_image_format	Image-kind byte offset.
k_stream_image_pixfmt	Raster pixel-format offset.
k_stream_image_reserved	Reserved-zero field offset.
k_stream_image_data_off	Payload-relative offset field.
k_stream_image_data_size	Stored payload-size field.
k_stream_image_raw_size	Decoded payload-size field.

Definition at line 58 of file book_stream_internal.h.

◆ stream_node_off_t

enum stream_node_off_t : uint8_t

Wire offsets inside a 24-byte DOM node record.

Enumerator
k_stream_node_kind	Node-kind byte offset.
k_stream_node_reserved	Reserved-zero byte offset.
k_stream_node_attr_count	Attribute-count field offset.
k_stream_node_name	Element-name string offset.
k_stream_node_text	Text string-offset field.
k_stream_node_first_attr	First-attribute index field.
k_stream_node_first_child	First-child node index field.
k_stream_node_next_sibling	Next-sibling node index field.

Definition at line 46 of file book_stream_internal.h.

Function Documentation

◆ internal_book_stream_le16()

uint16_t internal_book_stream_le16 ( const uint8_t * p )

inlinestatic

Decode one little-endian 16-bit field from unaligned bytes.

Combines two octets explicitly so behavior is independent of host byte order and does not require an aligned integer load.

Parameters

[in] p Readable two-byte wire field.

Returns: Host-order unsigned field value.

Return values

UINT16_C(0)	Both wire bytes are zero.
UINT16_MAX	Both wire bytes are 0xff.

Precondition: p addresses at least two readable bytes.; The source bytes remain stable for the duration of the two reads.

Postcondition: No memory or external state is modified.; The result is exactly p[0] | (p[1] << 8).

Note: Pure and thread-safe for immutable input.

Since: Version 0.1.0

Definition at line 92 of file book_stream_internal.h.

References k_stream_bits_per_byte, and RA8_INTERNAL.

Referenced by internal_validate_images(), internal_validate_raster(), internal_validate_svg(), priv_book_stream_validate_element(), and priv_book_stream_validate_text().

◆ internal_book_stream_le32()

uint32_t internal_book_stream_le32 ( const uint8_t * p )

inlinestatic

Decode one little-endian 32-bit field from unaligned bytes.

Combines four octets explicitly so behavior is independent of host byte order and does not require an aligned integer load.

Parameters

[in] p Readable four-byte wire field.

Returns: Host-order unsigned field value.

Return values

UINT32_C(0)	All four wire bytes are zero.
UINT32_MAX	All four wire bytes are 0xff.

Precondition: p addresses at least four readable bytes.; The source bytes remain stable for the duration of the four reads.

Postcondition: No memory or external state is modified.; The result is the exact canonical little-endian decoding.

Note: Pure and thread-safe for immutable input.

Since: Version 0.1.0

Definition at line 112 of file book_stream_internal.h.

References k_stream_bits_per_byte, k_stream_le_shift_3, and RA8_INTERNAL.

Referenced by internal_decode_header(), internal_validate_attrs(), internal_validate_chapters(), internal_validate_images(), internal_validate_one_node(), internal_validate_raster(), internal_validate_svg(), priv_book_stream_validate_element(), priv_book_stream_validate_styles(), and priv_book_stream_validate_text().

◆ priv_book_stream_nonempty_string_ref()

ra8_err_t priv_book_stream_nonempty_string_ref	(	const stream_validate_t *	ctx,
		uint32_t	off )

Require a string reference to name a non-empty interned string.

Proves the offset is a string boundary and rejects a NUL first byte.

Parameters

[in]	ctx	Validation state with canonical string-pool geometry.
[in]	off	Offset relative to the string pool.

Returns: Non-empty string-boundary validation status.

Return values

k_ra8_ok	The reference begins with a non-NUL byte.
k_ra8_err_invalid_arg	The reference is invalid or names an empty string.

Precondition: ctx and its exact-read callback are valid.; The string-pool envelope lies within the validated source layout.

Postcondition: No state is modified.; Success proves at least one non-NUL byte follows the boundary.

Note: Private translation-unit seam; performs at most two byte reads.

Since: Version 0.1.0

Definition at line 231 of file book_stream_wire.c.

References stream_validate_t::hdr, k_ra8_err_invalid_arg, k_ra8_ok, priv_book_stream_read(), priv_book_stream_string_ref(), RA8_PRIV, and book_header_t::string_off.

Referenced by internal_validate_attrs(), internal_validate_chapters(), internal_validate_images(), and priv_book_stream_validate_element().

◆ priv_book_stream_read()

ra8_err_t priv_book_stream_read	(	const stream_validate_t *	ctx,
		uint64_t	off,
		uint8_t *	dst,
		uint32_t	len )

Read one exact, bounded source span.

Private test seam for the overflow-safe source-range guard used by every streamed validation pass.

Parameters

[in]	ctx	Validation source.
[in]	off	Source byte offset.
[out]	dst	Destination buffer.
[in]	len	Exact byte count.

Returns: Callback status or invalid-size for an out-of-range span.

Return values

k_ra8_ok	The callback supplied the requested bytes.
k_ra8_err_invalid_size	The offset or length exceeds the source.

Precondition: All pointers are non-NULL and dst holds len bytes.; The callback obeys the exact-read contract.

Postcondition: Rejected spans do not invoke the callback.; Success fills exactly len bytes.

Note: Private MC/DC seam; performs no allocation.

Since: Version 0.1.0

Definition at line 20 of file book_stream_wire.c.

References k_ra8_err_invalid_size, RA8_PRIV, stream_validate_t::read, stream_validate_t::read_ctx, and stream_validate_t::source_size.

Referenced by internal_validate_attrs(), internal_validate_chapters(), internal_validate_crc(), internal_validate_images(), internal_validate_nodes(), priv_book_stream_nonempty_string_ref(), priv_book_stream_read_validate_header(), priv_book_stream_string_ref(), priv_book_stream_validate_string_envelope(), and priv_book_stream_validate_styles().

◆ priv_book_stream_read_validate_header()

ra8_err_t priv_book_stream_read_validate_header ( stream_validate_t * ctx )

Read, decode, and validate the canonical stream header and layout.

Reads the fixed wire header, decodes every little-endian field, and proves that all following tables and pools form one gap-free span.

Parameters

[in,out] ctx Validation state whose header receives decoded fields.

Returns: Header read and layout-validation status.

Return values

k_ra8_ok	The header and complete source layout are canonical.
k_ra8_err_invalid_arg	A magic, version, or feature invariant fails.
k_ra8_err_invalid_size	A source, scratch, table, or pool extent fails.

Precondition: ctx and its exact-read callback are valid.; ctx->source_size is at least the fixed wire-header length.

Postcondition: Success leaves ctx->hdr fully decoded and layout-validated.; Failure does not read outside the advertised source extent.

Note: Private translation-unit seam; performs no allocation.

Since: Version 0.1.0

Definition at line 203 of file book_stream_wire.c.

References stream_validate_t::hdr, internal_decode_header(), internal_validate_header_layout(), k_book_sizeof_header, k_ra8_ok, priv_book_stream_read(), and RA8_PRIV.

Referenced by internal_validate_body().

◆ priv_book_stream_string_ref()

ra8_err_t priv_book_stream_string_ref	(	const stream_validate_t *	ctx,
		uint32_t	off )

Require a referenced offset to name an interned-string boundary.

Accepts the empty-string sentinel at zero; every other offset must be in range and immediately preceded by a NUL terminator.

Parameters

[in]	ctx	Validation state with canonical string-pool geometry.
[in]	off	Offset relative to the string pool.

Returns: String-boundary validation status.

Return values

k_ra8_ok	`off` names the sentinel or a valid string boundary.
k_ra8_err_invalid_arg	The offset is outside the pool or mid-string.

Precondition: ctx and its exact-read callback are valid.; The string-pool envelope lies within the validated source layout.

Postcondition: No state is modified.; Success permits reads beginning at the referenced offset.

Note: Private translation-unit seam; performs at most one byte read.

Since: Version 0.1.0

Definition at line 214 of file book_stream_wire.c.

References stream_validate_t::hdr, k_ra8_err_invalid_arg, k_ra8_ok, priv_book_stream_read(), RA8_PRIV, book_header_t::string_off, and book_header_t::string_size.

Referenced by internal_validate_attrs(), internal_validate_chapters(), priv_book_stream_nonempty_string_ref(), priv_book_stream_validate_metadata(), priv_book_stream_validate_styles(), and priv_book_stream_validate_text().

◆ 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_string_envelope()

ra8_err_t priv_book_stream_validate_string_envelope ( const stream_validate_t * ctx )

Validate the string pool's leading and trailing NUL sentinels.

Private test seam for the read-status and two boundary-byte conditions used before any string reference is accepted.

Parameters

[in] ctx Validation state with canonical string-pool geometry.

Returns: String-envelope validation status.

Return values

k_ra8_ok	Both sentinel bytes are NUL.
k_ra8_err_invalid_size	The pool is empty or unreadable.
k_ra8_err_invalid_arg	One sentinel byte is non-NUL.

Precondition: ctx and its read callback are valid.; The advertised string-pool extent lies within the source.

Postcondition: No source or validation state is modified.; Success establishes both string-pool sentinels.

Note: Private MC/DC seam; performs at most two reads.

Since: Version 0.1.0

Definition at line 244 of file book_stream_wire.c.

References stream_validate_t::hdr, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, priv_book_stream_read(), RA8_PRIV, book_header_t::string_off, and book_header_t::string_size.

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

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ stream_bit_t

◆ stream_header_off_t

◆ stream_image_off_t

◆ stream_node_off_t

Function Documentation

◆ internal_book_stream_le16()

◆ internal_book_stream_le32()

◆ priv_book_stream_nonempty_string_ref()

◆ priv_book_stream_read()

◆ priv_book_stream_read_validate_header()

◆ priv_book_stream_string_ref()

◆ priv_book_stream_validate_element()

◆ priv_book_stream_validate_metadata()

◆ priv_book_stream_validate_string_envelope()

◆ priv_book_stream_validate_styles()

◆ priv_book_stream_validate_text()