Digest-verified media network backend over C6link. More...

#include "mdl_net_c6link.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "mdl_net_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_net_c6link.c:

Data Structures
struct	mdl_c6_output_t
	Transaction state that turns one C6 body into a network response. More...

Enumerations
enum	mdl_c6_output_kind_t : uint8_t { k_mdl_c6_output_buffer = 1U , k_mdl_c6_output_sink = 2U }
	Output destination selected for one synchronous adapter call. More...

Functions
static ra8_err_t	internal_c6_output_begin (void ctx, const char destination)
	Begin the local half of one transfer transaction.
static ra8_err_t	internal_c6_output_write (void ctx, const uint8_t data, uint16_t len, uint16_t *written)
	Append one verified-order C6 chunk to the selected output.
static ra8_err_t	internal_c6_output_commit (void *ctx)
	Publish the completed response to the caller-visible output.
static ra8_err_t	internal_c6_output_abort (void *ctx)
	Discard caller-visible partial bytes after a failed transfer.
static ra8_err_t	internal_c6_get (mdl_net_c6link_t backend, const char url, const mdl_net_req_t req, mdl_c6_output_t output, size_t out_len, mdl_net_resp_t resp)
	Execute one digest-verified policy-preserving C6 GET.
static ra8_err_t	internal_c6_get_buf (void ctx, const char url, const mdl_net_req_t req, char buf, size_t cap, size_t out_len, mdl_net_resp_t resp)
	GET url fully into a caller buffer (used for HTML pages).
static ra8_err_t	internal_c6_get_body (void ctx, const char url, const mdl_net_req_t req, mdl_net_body_sink_t sink, size_t out_len, mdl_net_resp_t resp)
	GET url and stream the body through an injected sink.
static void	internal_c6_destroy (void *ctx)
	Release the backend-private state (called by mdl_net_destroy).
ra8_err_t	mdl_net_c6link_init (mdl_net_iface_t net, mdl_net_c6link_t backend, ra8_c6link_t link, const ra8_mdl_sha256_iface_t sha256, uint16_t chunk_bytes, uint32_t max_chunks)
	Bind an open C6 link as a portable media network backend.

Detailed Description

Digest-verified media network backend over C6link.

Adapts one bounded C6 transfer to either a caller text buffer or the downloader's reset/write body sink without owning storage or hash memory.

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

Definition in file mdl_net_c6link.c.

Enumeration Type Documentation

◆ mdl_c6_output_kind_t

enum mdl_c6_output_kind_t : uint8_t

Output destination selected for one synchronous adapter call.

Enumerator
k_mdl_c6_output_buffer	Bounded NUL-terminated caller buffer.
k_mdl_c6_output_sink	Injected streaming body sink.

Definition at line 20 of file mdl_net_c6link.c.

Function Documentation

◆ internal_c6_destroy()

void internal_c6_destroy ( void * ctx )

static

Release the backend-private state (called by mdl_net_destroy).

Parameters

[in] ctx Backend-private state (never NULL).

Definition at line 275 of file mdl_net_c6link.c.

References RA8_INTERNAL.

Referenced by mdl_net_c6link_init().

◆ internal_c6_get()

ra8_err_t internal_c6_get	(	mdl_net_c6link_t *	backend,
		const char *	url,
		const mdl_net_req_t *	req,
		mdl_c6_output_t *	output,
		size_t *	out_len,
		mdl_net_resp_t *	resp )

static

Execute one digest-verified policy-preserving C6 GET.

Binds the selected output as a transfer storage transaction, runs the C6 coordinator, and copies only metadata proven by the wire.

Parameters

[in,out]	backend	Bound C6 network state.
[in]	url	HTTPS source URL.
[in]	req	Request policy to validate.
[in,out]	output	Selected caller output transaction.
[out]	out_len	Optional completed byte length.
[out]	resp	Optional observed response metadata.

Returns: Transfer, sink, or digest status.

Return values

k_ra8_ok	The complete verified body has HTTP status below 400.
k_ra8_err_busy	HTTP status 429 or 503 requires backoff.
k_ra8_err_not_found	Another HTTP 4xx status was observed.
k_ra8_fail	An HTTP 5xx status was observed.

Precondition: Pointer arguments are non-null except optional outputs.; The C6 link and SHA context are exclusively owned.

Postcondition: Success reports the exact terminal HTTP status and selected headers.; Failure leaves partial output cleared by the transaction abort.

Note: Classification is shared exactly with the curl backend.

Since: 0.1.0

Definition at line 190 of file mdl_net_c6link.c.

References ra8_mdl_transfer_result::bytes_stored, mdl_net_c6link_t::chunk_bytes, mdl_net_resp_t::content_type, ra8_mdl_http_response_t::content_type, mdl_net_resp_t::etag, ra8_mdl_http_response_t::etag, mdl_net_req_t::if_modified_since, mdl_net_req_t::if_none_match, internal_c6_output_abort(), internal_c6_output_begin(), internal_c6_output_commit(), internal_c6_output_write(), k_mdl_format_loose, k_ra8_err_invalid_size, k_ra8_ok, mdl_net_resp_t::last_modified, ra8_mdl_http_response_t::last_modified, mdl_net_c6link_t::link, mdl_net_c6link_t::max_chunks, memcpy(), priv_mdl_net_classify_http(), ra8_c6link_mdl_transfer(), RA8_INTERNAL, mdl_net_req_t::referer, ra8_mdl_transfer_result::response, mdl_net_resp_t::retry_after, ra8_mdl_http_response_t::retry_after, mdl_net_c6link_t::sha256, mdl_net_resp_t::status, ra8_mdl_http_response_t::status, mdl_net_req_t::timeout_ms, and mdl_net_req_t::user_agent.

Referenced by internal_c6_get_body(), and internal_c6_get_buf().

◆ internal_c6_get_body()

ra8_err_t internal_c6_get_body	(	void *	ctx,
		const char *	url,
		const mdl_net_req_t *	req,
		mdl_net_body_sink_t *	sink,
		size_t *	out_len,
		mdl_net_resp_t *	resp )

static

GET url and stream the body through an injected sink.

Parameters

[in]	ctx	Backend-private state (never NULL).
[in]	url	Absolute, scheme-validated http/https URL.
[in]	req	Session parameters (never NULL).
[in,out]	sink	Caller-owned bounded body sink (never NULL).
[out]	out_len	Bytes written. May be NULL.
[out]	resp	Response metadata (status + Retry-After). May be NULL.

Returns: An ra8_err_t per the mdl_net_get_body contract.

Definition at line 260 of file mdl_net_c6link.c.

References internal_c6_get(), k_mdl_c6_output_sink, and RA8_INTERNAL.

Referenced by mdl_net_c6link_init().

◆ internal_c6_get_buf()

ra8_err_t internal_c6_get_buf	(	void *	ctx,
		const char *	url,
		const mdl_net_req_t *	req,
		char *	buf,
		size_t	cap,
		size_t *	out_len,
		mdl_net_resp_t *	resp )

static

GET url fully into a caller buffer (used for HTML pages).

Parameters

[in]	ctx	Backend-private state (never NULL).
[in]	url	Absolute, scheme-validated http/https URL.
[in]	req	Session parameters (never NULL).
[out]	buf	Destination buffer (never NULL).
[in]	cap	Capacity of buf in bytes (never 0).
[out]	out_len	Bytes written (excluding any NUL). May be NULL.
[out]	resp	Response metadata (status + Retry-After). May be NULL.

Returns: An ra8_err_t per the mdl_net_get_buf contract.

Definition at line 243 of file mdl_net_c6link.c.

References internal_c6_get(), k_mdl_c6_output_buffer, and RA8_INTERNAL.

Referenced by mdl_net_c6link_init().

◆ internal_c6_output_abort()

ra8_err_t internal_c6_output_abort ( void * ctx )

static

Discard caller-visible partial bytes after a failed transfer.

Clears bounded text directly or delegates reset to the injected body sink, preserving cleanup failure for coordinator precedence.

Parameters

[in,out] ctx Bound mdl_c6_output_t.

Returns: Cleanup status.

Return values

k_ra8_ok Partial output was cleared.

Precondition: ctx points to live adapter-call state.; A prior begin succeeded.

Postcondition: Buffer output is empty; streaming output was reset.; Accepted length is zero on successful cleanup.

Note: A sink reset failure is propagated only when no earlier cause wins.

Since: 0.1.0

Definition at line 153 of file mdl_net_c6link.c.

References mdl_c6_output_t::buffer, mdl_net_body_sink_t::ctx, k_mdl_c6_output_buffer, k_ra8_ok, mdl_c6_output_t::kind, mdl_c6_output_t::length, RA8_INTERNAL, mdl_net_body_sink_t::reset, and mdl_c6_output_t::sink.

Referenced by internal_c6_get().

◆ internal_c6_output_begin()

ra8_err_t internal_c6_output_begin	(	void *	ctx,
		const char *	destination )

static

Begin the local half of one transfer transaction.

Validates the coordinator placeholder and resets only the selected local output shape before the first remote body chunk arrives.

Parameters

[in,out]	ctx	Bound mdl_c6_output_t.
[in]	destination	Nonempty coordinator placeholder.

Returns: Local readiness status.

Return values

k_ra8_ok	Output state was reset for a new body.
k_ra8_err_invalid_arg	Context or destination is invalid.

Precondition: ctx points to exclusively owned adapter-call state.; Streaming sinks were reset by mdl_net_get_body before dispatch.

Postcondition: Success sets the accepted length to zero.; Buffer output starts as an empty C string.

Note: Does not reset a streaming sink a second time.

Since: 0.1.0

Definition at line 59 of file mdl_net_c6link.c.

References mdl_c6_output_t::buffer, k_mdl_c6_output_buffer, k_ra8_err_invalid_arg, k_ra8_ok, mdl_c6_output_t::kind, mdl_c6_output_t::length, and RA8_INTERNAL.

Referenced by internal_c6_get().

◆ internal_c6_output_commit()

ra8_err_t internal_c6_output_commit ( void * ctx )

static

Publish the completed response to the caller-visible output.

Terminates bounded text output after digest validation; streaming sinks are already caller-visible and require no extra operation.

Parameters

[in,out] ctx Bound mdl_c6_output_t.

Returns: Publication status.

Return values

k_ra8_ok Output is complete and visible.

Precondition: Transport length and digest validation have completed.; Text output retains at least one byte for its terminator.

Postcondition: Buffer output is NUL-terminated at the exact body length.; Streaming output is unchanged because its sink owns publication.

Note: Synchronous and allocation-free.

Since: 0.1.0

Definition at line 130 of file mdl_net_c6link.c.

References mdl_c6_output_t::buffer, k_mdl_c6_output_buffer, k_ra8_ok, mdl_c6_output_t::kind, mdl_c6_output_t::length, and RA8_INTERNAL.

Referenced by internal_c6_get().

◆ internal_c6_output_write()

ra8_err_t internal_c6_output_write	(	void *	ctx,
		const uint8_t *	data,
		uint16_t	len,
		uint16_t *	written )

static

Append one verified-order C6 chunk to the selected output.

Copies into the bounded text destination or delegates to the injected streaming sink while enforcing exact progress.

Parameters

[in,out]	ctx	Bound mdl_c6_output_t.
[in]	data	Remote body bytes.
[in]	len	Valid byte count.
[out]	written	Exact bytes accepted.

Returns: Sink status.

Return values

k_ra8_ok	Every byte was accepted.
k_ra8_err_no_mem	Text output lacks room for bytes plus trailing NUL.
k_ra8_err_invalid_size	A sink reported impossible progress.

Precondition: All pointers are non-null and data spans len bytes.; Chunks arrive in the order enforced by the transfer coordinator.

Postcondition: Success advances output length by exactly len.; Failure reports zero accepted bytes to the coordinator.

Note: Synchronous and not thread-safe for a shared output.

Since: 0.1.0

Definition at line 92 of file mdl_net_c6link.c.

References mdl_c6_output_t::buffer, mdl_c6_output_t::cap, mdl_net_body_sink_t::ctx, k_mdl_c6_output_buffer, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_ok, mdl_c6_output_t::kind, mdl_c6_output_t::length, memcpy(), mdl_c6_output_t::sink, and mdl_net_body_sink_t::write.

Referenced by internal_c6_get().

◆ mdl_net_c6link_init()

ra8_err_t mdl_net_c6link_init	(	mdl_net_iface_t *	net,
		mdl_net_c6link_t *	backend,
		ra8_c6link_t *	link,
		const ra8_mdl_sha256_iface_t *	sha256,
		uint16_t	chunk_bytes,
		uint32_t	max_chunks )

nodiscard

Bind an open C6 link as a portable media network backend.

Parameters

[out]	net	Interface returned to downloader/session code.
[out]	backend	Caller-owned backend state retained by `net`.
[in,out]	link	Already-open exclusively owned C6 link.
[in]	sha256	Complete caller-owned streaming SHA-256 seam.
[in]	chunk_bytes	Requested bytes per pull.
[in]	max_chunks	Hard maximum pulls per response.

Returns: Binding status.

Return values

k_ra8_ok	The interface is ready for policy-preserving HTTPS requests.
k_ra8_err_null_ptr	A required pointer or SHA callback is null.
k_ra8_err_invalid_size	A transfer bound is zero or excessive.

Precondition: No request is active on link or backend.; SHA context storage remains live until the interface is destroyed.

Postcondition: Success initializes both caller-owned output objects.; Failure leaves net and backend zeroed after pointer validation.

Note: The binding owns neither the link nor SHA context.

Since: 0.1.0

Immutable method table for caller-owned C6 backend state.

Definition at line 280 of file mdl_net_c6link.c.

References ra8_mdl_sha256_iface::ctx, ra8_mdl_sha256_iface::final, ra8_mdl_sha256_iface::init, internal_c6_destroy(), internal_c6_get_body(), internal_c6_get_buf(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_mdl_chunk_data_max, k_ra8_ok, and ra8_mdl_sha256_iface::update.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_c6_output_kind_t

Function Documentation

◆ internal_c6_destroy()

◆ internal_c6_get()

◆ internal_c6_get_body()

◆ internal_c6_get_buf()

◆ internal_c6_output_abort()

◆ internal_c6_output_begin()

◆ internal_c6_output_commit()

◆ internal_c6_output_write()

◆ mdl_net_c6link_init()