mdl_pack.c File Reference

Implementation of the downloaded-folder archive packaging. More...

#include "mdl_pack.h"
#include <stdint.h>
#include <stdio.h>
#include "mdl_export.h"
#include "mdl_fetch.h"
#include "mdl_fetch_internal.h"
#include "mdl_sanitize.h"
#include "mdl_stream_internal.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for mdl_pack.c:

Go to the source code of this file.

Enumerations
enum	mdl_pack_size_t : uint16_t {   k_pack_leaf_bytes = 256 ,   k_pack_dir_bytes = 1024 }
	Path buffer sizes for a composed archive leaf and directory. More...

Functions
static ra8_err_t	internal_pack_text3 (ra8_io_stream_t *stream, const char *first, const char *second, const char *third)
	Append three borrowed packaging fragments to one stream.
static bool	internal_pack_snprintf_fit (int n, size_t cap)
	Test whether an snprintf result fully fit its destination.
static mdl_export_meta_t	internal_pack_metadata (mdl_storage_t *storage, const mdl_export_meta_t *meta, const char *dir)
	Copy explicit metadata or load it from a combined directory.
static void	internal_pack_report_failure (ra8_io_stream_t *diagnostic, const char *chap_id, const char *ext, ra8_err_t rc)
	Report one chapter's export failure with its error code.
static size_t	internal_pack_dir_output (mdl_storage_t *storage, mdl_format_t format, const char *dir, const char *chap_id, const char *ext, const mdl_export_meta_t *meta, mdl_export_workspace_t *ws, ra8_io_stream_t *output, ra8_io_stream_t *diagnostic)
	Package one chapter into a directory-output format (e.g.
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_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.
static void	internal_pack_report_combine_failure (ra8_io_stream_t *diagnostic, ra8_err_t rc)
	Report a combine-export failure with its error code.
static size_t	internal_pack_combined_dir_output (mdl_storage_t *storage, mdl_format_t format, const char *dir, const char *ext, const char *mark, const mdl_export_meta_t *meta, mdl_export_workspace_t *ws, ra8_io_stream_t *output, ra8_io_stream_t *diagnostic)
	Combine-package one directory into a directory-output format.
static size_t	internal_pack_combined_dir (mdl_storage_t *storage, mdl_format_t format, const char *series_dir, const char *combined_rel, bool incomplete, const mdl_export_meta_t *meta, mdl_export_workspace_t *ws, ra8_io_stream_t *output, ra8_io_stream_t *diagnostic)
	Package a combined chapter folder into the selected format.
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.
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.

Detailed Description

Implementation of the downloaded-folder archive packaging.

Discovers prepared chapter directories, validates bounded paths, and delegates deterministic container creation to the exporter using the caller-owned workspace.

Copyright

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

Definition in file mdl_pack.c.

Enumeration Type Documentation

mdl_pack_size_t

enum mdl_pack_size_t : uint16_t

Path buffer sizes for a composed archive leaf and directory.

Enumerator
k_pack_leaf_bytes	Composed archive/dir leaf name.
k_pack_dir_bytes	Directory-path buffer.

Definition at line 24 of file mdl_pack.c.

Function Documentation

internal_pack_combined_dir()

size_t internal_pack_combined_dir ( mdl_storage_t * storage, mdl_format_t format, const char * series_dir, const char * combined_rel, bool incomplete, const mdl_export_meta_t * meta, mdl_export_workspace_t * ws, ra8_io_stream_t * output, ra8_io_stream_t * diagnostic )

static

Package a combined chapter folder into the selected format.

Composes guarded input/output paths, auto-loads metadata when needed, marks incomplete filenames, and handles directory-output formats without claiming that a container file was created.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output format to write.
[in]	series_dir	Absolute series directory.
[in]	combined_rel	Sanitized combined-directory leaf.
[in]	incomplete	Whether the output filename must be marked incomplete.
[in]	meta	Metadata to embed, or NULL to auto-load it.
[in,out]	ws	Exclusive caller-owned exporter workspace.
[in,out]	output	Borrowed stream receiving the successful output path.
[in,out]	diagnostic	Borrowed stream receiving policy and failure diagnostics.

Returns

Count of failures from this operation.

Return values

0U	Packaging succeeded.
1U	A path was rejected or export failed.

Precondition

String arguments are non-NULL, NUL-terminated, and stable.

ws owns writable arena storage for the call.

Postcondition

Success leaves output matching format and incomplete.

Failure is diagnosed and never counted more than once.

Note

Not thread-safe for a shared workspace or output directory.

Since

0.1.0

Definition at line 333 of file mdl_pack.c.

References internal_pack_combined_dir_output(), internal_pack_metadata(), internal_pack_report_combine_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(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by mdl_pack_combined_meta().

internal_pack_combined_dir_output()

size_t internal_pack_combined_dir_output ( mdl_storage_t * storage, mdl_format_t format, const char * dir, const char * ext, const char * mark, const mdl_export_meta_t * meta, mdl_export_workspace_t * ws, ra8_io_stream_t * output, ra8_io_stream_t * diagnostic )

static

Combine-package one directory into a directory-output format.

Directory-output formats write per-page siblings directly into the combined directory rather than one container file, so success is reported against that directory rather than a container name that was never created.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output format to write; must be a directory-output format.
[in]	dir	Combined directory, used as both source and destination.
[in]	ext	Format's canonical extension, for diagnostics.
[in]	mark	" (INCOMPLETE)" or an empty string, for diagnostics.
[in]	meta	Metadata to embed.
[in,out]	ws	Exclusive caller-owned exporter workspace.
[in,out]	output	Borrowed stream receiving the successful output path.
[in,out]	diagnostic	Borrowed stream receiving failure diagnostics.

Returns

Count of failures from this operation.

Return values

0U	Packaging succeeded.
1U	Export or diagnostic reporting failed.

Precondition

format is a directory-output format.

String arguments are non-NULL, NUL-terminated, and stable.

Postcondition

Success leaves per-page siblings under dir.

Failure is diagnosed and never counted more than once.

Note

Not thread-safe for a shared workspace or output directory.

Since

Version 0.1.0

Definition at line 286 of file mdl_pack.c.

References internal_pack_report_combine_failure(), internal_pack_text3(), k_ra8_ok, mdl_export_chapter_meta_ws(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_pack_combined_dir().

internal_pack_dir_output()

size_t internal_pack_dir_output ( mdl_storage_t * storage, mdl_format_t format, const char * dir, const char * chap_id, const char * ext, const mdl_export_meta_t * meta, mdl_export_workspace_t * ws, ra8_io_stream_t * output, ra8_io_stream_t * diagnostic )

static

Package one chapter into a directory-output format (e.g.

JOF).

Directory-output formats write per-page siblings directly into the chapter directory rather than one container file, so success is reported against that directory rather than a container name that was never created.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	format	Output format to write; must be a directory-output format.
[in]	dir	Chapter directory, used as both source and destination.
[in]	chap_id	Chapter identifier, for diagnostics.
[in]	ext	Format's canonical extension, for diagnostics.
[in]	meta	Metadata to embed.
[in,out]	ws	Exclusive caller-owned exporter workspace.
[in,out]	output	Borrowed stream receiving the successful output path.
[in,out]	diagnostic	Borrowed stream receiving failure diagnostics.

Returns

Count of failures from this operation.

Return values

0U	Packaging succeeded.
1U	Export or diagnostic reporting failed.

Precondition

format is a directory-output format.

String arguments are non-NULL, NUL-terminated, and stable.

Postcondition

Success leaves per-page siblings under dir.

Failure is diagnosed and never counted more than once.

Note

Not thread-safe for a shared workspace or output directory.

Since

Version 0.1.0

Definition at line 159 of file mdl_pack.c.

References internal_pack_report_failure(), internal_pack_text3(), k_ra8_ok, mdl_export_chapter_meta_ws(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by mdl_pack_one_meta().

internal_pack_metadata()

mdl_export_meta_t internal_pack_metadata ( mdl_storage_t * storage, const mdl_export_meta_t * meta, const char * dir )

static

Copy explicit metadata or load it from a combined directory.

Uses caller exporter workspace and injected filesystem and stream objects. Artifacts publish only through the selected bounded exporter.

Parameters

[in,out]	storage	Injected storage interface.
[in]	meta	Validated artifact metadata.
[in]	dir	Directory path or handle for the operation.

Returns

Selected metadata value, using on-disk defaults when meta is null.

Return values

metadata

Explicit metadata copy or bounded on-disk/default value.

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 93 of file mdl_pack.c.

References mdl_meta_load_dir().

Referenced by internal_pack_combined_dir(), and mdl_pack_one_meta().

internal_pack_report_combine_failure()

void internal_pack_report_combine_failure ( ra8_io_stream_t * diagnostic, ra8_err_t rc )

static

Report a combine-export failure with its error code.

Builds " combine export FAILED (err 0x<rc>)\n" on diagnostic, threading the running stream status through every fragment so a mid-message write failure is never masked.

Parameters

[in,out]	diagnostic	Borrowed stream receiving the failure diagnostic.
[in]	rc	The failure code being reported.

Returns

Nothing; the caller reports the packaging failure regardless.

Precondition

diagnostic is non-NULL.

rc is the non-success value the failed combine export returned.

Postcondition

One diagnostic line was appended to diagnostic, or the stream's existing error was preserved.

No packaging state or failure counter is touched; the caller counts.

Note

Thread safety follows ownership of the supplied stream.

Since

Version 0.1.0

Definition at line 252 of file mdl_pack.c.

References k_ra8_ok, priv_mdl_stream_hex(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_pack_combined_dir(), and internal_pack_combined_dir_output().

internal_pack_report_failure()

void internal_pack_report_failure ( ra8_io_stream_t * diagnostic, const char * chap_id, const char * ext, ra8_err_t rc )

static

Report one chapter's export failure with its error code.

Builds " export <chap_id>.<ext> FAILED (err 0x<rc>)\n" on diagnostic, threading the running stream status through every fragment so a mid-message write failure is never masked.

Parameters

[in,out]	diagnostic	Borrowed stream receiving the failure diagnostic.
[in]	chap_id	Chapter identifier.
[in]	ext	Format's canonical extension.
[in]	rc	The failure code being reported.

Returns

Nothing; the caller reports the packaging failure regardless.

Precondition

diagnostic, chap_id, and ext are non-NULL.

rc is the non-success value the failed chapter export returned.

Postcondition

One diagnostic line was appended to diagnostic, or the stream's existing error was preserved.

No packaging state or failure counter is touched; the caller counts.

Note

Thread safety follows ownership of the supplied stream.

Since

Version 0.1.0

Definition at line 122 of file mdl_pack.c.

References internal_pack_text3(), priv_mdl_stream_hex(), priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_pack_dir_output(), and mdl_pack_one_meta().

internal_pack_snprintf_fit()

bool internal_pack_snprintf_fit ( int n, size_t cap )

static

Test whether an snprintf result fully fit its destination.

Treats negative encoding errors and the terminating-NUL boundary as failures so path construction never accepts truncated output.

Parameters

[in]	n	Return value produced by snprintf.
[in]	cap	Destination buffer capacity passed to snprintf.

Returns

Whether the complete formatted string fit.

Return values

true	n is non-negative and strictly smaller than cap.
false	Formatting failed or required at least cap bytes.

Precondition

cap is the exact capacity used by the matching snprintf call.

n has not been altered after that call.

Postcondition

No state is modified.

The result can safely gate subsequent path use.

Note

Thread-safe: this is a pure arithmetic predicate.

Since

0.1.0

Definition at line 72 of file mdl_pack.c.

References RA8_INTERNAL.

Referenced by internal_pack_combined_dir(), and mdl_pack_one_meta().

internal_pack_text3()

ra8_err_t internal_pack_text3 ( ra8_io_stream_t * stream, const char * first, const char * second, const char * third )

static

Append three borrowed packaging fragments to one stream.

Uses caller exporter workspace and injected filesystem and stream objects. Artifacts publish only through the selected bounded exporter.

Parameters

[in,out]	stream	Destination stream state.
[in]	first	First text fragment.
[in]	second	Second text fragment.
[in]	third	Third text fragment.

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 46 of file mdl_pack.c.

References k_ra8_ok, priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_pack_combined_dir(), internal_pack_combined_dir_output(), internal_pack_dir_output(), internal_pack_report_failure(), and mdl_pack_one_meta().

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