fsm/cl-brotli: Common Lisp bindings for the brotli compression library. - Codeberg.org
This website requires JavaScript.
fsm/cl-brotli
Watch
Star
Fork
You've already forked cl-brotli
Code
Issues
Pull requests
Activity
Common Lisp bindings for the brotli compression library.
1 commit
1 branch
0 tags
69 KiB
Common Lisp
98.7%
Makefile
1.3%
main
Find a file
HTTPS
Download ZIP<br>Download TAR.GZ<br>Download BUNDLE
Open with VS Code
Open with VSCodium
Open with Intellij IDEA
Frederico Muñoz
420e84b237
First public version
2026-06-04 17:05:07 +01:00
docs
First public version
2026-06-04 17:05:07 +01:00
examples
First public version
2026-06-04 17:05:07 +01:00
src
First public version
2026-06-04 17:05:07 +01:00
tests
First public version
2026-06-04 17:05:07 +01:00
.gitignore
First public version
2026-06-04 17:05:07 +01:00
cl-brotli-tests.asd
First public version
2026-06-04 17:05:07 +01:00
cl-brotli.asd
First public version
2026-06-04 17:05:07 +01:00
COPYING
First public version
2026-06-04 17:05:07 +01:00
Makefile
First public version
2026-06-04 17:05:07 +01:00
README.org
First public version
2026-06-04 17:05:07 +01:00
README.org
cl-brotli
Status
Reference implementation
System requirements
Usage
Compression levels
API
Benchmarks
Reading the output
Documentation
License
Additional info
Common Lisp bindings for the brotli compression library, providing Gray-stream-based compression and<br>decompression.
Status
Functional. Used as the brotli compression backend for datastar-cl. That said, not thoroughly<br>tested.
Reference implementation
This library is modelled directly on cl-zstd by Guillaume Le Vaillant: the file structure,<br>gray-stream class design, API naming, and test approach all follow cl-zstd as closely as possible.
This is intentional: cl-zstd is a clean, well-structured library and cl-brotli is meant to be<br>readable alongside it, but even more relevant for this choice, cl-zstd was already supported for SSE<br>streams, making it a good starting point: not being an expert in compression streams, having a<br>reference implementation to follow was fundamental.
Where the brotli C API forces a deviation, the source code includes a short comment explaining why.<br>Readers familiar with cl-zstd should be able to read cl-brotli with minimal friction.
System requirements
The brotli shared libraries must be installed:
# Debian/Ubuntu<br>apt install libbrotli1 libbrotli-dev
etc.
Usage
This is a library so usage will be done by applications; the following snippets show some of the<br>common entry points:
(ql:quickload :cl-brotli)
;; One-shot<br>(let* ((data #(1 2 3 4 5))<br>(compressed (brotli:compress-buffer data))<br>(decompressed (brotli:decompress-buffer compressed)))<br>(equalp data decompressed)) ; => T
;; Streaming (encoder)<br>(with-open-file (out "/tmp/data.br" :direction :output :element-type '(unsigned-byte 8))<br>(brotli:with-compressing-stream (stream out :level 4)<br>(write-sequence (cl-octet-streams:string-to-octets "some-bytes") stream)))
;; Streaming (decoder)<br>(with-open-file (in "/tmp/data.br" :element-type '(unsigned-byte 8))<br>(brotli:with-decompressing-stream (stream in)<br>(read-sequence buffer stream)))
An Huchentoot minimal example is in examples/server.lisp:
$ sbcl --load examples/server.lisp<br>[...]<br>Serving on http://localhost:4242/hello (C-c to stop)<br>[...]<br>127.0.0.1 - [2026-06-03 20:25:45] "GET /hello HTTP/1.1" 200 - "-" "curl/8.20.0"
Using curl:
$ curl --compressed -v http://localhost:4242/hello<br>[...]<br>> GET /hello HTTP/1.1<br>> Host: localhost:4242<br>> User-Agent: curl/8.20.0<br>> Accept: */*<br>> Accept-Encoding: deflate, gzip, br, zstd<br>[...]<br>; charset=utf-8<br>[...]<br>Hello, Brotli!
Compression levels
Brotli quality ranges from 0 (fastest) to 11 (best compression, slowest).
Default in this library: 4 . Fast, adequate for real-time streaming (e.g., SSE which was the<br>initial use-case).
Brotli's upstream default: 11 . Designed for static asset pre-compression, usually too slow for<br>per-event streaming.
API
The API mirrors cl-zstd closely; this table shows the initial mapping:
cl-brotli<br>cl-zstd equivalent
brotli:make-compressing-stream<br>zstd:make-compressing-stream
brotli:with-compressing-stream<br>zstd:with-compressing-stream
brotli:make-decompressing-stream<br>zstd:make-decompressing-stream
brotli:with-decompressing-stream<br>zstd:with-decompressing-stream
brotli:compress-buffer<br>zstd:compress-buffer
brotli:compress-stream<br>zstd:compress-stream
brotli:compress-file<br>zstd:compress-file
brotli:decompress-buffer<br>zstd:decompress-buffer
brotli:decompress-stream<br>zstd:decompress-stream
brotli:decompress-file<br>zstd:decompress-file
brotli:brotli-error<br>zstd:zstd-error
Benchmarks
A simple benchmark test was added to the test system; load it and call run-benchmarks:
(ql:quickload :cl-brotli-tests)<br>(brotli-benchmarks:run-benchmarks)
Three workloads are measured across 256 B / 4 KiB / 64 KiB / 1 MB payloads of "realistic" SSE-style<br>text (event: / data: lines with varied...