mdl_report.h File Reference

Human-facing progress and failure reporting for the mdl CLI. More...

#include "mdl_fetch.h"

Include dependency graph for mdl_report.h:

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

Go to the source code of this file.

Functions
ra8_err_t	mdl_report_progress (void *ctx, const mdl_fetch_progress_t *ev)
	Per-page progress sink: print one redirect-safe line per page.
ra8_err_t	mdl_report_progress_bar (void *ctx, const mdl_fetch_progress_t *ev)
	Per-page progress bar sink: render an in-place terminal progress bar.
ra8_err_t	mdl_report_failures (ra8_io_stream_t *diagnostic, const mdl_fetch_faillog_t *log)
	End-of-run summary: list every failure with its URL and reason.

Detailed Description

Human-facing progress and failure reporting for the mdl CLI.

The download loop (mdl_fetch) is deliberately silent and testable: it emits progress through an injected mdl_progress_fn and records failures into a mdl_fetch_faillog_t, never printing on its own. This module is the concrete presenter the CLI wires in – a redirect-safe per-page progress line and an end-of-run summary that names every lost page with a human-readable reason, so a long run is legible live and its failures survive the scrollback. Kept out of main.c so the entry point stays a thin dispatcher.

Copyright

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

Definition in file mdl_report.h.

Function Documentation

mdl_report_failures()

ra8_err_t mdl_report_failures	(	ra8_io_stream_t *	diagnostic,
		const mdl_fetch_faillog_t *	log )

End-of-run summary: list every failure with its URL and reason.

Prints one line per recorded failure (URL plus a human-readable reason derived from the classified error and HTTP status), preceded by the total count, so the information survives after the per-page diagnostics have scrolled away. A run with no failures prints nothing.

Parameters

[in,out]	diagnostic	Borrowed stream receiving the failure summary.
[in]	log	The run's failure log (never NULL).

Returns

Stream output status.

Return values

k_ra8_ok	No failures existed or the complete summary was accepted.
other	The diagnostic stream rejected a fragment.

Precondition

log is non-NULL and was cleared before the run it summarises.

diagnostic is bound when log contains failures.

Postcondition

Nothing is written when log->total == 0.

No state is modified.

Note

Thread safety follows the injected stream.

See also

mdl_fetch_faillog_t

Since

0.1.0

Definition at line 214 of file mdl_report.c.

References k_mdl_reason_max, k_ra8_ok, priv_mdl_fetch_reason(), priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by internal_run_prepared().

mdl_report_progress()

ra8_err_t mdl_report_progress	(	void *	ctx,
		const mdl_fetch_progress_t *	ev )

Per-page progress sink: print one redirect-safe line per page.

Signature-compatible with mdl_progress_fn so it can be wired straight into mdl_fetch_ctx_t::progress_fn. Prints the run/chapter/page position and, for a transferred page, its size and rate; a reused page is marked as such. Uses no terminal control sequences, so the output stays readable when redirected to a file or a pipe.

Parameters

[in]	ctx	Unused progress context (kept for the mdl_progress_fn ABI).
[in]	ev	The just-completed page's progress event, or NULL (no-op).

Returns

Stream output status.

Return values

k_ra8_ok	The event was absent or its complete line was accepted.
other	The output stream rejected a fragment.

Precondition

ev, when non-NULL, was populated by mdl_fetch_run.

ctx points to a bound ra8_io_stream_t when ev is non-NULL.

Postcondition

One line is written to the injected stream for a non-NULL ev.

No state is modified.

Note

Thread safety follows the injected stream.

See also

mdl_progress_fn

Since

0.1.0

Definition at line 119 of file mdl_report.c.

References mdl_fetch_progress_t::elapsed_ms, internal_fmt_rate(), internal_fmt_size(), internal_report_position(), k_human_bytes, k_ra8_ok, mdl_fetch_progress_t::page_bytes, priv_mdl_stream_text(), and mdl_fetch_progress_t::reused.

Referenced by internal_make_ctx().

mdl_report_progress_bar()

ra8_err_t mdl_report_progress_bar	(	void *	ctx,
		const mdl_fetch_progress_t *	ev )

Per-page progress bar sink: render an in-place terminal progress bar.

Rewrites one fixed-width bar with carriage returns and appends a newline when the final page completes. Reused pages omit rate data.

Parameters

[in]	ctx	Unused progress context (kept for the mdl_progress_fn ABI).
[in]	ev	The just-completed page's progress event, or NULL (no-op).

Returns

Stream output status.

Return values

k_ra8_ok	The event was absent or its complete update was accepted.
other	The output stream rejected a fragment or flush.

Precondition

ev, when non-NULL, contains a coherent page index and total.

ctx points to a bound ra8_io_stream_t when ev is non-NULL.

Postcondition

A non-NULL event updates the injected progress stream.

A terminal event leaves that stream positioned on a new line.

Note

Thread safety follows the injected stream.

Since

0.1.0

Definition at line 169 of file mdl_report.c.

References mdl_fetch_progress_t::elapsed_ms, internal_fmt_rate(), internal_fmt_size(), internal_percent_pad_width(), internal_report_position(), k_human_bytes, k_percent_scale, k_progress_bar_width, k_ra8_ok, mdl_fetch_progress_t::page_bytes, mdl_fetch_progress_t::page_index, mdl_fetch_progress_t::page_total, priv_mdl_stream_flush(), priv_mdl_stream_repeat(), priv_mdl_stream_text(), priv_mdl_stream_u64(), and mdl_fetch_progress_t::reused.

Referenced by internal_make_ctx().