diff options
Diffstat (limited to 'doc/src/manual')
| -rw-r--r-- | doc/src/manual/cowboy_http.asciidoc | 39 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_http2.asciidoc | 39 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_req.set_resp_headers.asciidoc | 15 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_websocket.asciidoc | 25 |
4 files changed, 107 insertions, 11 deletions
diff --git a/doc/src/manual/cowboy_http.asciidoc b/doc/src/manual/cowboy_http.asciidoc index 58f0435..96a5585 100644 --- a/doc/src/manual/cowboy_http.asciidoc +++ b/doc/src/manual/cowboy_http.asciidoc @@ -18,8 +18,11 @@ as a Ranch protocol. ---- opts() :: #{ active_n => pos_integer(), + alpn_default_protocol => http | http2, chunked => boolean(), connection_type => worker | supervisor, + dynamic_buffer => false | {pos_integer(), pos_integer()}, + hibernate => boolean(), http10_keepalive => boolean(), idle_timeout => timeout(), inactivity_timeout => timeout(), @@ -34,6 +37,7 @@ opts() :: #{ max_method_length => non_neg_integer(), max_request_line_length => non_neg_integer(), max_skip_body_length => non_neg_integer(), + protocols => [http | http2], proxy_header => boolean(), request_timeout => timeout(), reset_idle_timeout_on_send => boolean(), @@ -53,7 +57,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 @@ -61,6 +65,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. + chunked (true):: Whether chunked transfer-encoding is enabled for HTTP/1.1 connections. @@ -75,6 +85,21 @@ connection_type (supervisor):: Whether the connection process also acts as a supervisor. +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. + +hibernate (false):: + +Whether the connection process will hibernate automatically. + http10_keepalive (true):: Whether keep-alive is enabled for HTTP/1.0 connections. @@ -88,7 +113,7 @@ This option can be updated at any time using the 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_stream_flow_size (65535):: @@ -139,6 +164,13 @@ 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. +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 @@ -166,6 +198,9 @@ Ordered list of stream handlers that will handle all stream events. == 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*: 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. diff --git a/doc/src/manual/cowboy_http2.asciidoc b/doc/src/manual/cowboy_http2.asciidoc index 1d2619c..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, @@ -44,6 +47,7 @@ opts() :: #{ 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(), @@ -66,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 @@ -74,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. @@ -91,6 +101,17 @@ 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 @@ -110,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):: @@ -242,6 +267,13 @@ 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 @@ -289,6 +321,9 @@ 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 diff --git a/doc/src/manual/cowboy_req.set_resp_headers.asciidoc b/doc/src/manual/cowboy_req.set_resp_headers.asciidoc index 63fe424..9ca5901 100644 --- a/doc/src/manual/cowboy_req.set_resp_headers.asciidoc +++ b/doc/src/manual/cowboy_req.set_resp_headers.asciidoc @@ -11,7 +11,7 @@ cowboy_req:set_resp_headers - Set several response headers set_resp_headers(Headers, Req :: cowboy_req:req()) -> Req -Headers :: cowboy:http_headers() +Headers :: cowboy:http_headers() | [{binary(), iodata()}] ---- Set several headers to be sent with the response. @@ -32,8 +32,16 @@ instead of this function to set cookies. Headers:: -Headers as a map with keys being lowercase binary strings, -and values as binary strings. +Headers as a map with names being lowercase binary strings, +and values as iodata; or as a list with the same requirements +for names and values. ++ +When a list is given it is converted to its equivalent map, +with duplicate headers concatenated with a comma inserted +in-between. Support for lists is meant to simplify using +data from clients or other applications. ++ +The set-cookie header must not be set using this function. Req:: @@ -48,6 +56,7 @@ otherwise the headers will not be sent in the response. == Changelog +* *2.13*: The function now accepts a list of headers. * *2.0*: Function introduced. == Examples diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc index 6d822d9..319dbae 100644 --- a/doc/src/manual/cowboy_websocket.asciidoc +++ b/doc/src/manual/cowboy_websocket.asciidoc @@ -138,7 +138,9 @@ commands() :: [Command] Command :: {active, boolean()} | {deflate, boolean()} - | {set_options, #{idle_timeout => timeout()}} + | {set_options, #{ + idle_timeout => timeout(), + max_frame_size => non_neg_integer() | infinity}} | {shutdown_reason, any()} | Frame :: cow_ws:frame() ---- @@ -159,8 +161,8 @@ effect on connections that did not negotiate compression. set_options:: -Set Websocket options. Currently only the option `idle_timeout` -may be updated from a Websocket handler. +Set Websocket options. Currently only the options `idle_timeout` +and `max_frame_size` may be updated from a Websocket handler. shutdown_reason:: @@ -201,6 +203,7 @@ opts() :: #{ active_n => pos_integer(), compress => boolean(), deflate_opts => cow_ws:deflate_opts() + dynamic_buffer => false | {pos_integer(), pos_integer()}, idle_timeout => timeout(), max_frame_size => non_neg_integer() | infinity, req_filter => fun((cowboy_req:req()) -> map()), @@ -222,7 +225,7 @@ init(Req, State) -> 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 @@ -246,6 +249,17 @@ options and the zlib compression options. The defaults optimize the compression at the expense of some memory and CPU. +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. + idle_timeout (60000):: Time in milliseconds that Cowboy will keep the @@ -285,6 +299,9 @@ normal circumstances if necessary. == Changelog +* *2.13*: The `active_n` default value was changed to `1`. +* *2.13*: The `dynamic_buffer` option was added. +* *2.13*: The `max_frame_size` option can now be set dynamically. * *2.11*: Websocket over HTTP/2 is now considered stable. * *2.11*: HTTP/1.1 Websocket no longer traps exits by default. * *2.8*: The `active_n` option was added. |