diff options
Diffstat (limited to 'doc/src/manual/cowboy_websocket.asciidoc')
| -rw-r--r-- | doc/src/manual/cowboy_websocket.asciidoc | 65 |
1 files changed, 53 insertions, 12 deletions
diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc index 5b1558c..f30ffca 100644 --- a/doc/src/manual/cowboy_websocket.asciidoc +++ b/doc/src/manual/cowboy_websocket.asciidoc @@ -126,7 +126,7 @@ timeout:: received first. {error, Reason}:: - A socket error ocurred. + A socket error occurred. == Types @@ -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:: @@ -198,13 +200,16 @@ Cowboy does it automatically for you. [source,erlang] ---- opts() :: #{ - active_n => pos_integer(), - compress => boolean(), - deflate_opts => cow_ws:deflate_opts() - idle_timeout => timeout(), - max_frame_size => non_neg_integer() | infinity, - req_filter => fun((cowboy_req:req()) -> map()), - validate_utf8 => boolean() + active_n => pos_integer(), + compress => boolean(), + data_delivery => stream_handlers | relay, + data_delivery_flow => pos_integer(), + 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()), + validate_utf8 => boolean() } ---- @@ -222,7 +227,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 @@ -238,6 +243,22 @@ Whether to enable the Websocket frame compression extension. Frames will only be compressed for the clients that support this extension. +data_delivery (stream_handlers):: + +HTTP/2+ only. Determines how data will be delivered +to the Websocket session process. `stream_handlers` +is the default and makes data go through stream +handlers. `relay` is a faster method introduced in +Cowboy 2.14 and sends data directly. `relay` is +intended to become the default in Cowboy 3.0. + +data_delivery_flow (pos_integer()):: + +When the `relay` data delivery method is used, +this value may be used to decide how much the +flow control window should be for the Websocket +stream. Currently only applies to HTTP/2. + deflate_opts (#{}):: Configuration for the permessage-deflate Websocket @@ -246,6 +267,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 +317,15 @@ normal circumstances if necessary. == Changelog +* *2.14*: The `data_delivery` and `data_delivery_flow` options + were added. The `relay` data delivery mechanism + provides a better way of forwarding data to + HTTP/2+ Websocket session processes. +* *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. * *2.7*: The commands based interface has been documented. The old interface is now deprecated. |