Test-access surface for epub internal helpers (MC/DC). More...

#include <stddef.h>
#include <stdint.h>
#include "epub.h"
#include "miniz.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for epub_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
size_t	priv_epub_mem_read (void ctx, uint64_t offset, void buf, size_t len)
	Read one bounded span from resident EPUB media.
void	priv_epub_dirname (const char path, char dst, size_t cap)
	Copy the directory prefix of an EPUB package path.
size_t	priv_epub_stream_read (void opaque, mz_uint64 file_ofs, void buf, size_t n)
	Forward one bounded miniz read to streamed EPUB media.
ra8_err_t	priv_epub_finish_open (mz_zip_archive zip, epub_book_t out_book)
	Finish parsing one initialized ZIP reader into an EPUB book.
ra8_err_t	priv_epub_set_miniz_alloc (mz_zip_archive zip, epub_book_t book)
	Bind one ZIP reader to a book's caller-owned miniz arena.
void	priv_epub_join_path (const char dir, const char name, char *dst, size_t cap)
	Concatenate dir and name into dst, NUL-terminated.
bool	priv_epub_glyph_dim_invalid (int w, int h)
	Pure predicate: width OR height is negative.
bool	priv_epub_book_not_ready (uint8_t in_use, uint8_t zip_archive_active)
	Pure predicate: book unused OR zip archive inactive.
ra8_err_t	priv_epub_zip_guard_archive (mz_zip_archive *zip)
	Guard a just-opened ZIP archive against the decompression policy.
ra8_err_t	priv_epub_zip_guard_entry (const mz_zip_archive_file_stat *st)
	Guard one ZIP entry's declared sizes against the policy.

Detailed Description

Test-access surface for epub internal helpers (MC/DC).

Not part of the public API. Tests under tests/ MAY include this header to drive compound boolean decisions that sit in TU-private helpers behind the public epub facade. See CLAUDE.md "Test access to internal symbols (MC/DC scope)".

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

Definition in file epub_internal.h.

Function Documentation

◆ priv_epub_book_not_ready()

bool priv_epub_book_not_ready	(	uint8_t	in_use,
		uint8_t	zip_archive_active )

Pure predicate: book unused OR zip archive inactive.

Promoted from the inline OR at apps/shared_libs/epub/src/epub_chapter.c lines 300 and 369 (inside epub_load_chapter and epub_get_cover_image / epub_get_metadata).

Parameters

[in]	in_use	book->in_use byte (0 == unused).
[in]	zip_archive_active	book->zip_archive_active byte (0 == inactive).

Returns: Boolean reject predicate.

Return values

true	Caller must return `k_ra8_err_not_initialized`.
false	Book is ready.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the two inputs.

Note: Test-access only. Pure function.

MC/DC:

2-condition OR; N+1 = 3 vectors:

in_use=1, zip=1 -> false
in_use=0, zip=1 -> true (varies left)
in_use=1, zip=0 -> true (varies right)

Since: 0.1.0

Pure predicate: book unused OR zip archive inactive.

Promoted helper so the line-300/369 OR can be driven under MC/DC.

Parameters

[in]	in_use	Book "in_use" byte.
[in]	zip_archive_active	Book "zip_archive_active" byte.

Returns: Boolean reject predicate.

Return values

true	Caller returns not-initialized.
false	Book is ready.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 97 of file epub_chapter.c.

References RA8_PRIV.

Referenced by epub_entry_open(), epub_entry_pread(), epub_get_cover_image(), epub_get_embedded_font(), epub_get_resource(), and epub_load_chapter().

◆ priv_epub_dirname()

void priv_epub_dirname	(	const char *	path,
		char *	dst,
		size_t	cap )

Copy the directory prefix of an EPUB package path.

Test-access form of the helper used while binding the OPF base directory. Production callers keep using the public EPUB facade.

Parameters

[in]	path	NUL-terminated package path.
[out]	dst	Destination for the directory prefix.
[in]	cap	Capacity of `dst`.

Precondition: When non-null, path points to a NUL-terminated string.; A nonzero cap means dst is writable for cap bytes.

Postcondition: A destination with nonzero capacity is NUL-terminated.; A null destination or zero capacity causes no write.

Note: Test-access only and not thread-safe; performs no allocation.

MC/DC:: The destination-null / zero-capacity OR has one-invalid-at-a-time and all-valid vectors in test_epub_open.c.

Since: 0.1.0

Definition at line 115 of file epub_open.c.

References internal_byte_copy(), and RA8_PRIV.

Referenced by internal_parse_archive().

◆ priv_epub_finish_open()

ra8_err_t priv_epub_finish_open	(	mz_zip_archive *	zip,
		epub_book_t *	out_book )

Finish parsing one initialized ZIP reader into an EPUB book.

Test-access form of the common resident/streamed open tail. Production callers keep using epub_open or epub_open_streamed.

Parameters

[in,out]	zip	Initialized miniz reader.
[in,out]	out_book	Zeroed destination book.

Returns: Parse result or argument-validation error.

Return values

k_ra8_ok	The archive parsed and the book became live.
k_ra8_err_null_ptr	One required object was null.
k_ra8_err_decomp_entries	The archive exceeded the entry-count policy.
k_ra8_err_decomp_output_cap	An entry exceeded the output-size policy.
k_ra8_err_decomp_ratio	An entry exceeded the compression-ratio policy.
k_ra8_err_not_found	A required EPUB package entry was absent.
k_ra8_err_no_mem	A required entry or spine exceeded fixed storage.
k_ra8_err_invalid_size	A required XML document was empty.
k_ra8_err_validation_failed	The archive or package metadata was invalid.

Precondition: When non-null, zip is an initialized miniz reader.; When non-null, out_book points to zeroed writable storage.

Postcondition: Success marks out_book live.; A parse failure destroys the ZIP reader without marking the book live.

Note: Test-access only; not thread-safe because parsing uses shared scratch.

MC/DC:: The ZIP-null / book-null OR has one-null-at-a-time vectors in test_epub_open.c and all-valid vectors in test_epub_open_cov.c.

Since: 0.1.0

Definition at line 374 of file epub_open.c.

References epub_book_t::in_use, internal_parse_archive(), internal_zip_destroy(), k_epub_opf_xml_buf, k_ra8_err_null_ptr, k_ra8_ok, priv_epub_zip_guard_archive(), RA8_PRIV, and epub_book_t::zip_archive_active.

Referenced by epub_open(), and epub_open_streamed().

◆ priv_epub_glyph_dim_invalid()

bool priv_epub_glyph_dim_invalid	(	int	w,
		int	h )

Pure predicate: width OR height is negative.

Promoted from the inline OR at apps/shared_libs/epub/src/epub_chapter.c inside internal_font_init.

Parameters

[in]	w	Glyph bbox width.
[in]	h	Glyph bbox height.

Returns: Boolean reject predicate.

Return values

true	Caller must return `k_ra8_err_validation_failed`.
false	Both dimensions are non-negative.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the two inputs.

Note: Test-access only. Pure function.

MC/DC:

2-condition OR; N+1 = 3 vectors:

w>=0, h>=0 -> false
w<0, h>=0 -> true (varies left)
w>=0, h<0 -> true (varies right)

Since: 0.1.0

Pure predicate: width OR height is negative.

Promoted helper so the line-225 OR can be driven under MC/DC.

Parameters

[in]	w	Glyph bbox width.
[in]	h	Glyph bbox height.

Returns: Boolean reject predicate.

Return values

true	Caller returns validation-failed.
false	Both dimensions OK.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 77 of file epub_chapter.c.

References RA8_PRIV.

Referenced by internal_render_into().

◆ priv_epub_join_path()

void priv_epub_join_path	(	const char *	dir,
		const char *	name,
		char *	dst,
		size_t	cap )

Concatenate dir and name into dst, NUL-terminated.

Promoted from TU-private static linkage so tests can drive its line-76, line-82, line-89 compound decisions on the production source under -fcoverage-mcdc. Production callers MUST keep using the public epub facade.

Parameters

[in]	dir	Optional directory prefix (NUL-terminated, may be NULL).
[in]	name	Optional name suffix (NUL-terminated, may be NULL).
[out]	dst	Destination buffer (may be NULL when cap is 0).
[in]	cap	Capacity of dst in bytes.

Precondition: cap == 0 implies dst may be NULL.; cap > 0 implies dst is non-NULL and writeable for cap bytes.

Postcondition: dst is NUL-terminated when cap > 0.; No more than (cap - 1) bytes written from inputs.

Note: Test-access only.

MC/DC:: Drives the line-76 (dst == NULL || cap == 0U) OR and the two loop ANDs at lines 82 and 89.

Since: 0.1.0

Concatenate dir and name into dst, NUL-terminated.

Joins two NUL-terminated path components into the caller-supplied buffer with bounded length.

Parameters

[in]	dir	Directory prefix (may be NULL).
[in]	name	Name suffix (may be NULL).
[out]	dst	Destination buffer.
[in]	cap	Capacity of `dst` in bytes.

Precondition: cap == 0 implies dst may be NULL.; cap > 0 implies dst is non-NULL and writeable.

Postcondition: dst is NUL-terminated when cap > 0.; No more than (cap - 1) bytes written from inputs.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 118 of file epub_chapter.c.

References RA8_PRIV.

Referenced by epub_get_cover_image(), epub_get_embedded_font(), epub_get_resource(), epub_load_chapter(), internal_load_toc(), and internal_locate().

◆ priv_epub_mem_read()

size_t priv_epub_mem_read	(	void *	ctx,
		uint64_t	offset,
		void *	buf,
		size_t	len )

Read one bounded span from resident EPUB media.

Test-access form of the callback used by the resident ZIP and decompression preflight paths; production callers keep using the public EPUB facade.

Parameters

[in]	ctx	Bound epub_mem_media_t descriptor.
[in]	offset	Absolute archive offset.
[out]	buf	Destination for exactly `len` bytes.
[in]	len	Requested byte count.

Returns: Number of bytes copied, or zero when any guard rejects the request.

Return values

0	One guard rejected the request.
len	Exactly the requested bytes were copied.

Precondition: Non-null arguments address their documented extents.; The resident media outlives the call.

Postcondition: Success copies exactly len bytes.; Rejection does not modify the destination.

Note: Test-access only; performs no allocation.

MC/DC:: The four-condition OR rejects null media, null output, an offset past the archive, and a length beyond the remaining suffix. Its N+1 vectors are in test_epub_chapter.c.

Since: 0.1.0

Definition at line 83 of file epub_open.c.

References epub_mem_media_t::data, internal_byte_copy(), RA8_PRIV, and epub_mem_media_t::size.

Referenced by epub_open().

◆ priv_epub_set_miniz_alloc()

ra8_err_t priv_epub_set_miniz_alloc	(	mz_zip_archive *	zip,
		epub_book_t *	book )

Bind one ZIP reader to a book's caller-owned miniz arena.

Test-access form of the shared resident/streamed open helper. It initializes the embedded arena and installs all three allocation callbacks plus their opaque context.

Parameters

[in,out]	zip	Zeroed archive descriptor to configure.
[in,out]	book	Book owning the arena and workspace.

Returns: Arena initialization or argument-validation status.

Return values

k_ra8_ok	The arena and callbacks were installed.
k_ra8_err_null_ptr	One required object was null.

Precondition: Non-null objects are writable and distinct.; zip has not entered a miniz reader mode.

Postcondition: Success binds every allocator callback to book.; Null rejection mutates neither candidate object.

Note: Test-access only; the public EPUB ABI is unchanged.

MC/DC:: The two-condition null OR has one-null-at-a-time and all-valid vectors in test_epub_chapter.c.

Since: 0.1.0

Definition at line 342 of file epub_open.c.

References epub_miniz_workspace_t::bytes, epub_miniz_alloc(), epub_miniz_arena_init(), epub_miniz_free(), epub_miniz_realloc(), k_ra8_err_null_ptr, k_ra8_ok, epub_book_t::miniz_arena, epub_book_t::miniz_workspace, and RA8_PRIV.

Referenced by epub_open(), and epub_open_streamed().

◆ priv_epub_stream_read()

size_t priv_epub_stream_read	(	void *	opaque,
		mz_uint64	file_ofs,
		void *	buf,
		size_t	n )

Forward one bounded miniz read to streamed EPUB media.

Test-access form of the callback installed in a streamed ZIP reader. Production callers use epub_open_streamed.

Parameters

[in]	opaque	Bound epub_stream_media_t descriptor.
[in]	file_ofs	Absolute archive offset.
[out]	buf	Destination for up to `n` bytes.
[in]	n	Requested byte count.

Returns: Number of bytes supplied by the media callback, or zero on rejection.

Return values

0	The descriptor or callback was null, or the offset reached EOF.
n	The backing callback supplied the full bounded request.
<n	The backing callback supplied a short read.

Precondition: When non-null, opaque points to a live epub_stream_media_t.; When non-null, buf is writable for n bytes.

Postcondition: At most n bytes are written to buf.; A null descriptor or callback does not invoke backing media.

Note: Test-access only and not thread-safe; performs no allocation.

MC/DC:: The descriptor-null / callback-null OR has one-null-at-a-time and all-valid vectors in test_epub_open.c.

Since: 0.1.0

Definition at line 360 of file epub_open.c.

References epub_stream_media_t::ctx, RA8_PRIV, epub_stream_media_t::read, and epub_stream_media_t::size.

Referenced by epub_open_streamed().

◆ priv_epub_zip_guard_archive()

ra8_err_t priv_epub_zip_guard_archive ( mz_zip_archive * zip )

nodiscard

Guard a just-opened ZIP archive against the decompression policy.

The archive-level half of the unified decompression-limits retrofit (ra8_decomp_limits.h): rejects an archive whose central directory enumerates more entries than the default policy's max_entries – the many-tiny-entries resource bomb – before any entry is touched. Called once per mz_zip_reader_init* success (both the in-memory and streamed open paths funnel through priv_epub_finish_open).

Parameters

[in] zip Initialised miniz reader (non-NULL).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The entry count is within policy.
k_ra8_err_null_ptr	`zip` was NULL.
k_ra8_err_decomp_entries	The central directory exceeds the cap.

Precondition: zip was initialised by an mz_zip_reader_init* call.; The default decompression policy is in force (no per-book override).

Postcondition: No archive state is modified (pure count check).; On breach the caller must destroy the reader (fail-closed).

Note: Thread-safe: pure read of the reader's entry count.

See also: priv_epub_zip_guard_entry()

Since: 0.1.0

Definition at line 40 of file epub_zip_guard.c.

References k_ra8_err_decomp_entries, k_ra8_ok, ra8_decomp_limits_t::max_entries, RA8_CHECK_NULL_PTR, ra8_decomp_limits_default(), RA8_PRIV, and s_tag_zip_guard.

Referenced by priv_epub_finish_open().

◆ priv_epub_zip_guard_entry()

ra8_err_t priv_epub_zip_guard_entry ( const mz_zip_archive_file_stat * st )

nodiscard

Guard one ZIP entry's declared sizes against the policy.

The entry-level half of the retrofit: rejects an entry whose central-directory record declares an uncompressed size over the default policy's per-unit output cap, or over the compression-ratio bound relative to its compressed size (the lying-header / decompression-bomb signatures) – before any inflation starts. Called after every successful mz_zip_reader_file_stat that precedes an extraction.

Parameters

[in] st The entry's stat record (non-NULL).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Declared sizes are within policy.
k_ra8_err_null_ptr	`st` was NULL.
k_ra8_err_decomp_output_cap	Declared output exceeds the cap.
k_ra8_err_decomp_ratio	Declared output breaks the ratio.

Precondition: st came from a successful mz_zip_reader_file_stat.; The default decompression policy is in force.

Postcondition: No state is modified (pure check).; On breach the caller must not extract the entry (fail-closed).

Note: Thread-safe: pure read.

See also: priv_epub_zip_guard_archive()

Since: 0.1.0

Definition at line 51 of file epub_zip_guard.c.

References RA8_CHECK_NULL_PTR, ra8_decomp_check_declared(), ra8_decomp_limits_default(), RA8_PRIV, and s_tag_zip_guard.

Referenced by internal_extract(), internal_locate_extract(), internal_open_iter(), and internal_stored_data_offset().

Functions

Detailed Description

Function Documentation

◆ priv_epub_book_not_ready()

◆ priv_epub_dirname()

◆ priv_epub_finish_open()

◆ priv_epub_glyph_dim_invalid()

◆ priv_epub_join_path()

◆ priv_epub_mem_read()

◆ priv_epub_set_miniz_alloc()

◆ priv_epub_stream_read()

◆ priv_epub_zip_guard_archive()

◆ priv_epub_zip_guard_entry()