nhttp_compress (nhttp_lib v1.0.0)

View Source

HTTP compression utilities for nhttp.

Supports gzip and deflate content encoding for request/response bodies. Compression is configurable and can be disabled.

Configuration options:

  • compression => boolean() (default: true)
  • compression_level => 1..9 (default: 6)
  • compression_threshold => non_neg_integer() (default: 1024)
  • compress_mime_types => [binary()] (default: text/*, application/json, etc.)

Summary

Types

compress_opts()
encoding()
zlib_error()

Functions

compress(Data, Encoding, Level)

Compress data using the specified encoding. Returns {ok, CompressedData} or {error, Reason}.

decompress(Data, Encoding)

Decompress data using the specified encoding. Caps inflated output at ?DEFAULT_MAX_DECOMPRESSED_SIZE (16 MiB) to defend against decompression bombs. Use decompress/3 to override.

decompress(Data, Encoding, Max)

Decompress data with an explicit cap on the inflated output. Returns {error, max_output_exceeded} if decoding would produce more than Max bytes; pass infinity to disable the cap.

default_mime_types()

Return default MIME types eligible for compression.

encoding_header/1

Convert encoding atom to header value.

negotiate_encoding(Headers)

Negotiate encoding based on Accept-Encoding header. Returns the best encoding the client accepts that we support.

should_compress(ContentType, Size, MimeTypes)

Check if response should be compressed using the default threshold (?DEFAULT_COMPRESSION_THRESHOLD). Equivalent to should_compress(ContentType, Size, MimeTypes, ?DEFAULT_COMPRESSION_THRESHOLD).

should_compress(ContentType, Size, MimeTypes, Threshold)

Check if response should be compressed. Returns true when body size meets the threshold and Content-Type matches the compressible MIME types.

Types

compress_opts()

-type compress_opts() ::
          #{compression => boolean(),
            compression_level => 1..9,
            compression_threshold => non_neg_integer(),
            compress_mime_types => [binary()]}.

encoding()

-type encoding() :: gzip | deflate | identity.

zlib_error()

-type zlib_error() ::
          data_error | buf_error | stream_error | badarg | enomem | max_output_exceeded |
          {unknown, term()}.

Functions

compress(Data, Encoding, Level)

-spec compress(Data :: iodata(), Encoding :: gzip | deflate, Level :: 1..9) ->
                  {ok, binary()} | {error, zlib_error()}.

Compress data using the specified encoding. Returns {ok, CompressedData} or {error, Reason}.

decompress(Data, Encoding)

-spec decompress(Data :: binary(), Encoding :: encoding()) -> {ok, binary()} | {error, zlib_error()}.

Decompress data using the specified encoding. Caps inflated output at ?DEFAULT_MAX_DECOMPRESSED_SIZE (16 MiB) to defend against decompression bombs. Use decompress/3 to override.

decompress(Data, Encoding, Max)

-spec decompress(Data :: binary(), Encoding :: encoding(), Max) ->
                    {ok, binary()} | {error, zlib_error()}
                    when Max :: pos_integer() | infinity.

Decompress data with an explicit cap on the inflated output. Returns {error, max_output_exceeded} if decoding would produce more than Max bytes; pass infinity to disable the cap.

default_mime_types()

-spec default_mime_types() -> [binary()].

Return default MIME types eligible for compression.

encoding_header/1

-spec encoding_header(encoding()) -> binary().

Convert encoding atom to header value.

negotiate_encoding(Headers)

-spec negotiate_encoding(Headers :: [{binary(), binary()}]) -> encoding().

Negotiate encoding based on Accept-Encoding header. Returns the best encoding the client accepts that we support.

should_compress(ContentType, Size, MimeTypes)

-spec should_compress(ContentType :: binary() | undefined,
                      Size :: non_neg_integer(),
                      MimeTypes :: [binary()]) ->
                         boolean().

Check if response should be compressed using the default threshold (?DEFAULT_COMPRESSION_THRESHOLD). Equivalent to should_compress(ContentType, Size, MimeTypes, ?DEFAULT_COMPRESSION_THRESHOLD).

should_compress(ContentType, Size, MimeTypes, Threshold)

-spec should_compress(ContentType :: binary() | undefined,
                      Size :: non_neg_integer(),
                      MimeTypes :: [binary()],
                      Threshold :: non_neg_integer()) ->
                         boolean().

Check if response should be compressed. Returns true when body size meets the threshold and Content-Type matches the compressible MIME types.