Factory for the concrete libcurl-backed mdl_net_iface_t backend. More...

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

Include dependency graph for mdl_net_curl.h:

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

Data Structures
struct	mdl_net_curl_storage
	Opaque, aligned, caller-owned storage for one host network backend. More...

Typedefs
typedef struct mdl_net_curl_storage	mdl_net_curl_storage_t

Enumerations
enum	mdl_net_curl_storage_size_t : size_t { k_mdl_net_curl_storage_bytes = 1024U }
	Bytes reserved by the caller for one libcurl backend context. More...

Functions
ra8_err_t	mdl_net_curl_init (mdl_net_iface_t net, mdl_net_curl_storage_t storage, const mdl_net_policy_t *policy)
	Initialise a libcurl-backed host network interface in caller storage.

Detailed Description

Factory for the concrete libcurl-backed mdl_net_iface_t backend.

This is the ONE header that names the libcurl backend, and only the composition root (main.c) includes it. Every other layer – extraction, politeness, robots gating, the download loop – includes only mdl_net.h and sees the abstract mdl_net_iface_t vtable, so the concrete backend can be swapped (for the future NetX/Mbed backend, or a scripted test fake) without touching those layers. Keeping the factory out of mdl_net.h is what lets that header stay backend-agnostic.

See also: mdl_net.h The abstract seam and its dispatchers.

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

Definition in file mdl_net_curl.h.

Typedef Documentation

◆ mdl_net_curl_storage_t

typedef struct mdl_net_curl_storage mdl_net_curl_storage_t

Enumeration Type Documentation

◆ mdl_net_curl_storage_size_t

enum mdl_net_curl_storage_size_t : size_t

Bytes reserved by the caller for one libcurl backend context.

Enumerator
k_mdl_net_curl_storage_bytes	Private backend storage capacity.

Definition at line 26 of file mdl_net_curl.h.

Function Documentation

◆ mdl_net_curl_init()

ra8_err_t mdl_net_curl_init	(	mdl_net_iface_t *	net,
		mdl_net_curl_storage_t *	storage,
		const mdl_net_policy_t *	policy )

nodiscard

Initialise a libcurl-backed host network interface in caller storage.

The returned handle wires the libcurl backend's method table to a private libcurl easy handle hardened per policy (scheme allowlist, SSRF and cross-host redirect refusal, TLS verification, size and time bounds). One easy handle is reused across requests so the connection pool and cookie jar persist (unlike the Kotlin per-request client). This is the Dependency Injection seam: production wires this factory; tests wire a fake with the same mdl_net_iface_t shape.

Parameters

[out]	net	Caller-owned interface populated on success.
[in,out]	storage	Caller-owned private storage retained until destroy.
[in]	policy	Session security policy, or NULL for the safe defaults.

Returns: Canonical initialisation status.

Return values

k_ra8_ok	A ready interface; release resources with mdl_net_destroy.
k_ra8_err_invalid_arg	A required object or credential byte view is invalid, or a cookie row is unsafe.
k_ra8_err_invalid_size	One cookie row exceeds the bounded importer.
k_ra8_err_not_supported	This libcurl/TLS build cannot consume a caller-owned CA blob.
k_ra8_fail	Global/easy init or option hardening failed.

Precondition: libcurl is available at link time.; policy, when non-NULL, describes the intended escape hatches.; Credential bytes referenced by policy remain readable until mdl_net_destroy because custom CA data is bound with CURL_BLOB_NOCOPY.

Postcondition: On success net owns a hardened libcurl easy handle while caller storage remains valid.; On failure net and storage contain only zero bytes.

Note: Not thread-safe: one interface per worker.

Since: 0.1.0

Definition at line 819 of file mdl_net_curl.c.

References mdl_curl_ctx_t::allow_cross_host, mdl_net_policy_t::allow_cross_host_redirect, mdl_curl_ctx_t::allow_private, mdl_net_policy_t::allow_private_hosts, mdl_net_curl_storage::bytes, mdl_curl_ctx_t::ca_pem, mdl_net_policy_t::ca_pem, mdl_curl_ctx_t::cookies, mdl_net_policy_t::cookies, mdl_curl_ctx_t::curl, internal_apply_behavior_opts(), internal_apply_security_opts(), k_ra8_err_invalid_arg, k_ra8_fail, k_ra8_ok, mdl_curl_ctx_t::max_bytes, mdl_net_policy_t::max_response_bytes, mdl_curl_ctx_t::proxy, mdl_net_policy_t::proxy, s_curl_vtable, mdl_curl_ctx_t::socks5, and mdl_net_policy_t::socks5.

Referenced by internal_curl_open().

Data Structures

Typedefs

Enumerations