Appendix B. Migrating from Cowboy 2.10 to 2.11

Prev		Next

Cowboy 2.11 contains a variety of new features and bug fixes. Nearly all previously experimental features are now marked as stable, including Websocket over HTTP/2. Included is a fix for an HTTP/2 protocol CVE.

Cowboy 2.11 requires Erlang/OTP 24.0 or greater.

Cowboy is now using GitHub Actions for CI. The main reason for the move is to reduce costs by no longer having to self-host CI runners. The downside is that GitHub runners are less reliable and timing dependent tests are now more likely to fail.

B.1. Features added

A new HTTP/2 option max_cancel_stream_rate has been added to control the rate of stream cancellation the server will accept. By default Cowboy will accept 500 cancelled streams every 10 seconds.
A new stream handler cowboy_decompress_h has been added. It allows automatically decompressing incoming gzipped request bodies. It includes options to protect against zip bombs.
Websocket over HTTP/2 is no longer considered experimental. Note that the enable_connect_protocol option must be set to true in order to use Websocket over HTTP/2 for the time being.
Automatic mode for reading request bodies has been documented. In automatic mode, Cowboy waits indefinitely for data and sends a request_body message when data comes in. It mirrors {active, once} socket modes. This is ideal for loop handlers and is also used internally for HTTP/2 Websocket.
Ranged requests support is no longer considered experimental. It was added in 2.6 to both cowboy_static and cowboy_rest. Ranged responses can be produced either automatically (for the bytes unit) or manually. REST flowcharts have been updated with the new callbacks and steps related to handling ranged requests.
A new HTTP/1.1 and HTTP/2 option reset_idle_timeout_on_send has been added. When enabled, the idle_timeout will be reset every time Cowboy sends data to the socket.
Loop handlers may now return a timeout value in the place of hibernate. Timeouts behave the same as in gen_server.
The generate_etag callback of REST handlers now accepts undefined as a return value to allow conditionally generating etags.
The cowboy_compress_h options compress_threshold and compress_buffering are no longer considered experimental. They were de facto stable since 2.6 as they already were documented.
Functions cowboy:get_env/2,3 have been added.
Better error messages have been added when trying to send a 204 or 304 response with a body; when attempting to send two responses to a single request; when trying to push a response after the final response; when trying to send a set-cookie header without using cowboy_req:set_resp_cookie/3,4.

B.2. Features removed

Cowboy will no longer include the NPN extension when starting a TLS listener. This extension has long been deprecated and replaced with the ALPN extension. Cowboy will continue using the ALPN extension for protocol negotiation.

B.3. Bugs fixed

A fix was made to address the HTTP/2 CVE CVE-2023-44487 via the new HTTP/2 option max_cancel_stream_rate.
HTTP/1.1 requests that contain both a content-length and a transfer-encoding header will now be rejected to avoid security risks. Previous behavior was to ignore the content-length header as recommended by the HTTP RFC.
HTTP/1.1 connections would sometimes use the wrong timeout value to determine whether the connection should be closed. This resulted in connections staying up longer than intended. This should no longer be the case.
Cowboy now reacts to socket errors immediately for HTTP/1.1 and HTTP/2 when possible. Cowboy will notice when connections have been closed properly earlier than before. This also means that the socket option send_timeout_close will work as expected.
Shutting down HTTP/1.1 pipelined requests could lead to the current request being terminated before the response has been sent. This has been addressed.
When using HTTP/1.1 an invalid Connection header will now be rejected with a 400 status code instead of crashing.
The documentation now recommends increasing the HTTP/2 option max_frame_size_received. Cowboy currently uses the protocol default but will increase its default in a future release. Until then users are recommended to set the option to ensure larger requests are accepted and processed with acceptable performance.
Cowboy could sometimes send HTTP/2 WINDOW_UPDATE frames twice in a row. Now they should be consolidated.
Cowboy would sometimes send HTTP/2 WINDOW_UPDATE frames for streams that have stopped internally. This should no longer be the case.
The cowboy_compress_h stream handler will no longer attempt to compress responses that have an etag header to avoid caching issues.
The cowboy_compress_h will now always add accept-encoding to the vary header as it indicates that responses may be compressed.
Cowboy will now remove the trap_exit process flag when HTTP/1.1 connections upgrade to Websocket.
Exit gracefully instead of crashing when the socket gets closed when reading the PROXY header.
Missing cowboy_stream manual pages have been added.
A number of fixes were made to documentation and examples.