ra8_fmt_stream_rabook.c File Reference

Strict callback-driven RBKC and RABOOK1 inspection. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "book_chunked.h"
#include "miniz.h"
#include "ra8_attributes.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_stream_rabook.c:

Go to the source code of this file.

Data Structures
struct	source_adapter_t
	Positioned-source binding for the exact book-reader callback. More...

Enumerations
enum	report_constant_t : uint32_t {   k_report_radix = 10U ,   k_report_digits = 20U ,   k_report_rows = 4096U ,   k_report_idx_width = 5U ,   k_report_num_width = 10U }
	Bounded report formatting constants. More...

Functions
static ra8_err_t	internal_text (const ra8_fmt_sink_t *report, const char *text)
	Append one NUL-terminated literal to the report sink.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *report, uint64_t value, uint32_t width)
	Render one unsigned value with optional left padding.
static ra8_err_t	internal_field (const ra8_fmt_sink_t *report, const char *label, uint64_t value)
	Emit a labelled unsigned field and its terminating newline.
static ra8_err_t	internal_exact_read (void *opaque, uint64_t offset, uint8_t *bytes, uint32_t len)
	Adapt legal short positioned reads to one exact book read.
static ra8_err_t	internal_inflate (const void *src, size_t src_len, void *dst, size_t dst_cap, size_t *out_len)
	Inflate one RFC 1950 stream through miniz caller storage.
static ra8_err_t	internal_header (const ra8_fmt_sink_t *report, const ra8_fmt_source_t *source, const book_chunked_t *reader)
	Emit the established RBKC header block.
static ra8_err_t	internal_row (const ra8_fmt_sink_t *report, uint32_t idx, uint64_t begin, uint64_t end)
	Emit one established-width chunk inventory row.
static ra8_err_t	internal_table (const ra8_fmt_sink_t *report, const book_chunked_t *reader, bool verbose)
	Emit the bounded chunk inventory when verbose output is enabled.
static ra8_err_t	internal_report (const ra8_fmt_sink_t *report, const ra8_fmt_source_t *source, const book_chunked_t *reader, bool verbose)
	Emit a validated header, optional inventory, and stable verdict.
ra8_err_t	ra8_fmt_rabook_inspect_stream (const ra8_fmt_source_t *source, bool verbose, ra8_fmt_rabook_inspect_workspace_t *workspace, const ra8_fmt_sink_t *report)
	Strictly inspect one streamed RBKC container and its RABOOK1 payload.

Detailed Description

Strict callback-driven RBKC and RABOOK1 inspection.

Opens the container through positioned reads, validates every zlib stream and the complete inner book, then emits the established inventory.

Copyright

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

Since

0.1.0

Definition in file ra8_fmt_stream_rabook.c.

Enumeration Type Documentation

report_constant_t

enum report_constant_t : uint32_t

Bounded report formatting constants.

Enumerator
k_report_radix	Decimal digit radix.
k_report_digits	Digits required for uint64_t.
k_report_rows	Maximum verbose inventory rows.
k_report_idx_width	Legacy entry-column width.
k_report_num_width	Legacy byte-column width.

Definition at line 21 of file ra8_fmt_stream_rabook.c.

Function Documentation

internal_exact_read()

ra8_err_t internal_exact_read ( void * opaque, uint64_t offset, uint8_t * bytes, uint32_t len )

static

Adapt legal short positioned reads to one exact book read.

Bounds the complete requested range, then loops over positive short reads until the strict book-reader contract is satisfied.

Parameters

[in,out]	opaque	Bound source_adapter_t context.
[in]	offset	Absolute container byte offset.
[out]	bytes	Destination for exactly len bytes.
[in]	len	Exact requested byte count.

Returns

Source or range status.

Return values

k_ra8_ok	Exactly len bytes were copied.
k_ra8_err_invalid_size	The range exceeds the captured source.

Precondition

opaque resolves to a live immutable source.

bytes spans len bytes when len is nonzero.

Postcondition

Success initializes the complete destination span.

Source position and adapter binding remain unchanged.

Note

Supports injected sources that legally return short positive reads.

Since

0.1.0

Definition at line 140 of file ra8_fmt_stream_rabook.c.

References ra8_fmt_source_t::ctx, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_source_t::size, and source_adapter_t::source.

Referenced by ra8_fmt_rabook_inspect_stream().

internal_field()

ra8_err_t internal_field ( const ra8_fmt_sink_t * report, const char * label, uint64_t value )

static

Emit a labelled unsigned field and its terminating newline.

Writes the label, decimal value, and line ending fail-fast.

Parameters

[in]	report	Bound injected text sink.
[in]	label	NUL-terminated field label.
[in]	value	Unsigned value to render.

Returns

Sink status.

Return values

k_ra8_ok	The complete field line was accepted.
other	The first rejected sink span stopped output.

Precondition

report and its callback are non-null.

label is non-null and NUL-terminated.

Postcondition

Success emits exactly one complete field line.

Input values and sink binding remain unchanged.

Note

Thread safety inherits the injected sink.

Since

0.1.0

Definition at line 112 of file ra8_fmt_stream_rabook.c.

References internal_text(), internal_u64(), and k_ra8_ok.

Referenced by internal_header().

internal_header()

ra8_err_t internal_header ( const ra8_fmt_sink_t * report, const ra8_fmt_source_t * source, const book_chunked_t * reader )

static

Emit the established RBKC header block.

Preserves the original field labels and ordering for compatible CLI output after the strict reader has accepted the container.

Parameters

[in]	report	Bound injected text sink.
[in]	source	Validated immutable container source.
[in]	reader	Open strict chunk reader.

Returns

Sink status.

Return values

k_ra8_ok	The complete header block was accepted.
other	The first rejected sink span stopped output.

Precondition

All three arguments are non-null and remain live.

reader describes source after a successful open.

Postcondition

Success emits five labelled container fields.

Source and reader state remain unchanged.

Note

The reserved field is emitted as zero because open rejects otherwise.

Since

0.1.0

Definition at line 222 of file ra8_fmt_stream_rabook.c.

References book_chunked_t::chunk_bytes, book_chunked_t::chunk_count, book_chunked_t::inflated_total, internal_field(), internal_text(), internal_u64(), k_ra8_ok, and ra8_fmt_source_t::size.

Referenced by internal_report().

internal_inflate()

ra8_err_t internal_inflate ( const void * src, size_t src_len, void * dst, size_t dst_cap, size_t * out_len )

static

Inflate one RFC 1950 stream through miniz caller storage.

Parses the zlib wrapper and requires a non-wrapping output buffer.

Parameters

[in]	src	Complete compressed stream bytes.
[in]	src_len	Compressed byte length.
[out]	dst	Caller-owned inflated destination.
[in]	dst_cap	Destination byte capacity.
[out]	out_len	Receives the inflated byte length.

Returns

Decompression status.

Return values

k_ra8_ok	One complete stream was inflated.
k_ra8_err_validation_failed	The stream was malformed or oversized.

Precondition

Input and output spans are non-null and disjoint.

out_len is non-null and writable.

Postcondition

Success initializes out_len and its destination prefix.

Failure does not publish a usable output length.

Note

All decompressor state is bounded local or caller storage.

Since

0.1.0

Definition at line 186 of file ra8_fmt_stream_rabook.c.

References k_ra8_err_null_ptr, k_ra8_err_validation_failed, and k_ra8_ok.

internal_report()

ra8_err_t internal_report ( const ra8_fmt_sink_t * report, const ra8_fmt_source_t * source, const book_chunked_t * reader, bool verbose )

static

Emit a validated header, optional inventory, and stable verdict.

Sequences the established report sections fail-fast after strict outer and inner validation has completed.

Parameters

[in]	report	Bound injected text sink.
[in]	source	Validated immutable container source.
[in]	reader	Open validated chunk reader.
[in]	verbose	Whether to include the bounded chunk inventory.

Returns

Sink status.

Return values

k_ra8_ok	The complete requested report was accepted.
other	The first rejected sink span stopped output.

Precondition

All pointer arguments are non-null and remain live.

Outer streams and the inner book already passed strict validation.

Postcondition

Success ends with the established valid verdict line.

No source, reader, or workspace byte changes.

Note

Reporting occurs only after source stability revalidation.

Since

0.1.0

Definition at line 338 of file ra8_fmt_stream_rabook.c.

References internal_header(), internal_table(), internal_text(), and k_ra8_ok.

Referenced by ra8_fmt_rabook_inspect_stream().

internal_row()

ra8_err_t internal_row ( const ra8_fmt_sink_t * report, uint32_t idx, uint64_t begin, uint64_t end )

static

Emit one established-width chunk inventory row.

Renders index, absolute start, absolute end, and compressed length with the column widths used by the prior inspector.

Parameters

[in]	report	Bound injected text sink.
[in]	idx	Zero-based chunk index.
[in]	begin	Absolute compressed-stream start.
[in]	end	Absolute exclusive compressed-stream end.

Returns

Sink status.

Return values

k_ra8_ok	The complete row was accepted.
other	The first rejected sink span stopped output.

Precondition

report and its callback are non-null.

end is not less than begin.

Postcondition

Success emits one newline-terminated row.

Numeric inputs and sink binding remain unchanged.

Note

Values wider than their minimum columns are never truncated.

Since

0.1.0

Definition at line 265 of file ra8_fmt_stream_rabook.c.

References internal_text(), internal_u64(), k_ra8_ok, k_report_idx_width, and k_report_num_width.

Referenced by internal_table().

internal_table()

ra8_err_t internal_table ( const ra8_fmt_sink_t * report, const book_chunked_t * reader, bool verbose )

static

Emit the bounded chunk inventory when verbose output is enabled.

Walks validated table entries and reports at most 4096 rows.

Parameters

[in]	report	Bound injected text sink.
[in]	reader	Open validated chunk reader.
[in]	verbose	Whether inventory output is enabled.

Returns

Sink status.

Return values

k_ra8_ok	Output was disabled or every selected row was accepted.
other	The first rejected sink span stopped output.

Precondition

report and reader are non-null.

Reader table covers chunk_count + 1 validated entries.

Postcondition

Nonverbose success emits no bytes.

Verbose success emits a header and the bounded row prefix.

Note

Table traversal is bounded independently of hostile input size.

Since

0.1.0

Definition at line 301 of file ra8_fmt_stream_rabook.c.

References book_chunked_t::chunk_count, internal_row(), internal_text(), k_ra8_ok, k_report_rows, book_chunked_t::payload_off, and book_chunked_t::table.

Referenced by internal_report().

internal_text()

ra8_err_t internal_text ( const ra8_fmt_sink_t * report, const char * text )

static

Append one NUL-terminated literal to the report sink.

Measures the literal once and delegates its exact payload span.

Parameters

[in]	report	Bound injected text sink.
[in]	text	NUL-terminated source text.

Returns

Sink status.

Return values

k_ra8_ok	The complete literal was accepted.
other	The injected sink rejected the span.

Precondition

report and its callback are non-null.

text is non-null and NUL-terminated.

Postcondition

Exactly the bytes before NUL were offered once.

Source text and sink binding remain unchanged.

Note

Thread safety inherits the injected sink.

Since

0.1.0

Definition at line 50 of file ra8_fmt_stream_rabook.c.

References strlen().

Referenced by internal_field(), internal_header(), internal_report(), internal_row(), internal_table(), internal_u64(), and ra8_fmt_rabook_inspect_stream().

internal_u64()

ra8_err_t internal_u64 ( const ra8_fmt_sink_t * report, uint64_t value, uint32_t width )

static

Render one unsigned value with optional left padding.

Converts through fixed local buffers and emits spaces before digits when the requested field is wider than the decimal spelling.

Parameters

[in]	report	Bound injected text sink.
[in]	value	Unsigned value to render.
[in]	width	Minimum output field width.

Returns

Sink status.

Return values

k_ra8_ok	Every padding and digit byte was accepted.
other	The injected sink rejected a span.

Precondition

report and its callback are non-null.

The fixed digit buffer covers every uint64_t value.

Postcondition

Success emits exactly max(width, digit_count) bytes.

No locale, source, or global state changes.

Note

Thread safety inherits the injected sink.

Since

0.1.0

Definition at line 73 of file ra8_fmt_stream_rabook.c.

References internal_text(), k_ra8_ok, k_report_digits, and k_report_radix.

Referenced by internal_field(), internal_header(), and internal_row().

ra8_fmt_rabook_inspect_stream()

ra8_err_t ra8_fmt_rabook_inspect_stream ( const ra8_fmt_source_t * source, bool verbose, ra8_fmt_rabook_inspect_workspace_t * workspace, const ra8_fmt_sink_t * report )

nodiscard

Strictly inspect one streamed RBKC container and its RABOOK1 payload.

Parameters

[in]	source	Immutable positioned container source.
[in]	verbose	Emit the bounded chunk inventory.
[in,out]	workspace	Exact-or-larger table and validator buffers.
[in,out]	report	Human-readable injected text sink.

Returns

Container, decompression, inner-validation, or sink status.

Precondition

All workspace spans are disjoint and remain live for the call.

Postcondition

Every compressed stream and every inner reference has been validated on success; no source pointer or workspace pointer is retained.

Since

0.1.0

Definition at line 352 of file ra8_fmt_stream_rabook.c.

References book_chunked_open(), book_chunked_validate_strict(), ra8_fmt_rabook_inspect_workspace_t::chunk, ra8_fmt_rabook_inspect_workspace_t::chunk_cap, ra8_fmt_rabook_inspect_workspace_t::compressed, ra8_fmt_rabook_inspect_workspace_t::compressed_cap, ra8_fmt_source_t::ctx, internal_exact_read(), internal_inflate(), internal_report(), internal_text(), k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_rabook_inspect_workspace_t::scratch, ra8_fmt_rabook_inspect_workspace_t::scratch_cap, ra8_fmt_source_t::size, ra8_fmt_rabook_inspect_workspace_t::table, ra8_fmt_rabook_inspect_workspace_t::table_cap, and ra8_fmt_source_t::validate.

Referenced by internal_run_rabook().