Raw-DEFLATE compress / decompress over miniz, heap-free. More...

#include "ra8_compress.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "miniz.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"

Include dependency graph for ra8_compress.c:

Data Structures
struct	compress_ctx_t
	Bounded output sink for the tdefl put-buffer callback. More...

Functions
static mz_bool	internal_compress_put (const void buf, int len, void user)
	tdefl put-buffer callback: append len bytes to the bounded output.
static ra8_err_t	internal_ra8_compress_validate (const uint8_t src, const uint8_t out, const void scratch, uint32_t scratch_len, const uint32_t out_len)
	Validate ra8_compress arguments before driving the compressor.
static ra8_err_t	internal_ra8_compress_drive (tdefl_compressor d, compress_ctx_t ctx, const uint8_t src, uint32_t src_len, int flags, uint32_t out_len)
	Drive the miniz tdefl engine over src into the bounded sink.
ra8_err_t	ra8_compress (const uint8_t src, uint32_t src_len, uint8_t out, uint32_t out_cap, void scratch, uint32_t scratch_len, uint32_t out_len)
	Raw-DEFLATE compress src into out.
ra8_err_t	ra8_compress_zlib (const uint8_t src, uint32_t src_len, uint8_t out, uint32_t out_cap, void scratch, uint32_t scratch_len, uint32_t out_len)
	Zlib-wrap and DEFLATE-compress one bounded byte range.
ra8_err_t	ra8_decompress (const uint8_t src, uint32_t src_len, uint8_t out, uint32_t out_cap, uint32_t *out_len)
	Raw-DEFLATE decompress src into out.

Variables
static const char *const	s_tag = "ra8_compress"
	Module log tag.

Detailed Description

Raw-DEFLATE compress / decompress over miniz, heap-free.

Tag: [Ring 4 / Domain] {World: NS}

Decompression calls tinfl_decompress_mem_to_mem (its working state lives on miniz's SOUP stack, no heap). Compression drives the low-level tdefl engine with a caller-provided tdefl_compressor scratch and a put-buffer callback that appends into the bounded output – so no allocator is touched.

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

Definition in file ra8_compress.c.

Function Documentation

◆ internal_compress_put()

mz_bool internal_compress_put	(	const void *	buf,
		int	len,
		void *	user )

static

tdefl put-buffer callback: append len bytes to the bounded output.

Copies into the caller buffer while space remains; on overflow it flags the context and returns false so tdefl aborts.

Parameters

[in]	buf	Bytes emitted by the compressor.
[in]	len	Number of bytes emitted (non-negative).
[in]	user	The compress_ctx_t sink.

Returns: mz_bool MZ_TRUE on success, MZ_FALSE on overflow.

Return values

MZ_TRUE	Bytes appended.
MZ_FALSE	Output buffer full.

Precondition: user is a populated compress_ctx_t.; buf holds len bytes.

Postcondition: On success the sink grew by len bytes.; On overflow the sink's overflow flag is set.

Note: Not thread-safe with respect to the same sink.

Since: 0.1.0

Definition at line 67 of file ra8_compress.c.

References compress_ctx_t::cap, compress_ctx_t::len, memcpy(), compress_ctx_t::out, compress_ctx_t::overflow, and RA8_INTERNAL.

Referenced by internal_ra8_compress_drive().

◆ internal_ra8_compress_drive()

ra8_err_t internal_ra8_compress_drive	(	tdefl_compressor *	d,
		compress_ctx_t *	ctx,
		const uint8_t *	src,
		uint32_t	src_len,
		int	flags,
		uint32_t *	out_len )

static

Drive the miniz tdefl engine over src into the bounded sink.

Initializes the caller-provided compressor, runs a single finishing tdefl_compress_buffer pass, then maps overflow / engine status onto ra8_err_t. On success the produced length is taken from the sink.

Parameters

[in,out]	d	Caller compressor scratch, reinitialized here.
[in,out]	ctx	Bounded output sink (out/cap preset, len grows).
[in]	src	Bytes to compress.
[in]	src_len	Number of input bytes.
[in]	flags	Valid miniz tdefl_init() flags selecting raw or zlib output.
[out]	out_len	Compressed byte count on success.

Returns: ra8_err_t Compression result.

Return values

k_ra8_ok	Compressed; *out_len set from the sink.
k_ra8_err_no_mem	out was too small for the result.
k_ra8_fail	The compressor reported an error.

Precondition: d points to at least k_ra8_compress_scratch_bytes of scratch.; ctx->out/ctx->cap describe the destination, ctx->len == 0.

Postcondition: On k_ra8_ok *out_len equals the bytes appended to the sink.; On any non-ok return *out_len is left unchanged.

Note: Not thread-safe with respect to the same scratch or sink.

Since: 0.1.0

Definition at line 152 of file ra8_compress.c.

References internal_compress_put(), k_ra8_err_no_mem, k_ra8_fail, k_ra8_ok, compress_ctx_t::len, compress_ctx_t::overflow, and RA8_INTERNAL.

Referenced by ra8_compress(), and ra8_compress_zlib().

◆ internal_ra8_compress_validate()

ra8_err_t internal_ra8_compress_validate	(	const uint8_t *	src,
		const uint8_t *	out,
		const void *	scratch,
		uint32_t	scratch_len,
		const uint32_t *	out_len )

static

Validate ra8_compress arguments before driving the compressor.

Performs the four non-NULL precondition checks and the scratch-size lower-bound check, returning the matching ra8_err_t so the public entry point stays small. Kept separate from the compress drive so the validation decisions live in one cohesive block.

Parameters

[in]	src	Bytes to compress (checked non-NULL).
[in]	out	Destination buffer (checked non-NULL).
[in]	scratch	Caller compressor scratch (checked non-NULL).
[in]	scratch_len	Size of scratch in bytes (checked >= minimum).
[in]	out_len	Result-length out-pointer (checked non-NULL).

Returns: ra8_err_t Validation result.

Return values

k_ra8_ok	All arguments are valid.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_invalid_size	scratch_len is below the minimum.

Precondition: s_tag is initialized for logging.; The caller forwards its own arguments unchanged.

Postcondition: On a non-ok return the caller must propagate the code verbatim.; On k_ra8_ok every pointer argument is non-NULL.

Note: Pure precondition check; touches no compressor state.

Since: 0.1.0

Definition at line 108 of file ra8_compress.c.

References k_ra8_compress_scratch_bytes, k_ra8_err_invalid_size, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, and s_tag.

Referenced by ra8_compress(), and ra8_compress_zlib().

◆ ra8_compress()

ra8_err_t ra8_compress	(	const uint8_t *	src,
		uint32_t	src_len,
		uint8_t *	out,
		uint32_t	out_cap,
		void *	scratch,
		uint32_t	scratch_len,
		uint32_t *	out_len )

nodiscard

Raw-DEFLATE compress src into out.

Parameters

[in]	src	Bytes to compress.
[in]	src_len	Number of input bytes.
[out]	out	Destination for the compressed stream.
[in]	out_cap	Capacity of out in bytes.
[in]	scratch	Caller buffer >= k_ra8_compress_scratch_bytes, 8-byte aligned (holds the miniz compressor).
[in]	scratch_len	Size of scratch in bytes.
[out]	out_len	Compressed byte count on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Compressed; *out_len set.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_invalid_size	scratch_len is below the minimum.
k_ra8_err_no_mem	out was too small for the result.
k_ra8_fail	The compressor reported an error.

Precondition: scratch is at least k_ra8_compress_scratch_bytes and 8-aligned.; out is writable for out_cap bytes.

Postcondition: On success out[0 .. *out_len) decompresses back to src.; On any non-ok return out content is unspecified.

Note: Not thread-safe with respect to the same scratch.

Since: 0.1.0

Definition at line 173 of file ra8_compress.c.

References internal_ra8_compress_drive(), internal_ra8_compress_validate(), and k_ra8_ok.

Referenced by internal_encode_tile(), and ra8_vfs_compress_write().

◆ ra8_compress_zlib()

ra8_err_t ra8_compress_zlib	(	const uint8_t *	src,
		uint32_t	src_len,
		uint8_t *	out,
		uint32_t	out_cap,
		void *	scratch,
		uint32_t	scratch_len,
		uint32_t *	out_len )

nodiscard

Zlib-wrap and DEFLATE-compress one bounded byte range.

Uses the same caller-owned tdefl_compressor scratch and bounded output sink as ra8_compress, but emits an RFC 1950 zlib stream (two-byte header plus Adler-32 trailer). This is the wire shape used by each independently compressed chunk in an RBKC .rabook container. Keeping the wrapper choice explicit prevents raw RFC 1951 streams from being mislabeled as zlib data.

Parameters

[in]	src	Bytes to compress.
[in]	src_len	Number of input bytes.
[out]	out	Destination for the zlib stream.
[in]	out_cap	Writable capacity of `out`.
[in]	scratch	Caller buffer for one tdefl_compressor.
[in]	scratch_len	Size of `scratch` in bytes.
[out]	out_len	Receives the complete zlib-stream length.

Returns: Canonical compression status.

Return values

k_ra8_ok	A complete zlib stream was produced.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	Compressor scratch was too small.
k_ra8_err_no_mem	The bounded output could not hold the stream.
k_ra8_fail	The compressor rejected the input.

Precondition: scratch is at least k_ra8_compress_scratch_bytes and 8-byte aligned.; out spans out_cap writable bytes.

Postcondition: On success, inflating out[0..*out_len) as zlib reproduces src.; No allocator is called; all transient state is caller-owned.

Note: Not thread-safe with respect to the same buffers.

Since: 0.1.0

Definition at line 190 of file ra8_compress.c.

References internal_ra8_compress_drive(), internal_ra8_compress_validate(), and k_ra8_ok.

Referenced by internal_write_chunks().

◆ ra8_decompress()

ra8_err_t ra8_decompress	(	const uint8_t *	src,
		uint32_t	src_len,
		uint8_t *	out,
		uint32_t	out_cap,
		uint32_t *	out_len )

nodiscard

Raw-DEFLATE decompress src into out.

Parameters

[in]	src	Compressed stream (raw DEFLATE).
[in]	src_len	Number of input bytes.
[out]	out	Destination for the decompressed bytes.
[in]	out_cap	Capacity of out (must hold the whole result).
[out]	out_len	Decompressed byte count on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Decompressed; *out_len set.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_no_mem	out was too small, or the stream is corrupt.

Precondition: out is large enough to hold the whole decompressed stream.; src is a raw-DEFLATE stream produced compatibly.

Postcondition: On success out[0 .. *out_len) holds the original bytes.; On any non-ok return out content is unspecified.

Note: Heap-free; not thread-safe with respect to out.

Since: 0.1.0

Definition at line 208 of file ra8_compress.c.

References k_ra8_err_no_mem, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_decode_stream(), and ra8_vfs_compress_read().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_compress"

static

Module log tag.

Definition at line 30 of file ra8_compress.c.

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ internal_compress_put()

◆ internal_ra8_compress_drive()

◆ internal_ra8_compress_validate()

◆ ra8_compress()

◆ ra8_compress_zlib()

◆ ra8_decompress()

Variable Documentation

◆ s_tag