Strict no-heap RBKC validation and reading through the RA8 VFS. More...

#include "mdl_rabook_vfs.h"
#include <stdint.h>
#include <string.h>
#include "book_chunked.h"
#include "ra8_attributes.h"
#include "ra8_io_vfs.h"

Include dependency graph for mdl_rabook_vfs.c:

Functions
static ra8_err_t	internal_rabook_read_exact (void opaque, uint64_t offset, uint8_t dst, uint32_t len)
	Read one exact random range through an already-open VFS stream.
static void	internal_rabook_clear_open (mdl_rabook_vfs_t *ctx)
	Clear all state derived from an opened artifact.
static ra8_err_t	internal_rabook_close (mdl_rabook_vfs_t *ctx)
	Close a possibly live facade and clear open-derived state.
static ra8_err_t	internal_rabook_open_reader (mdl_rabook_vfs_t ctx, const char path, uint64_t expected_size, bool enforce_size)
	Open and parse one exact-size RBKC container without strict payload validation.
static ra8_err_t	internal_rabook_validate_open (mdl_rabook_vfs_t ctx, book_header_t out_header)
	Strictly validate the complete inner flat blob of an open reader.
ra8_err_t	mdl_rabook_vfs_init (mdl_rabook_vfs_t ctx, const mdl_rabook_vfs_config_t config)
	Initialize one strict RBKC VFS workspace binding.
ra8_err_t	mdl_rabook_vfs_validate (void opaque, const char staging_path, uint64_t total_bytes, const uint8_t sha256[k_ra8_mdl_sha256_bytes])
	Strictly validate one closed private RBKC staging object.
ra8_err_t	mdl_rabook_vfs_open (mdl_rabook_vfs_t ctx, const char path)
	Open and strictly revalidate a published RBKC object for consumption.
ra8_err_t	mdl_rabook_vfs_read_chunk (mdl_rabook_vfs_t ctx, uint64_t offset, uint8_t dst, uint32_t len)
	Read one exact chunk-aligned flat-blob span from an open book.
ra8_err_t	mdl_rabook_vfs_info (const mdl_rabook_vfs_t ctx, book_header_t out_header, uint64_t *out_flat_size)
	Copy metadata from an open strictly validated book.
ra8_err_t	mdl_rabook_vfs_close (mdl_rabook_vfs_t *ctx)
	Close and release an open VFS reader facade.

Detailed Description

Strict no-heap RBKC validation and reading through the RA8 VFS.

Tag: [Ring 4 / PAL] {World: NS}

Opens staged or published RBKC data through the named VFS, performs strict streamed validation, and exposes bounded chunk reads to callers.

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

Definition in file mdl_rabook_vfs.c.

Function Documentation

◆ internal_rabook_clear_open()

void internal_rabook_clear_open ( mdl_rabook_vfs_t * ctx )

static

Clear all state derived from an opened artifact.

Resets only state authorized by an open operation; initialization bindings and transfer-validation evidence deliberately remain available.

Parameters

[in,out] ctx Initialized context with no live file facade.

Precondition: ctx is non-null and file was already released.; No callback or reader concurrently observes ctx.

Postcondition: Reader geometry, metadata, size, and open are reset.; Caller workspace bindings and transfer-validation evidence remain.

Note: Not thread-safe through one context.

Since: 0.1.0

Definition at line 91 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::file_size, mdl_rabook_vfs_t::header, mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::reader.

Referenced by internal_rabook_close().

◆ internal_rabook_close()

ra8_err_t internal_rabook_close ( mdl_rabook_vfs_t * ctx )

static

Close a possibly live facade and clear open-derived state.

Attempts the VFS close when needed, then clears open state on every result so a reported close failure cannot leave a usable reader facade.

Parameters

[in,out] ctx Initialized context.

Returns: VFS close status or success when already closed.

Return values

k_ra8_ok No facade was live or the facade closed successfully.

Precondition: No concurrent reader uses ctx.; ctx is non-null and was initialized by the public initializer.

Postcondition: file is null and open false on every path.; The VFS facade slot is released according to its close contract.

Note: Not thread-safe through one context.

Since: 0.1.0

Definition at line 115 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, internal_rabook_clear_open(), k_ra8_ok, and ra8_io_vfs_file_close().

Referenced by internal_rabook_open_reader(), mdl_rabook_vfs_close(), mdl_rabook_vfs_open(), and mdl_rabook_vfs_validate().

◆ internal_rabook_open_reader()

ra8_err_t internal_rabook_open_reader	(	mdl_rabook_vfs_t *	ctx,
		const char *	path,
		uint64_t	expected_size,
		bool	enforce_size )

static

Open and parse one exact-size RBKC container without strict payload validation.

Opens through the existing VFS, enforces the requested size policy, and binds RBKC geometry to the retained read-only facade.

Parameters

[in,out]	ctx	Initialized closed context.
[in]	path	Named VFS artifact path.
[in]	expected_size	Required container length when `enforce_size` is true.
[in]	enforce_size	Whether the observed length must match exactly.

Returns: Open, size, or RBKC-geometry status.

Return values

k_ra8_ok The exact-size policy and outer RBKC geometry passed.

Precondition: Required workspace bindings were validated at initialization.; ctx has no live file facade.

Postcondition: Success binds reader and retains one open file.; Failure releases any acquired facade and clears open-derived state.

Note: Strict inner validation is deliberately a separate ordered step.

Since: 0.1.0

Definition at line 145 of file mdl_rabook_vfs.c.

References book_chunked_open(), mdl_rabook_vfs_t::compressed, mdl_rabook_vfs_t::compressed_cap, mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::file_size, mdl_rabook_vfs_t::inflate_cb, internal_rabook_close(), internal_rabook_read_exact(), k_ra8_err_invalid_size, k_ra8_fs_mode_read, k_ra8_ok, ra8_io_vfs_file_open(), ra8_io_vfs_file_size(), mdl_rabook_vfs_t::reader, mdl_rabook_vfs_t::table, and mdl_rabook_vfs_t::table_cap.

Referenced by mdl_rabook_vfs_open(), and mdl_rabook_vfs_validate().

◆ internal_rabook_read_exact()

ra8_err_t internal_rabook_read_exact	(	void *	opaque,
		uint64_t	offset,
		uint8_t *	dst,
		uint32_t	len )

static

Read one exact random range through an already-open VFS stream.

Seeks once, then converts permitted VFS short reads into an exact callback contract while rejecting successful zero progress and over-report.

Parameters

[in,out]	opaque	Bound mdl_rabook_vfs_t.
[in]	offset	Absolute RBKC file offset.
[out]	dst	Destination for exactly `len` bytes.
[in]	len	Exact byte count.

Returns: VFS or exact-read status.

Return values

k_ra8_ok	The complete range was read.
k_ra8_err_invalid_state	The VFS stream is not open.
k_ra8_err_invalid_size	A successful read made zero progress.

Precondition: Public validation established every pointer and range.; The file remains immutable and open for the callback duration.

Postcondition: Success initializes all destination bytes.; Failure never reports a complete range.

Note: Not thread-safe through one context.

Since: 0.1.0

Definition at line 45 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_protocol_error, k_ra8_ok, ra8_io_vfs_file_read(), ra8_io_vfs_file_seek(), and RA8_LOOP_BOUND.

Referenced by internal_rabook_open_reader().

◆ internal_rabook_validate_open()

ra8_err_t internal_rabook_validate_open	(	mdl_rabook_vfs_t *	ctx,
		book_header_t *	out_header )

static

Strictly validate the complete inner flat blob of an open reader.

Delegates to the existing strict streamed validator with the same caller-owned chunk and semantic scratch workspaces bound at initialization.

Parameters

[in,out]	ctx	Open parsed RBKC context.
[out]	out_header	Separate output storage for decoded metadata.

Returns: Strict container/payload validation status.

Return values

k_ra8_ok Every chunk and the canonical inner RABOOK1 payload passed.

Precondition: Reader, callback, and workspaces are live and mutually non-overlapping.; out_header does not alias the context or any workspace.

Postcondition: Success initializes out_header completely.; Failure zeroes out_header according to the strict validator contract.

Note: Reads and inflates every RBKC chunk without retaining the flat book.

Since: 0.1.0

Definition at line 197 of file mdl_rabook_vfs.c.

References book_chunked_validate_strict(), mdl_rabook_vfs_t::chunk, mdl_rabook_vfs_t::chunk_cap, mdl_rabook_vfs_t::reader, mdl_rabook_vfs_t::scratch, and mdl_rabook_vfs_t::scratch_cap.

Referenced by mdl_rabook_vfs_open(), and mdl_rabook_vfs_validate().

◆ mdl_rabook_vfs_close()

ra8_err_t mdl_rabook_vfs_close ( mdl_rabook_vfs_t * ctx )

nodiscard

Close and release an open VFS reader facade.

Parameters

[in,out] ctx Initialized context.

Returns: VFS close status, or success when already closed.

Precondition: No concurrent read uses ctx.

Postcondition: The context retains no file handle even when close reports an error.

Note: Does not unmount storage or modify the published file.

Since: 0.1.0

Definition at line 368 of file mdl_rabook_vfs.c.

References internal_rabook_close(), and k_ra8_err_null_ptr.

Referenced by internal_consume().

◆ mdl_rabook_vfs_info()

ra8_err_t mdl_rabook_vfs_info	(	const mdl_rabook_vfs_t *	ctx,
		book_header_t *	out_header,
		uint64_t *	out_flat_size )

nodiscard

Copy metadata from an open strictly validated book.

Parameters

[in]	ctx	Open validated context.
[out]	out_header	Receives the decoded flat RABOOK1 header.
[out]	out_flat_size	Receives the inflated flat-blob length.

Returns: Query status.

Return values

k_ra8_ok	Both outputs were initialized.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_state	No validated reader is open.

Precondition: No concurrent operation mutates ctx.

Postcondition: The open reader and file position are unchanged.

Since: 0.1.0

Definition at line 346 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::header, book_chunked_t::inflated_total, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::reader.

Referenced by internal_consume().

◆ mdl_rabook_vfs_init()

ra8_err_t mdl_rabook_vfs_init	(	mdl_rabook_vfs_t *	ctx,
		const mdl_rabook_vfs_config_t *	config )

nodiscard

Initialize one strict RBKC VFS workspace binding.

Parameters

[out]	ctx	Caller-owned context.
[in]	config	Complete inflater and workspace descriptor.

Returns: Initialization status.

Return values

k_ra8_ok	The context is ready for validation or open.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_size	A workspace capacity is zero or table has fewer than two entries.

Precondition: No reader is open in ctx.

Postcondition: Success leaves ctx closed with no retained VFS facade.; Failure leaves ctx unchanged.

Note: Does not touch the VFS or inspect workspace contents.

Since: 0.1.0

Definition at line 207 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_config_t::chunk, mdl_rabook_vfs_config_t::chunk_cap, mdl_rabook_vfs_config_t::compressed, mdl_rabook_vfs_config_t::compressed_cap, mdl_rabook_vfs_config_t::inflate_cb, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, mdl_rabook_vfs_config_t::scratch, mdl_rabook_vfs_config_t::scratch_cap, mdl_rabook_vfs_config_t::table, and mdl_rabook_vfs_config_t::table_cap.

Referenced by internal_bind_transfer().

◆ mdl_rabook_vfs_open()

ra8_err_t mdl_rabook_vfs_open	(	mdl_rabook_vfs_t *	ctx,
		const char *	path )

nodiscard

Open and strictly revalidate a published RBKC object for consumption.

Parameters

[in,out]	ctx	Initialized closed context.
[in]	path	Named VFS path of the published .rabook.

Returns: Strict validation, VFS, or inflater status.

Return values

k_ra8_err_invalid_state A reader is already open.

Precondition: The selected mount remains registered until close.

Postcondition: Success retains one read-only VFS file and a strictly validated reader.; Failure retains no file facade and publishes no reader metadata.

Note: Revalidation prevents a stage-time verdict from authorizing changed bytes.

Since: 0.1.0

Definition at line 298 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::header, internal_rabook_close(), internal_rabook_open_reader(), internal_rabook_validate_open(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, and mdl_rabook_vfs_t::open.

Referenced by internal_consume().

◆ mdl_rabook_vfs_read_chunk()

ra8_err_t mdl_rabook_vfs_read_chunk	(	mdl_rabook_vfs_t *	ctx,
		uint64_t	offset,
		uint8_t *	dst,
		uint32_t	len )

nodiscard

Read one exact chunk-aligned flat-blob span from an open book.

Parameters

[in,out]	ctx	Open validated context.
[in]	offset	Chunk-aligned inflated-blob offset.
[out]	dst	Destination for exactly `len` bytes.
[in]	len	Exact inflated span for the selected chunk.

Returns: book_chunked_read status.

Precondition: mdl_rabook_vfs_open succeeded and the context remains exclusive.

Postcondition: Success initializes exactly len bytes in dst.

Since: 0.1.0

Definition at line 328 of file mdl_rabook_vfs.c.

References book_chunked_read(), mdl_rabook_vfs_t::file, k_ra8_err_invalid_state, k_ra8_err_null_ptr, mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::reader.

Referenced by internal_consume().

◆ mdl_rabook_vfs_validate()

ra8_err_t mdl_rabook_vfs_validate	(	void *	opaque,
		const char *	staging_path,
		uint64_t	total_bytes,
		const uint8_t	sha256[k_ra8_mdl_sha256_bytes] )

nodiscard

Strictly validate one closed private RBKC staging object.

Opens staging_path read-only, proves its exact size, validates every RBKC stream and the complete canonical RABOOK1 payload, then closes it. This signature directly satisfies mdl_storage_vfs_validate_fn.

Parameters

[in,out]	opaque	Initialized mdl_rabook_vfs_t.
[in]	staging_path	Named VFS path to the private closed artifact.
[in]	total_bytes	Independently verified transfer byte count.
[in]	sha256	Independently verified transfer digest.

Returns: Strict validation, VFS, inflater, or close status.

Precondition: The staging path remains immutable for the call.; No reader is open in opaque.

Postcondition: Success retains only decoded metadata and the digest, never a file handle.; Failure leaves the context closed and not transfer-validated.

Note: This function neither commits nor deletes the staging object.

Since: 0.1.0

Definition at line 257 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::digest, mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::file_size, mdl_rabook_vfs_t::header, internal_rabook_close(), internal_rabook_open_reader(), internal_rabook_validate_open(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_mdl_sha256_bytes, k_ra8_ok, memcpy(), memset(), mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::transfer_validated.

Referenced by internal_bind_transfer().

Functions

Detailed Description

Function Documentation

◆ internal_rabook_clear_open()

◆ internal_rabook_close()

◆ internal_rabook_open_reader()

◆ internal_rabook_read_exact()

◆ internal_rabook_validate_open()

◆ mdl_rabook_vfs_close()

◆ mdl_rabook_vfs_info()

◆ mdl_rabook_vfs_init()

◆ mdl_rabook_vfs_open()

◆ mdl_rabook_vfs_read_chunk()

◆ mdl_rabook_vfs_validate()