mdl_fetch_body.c File Reference

Portable single-transaction response-body sink implementation. More...

#include <stdio.h>
#include <string.h>
#include "mdl_fetch_body_internal.h"
#include "mdl_urlname.h"

Include dependency graph for mdl_fetch_body.c:

Go to the source code of this file.

Functions
static bool	internal_body_paths (mdl_fetch_body_t *body, const char *extension)
	Replace both requested suffixes with one verified image suffix.
static ra8_err_t	internal_body_begin (mdl_fetch_body_t *body)
	Begin the exact or classified destination transaction once.
static ra8_err_t	internal_body_flush_prefix (mdl_fetch_body_t *body)
	Flush retained signature bytes into a newly active stage.
static ra8_err_t	internal_body_reset (void *context)
	Abort a prior retry attempt without beginning a new one.
static uint32_t	internal_body_buffer_prefix (mdl_fetch_body_t *body, const uint8_t *bytes, uint32_t length)
	Retain the bounded image prefix and return consumed source bytes.
static ra8_err_t	internal_body_write (void *context, const uint8_t *bytes, uint32_t length, uint32_t *out_written)
	Consume one exact or magic-typed network body chunk.
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 implementation.

Streams network body fragments into one injected transaction and validates complete content before publication.

Copyright

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

Definition in file mdl_fetch_body.c.

Function Documentation

internal_body_begin()

ra8_err_t internal_body_begin ( mdl_fetch_body_t * body )

static

Begin the exact or classified destination transaction once.

Copies an exact destination or classifies buffered image magic, then delegates truthful create/replace policy to storage.

Parameters

[in,out]

body

Initialized response body.

Returns

Canonical classification, path, or transaction status.

Return values

k_ra8_ok	A transaction was already active or is now active.
k_ra8_err_validation_failed	Buffered image magic is unsupported.

Precondition

body is non-NULL and owns an initialized storage binding.

Required source path strings remain live and NUL-terminated.

Postcondition

Success leaves exactly one private transaction active.

Failure publishes no destination.

Note

Repeated calls while active are idempotent.

Since

0.1.0

Definition at line 68 of file mdl_fetch_body.c.

References fw_fs_transaction_t::active, mdl_fetch_body_t::actual_abs, internal_body_paths(), k_mdl_fetch_body_exact, k_ra8_err_invalid_size, k_ra8_err_validation_failed, k_ra8_ok, mdl_storage_txn_begin(), mdl_urlname_sniff_image_type(), mdl_fetch_body_t::mode, mdl_fetch_body_t::prefix, mdl_fetch_body_t::prefix_bytes, RA8_INTERNAL, mdl_fetch_body_t::storage, mdl_fetch_body_t::target_abs, mdl_storage_txn_t::transaction, and mdl_fetch_body_t::writer.

Referenced by internal_body_flush_prefix(), and internal_body_write().

internal_body_buffer_prefix()

uint32_t internal_body_buffer_prefix ( mdl_fetch_body_t * body, const uint8_t * bytes, uint32_t length )

static

Retain the bounded image prefix and return consumed source bytes.

Copies only the remaining portion of the fixed magic-prefix buffer.

Parameters

[in,out]	body	Initialized image body.
[in]	bytes	Readable network bytes.
[in]	length	Available source extent.

Returns

Number of bytes copied into the prefix.

Return values

0	The prefix was already full or the source was empty.

Precondition

body and bytes are non-NULL for nonempty input.

Existing prefix length is within its fixed capacity.

Postcondition

Prefix length advances by the returned count.

No transaction or persistent destination is mutated.

Note

The caller handles all source bytes after the returned prefix extent.

Since

0.1.0

Definition at line 169 of file mdl_fetch_body.c.

References k_mdl_fetch_magic_bytes, memcpy(), mdl_fetch_body_t::prefix, and mdl_fetch_body_t::prefix_bytes.

Referenced by internal_body_write().

internal_body_flush_prefix()

ra8_err_t internal_body_flush_prefix ( mdl_fetch_body_t * body )

static

Flush retained signature bytes into a newly active stage.

Begins the selected transaction and writes the deferred prefix once.

Parameters

[in,out]

body

Initialized response body with a bounded prefix.

Returns

Canonical classification, begin, or write status.

Return values

k_ra8_ok	The prefix is empty and its transaction is active.
other	The underlying classification or transaction operation failed.

Precondition

body is non-NULL and owns initialized storage.

Retained prefix length does not exceed its fixed capacity.

Postcondition

Success clears the retained prefix count.

Failure publishes no destination and leaves cleanup to the caller.

Note

Prefix bytes are folded into the same running identity as later bytes.

Since

0.1.0

Definition at line 110 of file mdl_fetch_body.c.

References internal_body_begin(), k_ra8_ok, mdl_storage_txn_write(), mdl_fetch_body_t::prefix, mdl_fetch_body_t::prefix_bytes, RA8_INTERNAL, and mdl_fetch_body_t::writer.

Referenced by internal_body_write(), and priv_mdl_fetch_body_prepare().

internal_body_paths()

bool internal_body_paths ( mdl_fetch_body_t * body, const char * extension )

static

Replace both requested suffixes with one verified image suffix.

Formats absolute and relative destinations from their last suffix.

Parameters

[in,out]	body	Initialized magic-typed response body.
[in]	extension	Verified suffix without a leading dot.

Returns

Whether both bounded destinations fit.

Return values

true	Both paths were written completely.
false	A suffix was absent or one result exceeded capacity.

Precondition

body and extension are non-NULL.

Both source paths remain live and NUL-terminated.

Postcondition

Success initializes both actual paths.

Failure never begins or publishes a transaction.

Note

The requested source paths are not modified.

Since

0.1.0

Definition at line 30 of file mdl_fetch_body.c.

References mdl_fetch_body_t::actual_abs, mdl_fetch_body_t::actual_rel, RA8_INTERNAL, strrchr(), mdl_fetch_body_t::target_abs, and mdl_fetch_body_t::target_rel.

Referenced by internal_body_begin().

internal_body_reset()

ra8_err_t internal_body_reset ( void * context )

static

Abort a prior retry attempt without beginning a new one.

Implements the network reset callback over caller-owned body state.

Parameters

[in,out]

context

Borrowed mdl_fetch_body_t context.

Returns

Canonical argument or transaction-abort status.

Return values

k_ra8_ok	No private stage or accepted response byte remains.
k_ra8_err_invalid_arg	The context is NULL.

Precondition

A non-NULL context points to initialized writable body state.

The body is exclusively owned for the callback duration.

Postcondition

Success resets paths, prefix length, and accepted-byte count.

Failure leaves the abort error and diagnostic transaction state visible.

Note

Reset never creates a transaction, including before a 304 response.

Since

0.1.0

Definition at line 136 of file mdl_fetch_body.c.

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

Referenced by priv_mdl_fetch_body_sink().

internal_body_write()

ra8_err_t internal_body_write ( void * context, const uint8_t * bytes, uint32_t length, uint32_t * out_written )

static

Consume one exact or magic-typed network body chunk.

Defers a bounded magic prefix, begins one destination transaction, and appends every accepted byte through the running identity writer.

Parameters

[in,out]	context	Borrowed mdl_fetch_body_t context.
[in]	bytes	Readable source bytes or NULL for an empty chunk.
[in]	length	Source extent.
[out]	out_written	Exact accepted extent on success.

Returns

Canonical argument, classification, or transaction status.

Return values

k_ra8_ok	The complete chunk was accepted.
k_ra8_err_invalid_arg	A required pointer contract is invalid.

Precondition

Non-NULL context points to initialized, exclusively owned body state.

bytes covers length bytes whenever length is nonzero.

Postcondition

Success advances received bytes by exactly length.

Failure reports zero current-chunk progress and publishes nothing.

Note

Empty writes are no-ops and do not begin a transaction.

Since

0.1.0

Definition at line 197 of file mdl_fetch_body.c.

References fw_fs_transaction_t::active, internal_body_begin(), internal_body_buffer_prefix(), internal_body_flush_prefix(), k_mdl_fetch_body_image, k_mdl_fetch_magic_bytes, k_ra8_err_invalid_arg, k_ra8_ok, mdl_storage_txn_write(), mdl_fetch_body_t::mode, mdl_fetch_body_t::prefix_bytes, mdl_fetch_body_t::received, mdl_storage_txn_t::transaction, and mdl_fetch_body_t::writer.

Referenced by priv_mdl_fetch_body_sink().

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