mdl_app_direct.c File Reference

Direct artifact, page, pack, and run composition actions. More...

#include "mdl_app_internal.h"
#include "mdl_export_io_internal.h"
#include "mdl_fetch_body_internal.h"

Include dependency graph for mdl_app_direct.c:

Go to the source code of this file.

Data Structures
struct	mdl_direct_artifact_sink_t
	Transactional body sink for one directly downloaded artifact. More...

Functions
static ra8_err_t	internal_direct_text3 (ra8_io_stream_t *stream, const char *first, const char *second, const char *third)
	Append three borrowed direct-action fragments to one stream.
static void	internal_direct_latch (ra8_err_t error)
	Latch the first direct presenter failure for loop cancellation.
static ra8_err_t	internal_direct_pack_failure (const char *dir, const char *ext, ra8_err_t failure)
	Report one pack exporter failure with its exact hexadecimal status.
static ra8_err_t	internal_direct_artifact_reset (void *context)
	Abort a prior attempt and begin a fresh artifact transaction.
static ra8_err_t	internal_direct_artifact_write (void *context, const uint8_t *bytes, uint32_t length, uint32_t *out_written)
	Append one complete response chunk to the portable artifact stage.
static uint32_t	internal_max_u32 (uint32_t a, uint32_t b)
	Return the larger of two unsigned values.
static void	internal_remove_stale_page_variants (const char *out_dir, size_t page_no, const char *true_ext)
	Remove stale page files whose extensions differ from verified bytes.
static size_t	internal_publish_page_image (mdl_fetch_body_t *body, const char *out_dir, size_t idx)
	Validate and publish one staged page-mode image.
static size_t	internal_download_page_image (const char *url, const char *out_dir, uint32_t dmin, uint32_t dmax, uint32_t timeout, mdl_politeness_t *pol, size_t idx)
	Gate, space, and download one page-mode image.
static size_t	internal_download_page_images (const char *url, const char *out_dir, uint32_t max_imgs, uint64_t seed, uint32_t timeout, bool polite)
	Download the extracted page images into an output directory.
static bool	internal_prepare_output_dir (const char *out_dir, char *out_abs)
	Create and canonicalize one direct-action output directory.
static bool	internal_prepare_artifact_path (const char *out_dir, const char *leaf, char *final_path)
	Prepare the exact final path for one direct artifact.
static bool	internal_finish_artifact_fetch (mdl_direct_artifact_sink_t *state, ra8_err_t error, long status)
	Finalize or abort one direct artifact transfer.
static bool	internal_fetch_artifact (const char *url, const char *final_path, mdl_format_t format, uint32_t timeout, const mdl_run_opts_t *opts, size_t *got)
	Fetch one policy-approved artifact into an atomic holding path.
int	mdl_app_run_artifact (const char *url, const char *out_dir, uint32_t timeout, const mdl_run_opts_t *opts)
	Download, validate and atomically publish one direct artifact.
static bool	internal_extract_page_images (const char *url, const char *attr, uint32_t timeout)
	Fetch one page and populate the shared extracted-image list.
int	mdl_app_run_page (const char *url, const char *out_dir, const char *attr, uint32_t max_imgs, uint64_t seed, uint32_t timeout, const mdl_run_opts_t *opts)
	Download image resources from one direct page URL.
static int	internal_pack_directory_output (const char *dir, const char *ext, mdl_format_t format)
	Package a directory-output format and report its wildcard destination.
static int	internal_pack_file_output (const char *dir, const char *ext, mdl_format_t format)
	Package a file-output format beside its source directory.
int	mdl_app_run_pack (const char *dir, mdl_format_t format)
	Package an existing image directory without network access.

Detailed Description

Direct artifact, page, pack, and run composition actions.

Composes validated direct-download and offline-pack modes over the shared storage, network, governor, and exporter dependencies.

Copyright

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

Definition in file mdl_app_direct.c.

Function Documentation

internal_direct_artifact_reset()

ra8_err_t internal_direct_artifact_reset ( void * context )

static

Abort a prior attempt and begin a fresh artifact transaction.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Parameters

[in,out]

context

Caller-owned operation context.

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 107 of file mdl_app_direct.c.

References fw_fs_transaction_t::active, mdl_direct_artifact_sink_t::destination, mdl_direct_artifact_sink_t::format, k_ra8_err_invalid_arg, k_ra8_ok, mdl_direct_artifact_sink_t::output, priv_mdl_export_output_abort(), priv_mdl_export_output_begin(), RA8_INTERNAL, mdl_direct_artifact_sink_t::storage, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by internal_fetch_artifact().

internal_direct_artifact_write()

ra8_err_t internal_direct_artifact_write ( void * context, const uint8_t * bytes, uint32_t length, uint32_t * out_written )

static

Append one complete response chunk to the portable artifact stage.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Parameters

[in,out]	context	Caller-owned operation context.
[in]	bytes	Readable byte span.
[in]	length	Byte length of the supplied span.
[out]	out_written	Receives the committed byte count.

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 142 of file mdl_app_direct.c.

References k_ra8_err_invalid_arg, k_ra8_ok, mdl_direct_artifact_sink_t::output, priv_mdl_export_output_write(), and RA8_INTERNAL.

Referenced by internal_fetch_artifact().

internal_direct_latch()

void internal_direct_latch ( ra8_err_t error )

static

Latch the first direct presenter failure for loop cancellation.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Parameters

[in,out]

error

Error accumulator or error 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 59 of file mdl_app_direct.c.

References mdl_app_context_t::io_error, k_ra8_ok, priv_mdl_app_context(), and RA8_INTERNAL.

Referenced by internal_download_page_image(), internal_download_page_images(), internal_extract_page_images(), internal_fetch_artifact(), internal_finish_artifact_fetch(), internal_prepare_artifact_path(), internal_prepare_output_dir(), internal_publish_page_image(), internal_remove_stale_page_variants(), mdl_app_run_artifact(), and mdl_app_run_page().

internal_direct_pack_failure()

ra8_err_t internal_direct_pack_failure ( const char * dir, const char * ext, ra8_err_t failure )

static

Report one pack exporter failure with its exact hexadecimal status.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Parameters

[in]	dir	Directory path or handle for the operation.
[in]	ext	Filename extension without implicit allocation.
[out]	failure	Receives the originating failure.

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 83 of file mdl_app_direct.c.

References mdl_app_context_t::diagnostic, internal_direct_text3(), priv_mdl_app_context(), priv_mdl_stream_hex(), and priv_mdl_stream_text().

Referenced by internal_pack_directory_output(), and internal_pack_file_output().

internal_direct_text3()

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

static

Append three borrowed direct-action fragments to one stream.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

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 38 of file mdl_app_direct.c.

References k_ra8_ok, priv_mdl_stream_text(), and RA8_INTERNAL.

Referenced by internal_direct_pack_failure(), internal_extract_page_images(), internal_finish_artifact_fetch(), internal_pack_directory_output(), internal_pack_file_output(), internal_prepare_artifact_path(), internal_prepare_output_dir(), internal_remove_stale_page_variants(), mdl_app_run_artifact(), and mdl_app_run_pack().

internal_download_page_image()

size_t internal_download_page_image ( const char * url, const char * out_dir, uint32_t dmin, uint32_t dmax, uint32_t timeout, mdl_politeness_t * pol, size_t idx )

static

Gate, space, and download one page-mode image.

Enforces session policy and crawl delay, downloads to a holding leaf, requires a supported byte signature, then durably publishes page_NNNN.<true-ext>. URL suffixes and Content-Type cannot override the bytes, and no partial/unknown file is presented as an image.

Parameters

[in]	url	Referrer page URL.
[in]	out_dir	Output directory.
[in]	dmin	Minimum request delay in milliseconds.
[in]	dmax	Maximum request delay in milliseconds.
[in]	timeout	Per-request timeout in milliseconds.
[in,out]	pol	Initialized politeness state.
[in]	idx	Index into priv_mdl_app_context()->images.

Returns

Failure contribution for the page tally.

Return values

0	The image downloaded successfully.
1	Policy refusal or network/file failure occurred.

Precondition

url, out_dir, and pol are non-NULL.

idx is smaller than priv_mdl_app_context()->images.count.

Postcondition

Success leaves one image file in out_dir.

Failure is reported and contributes exactly one failure.

Note

Not thread-safe because it reads the shared session/image table.

Since

0.1.0

Definition at line 328 of file mdl_app_direct.c.

References internal_direct_latch(), internal_max_u32(), internal_publish_page_image(), k_file_path_bytes, k_leaf_name_bytes, k_mdl_reason_max, k_ra8_ok, mdl_net_get_body(), mdl_path_join(), mdl_politeness_wait(), mdl_session_url_allowed(), priv_mdl_app_context(), priv_mdl_fetch_body_abort(), priv_mdl_fetch_body_init_image(), priv_mdl_fetch_body_sink(), priv_mdl_fetch_reason(), priv_mdl_stream_text(), priv_mdl_stream_u64(), RA8_INTERNAL, mdl_app_context_t::session, mdl_net_resp_t::status, and mdl_session_t::user_agent.

Referenced by internal_download_page_images().

internal_download_page_images()

size_t internal_download_page_images ( const char * url, const char * out_dir, uint32_t max_imgs, uint64_t seed, uint32_t timeout, bool polite )

static

Download the extracted page images into an output directory.

Initializes deterministic delay state, applies the configured page limit, downloads each row, and prints the final tally.

Parameters

[in]	url	Referrer page URL.
[in]	out_dir	Output directory.
[in]	max_imgs	Maximum images, or zero for every extracted row.
[in]	seed	Politeness jitter seed.
[in]	timeout	Per-request timeout in milliseconds.
[in]	polite	Whether conservative delay bounds apply.

Returns

Number of refused or failed images.

Return values

0	Every attempted image succeeded.
positive	One or more attempted images failed.

Precondition

url and out_dir are non-NULL.

priv_mdl_app_context()->session and priv_mdl_app_context()->images are prepared.

Postcondition

At most max_imgs rows are attempted when it is nonzero.

A complete success/failure tally is printed.

Note

Not thread-safe because it uses shared image/session state.

Since

0.1.0

Definition at line 410 of file mdl_app_direct.c.

References mdl_url_list_t::count, mdl_app_context_t::images, internal_direct_latch(), internal_download_page_image(), k_page_img_delay_max, k_page_img_delay_min, k_polite_img_max_ms, k_polite_img_min_ms, k_ra8_ok, mdl_politeness_init(), priv_mdl_app_context(), priv_mdl_stream_text(), priv_mdl_stream_u64(), and RA8_INTERNAL.

Referenced by mdl_app_run_page().

internal_extract_page_images()

bool internal_extract_page_images ( const char * url, const char * attr, uint32_t timeout )

static

Fetch one page and populate the shared extracted-image list.

Parameters

[in]	url	Policy-approved absolute page URL.
[in]	attr	Image attribute selector.
[in]	timeout	Per-request timeout in milliseconds.

Returns

Whether at least one supported image URL was extracted.

Return values

true	The shared image list contains one or more URLs.
false	Fetching or extraction failed and was diagnosed.

Precondition

The shared session is initialized and url was policy-approved.

Postcondition

Success replaces the shared image list with this page's matches.

Failure never reports a usable empty list.

Note

Not thread-safe because it uses shared page and image buffers.

Since

0.1.0

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Precondition

Every required pointer is non-null and remains valid for the call.

Definition at line 706 of file mdl_app_direct.c.

References internal_direct_latch(), internal_direct_text3(), k_mdl_reason_max, k_ra8_ok, mdl_extract_images(), mdl_net_get_buf(), priv_mdl_app_context(), priv_mdl_fetch_reason(), priv_mdl_stream_text(), mdl_app_context_t::session, mdl_net_resp_t::status, and mdl_session_t::user_agent.

Referenced by mdl_app_run_page().

internal_fetch_artifact()

bool internal_fetch_artifact ( const char * url, const char * final_path, mdl_format_t format, uint32_t timeout, const mdl_run_opts_t * opts, size_t * got )

static

Fetch one policy-approved artifact into an atomic holding path.

Performs fetch artifact under the injected network, governor, and storage contracts; dependency failures are propagated before incomplete bytes are published.

Parameters

[in]	url	Absolute artifact URL.
[in]	final_path	Complete final publication path.
[in]	format	Exact structural verifier selection.
[in]	timeout	Per-request timeout in milliseconds.
[in]	opts	Validated network and identity policy.
[out]	got	Number of downloaded bytes on success.

Returns

Whether a complete staged artifact is ready for validation.

Return values

true	Download completed and network resources were released.
false	Policy, staging, initialization, or transfer failed.

Precondition

All pointer arguments are non-NULL and output capacities are PATH_MAX.

final_path remains confined beneath a canonical output directory.

Postcondition

Network resources are destroyed on every initialized path.

Failure removes any holding file created for this attempt.

Note

Not thread-safe because it replaces the shared network session.

Since

0.1.0

Definition at line 590 of file mdl_app_direct.c.

References internal_direct_artifact_reset(), internal_direct_artifact_write(), internal_direct_latch(), internal_finish_artifact_fetch(), k_mdl_ua_max, k_ra8_err_invalid_state, k_ra8_ok, mdl_net_destroy(), mdl_net_get_body(), mdl_net_provider_open(), mdl_session_url_allowed(), mdl_run_opts_t::net, mdl_direct_artifact_sink_t::output, mdl_run_opts_t::policy, priv_mdl_app_context(), priv_mdl_app_start_session(), priv_mdl_export_output_commit(), priv_mdl_stream_text(), RA8_INTERNAL, mdl_app_context_t::session, mdl_net_resp_t::status, mdl_app_context_t::storage, and mdl_session_t::user_agent.

Referenced by mdl_app_run_artifact().

internal_finish_artifact_fetch()

bool internal_finish_artifact_fetch ( mdl_direct_artifact_sink_t * state, ra8_err_t error, long status )

static

Finalize or abort one direct artifact transfer.

Parameters

[in,out]	state	Active artifact sink state.
[in]	error	Transfer or publication result.
[in]	status	HTTP status associated with error.

Returns

Whether the artifact was published.

Return values

true	Publication completed successfully.
false	The transfer failed and any transaction was aborted.

Precondition

state is non-NULL and initialized for the attempted transfer.

Postcondition

Failure leaves no active transaction.

A structural rejection retains its established diagnostic wording.

Note

Not thread-safe because diagnostics use the shared application context.

Since

0.1.0

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Precondition

Every required pointer is non-null and remains valid for the call.

Definition at line 542 of file mdl_app_direct.c.

References fw_fs_transaction_t::active, internal_direct_latch(), internal_direct_text3(), k_mdl_reason_max, k_ra8_err_validation_failed, k_ra8_ok, mdl_direct_artifact_sink_t::output, priv_mdl_app_context(), priv_mdl_export_output_abort(), priv_mdl_fetch_reason(), priv_mdl_stream_text(), mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by internal_fetch_artifact().

internal_max_u32()

uint32_t internal_max_u32 ( uint32_t a, uint32_t b )

static

Return the larger of two unsigned values.

Performs the comparison without arithmetic or narrowing.

Parameters

[in]	a	First value.
[in]	b	Second value.

Returns

The larger input value.

Return values

a	a is greater than b.
b	b is greater than or equal to a.

Precondition

Both inputs are valid uint32_t values.

No ordering relationship is required.

Postcondition

The result equals one input.

Neither input nor shared state is modified.

Note

Thread-safe and side-effect free.

Since

0.1.0

Definition at line 174 of file mdl_app_direct.c.

References RA8_INTERNAL.

Referenced by internal_download_page_image().

internal_pack_directory_output()

int internal_pack_directory_output ( const char * dir, const char * ext, mdl_format_t format )

static

Package a directory-output format and report its wildcard destination.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Parameters

[in]	dir	Directory path or handle for the operation.
[in]	ext	Filename extension without implicit allocation.
[in]	format	Requested output format.

Returns

Process-style packaging and presentation status.

Return values

0	Packaging and result presentation completed.
1	Export, path construction, or stream output failed.

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 810 of file mdl_app_direct.c.

References internal_direct_pack_failure(), internal_direct_text3(), k_ra8_ok, mdl_export_chapter_ws(), priv_mdl_app_context(), and priv_mdl_stream_text().

Referenced by mdl_app_run_pack().

internal_pack_file_output()

int internal_pack_file_output ( const char * dir, const char * ext, mdl_format_t format )

static

Package a file-output format beside its source directory.

Uses caller-owned application and transaction state. Preserves the first network, storage, export, or presentation failure.

Parameters

[in]	dir	Directory path or handle for the operation.
[in]	ext	Filename extension without implicit allocation.
[in]	format	Requested output format.

Returns

Process-style packaging and presentation status.

Return values

0	Packaging and result presentation completed.
1	Export, path construction, or stream output failed.

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 847 of file mdl_app_direct.c.

References internal_direct_pack_failure(), internal_direct_text3(), k_fw_fs_path_cap, k_ra8_ok, mdl_export_chapter_ws(), priv_mdl_app_context(), and priv_mdl_stream_text().

Referenced by mdl_app_run_pack().

internal_prepare_artifact_path()

bool internal_prepare_artifact_path ( const char * out_dir, const char * leaf, char * final_path )

static

Prepare the exact final path for one direct artifact.

Coordinates prepare artifact path with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	out_dir	Requested output directory.
[in]	leaf	Validated artifact leaf name.
[out]	final_path	Complete canonical publication path.

Returns

Whether the output directory and final path are safe.

Return values

true	final_path is ready for atomic staging.
false	Creation, canonicalization, or joining failed.

Precondition

All pointer arguments are non-NULL and final_path has PATH_MAX bytes.

leaf is the bounded final URL segment.

Postcondition

Success confines final_path beneath a canonical directory.

Failure emits the same stage-specific diagnostic as direct mode.

Note

Not safe for concurrent replacement of out_dir.

Since

0.1.0

Definition at line 503 of file mdl_app_direct.c.

References internal_direct_latch(), internal_direct_text3(), k_fw_fs_path_cap, k_ra8_ok, mdl_path_join(), priv_mdl_app_context(), and priv_mdl_app_storage_ensure_directory().

Referenced by mdl_app_run_artifact().

internal_prepare_output_dir()

bool internal_prepare_output_dir ( const char * out_dir, char * out_abs )

static

Create and canonicalize one direct-action output directory.

Coordinates prepare output dir with fixed application workspaces and propagates validation, storage, or network failure to the selected command runner.

Parameters

[in]	out_dir	Requested output directory.
[out]	out_abs	Canonical absolute output path.

Returns

Whether out_abs names a real directory.

Return values

true	The directory exists and was canonicalized.
false	Creation, resolution, or type validation failed.

Precondition

out_dir and out_abs are non-NULL.

out_abs has capacity PATH_MAX.

Postcondition

Success leaves a real directory at out_abs.

Failure emits one diagnostic and callers perform no network work.

Note

Not safe for concurrent replacement of out_dir.

Since

0.1.0

Definition at line 462 of file mdl_app_direct.c.

References internal_direct_latch(), internal_direct_text3(), k_fw_fs_path_cap, k_ra8_ok, priv_mdl_app_context(), priv_mdl_app_storage_ensure_directory(), and RA8_INTERNAL.

Referenced by mdl_app_run_page().

internal_publish_page_image()

size_t internal_publish_page_image ( mdl_fetch_body_t * body, const char * out_dir, size_t idx )

static

Validate and publish one staged page-mode image.

Performs publish page image under the injected network, governor, and storage contracts; dependency failures are propagated before incomplete bytes are published.

Parameters

[in,out]	body	Complete transaction-owned response body.
[in]	out_dir	Canonical output directory.
[in]	idx	Zero-based page image index.

Returns

Failure contribution for the page tally.

Return values

0	Supported bytes were atomically published.
1	Signature, path, or publication validation failed.

Precondition

body and out_dir are non-NULL and body owns the response stage.

Postcondition

Success leaves only the verified true-extension sibling.

Failure removes the holding file whenever it still exists.

Note

Not safe for concurrent writers targeting the same page index.

Since

0.1.0

Precondition

Every required pointer is non-null and remains valid for the call.

Definition at line 260 of file mdl_app_direct.c.

References mdl_fetch_body_t::actual_abs, internal_direct_latch(), internal_remove_stale_page_variants(), k_ext_bytes, k_ra8_ok, priv_mdl_app_context(), priv_mdl_fetch_body_abort(), priv_mdl_fetch_body_commit(), priv_mdl_fetch_body_prepare(), priv_mdl_stream_text(), priv_mdl_stream_u64(), and strrchr().

Referenced by internal_download_page_image().

internal_remove_stale_page_variants()

void internal_remove_stale_page_variants ( const char * out_dir, size_t page_no, const char * true_ext )

static

Remove stale page files whose extensions differ from verified bytes.

Enumerates the bounded supported image extensions, constructs each sibling leaf with checked formatting/joining, and unlinks every alternate while preserving the just-published true extension.

Parameters

[in]	out_dir	Output directory containing page-mode files.
[in]	page_no	One-based page number used in the fixed leaf pattern.
[in]	true_ext	Verified extension that must remain present.

Precondition

out_dir and true_ext are non-NULL and NUL-terminated.

true_ext names one supported image extension.

Postcondition

Every resolvable alternate page leaf has been unlinked or reported.

The leaf ending in true_ext is never removed.

Note

Not safe for concurrent writers targeting the same page number.

Since

0.1.0

Definition at line 195 of file mdl_app_direct.c.

References internal_direct_latch(), internal_direct_text3(), k_file_path_bytes, k_leaf_name_bytes, k_ra8_ok, mdl_path_join(), priv_mdl_app_context(), priv_mdl_app_storage_unlink_regular(), and strcmp().

Referenced by internal_publish_page_image().

mdl_app_run_artifact()

int mdl_app_run_artifact	(	const char *	url,
		const char *	out_dir,
		uint32_t	timeout,
		const mdl_run_opts_t *	opts )

Download, validate and atomically publish one direct artifact.

Accepts only formats with structural validators, stages the response through a transaction, validates it through the reader path, and only then commits it.

Parameters

[in]	url	Canonical absolute artifact URL.
[in]	out_dir	Canonical output directory.
[in]	timeout	Per-request timeout in milliseconds.
[in]	opts	Validated network and execution policy.

Returns

Run status.

Return values

0	A structurally valid artifact was published.
1	Format, path, network, validation, or commit failed.

Precondition

All pointers are non-NULL and a context is bound.

opts carries a transport provider.

Postcondition

Failure does not publish a partial destination artifact.

The transport opened for the run is destroyed on every path.

Note

Not thread-safe because validation uses the shared exporter workspace.

Since

0.1.0

Definition at line 636 of file mdl_app_direct.c.

References internal_direct_latch(), internal_direct_text3(), internal_fetch_artifact(), internal_prepare_artifact_path(), k_fw_fs_path_cap, k_leaf_name_bytes, k_mdl_format_invalid, k_ra8_ok, mdl_format_from_path(), mdl_format_is_verifiable(), mdl_urlname_last_segment(), mdl_verify_file(), priv_mdl_app_context(), priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by priv_mdl_compose_dispatch().

mdl_app_run_pack()

int mdl_app_run_pack	(	const char *	dir,
		mdl_format_t	format )

Package an existing image directory without network access.

Validates dir, distinguishes directory-output formats from file containers, and streams the supported images through the exporter.

Parameters

[in]	dir	Existing canonical chapter image directory.
[in]	format	Selected output format.

Returns

Run status.

Return values

0	Packaging completed successfully.
1	Path resolution or export failed.
2	The requested format is absent or invalid for pack mode.

Precondition

dir is non-NULL and a context is bound.

The bound exporter workspace is exclusively owned by the caller.

Postcondition

No network request is attempted by this mode.

Export errors are reported with their exact format.

Note

Not thread-safe because it uses the shared exporter workspace.

Since

0.1.0

Definition at line 874 of file mdl_app_direct.c.

References fw_fs_stat_t::exists, fw_fs_stat(), internal_direct_text3(), internal_pack_directory_output(), internal_pack_file_output(), k_fw_fs_node_directory, k_mdl_format_invalid, k_mdl_format_loose, k_ra8_ok, mdl_format_ext(), mdl_format_is_dir_output(), priv_mdl_app_context(), priv_mdl_stream_text(), and fw_fs_stat_t::type.

Referenced by priv_mdl_compose_dispatch().

mdl_app_run_page()

int mdl_app_run_page	(	const char *	url,
		const char *	out_dir,
		const char *	attr,
		uint32_t	max_imgs,
		uint64_t	seed,
		uint32_t	timeout,
		const mdl_run_opts_t *	opts )

Download image resources from one direct page URL.

Opens a transport through the injected provider, enforces URL policy, extracts the selected image attribute and downloads the bounded image set under the governor.

Parameters

[in]	url	Canonical absolute page URL.
[in]	out_dir	Canonical output directory.
[in]	attr	Image attribute selector.
[in]	max_imgs	Maximum images to transfer, or zero for every match.
[in]	seed	Deterministic politeness-jitter seed.
[in]	timeout	Per-request timeout in milliseconds.
[in]	opts	Validated network and execution policy.

Returns

Run status.

Return values

0	Every attempted image succeeded.
1	Network, policy, or image download failed.

Precondition

All pointers are non-NULL and a context is bound.

opts carries a transport provider.

Postcondition

No staged partial image remains published as a final page.

The transport opened for the run is destroyed on every path.

Note

Not thread-safe because it uses the shared extraction buffers.

Since

0.1.0

Definition at line 744 of file mdl_app_direct.c.

References internal_direct_latch(), internal_download_page_images(), internal_extract_page_images(), internal_prepare_output_dir(), k_fw_fs_path_cap, k_mdl_ua_max, k_ra8_ok, mdl_net_destroy(), mdl_net_provider_open(), mdl_session_url_allowed(), mdl_run_opts_t::net, mdl_run_opts_t::policy, mdl_run_opts_t::polite, priv_mdl_app_context(), priv_mdl_app_start_session(), priv_mdl_stream_text(), and priv_mdl_stream_u64().

Referenced by priv_mdl_compose_dispatch().