mdl_app_series.c File Reference

Series selection, download lifecycle, and export actions. More...

#include "mdl_app_internal.h"
#include "mdl_fetch_body_internal.h"

Include dependency graph for mdl_app_series.c:

Go to the source code of this file.

Data Structures
struct	series_prior_metadata_t
	Persisted descriptive fields retained across selector misses. More...

Functions
static ra8_err_t	internal_series_text3 (ra8_io_stream_t *stream, const char *first, const char *second, const char *third)
	Append three borrowed series-report fragments to one stream.
static bool	internal_list_range (const mdl_url_list_t *l, double *lo, double *hi)
	Determine the inclusive numeric range of a chapter list.
static void	internal_select_window (bool from_present, double from_num, size_t count, mdl_url_list_t *out)
	Select a bounded chapter window from the prepared list.
bool	priv_mdl_app_state_path_of (const char *abs_dir, char *out, size_t cap)
	Compose the absolute .mdl_state path for a series.
static bool	internal_copy_metadata_text (char *dst, size_t cap, const char *src)
	Copy one complete string into a fixed metadata field.
static bool	internal_build_export_metadata (const char *abs_dir, const mdl_chapter_rec_t *rec, mdl_export_meta_t *meta)
	Convert persisted series/chapter state into exporter metadata.
static size_t	internal_export_fresh_separate (mdl_format_t format, const char *abs_dir, const mdl_url_list_t *sel, int64_t run_start)
	Export every newly completed selected chapter separately.
static ra8_err_t	internal_report_stats (const char *abs_dir, const mdl_fetch_stats_t *st)
	Print the per-run download tally.
static mdl_fetch_layout_t	internal_choose_layout (const mdl_series_run_t *r, const mdl_url_list_t *sel, char *combined_rel, size_t cap, const char *slug)
	Choose output layout and its combined directory name.
static mdl_fetch_ctx_t	internal_make_ctx (const mdl_series_run_t *r, const mdl_site_t *site, const char *abs_dir, const char *state_path, mdl_governor_t *gov, mdl_cache_t *cache)
	Assemble a fetch context over the shared bounded buffers.
static size_t	internal_export_after (const mdl_series_run_t *r, const char *abs_dir, mdl_fetch_layout_t layout, const char *combined_rel, const mdl_url_list_t *sel, const mdl_fetch_stats_t *stats, int64_t run_start)
	Package freshly downloaded output according to the selected layout.
static ra8_err_t	internal_save_series_state (const char *state_path, const char *failure)
	Save the shared series state and report a contextual failure.
static void	internal_report_cover_failure (ra8_err_t error)
	Report a failed series-cover acquisition with its exact error code.
static ra8_err_t	internal_select_run_window (const mdl_series_run_t *r, const mdl_url_list_t **out_sel)
	Resolve the chapter-selection window for one prepared run.
static int	internal_run_prepared (const mdl_series_run_t *r, const mdl_site_t *site, const char *abs_dir, const char *state_path, mdl_cache_t *cache)
	Drive one prepared series through fetch, checkpoint, and export.
static void	internal_snapshot_prior_metadata (series_prior_metadata_t *prior)
	Snapshot metadata that may survive a temporary selector miss.
static bool	internal_reconcile_series_state (const mdl_series_run_t *run, const mdl_site_t *site, const series_prior_metadata_t *prior)
	Reconcile freshly scraped metadata with validated persisted state.
static int	internal_run_series_paths (const mdl_series_run_t *run, const mdl_site_t *site, mdl_cache_t *cache)
	Prepare paths, load state, reconcile metadata, and run one series.
static int	internal_run_series_network (const mdl_series_run_t *run, mdl_site_t *site)
	Run one prepared descriptor through the network-backed series flow.
int	mdl_app_run_series (const mdl_series_run_t *r)
	Execute one prepared series download.

Variables
static mdl_url_list_t	s_selected
	Selected chapter window for non-update downloads.
static mdl_fetch_faillog_t	s_faillog
	Bounded failure log for the active series run.

Detailed Description

Series selection, download lifecycle, and export actions.

Reconciles validated persistent state with scraped metadata, selects chapters by identity, fetches them, checkpoints, and exports results.

Copyright

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

Definition in file mdl_app_series.c.

Function Documentation

internal_build_export_metadata()

bool internal_build_export_metadata ( const char * abs_dir, const mdl_chapter_rec_t * rec, mdl_export_meta_t * meta )

static

Convert persisted series/chapter state into exporter metadata.

The series source URL is copied without truncation and the local cover leaf is resolved beneath the already-canonical series directory. A deterministic identifier folds the series URL and, for separate output, the chapter URL; the exporter derives modified time from verified page files.

Parameters

[in]	abs_dir	Canonical absolute series directory.
[in]	rec	Chapter record, or NULL for a combined series container.
[out]	meta	Exporter metadata to initialise and populate.

Returns

Whether every persisted field and composed path fit exactly.

Return values

true	meta is ready for a bounded exporter call.
false	A field/path exceeded the corresponding exporter contract.

Precondition

abs_dir and meta are non-NULL.

priv_mdl_app_context()->state has passed state validation and rec belongs to it or is NULL.

Postcondition

On true, no exporter field contains a silently truncated value.

No filesystem object or persistent state is modified.

Note

Not thread-safe: reads process-global priv_mdl_app_context()->state.

Since

0.1.0

Definition at line 206 of file mdl_app_series.c.

References mdl_export_meta_t::artist, mdl_export_meta_t::chapter_number, mdl_export_meta_t::chapter_title, mdl_export_meta_t::cover_path, mdl_export_meta_t::identifier, internal_copy_metadata_text(), k_mdl_read_ltr, k_mdl_read_rtl, k_mdl_state_read_rtl, mdl_export_meta_t::language, mdl_hash_bytes_seed(), mdl_hash_str(), mdl_meta_init(), mdl_path_join(), mdl_chapter_rec_t::number, mdl_chapter_rec_t::number_known, priv_mdl_app_context(), RA8_INTERNAL, mdl_export_meta_t::reading_direction, mdl_state_t::reading_direction, mdl_export_meta_t::series_title, mdl_chapter_rec_t::source_url, mdl_export_meta_t::source_url, mdl_app_context_t::state, strlen(), mdl_export_meta_t::summary, mdl_chapter_rec_t::title, and mdl_export_meta_t::writer.

Referenced by internal_export_after(), and internal_export_fresh_separate().

internal_choose_layout()

mdl_fetch_layout_t internal_choose_layout ( const mdl_series_run_t * r, const mdl_url_list_t * sel, char * combined_rel, size_t cap, const char * slug )

static

Choose output layout and its combined directory name.

Forces separate layout for updates, loose output, or explicit separation; otherwise names the combined range deterministically.

Parameters

[in]	r	Validated series-run parameters.
[in]	sel	Selected chapter URLs.
[out]	combined_rel	Combined relative directory leaf.
[in]	cap	Writable capacity of combined_rel.
[in]	slug	Sanitized series slug.

Returns

Selected mdl_fetch_layout_t value.

Return values

k_mdl_layout_separate	Chapters use individual directories.
k_mdl_layout_combined	Chapters share the named directory.

Precondition

All pointer arguments are non-NULL.

cap is the true output capacity and inputs are bounded.

Postcondition

Separate layout clears combined_rel.

Combined layout writes a deterministic NUL-terminated leaf.

Note

Thread-safe for distinct output buffers.

Since

0.1.0

Definition at line 363 of file mdl_app_series.c.

References mdl_series_run_t::combine, mdl_url_list_t::count, mdl_series_run_t::format, internal_list_range(), k_mdl_format_loose, k_mdl_layout_combined, k_mdl_layout_separate, RA8_INTERNAL, and mdl_series_run_t::update.

Referenced by internal_run_prepared().

internal_copy_metadata_text()

bool internal_copy_metadata_text ( char * dst, size_t cap, const char * src )

static

Copy one complete string into a fixed metadata field.

Uses a checked bounded write and clears the destination on overflow, so callers can never consume a plausible-looking truncated field.

Parameters

[out]	dst	Destination field.
[in]	cap	Writable byte capacity of dst.
[in]	src	NUL-terminated source.

Returns

Whether the complete source fit.

Return values

true	dst contains the complete source.
false	An argument was invalid or truncation would occur.

Precondition

dst and src are non-NULL.

cap is the true writable capacity of dst.

Postcondition

On true, dst is NUL-terminated and equals src.

On false with nonzero cap, dst is an empty string.

Note

Thread-safe: writes only caller-owned storage.

Since

0.1.0

Definition at line 168 of file mdl_app_series.c.

References RA8_INTERNAL.

Referenced by internal_build_export_metadata().

internal_export_after()

size_t internal_export_after ( const mdl_series_run_t * r, const char * abs_dir, mdl_fetch_layout_t layout, const char * combined_rel, const mdl_url_list_t * sel, const mdl_fetch_stats_t * stats, int64_t run_start )

static

Package freshly downloaded output according to the selected layout.

Skips loose output, exports one combined container when requested, or delegates current-run chapters to separate packaging.

Parameters

[in]	r	Validated series-run parameters.
[in]	abs_dir	Canonical series directory.
[in]	layout	Completed fetch layout.
[in]	combined_rel	Combined directory leaf when applicable.
[in]	sel	Selected chapter URLs.
[in]	stats	Completed fetch statistics.
[in]	run_start	Current-run timestamp boundary.

Returns

Number of packaging failures.

Return values

0	Packaging succeeded or loose output required none.
positive	Metadata or exporter work failed.

Precondition

All pointer arguments are non-NULL.

priv_mdl_app_context()->state and priv_mdl_app_context()->export_ws are initialized.

Postcondition

Successful container outputs are atomically published.

A metadata overflow is reported as an export failure.

Note

Not thread-safe because it uses shared exporter storage.

Since

0.1.0

Definition at line 455 of file mdl_app_series.c.

References mdl_run_opts_t::allow_incomplete, mdl_series_run_t::format, internal_build_export_metadata(), internal_export_fresh_separate(), k_mdl_format_loose, k_mdl_layout_combined, k_ra8_ok, mdl_pack_combined_meta(), mdl_series_run_t::opts, priv_mdl_app_context(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_run_prepared().

internal_export_fresh_separate()

size_t internal_export_fresh_separate ( mdl_format_t format, const char * abs_dir, const mdl_url_list_t * sel, int64_t run_start )

static

Export every newly completed selected chapter separately.

Resolves each selected URL to persisted state and exports only complete records fetched during the current run.

Parameters

[in]	format	Requested supported export format.
[in]	abs_dir	Canonical series directory.
[in]	sel	Selected chapter URL list.
[in]	run_start	Current-run timestamp boundary.

Returns

Number of metadata or exporter failures.

Return values

0	Every eligible chapter exported successfully.
positive	One or more eligible chapters failed.

Precondition

abs_dir and sel are non-NULL.

priv_mdl_app_context()->state and priv_mdl_app_context()->export_ws are initialized.

Postcondition

Ineligible or older chapters are not exported.

Persistent chapter state is unchanged.

Note

Not thread-safe because it uses shared state and workspace.

Since

0.1.0

Definition at line 276 of file mdl_app_series.c.

References mdl_chapter_rec_t::complete, mdl_url_list_t::count, mdl_chapter_rec_t::fetched_at, internal_build_export_metadata(), internal_series_text3(), k_mdl_chapter_id_max, mdl_pack_one_meta(), mdl_state_find_chapter(), mdl_urlname_last_segment(), priv_mdl_app_context(), RA8_INTERNAL, and mdl_url_list_t::urls.

Referenced by internal_export_after().

internal_list_range()

bool internal_list_range ( const mdl_url_list_t * l, double * lo, double * hi )

static

Determine the inclusive numeric range of a chapter list.

Parses every URL before updating the caller's minimum and maximum.

Parameters

[in]	l	Chapter URL list.
[out]	lo	Minimum parsed chapter number.
[out]	hi	Maximum parsed chapter number.

Returns

Whether a complete nonempty numeric range was available.

Return values

true	lo and hi hold the complete range.
false	The list was empty or a URL lacked a number.

Precondition

l, lo, and hi are non-NULL.

Every populated URL row is NUL-terminated.

Postcondition

Outputs are initialized even when the list is empty.

The input list is never modified.

Note

Thread-safe for distinct caller-owned inputs and outputs.

Since

0.1.0

Definition at line 62 of file mdl_app_series.c.

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

Referenced by internal_choose_layout().

internal_make_ctx()

mdl_fetch_ctx_t internal_make_ctx ( const mdl_series_run_t * r, const mdl_site_t * site, const char * abs_dir, const char * state_path, mdl_governor_t * gov, mdl_cache_t * cache )

static

Assemble a fetch context over the shared bounded buffers.

Connects validated run/site inputs to session, state, governor, scratch tables, failure log, and the requested progress callback.

Parameters

[in]	r	Validated series-run parameters.
[in]	site	Validated site descriptor.
[in]	abs_dir	Canonical series directory.
[in]	state_path	Complete state-file path.
[in,out]	gov	Initialized request governor.
[in,out]	cache	Bound persistent HTTP cache and index workspace.

Returns

Fully populated fetch context by value.

Return values

mdl_fetch_ctx_t

Context referencing the supplied and shared storage.

Precondition

All pointer arguments are non-NULL and outlive the fetch run.

priv_mdl_app_context()->session and shared bounded buffers are initialized.

Postcondition

The returned context owns no dynamically allocated memory.

No request or filesystem mutation has yet occurred.

Note

Not thread-safe because the context references process-global storage.

Since

0.1.0

Definition at line 403 of file mdl_app_series.c.

References mdl_app_context_t::diagnostic, mdl_app_context_t::images, k_ra8_ok, mdl_report_progress(), mdl_report_progress_bar(), mdl_series_run_t::opts, mdl_app_context_t::output, mdl_app_context_t::page, priv_mdl_app_context(), mdl_run_opts_t::progress, RA8_INTERNAL, mdl_run_opts_t::refetch, s_faillog, mdl_series_run_t::series_url, mdl_app_context_t::session, mdl_app_context_t::state, mdl_app_context_t::storage, mdl_series_run_t::timeout, and mdl_series_run_t::update.

Referenced by internal_run_prepared().

internal_reconcile_series_state()

bool internal_reconcile_series_state ( const mdl_series_run_t * run, const mdl_site_t * site, const series_prior_metadata_t * prior )

static

Reconcile freshly scraped metadata with validated persisted state.

Computes reconcile series state from bounded state records without allocation; persistent publication remains the responsibility of the injected storage transaction.

Parameters

[in]	run	Active series identity and descriptor path.
[in]	site	Loaded site descriptor.
[in]	prior	Snapshot of reusable prior descriptive fields.

Returns

Whether the complete metadata tuple fit persistent state.

Return values

true	State now contains the reconciled metadata tuple.
false	At least one bounded field rejected the complete value.

Precondition

All pointer arguments are non-NULL and shared state is loaded.

prior was produced by internal_snapshot_prior_metadata.

Postcondition

Required identity fields always reflect the current run.

Optional selector misses preserve the corresponding prior value.

Note

Not thread-safe because it mutates the shared series state.

Since

0.1.0

Definition at line 704 of file mdl_app_series.c.

References mdl_series_metadata_t::artist, series_prior_metadata_t::artist, series_prior_metadata_t::cover_path, mdl_series_metadata_t::cover_url, mdl_series_metadata_t::direction, mdl_site_t::host, k_ra8_ok, mdl_series_metadata_t::language, mdl_state_set_series(), mdl_state_set_series_metadata(), mdl_site_t::name, priv_mdl_app_context(), priv_mdl_stream_text(), RA8_INTERNAL, mdl_app_context_t::series_metadata, mdl_app_context_t::state, mdl_series_metadata_t::summary, series_prior_metadata_t::summary, mdl_series_metadata_t::title, series_prior_metadata_t::title, mdl_series_metadata_t::title_selected, mdl_series_metadata_t::writer, and series_prior_metadata_t::writer.

Referenced by internal_run_series_paths().

internal_report_cover_failure()

void internal_report_cover_failure ( ra8_err_t error )

static

Report a failed series-cover acquisition with its exact error code.

Coordinates caller-owned bounded network, state, and storage objects. Preserves the first failure and publishes only finished cover transactions.

Parameters

[in]

error

Exact failure value to report.

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 530 of file mdl_app_series.c.

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

Referenced by internal_run_prepared().

internal_report_stats()

ra8_err_t internal_report_stats ( const char * abs_dir, const mdl_fetch_stats_t * st )

static

Print the per-run download tally.

Emits chapter and page outcome counts with their output directory.

Parameters

[in]	abs_dir	Canonical series output directory.
[in]	st	Completed fetch statistics.

Precondition

abs_dir and st are non-NULL.

Standard output is available.

Postcondition

Exactly one summary line is attempted.

st and filesystem state remain unchanged.

Note

Output from concurrent callers may interleave.

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 325 of file mdl_app_series.c.

References mdl_fetch_stats_t::chapters_completed, mdl_fetch_stats_t::chapters_failed, mdl_fetch_stats_t::chapters_skipped, internal_series_text3(), mdl_app_context_t::output, mdl_fetch_stats_t::pages_failed, mdl_fetch_stats_t::pages_fetched, mdl_fetch_stats_t::pages_reused, priv_mdl_app_context(), priv_mdl_stream_text(), priv_mdl_stream_u64(), and RA8_INTERNAL.

Referenced by internal_run_prepared().

internal_run_prepared()

int internal_run_prepared ( const mdl_series_run_t * r, const mdl_site_t * site, const char * abs_dir, const char * state_path, mdl_cache_t * cache )

static

Drive one prepared series through fetch, checkpoint, and export.

Selects the requested window, creates the fetch context, acquires a verified cover, saves state around the fetch, and packages results.

Parameters

[in]	r	Validated series-run parameters.
[in]	site	Validated site descriptor.
[in]	abs_dir	Canonical series directory.
[in]	state_path	Complete state-file path.
[in,out]	cache	Bound persistent HTTP cache and index workspace.

Returns

Process-style status.

Return values

0	Fetch, state saves, and eligible exports all succeeded.
1	Selection, cover, fetch, state, or export work failed.

Precondition

All pointer arguments are non-NULL.

Chapters and series state have been prepared.

Postcondition

A successful run durably checkpoints current state.

Failures are reported and never presented as successful export.

Note

Not thread-safe because it owns the shared run composition state.

Since

0.1.0

Definition at line 594 of file mdl_app_series.c.

References internal_choose_layout(), internal_export_after(), internal_make_ctx(), internal_report_cover_failure(), internal_report_stats(), internal_save_series_state(), internal_select_run_window(), k_leaf_name_bytes, k_mdl_layout_combined, k_ra8_ok, k_slug_bytes, mdl_config_gov_cfg(), mdl_fetch_run(), mdl_governor_init(), mdl_report_failures(), mdl_sanitize_segment(), memset(), priv_mdl_app_context(), priv_mdl_app_ensure_series_cover(), mdl_fetch_ctx_t::progress_error, RA8_INTERNAL, s_faillog, and mdl_series_run_t::seed.

Referenced by internal_run_series_paths().

internal_run_series_network()

int internal_run_series_network ( const mdl_series_run_t * run, mdl_site_t * site )

static

Run one prepared descriptor through the network-backed series flow.

Opens a transport through the injected provider, binds the session, prepares cached chapters, reports the retained count, and runs path/state/export work.

Parameters

[in]	run	Complete validated series-run parameters.
[in]	site	Loaded and policy-adjusted site descriptor.

Returns

Process-style status.

Return values

0	Series processing completed without a reported failure.
1	Network, preparation, output, state, fetch, or export work failed.

Precondition

Both pointers are non-NULL and application streams are bound.

site has already received any requested polite policy overrides.

Postcondition

The network interface is destroyed on every initialized path.

Success leaves the cache and library in fully published states.

Note

The cache index workspace is borrowed exclusively for this call.

Since

0.1.0

Definition at line 809 of file mdl_app_series.c.

References mdl_app_context_t::cache_index, mdl_site_t::contact, mdl_app_context_t::diagnostic, internal_run_series_paths(), k_mdl_ua_max, k_ra8_ok, mdl_net_destroy(), mdl_net_provider_open(), priv_mdl_app_context(), priv_mdl_app_prepare_chapters(), priv_mdl_app_start_session(), priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, and mdl_app_context_t::storage.

Referenced by mdl_app_run_series().

internal_run_series_paths()

int internal_run_series_paths ( const mdl_series_run_t * run, const mdl_site_t * site, mdl_cache_t * cache )

static

Prepare paths, load state, reconcile metadata, and run one series.

Coordinates run series paths with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	run	Active series parameters.
[in]	site	Loaded site descriptor.
[in,out]	cache	Bound persistent HTTP cache and index workspace.

Returns

Process-style series status.

Return values

0	The prepared fetch/export lifecycle succeeded.
1	Path, state, metadata, fetch, or export work failed.

Precondition

run and site are non-NULL and chapters are prepared.

Shared scraped metadata corresponds to run.

Postcondition

Unreadable state is never overwritten.

Successful metadata is checkpointed by internal_run_prepared.

Note

Not thread-safe because it owns the shared series state.

Since

0.1.0

Definition at line 755 of file mdl_app_series.c.

References internal_reconcile_series_state(), internal_run_prepared(), internal_series_text3(), internal_snapshot_prior_metadata(), k_fw_fs_path_cap, k_ra8_ok, k_slug_bytes, mdl_state_load(), priv_mdl_app_context(), priv_mdl_app_prepare_series_dir(), priv_mdl_app_state_path_of(), priv_mdl_stream_hex(), and priv_mdl_stream_text().

Referenced by internal_run_series_network().

internal_save_series_state()

ra8_err_t internal_save_series_state ( const char * state_path, const char * failure )

static

Save the shared series state and report a contextual failure.

Parameters

[in]	state_path	Complete state-file path.
[in]	failure	Diagnostic prefix for a failed save.

Returns

State-save result.

Return values

k_ra8_ok	A new authenticated generation was published.
other	Persistence failed and the diagnostic was attempted.

Precondition

Both strings are non-NULL and NUL-terminated.

Postcondition

Success publishes one complete state generation.

Failure leaves the preceding generation authoritative.

Note

Not thread-safe because it uses shared state and storage.

Since

0.1.0

Coordinates caller-owned bounded network, state, and storage objects. Preserves the first failure and publishes only finished cover transactions.

Precondition

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

Definition at line 505 of file mdl_app_series.c.

References internal_series_text3(), k_ra8_ok, mdl_state_save(), priv_mdl_app_context(), and RA8_INTERNAL.

Referenced by internal_run_prepared().

internal_select_run_window()

ra8_err_t internal_select_run_window ( const mdl_series_run_t * r, const mdl_url_list_t ** out_sel )

static

Resolve the chapter-selection window for one prepared run.

Uses the complete prepared chapter list on an update run; otherwise selects the requested present/from-number window into the shared selection scratch and requires it be non-empty.

Parameters

[in]	r	Validated series-run parameters.
[out]	out_sel	Selected chapter-URL list on success.

Returns

Selection status.

Return values

k_ra8_ok	out_sel names a non-empty selection.
k_ra8_err_invalid_arg	The requested window selected zero chapters.

Precondition

r and out_sel are non-NULL.

The prepared chapter list and app diagnostic sink are available.

Postcondition

On failure a diagnostic explaining the empty selection was emitted.

An update run selects the prepared chapter list itself, unmodified.

Note

Not thread-safe; writes the shared selection-window scratch buffer.

Since

Version 0.1.0

Definition at line 558 of file mdl_app_series.c.

References mdl_app_context_t::chapters, mdl_series_run_t::chapters, mdl_series_run_t::from_num, mdl_series_run_t::from_present, internal_select_window(), k_ra8_err_invalid_arg, k_ra8_ok, priv_mdl_app_context(), priv_mdl_stream_text(), RA8_INTERNAL, s_selected, and mdl_series_run_t::update.

Referenced by internal_run_prepared().

internal_select_window()

void internal_select_window ( bool from_present, double from_num, size_t count, mdl_url_list_t * out )

static

Select a bounded chapter window from the prepared list.

Finds the first requested numeric chapter when present and copies at most count complete URL rows into caller output.

Parameters

[in]	from_present	Whether from_num constrains the first row.
[in]	from_num	Minimum numeric chapter when enabled.
[in]	count	Maximum rows to select.
[out]	out	Selected URL list.

Precondition

out is non-NULL.

priv_mdl_app_context()->chapters contains validated bounded rows.

Postcondition

out->count never exceeds count or the list capacity.

priv_mdl_app_context()->chapters remains unchanged.

Note

Not thread-safe because it reads shared priv_mdl_app_context()->chapters.

Since

0.1.0

Definition at line 101 of file mdl_app_series.c.

References mdl_app_context_t::chapters, mdl_url_list_t::count, k_mdl_url_max, mdl_urlname_chapter_parse(), memcpy(), priv_mdl_app_context(), and mdl_url_list_t::urls.

Referenced by internal_select_run_window().

internal_series_text3()

ra8_err_t internal_series_text3 ( ra8_io_stream_t * stream, const char * first, const char * second, const char * third )

static

Append three borrowed series-report fragments to one stream.

Coordinates caller-owned bounded network, state, and storage objects. Preserves the first failure and publishes only finished cover transactions.

Parameters

[in,out]	stream	Destination stream state.
[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 36 of file mdl_app_series.c.

References k_ra8_ok, priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_export_fresh_separate(), internal_report_stats(), internal_run_series_paths(), internal_save_series_state(), and mdl_app_run_series().

internal_snapshot_prior_metadata()

void internal_snapshot_prior_metadata ( series_prior_metadata_t * prior )

static

Snapshot metadata that may survive a temporary selector miss.

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

Parameters

[out]

prior

Bounded snapshot destination.

Precondition

prior is non-NULL and shared state passed validation.

Current scraped metadata contains the newly selected cover URL.

Postcondition

prior owns complete bounded copies of reusable prior fields.

Cover path is retained only while its source URL is unchanged.

Note

Not thread-safe because it reads the shared series state.

Since

0.1.0

Definition at line 671 of file mdl_app_series.c.

References mdl_state_t::artist, series_prior_metadata_t::artist, mdl_state_t::cover_path, series_prior_metadata_t::cover_path, mdl_series_metadata_t::cover_url, mdl_state_t::cover_url, priv_mdl_app_context(), RA8_INTERNAL, mdl_app_context_t::series_metadata, mdl_state_t::series_title, mdl_app_context_t::state, strcmp(), mdl_state_t::summary, series_prior_metadata_t::summary, series_prior_metadata_t::title, mdl_state_t::writer, and series_prior_metadata_t::writer.

Referenced by internal_run_series_paths().

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

priv_mdl_app_state_path_of()

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

Compose the absolute .mdl_state path for a series.

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

Variable Documentation

s_faillog

mdl_fetch_faillog_t s_faillog

static

Bounded failure log for the active series run.

Definition at line 17 of file mdl_app_series.c.

Referenced by internal_make_ctx(), and internal_run_prepared().

s_selected

mdl_url_list_t s_selected

static

Selected chapter window for non-update downloads.

Definition at line 14 of file mdl_app_series.c.

Referenced by internal_select_run_window().