The downloader's portable application layer: one run mode, one call. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_cache.h"
#include "mdl_export.h"
#include "mdl_extract.h"
#include "mdl_format.h"
#include "mdl_library.h"
#include "mdl_net.h"
#include "mdl_session.h"
#include "mdl_state.h"
#include "mdl_storage.h"
#include "ra8_err.h"
#include "ra8_io_stream.h"

Include dependency graph for mdl_app.h:

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

Go to the source code of this file.

Data Structures
struct	mdl_run_opts_t
	Cross-cutting policy and injected transport threaded into every mode. More...
struct	mdl_series_metadata_t
	Bounded metadata scraped while the series HTML is resident. More...
struct	mdl_series_run_t
	Parameters of one series download, as values rather than arguments. More...
struct	mdl_discover_run_t
	One search or browse request against a configured site descriptor. More...
struct	mdl_app_context_t
	The one bounded working set every application mode shares. More...

Enumerations
enum	mdl_app_limits_t : uint32_t { k_page_buf_bytes = 8U * 1024U * 1024U , k_export_arena_bytes = 96U * 1024U * 1024U , k_storage_work_bytes = 2048U }
	Fixed sizing for one application composition (large buffers in .bss). More...

Functions
void	mdl_app_bind (mdl_app_context_t *ctx)
	Bind the caller-owned working set every application mode will use.
int	mdl_app_run_series (const mdl_series_run_t *run)
	Execute one prepared series download.
int	mdl_app_run_list (const char *out_dir)
	List every tracked series under one library root.
int	mdl_app_run_remove (const char out_dir, const char url_or_slug)
	Remove one explicitly tracked series directory.
int	mdl_app_run_update_all (const mdl_series_run_t *base)
	Incrementally update every tracked series under a library root.
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.
int	mdl_app_run_verify (const char *target_dir)
	Verify one library or artifact tree without mutating it.
int	mdl_app_run_init_site (const char url, const char descriptor_dir)
	Create a starter descriptor for one validated site URL.
int	mdl_app_run_pack (const char *dir, mdl_format_t format)
	Package an existing image directory without network access.
int	mdl_app_run_artifact (const char url, const char out_dir, uint32_t timeout, const mdl_run_opts_t *opts)
	Download, validate and atomically publish one direct artifact.
int	mdl_app_run_page (const char url, const char out_dir, const char attr, uint32_t max_imgs, uint64_t seed, uint32_t timeout, const mdl_run_opts_t opts)
	Download image resources from one direct page URL.

Detailed Description

The downloader's portable application layer: one run mode, one call.

Everything above the individual subsystems (fetch, state, cache, export, verify, library) and below the thing that parsed a request. A build form supplies four host-shaped resources and then calls one of the mdl_app_run_* entry points below; it does not reimplement a mode:

the bounded mdl_app_context_t working set, bound once with mdl_app_bind, so the form decides where the multi-megabyte page and export buffers live;
a mdl_storage_t over fw_if_fs, so a mode names paths and never a host filesystem call;
two ra8_io_stream_t sinks, so a mode writes bytes and never stdio;
one mdl_net_provider_t, so a mode opens a transport for its run without naming libcurl, the C6 radio, or a test fake.

That last one is the seam that used to be absent: the mode functions called the libcurl factory directly, so the orchestration could only ever be compiled by the host CLI. The provider inverts it, and everything else here follows – these entry points take values, not an argv-shaped struct, so the argv grammar stays in the form that has one.

See also: mdl_net.h The transport vtable and the provider dispatcher.; mdl_storage.h The filesystem facade a form binds.

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

Definition in file mdl_app.h.

Enumeration Type Documentation

◆ mdl_app_limits_t

enum mdl_app_limits_t : uint32_t

Fixed sizing for one application composition (large buffers in .bss).

A form declares its storage with these so every form agrees on the bounds the modes were written against.

Since: 0.1.0

Enumerator
k_page_buf_bytes	Max HTML page size.
k_export_arena_bytes	Host export scratch ceiling.
k_storage_work_bytes	Per-handle FS backend state.

Definition at line 54 of file mdl_app.h.

Function Documentation

◆ mdl_app_bind()

void mdl_app_bind ( mdl_app_context_t * ctx )

Bind the caller-owned working set every application mode will use.

The composition seam for the application layer. A form declares one mdl_app_context_t in its own storage – static on a host, a reserved SRAM region on the device – initialises the members it owns (the two streams, the storage facade, the exporter workspace) and hands the address here. Every mode then reads that one context through a module-private accessor, so the downloader needs no global of its own and a test can bind a fixture context instead of the production one.

Binding is unconditional and reports nothing: there is exactly one thing it can do and one way to get it wrong, and passing a context the modes cannot dereference is a composition defect rather than a runtime condition – the same contract mdl_export_workspace_init already publishes for the exporter arena.

Parameters

[in,out] ctx Caller-owned context, live until the next bind.

Returns: Nothing.

Precondition: ctx addresses writable storage for one complete context.; No mode call is in progress on another thread.

Postcondition: ctx is the context every subsequent mode reads.; No caller storage is copied and no ownership is transferred.

Note: Not thread-safe: it publishes process-wide composition state.

Since: 0.1.0

Definition at line 28 of file mdl_app.c.

References s_app_ctx.

Referenced by internal_main_init().

◆ mdl_app_run_artifact()

int mdl_app_run_artifact	(	const char *	url,
		const char *	out_dir,
		uint32_t	timeout,
		const mdl_run_opts_t *	opts )

Download, validate and atomically publish one direct artifact.

Accepts only formats with structural validators, stages the response through a transaction, validates it through the reader path, and only then commits it.

Parameters

[in]	url	Canonical absolute artifact URL.
[in]	out_dir	Canonical output directory.
[in]	timeout	Per-request timeout in milliseconds.
[in]	opts	Validated network and execution policy.

Returns: Run status.

Return values

0	A structurally valid artifact was published.
1	Format, path, network, validation, or commit failed.

Precondition: All pointers are non-NULL and a context is bound.; opts carries a transport provider.

Postcondition: Failure does not publish a partial destination artifact.; The transport opened for the run is destroyed on every path.

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

Since: 0.1.0

Definition at line 636 of file mdl_app_direct.c.

References internal_direct_latch(), internal_direct_text3(), internal_fetch_artifact(), internal_prepare_artifact_path(), k_fw_fs_path_cap, k_leaf_name_bytes, k_mdl_format_invalid, k_ra8_ok, mdl_format_from_path(), mdl_format_is_verifiable(), mdl_urlname_last_segment(), mdl_verify_file(), priv_mdl_app_context(), priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by priv_mdl_compose_dispatch().

◆ 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_list()

int mdl_app_run_list ( const char * out_dir )

List every tracked series under one library root.

Visits only authenticated .mdl_state markers and reports each series' directory, source URL, and coverage summary.

Parameters

[in] out_dir Canonical library root to enumerate.

Returns: Run status.

Return values

0	Enumeration completed and every state file was readable.
1	Traversal failed or at least one state file was unreadable.

Precondition: out_dir is non-NULL and a context is bound.; The bound output stream accepts writes.

Postcondition: Every discovered tracked series is reported once.; No library data is modified.

Note: Not thread-safe because callbacks use the shared state scratch.

Since: 0.1.0

Definition at line 139 of file mdl_app_library.c.

References list_ctx_t::found, internal_library_report(), internal_library_text3(), internal_list_cb(), k_ra8_ok, mdl_library_for_each(), mdl_library_policy_default(), and priv_mdl_app_context().

Referenced by priv_mdl_compose_dispatch().

◆ mdl_app_run_pack()

int mdl_app_run_pack	(	const char *	dir,
		mdl_format_t	format )

Package an existing image directory without network access.

Validates dir, distinguishes directory-output formats from file containers, and streams the supported images through the exporter.

Parameters

[in]	dir	Existing canonical chapter image directory.
[in]	format	Selected output format.

Returns: Run status.

Return values

0	Packaging completed successfully.
1	Path resolution or export failed.
2	The requested format is absent or invalid for pack mode.

Precondition: dir is non-NULL and a context is bound.; The bound exporter workspace is exclusively owned by the caller.

Postcondition: No network request is attempted by this mode.; Export errors are reported with their exact format.

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

Since: 0.1.0

Definition at line 874 of file mdl_app_direct.c.

References fw_fs_stat_t::exists, fw_fs_stat(), internal_direct_text3(), internal_pack_directory_output(), internal_pack_file_output(), k_fw_fs_node_directory, k_mdl_format_invalid, k_mdl_format_loose, k_ra8_ok, mdl_format_ext(), mdl_format_is_dir_output(), priv_mdl_app_context(), priv_mdl_stream_text(), and fw_fs_stat_t::type.

Referenced by priv_mdl_compose_dispatch().

◆ mdl_app_run_page()

int mdl_app_run_page	(	const char *	url,
		const char *	out_dir,
		const char *	attr,
		uint32_t	max_imgs,
		uint64_t	seed,
		uint32_t	timeout,
		const mdl_run_opts_t *	opts )

Download image resources from one direct page URL.

Opens a transport through the injected provider, enforces URL policy, extracts the selected image attribute and downloads the bounded image set under the governor.

Parameters

[in]	url	Canonical absolute page URL.
[in]	out_dir	Canonical output directory.
[in]	attr	Image attribute selector.
[in]	max_imgs	Maximum images to transfer, or zero for every match.
[in]	seed	Deterministic politeness-jitter seed.
[in]	timeout	Per-request timeout in milliseconds.
[in]	opts	Validated network and execution policy.

Returns: Run status.

Return values

0	Every attempted image succeeded.
1	Network, policy, or image download failed.

Precondition: All pointers are non-NULL and a context is bound.; opts carries a transport provider.

Postcondition: No staged partial image remains published as a final page.; The transport opened for the run is destroyed on every path.

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

Since: 0.1.0

Definition at line 744 of file mdl_app_direct.c.

References internal_direct_latch(), internal_download_page_images(), internal_extract_page_images(), internal_prepare_output_dir(), k_fw_fs_path_cap, k_mdl_ua_max, k_ra8_ok, mdl_net_destroy(), mdl_net_provider_open(), mdl_session_url_allowed(), mdl_run_opts_t::net, mdl_run_opts_t::policy, mdl_run_opts_t::polite, priv_mdl_app_context(), priv_mdl_app_start_session(), priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by priv_mdl_compose_dispatch().

◆ mdl_app_run_remove()

int mdl_app_run_remove	(	const char *	out_dir,
		const char *	url_or_slug )

Remove one explicitly tracked series directory.

Derives the bounded slug, refuses symbolic-link and untracked targets, and requires the recorded series URL to resolve to the same slug before delegating recursive removal.

Parameters

[in]	out_dir	Canonical library root.
[in]	url_or_slug	Series URL or slug selected by the caller.

Returns: Run status.

Return values

0	The tracked tree was removed.
1	Resolution, marker validation, or removal failed.

Precondition: Both pointers are non-NULL and a context is bound.; The caller has authorised a destructive operation.

Postcondition: Untracked, corrupt, mismatched or symlinked directories are never removed.; Success reports the removed directory path.

Note: Not safe for concurrent mutation of the same tree.

Since: 0.1.0

Definition at line 236 of file mdl_app_library.c.

References internal_library_text3(), internal_resolve_removal_target(), k_dir_path_bytes, k_ra8_ok, mdl_library_policy_default(), mdl_library_remove_tree(), and priv_mdl_app_context().

Referenced by priv_mdl_compose_dispatch().

◆ mdl_app_run_series()

int mdl_app_run_series ( const mdl_series_run_t * run )

Execute one prepared series download.

Loads the descriptor, opens a transport through the injected provider, prepares the chapter list, reconciles persisted metadata, fetches, checkpoints and exports.

Parameters

[in] run Prepared series identity, selection, format, and policy.

Returns: Run status.

Return values

0	The operation completed.
nonzero	Validation or a dependency failed.

Precondition: run is non-NULL and a context is bound.; The bound context is exclusively owned by the calling thread.

Postcondition: No ownership of caller-provided storage is transferred.; The transport opened for the run is destroyed on every path.

Note: Not thread-safe because it uses the bound application context.

Since: 0.1.0

Definition at line 853 of file mdl_app_series.c.

References mdl_series_run_t::cache_dir, mdl_series_run_t::cfg_path, mdl_site_t::host, internal_run_series_network(), internal_series_text3(), k_ra8_ok, mdl_site_t::kind, mdl_config_apply_polite(), mdl_config_load(), mdl_site_t::name, mdl_series_run_t::opts, mdl_series_run_t::out_dir, mdl_run_opts_t::polite, priv_mdl_app_context(), priv_mdl_app_storage_ensure_directory(), and priv_mdl_stream_text().

Referenced by internal_update_all_cb(), mdl_app_run_discover(), and priv_mdl_compose_dispatch().

◆ mdl_app_run_update_all()

int mdl_app_run_update_all ( const mdl_series_run_t * base )

Incrementally update every tracked series under a library root.

Enumerates the library with a fixed run template, inherits each series' recorded URL and descriptor, and summarises the failures.

Parameters

[in] base Template run parameters, including the library root.

Returns: Run status.

Return values

0	Traversal and every attempted update succeeded.
1	Traversal or at least one series update failed.

Precondition: base is non-NULL and names a valid output root.; A context is bound and its workspaces are initialised.

Postcondition: Every tracked series is visited at most once.; Failures remain visible in the returned status and the diagnostics.

Note: Not thread-safe because updates reuse the bound context.

Since: 0.1.0

Definition at line 331 of file mdl_app_library.c.

References update_all_ctx_t::failed, internal_library_report(), internal_library_text3(), internal_update_all_cb(), k_ra8_ok, mdl_library_for_each(), mdl_library_policy_default(), mdl_series_run_t::out_dir, priv_mdl_app_context(), priv_mdl_stream_text(), priv_mdl_stream_u64(), and update_all_ctx_t::updated.

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

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_app_limits_t

Function Documentation

◆ mdl_app_bind()

◆ mdl_app_run_artifact()

◆ mdl_app_run_discover()

◆ mdl_app_run_init_site()

◆ mdl_app_run_list()

◆ mdl_app_run_pack()

◆ mdl_app_run_page()

◆ mdl_app_run_remove()

◆ mdl_app_run_series()

◆ mdl_app_run_update_all()

◆ mdl_app_run_verify()