Migrating from Cowboy 2.7 to 2.8

Cowboy 2.8 contains many optimizations for all protocols. HTTP/1.1 has received the largest improvements and Cowboy will now be able to handle noticeably more requests. Thanks to the folks at Stressgrid for helping identify that the performance was lower than it should have been and for benchmarking my many changes and experiments.

Cowboy 2.8 also contains a small number of tweaks and bug fixes. Cowboy 2.8 is the first Cowboy release, ever, to be consistently green on all tested platforms. This is mostly due to the reworking of some test cases, but a few bugs were discovered and fixed in the process.

Cowboy 2.8 requires Erlang/OTP 22.0 or greater. It may also work out of the box with Erlang/OTP 21.3 but this was not tested and is not supported.

Features added

  • Cowboy will now use active,N instead of active,once to receive data from the socket. This greatly improves the performance and allows Cowboy to process more requests, especially for HTTP/1.1. The active_n protocol option can be configured to change the active,N value. The default is 100 for all protocols.
  • Add a linger_timeout option for HTTP/2. The default is 1000, or one second. This helps ensure that the final GOAWAY frame will be properly received by clients.
  • The function cowboy_req:parse_header/2,3 will now parse the headers access-control-request-headers, access-control-request-method, content-encoding, content-language, max-forwards, origin, proxy-authorization and trailer.
  • A Performance chapter has been added to the guide. More content will be added in future releases.
  • Update Cowlib to 2.9.1.

Experimental features added

  • A protocols protocol option allows configuring which protocol will be used for clear listeners. Setting it to [http2] will disable HTTP/1.1 entirely. This feature will be extended in a future release.

Features modified

  • The default value for HTTP/1.1's max_keepalive option has been increased. It now allows 1000 requests before gracefully closing the connection.
  • The default value for HTTP/2's max_received_frame_rate option has been increased. It now allows 10000 frames every 10 seconds.
  • Cowboy will now accept whitespace in cookie names. This is in line with the recommended parsing algorithm for the upcoming cookie RFC update, and corresponds to what browsers are doing.

Bugs fixed

  • The number of Transport:send/2 calls has been optimized for HTTP/2. Reducing the number of calls has a noticeable impact on the number of requests that can be processed.
  • Trying to use cowboy_req:reply/4 with a status code of 204 or 304 and a non-empty response body will now result in a crash. Using cowboy_req:stream_reply/2,3 with 204 or 304 and then attempting to send a body will also result in a crash. These status codes disallow response bodies and trying to send one will break HTTP/1.1 framing.
  • A crash has been fixed related to HTTP/1.1 pipelining. The bug was most likely introduced in Cowboy 2.6 when flow control was added for HTTP/1.1 request bodies.
  • The HTTP/1.1 protocol code could get stuck because of flow control. This has been corrected.
  • A crash has been fixed for HTTP/1.1. It occurred when a flow control update was requested (such as reading the request body) after the body was fully read.
  • The timeout was incorrectly reset sometimes when a stream (a pair of request/response) terminated. This has been corrected.
  • Handling of hibernation for Websocket has been improved. Websocket over HTTP/2 now supports hibernating. Stray messages no longer cancel hibernation.
  • The cowboy_compress_h stream handler will now ignore malformed accept-encoding headers instead of crashing.
  • The manual pages for cowboy:start_clear(3) and cowboy:start_tls(3) now mentions that some protocol options may be documented in the releevant stream handler.
  • The manual page for cowboy_req:parse_header(3) was corrected. When an unsupported header is given the function crashes, it does not return an undefined tuple.
  • The routing algorithm description in the user guide has been improved.
  • The test suites are now consistently green on all tested platforms. Most of the test failures were caused by flaky tests. Avoiding the use of timeouts fixed most of them. A small number of tests had to be reworked.

Cowboy 2.10 User Guide


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.