mdl_export_rabook.c File Reference

Bounded fixed-layout EPUB-to-RBKC writer for media chapters. More...

#include <stddef.h>
#include <string.h>
#include "book.h"
#include "mdl_export_rabook_internal.h"
#include "miniz.h"
#include "ra8_rabook_container.h"
#include "ra8_rabook_pipeline.h"

Include dependency graph for mdl_export_rabook.c:

Go to the source code of this file.

Data Structures
struct	mdl_rabook_profile_t
	All fixed-profile views carved from the export workspace. More...

Enumerations
enum	mdl_rabook_profile_limit_t : uint32_t {   k_rabook_page_cap = 47U ,   k_rabook_chapter_cap = 48U ,   k_rabook_node_cap = 512U ,   k_rabook_attr_cap = 256U ,   k_rabook_style_cap = 4U ,   k_rabook_image_cap = 48U ,   k_rabook_string_bytes = 256U * 1024U ,   k_rabook_image_pool_bytes = 24U * 1024U * 1024U ,   k_rabook_flat_bytes = 26U * 1024U * 1024U ,   k_rabook_xhtml_bytes = 64U * 1024U ,   k_rabook_image_raw_bytes = 8U * 1024U * 1024U ,   k_rabook_image_arena_bytes = 20U * 1024U * 1024U ,   k_rabook_gray_bytes = 1024U * 1024U ,   k_rabook_css_bytes = 64U * 1024U ,   k_rabook_max_image_edge = 1024U ,   k_rabook_chunk_bytes = 1024U * 1024U ,   k_rabook_compressed_bytes = k_rabook_chunk_bytes + (64U * 1024U) ,   k_rabook_offset_entries = 64U }
	Fixed production conversion profile within the 96 MiB CLI arena. More...

Functions
static ra8_err_t	internal_allocate_builder (mdl_export_workspace_t *workspace, mdl_rabook_profile_t *profile)
	Allocate the builder tables and resident flat-book pools.
static ra8_err_t	internal_allocate_pipeline (mdl_export_workspace_t *workspace, mdl_rabook_profile_t *profile)
	Allocate the streamed EPUB parser and image-conversion scratch.
static ra8_err_t	internal_allocate_container (mdl_export_workspace_t *workspace, mdl_rabook_profile_t *profile)
	Allocate the independent-chunk RBKC writer workspace.
static ra8_err_t	internal_allocate_profile (mdl_export_workspace_t *workspace, mdl_rabook_profile_t *profile)
	Carve the complete fixed conversion profile from caller storage.
static ra8_err_t	internal_write_temp_epub (mdl_storage_t *storage, const char *directory, char names[][k_name_max], size_t count, const char *destination, const mdl_export_meta_t *meta, mdl_export_workspace_t *workspace, char *temp_path, bool *temp_exists)
	Produce and validate one private fixed-layout EPUB intermediate.
static ra8_err_t	internal_close_compile_sources (ra8_err_t error, epub_book_t *book, mdl_rabook_epub_source_t *source)
	Close both compile-time EPUB readers, preserving the first error.
static ra8_err_t	internal_check_compiled_page_count (const void *blob, size_t page_count)
	Confirm the compiled flat book matches the source page count.
static ra8_err_t	internal_compile_temp (mdl_storage_t *storage, const char *temp_path, size_t page_count, mdl_export_workspace_t *workspace, mdl_rabook_profile_t *profile, mdl_rabook_flat_source_t *flat)
	Compile one temporary EPUB into a validated resident flat RABOOK1.
static ra8_err_t	internal_emit_container (mdl_storage_t *storage, const char *destination, mdl_rabook_flat_source_t *flat, mdl_rabook_profile_t *profile, mdl_export_workspace_t *workspace)
	Stream one flat book into a strictly validated final RBKC transaction.
ra8_err_t	priv_mdl_export_rabook (mdl_storage_t *storage, const char *directory, char names[][k_name_max], size_t count, const char *destination, const mdl_export_meta_t *meta, mdl_export_workspace_t *workspace)
	Compile one page directory into a strict chunked RABOOK artifact.

Detailed Description

Bounded fixed-layout EPUB-to-RBKC writer for media chapters.

Reuses the production EPUB writer and firmware RABOOK compiler under one caller-owned 96 MiB profile, then strictly validates the staged RBKC container before atomic publication.

[Ring 4 / Domain] {World: NS}

Copyright

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

Since

0.1.0

Definition in file mdl_export_rabook.c.

Enumeration Type Documentation

mdl_rabook_profile_limit_t

enum mdl_rabook_profile_limit_t : uint32_t

Fixed production conversion profile within the 96 MiB CLI arena.

Enumerator
k_rabook_page_cap	EPUB manifest-safe page count.
k_rabook_chapter_cap	Builder chapter rows.
k_rabook_node_cap	Fixed-page XHTML DOM nodes.
k_rabook_attr_cap	Fixed-page XHTML attributes.
k_rabook_style_cap	Stylesheet descriptors.
k_rabook_image_cap	Pages plus one external cover.
k_rabook_string_bytes	Interned metadata/DOM strings.
k_rabook_image_pool_bytes	48 gray4 1024-square rasters.
k_rabook_flat_bytes	Flat RABOOK1 output.
k_rabook_xhtml_bytes	One page XHTML member.
k_rabook_image_raw_bytes	One encoded image member.
k_rabook_image_arena_bytes	One stb grayscale decode.
k_rabook_gray_bytes	1024-square downscale buffer.
k_rabook_css_bytes	One stylesheet member.
k_rabook_max_image_edge	Output raster long-edge clamp.
k_rabook_chunk_bytes	Independent RBKC chunk size.
k_rabook_compressed_bytes	One complete zlib stream.
k_rabook_offset_entries	RBKC offset table entries.

Definition at line 25 of file mdl_export_rabook.c.

Function Documentation

internal_allocate_builder()

ra8_err_t internal_allocate_builder ( mdl_export_workspace_t * workspace, mdl_rabook_profile_t * profile )

static

Allocate the builder tables and resident flat-book pools.

Carves each typed table and byte pool in declaration order, then publishes capacities only after every required span exists.

Parameters

[in,out]	workspace	Exclusive export arena.
[out]	profile	Profile receiving builder views.

Returns

Capacity status.

Return values

k_ra8_ok	Every builder arena was reserved.
k_ra8_err_invalid_size	The export arena is too small.

Precondition

Pointers are non-NULL and profile is zero-initialized.

workspace is exclusively mutable.

Postcondition

Success initializes every ra8_rabook_buffers_t member.

Failure publishes no usable builder profile.

Note

Allocations are monotonic and released only by workspace reset.

Since

0.1.0

Definition at line 72 of file mdl_export_rabook.c.

References ra8_rabook_buffers_t::attr_cap, ra8_rabook_buffers_t::attrs, mdl_rabook_profile_t::builder, ra8_rabook_buffers_t::chapter_cap, ra8_rabook_buffers_t::chapters, ra8_rabook_buffers_t::image_cap, ra8_rabook_buffers_t::image_pool, ra8_rabook_buffers_t::image_pool_cap, ra8_rabook_buffers_t::images, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_attr_cap, k_rabook_chapter_cap, k_rabook_flat_bytes, k_rabook_image_cap, k_rabook_image_pool_bytes, k_rabook_node_cap, k_rabook_string_bytes, k_rabook_style_cap, mdl_export_workspace_take(), ra8_rabook_buffers_t::node_cap, ra8_rabook_buffers_t::nodes, ra8_rabook_buffers_t::out, ra8_rabook_buffers_t::out_cap, RA8_INTERNAL, ra8_rabook_buffers_t::string_cap, ra8_rabook_buffers_t::string_pool, ra8_rabook_buffers_t::stylesheet_cap, and ra8_rabook_buffers_t::stylesheets.

Referenced by internal_allocate_profile().

internal_allocate_container()

ra8_err_t internal_allocate_container ( mdl_export_workspace_t * workspace, mdl_rabook_profile_t * profile )

static

Allocate the independent-chunk RBKC writer workspace.

Reserves one input chunk, one worst-case compressed stream, the miniz compressor object, and the bounded chunk-offset table.

Parameters

[in,out]	workspace	Exclusive export arena.
[out]	profile	Profile receiving container views.

Returns

Capacity status.

Return values

k_ra8_ok	Every container span was reserved.
k_ra8_err_invalid_size	The export arena is too small.

Precondition

Pointers are non-NULL and earlier profile allocations succeeded.

Container spans must remain non-overlapping and exclusively mutable.

Postcondition

Success initializes every container workspace member.

Failure publishes no usable container workspace.

Note

The offset table covers the fixed flat-output cap.

Since

0.1.0

Definition at line 180 of file mdl_export_rabook.c.

References ra8_rabook_container_workspace_t::compressed, ra8_rabook_container_workspace_t::compressed_cap, ra8_rabook_container_workspace_t::compressor, ra8_rabook_container_workspace_t::compressor_cap, mdl_rabook_profile_t::container, ra8_rabook_container_workspace_t::input, ra8_rabook_container_workspace_t::input_cap, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_chunk_bytes, k_rabook_compressed_bytes, k_rabook_offset_entries, mdl_export_workspace_take(), ra8_rabook_container_workspace_t::offset_cap, ra8_rabook_container_workspace_t::offsets, and RA8_INTERNAL.

Referenced by internal_allocate_profile().

internal_allocate_pipeline()

ra8_err_t internal_allocate_pipeline ( mdl_export_workspace_t * workspace, mdl_rabook_profile_t * profile )

static

Allocate the streamed EPUB parser and image-conversion scratch.

Reserves one reusable member buffer, stb arena, gray raster, CSS buffer, and XML workspace for the fixed grayscale compiler profile.

Parameters

[in,out]	workspace	Exclusive export arena.
[out]	profile	Profile receiving compiler views.

Returns

Capacity status.

Return values

k_ra8_ok	Every parser and raster arena was reserved.
k_ra8_err_invalid_size	The export arena is too small.

Precondition

Pointers are non-NULL and builder allocation already succeeded.

Profile and workspace remain exclusively mutable.

Postcondition

Success configures a gray4 1024-long-edge compiler profile.

Failure publishes no usable pipeline profile.

Note

The profile intentionally rejects larger source working sets.

Since

0.1.0

Definition at line 129 of file mdl_export_rabook.c.

References mdl_rabook_profile_t::book, mdl_rabook_profile_t::image_arena, k_book_pixfmt_gray4, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_css_bytes, k_rabook_gray_bytes, k_rabook_image_arena_bytes, k_rabook_image_raw_bytes, k_rabook_max_image_edge, k_rabook_xhtml_bytes, mdl_export_workspace_take(), memset(), mdl_rabook_profile_t::pipeline, and RA8_INTERNAL.

Referenced by internal_allocate_profile().

internal_allocate_profile()

ra8_err_t internal_allocate_profile ( mdl_export_workspace_t * workspace, mdl_rabook_profile_t * profile )

static

Carve the complete fixed conversion profile from caller storage.

Sequences builder, streamed-EPUB, raster, and RBKC reservations so later stages never allocate or silently reduce an earlier bound.

Parameters

[in,out]	workspace	Exclusive reset export arena.
[out]	profile	Complete profile on success.

Returns

First builder, pipeline, or container capacity failure.

Return values

k_ra8_ok	The complete fixed profile fits.
k_ra8_err_invalid_size	A required span does not fit.

Precondition

Pointers are non-NULL and workspace has used equal to zero.

profile is exclusively writable.

Postcondition

Success leaves all profile pointers within the caller arena.

Failure never falls back to dynamic allocation.

Note

The caller may inspect workspace high-water after the operation.

Since

0.1.0

Definition at line 221 of file mdl_export_rabook.c.

References internal_allocate_builder(), internal_allocate_container(), internal_allocate_pipeline(), k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_compile_temp().

internal_check_compiled_page_count()

ra8_err_t internal_check_compiled_page_count ( const void * blob, size_t page_count )

static

Confirm the compiled flat book matches the source page count.

Compares the RABOOK1 chapter and image counts against the source EPUB's expected page count, tolerating exactly one synthesized cover image beyond the page count.

Parameters

[in]	blob	Validated RABOOK1 buffer (already passed book_validate).
[in]	page_count	Expected source spine/image minimum.

Returns

Whether the compiled counts fall within the expected range.

Return values

k_ra8_ok	Chapter and image counts both match expectations.
k_ra8_err_validation_failed	A page or image was lost or added.

Precondition

blob has already passed book_validate.

page_count is representable as a uint32_t.

Postcondition

No state is mutated; only blob's header is read.

No diagnostic is emitted; the returned status is the only report.

Note

Not thread-safe against a concurrent writer of blob.

Since

0.1.0

Definition at line 348 of file mdl_export_rabook.c.

References book_header(), book_header_t::chapter_count, book_header_t::image_count, k_ra8_err_validation_failed, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_compile_temp().

internal_close_compile_sources()

ra8_err_t internal_close_compile_sources ( ra8_err_t error, epub_book_t * book, mdl_rabook_epub_source_t * source )

static

Close both compile-time EPUB readers, preserving the first error.

Closes the resident streamed book view first, then the portable EPUB source reader, regardless of any prior pipeline failure. A close failure only replaces error when the pipeline had otherwise succeeded, so the earliest real failure always wins.

Parameters

[in]	error	Status accumulated by the compile pipeline before this close step; k_ra8_ok if every prior step succeeded.
[in,out]	book	Resident streamed EPUB view; closed only if in use.
[in,out]	source	Portable EPUB source reader; closed only if open.

Returns

The first non-ok status among error and both close calls.

Return values

k_ra8_ok	Every prior step and both closes succeeded.
other	The first failure among error and the two closes.

Precondition

book and source describe the same compile-time EPUB.

Both readers are safe to close exactly once from this call.

Postcondition

Both readers are closed regardless of the returned status.

error is never weakened: an existing failure survives an independent close failure on either reader.

Note

Not thread-safe; the caller retains exclusive ownership of both readers for the duration of this call.

Since

0.1.0

Definition at line 312 of file mdl_export_rabook.c.

References epub_close(), mdl_rabook_epub_source_t::file, epub_book_t::in_use, fw_fs_file_t::is_open, k_ra8_ok, and priv_mdl_rabook_epub_close().

Referenced by internal_compile_temp().

internal_compile_temp()

ra8_err_t internal_compile_temp ( mdl_storage_t * storage, const char * temp_path, size_t page_count, mdl_export_workspace_t * workspace, mdl_rabook_profile_t * profile, mdl_rabook_flat_source_t * flat )

static

Compile one temporary EPUB into a validated resident flat RABOOK1.

Opens the EPUB through portable random reads, invokes the production compiler, closes both readers, and checks exact page/image counts.

Parameters

[in,out]	storage	Exclusive portable storage binding.
[in]	temp_path	Canonical validated EPUB path.
[in]	page_count	Expected spine/image minimum.
[in,out]	workspace	Reset caller export arena.
[out]	profile	Complete retained compiler/container profile.
[out]	flat	Resident flat-book source view.

Returns

Open, compiler, close, or structural status.

Return values

k_ra8_ok	A valid flat book has exact chapter and image counts.
k_ra8_err_validation_failed	Compiler output lost or added a page image.

Precondition

Pointers are non-NULL and the temporary EPUB is immutable.

workspace is exclusively mutable and large enough for the profile.

Postcondition

Success initializes flat within workspace.

Every opened EPUB and portable source is closed on return.

Note

The retained profile remains valid until workspace reset.

Since

0.1.0

Definition at line 380 of file mdl_export_rabook.c.

References mdl_rabook_profile_t::book, book_validate(), mdl_rabook_profile_t::builder, epub_open_streamed(), mdl_rabook_epub_source_t::error, internal_allocate_profile(), internal_check_compiled_page_count(), internal_close_compile_sources(), k_ra8_ok, mdl_rabook_profile_t::pipeline, priv_mdl_rabook_epub_open(), priv_mdl_rabook_epub_read(), RA8_INTERNAL, rabook_compile_from_epub_to_buffer(), mdl_rabook_epub_source_t::size_bytes, and mdl_export_workspace::used.

Referenced by priv_mdl_export_rabook().

internal_emit_container()

ra8_err_t internal_emit_container ( mdl_storage_t * storage, const char * destination, mdl_rabook_flat_source_t * flat, mdl_rabook_profile_t * profile, mdl_export_workspace_t * workspace )

static

Stream one flat book into a strictly validated final RBKC transaction.

Feeds the resident RABOOK1 blob through independent zlib chunks and relies on the shared transaction verifier before atomic publication.

Parameters

[in,out]	storage	Exclusive portable storage binding.
[in]	destination	Canonical final RABOOK path.
[in]	flat	Resident validated flat-book source.
[in,out]	profile	Retained container workspace.
[in,out]	workspace	Export/strict-validation arena.

Returns

Container write, validation, or publication status.

Return values

k_ra8_ok	A complete strict RBKC artifact was published.
other	A transaction, compressor, validator, commit, or abort error.

Precondition

All pointers are non-NULL and profile spans remain alive.

No temporary source file remains open.

Postcondition

Failure before publication preserves an existing destination.

Success publishes exactly one reader-openable .rabook file.

Note

Power-loss durability follows the injected transaction backend.

Since

0.1.0

Definition at line 443 of file mdl_export_rabook.c.

References fw_fs_transaction_t::active, mdl_rabook_profile_t::container, mdl_export_output_t::extent, k_mdl_format_rabook, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_chunk_bytes, priv_mdl_export_output_abort(), priv_mdl_export_output_begin(), priv_mdl_export_output_commit(), priv_mdl_export_output_write_at(), priv_mdl_rabook_flat_read(), RA8_INTERNAL, ra8_rabook_container_write(), mdl_rabook_flat_source_t::size_bytes, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by priv_mdl_export_rabook().

internal_write_temp_epub()

ra8_err_t internal_write_temp_epub ( mdl_storage_t * storage, const char * directory, char names[][k_name_max], size_t count, const char * destination, const mdl_export_meta_t * meta, mdl_export_workspace_t * workspace, char * temp_path, bool * temp_exists )

static

Produce and validate one private fixed-layout EPUB intermediate.

Uses create-new sibling naming, the production EPUB writer, and its strict transaction verifier before exposing the intermediate path.

Parameters

[in,out]	storage	Exclusive portable storage binding.
[in]	directory	Canonical source chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in]	destination	Final path used to salt the private name.
[in]	meta	Resolved metadata.
[in,out]	workspace	Export/validation arena.
[out]	temp_path	Chosen canonical intermediate path.
[out]	temp_exists	Whether a committed temporary file must be removed.

Returns

EPUB write, validation, or publication status.

Return values

k_ra8_ok	A strictly validated temporary EPUB is visible.
other	A create, write, validate, commit, or abort error propagated.

Precondition

All pointers and rows are valid and stable.

The storage transaction workspace is free.

Postcondition

Success sets temp_exists true and names the temporary EPUB.

Failure reports truthful publication state for cleanup.

Note

The final destination is never modified here.

Since

0.1.0

Definition at line 258 of file mdl_export_rabook.c.

References fw_fs_transaction_t::active, k_fw_fs_path_cap, k_name_max, k_ra8_ok, priv_mdl_export_epub(), priv_mdl_export_output_abort(), priv_mdl_export_output_commit(), priv_mdl_rabook_temp_begin(), RA8_INTERNAL, mdl_storage_txn_t::transaction, and mdl_export_output_t::writer.

Referenced by priv_mdl_export_rabook().

priv_mdl_export_rabook()

ra8_err_t priv_mdl_export_rabook	(	mdl_storage_t *	storage,
		const char *	directory,
		char	names[][k_name_max],
		size_t	count,
		const char *	destination,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	workspace )

Compile one page directory into a strict chunked RABOOK artifact.

Produces a private fixed-layout EPUB with the production writer, compiles it through the firmware RABOOK1 pipeline, wraps the flat blob as independent RBKC chunks, and validates the complete staged artifact before atomic publication.

Parameters

[in,out]	storage	Injected portable storage and transaction provider.
[in]	directory	Canonical chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count within the fixed RABOOK profile.
[in]	destination	Canonical final .rabook path.
[in]	meta	Resolved metadata to embed.
[in,out]	workspace	Exclusive caller-owned export/compiler workspace.

Returns

Writer, compiler, validator, or publication status.

Return values

k_ra8_ok	One strict RBKC artifact was published.
k_ra8_err_invalid_size	A page/profile/workspace bound was exceeded.
k_ra8_err_validation_failed	An intermediate or final artifact failed validation.

Precondition

All pointers and page rows are valid and stable for the complete call.

ws is exclusively mutable and no competing writer owns the destination.

Postcondition

Success publishes exactly one reader-openable RABOOK artifact.

Failure removes private intermediates and preserves any prior destination.

Note

Not thread-safe for shared storage, destination, or workspace.

Since

0.1.0

Definition at line 475 of file mdl_export_rabook.c.

References mdl_storage_t::fs, fw_fs_unlink(), internal_compile_temp(), internal_emit_container(), internal_write_temp_epub(), k_fw_fs_path_cap, k_name_max, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_page_cap, fw_fs_t::names, and RA8_PRIV.

Referenced by mdl_export_chapter_meta_ws().