Bounded per-host HTTP document cache for the media downloader. More...

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

Include dependency graph for mdl_cache.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_record_t
	One exact URL-keyed cached document observation. More...
struct	mdl_cache_index_t
	Caller-owned workspace for one loaded host index. More...
struct	mdl_cache_t
	One non-reentrant cache binding over caller storage. More...
struct	mdl_cache_result_t
	Observable outcome of one cache lookup. More...

Typedefs
typedef ra8_err_t(*	mdl_cache_fetch_fn) (void context, const char url, const mdl_net_req_t request, char buffer, size_t capacity, size_t out_length, mdl_net_resp_t response)
	Injected bounded GET callback used by the cache.

Enumerations
enum	mdl_cache_limit_t : uint16_t { k_mdl_cache_schema_version = 1U , k_mdl_cache_record_max = 128U }
	Persistent cache schema and fixed-capacity record bound. More...

Functions
ra8_err_t	mdl_cache_get_buf (mdl_cache_t cache, const char url, const mdl_net_req_t base_request, mdl_cache_fetch_fn fetch, void fetch_context, char buffer, size_t capacity, size_t out_length, mdl_net_resp_t response, mdl_cache_result_t result)
	Fetch one document through the per-host persistent cache.

Detailed Description

Bounded per-host HTTP document cache for the media downloader.

Stores exact URL identities, validators, response observations, and content hashes in one versioned index per host. Bodies and indexes publish through injected storage transactions; no ownership or host filesystem API crosses this interface.

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

Definition in file mdl_cache.h.

Typedef Documentation

◆ mdl_cache_fetch_fn

typedef ra8_err_t(* mdl_cache_fetch_fn) (void *context, const char *url, const mdl_net_req_t *request, char *buffer, size_t capacity, size_t *out_length, mdl_net_resp_t *response)

Injected bounded GET callback used by the cache.

Callers may dispatch directly to a network backend or wrap the call in a politeness governor and retry policy.

Parameters

[in,out]	context	Caller-owned fetch context.
[in]	url	Exact absolute request URL.
[in]	request	Request headers and timeout.
[out]	buffer	Destination body storage.
[in]	capacity	Writable bytes at `buffer`.
[out]	out_length	Body bytes written.
[out]	response	Finished response metadata.

Returns: Canonical network or policy status.

Precondition: Every pointer is non-NULL and capacity is nonzero.

Postcondition: Success initializes out_length and response.

Note: The callback retains no argument pointer.

Since: 0.1.0

Definition at line 78 of file mdl_cache.h.

Enumeration Type Documentation

◆ mdl_cache_limit_t

enum mdl_cache_limit_t : uint16_t

Persistent cache schema and fixed-capacity record bound.

Enumerator
k_mdl_cache_schema_version	Current binary index schema.
k_mdl_cache_record_max	Records retained per host.

Definition at line 24 of file mdl_cache.h.

Function Documentation

◆ mdl_cache_get_buf()

ra8_err_t mdl_cache_get_buf	(	mdl_cache_t *	cache,
		const char *	url,
		const mdl_net_req_t *	base_request,
		mdl_cache_fetch_fn	fetch,
		void *	fetch_context,
		char *	buffer,
		size_t	capacity,
		size_t *	out_length,
		mdl_net_resp_t *	response,
		mdl_cache_result_t *	result )

nodiscard

Fetch one document through the per-host persistent cache.

Verifies a retained body before reuse, sends saved validators when available, treats HTTP 304 as a body-free observation, and retries an unexpected 304 once without validators when no valid entity is held. Successful new bodies and index generations publish transactionally. A malformed/truncated index is removed and rebuilt rather than trusted or treated as library state.

Parameters

[in,out]	cache	Initialized cache binding.
[in]	url	Exact absolute URL.
[in]	base_request	Request identity, referer, and timeout.
[in]	fetch	Injected network/governor callback.
[in,out]	fetch_context	Context supplied to `fetch`.
[out]	buffer	Caller-owned body destination.
[in]	capacity	Writable byte capacity.
[out]	out_length	Exact returned body bytes.
[out]	response	Finished network or retained response metadata.
[out]	result	Cache-specific outcome.

Returns: Canonical cache, storage, network, or validation status.

Return values

k_ra8_ok	A nonempty verified body is in `buffer`.
k_ra8_err_invalid_arg	A binding, path, callback, or URL is invalid.
k_ra8_err_invalid_size	The response or persistent record is oversized.
other	The injected storage or fetch operation failed.

Precondition: All required pointers are non-NULL and cache is exclusively owned.; buffer spans capacity nonzero writable bytes.

Postcondition: Success returns complete bytes and a truthful cache result.; Failure never publishes a partial body or index generation.

Note: Thread-safe across independent bindings and storage workspaces.

Since: 0.1.0

Definition at line 537 of file mdl_cache.c.

References mdl_cache_result_t::body_reused, mdl_cache_record_t::etag, mdl_cache_lookup_t::held, mdl_cache_t::index, internal_cache_network(), internal_cache_prepare(), k_ra8_err_invalid_arg, k_ra8_ok, mdl_cache_record_t::last_modified, mdl_cache_lookup_t::record, mdl_cache_t::refetch, mdl_cache_lookup_t::retained_length, mdl_cache_t::root, and mdl_cache_t::storage.

Referenced by internal_cover_cached(), internal_mdl_fetch_chapter_html(), and priv_mdl_app_prepare_chapters().

Data Structures

Typedefs

Enumerations