aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/guide/book.asciidoc2
-rw-r--r--doc/src/guide/constraints.asciidoc5
-rw-r--r--doc/src/guide/getting_started.asciidoc2
-rw-r--r--doc/src/guide/introduction.asciidoc4
-rw-r--r--doc/src/guide/migrating_from_2.12.asciidoc115
-rw-r--r--doc/src/guide/req.asciidoc11
-rw-r--r--doc/src/manual/cowboy_http.asciidoc39
-rw-r--r--doc/src/manual/cowboy_http2.asciidoc39
-rw-r--r--doc/src/manual/cowboy_req.set_resp_headers.asciidoc15
-rw-r--r--doc/src/manual/cowboy_websocket.asciidoc25
10 files changed, 239 insertions, 18 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index cf8c943..58eda34 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -75,6 +75,8 @@ include::performance.asciidoc[Performance]
= Additional information
+include::migrating_from_2.12.asciidoc[Migrating from Cowboy 2.12 to 2.13]
+
include::migrating_from_2.11.asciidoc[Migrating from Cowboy 2.11 to 2.12]
include::migrating_from_2.10.asciidoc[Migrating from Cowboy 2.10 to 2.11]
diff --git a/doc/src/guide/constraints.asciidoc b/doc/src/guide/constraints.asciidoc
index 6cc1075..4eade8a 100644
--- a/doc/src/guide/constraints.asciidoc
+++ b/doc/src/guide/constraints.asciidoc
@@ -91,6 +91,11 @@ int(forward, Value) ->
The value must be returned even if it is not converted
by the constraint.
+The two other operations are currently experimental. They are
+meant to help implement HATEOAS type services, but proper
+support for HATEOAS is not expected to be available before
+Cowboy 3.0 because of Cowboy's current router's limitations.
+
The `reverse` operation does the opposite: it
takes a converted value and changes it back to what the
user input would have been.
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index a26802d..06677ee 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -69,7 +69,7 @@ fetch and compile Cowboy, and that we will use releases:
PROJECT = hello_erlang
DEPS = cowboy
-dep_cowboy_commit = 2.11.0
+dep_cowboy_commit = 2.13.0
REL_DEPS = relx
diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc
index 519608d..3a03a78 100644
--- a/doc/src/guide/introduction.asciidoc
+++ b/doc/src/guide/introduction.asciidoc
@@ -35,14 +35,14 @@ guarantee that the experience will be safe and smooth. You are advised
to perform the necessary testing and security audits prior to deploying
on other platforms.
-Cowboy is developed for Erlang/OTP 22.0 and newer.
+Cowboy is developed for Erlang/OTP 24.0 and newer.
=== License
Cowboy uses the ISC License.
----
-Copyright (c) 2011-2024, Loïc Hoguin <[email protected]>
+Copyright (c) 2011-2025, Loïc Hoguin <[email protected]>
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
diff --git a/doc/src/guide/migrating_from_2.12.asciidoc b/doc/src/guide/migrating_from_2.12.asciidoc
new file mode 100644
index 0000000..d058db3
--- /dev/null
+++ b/doc/src/guide/migrating_from_2.12.asciidoc
@@ -0,0 +1,115 @@
+[appendix]
+== Migrating from Cowboy 2.12 to 2.13
+
+Cowboy 2.13 focuses on improving the performance of
+Websocket, as well as the HTTP protocols. It also
+contains a variety of new features and bug fixes.
+In addition, Cowboy 2.13 is the first Cowboy version
+that contains the experimental HTTP/3 support.
+
+Cowboy 2.13 requires Erlang/OTP 24.0 or greater.
+
+=== Features added
+
+* The option `dynamic_buffer` has been added. When
+ enabled, Cowboy will dynamically change the
+ `buffer` socket option based on how much data
+ it receives. It will start at 1024 bytes and
+ go up to 131072 bytes by default. This applies
+ to HTTP/1.1, HTTP/2 and Websocket. The performance
+ gains are very important depending on the scenario.
+
+* HTTP/1.1 and HTTP/2 now accept the `hibernate`
+ option. When set the connection process will
+ automatically hibernate to reduce memory usage
+ at a small performance cost.
+
+* The `protocols` and `alpn_default_protocol` protocol
+ options have been added to control exactly which
+ HTTP protocols are allowed over clear and TLS listeners.
+
+* The Websocket `max_frame_size` option can now be
+ set dynamically via the `set_options` command.
+ This allows configuring a smaller max size and
+ increase it after authentication or other checks.
+
+* `cowboy_req:set_resp_headers` now accept lists of
+ headers. This can be used to simplify passing
+ headers coming from client applications such as
+ Gun. Note that the set-cookie header cannot be
+ provided using this function.
+
+* `cowboy_rest` now always sets the allow header.
+
+* Update Ranch to 1.8.1.
+
+* Update Cowlib to 2.14.0.
+
+* When using Hex.pm, version check requirements will
+ now be relaxed. Cowboy will accept any Ranch version
+ from 1.8.0 to 2.2.0 as well as future 2.x versions.
+ Similarly, any Cowlib 2.x version from 2.14.0 will
+ be accepted.
+
+=== Experimental features added
+
+* Experimental support for HTTP/3 has been added,
+ including Websocket over HTTP/3. HTTP/3 support
+ is disabled by default; to enable, the environment
+ variable COWBOY_QUICER must be set at compile-time.
+
+=== Features deprecated
+
+* The `inactivity_timeout` option is now deprecated
+ for all protocols. It is de facto ignored when
+ `hibernate` is enabled.
+
+=== Optimisation-related changes
+
+* The behavior of the `idle_timeout` timer has been
+ changed for HTTP/2 and Websocket. Cowboy used to
+ reset the timer on every data packet received from
+ the socket. Now Cowboy will check periodically
+ whether new data was received in the interval.
+
+* URI and query string hex encoding and decoding has
+ been optimised.
+
+* Websocket UTF-8 validation of text frames has been
+ optimised.
+
+* Websocket unmasking has been optimised.
+
+=== Bugs fixed
+
+* HTTP/1.1 upgrade to HTTP/2 is now disabled over TLS,
+ as HTTP/2 over TLS must be negotiated via ALPN.
+
+* `cowboy_req:filter_cookies` could miss valid cookies.
+ It has been corrected.
+
+* HTTP/1.1 could get to a state where it would stop
+ receiving data from the socket, or buffer the data
+ without processing it, and the connection eventually
+ time out. This has been fixed.
+
+* Websocket did not compress zero-length frames properly.
+ This resulted in decompression errors in the client.
+ This has been corrected.
+
+* Websocket compression will now be disabled when only
+ the server sets `client_max_window_bits`, as otherwise
+ decompression errors will occur.
+
+* Websocket will now apply `max_frame_size` both to
+ compressed frames as well as the uncompressed payload.
+ Cowboy will stop decompressing when the limit is
+ reached.
+
+* Cowboy now properly handles exits of request processes
+ that occurred externally (e.g. via `exit/2`).
+
+* Invalid return values from `content_types_provided`
+ could result in an atom sent to the socket, leading
+ to a cryptic error message. The invalid value will
+ now result in a better error message.
diff --git a/doc/src/guide/req.asciidoc b/doc/src/guide/req.asciidoc
index 754e470..6b95228 100644
--- a/doc/src/guide/req.asciidoc
+++ b/doc/src/guide/req.asciidoc
@@ -258,7 +258,8 @@ contain two parameters of name `key`.
The same is true when trying to use the PHP-style suffix `[]`.
When a query string is `key[]=1&key[]=2`, the list returned will
-contain two parameters of name `key[]`.
+contain two parameters of name `key[]`. Cowboy does not require
+the `[]` suffix to properly handle repeated key names.
When a query string is simply `key`, Cowboy will return the
list `[{<<"key">>, true}]`, using `true` to indicate that the
@@ -291,9 +292,11 @@ If no default is provided and the value is missing, the
query string is deemed invalid and the process will crash.
When the query string is `key=1&key=2`, the value for `key`
-will be the list `[1, 2]`. Parameter names do not need to
-include the PHP-style suffix. Constraints may be used to
-ensure that only one value was passed through.
+will be the list `[<<"1">>, <<"2">>]`. Parameter names do not
+need to include the PHP-style suffix. Constraints may be used
+to ensure that only one value was given. Constraints do not
+automatically look inside the list, a custom constraint must
+be written if that is necessary.
=== Headers
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.
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-16 18:41:31 +0000