Descriptor-driven series preparation and safe path setup. More...

#include "mdl_app_internal.h"

Include dependency graph for mdl_app_prepare.c:

Functions
static ra8_err_t	internal_prepare_cache_fetch (void context, const char url, const mdl_net_req_t request, char buffer, size_t capacity, size_t out_length, mdl_net_resp_t response)
	Dispatch one cache request directly through the active network seam.
ra8_err_t	priv_mdl_app_report_cache (const char url, const mdl_cache_result_t result)
	Report verified cache reuse with its pre-request staleness.
static ra8_err_t	internal_prepare_diag3 (const char first, const char second, const char *third)
	Append three borrowed preparation diagnostics.
static void	internal_swap_rows (mdl_url_list_t *l, size_t a, size_t b)
	Swap two rows of a URL list.
static void	internal_reverse_list (mdl_url_list_t *l)
	Reverse a URL list in place.
static bool	internal_sort_by_chapter_num (mdl_url_list_t *l)
	Sort a URL list by parsed chapter number.
static ra8_err_t	internal_apply_order (mdl_url_list_t *l, mdl_chapter_order_t order)
	Apply the configured chapter ordering in place.
static void	internal_filter_prefix (mdl_url_list_t l, const char prefix)
	Keep only list entries whose URL starts with a prefix.
static ra8_err_t	internal_warn_no_contact (void)
	Print the missing-operator-contact warning once.
static ra8_err_t	internal_extract_optional_metadata (const mdl_site_t site, const char html, size_t len)
	Extract the optional summary and creator fields.
static ra8_err_t	internal_extract_cover (const mdl_site_t site, const char series_url, const char *html, size_t len)
	Extract and resolve the configured required cover URL.
static ra8_err_t	internal_extract_series_metadata (const mdl_site_t site, const char series_url, const char *html, size_t len)
	Extract descriptor-driven series metadata from one fetched page.
static ra8_err_t	internal_prepare_filter_chapters (const mdl_site_t site, const char series_url)
	Retain only chapters belonging to the configured series.
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 a series page and build its ordered 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 the shared network session identity for one run.
bool	priv_mdl_app_prepare_series_dir (const char out_dir, const char series_url, char slug, size_t slug_cap, char abs_dir)
	Create and resolve a series directory beneath an output root.

Variables
static char	s_rowtmp [k_mdl_url_max]
	Scratch row used while reordering the prepared chapter list.

Detailed Description

Descriptor-driven series preparation and safe path setup.

Fetches and extracts configured series metadata into fixed buffers, sanitizes identities, and prepares paths contained by the library.

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

Definition in file mdl_app_prepare.c.

Function Documentation

◆ internal_apply_order()

ra8_err_t internal_apply_order	(	mdl_url_list_t *	l,
		mdl_chapter_order_t	order )

static

Apply the configured chapter ordering in place.

Selects document order, reverse order, or validated numeric order.

Parameters

[in,out]	l	URL list to reorder.
[in]	order	Validated descriptor ordering policy.

Precondition: l is non-NULL.; order is a valid mdl_chapter_order_t value.

Postcondition: The requested supported ordering is applied.; Numeric parse failure leaves document order intact and emits a warning.

Note: Not thread-safe because sorting uses shared row scratch.

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.

Definition at line 208 of file mdl_app_prepare.c.

References internal_reverse_list(), internal_sort_by_chapter_num(), k_mdl_order_asc, k_mdl_order_reverse, k_ra8_ok, priv_mdl_app_context(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_prepare_filter_chapters().

◆ internal_extract_cover()

ra8_err_t internal_extract_cover	(	const mdl_site_t *	site,
		const char *	series_url,
		const char *	html,
		size_t	len )

static

Extract and resolve the configured required cover URL.

Coordinates extract cover with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	site	Validated descriptor containing the cover selector.
[in]	series_url	Absolute URL used as the resolution base.
[in]	html	Complete fetched series HTML.
[in]	len	Number of readable bytes at `html`.

Returns: Canonical extraction or validation status.

Return values

k_ra8_ok	No cover was configured, or it resolved safely.
k_ra8_err_validation_failed	The selected cover was not a safe URL.
other	The configured selector did not yield a bounded value.

Precondition: All pointer arguments are non-NULL and html spans len bytes.; Shared series metadata has been cleared for this series.

Postcondition: Success populates the cover URL exactly when a selector is configured.; Failure prevents the series download from starting.

Note: Not thread-safe because it writes shared metadata.

Since: 0.1.0

Definition at line 371 of file mdl_app_prepare.c.

References internal_prepare_diag3(), k_mdl_url_max, k_ra8_err_validation_failed, k_ra8_ok, mdl_extract_resolve_url(), mdl_extract_selector(), priv_mdl_app_context(), priv_mdl_stream_text(), and mdl_site_t::series_cover_selector.

Referenced by internal_extract_series_metadata().

◆ internal_extract_optional_metadata()

ra8_err_t internal_extract_optional_metadata	(	const mdl_site_t *	site,
		const char *	html,
		size_t	len )

static

Extract the optional summary and creator fields.

Coordinates extract optional metadata with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	site	Validated descriptor containing optional selectors.
[in]	html	Complete fetched series HTML.
[in]	len	Number of readable bytes at `html`.

Returns: Canonical extraction status.

Return values

k_ra8_ok	Every configured field fit; misses were cleared and warned.
k_ra8_err_invalid_size	A selected value exceeded its destination.

Precondition: All pointer arguments are non-NULL and html spans len bytes.; Shared series metadata has been cleared for this series.

Postcondition: Successful matches populate their corresponding bounded fields.; Missing optional values remain empty and visible in diagnostics.

Note: Not thread-safe because it writes shared metadata.

Since: 0.1.0

< Validated descriptor selector.

< Bounded destination field.

< Destination byte capacity.

< Diagnostic field name.

Definition at line 300 of file mdl_app_prepare.c.

References mdl_series_metadata_t::artist, internal_prepare_diag3(), k_ra8_err_invalid_size, k_ra8_ok, mdl_extract_selector(), priv_mdl_app_context(), priv_mdl_stream_text(), mdl_site_t::series_artist_selector, mdl_site_t::series_author_selector, mdl_app_context_t::series_metadata, mdl_site_t::series_summary_selector, mdl_series_metadata_t::summary, and mdl_series_metadata_t::writer.

Referenced by internal_extract_series_metadata().

◆ internal_extract_series_metadata()

ra8_err_t internal_extract_series_metadata	(	const mdl_site_t *	site,
		const char *	series_url,
		const char *	html,
		size_t	len )

static

Extract descriptor-driven series metadata from one fetched page.

A missing/unmatched title falls back loudly to the stable URL leaf; optional descriptive fields warn and remain empty. A configured cover is a required contract: it must be found and resolve to an absolute URL, because silently exporting a book without its promised cover is a false success.

Parameters

[in]	site	Validated site descriptor.
[in]	series_url	Absolute URL used as the cover-resolution base.
[in]	html	Complete fetched series HTML.
[in]	len	Number of readable bytes at `html`.

Returns: An ra8_err_t extraction result.

Return values

k_ra8_ok	Metadata was extracted, with documented optional fallbacks.
k_ra8_err_invalid_size	A selected value exceeded its bounded field.
k_ra8_err_validation_failed	A configured cover URL was unsafe.
k_ra8_err_no_data	A configured cover selector matched no value.

Precondition: All pointer arguments are non-NULL and NUL-terminated where applicable.; html addresses at least len readable bytes.

Postcondition: On success, priv_mdl_app_context()->series_metadata contains no stale prior-series values.; On failure, callers do not begin a chapter download.

Note: Not thread-safe: replaces process-global bounded metadata scratch.

Since: 0.1.0

Definition at line 426 of file mdl_app_prepare.c.

References mdl_series_metadata_t::direction, internal_extract_cover(), internal_extract_optional_metadata(), internal_prepare_diag3(), k_mdl_state_read_ltr, k_mdl_state_read_rtl, k_ra8_err_invalid_size, k_ra8_err_no_data, k_ra8_ok, mdl_site_t::language, mdl_extract_selector(), mdl_urlname_last_segment(), memset(), priv_mdl_app_context(), priv_mdl_stream_text(), RA8_INTERNAL, mdl_site_t::reading_direction, mdl_app_context_t::series_metadata, mdl_site_t::series_title_selector, strcmp(), and mdl_series_metadata_t::title_selected.

Referenced by priv_mdl_app_prepare_chapters().

◆ internal_filter_prefix()

void internal_filter_prefix	(	mdl_url_list_t *	l,
		const char *	prefix )

static

Keep only list entries whose URL starts with a prefix.

Compacts matching bounded rows in place while retaining their order.

Parameters

[in,out]	l	URL list to filter.
[in]	prefix	NUL-terminated absolute URL prefix.

Precondition: l and prefix are non-NULL.; Every populated row is NUL-terminated.

Postcondition: l->count equals the number of matching rows.; Surviving rows preserve their relative order.

Note: Not thread-safe when callers concurrently mutate l.

Since: 0.1.0

Definition at line 235 of file mdl_app_prepare.c.

References mdl_url_list_t::count, k_mdl_url_max, memcpy(), RA8_INTERNAL, strlen(), strncmp(), and mdl_url_list_t::urls.

Referenced by internal_prepare_filter_chapters().

◆ internal_prepare_cache_fetch()

ra8_err_t internal_prepare_cache_fetch	(	void *	context,
		const char *	url,
		const mdl_net_req_t *	request,
		char *	buffer,
		size_t	capacity,
		size_t *	out_length,
		mdl_net_resp_t *	response )

static

Dispatch one cache request directly through the active network seam.

Adapts the cache callback signature to the already initialized downloader network interface without retaining any argument.

Parameters

[in,out]	context	Borrowed mdl_net_iface_t pointer.
[in]	url	Exact absolute request URL.
[in]	request	Completed request metadata.
[out]	buffer	Bounded body destination.
[in]	capacity	Writable body capacity.
[out]	out_length	Exact accepted bytes.
[out]	response	Finished response metadata.

Returns: Canonical network status.

Return values

k_ra8_ok	The response and exact body length were published.
other	The network backend rejected or failed the request.

Precondition: All pointers are non-NULL and the network handle is initialized.; buffer spans capacity writable bytes.

Postcondition: Success initializes both output objects.; No argument pointer is retained.

Note: Series indexes currently require no separate governor.

Since: 0.1.0

Definition at line 32 of file mdl_app_prepare.c.

References mdl_net_get_buf(), and RA8_INTERNAL.

Referenced by priv_mdl_app_prepare_chapters().

◆ internal_prepare_diag3()

ra8_err_t internal_prepare_diag3	(	const char *	first,
		const char *	second,
		const char *	third )

static

Append three borrowed preparation diagnostics.

Uses caller-owned application and storage state with injected diagnostics. Returns the first failure without publishing partial preparation.

Parameters

[in]	first	First text fragment.
[in]	second	Second text fragment.
[in]	third	Third text fragment.

Returns: Operation status.

Return values

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

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 107 of file mdl_app_prepare.c.

References mdl_app_context_t::diagnostic, k_ra8_ok, priv_mdl_app_context(), and priv_mdl_stream_text().

Referenced by internal_extract_cover(), internal_extract_optional_metadata(), internal_extract_series_metadata(), and priv_mdl_app_prepare_series_dir().

◆ internal_prepare_filter_chapters()

ra8_err_t internal_prepare_filter_chapters	(	const mdl_site_t *	site,
		const char *	series_url )

static

Retain only chapters belonging to the configured series.

Builds the descriptor-selected absolute prefix, removes relation links outside that prefix, and applies the configured ordering.

Parameters

[in]	site	Validated site descriptor.
[in]	series_url	Absolute series page URL.

Returns: Canonical filtering or ordering status.

Return values

k_ra8_ok	The retained rows are ordered as configured.
k_ra8_err_invalid_size	The bounded prefix cannot be represented.

Precondition: Both pointers are non-NULL and the chapter list is initialized.; Every chapter row is a canonical absolute URL.

Postcondition: Success removes cross-series rows and applies descriptor ordering.; Failure never reads or writes beyond the bounded prefix buffer.

Note: A configured sibling prefix takes precedence over the series URL.

Since: 0.1.0

Definition at line 500 of file mdl_app_prepare.c.

References mdl_site_t::chapter_order, mdl_site_t::chapter_url_prefix, internal_apply_order(), internal_filter_prefix(), k_dir_path_bytes, k_ra8_err_invalid_size, priv_mdl_app_context(), RA8_INTERNAL, and strlen().

Referenced by priv_mdl_app_prepare_chapters().

◆ internal_reverse_list()

void internal_reverse_list ( mdl_url_list_t * l )

static

Reverse a URL list in place.

Exchanges mirrored rows through internal_swap_rows without allocating.

Parameters

[in,out] l URL list to reverse.

Precondition: l is non-NULL.; l->count does not exceed its fixed row capacity.

Postcondition: Row order is exactly reversed.; l->count and row contents remain otherwise unchanged.

Note: Not thread-safe because internal_swap_rows uses shared scratch.

Since: 0.1.0

Definition at line 150 of file mdl_app_prepare.c.

References mdl_url_list_t::count, internal_swap_rows(), and RA8_INTERNAL.

Referenced by internal_apply_order().

◆ internal_sort_by_chapter_num()

bool internal_sort_by_chapter_num ( mdl_url_list_t * l )

static

Sort a URL list by parsed chapter number.

Validates every numeric identifier before performing the in-place selection sort, preserving input order when validation fails.

Parameters

[in,out] l URL list to validate and sort.

Returns: Whether every URL carried a numeric chapter identifier.

Return values

true	The list is sorted in ascending numeric order.
false	At least one identifier was missing and the list is unchanged.

Precondition: l is non-NULL.; l->count fits its fixed row table.

Postcondition: Success orders every existing row without changing the count.; Failure preserves every row and its original position.

Note: Not thread-safe because row swaps use shared scratch.

Since: 0.1.0

Definition at line 172 of file mdl_app_prepare.c.

References mdl_url_list_t::count, internal_swap_rows(), mdl_urlname_chapter_parse(), mdl_urlname_chapter_value(), min, RA8_INTERNAL, and mdl_url_list_t::urls.

Referenced by internal_apply_order().

◆ internal_swap_rows()

void internal_swap_rows	(	mdl_url_list_t *	l,
		size_t	a,
		size_t	b )

static

Swap two rows of a URL list.

Uses the fixed global row scratch so the bounded rows move intact.

Parameters

[in,out]	l	URL list to mutate.
[in]	a	First row index.
[in]	b	Second row index.

Precondition: l is non-NULL and owns complete URL rows.; a and b are smaller than l->count.

Postcondition: The selected rows exchange positions.; All other rows and l->count are unchanged.

Note: Not thread-safe because it uses s_rowtmp.

Since: 0.1.0

Definition at line 128 of file mdl_app_prepare.c.

References k_mdl_url_max, memcpy(), RA8_INTERNAL, s_rowtmp, and mdl_url_list_t::urls.

Referenced by internal_reverse_list(), and internal_sort_by_chapter_num().

◆ internal_warn_no_contact()

ra8_err_t internal_warn_no_contact ( void )

static

Print the missing-operator-contact warning once.

Suppresses duplicate warnings across sessions within one process.

Precondition: Standard error is available for diagnostic output.; The process uses the command-line single-threaded composition root.

Postcondition: The first call marks the warning as emitted.; Later calls produce no output.

Note: Not thread-safe because the one-time flag is function-static.

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.

Definition at line 264 of file mdl_app_prepare.c.

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

Referenced by priv_mdl_app_start_session().

◆ 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 a series page and build its ordered chapter list.

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 )

Create and resolve a series directory beneath an output root.

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 verified cache reuse with its pre-request staleness.

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 the shared network session identity for one run.

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

Variable Documentation

◆ s_rowtmp

char s_rowtmp[k_mdl_url_max]

static

Scratch row used while reordering the prepared chapter list.

Definition at line 88 of file mdl_app_prepare.c.

Referenced by internal_swap_rows().

Functions

Variables

Detailed Description

Function Documentation

◆ internal_apply_order()

◆ internal_extract_cover()

◆ internal_extract_optional_metadata()

◆ internal_extract_series_metadata()

◆ internal_filter_prefix()

◆ internal_prepare_cache_fetch()

◆ internal_prepare_diag3()

◆ internal_prepare_filter_chapters()

◆ internal_reverse_list()

◆ internal_sort_by_chapter_num()

◆ internal_swap_rows()

◆ internal_warn_no_contact()

◆ priv_mdl_app_prepare_chapters()

◆ priv_mdl_app_prepare_series_dir()

◆ priv_mdl_app_report_cache()

◆ priv_mdl_app_start_session()

Variable Documentation

◆ s_rowtmp