Racket

libbrotli: Brotli Compression for Racket🔗ℹ

Racket bindings for Google’s Brotli compression library. Provides one-shot compression/decompression of byte strings, a streaming output port for incremental compression, and a streaming input port for incremental decompression.

All compression and decompression functions accept an optional #:dictionary parameter for LZ77 prefix dictionaries. If a dictionary is used for compression, the same dictionary must be used for decompression. Dictionary data must not exceed 16 MiB.

1 One-Shot Compression🔗ℹ

procedure
(brotli-compress src
[ quality
#:window window
#:mode mode
#:lgblock lgblock
#:dictionary dictionary]) → bytes?
  src : bytes?
  quality : quality/c = BROTLI_DEFAULT_QUALITY
  window : window/c = BROTLI_DEFAULT_WINDOW
  mode : mode/c = BROTLI_MODE_GENERIC
  lgblock : lgblock/c = 0
  dictionary : bytes? = #""

Compresses src and returns a fresh byte string containing the compressed output.

procedure
(brotli-compress! src
dst
[ quality
#:window window
#:mode mode
#:lgblock lgblock
#:dictionary dictionary])
→ exact-nonnegative-integer?
  src : bytes?
  dst : bytes?
  quality : quality/c = BROTLI_DEFAULT_QUALITY
  window : window/c = BROTLI_DEFAULT_WINDOW
  mode : mode/c = BROTLI_MODE_GENERIC
  lgblock : lgblock/c = 0
  dictionary : bytes? = #""

Compresses src into the pre-allocated buffer dst. Returns the number of bytes written to dst. Raises exn:fail? if compression fails (e.g., dst is too small).

2 One-Shot Decompression🔗ℹ

procedure
(brotli-decompress src
[ max-decompressed-size
#:dictionary dictionary]) → bytes?
  src : bytes?
  max-decompressed-size : (or/c #f exact-positive-integer?) = #f
  dictionary : bytes? = #""

Decompresses src and returns a fresh byte string. When max-decompressed-size is not #f, the decompressed output is bounded to that many bytes; an exn:fail? is raised if the limit is exceeded. This guards against decompression bombs.

procedure
(brotli-decompress! src
dst
[ #:dictionary dictionary])
→ exact-nonnegative-integer?
  src : bytes?
  dst : bytes?
  dictionary : bytes? = #""

Decompresses src into the pre-allocated buffer dst. Returns the number of bytes written. Raises exn:fail? if dst is too small or the input is invalid.

3 Streaming Output Port🔗ℹ

procedure
(open-brotli-output out
[ #:quality quality
#:window window
#:mode mode
#:lgblock lgblock
#:dictionary dictionary
#:close? close?
#:name name]) → output-port?
  out : output-port?
  quality : quality/c = 6
  window : window/c = BROTLI_DEFAULT_WINDOW
  mode : mode/c = BROTLI_MODE_GENERIC
  lgblock : lgblock/c = 0
  dictionary : bytes? = #""
  close? : boolean? = #t
  name : symbol? = 'brotli-output

Returns a new output port that compresses everything written to it with Brotli and forwards the compressed bytes to out.

Calling flush-output on the returned port issues a Brotli FLUSH operation, ensuring the receiver can decode all data written so far. This is essential for streaming protocols like SSE.

Closing the returned port finalises the Brotli stream. If close? is #t (the default), the underlying port out is also closed; otherwise it is left open.

4 Streaming Input Port🔗ℹ

procedure
(open-brotli-input in
[ #:dictionary dictionary
#:close? close?
#:name name]) → input-port?
  in : input-port?
  dictionary : bytes? = #""
  close? : boolean? = #t
  name : symbol? = 'brotli-input

Returns a new input port that decompresses Brotli-compressed data read from in.

Reading from the returned port pulls compressed bytes from in, decompresses them incrementally, and returns the decompressed data. This allows decompression of arbitrarily large streams without loading the entire compressed input into memory.

Closing the returned port destroys the decoder state. If close? is #t (the default), the underlying port in is also closed; otherwise it is left open.

Raises exn:fail? if the compressed data is corrupt or the stream is truncated.

5 Contracts🔗ℹ

value
quality/c : flat-contract?

Equivalent to (integer-in 0 11). Accepts compression quality levels from 0 (fastest) to 11 (smallest output).

value
window/c : flat-contract?

Equivalent to (integer-in 10 24). Accepts sliding-window sizes (as a power of two) from 10 to 24. Larger values may improve compression at the cost of memory.

value
mode/c : flat-contract?

Accepts one of BROTLI_MODE_GENERIC (0), BROTLI_MODE_TEXT (1), or BROTLI_MODE_FONT (2).

value
lgblock/c : flat-contract?

Equivalent to (or/c (=/c 0) (integer-in 16 24)). Accepts 0 (auto-selected based on quality) or an explicit block size from 16 to 24. The value is the base-2 logarithm of the maximum input block size.

6 Constants🔗ℹ

6.1 Defaults🔗ℹ

value
BROTLI_DEFAULT_QUALITY : exact-nonnegative-integer? = 11

The default compression quality used by brotli-compress and brotli-compress!.

value
BROTLI_DEFAULT_WINDOW : exact-nonnegative-integer? = 22

The default sliding-window size used by brotli-compress, brotli-compress!, and open-brotli-output.

6.2 Quality Range🔗ℹ

value
BROTLI_MIN_QUALITY : exact-nonnegative-integer? = 0

Minimum compression quality (fastest).

value
BROTLI_MAX_QUALITY : exact-nonnegative-integer? = 11

Maximum compression quality (smallest output).

6.3 Window Range🔗ℹ

value
BROTLI_MIN_WINDOW_BITS : exact-nonnegative-integer? = 10

Minimum sliding-window size.

value
BROTLI_MAX_WINDOW_BITS : exact-nonnegative-integer? = 24

Maximum sliding-window size.

6.4 Compression Modes🔗ℹ

value
BROTLI_MODE_GENERIC : mode/c = 0

Generic mode. No assumptions about content type.

value
BROTLI_MODE_TEXT : mode/c = 1

Text mode. Optimized for UTF-8 input.

value
BROTLI_MODE_FONT : mode/c = 2

Font mode. Optimized for WOFF 2.0 fonts.

1	One-Shot Compression
2	One-Shot Decompression
3	Streaming Output Port
4	Streaming Input Port
5	Contracts
6	Constants