mdl_net.c File Reference

Backend-agnostic dispatchers for the mdl_net_iface_t vtable seam. More...

#include "mdl_net.h"
#include <stddef.h>
#include <string.h>
#include "mdl_net_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_net.c:

Go to the source code of this file.

Enumerations
enum	mdl_http_status_t : long {   k_mdl_http_client_error = 400L ,   k_mdl_http_too_many = 429L ,   k_mdl_http_server_error = 500L ,   k_mdl_http_unavailable = 503L }
	HTTP statuses that have downloader-specific handling. More...

Functions
ra8_err_t	priv_mdl_net_classify_http (long status)
	Classify one observed HTTP response status.
static void	internal_resp_reset (mdl_net_resp_t *resp)
	Zero a caller-supplied response block so early returns leave it clean.
ra8_err_t	mdl_net_provider_open (const mdl_net_provider_t *provider, const mdl_net_policy_t *policy, mdl_net_iface_t *out_net)
	Open a transport through an injected provider.
ra8_err_t	mdl_net_get_buf (mdl_net_iface_t *net, 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).
ra8_err_t	mdl_net_get_body (mdl_net_iface_t *net, 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 its body through a caller-owned sink.
void	mdl_net_destroy (mdl_net_iface_t *net)
	Deinitialise a caller-owned network interface.

Detailed Description

Backend-agnostic dispatchers for the mdl_net_iface_t vtable seam.

The thin layer every network caller actually reaches: it validates the handle and arguments, then forwards to the registered backend method with the backend's opaque ctx. It pulls in no libcurl and no concrete backend, so it links into the host unit tests alongside a scripted fake exactly as it links into the production tool alongside the libcurl backend – which is what makes the argument-validation decisions here testable without a network.

Copyright

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

Definition in file mdl_net.c.

Enumeration Type Documentation

mdl_http_status_t

enum mdl_http_status_t : long

HTTP statuses that have downloader-specific handling.

Enumerator
k_mdl_http_client_error	First client-error status.
k_mdl_http_too_many	Too Many Requests.
k_mdl_http_server_error	First server-error status.
k_mdl_http_unavailable	Service Unavailable.

Definition at line 24 of file mdl_net.c.

Function Documentation

internal_resp_reset()

void internal_resp_reset ( mdl_net_resp_t * resp )

static

Zero a caller-supplied response block so early returns leave it clean.

Accepts NULL so dispatcher validation paths can reset unconditionally.

Parameters

[out]

resp

Optional response metadata block.

Returns

Nothing.

Precondition

resp is NULL or points to writable mdl_net_resp_t storage.

The caller no longer needs the prior metadata.

Postcondition

A non-NULL response contains only zero bytes.

NULL input has no effect.

Note

Not thread-safe when callers share resp.

Since

0.1.0

Definition at line 57 of file mdl_net.c.

References memset(), and RA8_INTERNAL.

Referenced by mdl_net_get_body(), and mdl_net_get_buf().

mdl_net_destroy()

void mdl_net_destroy

(

mdl_net_iface_t *

net

)

Deinitialise a caller-owned network interface.

NULL-safe.

Forwards to the backend's destroy method, then clears the caller-owned handle. Neither the dispatcher nor a conforming backend frees net or its context: concrete composition roots provide all storage explicitly.

Parameters

[in]

net

Interface to release, or NULL.

Returns

Nothing.

Precondition

net, when non-NULL, was initialised by a backend constructor.

No dispatcher call on net is in progress.

Postcondition

Backend resources are released and net contains only zero bytes.

A NULL argument is a no-op.

Note

Not thread-safe: one interface per worker.

Since

0.1.0

Definition at line 120 of file mdl_net.c.

Referenced by internal_fetch_artifact(), internal_run_series_network(), mdl_app_run_discover(), and mdl_app_run_page().

mdl_net_get_body()

ra8_err_t mdl_net_get_body	(	mdl_net_iface_t *	net,
		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 its body through a caller-owned sink.

Validates the handle and arguments, then dispatches to the backend's get_body method after resetting sink. The backend enforces the session size cap and reports short writes or sink faults without owning storage. When resp is non-NULL it receives the finished transfer's HTTP status and raw Retry-After header so the governor can back off on a throttle.

Parameters

[in]	net	Network interface.
[in]	url	Absolute http/https URL.
[in]	req	Session parameters (must be non-NULL).
[in,out]	sink	Caller-owned reset/write body sink.
[out]	out_len	Bytes written. May be NULL.
[out]	resp	Response metadata (status + Retry-After), or NULL to skip.

Returns

An ra8_err_t transfer result.

Return values

k_ra8_ok	Body accepted, HTTP status < 400.
k_ra8_err_invalid_arg	NULL argument or refused scheme.
k_ra8_err_no_mem	Body exceeded the session size cap.
k_ra8_err_timeout	Request exceeded req->timeout_ms.
k_ra8_err_busy	HTTP 429 or 503 (throttled – back off).
k_ra8_err_not_found	HTTP 404 or another 4xx (skip this resource).
k_ra8_fail	Transport error, HTTP 5xx, or sink failure.

Precondition

net, when non-NULL, holds a fully populated vtable.

req, sink, and all sink callbacks/state are non-NULL.

Postcondition

The sink owns cleanup of bytes accepted before any failure.

*out_len, when out_len is non-NULL, is set only on k_ra8_ok.

*resp, when non-NULL, is filled with the observed status/header.

Note

Not thread-safe: one interface per worker.

Since

0.1.0

Definition at line 97 of file mdl_net.c.

References mdl_net_body_sink_t::ctx, internal_resp_reset(), k_ra8_err_invalid_arg, k_ra8_ok, mdl_net_body_sink_t::reset, and mdl_net_body_sink_t::write.

Referenced by internal_download_page_image(), internal_fetch_artifact(), and internal_mdl_fetch_governed_get_body().

mdl_net_get_buf()

ra8_err_t mdl_net_get_buf	(	mdl_net_iface_t *	net,
		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).

Validates the handle and arguments, then dispatches to the backend's get_buf method. The backend enforces the scheme allowlist and any security policy before contacting the network. When resp is non-NULL it receives the finished transfer's HTTP status and raw Retry-After header, letting the caller tell an absent page from a throttle from a server error – the distinction the robots.txt convention and the politeness governor both need.

Parameters

[in]	net	Network interface.
[in]	url	Absolute http/https URL.
[in]	req	Session parameters (must be non-NULL).
[out]	buf	Destination buffer.
[in]	cap	Capacity of buf in bytes (a trailing NUL is written when it fits, so pass cap >= body + 1 to guarantee a C string).
[out]	out_len	Bytes written (excluding any NUL). May be NULL.
[out]	resp	Response metadata (status + Retry-After), or NULL to skip.

Returns

An ra8_err_t transfer result.

Return values

k_ra8_ok	Body fetched, HTTP status < 400.
k_ra8_err_invalid_arg	NULL argument, cap == 0, or refused scheme.
k_ra8_err_no_mem	Body exceeded cap.
k_ra8_err_timeout	Request exceeded req->timeout_ms.
k_ra8_err_busy	HTTP 429 or 503 (throttled – back off).
k_ra8_err_not_found	HTTP 404 or another 4xx (skip this resource).
k_ra8_fail	Transport error or HTTP 5xx (server error).

Precondition

net, when non-NULL, holds a fully populated vtable.

req, buf are non-NULL and cap > 0 for a fetch to be attempted.

Postcondition

On any error the buffer contents are unspecified.

*out_len, when out_len is non-NULL, is set only on k_ra8_ok.

*resp, when non-NULL, is filled with the observed status/header.

Note

Not thread-safe: one interface per worker.

Since

0.1.0

Definition at line 78 of file mdl_net.c.

References internal_resp_reset(), and k_ra8_err_invalid_arg.

Referenced by internal_discover_fetch(), internal_extract_page_images(), internal_prepare_cache_fetch(), internal_session_fetch(), and priv_mdl_fetch_cache_get_buf().

mdl_net_provider_open()

ra8_err_t mdl_net_provider_open ( const mdl_net_provider_t * provider, const mdl_net_policy_t * policy, mdl_net_iface_t * out_net )

nodiscard

Open a transport through an injected provider.

The dispatcher half of the mdl_net_provider_t seam, matching the vtable dispatchers above: callers never invoke open directly, so the argument validation lives in one place and is testable with no backend at all. The output interface is cleared before anything else, so a rejected call leaves the caller a handle that mdl_net_destroy accepts.

Parameters

[in]	provider	Injected factory, or NULL.
[in]	policy	Session security policy for the new interface.
[out]	out_net	Caller-owned interface populated on success.

Returns

Canonical initialisation status.

Return values

k_ra8_ok	out_net owns a ready backend interface.
k_ra8_err_invalid_arg	A required object was NULL or unusable.
other	The backend factory's own failure.

Precondition

out_net addresses writable interface storage.

Credential bytes referenced by policy outlive the interface.

Postcondition

out_net contains only zero bytes on every failure path.

Success transfers no ownership of provider or policy.

Note

Not thread-safe: one interface per worker.

Since

0.1.0

Definition at line 64 of file mdl_net.c.

References k_ra8_err_invalid_arg.

Referenced by internal_fetch_artifact(), internal_run_series_network(), mdl_app_run_discover(), and mdl_app_run_page().

priv_mdl_net_classify_http()

ra8_err_t priv_mdl_net_classify_http

(

long

status

)

Classify one observed HTTP response status.

Applies the downloader's shared throttle, server-error, and client-error rules after a concrete backend completes its transport.

Parameters

[in]

status

Finished HTTP status in the inclusive range 100..599.

Returns

Canonical downloader result for the response status.

Return values

k_ra8_err_busy	Status 429 or 503 requires governor backoff.
k_ra8_fail	Any other status at or above 500.
k_ra8_err_not_found	Any other status at or above 400.
k_ra8_ok	Status below 400.

Precondition

status was obtained from a syntactically valid HTTP response.

Transport, capacity, and sink failures were handled before this call.

Postcondition

The status is classified without mutating caller or backend state.

Equal statuses always produce equal canonical results.

Note

This is private policy shared by curl and C6link backends.

Since

0.1.0

Definition at line 31 of file mdl_net.c.

References k_mdl_http_client_error, k_mdl_http_server_error, k_mdl_http_too_many, k_mdl_http_unavailable, k_ra8_err_busy, k_ra8_err_not_found, k_ra8_fail, k_ra8_ok, and RA8_PRIV.

Referenced by internal_c6_get(), and priv_mdl_net_curl_classify().