Portable source streams and validated exporter publication stages. More...

#include <limits.h>
#include <stdio.h>
#include <string.h>
#include "mdl_export_io_internal.h"
#include "mdl_hash.h"
#include "mdl_verify.h"

Include dependency graph for mdl_export_io.c:

Data Structures
struct	internal_export_validation_t
	Context retained while a staged artifact is structurally checked. More...
struct	internal_export_memory_t
	Sequential view over one caller-owned ZIP memory member. More...

Enumerations
enum	mdl_export_io_limit_t : uint32_t { k_export_io_calls = 2000001U }
	Bounded callback call count shared by archive stream adapters. More...

Functions
static ra8_err_t	internal_validate_stage (void ctx, fw_fs_file_t staged)
	Dispatch structural validation for one staged artifact.
static ra8_err_t	internal_output_write_at (mdl_export_output_t output, uint64_t offset, const uint8_t bytes, size_t length)
	Write a complete byte span at one staged offset.
ra8_err_t	priv_mdl_export_output_begin (mdl_export_output_t output, mdl_storage_t storage, const char *destination, mdl_format_t format)
	Bind a validated publication transaction to one destination.
ra8_err_t	priv_mdl_export_output_begin_new (mdl_export_output_t output, mdl_storage_t storage, const char *destination, mdl_format_t format)
	Bind a create-new validated publication transaction.
ra8_err_t	priv_mdl_export_output_write (mdl_export_output_t output, const uint8_t bytes, uint32_t length)
	Append one complete byte span to an active export stage.
ra8_err_t	priv_mdl_export_output_write_at (void opaque, uint64_t offset, const uint8_t bytes, uint32_t length, uint32_t *out_written)
	Write one complete span at an absolute active-stage offset.
size_t	priv_mdl_export_zip_write (void opaque, mz_uint64 file_offset, const void bytes, size_t length)
	Adapt random-offset miniz output to the active export stage.
ra8_err_t	priv_mdl_export_output_abort (mdl_export_output_t *output)
	Abort one unpublished export stage, retaining cleanup failure.
ra8_err_t	priv_mdl_export_output_commit (mdl_export_output_t output, mdl_export_workspace_t workspace, bool *out_published)
	Structurally validate and publish one completed export stage.
ra8_err_t	priv_mdl_export_source_open (mdl_export_source_t source, mdl_storage_t storage, const char *path)
	Open one regular source and snapshot its exact nonempty extent.
ra8_err_t	priv_mdl_export_source_close (mdl_export_source_t *source)
	Close one open source and clear its retained binding.
size_t	priv_mdl_export_zip_read (void opaque, mz_uint64 file_offset, void destination, size_t capacity)
	Adapt one sequential miniz source read to a portable file stream.
ra8_err_t	priv_mdl_export_source_verify_close (mdl_export_source_t *source)
	Verify the first source pass against an independent reread.
ra8_err_t	priv_mdl_export_zip_add_file (mz_zip_archive zip, mdl_storage_t storage, const char member, const char path, mz_uint flags)
	Add one portable source file through miniz callbacks.
static size_t	internal_memory_read (void opaque, mz_uint64 offset, void destination, size_t capacity)
	Serve a sequential ZIP read from immutable caller memory.
ra8_err_t	priv_mdl_export_zip_add_memory (mz_zip_archive zip, const char member, const uint8_t *bytes, size_t length, mz_uint flags)
	Add caller-owned memory through the deterministic ZIP read seam.
ra8_err_t	priv_mdl_export_source_copy (mdl_export_source_t source, mdl_export_sink_fn_t sink, void sink_ctx)
	Stream one portable source into a bounded caller sink.
ra8_err_t	priv_mdl_export_source_slurp (mdl_storage_t storage, const char path, uint8_t destination, size_t capacity, size_t out_length)
	Read one complete bounded portable source into caller storage.
ra8_err_t	priv_mdl_export_path_join (char out, size_t capacity, const char directory, const char *leaf)
	Join a canonical directory and leaf without truncation.

Detailed Description

Portable source streams and validated exporter publication stages.

Adapts injected storage readers and transactions to bounded exporter callbacks while preserving exact publication and abort semantics.

[Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file mdl_export_io.c.

Enumeration Type Documentation

◆ mdl_export_io_limit_t

enum mdl_export_io_limit_t : uint32_t

Bounded callback call count shared by archive stream adapters.

Enumerator
k_export_io_calls	Short-I/O progress ceiling.

Definition at line 22 of file mdl_export_io.c.

Function Documentation

◆ internal_memory_read()

size_t internal_memory_read	(	void *	opaque,
		mz_uint64	offset,
		void *	destination,
		size_t	capacity )

static

Serve a sequential ZIP read from immutable caller memory.

Enforces sequential bounded reads over immutable caller-owned bytes and records no ownership outside the callback context.

Parameters

[in,out]	opaque	Bound internal_export_memory_t.
[in]	offset	Requested sequential offset.
[out]	destination	Destination bytes.
[in]	capacity	Requested byte count.

Returns: Bytes copied, or zero on contract failure/EOF.

Return values

0	Exact EOF or callback contract failure.

Precondition: Context and destination remain valid for the callback.; offset equals the context's sequential cursor.

Postcondition: Success advances the exact sequential cursor.; Input bytes remain unchanged and caller-owned.

Note: Thread-safe across distinct contexts.

Since: 0.1.0

Definition at line 456 of file mdl_export_io.c.

References internal_export_memory_t::bytes, internal_export_memory_t::length, memcpy(), and internal_export_memory_t::offset.

Referenced by priv_mdl_export_zip_add_memory().

◆ internal_output_write_at()

ra8_err_t internal_output_write_at	(	mdl_export_output_t *	output,
		uint64_t	offset,
		const uint8_t *	bytes,
		size_t	length )

static

Write a complete byte span at one staged offset.

Retries bounded short writes and captures the first injected sink failure without claiming partial completion.

Parameters

[in,out]	output	Active output transaction.
[in]	offset	Absolute write offset at or below the current extent.
[in]	bytes	Readable source bytes.
[in]	length	Byte count.

Returns: Canonical seek/write/progress status.

Return values

k_ra8_ok	Every byte reached the stage.
k_ra8_fail	The sink failed or made zero progress.

Precondition: output owns one active stage and pointers satisfy length.; offset does not introduce a hole or overflow the extent.

Postcondition: Success advances the cursor and greatest written edge exactly.; Failure retains the first output error.

Note: ZIP backfills may overwrite but may never introduce a hole.

Since: 0.1.0

Definition at line 95 of file mdl_export_io.c.

References mdl_export_output_t::extent, fw_fs_transaction_seek(), fw_fs_transaction_write(), k_export_io_calls, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, mdl_export_output_t::offset, RA8_INTERNAL, mdl_storage_txn_t::transaction, mdl_storage_txn_t::write_calls, and mdl_export_output_t::writer.

Referenced by priv_mdl_export_output_write(), priv_mdl_export_output_write_at(), and priv_mdl_export_zip_write().

◆ internal_validate_stage()

ra8_err_t internal_validate_stage	(	void *	ctx,
		fw_fs_file_t *	staged )

static

Dispatch structural validation for one staged artifact.

Delegates exact format and extent validation without closing or reopening the transaction-owned staged handle.

Parameters

[in]	ctx	Immutable internal_export_validation_t.
[in,out]	staged	Open staged read handle.

Returns: Selected format validation status.

Return values

k_ra8_ok	The staged artifact is structurally valid.
k_ra8_err_validation_failed	The canonical reader rejected the stage.

Precondition: Both pointers are non-null and staged is exclusively owned.; The validation context carries a live exclusive workspace.

Postcondition: Success proves the canonical format reader accepts the complete stage.; The staged handle remains owned by the transaction.

Note: No publication occurs in this callback.

Since: 0.1.0

Definition at line 58 of file mdl_export_io.c.

References internal_export_validation_t::export_high_water, internal_export_validation_t::extent, internal_export_validation_t::format, mdl_export_workspace::high_water, k_ra8_err_invalid_arg, mdl_verify_open_file(), RA8_INTERNAL, internal_export_validation_t::storage, and internal_export_validation_t::workspace.

Referenced by mdl_storage_copy_atomic(), mdl_storage_txn_commit(), and priv_mdl_export_output_commit().

◆ priv_mdl_export_output_abort()

ra8_err_t priv_mdl_export_output_abort ( mdl_export_output_t * output )

Abort one unpublished export stage, retaining cleanup failure.

Delegates stage removal once and clears the exporter binding only after capturing the transaction's cleanup result.

Parameters

[in,out] output Active caller-owned staged output.

Returns: Abort status.

Return values

k_ra8_ok	The unpublished stage was removed.
k_ra8_fail	The injected transaction could not clean its stage.

Precondition: output is non-NULL and owns an active transaction.; No writer or verifier continues to borrow the staged handle.

Postcondition: The output no longer reports an active transaction.; The destination is never published by this call.

Note: Not thread-safe for a shared output state.

Since: 0.1.0

Definition at line 217 of file mdl_export_io.c.

References k_ra8_err_invalid_arg, k_ra8_ok, mdl_storage_txn_abort(), and mdl_export_output_t::writer.

Referenced by internal_direct_artifact_reset(), internal_emit_container(), internal_export_transaction(), internal_finish_artifact_fetch(), internal_jof_one(), internal_write_temp_epub(), and priv_mdl_export_output_commit().

◆ priv_mdl_export_output_begin()

ra8_err_t priv_mdl_export_output_begin	(	mdl_export_output_t *	output,
		mdl_storage_t *	storage,
		const char *	destination,
		mdl_format_t	format )

Bind a validated publication transaction to one destination.

Initializes the output cursor only after the injected storage transaction accepts the canonical destination.

Parameters

[out]	output	Caller-owned output state to initialize.
[in,out]	storage	Exclusive portable storage transaction provider.
[in]	destination	Canonical NUL-terminated destination path.
[in]	format	Exact format used by the canonical staged verifier.

Returns: Transaction-open status.

Return values

k_ra8_ok	A new unpublished stage is active.
k_ra8_err_invalid_arg	An argument or format is invalid.

Precondition: All pointers are non-NULL and destination is stable for the call.; output is not already bound to an active transaction.

Postcondition: Success initializes every output field and owns one active stage.; Failure leaves output inactive and publishes no destination bytes.

Note: Thread-safe across distinct storage and output bindings.

Since: 0.1.0

Definition at line 129 of file mdl_export_io.c.

References k_ra8_err_invalid_arg, k_ra8_ok, mdl_format_is_verifiable(), mdl_storage_txn_begin(), and mdl_export_output_t::writer.

Referenced by internal_direct_artifact_reset(), internal_emit_container(), internal_export_transaction(), and internal_jof_one().

◆ priv_mdl_export_output_begin_new()

ra8_err_t priv_mdl_export_output_begin_new	(	mdl_export_output_t *	output,
		mdl_storage_t *	storage,
		const char *	destination,
		mdl_format_t	format )

Bind a create-new validated publication transaction.

Mirrors priv_mdl_export_output_begin but refuses an existing destination, which is required for private intermediate artifacts.

Parameters

[out]	output	Caller-owned output state to initialize.
[in,out]	storage	Exclusive portable storage transaction provider.
[in]	destination	Canonical absent destination path.
[in]	format	Exact format used by the staged verifier.

Returns: Transaction-open status.

Return values

k_ra8_ok	A new unpublished stage is active.
k_ra8_err_exists	The destination already exists.
k_ra8_err_invalid_arg	An argument or format is invalid.

Precondition: All pointers are non-NULL and destination is stable for the call.; output is not already bound to an active transaction.

Postcondition: Success initializes every output field and owns one active stage.; Failure leaves output inactive and changes no named file.

Note: Thread-safe across distinct storage and output bindings.

Since: 0.1.0

Definition at line 146 of file mdl_export_io.c.

References k_ra8_err_invalid_arg, k_ra8_ok, mdl_format_is_verifiable(), mdl_storage_txn_begin_new(), RA8_PRIV, and mdl_export_output_t::writer.

Referenced by priv_mdl_rabook_temp_begin().

◆ priv_mdl_export_output_commit()

ra8_err_t priv_mdl_export_output_commit	(	mdl_export_output_t *	output,
		mdl_export_workspace_t *	workspace,
		bool *	out_published )

Structurally validate and publish one completed export stage.

Runs the canonical format verifier against the borrowed staged file, then asks the injected transaction to publish it once.

Parameters

[in,out]	output	Completed caller-owned staged output.
[in,out]	workspace	Exclusive caller arena used by the verifier.
[out]	out_published	Whether the transaction reports destination visibility.

Returns: Validation or commit status.

Return values

k_ra8_ok	Validation and publication completed.
k_ra8_err_validation_failed	Canonical structural validation failed.

Precondition: output owns an active transaction with no retained writer error.; workspace and out_published are writable and caller-owned.

Postcondition: Success leaves no active stage and sets out_published true.; Failure reports publication truthfully and leaves cleanup to the transaction.

Note: Power-loss durability depends on the injected storage capabilities.

Since: 0.1.0

Definition at line 229 of file mdl_export_io.c.

References fw_fs_transaction_t::active, mdl_export_output_t::error, mdl_export_output_t::extent, mdl_export_output_t::format, fw_fs_transaction_abort(), fw_fs_transaction_commit(), fw_fs_transaction_validate(), mdl_export_workspace::high_water, internal_validate_stage(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, priv_mdl_export_output_abort(), mdl_storage_txn_t::storage, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by internal_emit_container(), internal_export_transaction(), internal_fetch_artifact(), internal_jof_one(), and internal_write_temp_epub().

◆ priv_mdl_export_output_write()

ra8_err_t priv_mdl_export_output_write	(	mdl_export_output_t *	output,
		const uint8_t *	bytes,
		uint32_t	length )

Append one complete byte span to an active export stage.

Retries bounded short writes, advances the sequential cursor, and retains the first storage failure in the output state.

Parameters

[in,out]	output	Active caller-owned staged output.
[in]	bytes	Readable bytes to append.
[in]	length	Exact byte count to append.

Returns: Complete-write status.

Return values

k_ra8_ok	Every requested byte was written.
k_ra8_fail	The sink failed or made zero progress.

Precondition: output owns an active transaction and has no retained error.; bytes addresses length readable bytes when length is nonzero.

Postcondition: Success advances offset and extent by exactly length.; Failure retains the first error and never reports partial success.

Note: Not thread-safe for a shared output state.

Since: 0.1.0

Definition at line 164 of file mdl_export_io.c.

References fw_fs_transaction_t::active, mdl_export_output_t::error, internal_output_write_at(), k_ra8_err_invalid_arg, k_ra8_ok, mdl_export_output_t::offset, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by internal_direct_artifact_write(), internal_direct_sink(), internal_gzip_put(), internal_jof_sink(), and priv_mdl_export_tar_gzip().

◆ priv_mdl_export_output_write_at()

ra8_err_t priv_mdl_export_output_write_at	(	void *	opaque,
		uint64_t	offset,
		const uint8_t *	bytes,
		uint32_t	length,
		uint32_t *	out_written )

Write one complete span at an absolute active-stage offset.

Adapts the export transaction to the RABOOK container writer's random-write contract while retaining the first output error.

Parameters

[in,out]	opaque	Bound mdl_export_output_t.
[in]	offset	Absolute stage offset; holes are rejected.
[in]	bytes	Readable source bytes.
[in]	length	Exact requested byte count.
[out]	out_written	Exact written byte count on success.

Returns: Complete random-write status.

Return values

k_ra8_ok	Every requested byte was staged.
k_ra8_err_invalid_arg	A pointer or output lifecycle is invalid.
k_ra8_err_invalid_size	The write would create a hole or overflow.

Precondition: opaque owns one active transaction and bytes spans length bytes.; out_written is non-NULL and exclusively writable.

Postcondition: Success sets out_written to length and updates the staged extent.; Failure sets out_written to zero and retains the first output error.

Note: Not thread-safe for a shared output.

Since: 0.1.0

Definition at line 177 of file mdl_export_io.c.

References fw_fs_transaction_t::active, mdl_export_output_t::error, internal_output_write_at(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_PRIV, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by internal_emit_container().

◆ priv_mdl_export_path_join()

ra8_err_t priv_mdl_export_path_join	(	char *	out,
		size_t	capacity,
		const char *	directory,
		const char *	leaf )

Join a canonical directory and leaf without truncation.

Inserts one separator only when required and rejects arithmetic or capacity overflow before copying either component.

Parameters

[out]	out	Caller-owned destination string.
[in]	capacity	Total writable bytes including the terminator.
[in]	directory	Canonical NUL-terminated directory.
[in]	leaf	Canonical NUL-terminated leaf.

Returns: Join status.

Return values

k_ra8_ok	The complete joined path fits.
k_ra8_err_invalid_size	The complete path exceeds `capacity`.

Precondition: All pointers are non-NULL and input strings are stable.; out is writable for capacity bytes and does not overlap inputs.

Postcondition: Success leaves one NUL-terminated joined path.; Failure leaves out as an empty string when capacity is nonzero.

Note: Pure apart from the caller-owned destination.

Since: 0.1.0

Definition at line 551 of file mdl_export_io.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, and strcmp().

Referenced by internal_build_tar(), internal_cbz_add_pages(), internal_epub_add_page(), internal_epub_media_type_from_sniff(), internal_meta_candidate_path(), internal_metadata_set_page_timestamp(), priv_mdl_export_jof(), and priv_mdl_rabook_temp_begin().

◆ priv_mdl_export_source_close()

ra8_err_t priv_mdl_export_source_close ( mdl_export_source_t * source )

Close one open source and clear its retained binding.

Closes the injected stream exactly once and clears all borrowed storage and cursor state regardless of close status.

Parameters

[in,out] source Open caller-owned source state.

Returns: Close status.

Return values

k_ra8_ok	The source closed cleanly.
k_ra8_fail	The injected close operation failed.

Precondition: source is non-NULL and owns an open portable stream.; No callback continues to use the source handle.

Postcondition: The source owns no open stream.; The source's retained binding and extent are cleared.

Note: Not thread-safe for a shared source state.

Since: 0.1.0

Definition at line 315 of file mdl_export_io.c.

References mdl_export_source_t::file, fw_fs_close(), fw_fs_file_t::is_open, k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_tar_write_source(), priv_mdl_export_source_slurp(), and priv_mdl_export_zip_add_file().

◆ priv_mdl_export_source_copy()

ra8_err_t priv_mdl_export_source_copy	(	mdl_export_source_t *	source,
		mdl_export_sink_fn_t	sink,
		void *	sink_ctx )

Stream one portable source into a bounded caller sink.

Reads the exact snapshotted extent through storage scratch, offers each bounded span to the sink, then performs an independent reread.

Parameters

[in,out]	source	Open caller-owned source.
[in]	sink	Non-NULL bounded output callback.
[in,out]	sink_ctx	Opaque sink context retained by the caller.

Returns: Copy, identity, or close status.

Return values

k_ra8_ok	The whole stable source reached the sink.
k_ra8_err_validation_failed	The source changed during the copy.

Precondition: source owns an open stream and sink is callable.; The storage I/O scratch is exclusive to this operation.

Postcondition: The source is closed on every return path.; Success offers every source byte exactly once in order.

Note: Sink ownership never transfers to the exporter.

Since: 0.1.0

Definition at line 499 of file mdl_export_io.c.

References mdl_export_source_t::error, mdl_export_source_t::file, mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, fw_fs_file_t::is_open, k_ra8_err_invalid_arg, k_ra8_ok, mdl_export_source_t::offset, priv_mdl_export_source_verify_close(), priv_mdl_export_zip_read(), mdl_export_source_t::size, and mdl_export_source_t::storage.

Referenced by internal_tar_write_source().

◆ priv_mdl_export_source_open()

ra8_err_t priv_mdl_export_source_open	(	mdl_export_source_t *	source,
		mdl_storage_t *	storage,
		const char *	path )

Open one regular source and snapshot its exact nonempty extent.

Rejects missing, empty, symlink, and nonregular nodes before opening the stream through the injected portable filesystem.

Parameters

[out]	source	Caller-owned source state to initialize.
[in,out]	storage	Exclusive portable stream provider.
[in]	path	Canonical NUL-terminated source path.

Returns: Source-open status.

Return values

k_ra8_ok	A regular nonempty source is open.
k_ra8_err_invalid_arg	The node is symlinked or nonregular.

Precondition: Pointers are non-NULL and path remains stable for the call.; source does not own an open stream.

Postcondition: Success snapshots size and initializes hash/cursor state.; Failure leaves source clear and owns no stream.

Note: Not thread-safe against concurrent source replacement.

Since: 0.1.0

Definition at line 270 of file mdl_export_io.c.

References fw_fs_stat_t::exists, mdl_export_source_t::file, mdl_storage_t::file_workspace, mdl_storage_t::file_workspace_bytes, mdl_storage_t::fs, fw_fs_close(), fw_fs_file_size(), fw_fs_open(), fw_fs_stat(), fw_fs_file_t::is_open, k_fw_fs_node_file, k_fw_fs_open_read, k_mdl_fnv_offset, k_mdl_hash_max_file_bytes, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_err_protocol_error, k_ra8_ok, fw_fs_t::names, mdl_export_source_t::size, fw_fs_stat_t::size_bytes, fw_fs_t::streams, and fw_fs_stat_t::type.

Referenced by internal_tar_write_source(), priv_mdl_export_source_slurp(), and priv_mdl_export_zip_add_file().

◆ priv_mdl_export_source_slurp()

ra8_err_t priv_mdl_export_source_slurp	(	mdl_storage_t *	storage,
		const char *	path,
		uint8_t *	destination,
		size_t	capacity,
		size_t *	out_length )

Read one complete bounded portable source into caller storage.

Opens and consumes one stable regular file without truncation, verifies it through an independent reread, and returns exact length.

Parameters

[in,out]	storage	Exclusive portable source storage.
[in]	path	Canonical source path.
[out]	destination	Caller-owned byte buffer.
[in]	capacity	Writable destination capacity.
[out]	out_length	Exact copied extent on success.

Returns: Bounded read status.

Return values

k_ra8_ok	A stable complete source was copied.
k_ra8_err_invalid_size	The snapshot exceeds `capacity`.

Precondition: Pointers are non-NULL and destination is writable for capacity.; storage is initialized and exclusive to this read.

Postcondition: Success sets out_length and fills exactly that many bytes.; Failure sets out_length to zero and closes any opened stream.

Note: No partial buffer content is claimed on failure.

Since: 0.1.0

Definition at line 520 of file mdl_export_io.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_protocol_error, k_ra8_ok, priv_mdl_export_source_close(), priv_mdl_export_source_open(), priv_mdl_export_source_verify_close(), priv_mdl_export_zip_read(), and mdl_export_source_t::size.

Referenced by internal_jof_load_source(), and internal_meta_load_candidate().

◆ priv_mdl_export_source_verify_close()

ra8_err_t priv_mdl_export_source_verify_close ( mdl_export_source_t * source )

Verify the first source pass against an independent reread.

Requires complete first-pass consumption, seeks to the beginning, hashes an independent bounded reread, checks size stability, and closes.

Parameters

[in,out] source Open source after a complete first pass.

Returns: Identity and close status.

Return values

k_ra8_ok	Both passes and the final size snapshot match.
k_ra8_err_validation_failed	The source changed between passes.

Precondition: source owns an open regular stream.; Its first-pass cursor and hash describe the exported member bytes.

Postcondition: The source is closed on every return path.; Success proves both passes consumed the snapshotted extent identically.

Note: Fails closed on seek, read, stat, truncation, or growth.

Since: 0.1.0

Definition at line 368 of file mdl_export_io.c.

References mdl_export_source_t::error, mdl_export_source_t::file, fw_fs_close(), fw_fs_seek(), mdl_export_source_t::hash, mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, fw_fs_file_t::is_open, k_ra8_err_invalid_arg, k_ra8_err_protocol_error, k_ra8_ok, mdl_hash_stream(), mdl_export_source_t::offset, mdl_export_source_t::size, and mdl_export_source_t::storage.

Referenced by priv_mdl_export_source_copy(), priv_mdl_export_source_slurp(), and priv_mdl_export_zip_add_file().

◆ priv_mdl_export_zip_add_file()

ra8_err_t priv_mdl_export_zip_add_file	(	mz_zip_archive *	zip,
		mdl_storage_t *	storage,
		const char *	member,
		const char *	path,
		mz_uint	flags )

Add one portable source file through miniz callbacks.

Opens the source through injected storage, supplies deterministic callback metadata to miniz, then independently rereads before success.

Parameters

[in,out]	zip	Initialized caller-arena miniz writer.
[in,out]	storage	Exclusive portable source storage.
[in]	member	Canonical archive member name.
[in]	path	Canonical source path.
[in]	flags	Miniz compression flags.

Returns: Member-add status.

Return values

k_ra8_ok	The complete stable source was added.
k_ra8_err_validation_failed	The source changed during export.

Precondition: Pointers and strings are non-NULL and stable for the call.; zip is initialized with caller-owned allocator and output callbacks.

Postcondition: Success appends exactly one deterministic member.; Every opened source closes on success and failure.

Note: Uses a NULL member timestamp to preserve byte determinism.

Since: 0.1.0

Definition at line 399 of file mdl_export_io.c.

References mdl_export_source_t::error, k_ra8_fail, k_ra8_ok, priv_mdl_export_source_close(), priv_mdl_export_source_open(), priv_mdl_export_source_verify_close(), priv_mdl_export_zip_read(), and mdl_export_source_t::size.

Referenced by internal_cbz_add_pages(), internal_epub_add_external_cover(), internal_epub_add_page(), and priv_mdl_export_cbz().

◆ priv_mdl_export_zip_add_memory()

ra8_err_t priv_mdl_export_zip_add_memory	(	mz_zip_archive *	zip,
		const char *	member,
		const uint8_t *	bytes,
		size_t	length,
		mz_uint	flags )

Add caller-owned memory through the deterministic ZIP read seam.

Binds an immutable bounded cursor to miniz's read-callback API so generated metadata uses the same deterministic member path.

Parameters

[in,out]	zip	Initialized caller-arena miniz writer.
[in]	member	Canonical archive member name.
[in]	bytes	Immutable caller-owned member bytes.
[in]	length	Exact member extent.
[in]	flags	Miniz compression flags.

Returns: Member-add status.

Return values

k_ra8_ok	The memory member was added completely.
k_ra8_fail	Miniz rejected or incompletely consumed the member.

Precondition: Pointers are non-NULL and bytes remains readable for length.; zip is initialized and its caller arena remains live.

Postcondition: Success appends exactly one deterministic member.; Input bytes and caller ownership remain unchanged.

Note: Uses a NULL member timestamp to avoid host-clock dependence.

Since: 0.1.0

Definition at line 472 of file mdl_export_io.c.

References internal_memory_read(), k_ra8_err_invalid_arg, k_ra8_fail, k_ra8_ok, internal_export_memory_t::length, and internal_export_memory_t::offset.

Referenced by internal_cbz_add_metadata(), and priv_mdl_epub_add_str().

◆ priv_mdl_export_zip_read()

size_t priv_mdl_export_zip_read	(	void *	opaque,
		mz_uint64	file_offset,
		void *	destination,
		size_t	capacity )

Adapt one sequential miniz source read to a portable file stream.

Enforces exact sequential offsets, bounded progress, snapshotted extent, and a running first-pass identity hash for later reread.

Parameters

[in,out]	opaque	Borrowed mdl_export_source_t callback context.
[in]	file_offset	Absolute source offset requested by miniz.
[out]	destination	Writable callback destination.
[in]	capacity	Maximum bytes requested.

Returns: Bytes read, or zero on EOF/failure.

Return values

0	End of the snapshot or a retained protocol/storage failure.

Precondition: opaque owns an open source and destination is writable.; Calls are sequential and do not exceed the snapshotted extent.

Postcondition: Success advances the source cursor and hash by the returned count.; Failure retains a non-ok error unless the snapshot is exactly exhausted.

Note: Called synchronously by one miniz writer.

Since: 0.1.0

Definition at line 331 of file mdl_export_io.c.

References mdl_export_source_t::calls, mdl_export_source_t::error, mdl_export_source_t::file, fw_fs_read(), mdl_export_source_t::hash, fw_fs_file_t::is_open, k_export_io_calls, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_protocol_error, k_ra8_ok, mdl_hash_bytes_seed(), mdl_export_source_t::offset, and mdl_export_source_t::size.

Referenced by priv_mdl_export_source_copy(), priv_mdl_export_source_slurp(), and priv_mdl_export_zip_add_file().

◆ priv_mdl_export_zip_write()

size_t priv_mdl_export_zip_write	(	void *	opaque,
		mz_uint64	file_offset,
		const void *	bytes,
		size_t	length )

Adapt random-offset miniz output to the active export stage.

Seeks the injected transaction for ZIP backfill, writes the whole span with bounded progress, and returns miniz-compatible byte count.

Parameters

[in,out]	opaque	Borrowed mdl_export_output_t callback context.
[in]	file_offset	Absolute staged-file offset selected by miniz.
[in]	bytes	Readable archive bytes.
[in]	length	Requested byte count.

Returns: length on complete success, otherwise zero.

Return values

0	Seek, size, or write failure occurred.

Precondition: opaque is a live output and bytes is readable for length.; file_offset and length admit a uint64 extent without overflow.

Postcondition: Success updates the cursor and greatest staged extent exactly.; Failure retains the first error for the owning writer.

Note: Called synchronously by one miniz writer.

Since: 0.1.0

Definition at line 201 of file mdl_export_io.c.

References fw_fs_transaction_t::active, mdl_export_output_t::error, internal_output_write_at(), k_ra8_ok, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by priv_mdl_export_cbz(), and priv_mdl_export_epub().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_export_io_limit_t

Function Documentation

◆ internal_memory_read()

◆ internal_output_write_at()

◆ internal_validate_stage()

◆ priv_mdl_export_output_abort()

◆ priv_mdl_export_output_begin()

◆ priv_mdl_export_output_begin_new()

◆ priv_mdl_export_output_commit()

◆ priv_mdl_export_output_write()

◆ priv_mdl_export_output_write_at()

◆ priv_mdl_export_path_join()

◆ priv_mdl_export_source_close()

◆ priv_mdl_export_source_copy()

◆ priv_mdl_export_source_open()

◆ priv_mdl_export_source_slurp()

◆ priv_mdl_export_source_verify_close()

◆ priv_mdl_export_zip_add_file()

◆ priv_mdl_export_zip_add_memory()

◆ priv_mdl_export_zip_read()

◆ priv_mdl_export_zip_write()