aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_http.asciidoc
blob: 3c33ab720bc5d36e7d53a1c339399adce15d199e (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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
= cowboy_http(3)

== Name

cowboy_http - HTTP/1.1

== Description

The module `cowboy_http` implements HTTP/1.1 and HTTP/1.0
as a Ranch protocol.

== Options

// @todo Might be worth moving cowboy_clear/tls/stream_h options
// to their respective manual, when they are added.

[source,erlang]
----
opts() :: #{
    chunked                 => boolean(),
    connection_type         => worker | supervisor,
    env                     => cowboy_middleware:env(),
    http10_keepalive        => boolean(),
    idle_timeout            => timeout(),
    inactivity_timeout      => timeout(),
    linger_timeout          => timeout(),
    max_empty_lines         => non_neg_integer(),
    max_header_name_length  => non_neg_integer(),
    max_header_value_length => non_neg_integer(),
    max_headers             => non_neg_integer(),
    max_keepalive           => non_neg_integer(),
    max_method_length       => non_neg_integer(),
    max_request_line_length => non_neg_integer(),
    max_skip_body_length    => non_neg_integer(),
    middlewares             => [module()],
    proxy_header            => boolean(),
    request_timeout         => timeout(),
    sendfile                => boolean(),
    shutdown_timeout        => timeout(),
    stream_handlers         => [module()]
}
----

Configuration for the HTTP/1.1 protocol.

This configuration is passed to Cowboy when starting listeners
using `cowboy:start_clear/3` or `cowboy:start_tls/3` functions.

It can be updated without restarting listeners using the
Ranch functions `ranch:get_protocol_options/1` and
`ranch:set_protocol_options/2`.

The default value is given next to the option name:

chunked (true)::

Whether chunked transfer-encoding is enabled for HTTP/1.1 connections.
Note that a response streamed to the client without the chunked
transfer-encoding and without a content-length header will result
in the connection being closed at the end of the response body.

connection_type (supervisor)::

Whether the connection process also acts as a supervisor.

env (#{})::

Middleware environment.

http10_keepalive (true)::

Whether keep-alive is enabled for HTTP/1.0 connections.

idle_timeout (60000)::

Time in ms with no data received before Cowboy closes the connection.

inactivity_timeout (300000)::

Time in ms with nothing received at all before Cowboy closes the connection.

linger_timeout (1000)::

Time in ms that Cowboy will wait when closing the connection. This is
necessary to avoid the TCP reset problem as described in the
https://tools.ietf.org/html/rfc7230#section-6.6[section 6.6 of RFC7230].

max_empty_lines (5)::

Maximum number of empty lines before a request.

max_header_name_length (64)::

Maximum length of header names.

max_header_value_length (4096)::

Maximum length of header values.

max_headers (100)::

Maximum number of headers allowed per request.

max_keepalive (100)::

Maximum number of requests allowed per connection.

max_method_length (32)::

Maximum length of the method.

max_request_line_length (8000)::

Maximum length of the request line.

max_skip_body_length (1000000)::

Maximum length Cowboy is willing to skip when the user code did not read the body fully.
When the remaining length is too large or unknown Cowboy will close the connection.

middlewares ([cowboy_router, cowboy_handler])::

Middlewares to run for every request.

proxy_header (false)::

Whether incoming connections have a PROXY protocol header. The
proxy information will be passed forward via the `proxy_header`
key of the Req object.

request_timeout (5000)::

Time in ms with no requests before Cowboy closes the connection.

sendfile (true)::

Whether the sendfile syscall may be used. It can be useful to disable
it on systems where the syscall has a buggy implementation, for example
under VirtualBox when using shared folders.

shutdown_timeout (5000)::

Time in ms Cowboy will wait for child processes to shut down before killing them.

stream_handlers ([cowboy_stream_h])::

Ordered list of stream handlers that will handle all stream events.

== Changelog

* *2.6*: The `chunked`, `http10_keepalive`, `proxy_header` and `sendfile` options were added.
* *2.5*: The `linger_timeout` option was added.
* *2.2*: The `max_skip_body_length` option was added.
* *2.0*: The `timeout` option was renamed `request_timeout`.
* *2.0*: The `idle_timeout`, `inactivity_timeout` and `shutdown_timeout` options were added.
* *2.0*: The `max_method_length` option was added.
* *2.0*: The `max_request_line_length` default was increased from 4096 to 8000.
* *2.0*: The `connection_type` option was added.
* *2.0*: The `env` option is now a map instead of a proplist.
* *2.0*: The `stream_handlers` option was added.
* *2.0*: The `compress` option was removed in favor of the `cowboy_compress_h` stream handler.
* *2.0*: Options are now a map instead of a proplist.
* *2.0*: Protocol introduced. Replaces `cowboy_protocol`.

== See also

link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_http2(3)[cowboy_http2(3)],
link:man:cowboy_websocket(3)[cowboy_websocket(3)]