livery_codec behaviour (livery v0.2.0)

View Source

Content-coding codec behaviour and registry.

A codec turns response bytes into a single content-coding (the token sent in Content-Encoding, e.g. gzip). livery_compress negotiates the client's Accept-Encoding against the registered codecs and applies the chosen one to {full, _} and {chunked, _} bodies.

The built-in codecs livery_codec_gzip and livery_codec_deflate are always available (over OTP zlib, no dependency). A separate app (a future livery_brotli or livery_zstd) adds its coding by calling register/1 at its own application start; it then participates in negotiation without any change to livery core.

Callbacks

  • name/0 — the Content-Encoding token (lowercase binary).
  • compress/1 — one-shot compression of a whole body ({full, _}).
  • stream_init/0 — open a streaming context.
  • stream_update/2 — feed a chunk and FLUSH, returning the bytes emittable now (so each producer chunk reaches the client promptly).
  • stream_finish/1 — return the trailing bytes that finalize the stream. Does not release the context.
  • stream_close/1 — release the context; always called, including on the error path.

Summary

Functions

Find a registered codec by Content-Encoding token (case-insensitive).

Register an extra codec module.

All registered codecs in server-preference order.

Types

codec()

-type codec() :: module().

Callbacks

compress/1

-callback compress(iodata()) -> iodata().

name()

-callback name() -> binary().

stream_close/1

-callback stream_close(term()) -> ok.

stream_finish/1

-callback stream_finish(term()) -> iodata().

stream_init()

-callback stream_init() -> term().

stream_update/2

-callback stream_update(term(), iodata()) -> iodata().

Functions

lookup(Name)

-spec lookup(binary()) -> {ok, codec()} | error.

Find a registered codec by Content-Encoding token (case-insensitive).

register(Module)

-spec register(codec()) -> ok.

Register an extra codec module.

Idempotent; built-in codecs are ignored (always present). Intended to be called once at the registering app's start, not per request.

registered()

-spec registered() -> [codec()].

All registered codecs in server-preference order.

Always begins with the built-ins (gzip, then deflate), followed by any extras in registration order. The built-ins can never be dropped by registration.