SLeeLa SLeeLa # SLeeLa Compression Handlers **Package:** `compression/` **Date:** 2026-10-23 This package defines the SLeeLa general-purpose data-compression handler registry. It provides one place to identify major compression standards, describe their signatures/extensions, and expose whether a handler is natively implemented, requires an external library backend, is only recognized, or is a container. It is the compression counterpart to `codecs/` (audio): same plugin + manager architecture, applied to byte streams instead of PCM. ## Handler Classes - **Native** — SLeeLa contains the algorithm implementation. - **Backend** — the handler contract exists, but an approved library/backend is required for actual compress/decompress. - **Recognized** — the format can be identified and described, but compress/decompress is not claimed. - **Container** — identifies an archive/container rather than a single compression algorithm. No handler is advertised as fully implemented merely because its name appears in the registry. ## Major Standards Covered | Handler | Standard / Format | Typical role | State | |---|---|---|---| | Store | Raw / identity | Fallback, baseline | Native | | RLE | PackBits run-length | Simple runs | Native | | Huffman | Canonical Huffman | Entropy coding | Native | | LZW | Lempel-Ziv-Welch | Dictionary / legacy | Native | | DEFLATE | RFC 1951 | General purpose | Backend | | zlib | RFC 1950 | General purpose | Backend | | gzip | RFC 1952 | File / HTTP | Backend | | bzip2 | BWT + Huffman | High ratio | Backend | | LZMA | LZMA | High ratio | Backend | | xz | LZMA2 container | High ratio | Backend | | Zstandard | zstd | Fast, high ratio | Backend | | LZ4 | LZ4 frame | Very fast | Backend | | Brotli | Brotli | Web content | Backend | | Snappy | Snappy framed | Fast, in-memory | Backend | | ZIP | ZIP archive | Container | Container | ## Architecture: individual algorithms + a Loader/Manager Each algorithm is a **self-contained plugin** in its own folder under `compression/compressors//`, implementing a small common vtable (`compression/include/sleela_compressor_plugin.h`): `describe`, `load`, `unload`, `probe`, `compress`, `decompress`. Native algorithms ship C **and** C++ (the vtable/glue in `.c`, the byte-level codec in `.cpp`) plus their own `.md`; backend algorithms ship the C vtable plus a C++ signature probe. SLeeLa never links or calls an individual algorithm directly. It calls the **Compression Loader / Unloader / Management Controller** (`compression/include/sleela_compression_manager.h`), which owns every plugin's lifecycle: ``` SLeeLa -> Compression Manager (loader/unloader/controller) -> individual plugin load / unload / resolve / compress / decompress ``` - `sleela_compression_manager_create()` registers every known algorithm (none loaded). - `sleela_compression_manager_load(mgr, id)` / `..._unload(mgr, id)` manage lifecycle. - `..._resolve_extension` / `..._resolve_probe` pick an algorithm from a filename or content bytes. - `..._compress` / `..._decompress` dispatch to the loaded plugin. - A backend-less algorithm reports its state and returns a clean `SLEELA_COMPRESSION_ERR_UNSUPPORTED` instead of faking success. The SLeeLa-facing handle to the Loader is `lib/compression/SLCompressionLoader.sleela` (runnable demos: `lib/compression/compression.sleela` and `lib/compression/compression-pipeline.sleela`). ### Native algorithms (fully implemented in-package, no external library) - **Store** (`compressors/store/`) — the identity transform; the raw boundary every other algorithm is measured against. - **RLE** (`compressors/rle/`) — PackBits-style run-length encoding, lossless. - **Huffman** (`compressors/huffman/`) — static canonical Huffman with a self-describing header. - **LZW** (`compressors/lzw/`) — variable-width (9..12 bit) Lempel-Ziv-Welch with an explicit CLEAR code. All four round-trip losslessly and are covered by `tests/test_manager.c`. ### Backend algorithms (contract + probe, pluggable implementation) DEFLATE, zlib, gzip, bzip2, LZMA, xz, Zstandard, LZ4, Brotli, Snappy are **Backend** handlers: they identify the format (a C++ signature probe) and delegate compress/decompress to a **runtime-registered backend adapter**. ```c /* A host wires an approved library (zlib, libzstd, ...) at startup: */ static const sleela_compression_backend gzip_adapter = { "zlib", gz_comp, gz_decomp }; sleela_compression_backend_register(SLEELA_COMPRESSION_GZIP, &gzip_adapter); ``` With a backend registered, the plugin's compress/decompress dispatch to it; with none registered, they return `SLEELA_COMPRESSION_ERR_UNSUPPORTED` — never a false success. (No third-party libraries are bundled in-tree.) ZIP is a **Container** handler (probe + identification). ## C Handler Registry (metadata) The static registry is in: - `compression/include/sleela_compression.h` - `compression/src/sleela_compression.c` It provides stable algorithm identifiers, human-readable names, MIME/type and extension metadata, handler state, compress/decompress capability flags, lookup by identifier, lookup by file extension, and enumeration of the whole registry. The registry is metadata and dispatch infrastructure. It does not silently substitute a system utility or third-party library for an algorithm implementation. ## Result codes Shared by every plugin entry point and by the manager (`sleela_compression_result`): | Code | Meaning | |---|---| | `0` | ok | | `-1` | unsupported (backend not present) | | `-2` | invalid arguments | | `-3` | input is not this algorithm's format | | `-4` | I/O or allocation failure | | `-5` | algorithm not loaded | | `-6` | output buffer too small | ## Build and test ```sh # from compression/ make # builds build/libsleela_compression.a make test # builds and runs the registry + manager tests ``` ## Completion Policy A handler becomes **Native** only when the implementation, validation, tests, and build integration are present. A **Backend** handler may be wired to a supported library later; until then, callers can inspect its state and fail cleanly instead of receiving a false success. See `COMPRESSION.md` for the detailed registry and implementation order. --- # SLeeLa

SLeeLa — The Now. The Ingredient.

SLeeLa Marketing Logo