diff options
Diffstat (limited to 'doc/src/manual/cowboy_http2.asciidoc')
| -rw-r--r-- | doc/src/manual/cowboy_http2.asciidoc | 82 |
1 files changed, 78 insertions, 4 deletions
diff --git a/doc/src/manual/cowboy_http2.asciidoc b/doc/src/manual/cowboy_http2.asciidoc index de632be..7b34b88 100644 --- a/doc/src/manual/cowboy_http2.asciidoc +++ b/doc/src/manual/cowboy_http2.asciidoc @@ -18,12 +18,15 @@ as a Ranch protocol. ---- opts() :: #{ active_n => pos_integer(), + alpn_default_protocol => http | http2, connection_type => worker | supervisor, connection_window_margin_size => 0..16#7fffffff, connection_window_update_threshold => 0..16#7fffffff, + dynamic_buffer => false | {pos_integer(), pos_integer()}, enable_connect_protocol => boolean(), goaway_initial_timeout => timeout(), goaway_complete_timeout => timeout(), + hibernate => boolean(), idle_timeout => timeout(), inactivity_timeout => timeout(), initial_connection_window_size => 65535..16#7fffffff, @@ -35,14 +38,18 @@ opts() :: #{ max_connection_window_size => 0..16#7fffffff, max_decode_table_size => non_neg_integer(), max_encode_table_size => non_neg_integer(), + max_fragmented_header_block_size => 16384..16#7fffffff, max_frame_size_received => 16384..16777215, max_frame_size_sent => 16384..16777215 | infinity, max_received_frame_rate => {pos_integer(), timeout()}, max_reset_stream_rate => {pos_integer(), timeout()}, + max_cancel_stream_rate => {pos_integer(), timeout()}, max_stream_buffer_size => non_neg_integer(), max_stream_window_size => 0..16#7fffffff, preface_timeout => timeout(), + protocols => [http | http2], proxy_header => boolean(), + reset_idle_timeout_on_send => boolean(), sendfile => boolean(), settings_timeout => timeout(), stream_handlers => [module()], @@ -63,7 +70,7 @@ Ranch functions `ranch:get_protocol_options/1` and The default value is given next to the option name: -active_n (100):: +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 @@ -71,6 +78,12 @@ 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. +alpn_default_protocol (http):: + +Default protocol to use when the client connects over TLS +without ALPN. Can be set to `http2` to disable HTTP/1.1 +entirely. + connection_type (supervisor):: Whether the connection process also acts as a supervisor. @@ -88,11 +101,25 @@ The connection window will only get updated when its size becomes lower than this threshold, in bytes. This is to avoid sending too many `WINDOW_UPDATE` frames. +dynamic_buffer ({1024, 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. + enable_connect_protocol (false):: Whether to enable the extended CONNECT method to allow protocols like Websocket to be used over an HTTP/2 stream. -This option is experimental and disabled by default. ++ +For backward compatibility reasons, this option is disabled +by default. It must be enabled to use Websocket over HTTP/2. +It will be enabled by default in a future release. goaway_initial_timeout (1000):: @@ -104,13 +131,17 @@ goaway_complete_timeout (3000):: Time in ms to wait for ongoing streams to complete before closing the connection during a graceful shutdown. +hibernate (false):: + +Whether the connection process will hibernate automatically. + 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. +**DEPRECATED** Time in ms with nothing received at all before Cowboy closes the connection. initial_connection_window_size (65535):: @@ -167,11 +198,25 @@ Maximum header table size in bytes used by the encoder. The server will compare this value to what the client advertises and choose the smallest one as the encoder's header table size. +max_fragmented_header_block_size (32768):: + +Maximum header block size when headers are split over multiple HEADERS +and CONTINUATION frames. Clients that attempt to send header blocks +larger than this value will receive an ENHANCE_YOUR_CALM connection +error. Note that this value is not advertised and should be large +enough for legitimate requests. + max_frame_size_received (16384):: Maximum size in bytes of the frames received by the server. This value is advertised to the remote endpoint which can then decide to use any value lower or equal for its frame sizes. ++ +It is highly recommended to increase this value for performance reasons. +In a future Cowboy version the default will be increased to 1MB (1048576). +Too low values may result in very large file uploads failing because +Cowboy will detect the large number of frames as flood and close the +connection. max_frame_size_sent (infinity):: @@ -198,6 +243,14 @@ the number of streams that can be reset over a certain time period. The rate is expressed as a tuple `{NumResets, TimeMs}`. This is similar to a supervisor restart intensity/period. +max_cancel_stream_rate ({500, 10000}):: + +Maximum cancel stream rate per connection. This can be used to +protect against misbehaving or malicious peers, by limiting the +number of streams that the peer can reset over a certain time period. +The rate is expressed as a tuple `{NumCancels, TimeMs}`. This is +similar to a supervisor restart intensity/period. + max_stream_buffer_size (8000000):: Maximum stream buffer size in bytes. This is a soft limit used @@ -214,12 +267,24 @@ preface_timeout (5000):: Time in ms Cowboy is willing to wait for the connection preface. +protocols ([http2, http]):: + +Protocols that may be used when the client connects over +cleartext TCP. The default is to allow both HTTP/1.1 and +HTTP/2. HTTP/1.1 and HTTP/2 can be disabled entirely by +omitting them from the list. + 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. +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 @@ -256,6 +321,15 @@ too many `WINDOW_UPDATE` frames. == Changelog +* *2.13*: The `inactivity_timeout` option was deprecated. +* *2.13*: The `active_n` default value was changed to `1`. +* *2.13*: The `dynamic_buffer` and `hibernate` options were added. +* *2.11*: Websocket over HTTP/2 is now considered stable. +* *2.11*: The `reset_idle_timeout_on_send` option was added. +* *2.11*: Add the option `max_cancel_stream_rate` to protect + against another flood scenario. +* *2.9*: The `goaway_initial_timeout` and `goaway_complete_timeout` + options were added. * *2.8*: The `active_n` option was added. * *2.8*: The `linger_timeout` option was added. * *2.8*: The `max_received_frame_rate` default value has @@ -281,7 +355,7 @@ too many `WINDOW_UPDATE` frames. `max_frame_size_received`, `max_frame_size_sent` and `settings_timeout` to configure HTTP/2 SETTINGS and related behavior. -* *2.4*: Add the experimental option `enable_connect_protocol`. +* *2.4*: Add the option `enable_connect_protocol`. * *2.0*: Protocol introduced. == See also |