ra8_c6link_mdl_transfer.c File Reference

Bounded transactional coordinator for C6 media byte streams. More...

#include "ra8_c6link_mdl_transfer.h"
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_c6link_mdl_transfer_internal.h"

Include dependency graph for ra8_c6link_mdl_transfer.c:

Go to the source code of this file.

Data Structures
struct	mdl_transfer_state_t
	State that must be unwound together after storage begins. More...

Functions
static ra8_err_t	internal_mdl_transfer_validate (const ra8_c6link_t *link, const char *url, const char *destination, const ra8_mdl_transfer_config_t *config, const ra8_mdl_transfer_result_t *result)
	Validate every injected mechanism before creating temporary state.
static ra8_err_t	internal_mdl_transfer_abort (mdl_transfer_state_t *state, ra8_err_t cause)
	Cancel the remote job when active and always abort local temporary state.
static ra8_err_t	internal_mdl_transfer_store (const ra8_mdl_transfer_config_t *config, const ra8_mdl_chunk_t *chunk, uint64_t *bytes_stored)
	Persist and hash one non-terminal ordered chunk.
static ra8_err_t	internal_mdl_transfer_commit (mdl_transfer_state_t *state, const ra8_mdl_chunk_t *chunk, uint64_t bytes_stored, uint32_t chunks_received, ra8_mdl_transfer_result_t *result)
	Verify terminal metadata, validate identity, and commit the object.
ra8_err_t	ra8_c6link_mdl_transfer_commit_test (const ra8_mdl_transfer_config_t *config, const ra8_mdl_chunk_t *chunk, uint64_t bytes_stored, uint32_t chunks_received, ra8_mdl_transfer_result_t *result)
	Run the terminal commit stage against a caller-supplied chunk.
static ra8_err_t	internal_mdl_transfer_begin (ra8_c6link_t *link, const char *url, const char *destination, const ra8_mdl_transfer_config_t *config, ra8_mdl_transfer_result_t *result, mdl_transfer_state_t *state)
	Validate configuration, then start local storage and the remote job.
ra8_err_t	ra8_c6link_mdl_transfer (ra8_c6link_t *link, const char *url, const char *destination, const ra8_mdl_transfer_config_t *config, ra8_mdl_transfer_result_t *result)
	Fetch, verify, and atomically publish one remote byte stream.

Detailed Description

Bounded transactional coordinator for C6 media byte streams.

Tag

[Ring 4 / PAL] {World: NS}

Implements the storage/hash composition declared by ra8_c6link_mdl_transfer.h. It owns no static state and allocates no heap.

Copyright

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

Definition in file ra8_c6link_mdl_transfer.c.

Function Documentation

internal_mdl_transfer_abort()

ra8_err_t internal_mdl_transfer_abort ( mdl_transfer_state_t * state, ra8_err_t cause )

static

Cancel the remote job when active and always abort local temporary state.

Cleanup failures are returned only when no earlier cause exists.

Parameters

[in,out]	state	Transfer resources to unwind.
[in]	cause	Original failure, or success when cleanup itself triggered the result.

Returns

Original cause, then cancel error, then abort error in priority order.

Return values

k_ra8_ok	No cause and both cleanup operations succeeded.
k_ra8_err_cancelled	Cancellation completed normally.
k_ra8_fail	A cleanup mechanism failed without an earlier cause.

Precondition

state and its configuration are non-null.

storage_active accurately records successful begin.

Postcondition

The remote is asked to cancel if its session remains active.

Storage abort is called exactly once when active.

Note

Not thread-safe; it mutates the session and storage context.

Since

0.1.0

Definition at line 101 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_storage_iface::abort, ra8_mdl_session_t::active, mdl_transfer_state_t::config, ra8_mdl_storage_iface::ctx, k_ra8_ok, mdl_transfer_state_t::link, ra8_c6link_mdl_cancel(), RA8_INTERNAL, mdl_transfer_state_t::session, ra8_mdl_transfer_config::storage, and mdl_transfer_state_t::storage_active.

Referenced by ra8_c6link_mdl_transfer().

internal_mdl_transfer_begin()

ra8_err_t internal_mdl_transfer_begin ( ra8_c6link_t * link, const char * url, const char * destination, const ra8_mdl_transfer_config_t * config, ra8_mdl_transfer_result_t * result, mdl_transfer_state_t * state )

static

Validate configuration, then start local storage and the remote job.

Splits the transactional preamble from the per-chunk pull loop so ra8_c6link_mdl_transfer stays within its statement budget. Zeroes result once validation passes, and leaves state->storage_active false on any failure that precedes a successful storage.begin – the caller uses that flag to decide whether cleanup is required.

Parameters

[in]	link	Open c6link handle to bind into state.
[in]	url	Source URL for the remote StartRequest.
[in]	destination	Local destination handed to storage.begin.
[in]	config	Injected storage/hash/transport configuration.
[out]	result	Zeroed once configuration validation passes.
[out]	state	Prepared transfer state for the pull loop or cleanup.

Returns

Status to return immediately, or k_ra8_ok to enter the pull loop.

Return values

k_ra8_ok	The remote job is started; the pull loop may proceed.
other	Validation, storage, hash, or transport start-up failed.

Precondition

link, url, destination, config, and result are non-null.

state has not been used by an earlier transfer.

Postcondition

state->storage_active is true if and only if config->storage.begin returned k_ra8_ok.

On validation failure, neither storage nor the remote job is touched.

Note

Not thread-safe; it mutates injected storage/hash contexts.

Since

0.1.0

Definition at line 254 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_storage_iface::begin, mdl_transfer_state_t::config, ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, ra8_mdl_transfer_config::format, ra8_mdl_transfer_config::http, ra8_mdl_sha256_iface::init, internal_mdl_transfer_validate(), k_ra8_ok, mdl_transfer_state_t::link, ra8_c6link_mdl_start_request(), RA8_INTERNAL, mdl_transfer_state_t::session, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_config::storage, and mdl_transfer_state_t::storage_active.

Referenced by ra8_c6link_mdl_transfer().

internal_mdl_transfer_commit()

ra8_err_t internal_mdl_transfer_commit ( mdl_transfer_state_t * state, const ra8_mdl_chunk_t * chunk, uint64_t bytes_stored, uint32_t chunks_received, ra8_mdl_transfer_result_t * result )

static

Verify terminal metadata, validate identity, and commit the object.

Finalises the independent hash only after byte-count agreement, then gives an optional artifact validator the complete private object before atomic publication.

Parameters

[in,out]	state	Active transfer state.
[in]	chunk	Terminal COMPLETE response.
[in]	bytes_stored	Durable byte count.
[in]	chunks_received	Number of remote responses consumed.
[out]	result	Result written only after commit succeeds.

Returns

Verification or commit status.

Return values

k_ra8_ok	Digest matched and storage committed atomically.
k_ra8_err_invalid_size	Remote and local byte counts disagree.
k_ra8_err_checksum_mismatch	SHA-256 digests disagree.
k_ra8_fail	Hash finalisation or storage commit failed.

Precondition

chunk is a COMPLETE response carrying SHA-256.

Storage transaction is active and uncommitted.

Postcondition

Success clears storage_active and fills result.

Failure leaves storage_active set for caller cleanup.

Note

Not thread-safe; it finalises and commits injected contexts.

Since

0.1.0

Definition at line 182 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_storage_iface::commit, mdl_transfer_state_t::config, ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, ra8_mdl_sha256_iface::final, ra8_mdl_transfer_config::format, ra8_mdl_chunk_t::has_sha256, k_ra8_err_checksum_mismatch, k_ra8_err_invalid_size, k_ra8_mdl_sha256_bytes, k_ra8_ok, memcmp(), memcpy(), RA8_INTERNAL, ra8_mdl_chunk_t::response, ra8_mdl_chunk_t::sha256, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_result::sha256, ra8_mdl_transfer_config::storage, mdl_transfer_state_t::storage_active, ra8_mdl_chunk_t::total_bytes, and ra8_mdl_storage_iface::validate.

Referenced by ra8_c6link_mdl_transfer(), and ra8_c6link_mdl_transfer_commit_test().

internal_mdl_transfer_store()

ra8_err_t internal_mdl_transfer_store ( const ra8_mdl_transfer_config_t * config, const ra8_mdl_chunk_t * chunk, uint64_t * bytes_stored )

static

Persist and hash one non-terminal ordered chunk.

Rejects short successful writes because they would make the local digest describe bytes that are not durable in the temporary object.

Parameters

[in]	config	Injected storage and hash mechanisms.
[in]	chunk	Validated remote chunk.
[in,out]	bytes_stored	Running durable byte count.

Returns

Persistence status.

Return values

k_ra8_ok	Every chunk byte was persisted and hashed.
k_ra8_err_invalid_size	The write was short or the count overflowed.
k_ra8_fail	The storage or hash implementation failed.

Precondition

chunk is a DOWNLOADING response with non-zero data_len.

bytes_stored equals the temporary object's current length.

Postcondition

Success advances bytes_stored by exactly data_len.

Failure never commits the temporary object.

Note

Not thread-safe; it mutates injected contexts.

Since

0.1.0

Definition at line 137 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, ra8_mdl_chunk_t::data, ra8_mdl_chunk_t::data_len, k_ra8_err_invalid_size, k_ra8_ok, RA8_INTERNAL, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_config::storage, ra8_mdl_sha256_iface::update, and ra8_mdl_storage_iface::write.

Referenced by ra8_c6link_mdl_transfer().

internal_mdl_transfer_validate()

ra8_err_t internal_mdl_transfer_validate ( const ra8_c6link_t * link, const char * url, const char * destination, const ra8_mdl_transfer_config_t * config, const ra8_mdl_transfer_result_t * result )

static

Validate every injected mechanism before creating temporary state.

Keeps configuration rejection separate from transactional cleanup.

Parameters

[in]	link	Candidate open c6link handle.
[in]	url	Candidate source URL.
[in]	destination	Candidate RA8-local destination.
[in]	config	Candidate fixed transfer configuration.
[out]	result	Candidate result storage.

Returns

Validation status.

Return values

k_ra8_ok	Every required value is present and bounded.
k_ra8_err_null_ptr	A required value or function is null.
k_ra8_err_invalid_size	A numeric bound is invalid.

Precondition

Arguments may be null because this function validates them.

No injected callback has run.

Postcondition

No caller-owned state is modified.

Success guarantees every later indirect call target is non-null.

Note

Thread-safe when the caller does not mutate config concurrently.

Since

0.1.0

Definition at line 51 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_storage_iface::abort, ra8_mdl_storage_iface::begin, ra8_mdl_transfer_config::chunk_bytes, ra8_mdl_storage_iface::commit, ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, ra8_mdl_sha256_iface::final, ra8_mdl_transfer_config::format, ra8_mdl_sha256_iface::init, k_mdl_format_loose, k_mdl_format_rabook, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_mdl_chunk_data_max, k_ra8_mdl_transfer_bytes_max, k_ra8_ok, ra8_mdl_transfer_config::max_chunks, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_config::storage, ra8_mdl_sha256_iface::update, ra8_mdl_storage_iface::validate, and ra8_mdl_storage_iface::write.

Referenced by internal_mdl_transfer_begin().

ra8_c6link_mdl_transfer()

ra8_err_t ra8_c6link_mdl_transfer ( ra8_c6link_t * link, const char * url, const char * destination, const ra8_mdl_transfer_config_t * config, ra8_mdl_transfer_result_t * result )

nodiscard

Fetch, verify, and atomically publish one remote byte stream.

Starts a typed artifact transfer on an already-open c6link, pulls ordered bounded chunks, hashes exactly the bytes accepted by storage, compares the local digest with the C6 terminal digest, invokes the optional artifact validator against the private object, then commits. SHA equality proves transport integrity but does not prove .rabook identity: callers claiming any non-loose format must supply storage.validate. After a successful storage begin, every non-success path calls abort; an active remote session is also cancelled on local failure or cancellation.

Parameters

[in,out]	link	Already-open, exclusively owned c6link handle.
[in]	url	NUL-terminated source URL accepted by the C6 HTTPS backend.
[in]	destination	RA8-local destination understood only by storage.
[in]	config	Complete fixed-size storage, hash, cancellation, and bound policy.
[out]	result	Verified committed byte count and digest.

Returns

Canonical transfer status.

Return values

k_ra8_ok	Object verified and atomically committed.
k_ra8_err_null_ptr	Required pointer or injected function is null.
k_ra8_err_invalid_arg	Configuration or URL is invalid.
k_ra8_err_invalid_size	Chunk bound, response length, or byte count is invalid.
k_ra8_err_protocol_error	Remote state or ordering is incoherent.
k_ra8_err_checksum_mismatch	Local and remote SHA-256 digests differ.
k_ra8_err_cancelled	Caller requested cancellation or remote cancelled.
k_ra8_err_timeout	max_chunks was exhausted before completion.
k_ra8_fail	Injected storage, hash, or transport mechanism failed.

Precondition

ra8_c6link_open completed successfully for link.

No other thread uses link or any injected context concurrently.

Postcondition

Success leaves exactly one committed destination and no temporary state.

Failure leaves no committed destination and calls storage abort exactly once.

Note

Not thread-safe; c6link and injected contexts require exclusive ownership.

Warning

commit must provide the atomic publication guarantee; this module cannot synthesize it.

See also

ra8_c6link_mdl_start

Since

0.1.0

Definition at line 286 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_session_t::active, ra8_mdl_transfer_config::cancel_ctx, ra8_mdl_transfer_config::cancel_requested, ra8_mdl_transfer_config::chunk_bytes, internal_mdl_transfer_abort(), internal_mdl_transfer_begin(), internal_mdl_transfer_commit(), internal_mdl_transfer_store(), k_ra8_err_cancelled, k_ra8_err_timeout, k_ra8_mdl_state_cancelled, k_ra8_mdl_state_complete, k_ra8_mdl_state_downloading, k_ra8_ok, ra8_mdl_transfer_config::max_chunks, ra8_c6link_mdl_next(), mdl_transfer_state_t::session, ra8_mdl_chunk_t::state, and mdl_transfer_state_t::storage_active.

Referenced by internal_c6_get(), internal_transfer_and_consume(), and priv_media_download_image_run().

ra8_c6link_mdl_transfer_commit_test()

ra8_err_t ra8_c6link_mdl_transfer_commit_test	(	const ra8_mdl_transfer_config_t *	config,
		const ra8_mdl_chunk_t *	chunk,
		uint64_t	bytes_stored,
		uint32_t	chunks_received,
		ra8_mdl_transfer_result_t *	result )

Run the terminal commit stage against a caller-supplied chunk.

Forwards every argument unchanged to the module-private production commit helper with an active storage transaction, so a focused test drives the exact shipped digest-comparison, artifact-validation, and publication sequence rather than a copy of it.

Parameters

[in]	config	Complete transfer configuration supplying storage and hash.
[in]	chunk	Terminal chunk whose metadata the stage must verify.
[in]	bytes_stored	Durable byte count the injected digest describes.
[in]	chunks_received	Number of remote responses consumed.
[out]	result	Result written only after commit succeeds.

Returns

Verification or commit status from the production helper.

Return values

k_ra8_ok	Digest matched and storage committed atomically.
k_ra8_err_invalid_size	The digest is absent or the counts disagree.
k_ra8_err_checksum_mismatch	SHA-256 digests disagree.
k_ra8_fail	Hash finalisation or storage commit failed.

Precondition

config, chunk, and result are non-null and caller-owned.

The injected hash stream has already consumed bytes_stored bytes.

Postcondition

Success fills result with the committed identity.

Failure leaves result unmodified by this stage.

Note

Test helper; not thread-safe because it finalises injected contexts.

MC/DC:

The only seam that can drive (!chunk->has_sha256) true. A COMPLETE response without the mandatory 32-byte digest is rejected by the chunk-semantics validator in ra8_c6link_mdl.c before ra8_c6link_mdl_transfer() ever sees it, so that operand of the terminal-metadata guard has no public-API vector.

Since

0.1.0

Definition at line 220 of file ra8_c6link_mdl_transfer.c.

References internal_mdl_transfer_commit().