mdl_cache_internal.h File Reference

Private binary-index and body I/O seams for mdl_cache. More...

#include "mdl_cache.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_cache_internal.h:

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

Go to the source code of this file.

Data Structures
struct	mdl_cache_paths_t
	Complete paths and host identity derived for one request. More...

Functions
ra8_err_t	priv_mdl_cache_load (mdl_cache_t *cache, const char *url, mdl_cache_paths_t *paths, bool *rebuilt)
	Prepare a host directory and load or recover its index.
ra8_err_t	priv_mdl_cache_save (mdl_cache_t *cache, const mdl_cache_paths_t *paths)
	Transactionally publish the current host index.
ra8_err_t	priv_mdl_cache_read_body (mdl_storage_t *storage, const mdl_cache_paths_t *paths, const mdl_cache_record_t *record, char *buffer, size_t capacity, size_t *out_length)
	Read and hash-check one retained body into caller storage.
ra8_err_t	priv_mdl_cache_publish_body (mdl_storage_t *storage, const mdl_cache_paths_t *paths, uint64_t url_hash, uint64_t content_hash, const char *buffer, size_t length, char *relative_path, size_t relative_capacity)
	Publish one new body under its immutable content-derived leaf.

Detailed Description

Private binary-index and body I/O seams for mdl_cache.

Shares validated host paths and transaction helpers between the cache policy and persistent-I/O translation units.

Copyright

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

Definition in file mdl_cache_internal.h.

Function Documentation

priv_mdl_cache_load()

ra8_err_t priv_mdl_cache_load	(	mdl_cache_t *	cache,
		const char *	url,
		mdl_cache_paths_t *	paths,
		bool *	rebuilt )

Prepare a host directory and load or recover its index.

Derives a host-bound namespace, authenticates an existing index, and discards only a corrupt regular index before resetting it.

Parameters

[in,out]	cache	Cache binding and index workspace.
[in]	url	Request URL used to select the host.
[out]	paths	Derived host paths.
[out]	rebuilt	Whether a corrupt regular index was discarded.

Returns

Canonical path, namespace, or parse status.

Return values

k_ra8_ok	Paths and a valid or empty index are available.
k_ra8_err_invalid_state	A non-regular index or invalid namespace exists.
other	URL parsing, directory, file, or cleanup failed.

Precondition

All pointers are non-NULL and cache root is canonical.

Cache storage and index workspace are exclusively owned.

Postcondition

Success initializes both paths and cache->index.

Success reports corrupt-index recovery through rebuilt.

Note

A non-regular index fails closed and is never removed.

Since

0.1.0

Definition at line 532 of file mdl_cache_io.c.

References fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), mdl_cache_paths_t::host_hash, mdl_cache_t::index, mdl_cache_paths_t::index_path, internal_cache_decode(), internal_cache_discard_index(), internal_cache_paths(), k_fw_fs_node_file, k_mdl_cache_schema_version, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, fw_fs_t::names, RA8_PRIV, fw_fs_stat_t::size_bytes, mdl_cache_t::storage, and fw_fs_stat_t::type.

Referenced by internal_cache_prepare().

priv_mdl_cache_publish_body()

ra8_err_t priv_mdl_cache_publish_body	(	mdl_storage_t *	storage,
		const mdl_cache_paths_t *	paths,
		uint64_t	url_hash,
		uint64_t	content_hash,
		const char *	buffer,
		size_t	length,
		char *	relative_path,
		size_t	relative_capacity )

Publish one new body under its immutable content-derived leaf.

Derives the leaf from both URL and content identities, streams the exact bytes into a transaction, and commits only on full success.

Parameters

[in,out]	storage	Exclusive storage binding.
[in]	paths	Matching host directory.
[in]	url_hash	Stable URL identity.
[in]	content_hash	Exact body identity.
[in]	buffer	Complete body bytes.
[in]	length	Body extent.
[out]	relative_path	Published relative leaf.
[in]	relative_capacity	Writable leaf capacity.

Returns

Canonical transaction status.

Return values

k_ra8_ok	The immutable body is completely published.
k_ra8_err_invalid_arg	A pointer or length contract is invalid.
k_ra8_err_invalid_size	The leaf or full path exceeded its bound.
other	Transaction begin, write, commit, or abort failed.

Precondition

Body is nonempty and pointers/capacities are valid.

Storage and transaction workspace are exclusively owned.

Postcondition

Success publishes exactly length bytes atomically.

Success returns the exact relative leaf in relative_path.

Note

Orphaned immutable bodies are harmless after an index-save failure.

Since

0.1.0

Definition at line 832 of file mdl_cache_io.c.

References mdl_cache_paths_t::directory, internal_cache_body_leaf(), k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_path_join(), mdl_storage_txn_abort(), mdl_storage_txn_begin(), mdl_storage_txn_commit(), mdl_storage_txn_write(), and RA8_PRIV.

Referenced by internal_cache_publish().

priv_mdl_cache_read_body()

ra8_err_t priv_mdl_cache_read_body	(	mdl_storage_t *	storage,
		const mdl_cache_paths_t *	paths,
		const mdl_cache_record_t *	record,
		char *	buffer,
		size_t	capacity,
		size_t *	out_length )

Read and hash-check one retained body into caller storage.

Requires a regular exact-sized file, reads it completely with bounded progress, checks EOF, then authenticates the content hash.

Parameters

[in,out]	storage	Exclusive storage binding.
[in]	paths	Matching host directory.
[in]	record	Persistent body identity.
[out]	buffer	Destination storage.
[in]	capacity	Destination capacity.
[out]	out_length	Exact body extent.

Returns

Canonical file, size, or identity status.

Return values

k_ra8_ok	Exact authenticated bytes are available.
k_ra8_err_not_found	The retained body is absent.
k_ra8_err_validation_failed	The body hash differs.
other	Size, open, read, or close failed.

Precondition

Every pointer is non-NULL.

buffer spans capacity nonzero writable bytes.

Postcondition

Success publishes only an exact hash-matching body.

Failure leaves out_length equal to zero.

Note

A mismatched body is treated as validation failure.

Since

0.1.0

Definition at line 797 of file mdl_cache_io.c.

References mdl_cache_record_t::content_hash, mdl_cache_paths_t::directory, fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), internal_cache_read_body_exact(), k_fw_fs_node_file, k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_err_validation_failed, k_ra8_ok, mdl_hash_bytes(), mdl_path_join(), fw_fs_t::names, RA8_PRIV, mdl_cache_record_t::relative_path, fw_fs_stat_t::size_bytes, and fw_fs_stat_t::type.

Referenced by internal_cache_finish_304(), and internal_cache_prepare().

priv_mdl_cache_save()

ra8_err_t priv_mdl_cache_save	(	mdl_cache_t *	cache,
		const mdl_cache_paths_t *	paths )

Transactionally publish the current host index.

Encodes a checksummed generation directly into a portable storage transaction and commits only after every record is written.

Parameters

[in,out]	cache	Cache binding containing the index.
[in]	paths	Matching host paths from priv_mdl_cache_load.

Returns

Canonical serialization or publication status.

Return values

k_ra8_ok	The complete index generation was published.
k_ra8_err_invalid_arg	The index and host paths do not match.
other	Validation, transaction writing, commit, or abort failed.

Precondition

Index invariants and host identity are valid.

Cache storage and transaction workspace are exclusively owned.

Postcondition

Success publishes one complete checksummed generation.

Failure never exposes a partial index generation.

Note

Existing indexes require truthful atomic-replace support.

Since

0.1.0

Definition at line 699 of file mdl_cache_io.c.

References mdl_cache_index_t::host_hash, mdl_cache_paths_t::host_hash, mdl_cache_t::index, mdl_cache_paths_t::index_path, internal_cache_payload_identity(), internal_cache_put_u16(), internal_cache_put_u64(), internal_cache_record_valid(), internal_cache_write_records(), k_cache_header_bytes, k_cache_header_count, k_cache_header_host, k_cache_trailer_bytes, k_mdl_cache_record_max, k_mdl_cache_schema_version, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, mdl_storage_txn_abort(), mdl_storage_txn_begin(), mdl_storage_txn_commit(), mdl_storage_txn_write(), memcpy(), RA8_PRIV, mdl_cache_index_t::record_count, mdl_cache_index_t::records, s_cache_magic, mdl_cache_index_t::schema_version, and mdl_cache_t::storage.

Referenced by internal_cache_finish_304(), and internal_cache_publish().