mdl_app_storage.c File Reference

Portable application-storage policy over the injected filesystem. More...

#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include "mdl_app_storage_internal.h"

Include dependency graph for mdl_app_storage.c:

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.

Variables
static const char	s_site_descriptor_format []
	Complete starter descriptor template written by init-site mode.

Detailed Description

Portable application-storage policy over the injected filesystem.

Implements directory creation, guarded removal, and create-new site publication without exposing host filesystem types.

Copyright

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

Definition in file mdl_app_storage.c.

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

Variable Documentation

s_site_descriptor_format

const char s_site_descriptor_format[]

static

Initial value:

                                         =
"# Copyright (c) 2026 Brighton Sikarskie\n"
"# SPDX-License-Identifier: MIT\n"
"#\n"
"# Site descriptor for %s (%s).\n"
"# Generated by mdl --init-site\n"
"\n"
"name = %s\n"
"host = %s\n"
"kind = manga\n"
"\n"
"# --- chapter list (on a series page) ---\n"
"chapter_url_contains = /chapter-\n"
"# chapter_url_prefix = https://%s/path/to/series/chapters/\n"
"chapter_order = asc\n"
"\n"
"# --- search / discovery ---\n"
"search_url = https://%s/?s={q}\n"
"search_result_contains = /manga/\n"
"browse_url = https://%s/\n"
"\n"
"# --- page images (on a chapter page) ---\n"
"page_img_attr = data-src\n"
"page_img_url_contains = /uploads/\n"
"\n"
"# --- politeness (milliseconds; jittered in [min,max]) ---\n"
"img_delay_min = 500\n"
"img_delay_max = 1200\n"
"chapter_delay_min = 1500\n"
"chapter_delay_max = 3000\n"

Complete starter descriptor template written by init-site mode.

Definition at line 16 of file mdl_app_storage.c.

Referenced by priv_mdl_app_storage_publish_site().