Streaming HTTP(S) GET seam (a real function-pointer vtable) for the host manga downloader (v0). More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for mdl_net.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	mdl_net_req_t
	Per-request session parameters. More...
struct	mdl_net_bytes_t
	Read-only caller-owned byte view retained by a network backend. More...
struct	mdl_net_policy_t
	Session-wide security policy for the network backend. More...
struct	mdl_net_resp_t
	Per-transfer response metadata surfaced to the politeness governor. More...
struct	mdl_net_body_sink_t
	Caller-owned lifecycle and write seam for one response body. More...
struct	mdl_net_vtable_t
	Method table one network backend registers (Dependency Inversion). More...
struct	mdl_net_iface
struct	mdl_net_provider

Typedefs
typedef ra8_err_t(*	mdl_net_body_reset_fn) (void *ctx)
	Reset one caller-owned response-body sink before a transfer attempt.
typedef ra8_err_t(*	mdl_net_body_write_fn) (void ctx, const uint8_t bytes, uint32_t length, uint32_t *out_written)
	Consume one bounded response-body chunk.
typedef struct mdl_net_iface	mdl_net_iface_t
typedef struct mdl_net_provider	mdl_net_provider_t

Enumerations
enum	mdl_net_resp_size_t : uint16_t { k_mdl_retry_after_max = 64U , k_mdl_etag_max = 128U , k_mdl_last_mod_max = 64U , k_mdl_content_type_max = 128U }
	Captured-response-field buffer sizes. More...

Functions
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.
void	mdl_net_destroy (mdl_net_iface_t *net)
	Deinitialise a caller-owned network interface.
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.

Detailed Description

Streaming HTTP(S) GET seam (a real function-pointer vtable) for the host manga downloader (v0).

Dependency-inversion seam for buffered metadata requests and the current host-path file sink. URL extraction, politeness, and robots gating are backend-neutral. Response bodies are delivered through caller-owned bounded sinks, so neither this interface nor a backend knows whether bytes ultimately reach POSIX, RAM, FAT, VFS, or another device filesystem. The host backend is libcurl (mdl_net_curl.c, created through mdl_net_curl.h).

The interface is a genuine vtable, not a link-time name: mdl_net_iface_t is a { vtable, ctx } pair, and callers reach a backend only through the dispatchers below (mdl_net_get_buf, mdl_net_get_body, ::mdl_net_last_status, mdl_net_destroy). This is the NASA Power of 10 Rule 9 deviation CLAUDE.md documents for exactly this purpose: swapping the future NetX/Mbed backend, or a scripted mock in the host unit tests, is a vtable substitution, not an edit at every call site or a relink.

The library reuses the firmware error contract (ra8_err_t), but that common status type alone does not make the path-based file sink portable.

See also: mdl_net_curl.h The concrete libcurl backend factory (composition root).

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

Definition in file mdl_net.h.

Typedef Documentation

◆ mdl_net_body_reset_fn

typedef ra8_err_t(* mdl_net_body_reset_fn) (void *ctx)

Reset one caller-owned response-body sink before a transfer attempt.

Parameters

[in,out] ctx Opaque sink state supplied in mdl_net_body_sink_t.

Returns: Canonical sink readiness or cleanup status.

Precondition: ctx points to live caller-owned sink state.

Postcondition: Success leaves the sink empty and ready for one response body.

Note: Called once per dispatched attempt, including an HTTP 304 attempt.

Since: 0.1.0

Definition at line 137 of file mdl_net.h.

◆ mdl_net_body_write_fn

typedef ra8_err_t(* mdl_net_body_write_fn) (void *ctx, const uint8_t *bytes, uint32_t length, uint32_t *out_written)

Consume one bounded response-body chunk.

Parameters

[in,out]	ctx	Opaque sink state supplied in mdl_net_body_sink_t.
[in]	bytes	Response bytes readable for `length` bytes.
[in]	length	Chunk extent, at most UINT32_MAX.
[out]	out_written	Bytes durably accepted from this chunk.

Returns: Canonical sink status.

Precondition: ctx, bytes, and out_written are non-NULL for nonempty input.

Postcondition: Success reports progress no greater than length.

Note: The network backend fails a short successful consume closed.

Since: 0.1.0

Definition at line 151 of file mdl_net.h.

◆ mdl_net_iface_t

typedef struct mdl_net_iface mdl_net_iface_t

◆ mdl_net_provider_t

typedef struct mdl_net_provider mdl_net_provider_t

Enumeration Type Documentation

◆ mdl_net_resp_size_t

enum mdl_net_resp_size_t : uint16_t

Captured-response-field buffer sizes.

Enumerator
k_mdl_retry_after_max	Raw Retry-After header value buffer bytes.
k_mdl_etag_max	Raw ETag header value buffer bytes.
k_mdl_last_mod_max	Raw Last-Modified header value buffer bytes.
k_mdl_content_type_max	Raw Content-Type header value buffer bytes.

Definition at line 92 of file mdl_net.h.

Function Documentation

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ mdl_net_body_reset_fn

◆ mdl_net_body_write_fn

◆ mdl_net_iface_t

◆ mdl_net_provider_t

Enumeration Type Documentation

◆ mdl_net_resp_size_t

Function Documentation

◆ mdl_net_destroy()

◆ mdl_net_get_body()

◆ mdl_net_get_buf()

◆ mdl_net_provider_open()