mdl_state_internal.h File Reference

Module-private validation shared by the state model and codec. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_state.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_state_internal.h:

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

Go to the source code of this file.

Enumerations
enum	mdl_state_internal_limit_t : uint16_t { k_mdl_state_line_max }
	Largest complete serialized record including its terminator. More...

Functions
void	priv_mdl_state_set_opt (char *dst, size_t cap, const char *val)
	Copy one optional value into a bounded state field.
bool	priv_mdl_state_field_valid (const char *text, size_t cap)
	Validate one delimiter-free bounded state field.
bool	priv_mdl_state_relative_path_valid (const char *path, size_t cap)
	Validate a bounded relative path stored in state.
bool	priv_mdl_state_valid (const mdl_state_t *st)
	Validate all persisted state bounds and cross-field invariants.
bool	priv_mdl_state_decimal_to_binary64 (uint64_t mantissa, int32_t decimal_scale, bool negative, double *out)
	Convert one exact bounded decimal rational to binary64.
ra8_err_t	priv_mdl_state_parse_file (mdl_storage_t *storage, fw_fs_file_t *file, uint64_t offset, uint64_t length, uint16_t max_schema_version, mdl_state_t *st)
	Parse one exact state payload from an open portable file.

Detailed Description

Module-private validation shared by the state model and codec.

Declares bounded validation, exact decimal conversion, and streamed parsing seams.

Copyright

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

Definition in file mdl_state_internal.h.

Enumeration Type Documentation

mdl_state_internal_limit_t

enum mdl_state_internal_limit_t : uint16_t

Largest complete serialized record including its terminator.

Enumerator
k_mdl_state_line_max	Serialized line cap.

Definition at line 17 of file mdl_state_internal.h.

Function Documentation

priv_mdl_state_decimal_to_binary64()

bool priv_mdl_state_decimal_to_binary64	(	uint64_t	mantissa,
		int32_t	decimal_scale,
		bool	negative,
		double *	out )

Convert one exact bounded decimal rational to binary64.

Uses fixed-capacity integer division and nearest-even rounding without libc conversion.

Parameters

[in]	mantissa	Unsigned decimal significand (at most 17 digits).
[in]	decimal_scale	Signed power of ten applied to mantissa.
[in]	negative	Whether to set the binary64 sign bit.
[out]	out	Converted finite binary64 value.

Returns

Whether the exact value rounds to a non-underflowing finite binary64.

Return values

false

Scale, capacity, overflow, or nonzero underflow is invalid.

Precondition

out is non-NULL and decimal_scale is in [-400, 400].

mantissa carries at most 17 decimal digits.

Postcondition

Success is correctly rounded to nearest, ties to even without locale or libc conversion.

Failure publishes no numeric result contract.

Note

Signed zero is preserved.

Since

0.1.0

Definition at line 330 of file mdl_state_decimal.c.

References internal_mdl_state_big_bits(), internal_mdl_state_build_rational(), internal_mdl_state_compare_power(), internal_mdl_state_divide(), internal_mdl_state_encode(), k_state_binary64_exponent_max, k_state_binary64_exponent_min, k_state_binary64_fraction_bits, k_state_binary64_sign_shift, k_state_binary64_subnormal_scale, k_state_decimal_scale_max, memcpy(), and RA8_PRIV.

Referenced by internal_mdl_state_parse_double_field().

priv_mdl_state_field_valid()

bool priv_mdl_state_field_valid	(	const char *	text,
		size_t	cap )

Validate one delimiter-free bounded state field.

Measures through a fixed cap and rejects TAB, CR, and LF record delimiters.

Parameters

[in]	text	Candidate NUL-terminated field.
[in]	cap	Persisted field capacity.

Returns

Whether the complete value fits and contains no record delimiter.

Return values

false

NULL, unterminated, over-capacity, or delimiter-bearing input.

Precondition

cap is positive.

Candidate storage is readable through the terminator or cap.

Postcondition

Input remains unchanged.

Success guarantees safe exact serialization.

Note

Empty fields are valid.

Since

0.1.0

Validate one delimiter-free bounded state field.

Definition at line 70 of file mdl_state.c.

References RA8_PRIV, and strnlen().

Referenced by internal_mdl_state_apply_kv(), mdl_state_add_chapter_numbered(), mdl_state_add_page(), mdl_state_set_chapter_metadata(), mdl_state_set_series_metadata(), priv_mdl_state_relative_path_valid(), and priv_mdl_state_valid().

priv_mdl_state_parse_file()

ra8_err_t priv_mdl_state_parse_file	(	mdl_storage_t *	storage,
		fw_fs_file_t *	file,
		uint64_t	offset,
		uint64_t	length,
		uint16_t	max_schema_version,
		mdl_state_t *	st )

Parse one exact state payload from an open portable file.

Streams a declared payload extent and migrates supported schemas transactionally.

Parameters

[in,out]	storage	Initialized storage scratch binding.
[in,out]	file	Open file containing the payload.
[in]	offset	First payload byte.
[in]	length	Exact payload byte count.
[in]	max_schema_version	Highest schema authorized by the containing format.
[out]	st	State model receiving the parsed and migrated payload.

Returns

Canonical parse/read status.

Return values

k_ra8_err_invalid_state

Malformed, truncated, trailing, or unsupported payload.

Precondition

All pointers are non-NULL and file is open for reading.

Offset and length identify the authenticated payload extent.

max_schema_version is a supported nonzero schema version.

Postcondition

Success replaces st with the complete migrated/current state.

Failure leaves st initialized empty.

Note

Parsing uses bounded caller-owned scratch.

Since

0.1.0

Definition at line 845 of file mdl_state_codec.c.

References fw_fs_seek(), internal_mdl_state_parse_record(), internal_mdl_state_reader_line(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_mdl_state_line_max, k_mdl_state_version, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, mdl_state_init(), priv_mdl_state_valid(), and RA8_PRIV.

Referenced by internal_mdl_state_load_slot().

priv_mdl_state_relative_path_valid()

bool priv_mdl_state_relative_path_valid	(	const char *	path,
		size_t	cap )

Validate a bounded relative path stored in state.

Applies field bounds plus absolute-path and traversal rejection.

Parameters

[in]	path	Candidate path.
[in]	cap	Persisted field capacity.

Returns

Whether the path is relative, bounded, and non-traversing.

Return values

false

Empty, absolute, delimiter-bearing, or traversing path.

Precondition

cap is positive.

Candidate storage is readable through the terminator or cap.

Postcondition

Input remains unchanged.

Success is safe beneath the series root.

Note

Both slash variants are treated conservatively.

Since

0.1.0

Validate a bounded relative path stored in state.

Accepts empty paths and rejects absolute, empty-component, and .. component paths without accessing the filesystem.

Parameters

[in]	path	Candidate NUL-terminated path.
[in]	cap	Maximum field capacity, including NUL.

Returns

Whether the complete path is safe and bounded.

Return values

true	The path is empty or safely relative.
false	The path is malformed, overlong, absolute, or traversing.

Precondition

path is non-NULL.

cap is greater than zero.

Postcondition

path is unchanged.

No filesystem state is accessed or modified.

Note

Thread-safe: reads only caller storage.

Since

0.1.0

Definition at line 95 of file mdl_state.c.

References priv_mdl_state_field_valid(), RA8_PRIV, and strlen().

Referenced by internal_mdl_state_apply_metadata(), mdl_state_set_series_metadata(), and priv_mdl_state_valid().

priv_mdl_state_set_opt()

void priv_mdl_state_set_opt	(	char *	dst,
		size_t	cap,
		const char *	val )

Copy one optional value into a bounded state field.

Copies exact validated text while permitting an absent optional value.

Parameters

[out]	dst	Destination buffer.
[in]	cap	Destination capacity.
[in]	val	Optional NUL-terminated value.

Precondition

dst is non-NULL and cap is nonzero.

Non-NULL val fits including its terminator.

Postcondition

A non-NULL value is copied with NUL termination; NULL leaves dst unchanged.

No byte beyond cap is modified.

Note

Validation belongs to the caller.

Since

0.1.0

Copy one optional value into a bounded state field.

Definition at line 62 of file mdl_state.c.

References RA8_PRIV.

Referenced by internal_mdl_state_apply_kv(), and mdl_state_set_series().

priv_mdl_state_valid()

bool priv_mdl_state_valid

(

const mdl_state_t *

st

)

Validate all persisted state bounds and cross-field invariants.

Checks schema, counts, strings, chapter/page relationships, and finite numbers.

Parameters

[in]

st

State model to inspect.

Returns

Whether st can be serialized or accepted after parsing.

Return values

false

Any persisted invariant is violated.

Precondition

st is non-NULL.

The complete fixed-layout object is readable.

Postcondition

No state is modified.

Success qualifies the object for the current writer.

Note

Validation does not touch the filesystem.

Since

0.1.0

Validate all persisted state bounds and cross-field invariants.

Definition at line 142 of file mdl_state.c.

References mdl_state_t::artist, mdl_state_t::chapter_count, mdl_chapter_rec_t::chapter_id, mdl_state_t::chapters, mdl_chapter_rec_t::complete, mdl_state_t::config_path, mdl_state_t::cover_path, mdl_state_t::cover_url, mdl_page_rec_t::etag, mdl_page_rec_t::fetched_at, internal_mdl_state_chapter_number_valid(), internal_mdl_state_page_response_valid(), k_mdl_max_chapters, k_mdl_max_page_recs, k_mdl_state_read_ltr, k_mdl_state_read_rtl, k_mdl_state_version, mdl_state_t::language, mdl_page_rec_t::last_modified, mdl_chapter_rec_t::number, mdl_chapter_rec_t::number_known, mdl_chapter_rec_t::page_count, mdl_state_t::page_rec_count, mdl_state_t::pages, mdl_chapter_rec_t::pages_done, priv_mdl_state_field_valid(), priv_mdl_state_relative_path_valid(), RA8_PRIV, mdl_state_t::reading_direction, mdl_page_rec_t::rel_path, mdl_page_rec_t::response_status, mdl_state_t::series_title, mdl_state_t::series_url, mdl_state_t::site_host, mdl_state_t::site_name, mdl_chapter_rec_t::source_url, mdl_state_t::summary, mdl_chapter_rec_t::title, mdl_state_t::version, and mdl_state_t::writer.

Referenced by mdl_state_save(), and priv_mdl_state_parse_file().