mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 12:40:25 +00:00
fd9711d949
The read buffer was changed into an iovec to avoid doing too many binary concatenations and allocations. Decompression happens transparently: when decoding gzip, the content-encoding header is removed (we only decode when "gzip" is the only encoding so nothing remains). We always add a content_decoded key to the Req object. This key contains a list of codings that were decoded, in the reverse order in which they were. Currently it can only be empty or contain <<"gzip">> but future improvements or user handlers may see it contain more values. The option to disable decompression was renamed to decompress_enabled and defaults to true. It is no longer possible to enable/disable decompression in the middle of reading the body: this ensures that the data we pass forward is always valid. Various smaller improvements were made to the code, tests and manual pages.
80 lines
2.9 KiB
Text
80 lines
2.9 KiB
Text
[[streams]]
|
|
== Streams
|
|
|
|
A stream is the set of messages that form an HTTP
|
|
request/response pair.
|
|
|
|
The term stream comes from HTTP/2. In Cowboy, it is
|
|
also used when talking about HTTP/1.1 or HTTP/1.0.
|
|
It should not be confused with streaming the request
|
|
or response body.
|
|
|
|
All versions of HTTP allow clients to initiate
|
|
streams. HTTP/2 is the only one also allowing servers,
|
|
through its server push feature. Both client and
|
|
server-initiated streams go through the same process
|
|
in Cowboy.
|
|
|
|
=== Stream handlers
|
|
|
|
link:man:cowboy_stream(3)[Stream handlers]
|
|
must implement five different callbacks.
|
|
Four of them are directly related; one is special.
|
|
|
|
All callbacks receives the stream ID as first argument.
|
|
|
|
Most of them can return a list of commands to be executed
|
|
by Cowboy. When callbacks are chained, it is possible to
|
|
intercept and modify these commands. This can be useful
|
|
for modifying responses for example.
|
|
|
|
The `init/3` callback is invoked when a new request
|
|
comes in. It receives the Req object and the protocol options
|
|
for this listener.
|
|
|
|
The `data/4` callback is invoked when data from the request
|
|
body is received. It receives both this data and a flag
|
|
indicating whether more is to be expected.
|
|
|
|
The `info/3` callback is invoked when an Erlang message is
|
|
received for this stream. They will typically be messages
|
|
sent by the request process.
|
|
|
|
Finally the `terminate/3` callback is invoked with the
|
|
terminate reason for the stream. The return value is ignored.
|
|
Note that as with all terminate callbacks in Erlang, there
|
|
is no strong guarantee that it will be called.
|
|
|
|
The special callback `early_error/5` is called when an error
|
|
occurs before the request headers were fully received and
|
|
Cowboy is sending a response. It receives the partial Req
|
|
object, the error reason, the protocol options and the response
|
|
Cowboy will send. This response must be returned, possibly
|
|
modified.
|
|
|
|
=== Built-in handlers
|
|
|
|
Cowboy comes with four handlers.
|
|
|
|
link:man:cowboy_stream_h(3)[cowboy_stream_h] is the default
|
|
stream handler. It is the core of much of the functionality
|
|
of Cowboy. All chains of stream handlers should call it last.
|
|
|
|
link:man:cowboy_compress_h(3)[cowboy_compress_h] will
|
|
automatically compress responses when possible. It is not
|
|
enabled by default. It is a good example for writing your
|
|
own handlers that will modify responses.
|
|
|
|
link:man:cowboy_decompress_h(3)[cowboy_decompress_h] will
|
|
automatically decompress request bodies when possible.
|
|
It is not enabled by default. It is a good example for
|
|
writing your own handlers that will modify requests.
|
|
|
|
link:man:cowboy_metrics_h(3)[cowboy_metrics_h] gathers
|
|
metrics about a stream then passes them to a configurable
|
|
function. It is not enabled by default.
|
|
|
|
link:man:cowboy_tracer_h(3)[cowboy_tracer_h] can be used to
|
|
conditionally trace streams based on the contents of the
|
|
request or its origin. Trace events are passed to a
|
|
configurable function. It is not enabled by default.
|