mdl_app_storage_internal.h File Reference

Private portable filesystem operations shared by CLI application modes. More...

#include "mdl_storage.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for mdl_app_storage_internal.h:

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

Go to the source code of this file.

Functions
ra8_err_t	priv_mdl_app_storage_ensure_directory (mdl_storage_t *storage, const char *path)
	Ensure one canonical portable path names a real directory.
ra8_err_t	priv_mdl_app_storage_unlink_regular (mdl_storage_t *storage, const char *path, bool *out_removed)
	Remove one regular file while refusing symbolic or special nodes.
ra8_err_t	priv_mdl_app_storage_publish_site (mdl_storage_t *storage, const char *destination, const char *url, const char *host, const char *name)
	Render and create one starter site descriptor transactionally.

Detailed Description

Private portable filesystem operations shared by CLI application modes.

Keeps application policy over the existing mdl_storage_t and fw_fs contracts testable without introducing another file handle, path facade, allocator, or host-library dependency.

Copyright

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

Definition in file mdl_app_storage_internal.h.

Function Documentation

priv_mdl_app_storage_ensure_directory()

ra8_err_t priv_mdl_app_storage_ensure_directory	(	mdl_storage_t *	storage,
		const char *	path )

Ensure one canonical portable path names a real directory.

Parameters

[in,out]	storage	Initialized exclusive filesystem binding.
[in]	path	Canonical absolute directory path.

Returns

Canonical namespace status.

Return values

k_ra8_ok	The directory already existed or was created and rechecked.
k_ra8_err_access_denied	The path names a symbolic link.
k_ra8_err_invalid_arg	The path names another node type.
other	Stat or mkdir failure propagated from the injected backend.

Precondition

path is NUL-terminated and confined by storage.

Postcondition

Success proves the final node is a directory.

Failure never follows a symbolic link or removes an existing node.

Note

Not thread-safe against concurrent mutation of the same namespace.

Since

0.1.0

Uses canonical paths and caller-owned filesystem workspace only. Special nodes are rejected before any namespace mutation.

Precondition

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

Definition at line 47 of file mdl_app_storage.c.

References fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_mkdir(), fw_fs_stat(), k_fw_fs_node_directory, k_fw_fs_node_symlink, k_ra8_err_access_denied, k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, fw_fs_t::names, RA8_PRIV, and fw_fs_stat_t::type.

Referenced by internal_prepare_artifact_path(), internal_prepare_output_dir(), mdl_app_run_init_site(), mdl_app_run_series(), and priv_mdl_app_prepare_series_dir().

priv_mdl_app_storage_publish_site()

ra8_err_t priv_mdl_app_storage_publish_site	(	mdl_storage_t *	storage,
		const char *	destination,
		const char *	url,
		const char *	host,
		const char *	name )

Render and create one starter site descriptor transactionally.

Formats the bounded fixed template in the storage I/O scratch, then uses a create-new transaction whose exact size and FNV identity are independently reread before publication. Existing descriptors are never replaced on any backend.

Parameters

[in,out]	storage	Initialized exclusive filesystem binding.
[in]	destination	Canonical absent .conf path.
[in]	url	Original absolute site URL.
[in]	host	Complete normalized host.
[in]	name	Derived display name.

Returns

Canonical render, transaction, validation, or publication status.

Return values

k_ra8_ok	The independently validated template was published once.
k_ra8_err_exists	The destination already exists unchanged.
k_ra8_err_invalid_size	The rendered template exceeded bounded scratch.
other	Storage failure propagated without publishing partial bytes.

Precondition

All strings are non-NULL, NUL-terminated, and remain live for the call.

destination is confined by the bound filesystem.

Postcondition

Success exposes exactly the generated descriptor bytes.

Failure preserves an existing destination byte-for-byte.

Note

Not thread-safe for shared storage or concurrent same-path creation.

Since

0.1.0

Definition at line 107 of file mdl_app_storage.c.

References fw_fs_transaction_t::active, mdl_storage_t::fs, mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_storage_txn_abort(), mdl_storage_txn_begin_new(), mdl_storage_txn_commit(), mdl_storage_txn_write(), RA8_PRIV, s_site_descriptor_format, strncmp(), and mdl_storage_txn_t::transaction.

Referenced by mdl_app_run_init_site().

priv_mdl_app_storage_unlink_regular()

ra8_err_t priv_mdl_app_storage_unlink_regular	(	mdl_storage_t *	storage,
		const char *	path,
		bool *	out_removed )

Remove one regular file while refusing symbolic or special nodes.

Parameters

[in,out]	storage	Initialized exclusive filesystem binding.
[in]	path	Canonical absolute file path.
[out]	out_removed	Whether an existing regular file was removed.

Returns

Canonical namespace status; an absent path succeeds.

Return values

k_ra8_ok	The path was absent or its regular file was removed.
k_ra8_err_access_denied	The path names a symbolic link.
k_ra8_err_invalid_arg	The path names a directory or special node.
other	Stat or unlink failure propagated from the injected backend.

Precondition

path is NUL-terminated and confined by storage.

Postcondition

Success leaves no node at path and initializes out_removed.

Failure never follows or removes a symbolic link.

Note

A final-component replacement race remains harmless because unlink removes the named directory entry rather than following it.

Since

0.1.0

Uses canonical paths and caller-owned filesystem workspace only. Special nodes are rejected before any namespace mutation.

Precondition

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

Definition at line 77 of file mdl_app_storage.c.

References fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), fw_fs_unlink(), k_fw_fs_node_file, k_fw_fs_node_symlink, k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_ok, fw_fs_t::names, RA8_PRIV, and fw_fs_stat_t::type.

Referenced by internal_remove_stale_page_variants().