rabook_import.h File Reference

On-import EPUB -> .rabook compile-and-cache manager (#151). More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_fs.h"

Include dependency graph for rabook_import.h:

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

Go to the source code of this file.

Data Structures
struct	rabook_import_stamp_t
	Body of the sidecar freshness marker (<name>.rabook.mrk). More...
struct	rabook_import_cfg_t
	Injected dependencies + versioning for rabook_import_open. More...

Typedefs
typedef ra8_err_t(*	rabook_import_compile_fn) (void *compile_ctx, ra8_fs_mount_t *mount, const char *epub_path, const char *out_path)
	Dependency-injection seam: compile one EPUB into a .rabook blob.

Enumerations
enum	rabook_import_size_t : uint16_t {   k_rabook_import_name_cap = 128U ,   k_rabook_import_stamp_bytes = 20U }
	Fixed sizing constants for the cache-name layout. More...
enum	rabook_import_magic_t : uint32_t { k_rabook_import_stamp_magic = 0x52424B31U }
	Sentinel stamped into the freshness marker so a stray file is rejected. More...
enum	rabook_import_outcome_t : uint8_t {   k_rabook_import_hit = 0U ,   k_rabook_import_compiled = 1U }
	How rabook_import_open satisfied the request. More...

Functions
ra8_err_t	rabook_import_open (const rabook_import_cfg_t *cfg, const char *epub_path, char *out_cache_path, uint32_t cache_path_cap, rabook_import_outcome_t *out_outcome)
	Resolve a source .epub to a fresh cached .rabook, compiling once.

Detailed Description

On-import EPUB -> .rabook compile-and-cache manager (#151).

rabook_import makes the e-reader a self-contained appliance: drop a raw .epub on the SD card and the first open compiles it once into the flat, execute-in-place .rabook blob (via the injected compiler seam), caches the result on the card, and takes the fast cached path on every subsequent open.

This header is the cache manager + import state machine only. It owns:

• the on-disk cache convention (the source's own name, e.g. a .epub basename with .rabook cache + .rabook.mrk freshness marker beside it, now that ra8_fs writes VFAT long names – #600/#633),
• the freshness / staleness gate (a sidecar marker that stores the source size + CRC-32, the .rabook format version, and an importer version – any mismatch forces a re-derive),
• the compile-on-miss + write-through path with a crash-safe temp+rename,
• read-through on a hit (the cached .rabook is reused without recompiling).

Dependency-inversion seam

The actual EPUB -> RABOOK1 compile is reached only through the injected rabook_import_compile_fn function pointer, and the filesystem only through ra8_fs_mount_t. The manager itself depends on nothing but ra8_fs and ra8_core, so it is host-testable with a lightweight compile spy (no EPUB parser, no image decoder, no 24 MiB arenas). Production wires the real rabook_compile_from_epub behind the seam – see rabook_import_compiler.h for the supplied adapter.

Crash safety

The miss path writes <name>.rabook.tmp (temp), then atomically renames it over <name>.rabook, then writes the marker. A power loss mid-import leaves at most a stale temp (cleaned on the next retry) and never a half-written cache; the .rabook body CRC-32 (checked by book_open) is a second line of defence. The source .epub is never modified or deleted.

Note

Not thread-safe: one import at a time on the single reader core.

See also

rabook_import_compiler.h Production adapter onto the real compiler.

ra8_fs.h Filesystem the cache lives on.

Copyright

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

Since

Version 0.1.0

[Ring 4 / EPUB Import] {World: NS}

Definition in file rabook_import.h.

Typedef Documentation

rabook_import_compile_fn

typedef ra8_err_t(* rabook_import_compile_fn) (void *compile_ctx, ra8_fs_mount_t *mount, const char *epub_path, const char *out_path)

Dependency-injection seam: compile one EPUB into a .rabook blob.

The manager calls this on a cache miss to produce the bare RABOOK1 body at out_path. Production binds the real rabook_compile_from_epub (through the supplied adapter); host tests bind a spy that records the call count.

Parameters

[in]	compile_ctx	Opaque cookie supplied in the config; carries the EPUB handle + builder arenas in production.
[in,out]	mount	Mounted volume holding the source and the output.
[in]	epub_path	Root-level path of the source .epub.
[in]	out_path	Root-level path to write the .rabook body to (the manager passes a temp name, then renames it).

Returns

k_ra8_ok on success; any non-zero ra8_err_t aborts the import and the manager falls back without touching the cache.

Since

Version 0.1.0

Definition at line 143 of file rabook_import.h.

Enumeration Type Documentation

rabook_import_magic_t

enum rabook_import_magic_t : uint32_t

Sentinel stamped into the freshness marker so a stray file is rejected.

A marker that does not start with this tag (e.g. a same-named file left by another tool, or a torn write) is treated as absent and the book is re-derived.

Since

Version 0.1.0

Enumerator
k_rabook_import_stamp_magic	Importer marker tag "RBK1".

Definition at line 84 of file rabook_import.h.

rabook_import_outcome_t

enum rabook_import_outcome_t : uint8_t

How rabook_import_open satisfied the request.

Since

Version 0.1.0

Enumerator
k_rabook_import_hit	Fresh cache reused; the compiler was NOT invoked.
k_rabook_import_compiled	Miss/stale; the book was compiled and cached.

Definition at line 93 of file rabook_import.h.

rabook_import_size_t

enum rabook_import_size_t : uint16_t

Fixed sizing constants for the cache-name layout.

The cache entry is named after the SOURCE'S OWN name – the .epub basename with .rabook (cache), .rabook.tmp (crash-safe temp) or .rabook.mrk (freshness marker) appended – now that ra8_fs writes VFAT long names (#600/#633). The CRC-32 still keys freshness inside the marker, but no longer names the file. k_rabook_import_name_cap bounds the derivation onto fixed buffers; a source whose derived name does not fit is refused rather than truncated.

Since

Version 0.1.0

Enumerator
k_rabook_import_name_cap	Cache/temp/marker name buffer bytes incl. NUL.
k_rabook_import_stamp_bytes	Pinned size of the freshness stamp.

Definition at line 71 of file rabook_import.h.

Function Documentation

rabook_import_open()

ra8_err_t rabook_import_open ( const rabook_import_cfg_t * cfg, const char * epub_path, char * out_cache_path, uint32_t cache_path_cap, rabook_import_outcome_t * out_outcome )

nodiscard

Resolve a source .epub to a fresh cached .rabook, compiling once.

State machine on "open `epub_path`":

1. Derive the cache names from the source's own basename: <name>.rabook (cache), <name>.rabook.tmp (temp) and <name>.rabook.mrk (marker).
2. Stream the source bytes through CRC-32 to derive (size, crc); the crc keys the freshness stamp (not the file name), so a content change under the same source name still forces a re-derive.
3. If the marker <name>.rabook.mrk matches the expected stamp AND the cache file is present -> hit: emit the cache path, do not invoke compile.
4. Otherwise -> miss/stale: clear any stale temp, call compile to <name>.rabook.tmp, atomically rename it over <name>.rabook, write the fresh marker, and emit the cache path.

Parameters

[in]	cfg	Injected dependencies + versioning (see struct).
[in]	epub_path	Root-level path of the source .epub.
[out]	out_cache_path	Receives the NUL-terminated cache .rabook path the caller then opens with book_open.
[in]	cache_path_cap	Capacity of out_cache_path in bytes; must hold the derived <name>.rabook name and its terminator.
[out]	out_outcome	Receives k_rabook_import_hit or k_rabook_import_compiled on success.

Returns

Error code.

Return values

k_ra8_ok	Cache is fresh (hit) or freshly written (compiled).
k_ra8_err_null_ptr	A required pointer (incl. an injected dependency) is NULL.
k_ra8_err_invalid_arg	epub_path has no usable basename.
k_ra8_err_invalid_size	cache_path_cap is too small for the derived name, the derived name overflows the fixed buffer, or scratch_cap is zero.
k_ra8_err_not_found	The source .epub does not exist.
k_ra8_err_*	Propagated filesystem or compiler error (on a compile error the cache is left untouched).

Precondition

cfg, epub_path, out_cache_path, and out_outcome are non-NULL.

cfg->mount, cfg->compile, and cfg->scratch are non-NULL.

Postcondition

On k_ra8_ok, out_cache_path is a NUL-terminated path to a present cache file and *out_outcome records hit vs compiled.

On any error the source .epub is unmodified and no half cache remains.

Note

Not thread-safe; callers serialise imports.

See also

rabook_import_compiler.h

Since

Version 0.1.0

Definition at line 806 of file rabook_import.c.

References rabook_import_cfg_t::format_version, rabook_import_cfg_t::importer_version, internal_cache_is_fresh(), internal_compile_and_cache(), internal_compute_source_key(), internal_copy_name(), internal_derive_names(), internal_derive_stem(), internal_file_exists(), internal_validate_open_args(), k_ra8_err_invalid_size, k_ra8_ok, k_rabook_import_compiled, k_rabook_import_hit, k_rabook_import_name_cap, k_rabook_import_stamp_magic, rabook_import_cfg_t::mount, rabook_import_cfg_t::scratch, rabook_import_cfg_t::scratch_cap, and strlen().

Referenced by imp_run().