|author||Loïc Hoguin <[email protected]>||2019-10-07 17:48:45 +0200|
|committer||Loïc Hoguin <[email protected]>||2019-10-07 17:48:45 +0200|
Add migration guide for Cowboy 2.7
3 files changed, 198 insertions, 30 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 2101407..f5989eb 100644
@@ -73,7 +73,7 @@ include::middlewares.asciidoc[Middlewares]
= Additional information
-include::migrating_from_2.6.asciidoc[Changes since Cowboy 2.6]
+include::migrating_from_2.6.asciidoc[Migrating from Cowboy 2.6 to 2.7]
include::migrating_from_2.5.asciidoc[Migrating from Cowboy 2.5 to 2.6]
diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc
index 1f9b52e..18023ae 100644
@@ -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 19.0 and newer.
+Cowboy is developed for Erlang/OTP 20.0 and newer.
Cowboy uses the ISC License.
-Copyright (c) 2011-2017, Loïc Hoguin <[email protected]>
+Copyright (c) 2011-2019, 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.6.asciidoc b/doc/src/guide/migrating_from_2.6.asciidoc
index 1e85f14..a735ef9 100644
@@ -1,41 +1,209 @@
-== Changes since Cowboy 2.6
+== Migrating from Cowboy 2.6 to 2.7
-The following patch versions were released since Cowboy 2.6:
+Cowboy 2.7 improves the HTTP/2 code with optimizations
+around the sending of DATA and WINDOW_UPDATE frames;
+graceful shutdown of the connection when the client is
+going away; and rate limiting mechanisms. New options
+and mechanisms have also been added to control the
+amount of memory Cowboy ends up using with both HTTP/1.1
+and HTTP/2. Much, but not all, of this work was done
+to address HTTP/2 CVEs about potential denial of service.
-=== Cowboy 2.6.3
+In addition, many of the experimental features introduced
+in previous releases have been marked stable and are now
-This release updates Cowlib to 2.7.3 to fix the `vsn`
-value in the 'cowlib.app' file that was causing issues
-to Elixir users.
+Cowboy 2.7 requires Erlang/OTP 20.0 or greater.
-=== Cowboy 2.6.2
+=== Features added
-This release updates Cowlib to 2.7.2.
+* Cowboy is now compatible with both Ranch 1.7 and the
+ upcoming Ranch 2.0.
-A bug in the HTTP/2 code that resulted in the failure to
-fully send iolist response bodies has been fixed. Cowboy
-would just wait indefinitely in those cases.
+* The number of HTTP/2 WINDOW_UPDATE frames Cowboy sends
+ has been greatly reduced. Cowboy now applies heuristics
+ to determine whether it is necessary to update the window,
+ based on the current window size and the amount of data
+ requested by streams (the `cowboy_req:read_body/2` length
+ for example). Six new options have been added to control
+ this behavior: `connection_window_margin_size`,
+ `max_connection_window_size`, `max_stream_window_size`,
+ `stream_window_margin_size` and
-Cowboy will now use the host header when the HTTP/2
-:authority pseudo header is missing. A common scenario
-where this occurs is when proxies translate incoming
-HTTP/1.1 requests to HTTP/2.
+* HTTP/2 connections will now be shut down gracefully
+ when receiving a GOAWAY frame. Cowboy will simply
+ wait for existing streams to finish before closing
+ the connection.
-The `cowboy_static` handler will now properly detect
-the type of files that have an uppercase or mixed
+* Functions that stream the response body now have
+ backpressure applied. They now wait for a message
+ to be sent back. The message will be held off when
+ using HTTP/2 and the buffer sizes exceed either
+ `max_connection_buffer_size` or `max_stream_buffer_size`.
+ For HTTP/1.1 the data is sent synchronously and we
+ rely instead on the TCP backpressure.
-A bug where the stacktrace was incorrect in error messages
-has been fixed. The problem occurred when an exception
-occurred in the handler's terminate callback.
+* A new HTTP/2 option `stream_window_data_threshold`
+ can be used to control how little the DATA frames that
+ Cowboy sends can get. By default Cowboy will wait for
+ the window to be large enough to send either everything
+ queued or to reach the default maximum frame size of
+ 16384 bytes.
-Minor documentation fixes.
+* A new HTTP/2 option `max_receive_frame_rate` can be
+ used to control how fast the server is willing to receive
+ frames. By default it will accept 1000 frames every 10
-=== Cowboy 2.6.1
+* A new HTTP/2 option `max_reset_stream_rate` can be
+ used to control the rate of errors the server is
+ willing to accept. By default it will accept 10
+ stream resets every 10 seconds.
-This release updates Ranch to 1.7.1.
+* The HTTP/1.1 and HTTP/2 option `logger` is now
-It fixes an issue with the PROXY protocol where the wrong
-CRC32 algorithm was used and would cause checksum
-verification to fail.
+* The Websocket option `validate_utf8` has been
+ added. It can be used to disable the expensive UTF-8
+ validation for incoming text and close frames.
+* The experimental commands based Websocket interface
+ is now considered stable and has been documented.
+ The old interface is now deprecated.
+* The experimental stream handlers `cowboy_metrics_h`
+ and `cowboy_tracer_h` are now considered stable and
+ have been documented.
+* The stream handler commands `set_options` and `log`
+ are now considered stable and have been documented.
+* The router is now capable of retrieving dispatch
+ rules directly from the `persistent_term` storage
+ (available starting from Erlang/OTP 21.2).
+* Support for the status codes 208 and 508 has been
+* Update Ranch to 1.7.1.
+* Update Cowlib to 2.8.0.
+=== Experimental features added
+* It is now possible to read the response body from any
+ process, as well as doing any other `cowboy_req`
+ operations. Since this is not recommended due to
+ race condition concerns this feature will always
+ remain experimental.
+=== New functions
+* The function `cowboy_req:filter_cookies/2` has been
+ added. It can be called before parsing/matching
+ cookies in order to filter out undesirables. The
+ main reason for doing this is to avoid most parse
+ errors that may occur when dealing with Web browsers
+ cookies that is very permissive of invalid content)
+ and to be able to recover in other cases.
+* The function `cowboy_req:cast/2` has been added.
+ It can be used to send events to stream handlers.
+=== Bugs fixed
+* A number of fixes and additions were made to address the
+ HTTP/2 CVEs CVE-2019-9511 through CVE-2019-9518, except
+ for CVE-2019-9513 which required no intervention as the
+ relevant protocol feature is not implemented by Cowboy.
+* The HTTP/2 connection window could become larger than the
+ protocol allows, leading to errors. This has been corrected.
+* The presence of empty header names in HTTP/2 requests now
+ results in the request to be rejected.
+* Cowboy will now remove headers specific to HTTP/1.1
+ (the hop by hop headers such as connection or upgrade)
+ when building an HTTP/2 response.
+* A bug in the HTTP/2 code that resulted in the failure to
+ fully send iolist response bodies has been fixed. Cowboy
+ would just wait indefinitely in those cases.
+* It was possible for a final empty HTTP/2 DATA frame to get
+ stuck and never sent when the window reached 0 and the remote
+ end did not increase the window anymore. This has been
+* Cowboy now uses the host header when the HTTP/2
+ :authority pseudo header is missing. A common scenario
+ where this occurs is when proxies translate incoming
+ HTTP/1.1 requests to HTTP/2.
+* HTTP/1.1 connections are now properly closed when the
+ user code sends less data than advertised in the response
+* Cowboy will now close HTTP/1.1 connections immediately when
+ a header line is missing a colon separator. Previously it
+ was waiting for more data.
+* It was possible for Cowboy to receive stray timeout messages
+ for HTTP/1.1 connections. This has been addressed.
+* The type for the Req object has been updated to accept
+ custom fields as was already documented.
+* The authentication scheme returned when parsing the
+ authorization header is now case insensitive, which
+ means it will be returned as lowercase.
+* Cowboy no longer discards data that follows a Websocket
+ upgrade request. Note that the protocol does not allow
+ sending data before receiving a successful Websocket
+ upgrade response, so this fix is more out of principle
+ rather than to fix a real world issue.
+* The `cowboy_static` handler will now properly detect
+ the type of files that have an uppercase or mixed
+ extension component.
+* The `cowboy_static` handler is now consistent across all
+ supported platforms. It now explicitly rejects `path_info`
+ components that include a forward slash, backward slash
+ or NUL character.
+* The update to Ranch 1.7.1 fixes an issue with the PROXY
+ protocol that would cause checksum verification to fail.
+* The HTTP/1.1 error reason for `stream_error` mistakenly
+ contained an extra element. It has now been removed.
+* The `PartialReq` given to the `early_error` stream handler
+ callback now includes headers when the protocol is HTTP/2.
+* A bug where the stacktrace was incorrect in error messages
+ has been fixed. The problem occurred when an exception
+ occurred in the handler's terminate callback.
+* The REST flowchart for POST, PATCH and PUT has received
+ a number of fixes and had to be greatly reworked as a
+ result. When the method is PUT, we do not check for
+ the location header in the response. When the resource
+ doesn't exist and the method was PUT the flowchart was
+ largely incorrect. A 415 response may occur after the
+ `content_types_accepted` callback and was missing from
+ the flowchart.
+* The documentation for `content_types_accepted` now
+ includes the media type wildcard that was previously
+* The documentation for a type found in `cow_cookie`
+ was missing. A manual page for `cow_cookie` was added
+ and can be found in the Cowlib documentation.