book_stream_wire.c File Reference

Wire decoding and canonical layout validation for streamed books. More...

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

Include dependency graph for book_stream_wire.c:

Go to the source code of this file.

Functions
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.
static void	internal_decode_header (const uint8_t *raw, book_header_t *hdr)
	Decode the fixed header from canonical little-endian wire bytes.
static ra8_err_t	internal_layout_segment (uint32_t off, uint32_t count, uint32_t elem, uint64_t *cursor)
	Require one segment to begin at the canonical cursor and advance it.
static ra8_err_t	internal_validate_header_fields (const stream_validate_t *ctx)
	Validate decoded header fields before walking the table layout.
static ra8_err_t	internal_validate_header_layout (const stream_validate_t *ctx)
	Validate version, flags, exact source length, and canonical layout.
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_validate_string_envelope (const stream_validate_t *ctx)
	Validate the string pool's leading and trailing NUL sentinels.

Detailed Description

Wire decoding and canonical layout validation for streamed books.

Owns the exact-read guard, fixed-header decoding, gap-free table geometry, and interned-string boundary checks used by the semantic stream passes. Keeping wire concerns here leaves book_stream.c responsible for coordinating the chapter, DOM, attribute, stylesheet, image, and integrity validators.

Copyright

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

Since

Version 0.1.0

Definition in file book_stream_wire.c.

Function Documentation

internal_decode_header()

void internal_decode_header ( const uint8_t * raw, book_header_t * hdr )

static

Decode the fixed header from canonical little-endian wire bytes.

Copies the byte magic and decodes every scalar field explicitly; no packed-structure alias or host-endian assumption is used.

Parameters

[in]	raw	Header wire bytes.
[out]	hdr	Decoded host-order header.

Precondition

raw holds exactly k_book_sizeof_header bytes.

hdr addresses one writable header object disjoint from raw.

Postcondition

Every header field is populated.

Bytes outside hdr are not modified.

Note

Pure and thread-safe.

Since

Version 0.1.0

Definition at line 44 of file book_stream_wire.c.

References book_header_t::attr_count, book_header_t::attr_off, book_header_t::author_off, book_header_t::chapter_count, book_header_t::chapter_off, book_header_t::cover_image_index, book_header_t::crc32_val, book_header_t::flags, book_header_t::format_version, book_header_t::identifier_off, book_header_t::image_count, book_header_t::image_off, book_header_t::image_pool_off, book_header_t::image_pool_size, internal_book_stream_le32(), k_stream_hdr_attr_count, k_stream_hdr_attr_off, k_stream_hdr_author, k_stream_hdr_chapter_count, k_stream_hdr_chapter_off, k_stream_hdr_cover, k_stream_hdr_crc, k_stream_hdr_flags, k_stream_hdr_identifier, k_stream_hdr_image_count, k_stream_hdr_image_off, k_stream_hdr_language, k_stream_hdr_node_count, k_stream_hdr_node_off, k_stream_hdr_pool_off, k_stream_hdr_pool_size, k_stream_hdr_string_off, k_stream_hdr_string_size, k_stream_hdr_style_count, k_stream_hdr_style_off, k_stream_hdr_title, k_stream_hdr_total, k_stream_hdr_version, book_header_t::language_off, book_header_t::magic, memcpy(), book_header_t::node_count, book_header_t::node_off, RA8_INTERNAL, book_header_t::string_off, book_header_t::string_size, book_header_t::stylesheet_count, book_header_t::stylesheet_off, book_header_t::title_off, and book_header_t::total_size.

Referenced by priv_book_stream_read_validate_header().

internal_layout_segment()

ra8_err_t internal_layout_segment ( uint32_t off, uint32_t count, uint32_t elem, uint64_t * cursor )

static

Require one segment to begin at the canonical cursor and advance it.

Enforces gap-free table layout and performs the count-by-element product in 64 bits before accepting a 32-bit wire offset.

Parameters

[in]	off	Stored segment offset.
[in]	count	Number of records or bytes.
[in]	elem	Wire bytes per record.
[in,out]	cursor	Expected start and resulting end.

Returns

k_ra8_ok, or invalid-size for a gap, overlap, or 32-bit overflow.

Return values

k_ra8_ok	The segment begins at the cursor and its end is representable.
k_ra8_err_invalid_size	The offset differs or the end exceeds UINT32_MAX.

Precondition

cursor is non-NULL.

cursor contains the validated end of the preceding segment.

Postcondition

Success advances cursor by count times elem.

Failure leaves cursor unchanged unless the start already matched.

Note

Pure except for cursor.

Since

Version 0.1.0

Definition at line 92 of file book_stream_wire.c.

References k_ra8_err_invalid_size, and k_ra8_ok.

Referenced by internal_validate_header_layout().

internal_validate_header_fields()

ra8_err_t internal_validate_header_fields ( const stream_validate_t * ctx )

static

Validate decoded header fields before walking the table layout.

Checks magic, supported features, exact source length, and scratch ownership-map capacity without reading any table data.

Parameters

[in]

ctx

State containing a decoded header.

Returns

Strict decoded-header validation status.

Return values

k_ra8_ok	The decoded header fields are supported and bounded.
k_ra8_err_invalid_arg	Magic, version, or feature bits are invalid.
k_ra8_err_invalid_size	Source or scratch geometry is invalid.

Precondition

ctx is non-NULL and its header is decoded.

ctx->source_size and scratch capacity describe accessible storage.

Postcondition

No state is modified.

Success permits validation of the canonical segment layout.

Note

Pure and thread-safe.

Since

Version 0.1.0

Definition at line 121 of file book_stream_wire.c.

References book_header_t::flags, book_header_t::format_version, stream_validate_t::hdr, k_book_flag_mask_known, k_book_format_version, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_stream_bits_per_byte, k_stream_mark_round, book_header_t::magic, book_header_t::node_count, RA8_INTERNAL, stream_validate_t::scratch_cap, stream_validate_t::source_size, and book_header_t::total_size.

Referenced by internal_validate_header_layout().

internal_validate_header_layout()

ra8_err_t internal_validate_header_layout ( const stream_validate_t * ctx )

static

Validate version, flags, exact source length, and canonical layout.

Validates the decoded fields, then walks every table and pool in canonical wire order.

Parameters

[in]

ctx

State containing a decoded header.

Returns

Strict header/layout validation status.

Return values

k_ra8_ok	The header and all segment extents are canonical.
k_ra8_err_invalid_arg	Magic, version, or feature bits are invalid.
k_ra8_err_invalid_size	Source, scratch, or segment geometry is invalid.

Precondition

ctx is non-NULL and its header is decoded.

ctx->source_size and scratch capacity describe accessible storage.

Postcondition

No state is modified.

Success proves every later table and pool read is within the source.

Note

Pure and thread-safe.

Since

Version 0.1.0

Definition at line 157 of file book_stream_wire.c.

References book_header_t::attr_count, book_header_t::attr_off, book_header_t::chapter_count, book_header_t::chapter_off, stream_validate_t::hdr, book_header_t::image_count, book_header_t::image_off, book_header_t::image_pool_off, book_header_t::image_pool_size, internal_layout_segment(), internal_validate_header_fields(), k_book_sizeof_attr, k_book_sizeof_chapter, k_book_sizeof_header, k_book_sizeof_image, k_book_sizeof_node, k_book_sizeof_stylesheet, k_ra8_err_invalid_size, k_ra8_ok, book_header_t::node_count, book_header_t::node_off, RA8_INTERNAL, book_header_t::string_off, book_header_t::string_size, book_header_t::stylesheet_count, book_header_t::stylesheet_off, and book_header_t::total_size.

Referenced by priv_book_stream_read_validate_header().

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