Skip to content

Repository navigation

api.md

Latest commit

 

History

History
54 lines (36 loc) · 6.29 KB

api.md

File metadata and controls

54 lines (36 loc) · 6.29 KB
Raw

abitious API reference

This page describes the public runtime module and the C ABI in each platform package. The Rust codec and producer crates are workspace implementation crates; they are not published as Rust libraries. The frozen pressed-data format has a separate format specification.

Node.js runtime module

Install @abitious/cli and require it from CommonJS:

const addon = require('@abitious/cli')

console.log(addon.triple)
console.log(addon.stub)
console.log(addon.bin)

The module resolves the platform package while loading. It exports these paths and values:

Property Meaning
triple Resolved platform target, such as linux-x64-gnu.
pkg Name of the matching @abitious/<triple> package.
dir Installed directory for that platform package.
stub Path to its generic self-extracting addon stub.
ffi Path to its filesystem-compression shared library.
bin Path to the host abi producer executable.
nativeFfi A filesystem API adapter, or undefined when no supported FFI or binder is available.

On Node versions with node:ffi, or runtimes that provide node:smol-ffi, nativeFfi.name identifies the selected module. Otherwise the package can load its platform bind.node addon and identify it as napi-bind. A missing platform package makes require('@abitious/cli') throw an error that names the package to install.

The nativeFfi adapter provides probe(path), inspect(path), compressFile(path), and close(). probe returns 0 for a supported filesystem, 1 when the file is already compressed, 2 when compression is unsupported, and -1 on invalid input or an I/O error. inspect returns { compressed, logical, physical }; compressFile returns { status, before, after }. Compression status values are 0 compressed, 1 no size gain, 2 already compressed, 3 unsupported, and 4 skipped by the size gate. The byte counts use bigint.

The runtime FFI selects an available native module at load time. Node's built-in FFI is experimental and requires --experimental-ffi on Node 26. nativeFfi can be undefined when the runtime has no supported FFI module and the platform binder cannot load.

FFI carrier

Use the abi pack-ffi command to wrap an existing shared library in a self-extracting .node file. The command needs the target shared library and a target triple. It does not invoke Cargo. The platform producer bundle includes a template for each of the eight supported targets. The producer checks templates/manifest.json and each template's SHA-512 before it uses a bundled template. Use --template to provide a template path explicitly.

The carrier extracts the original library under abitious-ffi-<uid> in the OS temporary directory on Unix. Windows uses abitious-ffi-<user>. The filename contains the full SHA-512 and the platform library extension. The loader checks the FFI envelope, target metadata, and library hash. It stops when validation fails or when the cache path is unsafe. Darwin carriers require injection on a macOS host. pack-ffi ad-hoc signs the modified carrier so macOS can load it. The tag workflow signs and notarizes producer bundle binaries with Developer ID credentials. It fails closed when signing or notarization does not pass. A generated carrier needs separate signing before public macOS distribution.

The native workflow builds four targets on branch pushes and pull requests. A manual all-target run or a v* tag push builds all eight targets, including musl and Windows. The workflow tests template loading on the matching native runner. The aggregate archive is abitious-ffi-producer-bundles.tar.gz with a .sha512 sidecar. Its Actions artifact has a maximum configured retention of 400 days and needs authenticated download access. A public release asset requires release.githubAssetWorkflow to name this workflow and the tag release pipeline to pass its publish-before-release gate. The tag build also requires the Developer ID certificate, Apple notarization credentials, and accepted submissions for every macOS producer binary.

Platform C ABI

Each platform package contains a shared library with four exported functions. Callers must pass UTF-8, NUL-terminated paths. The abitious_ffi_version() function returns ABI version 1.

Function Return values and output
abitious_probe(path) 0 supported, 1 already compressed, 2 unsupported, -1 invalid input or I/O error.
abitious_stat(path, compressed, logical, physical) 0 on success and writes the compression flag plus logical and physical byte counts; -1 on error.
abitious_compress_file(path, before, after) 0 compressed, 1 no size gain, 2 already compressed, 3 unsupported, 4 skipped, -1 on error. Optional output pointers receive byte counts when available.
abitious_ffi_version() Returns 1.

The C functions that write through pointers require each non-null pointer to point to writable memory of the declared size. Treat these calls as unsafe at the FFI boundary. A successful compression changes the file at path; unsupported compression can leave the file unchanged.