Stream deterministic CBT and gzip-wrapped CBT containers. More...

#include <stdio.h>
#include <string.h>
#include "mdl_export.h"
#include "mdl_export_internal.h"
#include "miniz.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_export_tar.c:

Data Structures
struct	internal_tar_sink_t
	Direct tar sink adapter. More...
struct	internal_gzip_sink_t
	Online gzip state receiving the uncompressed tar stream. More...

Enumerations
enum	mdl_tar_layout_t : uint16_t { k_tar_block = 512U , k_off_name = 0U , k_len_name = 100U , k_off_mode = 100U , k_off_uid = 108U , k_off_gid = 116U , k_len_id = 8U , k_off_size = 124U , k_len_size = 12U , k_off_mtime = 136U , k_len_mtime = 12U , k_off_chksum = 148U , k_len_chksum = 8U , k_off_type = 156U , k_off_magic = 257U , k_len_magic = 6U , k_off_version = 263U }
	ustar header field offsets and widths. More...
enum	mdl_tar_mode_t : uint16_t { k_file_mode = 0644U }
	Fixed regular-file mode in deterministic tar headers. More...
enum	mdl_tar_size_t : uint64_t { k_tar_size_max = 077777777777ULL }
	Largest payload representable by the fixed eleven-digit tar field. More...
enum	mdl_gzip_layout_t : uint16_t { k_gzip_header_bytes = 10U , k_gzip_u32_bytes = 4U , k_byte_bits = 8U , k_byte_mask = 255U }
	Gzip framing and serialization constants. More...
enum	mdl_gzip_header_t : uint8_t { k_gzip_id1 = 0x1FU , k_gzip_id2 = 0x8BU , k_gzip_deflate = 0x08U , k_gzip_os_unknown = 0xFFU }
	Fixed non-zero bytes in the RFC 1952 header. More...

Functions
static size_t	internal_round_block (size_t bytes)
	Round one payload extent to a whole tar record.
static ra8_err_t	internal_tar_header (uint8_t block, const char name, size_t size)
	Build one deterministic ustar regular-file header.
static ra8_err_t	internal_direct_sink (void ctx, const uint8_t bytes, uint32_t length)
	Append bytes directly to an archive publication stage.
static ra8_err_t	internal_write_zeros (mdl_export_sink_fn_t sink, void *ctx, uint32_t length)
	Emit zero padding through one archive sink.
static ra8_err_t	internal_tar_write_memory (mdl_export_sink_fn_t sink, void ctx, const char name, const uint8_t *bytes, size_t length)
	Emit one bounded in-memory tar member.
static ra8_err_t	internal_tar_write_source (mdl_storage_t storage, const char path, const char member, mdl_export_sink_fn_t sink, void ctx)
	Emit one portable source as a verified tar member.
static ra8_err_t	internal_build_tar (mdl_storage_t storage, const char directory, char names[][k_name_max], size_t count, const mdl_export_meta_t meta, mdl_export_sink_fn_t sink, void ctx)
	Stream a complete deterministic ustar archive.
static mz_bool	internal_gzip_put (const void bytes, int length, void ctx)
	Append DEFLATE callback output to the active stage.
static ra8_err_t	internal_gzip_sink (void ctx, const uint8_t bytes, uint32_t length)
	Feed one uncompressed tar span into streaming DEFLATE.
static void	internal_put_u32le (uint8_t *bytes, uint32_t value)
	Serialize one little-endian gzip trailer scalar.
ra8_err_t	priv_mdl_export_tar (mdl_storage_t storage, const char dir, char names[][k_name_max], size_t count, mdl_export_output_t output, const mdl_export_meta_t meta)
	Write an uncompressed CBT tar archive.
ra8_err_t	priv_mdl_export_tar_gzip (mdl_storage_t storage, const char dir, char names[][k_name_max], size_t count, mdl_export_output_t output, const mdl_export_meta_t meta, mdl_export_workspace_t *ws)
	Write a gzip-wrapped CBT archive.

Variables
static const uint8_t	s_ustar_magic [k_len_magic] = {'u', 's', 't', 'a', 'r', '\0'}
	Fixed ustar magic and version payloads.
static const uint8_t	s_ustar_version [2] = {'0', '0'}

Detailed Description

Stream deterministic CBT and gzip-wrapped CBT containers.

Emits ustar records directly into a caller-owned portable sink. Gzip wraps that same stream online, so no intermediate archive or host stream exists and all publication remains one validated transaction.

[Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file mdl_export_tar.c.

Enumeration Type Documentation

◆ mdl_gzip_header_t

enum mdl_gzip_header_t : uint8_t

Fixed non-zero bytes in the RFC 1952 header.

Enumerator
k_gzip_id1	Gzip identification byte one.
k_gzip_id2	Gzip identification byte two.
k_gzip_deflate	DEFLATE compression method.
k_gzip_os_unknown	Unknown originating OS.

Definition at line 63 of file mdl_export_tar.c.

◆ mdl_gzip_layout_t

enum mdl_gzip_layout_t : uint16_t

Gzip framing and serialization constants.

Enumerator
k_gzip_header_bytes	Fixed RFC 1952 header.
k_gzip_u32_bytes	Trailer scalar width.
k_byte_bits	Bits shifted per byte.
k_byte_mask	Low-byte extraction.

Definition at line 55 of file mdl_export_tar.c.

◆ mdl_tar_layout_t

enum mdl_tar_layout_t : uint16_t

ustar header field offsets and widths.

Enumerator
k_tar_block	Tar record size.
k_off_name	Name field offset.
k_len_name	Name field width.
k_off_mode	Mode field offset.
k_off_uid	UID field offset.
k_off_gid	GID field offset.
k_len_id	Mode/UID/GID field width.
k_off_size	Size field offset.
k_len_size	Size field width.
k_off_mtime	Timestamp field offset.
k_len_mtime	Timestamp field width.
k_off_chksum	Checksum field offset.
k_len_chksum	Checksum field width.
k_off_type	Entry-type field offset.
k_off_magic	Ustar magic offset.
k_len_magic	Ustar magic width.
k_off_version	Ustar version offset.

Definition at line 24 of file mdl_export_tar.c.

◆ mdl_tar_mode_t

enum mdl_tar_mode_t : uint16_t

Fixed regular-file mode in deterministic tar headers.

Enumerator
k_file_mode	Portable regular-file permission bits.

Definition at line 45 of file mdl_export_tar.c.

◆ mdl_tar_size_t

enum mdl_tar_size_t : uint64_t

Largest payload representable by the fixed eleven-digit tar field.

Enumerator
k_tar_size_max	Maximum classic octal payload size.

Definition at line 50 of file mdl_export_tar.c.

Function Documentation

◆ internal_build_tar()

ra8_err_t internal_build_tar	(	mdl_storage_t *	storage,
		const char *	directory,
		char	names[][k_name_max],
		size_t	count,
		const mdl_export_meta_t *	meta,
		mdl_export_sink_fn_t	sink,
		void *	ctx )

static

Stream a complete deterministic ustar archive.

Emits page members in sorted order, one generated ComicInfo member, and the two-record ustar trailer without retaining the archive.

Parameters

[in,out]	storage	Bound portable filesystem.
[in]	directory	Chapter directory.
[in]	names	Sorted page rows.
[in]	count	Page count.
[in]	meta	Metadata to encode.
[in]	sink	Destination callback.
[in,out]	ctx	Destination context.

Returns: Complete tar-stream status.

Return values

k_ra8_ok	The complete archive stream was accepted.
k_ra8_fail	A source, metadata, or sink operation failed.

Precondition: All pointers are valid and sources remain stable.; names contains count terminated rows in desired member order.

Postcondition: Success includes ComicInfo and two zero trailer records.; Failure stops at the first rejected source or output span.

Note: Not thread-safe for shared storage or sink state.

Since: 0.1.0

Definition at line 313 of file mdl_export_tar.c.

References internal_tar_write_memory(), internal_tar_write_source(), k_fw_fs_path_cap, k_name_max, k_ra8_ok, k_tar_block, mdl_export_build_comicinfo_pages(), priv_mdl_export_path_join(), RA8_INTERNAL, and strlen().

Referenced by priv_mdl_export_tar(), and priv_mdl_export_tar_gzip().

◆ internal_direct_sink()

ra8_err_t internal_direct_sink	(	void *	ctx,
		const uint8_t *	bytes,
		uint32_t	length )

static

Append bytes directly to an archive publication stage.

Adapts the generic tar sink contract to the exporter transaction's complete-write operation without taking ownership.

Parameters

[in,out]	ctx	Bound internal_tar_sink_t.
[in]	bytes	Source bytes.
[in]	length	Source extent.

Returns: Transaction write status.

Return values

k_ra8_ok	Every byte was appended.
k_ra8_fail	The injected transaction sink failed.

Precondition: Context and byte span are valid.; The bound output owns an active transaction.

Postcondition: Success appends exactly length bytes.; Failure remains retained by the output transaction.

Note: Not thread-safe for a shared stage.

Since: 0.1.0

Definition at line 166 of file mdl_export_tar.c.

References priv_mdl_export_output_write(), and RA8_INTERNAL.

Referenced by priv_mdl_export_tar().

◆ internal_gzip_put()

mz_bool internal_gzip_put	(	const void *	bytes,
		int	length,
		void *	ctx )

static

Append DEFLATE callback output to the active stage.

Converts miniz's signed callback count to the bounded transaction writer contract and retains the first output failure.

Parameters

[in]	bytes	Compressed bytes.
[in]	length	Signed miniz byte count.
[in,out]	ctx	Bound internal_gzip_sink_t.

Returns: Miniz callback status.

Return values

MZ_TRUE	The complete compressed span was accepted.
MZ_FALSE	Arguments or the output transaction failed.

Precondition: Context and nonnegative byte span are valid.; The bound output owns an active transaction.

Postcondition: Failure is retained for exact caller propagation.; Success appends exactly length compressed bytes.

Note: Not thread-safe for shared gzip state.

Since: 0.1.0

Definition at line 364 of file mdl_export_tar.c.

References internal_gzip_sink_t::error, k_ra8_ok, internal_gzip_sink_t::output, priv_mdl_export_output_write(), and RA8_INTERNAL.

Referenced by priv_mdl_export_tar_gzip().

◆ internal_gzip_sink()

ra8_err_t internal_gzip_sink	(	void *	ctx,
		const uint8_t *	bytes,
		uint32_t	length )

static

Feed one uncompressed tar span into streaming DEFLATE.

Updates the gzip CRC and modulo-size before passing the complete input span to the caller-arena compressor.

Parameters

[in,out]	ctx	Bound internal_gzip_sink_t.
[in]	bytes	Tar bytes.
[in]	length	Tar byte count.

Returns: Compression/output status.

Return values

k_ra8_ok	The complete tar span was consumed.
k_ra8_fail	Compression or compressed-output delivery failed.

Precondition: Context and byte span are valid.; The caller-arena compressor remains initialized.

Postcondition: Success folds the complete span into CRC, size, and DEFLATE state.; Failure is retained in the shared gzip sink state.

Note: Not thread-safe for shared compressor state.

Since: 0.1.0

Definition at line 391 of file mdl_export_tar.c.

References internal_gzip_sink_t::compressor, internal_gzip_sink_t::crc, internal_gzip_sink_t::error, k_ra8_fail, k_ra8_ok, RA8_INTERNAL, and internal_gzip_sink_t::size.

Referenced by priv_mdl_export_tar_gzip().

◆ internal_put_u32le()

void internal_put_u32le	(	uint8_t *	bytes,
		uint32_t	value )

static

Serialize one little-endian gzip trailer scalar.

Emits the low byte first and shifts exactly once per output byte.

Parameters

[out]	bytes	Four writable bytes.
[in]	value	Scalar to encode.

Precondition: bytes covers k_gzip_u32_bytes bytes.; k_gzip_u32_bytes equals the encoded uint32 width.

Postcondition: The portable little-endian representation is complete.; Exactly k_gzip_u32_bytes caller-owned bytes are modified.

Note: Thread-safe across distinct output bytes.

Since: 0.1.0

Definition at line 417 of file mdl_export_tar.c.

References k_byte_bits, k_byte_mask, k_gzip_u32_bytes, and RA8_INTERNAL.

Referenced by priv_mdl_export_tar_gzip().

◆ internal_round_block()

size_t internal_round_block ( size_t bytes )

static

Round one payload extent to a whole tar record.

Adds at most one record-minus-one before integer division so no loop or hidden state is required.

Parameters

[in] bytes Payload extent.

Returns: Smallest record-aligned extent not below bytes.

Return values

size_t Record-aligned padded extent.

Precondition: bytes leaves room for one record-minus-one addition.; k_tar_block is a nonzero compile-time record size.

Postcondition: The result is divisible by k_tar_block.; The result is not smaller than bytes.

Note: Thread-safe and side-effect free.

Since: 0.1.0

Definition at line 102 of file mdl_export_tar.c.

References k_tar_block, and RA8_INTERNAL.

Referenced by internal_tar_write_memory(), and internal_tar_write_source().

◆ internal_tar_header()

ra8_err_t internal_tar_header	(	uint8_t *	block,
		const char *	name,
		size_t	size )

static

Build one deterministic ustar regular-file header.

Zeroes the complete record, encodes fixed owner/time fields, then computes the checksum with the checksum field represented by spaces.

Parameters

[out]	block	Writable tar record.
[in]	name	Bounded archive member name.
[in]	size	Exact payload extent.

Returns: Header construction status.

Return values

k_ra8_ok	The complete header was written.
k_ra8_err_invalid_size	A field cannot represent its input.

Precondition: Pointers are valid and block covers k_tar_block bytes.; name is NUL-terminated and stable for the call.

Postcondition: Success initializes every record byte deterministically.; Failure never reports a truncated name or unrepresentable size as valid.

Note: Thread-safe across distinct output records.

Since: 0.1.0

Definition at line 124 of file mdl_export_tar.c.

References k_file_mode, k_len_chksum, k_len_id, k_len_mtime, k_len_name, k_len_size, k_off_chksum, k_off_gid, k_off_magic, k_off_mode, k_off_mtime, k_off_name, k_off_size, k_off_type, k_off_uid, k_off_version, k_ra8_err_invalid_size, k_ra8_ok, k_tar_block, k_tar_size_max, memcpy(), memset(), RA8_INTERNAL, s_ustar_magic, s_ustar_version, and strlen().

Referenced by internal_tar_write_memory(), and internal_tar_write_source().

◆ internal_tar_write_memory()

ra8_err_t internal_tar_write_memory	(	mdl_export_sink_fn_t	sink,
		void *	ctx,
		const char *	name,
		const uint8_t *	bytes,
		size_t	length )

static

Emit one bounded in-memory tar member.

Writes a deterministic header, the exact payload, and record padding sequentially through the caller sink.

Parameters

[in]	sink	Destination callback.
[in,out]	ctx	Destination context.
[in]	name	Archive member name.
[in]	bytes	Payload bytes.
[in]	length	Payload extent.

Returns: Header, payload, or padding status.

Return values

k_ra8_ok	The complete member was emitted.
k_ra8_err_invalid_size	A header field or payload bound was exceeded.

Precondition: Inputs satisfy their declared bounds.; sink and ctx remain valid for all callbacks.

Postcondition: Success leaves the sink at a tar-record boundary.; Failure stops at the first rejected component.

Note: Not thread-safe for a shared sink.

Since: 0.1.0

Definition at line 214 of file mdl_export_tar.c.

References internal_round_block(), internal_tar_header(), internal_write_zeros(), k_ra8_err_invalid_size, k_ra8_ok, k_tar_block, and RA8_INTERNAL.

Referenced by internal_build_tar().

◆ internal_tar_write_source()

ra8_err_t internal_tar_write_source	(	mdl_storage_t *	storage,
		const char *	path,
		const char *	member,
		mdl_export_sink_fn_t	sink,
		void *	ctx )

static

Emit one portable source as a verified tar member.

Snapshots the regular source, writes its deterministic header, streams the first pass, verifies an independent reread, and pads.

Parameters

[in,out]	storage	Bound portable filesystem.
[in]	path	Canonical source path.
[in]	member	Archive member name.
[in]	sink	Destination callback.
[in,out]	ctx	Destination context.

Returns: Source, header, sink, or preservation status.

Return values

k_ra8_ok	The complete stable source member was emitted.
k_ra8_err_validation_failed	The source changed between passes.

Precondition: Inputs remain stable and storage is exclusively owned.; sink and ctx remain callable for the complete member.

Postcondition: Success independently verifies the complete source first pass.; Every opened source stream is closed on success and failure.

Note: Concurrent source mutation fails closed.

Since: 0.1.0

Definition at line 256 of file mdl_export_tar.c.

References mdl_export_source_t::file, internal_round_block(), internal_tar_header(), internal_write_zeros(), fw_fs_file_t::is_open, k_ra8_err_invalid_size, k_ra8_ok, k_tar_block, priv_mdl_export_source_close(), priv_mdl_export_source_copy(), priv_mdl_export_source_open(), RA8_INTERNAL, and mdl_export_source_t::size.

Referenced by internal_build_tar().

◆ internal_write_zeros()

ra8_err_t internal_write_zeros	(	mdl_export_sink_fn_t	sink,
		void *	ctx,
		uint32_t	length )

static

Emit zero padding through one archive sink.

Uses one bounded zero record and never emits a callback for a zero-length request.

Parameters

[in]	sink	Destination callback.
[in,out]	ctx	Destination context.
[in]	length	Zero-byte extent, at most one tar record.

Returns: Sink status.

Return values

k_ra8_ok	Padding was empty or completely accepted.
k_ra8_fail	The injected sink rejected the padding.

Precondition: sink is non-null and length does not exceed k_tar_block.; ctx remains valid for the callback duration.

Postcondition: Success appends exactly length zero bytes.; No caller-owned input buffer is mutated.

Note: Thread-safe across distinct sinks.

Since: 0.1.0

Definition at line 189 of file mdl_export_tar.c.

References k_ra8_ok, and k_tar_block.

Referenced by internal_tar_write_memory(), and internal_tar_write_source().

◆ priv_mdl_export_tar()

ra8_err_t priv_mdl_export_tar	(	mdl_storage_t *	storage,
		const char *	dir,
		char	names[][k_name_max],
		size_t	count,
		mdl_export_output_t *	output,
		const mdl_export_meta_t *	meta )

Write an uncompressed CBT tar archive.

Streams page members and ComicInfo through deterministic ustar records without retaining the whole archive.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in,out]	output	Active validated-publication output.
[in]	meta	Resolved metadata.

Returns: Writer status.

Return values

k_ra8_ok	A complete CBT was written.
k_ra8_err_invalid_size	A ustar or metadata bound was exceeded.
k_ra8_fail	File I/O failed.

Precondition: Paths and rows are valid and stable.; output owns an active transaction.

Postcondition: Every opened source stream is closed.; Success includes the complete ustar trailer.

Note: Not thread-safe for the same output.

Since: 0.1.0

Definition at line 425 of file mdl_export_tar.c.

References internal_build_tar(), internal_direct_sink(), k_name_max, and RA8_PRIV.

Referenced by internal_export_dispatch().

◆ priv_mdl_export_tar_gzip()

ra8_err_t priv_mdl_export_tar_gzip	(	mdl_storage_t *	storage,
		const char *	dir,
		char	names[][k_name_max],
		size_t	count,
		mdl_export_output_t *	output,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws )

Write a gzip-wrapped CBT archive.

Streams deterministic ustar records directly through caller-arena DEFLATE into the active output; no intermediate archive exists.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in,out]	output	Active validated-publication output.
[in]	meta	Resolved metadata.
[in,out]	ws	Exclusive exporter workspace.

Returns: Writer status.

Return values

k_ra8_ok	A complete gzip stream was written.
k_ra8_err_invalid_size	A bound or workspace was exceeded.
k_ra8_fail	File or compression I/O failed.

Precondition: Paths and rows are valid and stable.; Workspace bytes remain live throughout the call.

Postcondition: No intermediate file is created.; Success includes the gzip checksum trailer.

Note: Not thread-safe for shared output or workspace.

Since: 0.1.0

Definition at line 436 of file mdl_export_tar.c.

References internal_gzip_sink_t::crc, internal_gzip_sink_t::error, internal_build_tar(), internal_gzip_put(), internal_gzip_sink(), internal_put_u32le(), k_gzip_deflate, k_gzip_header_bytes, k_gzip_id1, k_gzip_id2, k_gzip_os_unknown, k_gzip_u32_bytes, k_name_max, k_ra8_err_invalid_size, k_ra8_fail, k_ra8_ok, mdl_export_workspace_take(), priv_mdl_export_output_write(), RA8_PRIV, and internal_gzip_sink_t::size.

Referenced by internal_export_dispatch().

Variable Documentation

◆ s_ustar_magic

const uint8_t s_ustar_magic[k_len_magic] = {'u', 's', 't', 'a', 'r', '\0'}

static

Fixed ustar magic and version payloads.

Definition at line 85 of file mdl_export_tar.c.

Referenced by internal_tar_header().

◆ s_ustar_version

const uint8_t s_ustar_version[2] = {'0', '0'}

static

Definition at line 86 of file mdl_export_tar.c.

Referenced by internal_tar_header().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ mdl_gzip_header_t

◆ mdl_gzip_layout_t

◆ mdl_tar_layout_t

◆ mdl_tar_mode_t

◆ mdl_tar_size_t

Function Documentation

◆ internal_build_tar()

◆ internal_direct_sink()

◆ internal_gzip_put()

◆ internal_gzip_sink()

◆ internal_put_u32le()

◆ internal_round_block()

◆ internal_tar_header()

◆ internal_tar_write_memory()

◆ internal_tar_write_source()

◆ internal_write_zeros()

◆ priv_mdl_export_tar()

◆ priv_mdl_export_tar_gzip()

Variable Documentation

◆ s_ustar_magic

◆ s_ustar_version