mdl_compose.c File Reference

The composition of THIS form: libcurl in, one parsed command out. More...

#include "mdl_compose_internal.h"
#include "mdl_net_curl.h"

Include dependency graph for mdl_compose.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_curl_open (void *ctx, const mdl_net_policy_t *policy, mdl_net_iface_t *out_net)
	Open one hardened libcurl interface over the form's backend storage.
const mdl_net_provider_t *	priv_mdl_compose_net_provider (void)
	The libcurl transport factory this form injects into every run.
mdl_series_run_t	priv_mdl_compose_build_run (const mdl_args_t *a, mdl_format_t format, const mdl_run_opts_t *opts, const mdl_nums_t *n)
	Translate validated argv state into one portable series-run value.
int	priv_mdl_compose_dispatch (const mdl_args_t *a, mdl_cli_mode_t mode, mdl_format_t format, const mdl_run_opts_t *opts, const mdl_nums_t *nums, const mdl_series_run_t *run)
	Route the one validated mode to its portable application entry point.

Variables
static mdl_net_curl_storage_t	s_curl_storage
	The one caller-owned libcurl backend context this form provides.
static const mdl_net_provider_t	s_curl_provider
	This form's injected transport factory, bound once at compile time.

Detailed Description

The composition of THIS form: libcurl in, one parsed command out.

Two translations and nothing else. The first binds the concrete libcurl backend into the abstract mdl_net_provider_t seam the application layer consumes, over storage this form owns. The second turns one validated mdl_args_t plus the mode mdl_cli_validate chose into a call on one ::mdl_app.h entry point. Keeping both here is what lets main.c stay process plumbing and the downloader stay free of a command line.

Copyright

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

Definition in file mdl_compose.c.

Function Documentation

internal_curl_open()

ra8_err_t internal_curl_open ( void * ctx, const mdl_net_policy_t * policy, mdl_net_iface_t * out_net )

static

Open one hardened libcurl interface over the form's backend storage.

The concrete half of the mdl_net_provider_t seam; the factory's private storage arrives as ctx so this function names no global.

Parameters

[in,out]	ctx	The provider's mdl_net_curl_storage_t.
[in]	policy	Session security policy to harden the handle with.
[out]	out_net	Interface populated on success.

Returns

Canonical backend initialisation status.

Return values

k_ra8_ok	out_net owns a hardened libcurl easy handle.
other	The libcurl backend rejected the policy or failed to init.

Precondition

ctx addresses this form's backend storage.

Credential bytes referenced by policy stay readable until destroy.

Postcondition

Failure leaves out_net and ctx holding only zero bytes.

Success transfers no ownership of ctx.

Note

Not thread-safe: one interface per worker.

Since

0.1.0

Definition at line 49 of file mdl_compose.c.

References mdl_net_curl_init().

priv_mdl_compose_build_run()

mdl_series_run_t priv_mdl_compose_build_run	(	const mdl_args_t *	a,
		mdl_format_t	format,
		const mdl_run_opts_t *	opts,
		const mdl_nums_t *	n )

Translate validated argv state into one portable series-run value.

Copies only validated selections, numeric bounds, output format and policy pointers, so the application layer sees values rather than the argv-shaped structs that produced them.

Parameters

[in]	a	Parsed and validated command-line options.
[in]	format	Validated output format.
[in]	opts	Validated run policy, including the injected transport.
[in]	n	Validated numeric command options.

Returns

The assembled run description.

Return values

mdl_series_run_t

A value borrowing the caller-owned argument storage.

Precondition

a, opts and n are non-NULL and were validated.

Referenced strings outlive every dispatched run function.

Postcondition

The returned value owns no newly allocated storage.

The input objects remain unchanged.

Note

Thread-safe for independent input objects.

Since

0.1.0

Definition at line 71 of file mdl_compose.c.

References mdl_args_t::cache_dir, mdl_args_t::cfg, mdl_nums_t::chapters, mdl_nums_t::from_num, mdl_nums_t::from_present, mdl_args_t::out, RA8_PRIV, mdl_nums_t::seed, mdl_args_t::separate, mdl_args_t::series, mdl_nums_t::timeout, and mdl_args_t::update.

Referenced by internal_main_run().

priv_mdl_compose_dispatch()

int priv_mdl_compose_dispatch	(	const mdl_args_t *	a,
		mdl_cli_mode_t	mode,
		mdl_format_t	format,
		const mdl_run_opts_t *	opts,
		const mdl_nums_t *	nums,
		const mdl_series_run_t *	run )

Route the one validated mode to its portable application entry point.

The whole of the argv-to-application translation: every case reads the fields that mode needs out of a and nums and calls one ::mdl_app.h entry point. The mode enum already encodes the selection strictly, so no case re-derives it from option precedence.

Parameters

[in]	a	Parsed and validated command-line options.
[in]	mode	The one mode mdl_cli_validate selected.
[in]	format	Validated output format.
[in]	opts	Validated run policy, including the injected transport.
[in]	nums	Validated numeric command options.
[in]	run	Prepared series-run template.

Returns

Process-style status from the selected mode.

Return values

0	The selected operation completed successfully.
1	The selected operation reported an execution failure.
2	The mode value was not one validation can produce.

Precondition

All pointer arguments are non-NULL.

mode was produced by mdl_cli_validate and a context is bound.

Postcondition

Exactly one mode entry point is invoked.

Non-selected mode entry points perform no work.

Note

Not thread-safe because the modes share one bound context.

Since

0.1.0

Definition at line 91 of file mdl_compose.c.

References mdl_args_t::attr, mdl_args_t::browse, mdl_args_t::cfg, mdl_args_t::init_site_url, k_mdl_cli_mode_artifact, k_mdl_cli_mode_browse, k_mdl_cli_mode_init_site, k_mdl_cli_mode_list, k_mdl_cli_mode_pack, k_mdl_cli_mode_page, k_mdl_cli_mode_remove, k_mdl_cli_mode_search, k_mdl_cli_mode_series, k_mdl_cli_mode_update_all, k_mdl_cli_mode_verify, mdl_nums_t::max_imgs, mdl_app_run_artifact(), mdl_app_run_discover(), mdl_app_run_init_site(), mdl_app_run_list(), mdl_app_run_pack(), mdl_app_run_page(), mdl_app_run_remove(), mdl_app_run_series(), mdl_app_run_update_all(), mdl_app_run_verify(), mdl_args_t::out, mdl_args_t::pack, mdl_args_t::page_url, mdl_args_t::pick, mdl_nums_t::pick, RA8_PRIV, mdl_args_t::remove_series, mdl_nums_t::seed, mdl_nums_t::timeout, and mdl_args_t::verify_dir.

Referenced by internal_main_run().

priv_mdl_compose_net_provider()

const mdl_net_provider_t * priv_mdl_compose_net_provider

(

void

)

The libcurl transport factory this form injects into every run.

Returns the one provider whose open wires mdl_net_curl_init over this form's own backend storage. A run mode receives it through mdl_run_opts_t and never names libcurl; another form returns a different provider from its own composition and the modes are unchanged.

Returns

The provider to publish in mdl_run_opts_t::net.

Return values

non-NULL

A process-lifetime provider valid for the whole run.

Precondition

The process is single-threaded with respect to network runs.

No interface previously opened from this provider is still live.

Postcondition

No caller-visible state is modified.

Successive calls return the same provider.

Note

Not thread-safe: one backend storage serves one serial run at a time.

Since

0.1.0

Definition at line 66 of file mdl_compose.c.

References RA8_PRIV, and s_curl_provider.

Referenced by main().

Variable Documentation

s_curl_provider

const mdl_net_provider_t s_curl_provider

static

Initial value:

= {.ctx  = &s_curl_storage,
   .open = internal_curl_open}

This form's injected transport factory, bound once at compile time.

Immutable, so the seam cannot be repointed at run time by anything other than a different composition root.

Note

Published through priv_mdl_compose_net_provider.

Warning

Do not name it from another translation unit.

Since

0.1.0

Definition at line 63 of file mdl_compose.c.

Referenced by priv_mdl_compose_net_provider().

s_curl_storage

mdl_net_curl_storage_t s_curl_storage

static

The one caller-owned libcurl backend context this form provides.

Static rather than per-call so the provider can hand the same bytes to every run without the application layer knowing a backend needs storage at all. One object is enough because runs are strictly serial: a mode destroys its interface before any other mode opens one, and discovery destroys its own before dispatching a series.

Note

Written only through internal_curl_open.

Warning

Never reuse it while an interface opened from it is still live.

Since

0.1.0

Definition at line 29 of file mdl_compose.c.