Archive packaging of downloaded page folders for the mdl CLI. More...

#include <stddef.h>
#include "mdl_export.h"
#include "mdl_fetch.h"

Include dependency graph for mdl_pack.h:

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

Functions
size_t	mdl_pack_one (mdl_storage_t storage, mdl_format_t format, const char series_dir, const char chap_id, mdl_export_workspace_t ws, ra8_io_stream_t output, ra8_io_stream_t diagnostic)
	Package one downloaded chapter folder into `format`.
size_t	mdl_pack_one_meta (mdl_storage_t storage, mdl_format_t format, const char series_dir, const char chap_id, const mdl_export_meta_t meta, mdl_export_workspace_t ws, ra8_io_stream_t output, ra8_io_stream_t *diagnostic)
	Package one downloaded chapter folder into `format` with rich metadata.
size_t	mdl_pack_combined (mdl_storage_t storage, mdl_format_t format, bool allow_incomplete, const char series_dir, const char combined_rel, const mdl_fetch_stats_t stats, mdl_export_workspace_t ws, ra8_io_stream_t output, ra8_io_stream_t *diagnostic)
	Package a combined page directory when completion policy permits.
size_t	mdl_pack_combined_meta (mdl_storage_t storage, mdl_format_t format, bool allow_incomplete, const char series_dir, const char combined_rel, const mdl_fetch_stats_t stats, const mdl_export_meta_t meta, mdl_export_workspace_t ws, ra8_io_stream_t output, ra8_io_stream_t diagnostic)
	Package a combined page folder into `format` with rich metadata.

Detailed Description

Archive packaging of downloaded page folders for the mdl CLI.

The download loop only puts verified page bytes on disk; turning a chapter or a combined page folder into a reader-openable container (or per-page JOF siblings) is this module's job. It is kept separate from the run orchestration so the "when do we package" policy – in particular the refusal to emit a complete-looking archive from an incomplete run – lives in one place, and so main.c stays a thin dispatcher. Every path is composed through the guarded mdl_path_join, so an untrusted leaf can never escape the series directory.

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

Definition in file mdl_pack.h.

Function Documentation

◆ mdl_pack_combined()

size_t mdl_pack_combined	(	mdl_storage_t *	storage,
		mdl_format_t	format,
		bool	allow_incomplete,
		const char *	series_dir,
		const char *	combined_rel,
		const mdl_fetch_stats_t *	stats,
		mdl_export_workspace_t *	ws,
		ra8_io_stream_t *	output,
		ra8_io_stream_t *	diagnostic )

Package a combined page directory when completion policy permits.

Delegates to the metadata-aware variant and auto-loads metadata. Incomplete runs are skipped unless explicitly allowed, in which case the output filename is marked INCOMPLETE.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output container format.
[in]	allow_incomplete	Whether a partial run may be packaged.
[in]	series_dir	Absolute, resolved series directory.
[in]	combined_rel	Sanitized combined-directory leaf.
[in]	stats	Completed run statistics controlling the policy decision.
[in,out]	ws	Caller-owned bounded exporter workspace.
[in,out]	output	Borrowed stream receiving successful package paths.
[in,out]	diagnostic	Borrowed stream receiving policy and failure diagnostics.

Returns: The number of packaging failures.

Return values

0U	Nothing required packaging, policy skipped it, or export succeeded.
1U	Path validation or export failed.

Precondition: All pointer arguments are non-NULL and NUL strings are terminated.; ws is exclusive to this call and owns writable arena bytes.

Postcondition: A disallowed incomplete run creates no combined archive.; An allowed incomplete export is visibly marked in its filename.

Note: Not thread-safe when callers share a workspace or output path.

Since: 0.1.0

Definition at line 428 of file mdl_pack.c.

References mdl_pack_combined_meta().

◆ mdl_pack_combined_meta()

size_t mdl_pack_combined_meta	(	mdl_storage_t *	storage,
		mdl_format_t	format,
		bool	allow_incomplete,
		const char *	series_dir,
		const char *	combined_rel,
		const mdl_fetch_stats_t *	stats,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws,
		ra8_io_stream_t *	output,
		ra8_io_stream_t *	diagnostic )

Package a combined page folder into format with rich metadata.

Applies the same incomplete-run policy as mdl_pack_combined but embeds caller-supplied metadata instead of auto-loading it.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output container format.
[in]	allow_incomplete	Whether a partial run may be packaged.
[in]	series_dir	Absolute, resolved series directory.
[in]	combined_rel	Sanitized combined-directory leaf.
[in]	stats	Completed run statistics controlling the policy decision.
[in]	meta	Metadata to embed, or NULL to auto-load it.
[in,out]	ws	Caller-owned bounded exporter workspace.
[in,out]	output	Borrowed stream receiving successful package paths.
[in,out]	diagnostic	Borrowed stream receiving policy and failure diagnostics.

Returns: The number of packaging failures.

Return values

0U	Nothing required packaging, policy skipped it, or export succeeded.
1U	Path validation or export failed.

Precondition: All pointer arguments are non-NULL except optional meta.; ws is exclusive to this call and owns writable arena bytes.

Postcondition: A disallowed incomplete run creates no combined archive.; Successful partial output carries the INCOMPLETE marker.

Note: Not thread-safe when callers share a workspace or output path.

Since: 0.1.0

Definition at line 386 of file mdl_pack.c.

References mdl_fetch_stats_t::chapters_completed, mdl_fetch_stats_t::chapters_failed, internal_pack_combined_dir(), k_ra8_ok, mdl_fetch_stats_t::pages_failed, priv_mdl_fetch_run_incomplete(), priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by internal_export_after(), and mdl_pack_combined().

◆ mdl_pack_one()

size_t mdl_pack_one	(	mdl_storage_t *	storage,
		mdl_format_t	format,
		const char *	series_dir,
		const char *	chap_id,
		mdl_export_workspace_t *	ws,
		ra8_io_stream_t *	output,
		ra8_io_stream_t *	diagnostic )

Package one downloaded chapter folder into format.

Composes <series_dir>/<chap_id> as the source page folder and writes the container beside it (or, for a directory-output format such as JOF, per-page siblings inside the folder). A path that would escape the series directory, or an export error, is reported and counted as one failure.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output container/format (never k_mdl_format_loose here).
[in]	series_dir	Absolute, resolved series directory.
[in]	chap_id	Sanitised chapter identifier (the page folder leaf).
[in,out]	ws	Caller-owned bounded exporter workspace.
[in,out]	output	Borrowed stream receiving successful package paths.
[in,out]	diagnostic	Borrowed stream receiving failure diagnostics.

Returns: The number of export failures (0 on success, 1 on any failure).

Return values

0U	The chapter was packaged.
1U	A path was rejected or the export failed (diagnostic printed).

Precondition: series_dir and chap_id are non-NULL and NUL-terminated.; series_dir names an existing directory.

Postcondition: On success a container (or JOF siblings) exists for the chapter.; On failure a diagnostic naming the chapter was written to stderr.

Note: Not thread-safe (shared cwd during path resolution).

Since: 0.1.0

Definition at line 225 of file mdl_pack.c.

References mdl_pack_one_meta().

◆ mdl_pack_one_meta()

size_t mdl_pack_one_meta	(	mdl_storage_t *	storage,
		mdl_format_t	format,
		const char *	series_dir,
		const char *	chap_id,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws,
		ra8_io_stream_t *	output,
		ra8_io_stream_t *	diagnostic )

Package one downloaded chapter folder into format with rich metadata.

Uses meta instead of auto-loading the chapter metadata files, while retaining guarded path composition and atomic export behavior.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output container format.
[in]	series_dir	Absolute, resolved series directory.
[in]	chap_id	Sanitized chapter directory leaf.
[in]	meta	Metadata to embed, or NULL to auto-load it.
[in,out]	ws	Caller-owned bounded exporter workspace.
[in,out]	output	Borrowed stream receiving successful package paths.
[in,out]	diagnostic	Borrowed stream receiving failure diagnostics.

Returns: The number of failures from this one packaging operation.

Return values

0U	Packaging succeeded.
1U	Path validation or export failed.

Precondition: series_dir and chap_id are non-NULL and NUL-terminated.; ws owns writable arena storage for the duration of the call.

Postcondition: Success creates the selected container or per-page artifacts.; Failure is counted once and diagnosed without replacing a good output.

Note: Not thread-safe when callers share a workspace or output path.

Since: 0.1.0

Definition at line 182 of file mdl_pack.c.

References internal_pack_dir_output(), internal_pack_metadata(), internal_pack_report_failure(), internal_pack_snprintf_fit(), internal_pack_text3(), k_pack_dir_bytes, k_pack_leaf_bytes, k_ra8_ok, mdl_export_chapter_meta_ws(), mdl_format_ext(), mdl_format_is_dir_output(), mdl_path_join(), and priv_mdl_stream_text().

Referenced by internal_export_fresh_separate(), and mdl_pack_one().

Functions

Detailed Description

Function Documentation

◆ mdl_pack_combined()

◆ mdl_pack_combined_meta()

◆ mdl_pack_one()

◆ mdl_pack_one_meta()