Tracked-library list, remove, and update-all actions. More...

#include "mdl_app_internal.h"

Include dependency graph for mdl_app_library.c:

Data Structures
struct	list_ctx_t
struct	update_all_ctx_t
	Context threaded through internal_update_all_cb for --update-all. More...

Functions
static ra8_err_t	internal_library_text3 (ra8_io_stream_t stream, const char first, const char second, const char third)
	Write up to three borrowed fragments through one selected sink.
static ra8_err_t	internal_library_report (const char *action, ra8_err_t error)
	Report a portable library-enumeration failure in user-facing terms.
static ra8_err_t	internal_list_cb (const char series_dir, const char state_path, const mdl_state_t state, void ctx, bool *out_continue)
	Print one tracked series for library-list mode.
int	mdl_app_run_list (const char *out_dir)
	List every tracked series under one library root.
static bool	internal_resolve_removal_target (const char out_dir, const char url_or_slug, char *dir)
	Resolve and authenticate one tracked library-removal target.
int	mdl_app_run_remove (const char out_dir, const char url_or_slug)
	Remove one explicitly tracked series directory.
static ra8_err_t	internal_update_all_cb (const char series_dir, const char state_path, const mdl_state_t state, void ctx, bool *out_continue)
	Incrementally update one visited tracked series.
int	mdl_app_run_update_all (const mdl_series_run_t *base)
	Incrementally update every tracked series under a library root.

Detailed Description

Tracked-library list, remove, and update-all actions.

Enumerates only verified state markers through injected storage and dispatches the selected bounded management action synchronously.

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

Definition in file mdl_app_library.c.

Function Documentation

◆ internal_library_report()

ra8_err_t internal_library_report	(	const char *	action,
		ra8_err_t	error )

static

Report a portable library-enumeration failure in user-facing terms.

Parameters

[in]	action	Human-readable action that failed.
[in]	error	Canonical library error.

Precondition: action is non-NULL and NUL-terminated.; error is not k_ra8_ok.

Postcondition: One actionable diagnostic is emitted to standard error.; No library or callback state is modified.

Note: Capacity diagnostics use exact observations retained by the workspace.

Since: 0.1.0

Authenticates bounded paths through the injected storage facade. Enumeration or removal failures are reported without claiming success.

Returns: Operation status.

Return values

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

Definition at line 59 of file mdl_app_library.c.

References mdl_library_workspace_t::entry_limit, internal_library_text3(), k_ra8_err_hw_not_ready, k_ra8_err_invalid_size, k_ra8_err_invalid_state, mdl_app_context_t::library_workspace, priv_mdl_app_context(), priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, and mdl_library_workspace_t::required_entries.

Referenced by mdl_app_run_list(), and mdl_app_run_update_all().

◆ internal_library_text3()

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

static

Write up to three borrowed fragments through one selected sink.

Authenticates bounded paths through the injected storage facade. Enumeration or removal failures are reported without claiming success.

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 32 of file mdl_app_library.c.

References k_ra8_ok, priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_library_report(), internal_list_cb(), internal_resolve_removal_target(), internal_update_all_cb(), mdl_app_run_list(), mdl_app_run_remove(), and mdl_app_run_update_all().

◆ internal_list_cb()

ra8_err_t internal_list_cb	(	const char *	series_dir,
		const char *	state_path,
		const mdl_state_t *	state,
		void *	ctx,
		bool *	out_continue )

static

Print one tracked series for library-list mode.

Prints the canonical directory, source URL, and coverage from the state generation authenticated by the library enumerator.

Parameters

[in]	series_dir	Canonical tracked-series directory.
[in]	state_path	Complete .mdl_state path.
[in]	state	Already authenticated state generation.
[in,out]	ctx	Pointer to a list_ctx_t accumulator.
[out]	out_continue	Set true to visit the remaining series.

Returns: Iterator continuation result.

Return values

k_ra8_ok Continue enumeration, including after unreadable state.

Precondition: All pointer arguments are non-NULL.; ctx points to writable list_ctx_t storage.

Postcondition: found increases exactly once.; The callback requests continued enumeration.

Note: Not thread-safe because standard output is shared.

Since: 0.1.0

Definition at line 115 of file mdl_app_library.c.

References list_ctx_t::found, internal_library_text3(), k_cov_bytes, k_ra8_ok, mdl_state_coverage(), priv_mdl_app_context(), priv_mdl_stream_text(), RA8_INTERNAL, and mdl_state_t::series_url.

Referenced by mdl_app_run_list().

◆ internal_resolve_removal_target()

bool internal_resolve_removal_target	(	const char *	out_dir,
		const char *	url_or_slug,
		char *	dir )

static

Resolve and authenticate one tracked library-removal target.

Parameters

[in]	out_dir	Library root.
[in]	url_or_slug	User-selected series URL or slug.
[out]	dir	Complete confined target directory.

Returns: Whether dir names the authenticated tracked series.

Return values

true	The target is a real directory with matching authenticated state.
false	The path, marker, state, or recorded identity was rejected.

Precondition: All pointers are non-NULL; dir covers k_dir_path_bytes bytes.

Postcondition: Success authorizes only the later guarded removal call.; Failure does not mutate the library.

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

Since: 0.1.0

Authenticates bounded paths through the injected storage facade. Enumeration or removal failures are reported without claiming success.

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

Definition at line 182 of file mdl_app_library.c.

References fw_fs_stat_t::exists, fw_fs_stat(), internal_library_text3(), k_dir_path_bytes, k_fw_fs_node_directory, k_ra8_ok, k_slug_bytes, mdl_path_join(), mdl_state_load_authenticated(), mdl_state_probe(), mdl_urlname_last_segment(), priv_mdl_app_context(), priv_mdl_app_state_path_of(), strcmp(), and fw_fs_stat_t::type.

Referenced by mdl_app_run_remove().

◆ internal_update_all_cb()

ra8_err_t internal_update_all_cb	(	const char *	series_dir,
		const char *	state_path,
		const mdl_state_t *	state,
		void *	ctx,
		bool *	out_continue )

static

Incrementally update one visited tracked series.

Uses authenticated URL/config identity, derives a run from the caller's template, and records success or a nonfatal series failure.

Parameters

[in]	series_dir	Canonical tracked-series directory.
[in]	state_path	Complete .mdl_state path.
[in]	state	Already authenticated state generation.
[in,out]	ctx	Pointer to an update_all_ctx_t accumulator.
[out]	out_continue	Set true to visit the remaining series.

Returns: Iterator continuation result.

Return values

k_ra8_ok Continue enumeration after either outcome.

Precondition: All pointer arguments are non-NULL.; ctx points to a valid template and writable counters.

Postcondition: Exactly one of updated or failed increases.; Unreadable or incomplete identity is never overwritten.

Note: Not thread-safe because it invokes mdl_app_run_series with shared state.

Since: 0.1.0

Definition at line 287 of file mdl_app_library.c.

References update_all_ctx_t::base, mdl_series_run_t::cfg_path, mdl_state_t::config_path, update_all_ctx_t::failed, internal_library_text3(), k_mdl_cfgpath_max, k_mdl_url_max, k_ra8_ok, mdl_app_run_series(), priv_mdl_app_context(), RA8_INTERNAL, mdl_state_t::series_url, and update_all_ctx_t::updated.

Referenced by mdl_app_run_update_all().

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

Data Structures

Functions

Detailed Description

Function Documentation

◆ internal_library_report()

◆ internal_library_text3()

◆ internal_list_cb()

◆ internal_resolve_removal_target()

◆ internal_update_all_cb()

◆ mdl_app_run_list()

◆ mdl_app_run_remove()

◆ mdl_app_run_update_all()