Cached series-cover acquisition and validated publication. More...

#include <limits.h>
#include <stdint.h>
#include <string.h>
#include "mdl_app_internal.h"
#include "mdl_fetch_body_internal.h"

Include dependency graph for mdl_app_cover.c:

Functions
static bool	internal_cover_copy (char destination, size_t capacity, const char source)
	Copy one complete cover metadata string.
static bool	internal_cover_current (mdl_fetch_ctx_t ctx, const char series_directory)
	Determine whether the recorded local cover still has image magic.
static ra8_err_t	internal_cover_finish (mdl_fetch_body_t *body, size_t bytes)
	Validate, name, and publish one complete cover body transaction.
static ra8_err_t	internal_cover_publish_cached (mdl_fetch_ctx_t ctx, const char holding, size_t bytes)
	Feed one cached cover buffer into the validated image transaction.
static ra8_err_t	internal_cover_stream (mdl_fetch_ctx_t ctx, const char holding, const char *host, uint32_t minimum_delay, uint32_t maximum_delay)
	Fetch one cover directly into a private image transaction.
static ra8_err_t	internal_cover_cached (mdl_fetch_ctx_t ctx, const char holding, const char *host, uint32_t minimum_delay, uint32_t maximum_delay, bool current)
	Fetch or revalidate one cover through the persistent host cache.
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.

Detailed Description

Cached series-cover acquisition and validated publication.

Revalidates cover URLs through the persistent per-host cache, keeps a verified local cover untouched on reuse, and publishes changed or recovered bytes only after magic-derived typing in one transaction.

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

Definition in file mdl_app_cover.c.

Function Documentation

◆ internal_cover_cached()

ra8_err_t internal_cover_cached	(	mdl_fetch_ctx_t *	ctx,
		const char *	holding,
		const char *	host,
		uint32_t	minimum_delay,
		uint32_t	maximum_delay,
		bool	current )

static

Fetch or revalidate one cover through the persistent host cache.

Uses the governed buffer callback, reports staleness, leaves a verified current cover untouched on reuse, and publishes otherwise.

Parameters

[in,out]	ctx	Active fetch and cache dependencies.
[in]	holding	Canonical requested holding path.
[in]	host	Parsed governor host key.
[in]	minimum_delay	Minimum request delay in milliseconds.
[in]	maximum_delay	Maximum request delay in milliseconds.
[in]	current	Whether a verified local cover already exists.

Returns: Canonical cache, diagnostic, or publication status.

Return values

k_ra8_ok	A current verified cover exists after the call.
other	Cache fetching, reporting, image validation, or publication failed.

Precondition: Every pointer is non-NULL and ctx->cache is initialized.; Robots and URL policy already accepted the cover URL.

Postcondition: A 304/current-body reuse never opens the cover destination for writing.; Changed or recovered bytes use the validated body transaction.

Note: The shared page buffer is free after series metadata extraction.

Since: 0.1.0

Definition at line 234 of file mdl_app_cover.c.

References mdl_cache_result_t::body_reused, mdl_fetch_ctx_t::cache, mdl_fetch_cache_request::host, internal_cover_copy(), internal_cover_publish_cached(), k_ra8_err_invalid_size, k_ra8_ok, mdl_cache_get_buf(), mdl_fetch_ctx_t::page_buf, mdl_fetch_ctx_t::page_cap, priv_mdl_app_context(), priv_mdl_app_report_cache(), priv_mdl_fetch_cache_get_buf(), priv_mdl_fetch_record_fail(), RA8_INTERNAL, mdl_state_t::series_url, mdl_fetch_ctx_t::session, mdl_app_context_t::state, mdl_net_resp_t::status, mdl_fetch_ctx_t::timeout_ms, and mdl_session_t::user_agent.

Referenced by priv_mdl_app_ensure_series_cover().

◆ internal_cover_copy()

bool internal_cover_copy	(	char *	destination,
		size_t	capacity,
		const char *	source )

static

Copy one complete cover metadata string.

Measures before copying so state never retains a truncated body leaf after an otherwise successful publication.

Parameters

[out]	destination	Writable destination field.
[in]	capacity	Destination byte capacity.
[in]	source	NUL-terminated source.

Returns: Whether the complete source fit.

Return values

true	The destination equals the complete source.
false	An argument was invalid or the source was oversized.

Precondition: A non-NULL destination spans capacity bytes.; A non-NULL source is NUL-terminated.

Postcondition: Success leaves a complete NUL-terminated copy.; Failure clears a nonempty destination buffer.

Note: Allocation-free and thread-safe across distinct buffers.

Since: 0.1.0

Definition at line 34 of file mdl_app_cover.c.

References memcpy(), RA8_INTERNAL, and strlen().

Referenced by internal_cover_cached(), and internal_cover_finish().

◆ internal_cover_current()

bool internal_cover_current	(	mdl_fetch_ctx_t *	ctx,
		const char *	series_directory )

static

Determine whether the recorded local cover still has image magic.

Resolves the retained relative path beneath the series directory and accepts it only when the portable sniffer recognizes its bytes.

Parameters

[in,out]	ctx	Active fetch context and storage binding.
[in]	series_directory	Canonical absolute series directory.

Returns: Whether a verified local cover exists.

Return values

true	State names a present supported image.
false	State has no cover or its path/bytes are invalid.

Precondition: Both pointers are non-NULL and the directory is canonical.; State has passed its persistent validation contract.

Postcondition: No state or file content is modified.; True proves the current cover is safe for packaging.

Note: File inspection uses only the injected portable storage facade.

Since: 0.1.0

Definition at line 64 of file mdl_app_cover.c.

References mdl_state_t::cover_path, k_fw_fs_path_cap, k_ra8_ok, mdl_path_join(), mdl_urlname_sniff_file(), priv_mdl_app_context(), RA8_INTERNAL, mdl_app_context_t::state, and mdl_fetch_ctx_t::storage.

Referenced by priv_mdl_app_ensure_series_cover().

◆ internal_cover_finish()

ra8_err_t internal_cover_finish	(	mdl_fetch_body_t *	body,
		size_t	bytes )

static

Validate, name, and publish one complete cover body transaction.

Flushes the retained signature, copies the magic-derived body leaf into state, and commits only after independent staged validation.

Parameters

[in,out]	body	Completed cover body transaction.
[in]	bytes	Exact response-body extent for diagnostics.

Returns: Canonical classification, state, or publication status.

Return values

k_ra8_ok	A validated cover and state leaf are available.
k_ra8_err_invalid_size	The state leaf could not fit.
other	Image classification, diagnostic, commit, or abort failed.

Precondition: body is initialized and exclusively owned.; Every accepted response byte has reached body.

Postcondition: Success publishes exactly one magic-typed cover.; Failure leaves no active cover transaction.

Note: A post-publication error clears the state leaf rather than lying.

Since: 0.1.0

Definition at line 93 of file mdl_app_cover.c.

References mdl_fetch_body_t::actual_rel, mdl_state_t::cover_path, internal_cover_copy(), k_ra8_err_invalid_size, k_ra8_ok, priv_mdl_app_context(), priv_mdl_fetch_body_abort(), priv_mdl_fetch_body_commit(), priv_mdl_fetch_body_prepare(), priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, and mdl_app_context_t::state.

Referenced by internal_cover_publish_cached(), and internal_cover_stream().

◆ internal_cover_publish_cached()

ra8_err_t internal_cover_publish_cached	(	mdl_fetch_ctx_t *	ctx,
		const char *	holding,
		size_t	bytes )

static

Feed one cached cover buffer into the validated image transaction.

Reuses the production body sink so cached bytes follow the same signature, naming, stage-validation, and publication path as a stream.

Parameters

[in,out]	ctx	Active fetch and storage context.
[in]	holding	Canonical requested holding path.
[in]	bytes	Complete cached body extent.

Returns: Canonical body-sink or publication status.

Return values

k_ra8_ok	The cached body became a validated local cover.
k_ra8_err_invalid_size	The body exceeds the sink write width.
other	Sink initialization, writing, validation, or commit failed.

Precondition: ctx and holding are non-NULL.; ctx->page_buf spans at least bytes initialized bytes.

Postcondition: Success publishes exactly the cached bytes once.; Failure attempts to abort every active stage.

Note: This path performs no network operation.

Since: 0.1.0

Definition at line 139 of file mdl_app_cover.c.

References mdl_net_body_sink_t::ctx, internal_cover_finish(), k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, mdl_fetch_ctx_t::page_buf, priv_mdl_fetch_body_abort(), priv_mdl_fetch_body_init_image(), priv_mdl_fetch_body_sink(), mdl_fetch_ctx_t::storage, and mdl_net_body_sink_t::write.

Referenced by internal_cover_cached().

◆ internal_cover_stream()

ra8_err_t internal_cover_stream	(	mdl_fetch_ctx_t *	ctx,
		const char *	holding,
		const char *	host,
		uint32_t	minimum_delay,
		uint32_t	maximum_delay )

static

Fetch one cover directly into a private image transaction.

Preserves the non-cache fallback for callers that intentionally do not supply a cache binding while retaining governed bounded retries.

Parameters

[in,out]	ctx	Active fetch dependencies.
[in]	holding	Canonical requested holding path.
[in]	host	Parsed governor host key.
[in]	minimum_delay	Minimum request delay in milliseconds.
[in]	maximum_delay	Maximum request delay in milliseconds.

Returns: Canonical network or publication status.

Return values

k_ra8_ok	The streamed cover was validated and published.
other	Network, body, diagnostic, or transaction work failed.

Precondition: Every pointer is non-NULL and delay bounds are valid.; Robots and URL policy already accepted the cover URL.

Postcondition: Success names one verified local cover in state.; Failure records the exact transfer failure and aborts its stage.

Note: Used only when ctx->cache == NULL.

Since: 0.1.0

Definition at line 180 of file mdl_app_cover.c.

References internal_cover_finish(), k_ra8_ok, priv_mdl_app_context(), priv_mdl_fetch_body_abort(), priv_mdl_fetch_body_init_image(), priv_mdl_fetch_body_sink(), priv_mdl_fetch_record_fail(), priv_mdl_fetch_with_retry(), RA8_INTERNAL, mdl_state_t::series_url, mdl_fetch_ctx_t::session, mdl_app_context_t::state, mdl_net_resp_t::status, mdl_fetch_ctx_t::storage, mdl_fetch_ctx_t::timeout_ms, and mdl_session_t::user_agent.

Referenced by priv_mdl_app_ensure_series_cover().

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

Functions

Detailed Description

Function Documentation

◆ internal_cover_cached()

◆ internal_cover_copy()

◆ internal_cover_current()

◆ internal_cover_finish()

◆ internal_cover_publish_cached()

◆ internal_cover_stream()

◆ priv_mdl_app_ensure_series_cover()