Implementation of the mdl progress + failure presenter. More...

#include "mdl_report.h"
#include <stdint.h>
#include <stdio.h>
#include "mdl_fetch.h"
#include "mdl_fetch_internal.h"
#include "mdl_stream_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_report.c:

Enumerations
enum	mdl_report_scale_t : uint32_t { k_bytes_per_kib = 1024U , k_bytes_per_mib = 1024U * 1024U , k_ms_per_sec = 1000U , k_human_bytes = 32U , k_progress_bar_width = 20U , k_percent_scale = 100U , k_percent_two_digits = 10U }
	Human-readable size/rate scaling and buffer sizes. More...

Functions
static void	internal_fmt_size (uint64_t bytes, char *buf, size_t cap)
	Format a byte count as a compact human-readable string.
static void	internal_fmt_rate (uint64_t bytes, uint32_t elapsed_ms, char *buf, size_t cap)
	Format a byte transfer rate as a compact string.
static ra8_err_t	internal_report_position (ra8_err_t error, ra8_io_stream_t output, const mdl_fetch_progress_t ev)
	Append the common chapter and page coordinates for one event.
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.
static uint32_t	internal_percent_pad_width (uint32_t pct)
	Width of the space padding before a whole-percent value.
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

Implementation of the mdl progress + failure presenter.

Formats bounded status text and translates downloader progress and terminal results into the configured command-line presentation.

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

Definition in file mdl_report.c.

Enumeration Type Documentation

◆ mdl_report_scale_t

enum mdl_report_scale_t : uint32_t

Human-readable size/rate scaling and buffer sizes.

Enumerator
k_bytes_per_kib	Bytes in a kibibyte.
k_bytes_per_mib	Bytes in a mebibyte.
k_ms_per_sec	Milliseconds per second (rate).
k_human_bytes	Size/rate string buffer bytes.
k_progress_bar_width	Rendered progress-bar cells.
k_percent_scale	Whole-percent conversion scale.
k_percent_two_digits	First two-digit percentage.

Definition at line 20 of file mdl_report.c.

Function Documentation

◆ internal_fmt_rate()

void internal_fmt_rate	(	uint64_t	bytes,
		uint32_t	elapsed_ms,
		char *	buf,
		size_t	cap )

static

Format a byte transfer rate as a compact string.

Converts elapsed milliseconds to bytes per second, scales to KB/s or MB/s, and emits a placeholder when elapsed time is zero.

Parameters

[in]	bytes	Bytes transferred during the interval.
[in]	elapsed_ms	Interval duration in milliseconds.
[out]	buf	Destination text buffer.
[in]	cap	Writable capacity of `buf`.

Precondition: buf points to cap writable bytes.; cap is large enough for the documented compact representation.

Postcondition: buf contains a NUL-terminated rate or placeholder string.; No state other than buf is modified.

Note: Thread-safe across distinct destination buffers.

Since: 0.1.0

Definition at line 74 of file mdl_report.c.

References k_bytes_per_kib, k_bytes_per_mib, and k_ms_per_sec.

Referenced by mdl_report_progress(), and mdl_report_progress_bar().

◆ internal_fmt_size()

void internal_fmt_size	(	uint64_t	bytes,
		char *	buf,
		size_t	cap )

static

Format a byte count as a compact human-readable string.

Chooses bytes, KiB-style KB, or MiB-style MB and emits one decimal place for scaled values into the caller's bounded buffer.

Parameters

[in]	bytes	Byte count to render.
[out]	buf	Destination text buffer.
[in]	cap	Writable capacity of `buf`.

Precondition: buf points to cap writable bytes.; cap is large enough for the documented compact representation.

Postcondition: buf contains a NUL-terminated size string.; No state other than buf is modified.

Note: Thread-safe across distinct destination buffers.

Since: 0.1.0

Definition at line 44 of file mdl_report.c.

References k_bytes_per_kib, k_bytes_per_mib, and RA8_INTERNAL.

Referenced by mdl_report_progress(), and mdl_report_progress_bar().

◆ internal_percent_pad_width()

uint32_t internal_percent_pad_width ( uint32_t pct )

static

Width of the space padding before a whole-percent value.

Keeps the percent column right-aligned to three digits: two spaces before a one-digit value, one before a two-digit value, and none before the three-digit maximum.

Parameters

[in] pct Whole-percent value already clamped to [0, 100].

Returns: Number of leading padding spaces.

Return values

2	`pct` is a single digit.
1	`pct` is two digits.
0	`pct` is three digits.

Precondition: pct is at most k_percent_scale.; k_percent_two_digits is less than k_percent_scale.

Postcondition: No state is modified.; The returned width plus pct's digit count is always three.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 158 of file mdl_report.c.

References k_percent_scale, k_percent_two_digits, and RA8_INTERNAL.

Referenced by mdl_report_progress_bar().

◆ internal_report_position()

ra8_err_t internal_report_position	(	ra8_err_t	error,
		ra8_io_stream_t *	output,
		const mdl_fetch_progress_t *	ev )

static

Append the common chapter and page coordinates for one event.

Writes coordinates in stable field order through the injected stream. The first sink error is returned unchanged and prevents later fields.

Parameters

[in,out]	error	Error accumulator or error value.
[out]	output	Destination report stream.
[in]	ev	Structured report event.

Returns: Operation status.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Since: Version 0.1.0

Definition at line 105 of file mdl_report.c.

References mdl_fetch_progress_t::chapter_id, mdl_fetch_progress_t::chapter_index, mdl_fetch_progress_t::chapter_total, mdl_fetch_progress_t::page_index, mdl_fetch_progress_t::page_total, priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by mdl_report_progress(), and mdl_report_progress_bar().

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_report_scale_t

Function Documentation

◆ internal_fmt_rate()

◆ internal_fmt_size()

◆ internal_percent_pad_width()

◆ internal_report_position()

◆ mdl_report_failures()

◆ mdl_report_progress()

◆ mdl_report_progress_bar()