Bounded, no-heap structural validation of mdl artifacts. More...

#include <stddef.h>
#include "mdl_export.h"
#include "mdl_storage.h"
#include "ra8_err.h"

Include dependency graph for mdl_verify.h:

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

Data Structures
struct	mdl_verify_report_t

Functions
ra8_err_t	mdl_format_from_path (const char path, mdl_format_t out_format)
	Infer an artifact format from its complete path suffix.
bool	mdl_format_is_verifiable (mdl_format_t format)
	Report whether a format has an in-process structural validator.
ra8_err_t	mdl_verify_open_file (mdl_storage_t storage, mdl_format_t format, fw_fs_file_t file, uint64_t size_bytes, mdl_export_workspace_t workspace, mdl_verify_report_t report)
	Validate an artifact through a borrowed open filesystem handle.
ra8_err_t	mdl_verify_file (mdl_storage_t storage, mdl_format_t format, const char path, mdl_export_workspace_t workspace, mdl_verify_report_t report)
	Validate a completed artifact using caller-owned scratch only.

Detailed Description

Bounded, no-heap structural validation of mdl artifacts.

Declares path-based format inference and structural validation that reports artifact contents while using caller-owned scratch storage.

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

Definition in file mdl_verify.h.

Function Documentation

◆ mdl_format_from_path()

ra8_err_t mdl_format_from_path	(	const char *	path,
		mdl_format_t *	out_format )

Infer an artifact format from its complete path suffix.

Matches the complete, case-insensitive suffix so multi-dot formats such as .cbt.gz are not misclassified by their last extension.

Parameters

[in]	path	NUL-terminated artifact path to classify.
[out]	out_format	Receives the recognized format or invalid sentinel.

Returns: Classification status.

Return values

k_ra8_ok	A supported artifact suffix was recognized.
k_ra8_err_invalid_arg	Either pointer is NULL.
k_ra8_err_not_supported	The suffix is not supported.

Precondition: path, when non-NULL, is NUL-terminated.; out_format, when non-NULL, addresses writable storage.

Postcondition: Success stores a verifiable format in out_format.; Failure for an unknown suffix stores k_mdl_format_invalid.

Note: Thread-safe: reads arguments and writes caller-owned storage only.

Since: 0.1.0

< Complete artifact suffix.

< Corresponding format.

Definition at line 107 of file mdl_verify.c.

References internal_ends_ci(), k_mdl_format_cbt, k_mdl_format_cbt_gz, k_mdl_format_cbz, k_mdl_format_epub, k_mdl_format_invalid, k_mdl_format_jof, k_mdl_format_rabook, k_ra8_err_invalid_arg, k_ra8_err_not_supported, and k_ra8_ok.

Referenced by internal_verify_artifact_entry(), and mdl_app_run_artifact().

◆ mdl_format_is_verifiable()

bool mdl_format_is_verifiable ( mdl_format_t format )

Report whether a format has an in-process structural validator.

Distinguishes advertised native formats from reserved enum values whose readers or writers are not yet exposed by this host tool.

Parameters

[in] format Format enum value to query.

Returns: Whether mdl_verify_file implements the format.

Return values

true	The format can be structurally validated in process.
false	The format is invalid, loose, or currently unsupported.

Precondition: format is represented by mdl_format_t.; The caller does not infer writer availability from this predicate.

Postcondition: No caller or global state is modified.; Repeated calls with the same value return the same result.

Note: Thread-safe: this is a pure classifier.

Since: 0.1.0

Definition at line 131 of file mdl_verify.c.

References k_mdl_format_cbt, k_mdl_format_cbt_gz, k_mdl_format_cbz, k_mdl_format_epub, k_mdl_format_jof, and k_mdl_format_rabook.

Referenced by internal_verify_artifact_entry(), mdl_app_run_artifact(), priv_mdl_export_output_begin(), and priv_mdl_export_output_begin_new().

◆ mdl_verify_file()

ra8_err_t mdl_verify_file	(	mdl_storage_t *	storage,
		mdl_format_t	format,
		const char *	path,
		mdl_export_workspace_t *	workspace,
		mdl_verify_report_t *	report )

Validate a completed artifact using caller-owned scratch only.

Dispatches to the format-specific ZIP, tar, gzip, JOF, or strict RBKC reader, rejects unsafe member paths and missing required metadata, and resets the workspace so high_water describes this call alone. ZIP and JOF use positioned reads; TAR and gzip are streamed through bounded chunks, so no complete compressed or decoded archive is retained. Every opened stream is closed before return.

Parameters

[in,out]	storage	Injected filesystem and exclusive file workspace.
[in]	format	Expected artifact format.
[in]	path	NUL-terminated path to the completed artifact.
[in,out]	workspace	Caller-owned bounded validation workspace.
[out]	report	Structural counts populated only on success.

Returns: Validation or argument status.

Return values

k_ra8_ok	The artifact is structurally valid for `format`.
k_ra8_err_invalid_arg	A pointer, workspace, or format is invalid.
k_ra8_err_invalid_size	The caller workspace is too small.
k_ra8_err_validation_failed	Container structure or metadata is bad.
k_ra8_err_not_supported	The reserved format has no validator.
other	A filesystem open/read/seek/size/close failure was propagated.

Precondition: path is canonical, NUL-terminated, and names a stable completed file.; storage, workspace, and report are exclusive to this call.

Postcondition: workspace->used and workspace->high_water describe this validation attempt.; On success report contains format, member, page, and metadata data.; On failure report retains its entry value.

Note: Thread-safe across calls that use distinct workspaces and reports.

Since: 0.1.0

Definition at line 520 of file mdl_verify.c.

References mdl_export_workspace::data, mdl_storage_t::file_workspace, mdl_storage_t::file_workspace_bytes, mdl_storage_t::fs, mdl_export_workspace::high_water, internal_io_close(), internal_io_open(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_err_invalid_arg, k_ra8_ok, mdl_verify_open_file(), and mdl_export_workspace::used.

Referenced by internal_verify_artifact_entry(), and mdl_app_run_artifact().

◆ mdl_verify_open_file()

ra8_err_t mdl_verify_open_file	(	mdl_storage_t *	storage,
		mdl_format_t	format,
		fw_fs_file_t *	file,
		uint64_t	size_bytes,
		mdl_export_workspace_t *	workspace,
		mdl_verify_report_t *	report )

Validate an artifact through a borrowed open filesystem handle.

Dispatches to the same ZIP, tar, gzip, JOF, or strict RBKC validator used by mdl_verify_file after seeking file to offset zero. This entry point lets an exporter validate a staged transaction before commit without publishing or reopening the stage by name. The handle is borrowed: this function never closes it, and its final offset is unspecified. The size is an immutable caller-supplied snapshot.

Parameters

[in,out]	storage	Injected storage buffers used by streaming readers.
[in]	format	Expected artifact format.
[in,out]	file	Borrowed readable and seekable open handle.
[in]	size_bytes	Stable artifact extent in bytes.
[in,out]	workspace	Caller-owned bounded validation workspace.
[out]	report	Structural counts populated only on success.

Returns: Validation, argument, or stream status.

Return values

k_ra8_ok	The staged artifact is structurally valid for `format`.
k_ra8_err_invalid_arg	A pointer, workspace, or format is invalid.
k_ra8_err_invalid_size	The caller workspace is too small.
k_ra8_err_validation_failed	Container structure or metadata is bad.
k_ra8_err_not_supported	The reserved format has no validator.
other	A seek or read failure was propagated.

Precondition: file remains exclusively borrowed for the complete call.; size_bytes is the stable size of the staged artifact.

Postcondition: file remains open and owned by the caller.; On failure report retains its entry value.; workspace->high_water describes this validation attempt.

Note: Thread-safe across distinct handles, workspaces, buffers, and reports.

Since: 0.1.0

Definition at line 491 of file mdl_verify.c.

References mdl_export_workspace::data, fw_fs_seek(), mdl_export_workspace::high_water, internal_verify_borrowed(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_err_invalid_arg, k_ra8_ok, and mdl_export_workspace::used.

Referenced by internal_validate_stage(), and mdl_verify_file().

Data Structures

Functions

Detailed Description

Function Documentation

◆ mdl_format_from_path()

◆ mdl_format_is_verifiable()

◆ mdl_verify_file()

◆ mdl_verify_open_file()