mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-14 04:10:24 +00:00
49be0f57cf
Cowboy will set the socket's buffer size dynamically to better fit the current workload. When the incoming data is small, a low buffer size reduces the memory footprint and improves responsiveness and therefore performance. When the incoming data is large, such as large HTTP request bodies, a larger buffer size helps us avoid doing too many binary appends and related allocations. Setting a large buffer size for all use cases is sub-optimal because allocating more than needed necessarily results in a performance hit (not just increased memory usage). By default Cowboy starts with a buffer size of 8192 bytes. It then doubles or halves the buffer size depending on the size of the data it receives from the socket. It stops decreasing at 8192 and increasing at 131072 by default. To keep track of the size of the incoming data Cowboy maintains a moving average. It allows Cowboy to avoid changing the buffer too often but still react quickly when necessary. Cowboy will increase the buffer size when the moving average is above 90% of the current buffer size, and decrease when the moving average is below 40% of the current buffer size. The current buffer size and moving average are propagated when switching protocols. The dynamic buffer is implemented in HTTP/1, HTTP/2 and HTTP/1 Websocket. HTTP/2 Websocket has it disabled because it doesn't interact directly with the socket; in that case it is HTTP/2 that has a dynamic buffer. The dynamic buffer provides a very large performance improvement in many scenarios, at minimal cost for others. Because it largely depend on the underlying protocol the improvements are no all equal. TLS and compression also impact the results. The improvement when reading a large request body, with the requests repeated in a fast loop are: * HTTP: 6x to 20x faster * HTTPS: 2x to 6x faster * H2: 4x to 5x faster * H2C: 20x to 40x faster I am not sure why H2C's performance was so bad, especially compared to H2, when using default buffer sizes. Dynamic buffers make H2C a lot more viable with default settings. The performance impact on "hello world" type requests is minimal, it goes from -5% to +5% roughly. Websocket improvements vary again depending on the protocol, but also depending on whether compression is enabled: * HTTP echo: roughly 2x faster * HTTP send: roughly 4x faster * H2C echo: roughly 2x faster * H2C send: 3x to 4x faster In the echo test we reply back, and Gun doesn't have the dynamic buffer optimisation, so that probably explains the x2 difference. With compression however there isn't much improvement. The results are roughly within -10% to +10% of each other. Zlib compression seems to be a bottleneck, or at least to modify the performance profile to such an extent that the size of the buffer does not matter. This happens to randomly generated binary data as well so it is probably not caused by the test data.
204 lines
6.3 KiB
Text
204 lines
6.3 KiB
Text
= 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 options
|
|
// to their respective manual, when they are added.
|
|
|
|
[source,erlang]
|
|
----
|
|
opts() :: #{
|
|
active_n => pos_integer(),
|
|
chunked => boolean(),
|
|
connection_type => worker | supervisor,
|
|
dynamic_buffer => false | {pos_integer(), pos_integer()},
|
|
http10_keepalive => boolean(),
|
|
idle_timeout => timeout(),
|
|
inactivity_timeout => timeout(),
|
|
initial_stream_flow_size => non_neg_integer(),
|
|
linger_timeout => timeout(),
|
|
logger => module(),
|
|
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(),
|
|
proxy_header => boolean(),
|
|
request_timeout => timeout(),
|
|
reset_idle_timeout_on_send => boolean(),
|
|
sendfile => boolean(),
|
|
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:
|
|
|
|
active_n (1)::
|
|
|
|
The number of packets Cowboy will request from the socket at once.
|
|
This can be used to tweak the performance of the server. Higher
|
|
values reduce the number of times Cowboy need to request more
|
|
packets from the port driver at the expense of potentially
|
|
higher memory being used.
|
|
|
|
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.
|
|
+
|
|
This option can be updated at any time using the
|
|
`set_options` stream handler command.
|
|
|
|
connection_type (supervisor)::
|
|
|
|
Whether the connection process also acts as a supervisor.
|
|
|
|
dynamic_buffer ({8192, 131072})::
|
|
|
|
Cowboy will dynamically change the socket's `buffer` size
|
|
depending on the size of the data it receives from the socket.
|
|
This lets Cowboy use the optimal buffer size for the current
|
|
workload.
|
|
+
|
|
The dynamic buffer size functionality can be disabled by
|
|
setting this option to `false`. Cowboy will also disable
|
|
it by default when the `buffer` transport option is configured.
|
|
|
|
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.
|
|
+
|
|
This option can be updated at any time using the
|
|
`set_options` stream handler command.
|
|
|
|
inactivity_timeout (300000)::
|
|
|
|
Time in ms with nothing received at all before Cowboy closes the connection.
|
|
|
|
initial_stream_flow_size (65535)::
|
|
|
|
Amount of data in bytes Cowboy will read from the socket
|
|
right after a request was fully received. This is a soft
|
|
limit.
|
|
|
|
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].
|
|
|
|
logger (error_logger)::
|
|
|
|
The module that will be used to write log messages.
|
|
|
|
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 (1000)::
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
reset_idle_timeout_on_send (false)::
|
|
|
|
Whether the `idle_timeout` gets reset when sending data
|
|
to the socket.
|
|
|
|
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.
|
|
|
|
stream_handlers ([cowboy_stream_h])::
|
|
|
|
Ordered list of stream handlers that will handle all stream events.
|
|
|
|
== Changelog
|
|
|
|
* *2.13*: The `active_n` default value was changed to `1`.
|
|
* *2.13*: The `dynamic_buffer` option was added.
|
|
* *2.11*: The `reset_idle_timeout_on_send` option was added.
|
|
* *2.8*: The `active_n` option was added.
|
|
* *2.7*: The `initial_stream_flow_size` and `logger` options were added.
|
|
* *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)]
|