mdl_app_internal.h File Reference

Module-private contract shared by the application-mode translation units. More...

#include <inttypes.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include "mdl_app.h"
#include "mdl_app_storage_internal.h"
#include "mdl_cache.h"
#include "mdl_config.h"
#include "mdl_discover.h"
#include "mdl_export.h"
#include "mdl_extract.h"
#include "mdl_fetch.h"
#include "mdl_fetch_internal.h"
#include "mdl_hash.h"
#include "mdl_library.h"
#include "mdl_net.h"
#include "mdl_pack.h"
#include "mdl_pathfs.h"
#include "mdl_politeness.h"
#include "mdl_report.h"
#include "mdl_sanitize.h"
#include "mdl_session.h"
#include "mdl_state.h"
#include "mdl_storage.h"
#include "mdl_stream_internal.h"
#include "mdl_url_guard.h"
#include "mdl_urlname.h"
#include "mdl_verify.h"
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_io_stream.h"

Include dependency graph for mdl_app_internal.h:

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

Go to the source code of this file.

Enumerations
enum	mdl_bufsize_t : uint16_t {   k_slug_bytes = 128 ,   k_leaf_name_bytes = 256 ,   k_dir_path_bytes = 1024 ,   k_file_path_bytes = 1200 ,   k_cov_bytes = 256 ,   k_ext_bytes = 8 ,   k_page_img_delay_min = 400 ,   k_page_img_delay_max = 800 }
	On-stack string buffer sizes and page-mode delays. More...
enum	mdl_polite_floor_t : uint16_t {   k_polite_img_min_ms = 2000 ,   k_polite_img_max_ms = 4000 }
	Polite per-image delay floors for page mode (milliseconds). More...

Functions
mdl_app_context_t *	priv_mdl_app_context (void)
	The working set the composition root bound with mdl_app_bind.
ra8_err_t	priv_mdl_app_report_cache (const char *url, const mdl_cache_result_t *result)
	Report corruption recovery or verified cache reuse with staleness.
ra8_err_t	priv_mdl_app_ensure_series_cover (mdl_fetch_ctx_t *ctx, const char *series_directory)
	Ensure series state names one verified cached or freshly fetched cover.
ra8_err_t	priv_mdl_app_prepare_chapters (const mdl_site_t *site, const char *series_url, uint32_t timeout, mdl_cache_t *cache)
	Fetch and extract a series' bounded chapter list.
ra8_err_t	priv_mdl_app_start_session (mdl_net_iface_t *net, const mdl_run_opts_t *opts, const char *cfg_contact, char *ua, size_t ua_cap)
	Initialize one bounded network-policy session.
bool	priv_mdl_app_prepare_series_dir (const char *out_dir, const char *series_url, char *slug, size_t slug_cap, char *abs_dir)
	Prepare a contained canonical directory for one series.
bool	priv_mdl_app_state_path_of (const char *abs_dir, char *out, size_t cap)
	Compose the state-journal path within a series directory.

Detailed Description

Module-private contract shared by the application-mode translation units.

The bounded sizing every mode was written against, the accessor for the one bound working set, and the helpers the modes share across translation units. Nothing here names a host facility: the transport arrives as mdl_net_provider_t, the filesystem as mdl_storage_t and the sinks as ra8_io_stream_t, which is what lets these units compile in a form that has no libcurl and no POSIX.

Copyright

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

Definition in file mdl_app_internal.h.

Enumeration Type Documentation

mdl_bufsize_t

enum mdl_bufsize_t : uint16_t

On-stack string buffer sizes and page-mode delays.

Enumerator
k_slug_bytes	Series slug buffer.
k_leaf_name_bytes	Composed archive/dir leaf name.
k_dir_path_bytes	Directory-path buffer.
k_file_path_bytes	File-path buffer.
k_cov_bytes	Coverage summary line buffer.
k_ext_bytes	Image-extension buffer.
k_page_img_delay_min	page-mode per-image floor, ms.
k_page_img_delay_max	page-mode per-image ceiling, ms.

Definition at line 52 of file mdl_app_internal.h.

mdl_polite_floor_t

enum mdl_polite_floor_t : uint16_t

Polite per-image delay floors for page mode (milliseconds).

Enumerator
k_polite_img_min_ms	Polite per-image floor.
k_polite_img_max_ms	Polite per-image ceiling.

Definition at line 64 of file mdl_app_internal.h.

Function Documentation

priv_mdl_app_context()

mdl_app_context_t * priv_mdl_app_context

(

void

)

The working set the composition root bound with mdl_app_bind.

The one way an application mode reaches shared bounded state. It is a function rather than an extern object so the storage stays owned by the form and this layer keeps no global of its own.

Returns

The bound context.

Return values

non-NULL	The context most recently passed to mdl_app_bind.
nullptr	No form has bound a context yet.

Precondition

A form has called mdl_app_bind for any mode to be usable.

The caller does not retain the pointer past the next bind.

Postcondition

No context state is modified.

Successive calls return the same pointer until the next bind.

Note

Not thread-safe against a concurrent mdl_app_bind.

Since

0.1.0

Definition at line 33 of file mdl_app.c.

References RA8_PRIV, and s_app_ctx.

Referenced by internal_admin_latch(), internal_apply_order(), internal_build_export_metadata(), internal_cover_cached(), internal_cover_current(), internal_cover_finish(), internal_cover_stream(), internal_direct_latch(), internal_direct_pack_failure(), internal_download_page_image(), internal_download_page_images(), internal_export_after(), internal_export_fresh_separate(), internal_extract_cover(), internal_extract_optional_metadata(), internal_extract_page_images(), internal_extract_series_metadata(), internal_fetch_artifact(), internal_finish_artifact_fetch(), internal_init_site_identity(), internal_library_report(), internal_list_cb(), internal_make_ctx(), internal_pack_directory_output(), internal_pack_file_output(), internal_prepare_artifact_path(), internal_prepare_diag3(), internal_prepare_filter_chapters(), internal_prepare_output_dir(), internal_publish_page_image(), internal_reconcile_series_state(), internal_remove_stale_page_variants(), internal_report_cover_failure(), internal_report_stats(), internal_resolve_removal_target(), internal_run_prepared(), internal_run_series_network(), internal_run_series_paths(), internal_save_series_state(), internal_select_run_window(), internal_select_window(), internal_snapshot_prior_metadata(), internal_update_all_cb(), internal_verify_artifact_entry(), internal_verify_artifacts(), internal_verify_library_root(), internal_verify_page_rec(), internal_verify_series_dir(), internal_warn_no_contact(), 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(), priv_mdl_app_ensure_series_cover(), priv_mdl_app_prepare_chapters(), priv_mdl_app_prepare_series_dir(), priv_mdl_app_report_cache(), and priv_mdl_app_start_session().

priv_mdl_app_ensure_series_cover()

ra8_err_t priv_mdl_app_ensure_series_cover	(	mdl_fetch_ctx_t *	ctx,
		const char *	series_directory )

Ensure series state names one verified cached or freshly fetched cover.

Applies robots/governor policy, revalidates through the per-host cache when bound, and publishes only magic-typed complete image bytes.

Parameters

[in,out]	ctx	Fully configured fetch context.
[in]	series_directory	Canonical absolute series directory.

Returns

Canonical cache, policy, network, or publication status.

Return values

k_ra8_ok	No cover is configured or a verified local cover exists.
k_ra8_err_invalid_arg	A required binding, URL, or path is invalid.
k_ra8_err_validation_failed	Returned bytes are not a supported image.
other	Cache, governor, network, diagnostic, or storage work failed.

Precondition

Both pointers are non-NULL and the directory is canonical.

Application state and storage bindings are initialized and exclusive.

Postcondition

Success with a configured URL names a verified local cover.

Failure leaves no active cover publication transaction.

Note

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

Since

0.1.0

Definition at line 274 of file mdl_app_cover.c.

References mdl_fetch_ctx_t::cache, mdl_site_t::img_delay_max, mdl_site_t::img_delay_min, internal_cover_cached(), internal_cover_current(), internal_cover_stream(), k_fw_fs_path_cap, k_mdl_gov_host_max, k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_path_join(), mdl_session_url_allowed(), mdl_url_host(), priv_mdl_app_context(), RA8_PRIV, mdl_fetch_ctx_t::refetch, mdl_fetch_ctx_t::session, and mdl_fetch_ctx_t::site.

Referenced by internal_run_prepared().

priv_mdl_app_prepare_chapters()

ra8_err_t priv_mdl_app_prepare_chapters	(	const mdl_site_t *	site,
		const char *	series_url,
		uint32_t	timeout,
		mdl_cache_t *	cache )

Fetch and extract a series' bounded chapter list.

Applies the selected descriptor and governed session to the series document, replacing the shared chapter list only with validated URLs.

Parameters

[in]	site	Selected site descriptor.
[in]	series_url	Canonical series URL.
[in]	timeout	Per-request timeout in milliseconds.
[in,out]	cache	Bound persistent HTTP cache and index workspace.

Returns

Canonical downloader status.

Return values

k_ra8_ok	The operation completed.
other	Validation, capacity, network, or storage failed.

Precondition

Required pointer arguments remain valid for the call duration.

The bound application context is exclusively owned by this thread.

Postcondition

No ownership of caller-provided storage is transferred.

The call completes synchronously before returning to its dispatcher.

Note

The function performs no dynamic allocation and retains no caller pointer.

Since

0.1.0

Fetch and extract a series' bounded chapter list.

Enforces session policy, extracts descriptor metadata and anchors, then filters cross-series links and applies configured ordering.

Parameters

[in]	site	Validated site descriptor.
[in]	series_url	Absolute series page URL.
[in]	timeout	Per-request timeout in milliseconds.
[in,out]	cache	Bound persistent HTTP cache and index workspace.

Returns

An ra8_err_t preparation result.

Return values

k_ra8_ok	Metadata and chapter rows were prepared.
k_ra8_fail	Session policy refused the series URL.
k_ra8_err_invalid_size	A configured prefix or extracted field exceeded its bound.
other	Fetch, extraction, validation, or ordering failed.

Precondition

site and series_url are non-NULL.

priv_mdl_app_context()->session is initialized and timeout is nonzero.

Postcondition

Success replaces priv_mdl_app_context()->chapters and priv_mdl_app_context()->series_metadata.

Failure prevents the caller from starting chapter downloads.

Note

Not thread-safe because it uses process-global bounded buffers.

Since

0.1.0

Definition at line 547 of file mdl_app_prepare.c.

References mdl_site_t::chapter_url_contains, internal_extract_series_metadata(), internal_prepare_cache_fetch(), internal_prepare_filter_chapters(), k_ra8_fail, k_ra8_ok, mdl_cache_get_buf(), mdl_extract_anchors(), mdl_session_url_allowed(), priv_mdl_app_context(), priv_mdl_app_report_cache(), RA8_PRIV, mdl_app_context_t::session, and mdl_session_t::user_agent.

Referenced by internal_run_series_network().

priv_mdl_app_prepare_series_dir()

bool priv_mdl_app_prepare_series_dir	(	const char *	out_dir,
		const char *	series_url,
		char *	slug,
		size_t	slug_cap,
		char *	abs_dir )

Prepare a contained canonical directory for one series.

Derives and sanitizes the URL identity, creates the series directory through injected storage, and returns its canonical absolute path.

Parameters

[in]	out_dir	Output-library root path.
[in]	series_url	Canonical series URL.
[out]	slug	Receives the sanitized stable series identifier.
[in]	slug_cap	Capacity of slug in bytes.
[out]	abs_dir	Receives the canonical absolute series directory.

Returns

Whether the requested condition or operation succeeded.

Return values

true	The condition holds or the operation completed.
false	Input was rejected or the condition does not hold.

Precondition

Required pointer arguments remain valid for the call duration.

slug and abs_dir reference their fixed application capacities.

Postcondition

No ownership of caller-provided storage is transferred.

Success returns a directory contained beneath out_dir.

Note

The function performs no dynamic allocation and retains no caller pointer.

Since

0.1.0

Prepare a contained canonical directory for one series.

Derives the bounded URL slug, joins it under the canonical output root, creates both directories as needed, rejects a symbolic-link leaf, and proves the resolved series path remains contained.

Parameters

[in]	out_dir	Output library root.
[in]	series_url	Absolute series URL used to derive the slug.
[out]	slug	Destination for the series slug.
[in]	slug_cap	Writable capacity of slug.
[out]	abs_dir	Destination for the canonical directory path.

Returns

Whether the directory was safely prepared.

Return values

true	slug and abs_dir contain complete results.
false	Joining, creation, or canonicalization failed.

Precondition

All pointer arguments are non-NULL.

Output buffers satisfy their documented bounded capacities.

Postcondition

Success leaves a real series directory strictly beneath the output root.

Failure is reported and callers do not use abs_dir.

Note

Not safe for concurrent mutation of the same filesystem path.

Since

0.1.0

Definition at line 657 of file mdl_app_prepare.c.

References internal_prepare_diag3(), k_fw_fs_path_cap, k_ra8_ok, mdl_join_dir_under(), mdl_urlname_last_segment(), priv_mdl_app_context(), priv_mdl_app_storage_ensure_directory(), RA8_PRIV, and mdl_app_context_t::storage.

Referenced by internal_run_series_paths().

priv_mdl_app_report_cache()

ra8_err_t priv_mdl_app_report_cache	(	const char *	url,
		const mdl_cache_result_t *	result )

Report corruption recovery or verified cache reuse with staleness.

Emits a rebuild warning and, for retained-body reuse, the exact age, observed status, and URL through the bound diagnostic stream.

Parameters

[in]	url	Exact cached URL.
[in]	result	Completed cache outcome.

Returns

Canonical diagnostic-stream status.

Return values

k_ra8_ok	Every applicable diagnostic was accepted.
other	The diagnostic stream rejected a write.

Precondition

Both pointers are non-NULL and the application diagnostic is bound.

result came from one completed mdl_cache_get_buf call.

Postcondition

Reuse emits one complete staleness line.

Non-reuse emits only a corruption-rebuild warning when applicable.

Note

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

Since

0.1.0

Report corruption recovery or verified cache reuse with staleness.

Parameters

[in]	url	Exact cached URL.
[in]	result	Completed cache outcome.

Returns

First diagnostic-stream status.

Precondition

Both pointers are non-NULL.

Shared diagnostic stream is bound.

Postcondition

Reuse emits one line containing age and status.

Non-reuse emits only a corruption-rebuild warning when applicable.

Note

Output failure is propagated to the caller.

Since

0.1.0

Definition at line 61 of file mdl_app_prepare.c.

References mdl_cache_result_t::age_seconds, mdl_cache_result_t::body_reused, mdl_app_context_t::diagnostic, mdl_cache_result_t::index_rebuilt, k_ra8_ok, mdl_cache_result_t::observed_status, priv_mdl_app_context(), priv_mdl_stream_text(), priv_mdl_stream_u64(), and RA8_PRIV.

Referenced by internal_cover_cached(), and priv_mdl_app_prepare_chapters().

priv_mdl_app_start_session()

ra8_err_t priv_mdl_app_start_session	(	mdl_net_iface_t *	net,
		const mdl_run_opts_t *	opts,
		const char *	cfg_contact,
		char *	ua,
		size_t	ua_cap )

Initialize one bounded network-policy session.

Builds the identifying user agent in ua, applies contact and run policy, and binds net without retaining temporary input storage.

Parameters

[out]	net	Injected network interface to configure.
[in]	opts	Validated network and execution policy.
[in]	cfg_contact	Configured contact identity for governed requests.
[out]	ua	Receives the NUL-terminated user-agent string.
[in]	ua_cap	Capacity of ua in bytes.

Precondition

Required pointer arguments remain valid for the call duration.

ua references ua_cap writable bytes and net is uninitialized.

Postcondition

No ownership of caller-provided storage is transferred.

ua is NUL-terminated and net reflects the complete session policy.

Note

The function performs no dynamic allocation and retains no caller pointer.

Since

0.1.0

Returns

Operation status.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Initialize one bounded network-policy session.

Applies CLI-over-descriptor contact precedence and builds the bounded user agent before configuring robots enforcement.

Parameters

[in,out]	net	Initialized network interface.
[in]	opts	Validated run policy.
[in]	cfg_contact	Optional descriptor contact string.
[out]	ua	User-agent buffer.
[in]	ua_cap	Writable capacity of ua.

Precondition

net, opts, and ua are non-NULL.

ua_cap is the true writable user-agent capacity.

Postcondition

priv_mdl_app_context()->session references net and the completed identity.

Missing contact emits at most one process warning.

Note

Not thread-safe because it replaces priv_mdl_app_context()->session.

Since

0.1.0

Definition at line 612 of file mdl_app_prepare.c.

References mdl_run_opts_t::contact, mdl_run_opts_t::honor_robots, internal_warn_no_contact(), k_ra8_ok, mdl_session_build_ua(), mdl_session_init(), priv_mdl_app_context(), and RA8_PRIV.

Referenced by internal_fetch_artifact(), internal_run_series_network(), mdl_app_run_discover(), and mdl_app_run_page().

priv_mdl_app_state_path_of()

bool priv_mdl_app_state_path_of	(	const char *	abs_dir,
		char *	out,
		size_t	cap )

Compose the state-journal path within a series directory.

Joins the fixed state filename to abs_dir and rejects truncation; no file is opened or published by this helper.

Parameters

[in]	abs_dir	Canonical absolute series directory.
[out]	out	Caller-provided result storage.
[in]	cap	Capacity of the associated output buffer in bytes.

Returns

Whether the requested condition or operation succeeded.

Return values

true	The condition holds or the operation completed.
false	Input was rejected or the condition does not hold.

Precondition

Required pointer arguments remain valid for the call duration.

out references cap writable bytes.

Postcondition

No ownership of caller-provided storage is transferred.

Success leaves out NUL-terminated within cap.

Note

The function performs no dynamic allocation and retains no caller pointer.

Since

0.1.0

Compose the state-journal path within a series directory.

Uses checked formatting and rejects every truncated result.

Parameters

[in]	abs_dir	Canonical series directory.
[out]	out	Destination path buffer.
[in]	cap	Writable capacity of out.

Returns

Whether the complete state path fit.

Return values

true	out contains the NUL-terminated path.
false	Formatting failed or required at least cap bytes.

Precondition

abs_dir and out are non-NULL.

cap is the true capacity of out.

Postcondition

Success appends exactly /.mdl_state.

No filesystem object is created or modified.

Note

Thread-safe for distinct output buffers.

Since

0.1.0

Definition at line 138 of file mdl_app_series.c.

References RA8_PRIV.

Referenced by internal_resolve_removal_target(), and internal_run_series_paths().