Portable bounded operations over a tracked media library. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_state.h"
#include "mdl_storage.h"
#include "ra8_err.h"

Include dependency graph for mdl_library.h:

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

Data Structures
struct	mdl_library_policy_t
	Caller-selected limits within the compile-time hard ceilings. More...
struct	mdl_library_workspace_t
	Caller-owned directory cursor storage and iterative traversal stack. More...

Typedefs
typedef ra8_err_t(*	mdl_library_fn) (const char series_dir, const char state_path, const mdl_state_t state, void ctx, bool *out_continue)
	Per-series visitor callback for mdl_library_for_each.

Enumerations
enum	mdl_library_limit_t : uint32_t { k_mdl_library_entry_limit = 100000U , k_mdl_library_operation_limit = 500000U , k_mdl_library_depth_limit = 32U }
	Hard ceilings accepted by the portable library algorithms. More...

Functions
ra8_err_t	mdl_library_workspace_init (mdl_library_workspace_t workspace, void directory_workspace, uint32_t directory_workspace_bytes)
	Bind caller-owned directory storage to a reusable library workspace.
mdl_library_policy_t	mdl_library_policy_default (void)
	Return the production library traversal policy.
ra8_err_t	mdl_library_for_each (mdl_storage_t storage, const char out_dir, mdl_state_t state_scratch, mdl_library_workspace_t workspace, const mdl_library_policy_t policy, mdl_library_fn callback, void callback_ctx)
	Visit every authenticated tracked series under a library root.
ra8_err_t	mdl_library_remove_tree (mdl_storage_t storage, const char dir, const mdl_library_policy_t policy, mdl_library_workspace_t workspace)
	Remove one canonical directory tree through portable namespace calls.

Detailed Description

Portable bounded operations over a tracked media library.

A library is one canonical directory in an injected mdl_storage_t binding. Immediate child directories are tracked only when .mdl_state or its .alt peer contains an authenticated state generation. Enumeration and recursive removal use only fw_fs namespace and stream operations; no host path or allocator-backed directory object crosses this domain seam.

Removal is an iterative post-order walk over caller-owned path storage. The caller also supplies explicit entry, depth, and operation limits, making worst-case work visible at every composition root.

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

Definition in file mdl_library.h.

Typedef Documentation

◆ mdl_library_fn

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

Per-series visitor callback for mdl_library_for_each.

Receives the already authenticated state generation selected from the logical marker and .alt; setting out_continue false stops enumeration successfully, while a returned error aborts it.

Parameters

[in]	series_dir	Canonical path of one tracked series directory.
[in]	state_path	Canonical logical .mdl_state path.
[in]	state	Validated state, borrowed until this callback returns.
[in,out]	ctx	Opaque caller context, possibly NULL.
[out]	out_continue	Set false to stop normally or true to continue.

Returns: Callback status propagated unchanged by the enumeration.

Return values

k_ra8_ok The callback completed and initialized out_continue.

Precondition: Path/state/output pointers are non-NULL and paths are NUL-terminated.; The callback does not retain state or mutate the enumerated directory.

Postcondition: The callback initializes out_continue on success.; No ownership of path, state, or context storage is transferred.

Note: Invoked serially; not thread-safe with shared context.

Since: 0.1.0

Definition at line 121 of file mdl_library.h.

Enumeration Type Documentation

◆ mdl_library_limit_t

enum mdl_library_limit_t : uint32_t

Hard ceilings accepted by the portable library algorithms.

Enumerator
k_mdl_library_entry_limit	Maximum discovered entries.
k_mdl_library_operation_limit	Maximum namespace calls.
k_mdl_library_depth_limit	Maximum child-dir nesting.

Definition at line 29 of file mdl_library.h.

Function Documentation

◆ mdl_library_for_each()

ra8_err_t mdl_library_for_each	(	mdl_storage_t *	storage,
		const char *	out_dir,
		mdl_state_t *	state_scratch,
		mdl_library_workspace_t *	workspace,
		const mdl_library_policy_t *	policy,
		mdl_library_fn	callback,
		void *	callback_ctx )

nodiscard

Visit every authenticated tracked series under a library root.

Validates the canonical root, enumerates at most max_entries + 1 immediate entries to distinguish the exact cap from cap+1, and authenticates both state generations before invoking callback. An absent root is an empty library. Clean callback stop succeeds; callback, list, stat, state-read, and close errors propagate.

Parameters

[in,out]	storage	Initialized portable filesystem binding.
[in]	out_dir	Canonical library-root path.
[in,out]	state_scratch	Caller-owned state model reused per callback.
[in,out]	workspace	Initialized caller-owned cursor storage.
[in]	policy	Explicit bounded traversal policy.
[in]	callback	Authenticated-series visitor.
[in,out]	callback_ctx	Opaque callback context, possibly NULL.

Returns: Canonical traversal, authentication, or callback status.

Return values

k_ra8_ok	Enumeration completed, stopped cleanly, or root was absent.
k_ra8_err_invalid_size	The immediate entry cap was exceeded.
k_ra8_err_invalid_arg	A binding, policy, path, or root type is invalid.
other	A namespace, stream, authentication, close, or callback error.

Precondition: Required pointers are non-NULL and out_dir is canonical.; Storage, state scratch, and workspace are exclusively owned for the call.; The workspace meets storage->fs->caps.directory_workspace_*.

Postcondition: Every callback receives one authenticated state and runs at most once for each accepted immediate directory entry.; Enumeration never modifies the library namespace.

Note: Not thread-safe because storage and state scratch are reused.

Since: 0.1.0

Definition at line 304 of file mdl_library.c.

References mdl_library_workspace_t::directory_workspace, mdl_library_workspace_t::directory_workspace_bytes, mdl_library_workspace_t::entry_limit, mdl_storage_t::fs, internal_library_enumerate(), internal_library_policy(), internal_library_root(), internal_library_workspace_reset(), k_ra8_err_invalid_arg, k_ra8_ok, and mdl_library_policy_t::max_entries.

Referenced by mdl_app_run_list(), and mdl_app_run_update_all().

◆ mdl_library_policy_default()

mdl_library_policy_t mdl_library_policy_default ( void )

nodiscard

Return the production library traversal policy.

Selects the complete fixed entry, operation, and depth ceilings; tests may pass a stricter policy to exercise every boundary.

Returns: Policy containing all production hard ceilings.

Return values

mdl_library_policy_t Complete bounded production policy.

Precondition: No initialization or filesystem binding is required.; The returned value is copied by the caller before optional narrowing.

Postcondition: Every field is nonzero and within its corresponding hard ceiling.; No global or caller state is modified.

Note: Thread-safe and side-effect free.

Since: 0.1.0

Definition at line 29 of file mdl_library.c.

References k_mdl_library_depth_limit, k_mdl_library_entry_limit, and k_mdl_library_operation_limit.

Referenced by mdl_app_run_list(), mdl_app_run_remove(), and mdl_app_run_update_all().

◆ mdl_library_remove_tree()

ra8_err_t mdl_library_remove_tree	(	mdl_storage_t *	storage,
		const char *	dir,
		const mdl_library_policy_t *	policy,
		mdl_library_workspace_t *	workspace )

nodiscard

Remove one canonical directory tree through portable namespace calls.

Performs a non-recursive iterative post-order traversal using fw_fs_dir_open, fw_fs_dir_next, fw_fs_dir_close, fw_fs_stat, fw_fs_unlink, and fw_fs_rmdir. Symlinks and other special nodes are refused, never followed. Every bound and dependency failure is returned even when prior children were already removed, making partial deletion explicit.

Parameters

[in,out]	storage	Initialized portable filesystem binding.
[in]	dir	Canonical non-root directory to remove.
[in]	policy	Explicit entry, depth, and operation limits.
[in,out]	workspace	Initialized iterative path stack and counters.

Returns: Canonical removal or traversal status.

Return values

k_ra8_ok	The tree was removed or was already absent.
k_ra8_err_access_denied	A symbolic link or protected root was seen.
k_ra8_err_invalid_size	A path, entry, depth, or operation cap was exceeded.
k_ra8_err_invalid_arg	A binding, policy, path, or node type is invalid.
other	A list, stat, unlink, or rmdir failure propagated unchanged.

Precondition: Required pointers are non-NULL, dir is canonical, and workspaces are idle.; workspace was initialized by mdl_library_workspace_init.; The caller has authenticated that dir is the intended tracked series.

Postcondition: Success leaves no node at dir.; Failure never accesses a path not lexically contained beneath dir.

Note: Not thread-safe against concurrent mutation of the same tree.

Since: 0.1.0

Definition at line 609 of file mdl_library.c.

References mdl_library_workspace_t::directory_workspace, mdl_library_workspace_t::directory_workspace_bytes, mdl_storage_t::fs, internal_library_policy(), internal_library_remove_root(), internal_library_remove_walk(), k_ra8_err_invalid_arg, k_ra8_ok, and mdl_library_workspace_t::paths.

Referenced by mdl_app_run_remove().

◆ mdl_library_workspace_init()

ra8_err_t mdl_library_workspace_init	(	mdl_library_workspace_t *	workspace,
		void *	directory_workspace,
		uint32_t	directory_workspace_bytes )

nodiscard

Bind caller-owned directory storage to a reusable library workspace.

The storage must satisfy the selected filesystem's advertised directory-workspace size and alignment. Its size is independent of the number of library entries; enumeration retains only one value.

Parameters

[out]	workspace	Library workspace to initialize.
[in,out]	directory_workspace	Caller-owned backend cursor state.
[in]	directory_workspace_bytes	Accessible workspace extent.

Returns: Workspace binding status.

Return values

k_ra8_ok	The workspace is initialized and idle.
k_ra8_err_invalid_arg	A pointer or zero capacity is invalid.

Precondition: directory_workspace addresses the reported writable extent.; Neither storage region is in use by another traversal.

Postcondition: Success retains the workspace pointer and extent and clears counters.; Failure does not initialize a usable workspace.

Note: No memory is allocated or ownership transferred.

Since: 0.1.0

Definition at line 36 of file mdl_library.c.

References k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_storage_init().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ mdl_library_fn

Enumeration Type Documentation

◆ mdl_library_limit_t

Function Documentation

◆ mdl_library_for_each()

◆ mdl_library_policy_default()

◆ mdl_library_remove_tree()

◆ mdl_library_workspace_init()