Portable single-transaction response-body sink for media fetches. More...

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

Include dependency graph for mdl_fetch_body_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_fetch_body_t
	Caller-owned state for one retryable streamed fetch. More...

Enumerations
enum	mdl_fetch_body_limit_t : uint8_t { k_mdl_fetch_magic_bytes = 16U }
	Bounded signature extent retained before image publication begins. More...
enum	mdl_fetch_body_mode_t : uint8_t { k_mdl_fetch_body_exact = 0U , k_mdl_fetch_body_image = 1U }
	Destination policy for one response body. More...

Functions
ra8_err_t	priv_mdl_fetch_body_init_exact (mdl_fetch_body_t body, mdl_storage_t storage, const char *target_abs)
	Initialize an exact-path transactional body sink.
ra8_err_t	priv_mdl_fetch_body_init_image (mdl_fetch_body_t body, mdl_storage_t storage, const char target_abs, const char target_rel)
	Initialize a magic-typed image body sink.
mdl_net_body_sink_t	priv_mdl_fetch_body_sink (mdl_fetch_body_t *body)
	Return the network sink view of one body state.
ra8_err_t	priv_mdl_fetch_body_prepare (mdl_fetch_body_t *body)
	Finish prefix classification and make a nonempty stage commit-ready.
ra8_err_t	priv_mdl_fetch_body_commit (mdl_fetch_body_t *body)
	Validate exact size/hash and publish one prepared body.
ra8_err_t	priv_mdl_fetch_body_abort (mdl_fetch_body_t *body)
	Abort any private stage owned by a body sink.

Detailed Description

Portable single-transaction response-body sink for media fetches.

Declares the caller-owned state and lifecycle used to stage, verify, commit, or abort one bounded response body.

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

Definition in file mdl_fetch_body_internal.h.

Enumeration Type Documentation

◆ mdl_fetch_body_limit_t

enum mdl_fetch_body_limit_t : uint8_t

Bounded signature extent retained before image publication begins.

Enumerator
k_mdl_fetch_magic_bytes	Largest supported image signature prefix.

Definition at line 22 of file mdl_fetch_body_internal.h.

◆ mdl_fetch_body_mode_t

enum mdl_fetch_body_mode_t : uint8_t

Destination policy for one response body.

Enumerator
k_mdl_fetch_body_exact	Publish under the supplied exact path.
k_mdl_fetch_body_image	Derive the suffix from image magic.

Definition at line 27 of file mdl_fetch_body_internal.h.

Function Documentation

◆ priv_mdl_fetch_body_abort()

ra8_err_t priv_mdl_fetch_body_abort ( mdl_fetch_body_t * body )

Abort any private stage owned by a body sink.

Delegates stage cleanup and clears accepted bytes on success.

Parameters

[in,out] body Initialized body state.

Returns: Canonical cleanup status.

Return values

k_ra8_ok	No private stage remains.
k_ra8_err_invalid_arg	The body pointer is NULL.

Precondition: body is non-NULL and exclusively owned.; The body's storage binding remains live if a stage is active.

Postcondition: Success leaves no active transaction or accepted response bytes.; Failure preserves diagnostic state and publishes no new destination.

Note: Required after network, status, or state failures.

Since: 0.1.0

Definition at line 292 of file mdl_fetch_body.c.

References k_ra8_err_invalid_arg, k_ra8_ok, mdl_storage_txn_abort(), mdl_fetch_body_t::prefix_bytes, mdl_fetch_body_t::received, and mdl_fetch_body_t::writer.

Referenced by internal_cover_finish(), internal_cover_publish_cached(), internal_cover_stream(), internal_download_page_image(), internal_fetch_asset_execute(), internal_mdl_fetch_prepare_page(), internal_mdl_fetch_publish_page(), internal_mdl_fetch_resolve_not_modified(), and internal_publish_page_image().

◆ priv_mdl_fetch_body_commit()

ra8_err_t priv_mdl_fetch_body_commit ( mdl_fetch_body_t * body )

Validate exact size/hash and publish one prepared body.

Independently rereads the private stage before one durable commit.

Parameters

[in,out] body Prepared body transaction.

Returns: Canonical validation, commit, or cleanup status.

Return values

k_ra8_ok	The independently verified body was published.
other	Validation, publication, or cleanup failed.

Precondition: priv_mdl_fetch_body_prepare succeeded.; Persistent-state capacity and destination policy have been checked.

Postcondition: Success publishes exactly once and leaves no active transaction.; A prepublication failure attempts cleanup and preserves any prior destination.

Note: A backend may truthfully return a postpublication durability error; the body's identity/path fields remain readable in either case.

Since: 0.1.0

Definition at line 284 of file mdl_fetch_body.c.

References fw_fs_transaction_t::active, k_ra8_err_invalid_arg, mdl_storage_txn_commit(), mdl_storage_txn_t::transaction, and mdl_fetch_body_t::writer.

Referenced by internal_cover_finish(), internal_fetch_asset_execute(), internal_mdl_fetch_publish_page(), and internal_publish_page_image().

◆ priv_mdl_fetch_body_init_exact()

ra8_err_t priv_mdl_fetch_body_init_exact	(	mdl_fetch_body_t *	body,
		mdl_storage_t *	storage,
		const char *	target_abs )

Initialize an exact-path transactional body sink.

Binds the caller's storage and destination without filesystem I/O.

Parameters

[out]	body	Caller-owned sink state.
[in,out]	storage	Initialized exclusive storage binding.
[in]	target_abs	Canonical exact destination.

Returns: Canonical argument status.

Return values

k_ra8_ok	The body is ready to bind to the network seam.
k_ra8_err_invalid_arg	A required pointer/path is invalid.

Precondition: body is inactive and writable.; target_abs remains valid through the synchronous fetch.

Postcondition: No filesystem transaction has begun.; Success initializes an empty accepted-byte count.

Note: The first nonempty body chunk begins the transaction.

Since: 0.1.0

Definition at line 233 of file mdl_fetch_body.c.

References k_mdl_fetch_body_exact, k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_fetch_asset_execute().

◆ priv_mdl_fetch_body_init_image()

ra8_err_t priv_mdl_fetch_body_init_image	(	mdl_fetch_body_t *	body,
		mdl_storage_t *	storage,
		const char *	target_abs,
		const char *	target_rel )

Initialize a magic-typed image body sink.

Binds requested paths while deferring suffix selection to body magic.

Parameters

[out]	body	Caller-owned sink state.
[in,out]	storage	Initialized exclusive storage binding.
[in]	target_abs	URL-derived absolute destination.
[in]	target_rel	URL-derived relative destination.

Returns: Canonical argument status.

Return values

k_ra8_ok	The body is ready with no transaction created.
k_ra8_err_invalid_arg	A required pointer/path is invalid.

Precondition: Paths remain valid through the synchronous fetch.; Each path contains a replaceable suffix.

Postcondition: At most sixteen leading bytes are buffered before transaction begin.; No filesystem transaction has begun.

Note: Content-Type never overrides unsupported or conflicting bytes.

Since: 0.1.0

Definition at line 248 of file mdl_fetch_body.c.

References k_mdl_fetch_body_image, k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_cover_publish_cached(), internal_cover_stream(), internal_download_page_image(), and internal_mdl_fetch_prepare_page().

◆ priv_mdl_fetch_body_prepare()

ra8_err_t priv_mdl_fetch_body_prepare ( mdl_fetch_body_t * body )

Finish prefix classification and make a nonempty stage commit-ready.

Flushes a short retained signature after a successful response.

Parameters

[in,out] body Completed successful non-304 response body.

Returns: Canonical size, type, path, or transaction status.

Return values

k_ra8_ok	The actual paths and complete private stage are ready.
k_ra8_err_invalid_size	The body was empty.
k_ra8_err_validation_failed	Image magic was unsupported.
other	Path or transaction failure propagated.

Precondition: The network call returned k_ra8_ok with a status other than 304.; body is initialized and exclusively owned.

Postcondition: Success does not validate, publish, or mutate persistent state.; Failure leaves any active private stage available for explicit abort.

Note: Callers may perform state-capacity checks before commit.

Since: 0.1.0

Definition at line 270 of file mdl_fetch_body.c.

References fw_fs_transaction_t::active, internal_body_flush_prefix(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_fetch_body_t::received, mdl_fetch_body_t::storage, mdl_storage_txn_t::transaction, and mdl_fetch_body_t::writer.

Referenced by internal_cover_finish(), internal_fetch_asset_execute(), internal_mdl_fetch_publish_page(), and internal_publish_page_image().

◆ priv_mdl_fetch_body_sink()

mdl_net_body_sink_t priv_mdl_fetch_body_sink ( mdl_fetch_body_t * body )

Return the network sink view of one body state.

Exposes reset/write callbacks borrowing the supplied body context.

Parameters

[in,out] body Initialized body state.

Returns: Reset/write callback binding borrowing body.

Return values

mdl_net_body_sink_t A complete synchronous callback view.

Precondition: body remains live until the network call returns.; body is initialized and exclusively owned.

Postcondition: No state is changed by constructing the view.; The returned view points back to body.

Note: The returned context is not retained by the dispatcher.

Since: 0.1.0

Definition at line 264 of file mdl_fetch_body.c.

References internal_body_reset(), and internal_body_write().

Referenced by internal_cover_publish_cached(), internal_cover_stream(), internal_download_page_image(), internal_fetch_asset_execute(), internal_mdl_fetch_prepare_page(), and internal_mdl_fetch_resolve_not_modified().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_fetch_body_limit_t

◆ mdl_fetch_body_mode_t

Function Documentation

◆ priv_mdl_fetch_body_abort()

◆ priv_mdl_fetch_body_commit()

◆ priv_mdl_fetch_body_init_exact()

◆ priv_mdl_fetch_body_init_image()

◆ priv_mdl_fetch_body_prepare()

◆ priv_mdl_fetch_body_sink()