API reference

Brotli is a Parquet page codec (CompressionCodec.BROTLI) and the last one magmalake could not read. A Brotli stream records no uncompressed size anywhere — not in a header, not in a trailer — which shapes this API:

• decompress(data, uncompressed_size) is the Parquet path. A page header carries uncompressed_page_size, so the output buffer can be sized exactly and the stream decoded in a single pass.
• decompress_unsized(data) is for everything else (a bare .br file, a blob from somewhere that did not record a length). It guesses a capacity and doubles it until the stream fits, re-decoding from the start each time — Brotli's one-shot decoder cannot resume, so a short buffer costs a full retry. Use the sized form whenever the size is known.

Mirrors zstd.mojo's and lz4.mojo's FFI pattern: a single-call C wrapper (shim/brotli_wrapper.c, built to $CONDA_PREFIX/lib/libbrotlimojo.{dylib,so} by the brotli-shim pixi package) so Mojo never reads back internal library state after a foreign call. The handle is opened once per process and never closed (_LIB below) — a dlopen/dlclose cycle costs hundreds of microseconds, far more than decompressing a Parquet page, so opening one per call made the binding's fixed cost dwarf the work it wrapped. It is passed as an imm borrow to each worker function, so Mojo's ASAP destruction cannot dlclose the library between get_function and the call it returned.