brotli

brotli is a pure Go port of Google’s reference Brotli compression library, translated from the original C implementation with the author’s own c2go tool rather than wrapped via cgo bindings. It exposes NewWriter and NewReader constructors that mirror the ergonomics of Go’s standard compress/gzip package, along with tunable WriterOptions for quality and window-size trade-offs across the full BestSpeed-to-BestCompression range.

Beyond the core codec, the library ships an HTTPCompressor helper that negotiates brotli versus gzip versus no compression directly from a request’s Accept-Encoding header, a bundled flate/gzip-compatible subpackage, and an experimental matchfinder package that decouples LZ77 match-finding from entropy coding so custom compression strategies can be composed via the newer NewWriterV2 API.

What You Get

• Standard-library-style Writer and Reader types for encoding and decoding brotli streams
• Quality and window-size tunables (WriterOptions) covering the full BestSpeed-to-BestCompression range
• An HTTP helper (HTTPCompressor) that negotiates brotli vs gzip automatically from request headers
• A bundled flate/gzip-compatible subpackage for projects that want one dependency covering multiple formats
• An experimental matchfinder API for composing custom LZ77 and entropy-coding strategies

Common Use Cases

• Compressing HTTP API and web server responses on the fly
• Pre-compressing static assets for CDN delivery
• Replacing cgo-based Brotli bindings in cross-compiled or WASM Go binaries
• Prototyping custom LZ77 compression strategies via the matchfinder package

Under The Hood

Architecture The library is organized as a flat package translated from Google’s C reference implementation via the author’s c2go tool, with encode.go and decode.go orchestrating state-machine-based encoder and decoder routines, Writer and Reader types in writer.go and reader.go wrapping io.Writer/io.Reader behind a Reset-based reuse pattern, and a family of pluggable hashers (h5.go, h6.go, h10.go, hash_*.go) selected at runtime by chooseHasher() based on the requested quality level. A separate matchfinder subpackage defines MatchFinder and Encoder interfaces that decouple LZ77 match-finding from entropy coding, backing the newer, experimental NewWriterV2 API. Naming and structure still carry visible marks of the C-to-Go translation (globals like octetTypes, struct fields like literal_hgroup and block_type_trees), which keeps the core codec dense but consistent once the state-machine pattern is understood.

Tech Stack The module is pure Go (go.mod targets Go 1.22) with a single non-test dependency, github.com/xyproto/randomstring, used only in the test suite for generating randomized input data. A bundled flate subpackage reimplements drop-in equivalents of the standard library’s compress/flate and compress/gzip writers, and http.go integrates directly with net/http to add Accept-Encoding-based content negotiation to any http.ResponseWriter. There is no cgo dependency anywhere in the codebase, which is the library’s central technical proposition versus bindings to Google’s original C implementation.

Code Quality The repository has three test files — brotli_test.go (over 1,000 lines covering round-trip compression and decompression across quality levels), example_test.go, and flate/flate_test.go — exercising the public API with real corpus-style data. Error handling is idiomatic Go, using sentinel errors (errEncode, errWriterClosed, errExcessiveInput, errInvalidState) rather than panics. No linter configuration (no .golangci.yml) or CI workflow directory is present in the cloned source, so it’s unclear whether tests and vetting are enforced automatically on every change versus run manually by the maintainer before tagging a release.

API Design The public surface deliberately mirrors Go’s standard compress/gzip and compress/flate conventions — NewWriter, NewReader, Reset, Close — so anyone familiar with the standard library can adopt it with almost no new API to learn. HTTPCompressor and HTTPCompressorWithLevel collapse content-negotiation boilerplate into a single call for HTTP handlers, automatically choosing brotli, gzip, or no compression from the Accept-Encoding header. The newer, explicitly experimental NewWriterV2 and matchfinder package expose a lower-level MatchFinder/Encoder interface pair for callers who want to swap in custom LZ77 or entropy-coding strategies, a level of extensibility uncommon among general-purpose compression libraries, though the README is explicit that these newer APIs carry no SemVer compatibility guarantee yet.