= cowboy_decompress_h(3)

== Name

cowboy_decompress_h - Decompress stream handler

== Description

The module `cowboy_decompress_h` decompresses request bodies
automatically when the server supports it.

The only compression algorithm currently supported is the
gzip algorithm. Another limitation is that decompression
is only attempted when gzip is the only content-encoding
in the request.

This stream handler always adds a field to the Req object
with the name `content_decoded` which is treated as a
list of decoded content-encoding values. Currently this
list may only contain the `<<"gzip">>` binary if content
may be decoded; or be empty otherwise.

== Options

[source,erlang]
----
opts() :: #{
	decompress_enabled => boolean(),
	decompress_ratio_limit => non_neg_integer()
}
----

Configuration for the decompress stream handler.

The default value is given next to the option name:

decompress_ratio_limit (20)::
The max ratio of the compressed and decompressed body
before it is rejected with a `413 Payload Too Large`
error response.
+
This option can be updated at any time using the
`set_options` stream handler command.

decompress_enabled (true)::

Whether the handler is enabled by default.
+
This option can be updated using the `set_options`
stream handler command. This allows disabling
decompression for the current stream. Attempts
to enable or disable decompression after starting
to read the body will be ignored.
+
Note that when the handler initialises it removes
the `content-encoding: gzip` header if any and
prepares for decompression even when
`decompress_enabled` is initially set to `false`.
The `content_decoded` Req object field will
contain `<<"gzip">>` when that happens.

== Events

The decompress stream handler does not produce any event.

== Changelog

* *2.11*: Module introduced.

== See also

link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_stream(3)[cowboy_stream(3)],
link:man:cowboy_compress_h(3)[cowboy_compress_h(3)],
link:man:cowboy_metrics_h(3)[cowboy_metrics_h(3)],
link:man:cowboy_stream_h(3)[cowboy_stream_h(3)],
link:man:cowboy_tracer_h(3)[cowboy_tracer_h(3)]
