blob: 0ac84cec7d3e77656eedf282140ca848875f4ac7 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
[[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_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.
|
