ra8_c6link_mdl.c File Reference

Pull-based media download client over generated protobuf codecs. More...

#include "ra8_c6link_mdl.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_c6link_internal.h"
#include "ra8_c6link_mdl_internal.h"
#include "ra8_media_download.pb-c.h"

Include dependency graph for ra8_c6link_mdl.c:

Go to the source code of this file.

Data Structures
struct	mdl_take_ctx_t
	Context consumed synchronously by the CustomRpc response extractor. More...
struct	mdl_http_headers_t
	Fixed-capacity storage for the four optional MDL HTTP request headers. More...

Enumerations
enum	mdl_take_kind_t : uint8_t {   k_mdl_take_accepted = 1U ,   k_mdl_take_chunk = 2U ,   k_mdl_take_cancelled = 3U }
	Response extractor variants. More...

Functions
static bool	internal_mdl_http_field_valid (const char *text, size_t cap)
	Validate one optional HTTP field against its protocol bound.
static bool	internal_mdl_http_response_valid (const Ra8__Mdl__Chunk *msg)
	Validate terminal HTTP metadata carried by a generated Chunk.
static void	internal_mdl_http_field_copy (char *destination, const char *source, size_t cap)
	Copy one already-bounded HTTP field into fixed response storage.
static ra8_err_t	internal_mdl_accept_chunk (mdl_take_ctx_t *take, const Ra8__Mdl__Chunk *msg)
	Copy one validated generated chunk and advance its active session.
static bool	internal_mdl_chunk_semantics_valid (const Ra8__Mdl__Chunk *msg)
	Validate state-specific fields of one correlated chunk.
static ra8_err_t	internal_mdl_take_accepted (mdl_take_ctx_t *take, const ProtobufCBinaryData *data)
	Decode and validate one accepted-job response.
static ra8_err_t	internal_mdl_take_chunk (mdl_take_ctx_t *take, const ProtobufCBinaryData *data)
	Decode a chunk and enforce correlation and size bounds.
static ra8_err_t	internal_mdl_take_cancelled (mdl_take_ctx_t *take, const uint8_t *data, size_t len)
	Decode a cancellation acknowledgement for the active job.
static ra8_err_t	internal_mdl_take_response (void *ctx, const void *msg_v)
	Extract one generated media payload from a CustomRpc response.
static ra8_err_t	internal_mdl_call (ra8_c6link_t *link, uint32_t operation, uint8_t *data, size_t data_len, mdl_take_ctx_t *take)
	Send one already-encoded generated message through CustomRpc.
ra8_err_t	ra8_c6link_mdl_take_cancelled_test (ra8_c6link_t *link, ra8_mdl_session_t *session, const uint8_t *packed, size_t len)
	Judge one cancellation acknowledgement exactly as the client does.
bool	ra8_c6link_mdl_http_field_valid_test (const char *text, size_t cap)
	Judge one decoded HTTP header exactly as the client does.
bool	ra8_c6link_mdl_http_response_valid_test (const Ra8__Mdl__Chunk *msg)
	Judge one decoded response's HTTP metadata exactly as the client does.
bool	ra8_c6link_mdl_chunk_semantics_valid_test (const Ra8__Mdl__Chunk *msg)
	Judge one decoded response's state semantics exactly as the client does.
static ra8_err_t	internal_mdl_start_request_valid (const ra8_mdl_request_t *request, size_t *out_url_len)
	Validate every caller-supplied start-request field before staging.
static void	internal_mdl_stage_headers (const ra8_mdl_http_policy_t *http, mdl_http_headers_t *out)
	Copy every present optional HTTP header into bounded local storage.
ra8_err_t	ra8_c6link_mdl_start_request (ra8_c6link_t *link, const ra8_mdl_request_t *request, ra8_mdl_session_t *session)
	Start one typed request while preserving downloader HTTP policy.
ra8_err_t	ra8_c6link_mdl_start (ra8_c6link_t *link, const char *url, mdl_format_t format, ra8_mdl_session_t *session)
	Start retrieval of one selected artifact and receive its job identifier.
ra8_err_t	ra8_c6link_mdl_next (ra8_c6link_t *link, ra8_mdl_session_t *session, uint16_t max_bytes, ra8_mdl_chunk_t *chunk)
	Pull the next bounded chunk while acknowledging the prior offset.
ra8_err_t	ra8_c6link_mdl_cancel (ra8_c6link_t *link, ra8_mdl_session_t *session)
	Cancel one active remote job and invalidate its local session.

Detailed Description

Pull-based media download client over generated protobuf codecs.

Encodes bounded media requests and validates every correlated response before mutating caller-owned session or chunk state.

Copyright

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

Definition in file ra8_c6link_mdl.c.

Enumeration Type Documentation

mdl_take_kind_t

enum mdl_take_kind_t : uint8_t

Response extractor variants.

Enumerator
k_mdl_take_accepted	Extract an Accepted response.
k_mdl_take_chunk	Extract a Chunk response.
k_mdl_take_cancelled	Extract a Cancelled response.

Definition at line 33 of file ra8_c6link_mdl.c.

Function Documentation

internal_mdl_accept_chunk()

ra8_err_t internal_mdl_accept_chunk ( mdl_take_ctx_t * take, const Ra8__Mdl__Chunk * msg )

static

Copy one validated generated chunk and advance its active session.

Translates generated state and metadata into the allocation-free client contract after correlation and capacity checks have succeeded.

Parameters

[in,out]	take	Active extraction and session context.
[in]	msg	Fully validated generated Chunk.

Returns

Remote terminal status.

Return values

k_ra8_ok	Data, completion, or cancellation was accepted.
other	The exact nonzero FAILED status supplied by the remote service.

Precondition

take and msg are non-null and correlation validation succeeded.

Generated byte/string spans remain live for the complete call.

Postcondition

Caller output contains the exact bounded decoded fields.

Session correlation advances once and terminal state deactivates it.

Note

This helper performs no protobuf allocation or release.

Since

0.1.0

Definition at line 152 of file ra8_c6link_mdl.c.

References ra8_mdl_session_t::active, mdl_take_ctx_t::chunk, Ra8__Mdl__Chunk::content_type, ra8_mdl_http_response_t::content_type, Ra8__Mdl__Chunk::data, ra8_mdl_chunk_t::data, Ra8__Mdl__Chunk::etag, ra8_mdl_http_response_t::etag, ra8_mdl_chunk_t::has_sha256, Ra8__Mdl__Chunk::http_status, internal_mdl_http_field_copy(), Ra8__Mdl__Chunk::job_id, k_ra8_mdl_sha256_bytes, k_ra8_ok, Ra8__Mdl__Chunk::last_modified, ra8_mdl_http_response_t::last_modified, memcpy(), ra8_mdl_session_t::next_offset, ra8_mdl_session_t::next_sequence, Ra8__Mdl__Chunk::offset, RA8__MDL__STATE__STATE_CANCELLED, RA8__MDL__STATE__STATE_COMPLETE, RA8__MDL__STATE__STATE_FAILED, RA8_INTERNAL, ra8_mdl_chunk_t::response, Ra8__Mdl__Chunk::retry_after, ra8_mdl_http_response_t::retry_after, Ra8__Mdl__Chunk::sequence, mdl_take_ctx_t::session, Ra8__Mdl__Chunk::sha256, ra8_mdl_chunk_t::sha256, Ra8__Mdl__Chunk::state, Ra8__Mdl__Chunk::status, ra8_mdl_http_response_t::status, and Ra8__Mdl__Chunk::total_bytes.

Referenced by internal_mdl_take_chunk().

internal_mdl_call()

ra8_err_t internal_mdl_call ( ra8_c6link_t * link, uint32_t operation, uint8_t * data, size_t data_len, mdl_take_ctx_t * take )

static

Send one already-encoded generated message through CustomRpc.

Wraps caller-owned inner bytes without retaining them after the synchronous call.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in]	operation	Stable media operation identifier.
[in]	data	Packed inner request bytes.
[in]	data_len	Valid bytes at data.
[in,out]	take	Expected response extraction context.

Returns

Transport, remote, or response-validation status.

Return values

k_ra8_ok	The expected response was extracted.
k_ra8_err_protocol_error	Response identity or payload was invalid.

Precondition

Every pointer is non-null and data_len is within the local buffer.

ra8_c6link_open succeeded and no concurrent caller uses link.

Postcondition

Inner request storage is no longer referenced when the call returns.

Response state changes only through internal_mdl_take_response.

Note

Synchronous and not thread-safe for a shared link.

Since

0.1.0

Definition at line 420 of file ra8_c6link_mdl.c.

References internal_mdl_take_response(), mdl_take_ctx_t::link, mdl_take_ctx_t::operation, priv_c6link_rpc_call(), and RA8_INTERNAL.

Referenced by ra8_c6link_mdl_cancel(), ra8_c6link_mdl_next(), and ra8_c6link_mdl_start_request().

internal_mdl_chunk_semantics_valid()

bool internal_mdl_chunk_semantics_valid ( const Ra8__Mdl__Chunk * msg )

static

Validate state-specific fields of one correlated chunk.

Enforces data/digest/status combinations and overflow-safe totals.

Parameters

[in]

msg

Decoded generated chunk.

Returns

Whether the semantic combination is valid.

Return values

true	State-specific fields and totals are coherent.
false	A state, size, status, or digest rule is violated.

Precondition

msg is non-null and decoded by the bounded link arena.

Binary-data lengths describe their decoded buffers.

Postcondition

No caller or decoded state is modified.

True guarantees later bounded copies are size-safe.

Note

Reentrant for independent decoded messages.

Since

0.1.0

Definition at line 208 of file ra8_c6link_mdl.c.

References Ra8__Mdl__Chunk::data, internal_mdl_http_response_valid(), k_ra8_mdl_sha256_bytes, Ra8__Mdl__Chunk::offset, RA8__MDL__STATE__STATE_CANCELLED, RA8__MDL__STATE__STATE_COMPLETE, RA8__MDL__STATE__STATE_DOWNLOADING, RA8__MDL__STATE__STATE_FAILED, RA8_INTERNAL, Ra8__Mdl__Chunk::sha256, Ra8__Mdl__Chunk::state, Ra8__Mdl__Chunk::status, and Ra8__Mdl__Chunk::total_bytes.

Referenced by internal_mdl_take_chunk(), and ra8_c6link_mdl_chunk_semantics_valid_test().

internal_mdl_http_field_copy()

void internal_mdl_http_field_copy ( char * destination, const char * source, size_t cap )

static

Copy one already-bounded HTTP field into fixed response storage.

Copies through the validated terminator so the public response retains the exact header spelling selected by the C6 service.

Parameters

[out]	destination	Fixed caller response array.
[in]	source	Validated NUL-terminated decoded field.
[in]	cap	Capacity of destination and validated source bound.

Precondition

Pointers are non-null and source terminates before cap.

Source and destination do not overlap.

Postcondition

Destination contains one exact NUL-terminated copy.

Bytes beyond the terminator are unchanged.

Note

Caller validation makes this helper infallible.

Since

0.1.0

Definition at line 130 of file ra8_c6link_mdl.c.

References memcpy(), and strnlen().

Referenced by internal_mdl_accept_chunk().

internal_mdl_http_field_valid()

bool internal_mdl_http_field_valid ( const char * text, size_t cap )

static

Validate one optional HTTP field against its protocol bound.

Treats null as absent and rejects CR/LF header injection.

Parameters

[in]	text	Optional NUL-terminated field.
[in]	cap	Maximum extent including NUL.

Returns

Field validity.

Return values

true	Field is absent or bounded and single-line.
false	Field is unterminated, too large, or contains CR/LF.

Precondition

cap is nonzero.

Non-null text is readable through its first NUL or cap bytes.

Postcondition

No input or global state is modified.

True guarantees the field can be encoded within its fixed bound.

Note

Pure and reentrant.

Since

0.1.0

Definition at line 66 of file ra8_c6link_mdl.c.

References RA8_INTERNAL, and strnlen().

Referenced by internal_mdl_http_response_valid(), internal_mdl_start_request_valid(), and ra8_c6link_mdl_http_field_valid_test().

internal_mdl_http_response_valid()

bool internal_mdl_http_response_valid ( const Ra8__Mdl__Chunk * msg )

static

Validate terminal HTTP metadata carried by a generated Chunk.

Requires a real status only on COMPLETE and bounds every selected response header before any caller copy.

Parameters

[in]

msg

Decoded generated chunk.

Returns

Metadata validity.

Return values

true	Metadata matches the chunk state and all string bounds.
false	Status, presence, termination, or a header bound is invalid.

Precondition

msg is non-null and owns decoded string pointers.

The protobuf arena remains live for the complete call.

Postcondition

No decoded or caller-owned state is modified.

True authorizes bounded response-header copies.

Note

Pure and reentrant for independent messages.

Since

0.1.0

Definition at line 98 of file ra8_c6link_mdl.c.

References Ra8__Mdl__Chunk::content_type, Ra8__Mdl__Chunk::etag, Ra8__Mdl__Chunk::http_status, internal_mdl_http_field_valid(), k_ra8_mdl_content_type_max, k_ra8_mdl_etag_max, k_ra8_mdl_http_date_max, k_ra8_mdl_http_status_max, k_ra8_mdl_http_status_min, k_ra8_mdl_retry_after_max, Ra8__Mdl__Chunk::last_modified, RA8__MDL__STATE__STATE_COMPLETE, RA8_INTERNAL, Ra8__Mdl__Chunk::retry_after, and Ra8__Mdl__Chunk::state.

Referenced by internal_mdl_chunk_semantics_valid(), and ra8_c6link_mdl_http_response_valid_test().

internal_mdl_stage_headers()

void internal_mdl_stage_headers ( const ra8_mdl_http_policy_t * http, mdl_http_headers_t * out )

static

Copy every present optional HTTP header into bounded local storage.

Split out of ra8_c6link_mdl_start_request() so that entry point stays under the reviewed statement-count threshold. Each field was already length-checked by internal_mdl_start_request_valid(), so each copy is bounded by its own protocol maximum; an absent field keeps the zero-initialized empty string.

Parameters

[in]	http	Caller-supplied optional headers; individual members may be null.
[out]	out	Zero-initialized staging storage to fill.

Returns

Nothing.

Precondition

http and out are non-null.

Every non-null member of http fits its protocol maximum.

Postcondition

Every present member is copied and NUL-terminated in out.

Absent members are left as the caller's zero initialization.

Note

Not thread-safe for a shared out.

Since

0.1.0

Definition at line 558 of file ra8_c6link_mdl.c.

References mdl_http_headers_t::if_modified_since, ra8_mdl_http_policy_t::if_modified_since, mdl_http_headers_t::if_none_match, ra8_mdl_http_policy_t::if_none_match, memcpy(), RA8_INTERNAL, mdl_http_headers_t::referer, ra8_mdl_http_policy_t::referer, strlen(), mdl_http_headers_t::user_agent, and ra8_mdl_http_policy_t::user_agent.

Referenced by ra8_c6link_mdl_start_request().

internal_mdl_start_request_valid()

ra8_err_t internal_mdl_start_request_valid ( const ra8_mdl_request_t * request, size_t * out_url_len )

static

Validate every caller-supplied start-request field before staging.

Split out of ra8_c6link_mdl_start_request() so the argument contract and the wire encoding are separately reviewable and each stays inside the NASA Power of 10 Rule 4 length cap. The validation checks and their order are unchanged; the null-pointer guards are split between the caller and this helper, and every one of them still yields k_ra8_err_null_ptr.

Parameters

[in]	request	Caller request; may be null.
[out]	out_url_len	Receives the validated URL length on success, so the caller copies exactly the length that was bounded here rather than re-deriving it from caller-owned memory. The single call site passes the address of a local, so this pointer is not re-checked here.

Returns

Validation status.

Return values

k_ra8_ok	Every field satisfies the documented contract.
k_ra8_err_null_ptr	request or its URL is null.
k_ra8_err_invalid_arg	A field is out of range or malformed.

Precondition

The caller has already rejected a null link and session.

out_url_len is non-null.

request is readable for the whole structure.

Postcondition

out_url_len holds the bounded URL length on success only.

The return value is one of the documented retvals.

Note

Not thread-safe for a shared request structure.

Since

0.1.0

Definition at line 497 of file ra8_c6link_mdl.c.

References ra8_mdl_request_t::format, ra8_mdl_request_t::http, ra8_mdl_http_policy_t::if_modified_since, ra8_mdl_http_policy_t::if_none_match, internal_mdl_http_field_valid(), k_mdl_format_rabook, k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_mdl_etag_max, k_ra8_mdl_http_date_max, k_ra8_mdl_referer_max, k_ra8_mdl_timeout_ms_max, k_ra8_mdl_url_max, k_ra8_mdl_user_agent_max, k_ra8_ok, RA8_INTERNAL, ra8_mdl_http_policy_t::referer, strncmp(), strnlen(), ra8_mdl_http_policy_t::timeout_ms, ra8_mdl_request_t::url, and ra8_mdl_http_policy_t::user_agent.

Referenced by ra8_c6link_mdl_start_request().

internal_mdl_take_accepted()

ra8_err_t internal_mdl_take_accepted ( mdl_take_ctx_t * take, const ProtobufCBinaryData * data )

static

Decode and validate one accepted-job response.

Uses the link-owned bounded arena and updates the session only after validation.

Parameters

[in,out]	take	Response extraction context.
[in]	data	Packed generated Accepted response.

Returns

Decode status.

Return values

k_ra8_ok	Session was activated with bounded correlation state.
k_ra8_err_protocol_error	Decode or field validation failed.

Precondition

take, its link/session, and data are non-null.

The link arena is exclusively owned for this synchronous callback.

Postcondition

Success initializes an active session.

Failure leaves the caller's session unchanged.

Note

Not thread-safe for a shared c6link arena.

Since

0.1.0

Definition at line 254 of file ra8_c6link_mdl.c.

References Ra8__Mdl__Accepted::base, Ra8__Mdl__Accepted::format, Ra8__Mdl__Accepted::job_id, k_ra8_err_protocol_error, k_ra8_mdl_chunk_data_max, k_ra8_mdl_protocol_version, k_ra8_ok, mdl_take_ctx_t::link, Ra8__Mdl__Accepted::max_chunk_bytes, priv_c6link_arena_bind(), Ra8__Mdl__Accepted::protocol_version, ra8__mdl__accepted__free_unpacked(), ra8__mdl__accepted__unpack(), RA8_INTERNAL, mdl_take_ctx_t::requested_format, and mdl_take_ctx_t::session.

Referenced by internal_mdl_take_response().

internal_mdl_take_cancelled()

ra8_err_t internal_mdl_take_cancelled ( mdl_take_ctx_t * take, const uint8_t * data, size_t len )

static

Decode a cancellation acknowledgement for the active job.

Rejects acknowledgements for another job or protocol version.

Parameters

[in,out]	take	Active extraction/session context.
[in]	data	Packed generated Cancelled response.
[in]	len	Valid bytes at data; the decoder reads no further.

Returns

Decode status.

Return values

k_ra8_ok	Matching cancellation deactivated the session.
k_ra8_err_protocol_error	Decode or correlation validation failed.

Precondition

take and its active session are non-null.

The link arena is exclusively owned for this callback.

Postcondition

Success makes the session inactive.

Failure preserves session activity for caller recovery.

Note

Not thread-safe for a shared session or c6link arena.

Since

0.1.0

Definition at line 336 of file ra8_c6link_mdl.c.

References ra8_mdl_session_t::active, Ra8__Mdl__Cancelled::base, Ra8__Mdl__Cancelled::job_id, ra8_mdl_session_t::job_id, k_ra8_err_protocol_error, k_ra8_mdl_protocol_version, k_ra8_ok, mdl_take_ctx_t::link, priv_c6link_arena_bind(), Ra8__Mdl__Cancelled::protocol_version, ra8__mdl__cancelled__free_unpacked(), ra8__mdl__cancelled__unpack(), mdl_take_ctx_t::session, and Ra8__Mdl__Cancelled::status.

Referenced by internal_mdl_take_response(), and ra8_c6link_mdl_take_cancelled_test().

internal_mdl_take_chunk()

ra8_err_t internal_mdl_take_chunk ( mdl_take_ctx_t * take, const ProtobufCBinaryData * data )

static

Decode a chunk and enforce correlation and size bounds.

Accepts only the exact active job, sequence, offset, and requested span.

Parameters

[in,out]	take	Active extraction/session context.
[in]	data	Packed generated Chunk response.

Returns

Decode or remote terminal status.

Return values

k_ra8_ok	A valid data or successful terminal chunk was copied.
k_ra8_err_protocol_error	Decode or correlation validation failed.

Precondition

take owns an active session and non-null output chunk.

The link arena is exclusively owned for this callback.

Postcondition

Success advances offset/sequence by exactly the decoded data length.

A valid terminal response deactivates the session.

Note

Not thread-safe for a shared session or c6link arena.

Since

0.1.0

Definition at line 298 of file ra8_c6link_mdl.c.

References Ra8__Mdl__Chunk::base, Ra8__Mdl__Chunk::data, internal_mdl_accept_chunk(), internal_mdl_chunk_semantics_valid(), Ra8__Mdl__Chunk::job_id, ra8_mdl_session_t::job_id, k_ra8_err_protocol_error, k_ra8_mdl_chunk_data_max, k_ra8_mdl_protocol_version, mdl_take_ctx_t::link, ra8_mdl_session_t::next_offset, ra8_mdl_session_t::next_sequence, Ra8__Mdl__Chunk::offset, priv_c6link_arena_bind(), Ra8__Mdl__Chunk::protocol_version, ra8__mdl__chunk__free_unpacked(), ra8__mdl__chunk__unpack(), RA8_INTERNAL, mdl_take_ctx_t::requested_bytes, Ra8__Mdl__Chunk::sequence, and mdl_take_ctx_t::session.

Referenced by internal_mdl_take_response().

internal_mdl_take_response()

ra8_err_t internal_mdl_take_response ( void * ctx, const void * msg_v )

static

Extract one generated media payload from a CustomRpc response.

Validates outer response identity/status before selecting the expected inner type.

Parameters

[in,out]	ctx	mdl_take_ctx_t selected by the initiating call.
[in]	msg_v	Decoded ESP-hosted Rpc response.

Returns

Extraction status.

Return values

k_ra8_ok	Expected inner response was accepted.
k_ra8_err_protocol_error	Outer or inner response is incoherent.

Precondition

ctx and msg_v are non-null for the synchronous callback.

kind matches the initiating media operation.

Postcondition

Success applies exactly one expected state transition.

Failure does not select a different inner response type.

Note

Not thread-safe for a shared c6link/session.

Since

0.1.0

Definition at line 370 of file ra8_c6link_mdl.c.

References internal_mdl_take_accepted(), internal_mdl_take_cancelled(), internal_mdl_take_chunk(), k_mdl_take_accepted, k_mdl_take_cancelled, k_mdl_take_chunk, k_ra8_err_protocol_error, k_ra8_ok, mdl_take_ctx_t::kind, mdl_take_ctx_t::link, mdl_take_ctx_t::operation, priv_c6link_resp(), and RA8_INTERNAL.

Referenced by internal_mdl_call().

ra8_c6link_mdl_cancel()

ra8_err_t ra8_c6link_mdl_cancel ( ra8_c6link_t * link, ra8_mdl_session_t * session )

nodiscard

Cancel one active remote job and invalidate its local session.

Sends the generated CancelRequest and validates the returned job id before changing local state.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in,out]	session	Active job to cancel.

Returns

Cancellation status.

Return values

k_ra8_ok	Remote acknowledged cancellation and session is inactive.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_state	Session is not active.
k_ra8_err_invalid_size	Encoded request exceeds its static buffer.
k_ra8_err_protocol_error	Cancellation acknowledgement is incoherent.
k_ra8_err_timeout	C6 did not answer inside the RPC budget.

Precondition

session came from a successful ra8_c6link_mdl_start.

No other thread uses link concurrently.

Postcondition

Success leaves session inactive.

Failure preserves the session for retry or caller recovery.

Note

Not thread-safe; the c6link handle and session are single-owner.

Since

0.1.0

Definition at line 659 of file ra8_c6link_mdl.c.

References ra8_mdl_session_t::active, internal_mdl_call(), Ra8__Mdl__CancelRequest::job_id, ra8_mdl_session_t::job_id, k_mdl_take_cancelled, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_mdl_protocol_version, k_ra8_mdl_rpc_cancel, ra8_c6link::mdl_request, Ra8__Mdl__CancelRequest::protocol_version, ra8__mdl__cancel_request__get_packed_size(), RA8__MDL__CANCEL_REQUEST__INIT, and ra8__mdl__cancel_request__pack().

Referenced by internal_mdl_transfer_abort().

ra8_c6link_mdl_chunk_semantics_valid_test()

bool ra8_c6link_mdl_chunk_semantics_valid_test

(

const Ra8__Mdl__Chunk *

msg

)

Judge one decoded response's state semantics exactly as the client does.

Forwards unchanged to the module-private predicate that enforces the data/digest/status combination each state permits, plus the overflow-safe relationship between offset, data length, and declared total.

Parameters

[in]

msg

Decoded generated chunk.

Returns

Semantic validity.

Return values

true	State, size, status, and digest fields are mutually coherent.
false	A state-specific rule or the total-covers-data rule is broken.

Precondition

msg is non-null and decoded into a live bounded arena.

Binary-data lengths describe their decoded buffers.

Postcondition

No decoded or session state is modified.

True guarantees the later bounded copies are size-safe.

Note

Test helper; pure and reentrant.

MC/DC:

Five decisions across four mutually exclusive states, up to six conditions each. Every vector needs one field of one state changed in isolation, which a transport fault cannot express without a new injection per condition.

Since

0.1.0

Definition at line 464 of file ra8_c6link_mdl.c.

References internal_mdl_chunk_semantics_valid(), and RA8_TEST_HELPER.

ra8_c6link_mdl_http_field_valid_test()

bool ra8_c6link_mdl_http_field_valid_test	(	const char *	text,
		size_t	cap )

Judge one decoded HTTP header exactly as the client does.

Forwards unchanged to the module-private predicate, so a focused test drives the shipped bound and line-discipline logic rather than a copy. An absent header is valid; the C6 service sends the empty string for one it did not observe.

Parameters

[in]	text	Candidate decoded protobuf string, or null for absent.
[in]	cap	Maximum extent including the terminating NUL.

Returns

Header validity.

Return values

true	Absent, or terminates before cap with no CR or LF.
false	The header is unterminated or carries a header-injection byte.

Precondition

cap is nonzero.

Non-null text is readable for at least cap bytes.

Postcondition

No decoded or session state is modified.

True authorizes copying the header into the public response.

Note

Test helper; pure and reentrant.

MC/DC:

The CR/LF decision needs one vector per byte class, and the C6 model would need a distinct hand-packed terminal response per vector to reach them.

Since

0.1.0

Definition at line 454 of file ra8_c6link_mdl.c.

References internal_mdl_http_field_valid(), and RA8_TEST_HELPER.

ra8_c6link_mdl_http_response_valid_test()

bool ra8_c6link_mdl_http_response_valid_test

(

const Ra8__Mdl__Chunk *

msg

)

Judge one decoded response's HTTP metadata exactly as the client does.

Forwards unchanged to the module-private predicate that separates a non-terminal response, which must carry no metadata at all, from a COMPLETE response, whose status must be HTTP-shaped and whose four selected headers must each be bounded single-line text.

Parameters

[in]

msg

Decoded generated chunk.

Returns

Metadata validity.

Return values

true	The metadata matches what this response's state permits.
false	A status or header rule for that state is violated.

Precondition

msg is non-null and decoded into a live bounded arena.

Every string member is null or NUL-terminated within its bound.

Postcondition

No decoded or session state is modified.

True authorizes the state-specific semantic checks that follow.

Note

Test helper; pure and reentrant.

MC/DC:

Two decisions, six conditions in the terminal one. Driving them through the modelled transport would need one malformed-header fault per condition, and the non-terminal decision would need a data response carrying metadata that the service is structurally unable to emit.

Since

0.1.0

Definition at line 459 of file ra8_c6link_mdl.c.

References internal_mdl_http_response_valid(), and RA8_TEST_HELPER.

ra8_c6link_mdl_next()

ra8_err_t ra8_c6link_mdl_next ( ra8_c6link_t * link, ra8_mdl_session_t * session, uint16_t max_bytes, ra8_mdl_chunk_t * chunk )

nodiscard

Pull the next bounded chunk while acknowledging the prior offset.

Encodes the session's exact next sequence/offset contract and advances it only after a correlated protobuf response passes validation.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in,out]	session	Active job correlation state.
[in]	max_bytes	Requested body-byte bound for this response.
[out]	chunk	Correlated response, including terminal metadata.

Returns

Pull status.

Return values

k_ra8_ok	A valid data or terminal response was decoded.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_state	Session is inactive or invalid.
k_ra8_err_invalid_size	Requested or encoded size exceeds a bound.
k_ra8_err_protocol_error	Job, sequence, offset, state, or fields are incoherent.
k_ra8_err_timeout	C6 did not answer inside the RPC budget.

Precondition

session came from a successful ra8_c6link_mdl_start.

max_bytes is non-zero and no larger than the negotiated maximum.

Postcondition

Success advances session correlation by exactly the returned data length.

A terminal response makes session inactive.

Note

Not thread-safe; the c6link handle and session are single-owner.

Since

0.1.0

Definition at line 624 of file ra8_c6link_mdl.c.

References Ra8__Mdl__NextRequest::acknowledged_offset, ra8_mdl_session_t::active, internal_mdl_call(), Ra8__Mdl__NextRequest::job_id, ra8_mdl_session_t::job_id, k_mdl_take_chunk, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_mdl_chunk_data_max, k_ra8_mdl_protocol_version, k_ra8_mdl_rpc_next, Ra8__Mdl__NextRequest::max_bytes, ra8_mdl_session_t::max_chunk_bytes, ra8_c6link::mdl_request, ra8_mdl_session_t::next_offset, Ra8__Mdl__NextRequest::protocol_version, ra8__mdl__next_request__get_packed_size(), RA8__MDL__NEXT_REQUEST__INIT, and ra8__mdl__next_request__pack().

Referenced by ra8_c6link_mdl_transfer().

ra8_c6link_mdl_start()

ra8_err_t ra8_c6link_mdl_start ( ra8_c6link_t * link, const char * url, mdl_format_t format, ra8_mdl_session_t * session )

nodiscard

Start retrieval of one selected artifact and receive its job identifier.

Encodes a generated protobuf StartRequest with the exact artifact identity. loose selects an untyped source body; other values require the returned bytes to be that format and must be validated before publication.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in]	url	NUL-terminated HTTPS source URL below k_ra8_mdl_url_max.
[in]	format	Artifact identity requested from the C6 backend.
[out]	session	Accepted job correlation state.

Returns

Start status.

Return values

k_ra8_ok	Remote job accepted.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	URL or format is invalid.
k_ra8_err_invalid_size	URL or encoded request exceeds its bound.
k_ra8_err_protocol_error	Remote response is malformed.
k_ra8_err_timeout	C6 did not answer inside the RPC budget.

Precondition

ra8_c6link_open completed successfully for link.

No other thread uses link concurrently.

Postcondition

Success produces an active non-zero job in session.

Failure leaves session inactive and zeroed after argument validation.

Note

Not thread-safe; the c6link handle is single-owner.

Since

0.1.0

Definition at line 615 of file ra8_c6link_mdl.c.

References ra8_c6link_mdl_start_request().

ra8_c6link_mdl_start_request()

ra8_err_t ra8_c6link_mdl_start_request ( ra8_c6link_t * link, const ra8_mdl_request_t * request, ra8_mdl_session_t * session )

nodiscard

Start one typed request while preserving downloader HTTP policy.

This is the protocol-v3 entry point used by the portable network adapter. It validates every bounded header locally before encoding it. ra8_c6link_mdl_start is the empty-policy convenience wrapper.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in]	request	Complete typed HTTPS request and optional headers.
[out]	session	Accepted job correlation state.

Returns

Start status.

Return values

k_ra8_ok	Remote job accepted.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	URL, format, timeout, or header is invalid.
k_ra8_err_invalid_size	A bounded string or request encoding is too large.
k_ra8_err_protocol_error	Remote response is malformed.

Precondition

ra8_c6link_open completed successfully for link.

No other thread uses link concurrently.

Postcondition

Success produces an active non-zero job in session.

Failure leaves session inactive after pointer validation.

Note

Not thread-safe; the c6link handle is single-owner.

Since

0.1.0

Definition at line 575 of file ra8_c6link_mdl.c.

References Ra8__Mdl__StartRequest::format, ra8_mdl_request_t::format, ra8_mdl_request_t::http, mdl_http_headers_t::if_modified_since, Ra8__Mdl__StartRequest::if_modified_since, mdl_http_headers_t::if_none_match, Ra8__Mdl__StartRequest::if_none_match, internal_mdl_call(), internal_mdl_stage_headers(), internal_mdl_start_request_valid(), k_mdl_take_accepted, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_mdl_protocol_version, k_ra8_mdl_rpc_start, k_ra8_mdl_url_max, k_ra8_ok, ra8_c6link::mdl_request, memcpy(), Ra8__Mdl__StartRequest::protocol_version, ra8__mdl__start_request__get_packed_size(), ra8__mdl__start_request__init(), ra8__mdl__start_request__pack(), mdl_http_headers_t::referer, Ra8__Mdl__StartRequest::referer, Ra8__Mdl__StartRequest::timeout_ms, ra8_mdl_http_policy_t::timeout_ms, Ra8__Mdl__StartRequest::url, ra8_mdl_request_t::url, mdl_http_headers_t::user_agent, and Ra8__Mdl__StartRequest::user_agent.

Referenced by internal_mdl_transfer_begin(), and ra8_c6link_mdl_start().

ra8_c6link_mdl_take_cancelled_test()

ra8_err_t ra8_c6link_mdl_take_cancelled_test	(	ra8_c6link_t *	link,
		ra8_mdl_session_t *	session,
		const uint8_t *	packed,
		size_t	len )

Judge one cancellation acknowledgement exactly as the client does.

Builds the fields of the take context the cancelled path reads and runs the identical decode-and-correlate path, so a test observes the client's real acceptance rule rather than a reimplementation of it.

Parameters

[in,out]	link	Open link whose bounded arena decodes the message.
[in,out]	session	Caller session the acknowledgement must correlate to.
[in]	packed	Packed generated Cancelled bytes.
[in]	len	Valid bytes at packed.

Returns

Decode status.

Return values

k_ra8_ok	A matching acknowledgement deactivated session.
k_ra8_err_protocol_error	Decode or correlation validation failed.

Precondition

link is open and session carries the expected job identity.

packed is readable for len bytes.

Postcondition

Success makes session inactive; failure preserves its state.

The decoded message is released before return; no decoded pointer escapes into session or to the caller.

Note

Test helper; not thread-safe for a shared link or session.

Since

0.1.0

Definition at line 445 of file ra8_c6link_mdl.c.

References internal_mdl_take_cancelled(), k_mdl_take_cancelled, and RA8_TEST_HELPER.