Discovery, descriptor generation, and verification actions. More...

#include "mdl_app_internal.h"

Include dependency graph for mdl_app_admin.c:

Data Structures
struct	verify_stats_t
	Stats accumulated during a library/series verification run. More...

Functions
static void	internal_admin_latch (ra8_err_t error)
	Latch the first administration presenter failure.
static void	internal_admin_text3 (ra8_io_stream_t stream, const char first, const char second, const char third)
	Append three borrowed administration fragments and latch failure.
int	mdl_app_run_discover (const mdl_discover_run_t request, const mdl_run_opts_t opts, const mdl_series_run_t *base)
	Run search or browse discovery and optionally download one result.
static bool	internal_init_site_identity (const char url, const char descriptor_dir, char host, char slug, char name, char out_path)
	Derive bounded descriptor identity and destination fields.
int	mdl_app_run_init_site (const char url, const char descriptor_dir)
	Create a starter descriptor for one validated site URL.
static void	internal_verify_artifact_entry (const char dir, const fw_fs_dirent_value_t entry, verify_stats_t *st)
	Classify one recognized artifact directory entry.
static void	internal_verify_artifacts (const char dir, verify_stats_t st)
	Structurally validate recognized artifacts in one directory.
static bool	internal_verify_page_rec (const char series_dir, const mdl_page_rec_t rec, verify_stats_t *st)
	Verify one tracked page's presence and content hash.
static void	internal_verify_series_dir (const char series_dir, const char state_path, verify_stats_t *st)
	Verify persisted pages and artifacts for one tracked series.
static void	internal_verify_library_root (const char canonical, verify_stats_t stats)
	Verify root-level artifacts and every tracked child series.
static ra8_err_t	internal_verify_print_summary (ra8_io_stream_t output, const verify_stats_t st)
	Stream the verification totals summary line.
int	mdl_app_run_verify (const char *target_dir)
	Verify one library or artifact tree without mutating it.

Variables
static mdl_hit_list_t	s_results
	Bounded titled discovery hits for the active query.

Detailed Description

Discovery, descriptor generation, and verification actions.

Owns bounded CLI administration workflows: site discovery, atomic starter-descriptor publication, and read-only library verification.

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

Definition in file mdl_app_admin.c.

Function Documentation

◆ internal_admin_latch()

void internal_admin_latch ( ra8_err_t error )

static

Latch the first administration presenter failure.

Uses bounded application and filesystem state with injected output. The first failure is latched and no later operation overwrites it.

Parameters

[in] error Candidate failure value to latch.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Since: Version 0.1.0

Definition at line 25 of file mdl_app_admin.c.

References mdl_app_context_t::io_error, k_ra8_ok, priv_mdl_app_context(), and RA8_INTERNAL.

Referenced by internal_admin_text3(), and internal_verify_artifact_entry().

◆ internal_admin_text3()

void internal_admin_text3	(	ra8_io_stream_t *	stream,
		const char *	first,
		const char *	second,
		const char *	third )

static

Append three borrowed administration fragments and latch failure.

Uses bounded application and filesystem state with injected output. The first failure is latched and no later operation overwrites it.

Parameters

[in,out]	stream	Destination stream state.
[in]	first	First text fragment.
[in]	second	Second text fragment.
[in]	third	Third text fragment.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Since: Version 0.1.0

Definition at line 46 of file mdl_app_admin.c.

References internal_admin_latch(), k_ra8_ok, priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_init_site_identity(), internal_verify_artifact_entry(), internal_verify_artifacts(), internal_verify_page_rec(), internal_verify_series_dir(), mdl_app_run_init_site(), and mdl_app_run_verify().

◆ internal_init_site_identity()

bool internal_init_site_identity	(	const char *	url,
		const char *	descriptor_dir,
		char *	host,
		char *	slug,
		char *	name,
		char *	out_path )

static

Derive bounded descriptor identity and destination fields.

Coordinates init site identity with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	url	Absolute site URL.
[out]	host	Complete normalized URL host.
[out]	slug	First non-www host label, or site when empty.
[out]	name	Display name derived from `slug`.
[in]	descriptor_dir	Canonical composition-selected descriptor directory.
[out]	out_path	Descriptor destination beneath `descriptor_dir`.

Returns: Whether all required identity fields were derived.

Return values

true	Every output contains a complete NUL-terminated value.
false	`url` was absent or its host was invalid.

Precondition: Output arrays use their corresponding compile-time capacities.; url is NULL or NUL-terminated.

Postcondition: Failure emits the original usage or host diagnostic.; No filesystem content is created or modified.

Note: Thread-safe for distinct caller-owned outputs.

Since: 0.1.0

Definition at line 131 of file mdl_app_admin.c.

References internal_admin_text3(), k_fw_fs_path_cap, k_leaf_name_bytes, k_mdl_host_max, k_mdl_name_max, k_ra8_ok, mdl_path_join(), mdl_url_host(), priv_mdl_app_context(), priv_mdl_stream_text(), RA8_INTERNAL, and strncmp().

Referenced by mdl_app_run_init_site().

◆ internal_verify_artifact_entry()

void internal_verify_artifact_entry	(	const char *	dir,
		const fw_fs_dirent_value_t *	entry,
		verify_stats_t *	st )

static

Classify one recognized artifact directory entry.

Parameters

[in]	dir	Canonical directory containing `entry`.
[in]	entry	Complete cursor value to inspect without following links.
[in,out]	st	Verification counters to update.

Precondition: All pointer arguments are non-NULL.

Postcondition: Unrecognized suffixes leave st unchanged; recognized entries increment archives_checked and exactly one outcome counter.

Note: Not thread-safe because validation uses the shared exporter workspace.

Since: 0.1.0

Uses bounded application and filesystem state with injected output. The first failure is latched and no later operation overwrites it.

Precondition: Every required pointer is non-null and remains valid for the call.

Postcondition: Documented outputs and the return value describe the same outcome.

Definition at line 250 of file mdl_app_admin.c.

References verify_stats_t::archives_checked, verify_stats_t::archives_corrupt, verify_stats_t::archives_valid, fw_fs_stat_t::exists, fw_fs_stat(), internal_admin_latch(), internal_admin_text3(), k_fw_fs_node_file, k_fw_fs_path_cap, k_mdl_format_invalid, k_ra8_ok, mdl_format_from_path(), mdl_format_is_verifiable(), mdl_path_join(), mdl_verify_file(), fw_fs_dirent_value_t::name, mdl_app_context_t::output, priv_mdl_app_context(), priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, fw_fs_dirent_value_t::type, and fw_fs_stat_t::type.

Referenced by internal_verify_artifacts().

◆ internal_verify_artifacts()

void internal_verify_artifacts	(	const char *	dir,
		verify_stats_t *	st )

static

Structurally validate recognized artifacts in one directory.

Infers supported formats from complete suffixes, rejects nonregular candidates, and validates contents through format reader paths.

Parameters

[in]	dir	Canonical directory to scan.
[in,out]	st	Verification counters to update.

Precondition: dir and st are non-NULL.; priv_mdl_app_context()->export_ws is initialized for bounded validation scratch.

Postcondition: Every recognized directory entry increments archives_checked once.; Each checked artifact increments exactly one outcome counter.

Note: Not thread-safe because it uses the shared exporter workspace.

Since: 0.1.0

Definition at line 314 of file mdl_app_admin.c.

References verify_stats_t::fs_errors, fw_fs_dir_close(), fw_fs_dir_next(), fw_fs_dir_open(), internal_admin_text3(), internal_verify_artifact_entry(), k_ra8_ok, fw_fs_dirent_value_t::name, priv_mdl_app_context(), and RA8_INTERNAL.

Referenced by internal_verify_library_root(), and internal_verify_series_dir().

◆ internal_verify_library_root()

void internal_verify_library_root	(	const char *	canonical,
		verify_stats_t *	stats )

static

Verify root-level artifacts and every tracked child series.

Coordinates verify library root with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	canonical	Canonical library root.
[in,out]	stats	Verification counters to update.

Precondition: canonical and stats are non-NULL.; canonical names a real directory.

Postcondition: Every recognized root artifact and tracked child is classified once.; Enumeration failures increment stats->fs_errors.

Note: Not thread-safe because child verification uses shared state.

Since: 0.1.0

Definition at line 469 of file mdl_app_admin.c.

References fw_fs_stat_t::exists, verify_stats_t::fs_errors, fw_fs_dir_close(), fw_fs_dir_next(), fw_fs_dir_open(), fw_fs_stat(), internal_verify_artifacts(), internal_verify_series_dir(), k_fw_fs_node_directory, k_fw_fs_path_cap, k_ra8_ok, mdl_path_join(), mdl_state_probe(), fw_fs_dirent_value_t::name, priv_mdl_app_context(), RA8_INTERNAL, fw_fs_dirent_value_t::type, and fw_fs_stat_t::type.

Referenced by mdl_app_run_verify().

◆ internal_verify_page_rec()

bool internal_verify_page_rec	(	const char *	series_dir,
		const mdl_page_rec_t *	rec,
		verify_stats_t *	st )

static

Verify one tracked page's presence and content hash.

Resolves the page's canonical path beneath the series root, confirms it exists as a regular file, then compares its content hash against the recorded value.

Parameters

[in]	series_dir	Canonical tracked-series directory.
[in]	rec	Recorded page whose file and hash are checked.
[in,out]	st	Verification counters to update.

Returns: Whether the caller's page loop should keep going.

Return values

true	One of pages_missing, pages_corrupt, or pages_valid increased; continue with the next page.
false	A diagnostic write hit the shared I/O error latch; the caller must abort the whole series verification.

Precondition: All pointer arguments are non-NULL.; rec->rel_path is relative to series_dir and NUL-terminated.

Postcondition: Exactly one counter increases when this returns true.; Neither the page file nor the recorded page entry is modified.

Note: Not thread-safe; shares the application's I/O error latch.

Since: 0.1.0

Definition at line 377 of file mdl_app_admin.c.

References mdl_page_rec_t::content_hash, fw_fs_stat_t::exists, fw_fs_stat(), internal_admin_text3(), k_fw_fs_node_file, k_fw_fs_path_cap, k_ra8_ok, mdl_hash_file(), verify_stats_t::pages_corrupt, verify_stats_t::pages_missing, verify_stats_t::pages_valid, priv_mdl_app_context(), mdl_page_rec_t::rel_path, and fw_fs_stat_t::type.

Referenced by internal_verify_series_dir().

◆ internal_verify_print_summary()

ra8_err_t internal_verify_print_summary	(	ra8_io_stream_t *	output,
		const verify_stats_t *	st )

static

Stream the verification totals summary line.

Composes the fixed "verify complete" line with series, page, and artifact counters in one non-branching stream chain.

Parameters

[in,out]	output	Bound stream sink.
[in]	st	Final verification counters.

Returns: Stream status.

Return values

k_ra8_ok	The complete summary line was written.
other	The first stream write failure.

Precondition: output and st are non-NULL.; Every counter in st already holds its final value.

Postcondition: Success writes exactly one terminated summary line.; A failure preserves the first failing fragment's status and writes nothing after it.

Note: Not thread-safe for a shared stream.

Since: 0.1.0

Definition at line 536 of file mdl_app_admin.c.

References verify_stats_t::archives_corrupt, verify_stats_t::archives_valid, k_ra8_ok, verify_stats_t::pages_corrupt, verify_stats_t::pages_missing, verify_stats_t::pages_valid, priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, and verify_stats_t::series_checked.

Referenced by mdl_app_run_verify().

◆ internal_verify_series_dir()

void internal_verify_series_dir	(	const char *	series_dir,
		const char *	state_path,
		verify_stats_t *	st )

static

Verify persisted pages and artifacts for one tracked series.

Loads validated state, resolves every page beneath the canonical series root, compares content hashes, then checks local artifacts.

Parameters

[in]	series_dir	Canonical tracked-series directory.
[in]	state_path	Complete .mdl_state path.
[in,out]	st	Verification counters to update.

Precondition: All pointer arguments are non-NULL.; series_dir is canonical and st is initialized.

Postcondition: series_checked increases exactly once.; Every recorded page is classified as valid, missing/unsafe, or corrupt.

Note: Not thread-safe because state and validator workspace are shared.

Since: 0.1.0

Definition at line 427 of file mdl_app_admin.c.

References internal_admin_text3(), internal_verify_artifacts(), internal_verify_page_rec(), k_ra8_ok, mdl_state_load(), mdl_state_t::page_rec_count, mdl_state_t::pages, priv_mdl_app_context(), verify_stats_t::series_checked, mdl_app_context_t::state, and verify_stats_t::state_errors.

Referenced by internal_verify_library_root(), and mdl_app_run_verify().

◆ mdl_app_run_discover()

int mdl_app_run_discover	(	const mdl_discover_run_t *	req,
		const mdl_run_opts_t *	opts,
		const mdl_series_run_t *	base )

Run search or browse discovery and optionally download one result.

Loads the descriptor, opens a transport through the injected provider, lists the bounded hits, and feeds an explicitly selected hit into series mode.

Parameters

[in]	req	Validated discovery selection.
[in]	opts	Validated network and execution policy.
[in]	base	Series defaults inherited by the chosen hit.

Returns: Run status.

Return values

0	Results were listed or the selected series succeeded.
nonzero	Descriptor, network, discovery, or series work failed.

Precondition: All pointers are non-NULL and a context is bound.; req names a descriptor the bound storage can read.

Postcondition: The discovery transport is destroyed before return.; A picked URL is downloaded only when selection produced a complete URL.

Note: Not thread-safe because it uses the shared discovery buffers.

Since: 0.1.0

Definition at line 56 of file mdl_app_admin.c.

References mdl_discover_run_t::browse, mdl_discover_run_t::cfg_path, mdl_site_t::contact, mdl_app_context_t::diagnostic, mdl_app_context_t::io_error, k_mdl_discover_browse, k_mdl_discover_search, k_mdl_ua_max, k_mdl_url_max, k_ra8_ok, mdl_app_run_series(), mdl_config_apply_polite(), mdl_config_gov_cfg(), mdl_config_load(), mdl_discover_run(), mdl_governor_init(), mdl_net_destroy(), mdl_net_provider_open(), mdl_run_opts_t::net, mdl_app_context_t::output, mdl_app_context_t::page, mdl_discover_run_t::pick, mdl_run_opts_t::policy, mdl_run_opts_t::polite, priv_mdl_app_context(), priv_mdl_app_start_session(), priv_mdl_stream_text(), s_results, mdl_discover_run_t::seed, mdl_app_context_t::session, mdl_discover_run_t::term, and mdl_discover_run_t::timeout.

Referenced by priv_mdl_compose_dispatch().

◆ mdl_app_run_init_site()

int mdl_app_run_init_site	(	const char *	url,
		const char *	descriptor_dir )

Create a starter descriptor for one validated site URL.

Derives the descriptor identity, joins it beneath the caller-selected descriptor directory, and publishes it through a validated create-new transaction that never replaces an existing file.

Parameters

[in]	url	Canonical absolute site URL.
[in]	descriptor_dir	Canonical existing directory chosen by the form.

Returns: Run status.

Return values

0	The descriptor template was created.
1	The destination could not be created.
2	The URL was absent or its host could not be extracted.

Precondition: descriptor_dir is a canonical absolute path and a context is bound.; The bound storage owns the descriptor namespace exclusively.

Postcondition: Failure preserves any existing descriptor byte-for-byte.; Success publishes exactly the generated descriptor bytes.

Note: Not safe for concurrent creation of the same descriptor path.

Since: 0.1.0

Definition at line 171 of file mdl_app_admin.c.

References internal_admin_text3(), internal_init_site_identity(), k_fw_fs_path_cap, k_mdl_host_max, k_mdl_name_max, k_ra8_err_exists, k_ra8_ok, mdl_app_context_t::output, priv_mdl_app_context(), priv_mdl_app_storage_ensure_directory(), priv_mdl_app_storage_publish_site(), and priv_mdl_stream_text().

Referenced by priv_mdl_compose_dispatch().

◆ mdl_app_run_verify()

int mdl_app_run_verify ( const char * target_dir )

Verify one library or artifact tree without mutating it.

Detects a direct tracked-series marker or enumerates child series, rehashes every recorded page, validates recognised artifacts through their format readers, and prints the totals.

Parameters

[in] target_dir Canonical directory tree to verify.

Returns: Run status.

Return values

0	At least one target was found and every check passed.
1	The root was invalid, empty of targets, or a check failed.

Precondition: target_dir is non-NULL and a context is bound.; The bound exporter workspace is initialised.

Postcondition: The target tree and its artifacts remain unmodified.; Every discovered failure contributes to the status and the summary.

Note: Not thread-safe because it uses the shared validator workspace.

Since: 0.1.0

Definition at line 554 of file mdl_app_admin.c.

References verify_stats_t::archives_checked, verify_stats_t::archives_corrupt, fw_fs_stat_t::exists, verify_stats_t::fs_errors, fw_fs_stat(), internal_admin_text3(), internal_verify_library_root(), internal_verify_print_summary(), internal_verify_series_dir(), k_fw_fs_node_directory, k_fw_fs_path_cap, k_ra8_ok, mdl_path_join(), mdl_state_probe(), mdl_app_context_t::output, verify_stats_t::pages_corrupt, verify_stats_t::pages_missing, priv_mdl_app_context(), verify_stats_t::series_checked, verify_stats_t::state_errors, and fw_fs_stat_t::type.

Referenced by priv_mdl_compose_dispatch().

Variable Documentation

◆ s_results

mdl_hit_list_t s_results

static

Bounded titled discovery hits for the active query.

Definition at line 12 of file mdl_app_admin.c.

Referenced by mdl_app_run_discover().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ internal_admin_latch()

◆ internal_admin_text3()

◆ internal_init_site_identity()

◆ internal_verify_artifact_entry()

◆ internal_verify_artifacts()

◆ internal_verify_library_root()

◆ internal_verify_page_rec()

◆ internal_verify_print_summary()

◆ internal_verify_series_dir()

◆ mdl_app_run_discover()

◆ mdl_app_run_init_site()

◆ mdl_app_run_verify()

Variable Documentation

◆ s_results