|
|
[appendix]
== Migrating from Cowboy 2.6 to 2.7
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.
In addition, many of the experimental features introduced
in previous releases have been marked stable and are now
documented.
Cowboy 2.7 requires Erlang/OTP 20.0 or greater.
=== Features added
* Cowboy is now compatible with both Ranch 1.7 and the
upcoming Ranch 2.0.
* 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`,
`connection_window_update_threshold`,
`max_connection_window_size`, `max_stream_window_size`,
`stream_window_margin_size` and
`stream_window_update_threshold`.
* 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.
* 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 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.
* 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
seconds.
* 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.
* Flow control for incoming data has been implemented
for HTTP/1.1. Cowboy will now wait for the user code
to ask for the request body before reading it from
the socket. The option `initial_stream_flow_size`
controls how much data Cowboy will read without
being asked.
* The HTTP/1.1 and HTTP/2 option `logger` is now
documented.
* 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.
* A new Websocket handler command `shutdown_reason`
can be used to change the normal exit reason of
Websocket processes. By default `normal` is used;
with this command the exit reason can be changed
to `{shutdown, ShutdownReason}`.
* 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
added.
* 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
(which have a string-based Javascript interface to
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
corrected.
* 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
headers.
* 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, resulting in crashes. The timeout
handling in HTTP/1.1 has been reworked and the issue should
no longer occur.
* 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
missing.
* 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.
|
