Prev   Next

Appendix G. Migrating from Cowboy 2.5 to 2.6

Cowboy 2.6 greatly refactored the HTTP/2 code, a large part of which was moved to Cowlib and is now used by both the Cowboy server and the Gun client.

A large number of tickets were also closed which resulted in many bugs fixed and many features and options added, although some of them are still experimental.

G.1. Features added

  • Add support for the PROXY protocol header. It can be enabled via the proxy_header option. The proxy information can then be found under the proxy_info key in the Req object.
  • Allow using sendfile tuples in cowboy_req:stream_body/3 and in the data command in stream handlers. The only caveat is that when using cowboy_compress_h the sendfile tuples may have to be converted to in-memory data in order to compress them. This is the case for gzip compression.
  • The stream handlers cowboy_stream_h and cowboy_compress_h are now documented.
  • Add the chunked option to allow disabling chunked transfer-encoding for HTTP/1.1 connections.
  • Add the http10_keepalive option to allow disabling keep-alive for HTTP/1.0 connections.
  • Add the idle_timeout option for HTTP/2.
  • Add the sendfile option to both HTTP/1.1 and HTTP/2. It allows disabling the sendfile syscall entirely for all connections. It is recommended to disable sendfile when using VirtualBox shared folders.
  • Add the rate_limited/2 callback to REST handlers.
  • Add the deflate_opts option to Websocket handlers that allows configuring deflate options for the permessage-deflate extension.
  • Add the charset option to cowboy_static.
  • Add support for the SameSite cookie attribute.
  • Update Ranch to 1.7.0
  • Update Cowlib to 2.7.0

G.2. Experimental features added

  • Add support for range requests (RFC7233) in REST handlers. This adds two new callbacks: ranges_accepted/2 and range_satisfiable/2 along with the user-specified ProvideRangeCallback/2.
  • Add automatic handling of range requests to REST handlers that return the callback auto from ranges_accepted/2. Cowboy will call the configured ProvideCallback and then split the output automatically for the ranged response.
  • Enable range requests support in cowboy_static.
  • Add the {deflate, boolean()} Websocket handler command to disable permessage-deflate compression temporarily.
  • Add the compress_threshold option which allows configuring how much data must be present in a response body to compress it. This only applies to non-streamed bodies at this time.
  • Add the compress_buffering option which allows controlling whether some buffering may be done when streaming a response body. Change the default behavior to not buffer to make sure it works by default in all scenarios.
  • Add the {set_options, map()} command to stream handlers and Websocket handlers. This can be used to update options on a per-request basis. Allow overriding the idle_timeout option for both HTTP/1.1 and Websocket, the cowboy_compress_h options for HTTP/1.1 and HTTP/2 and the chunked option for HTTP/1.1.

G.3. Bugs fixed

  • Do not send a content-length automatically with 304 responses. This status code allows a content-length that corresponds to what would have been sent for a 200 response, but is never followed by a body.
  • HTTP/2 streams are now terminated once the body has been sent fully, instead of immediately once the stop command is returned (by default when the request process exits). Metrics will therefore more accurately represent when a stream ended.
  • Terminate connection processes gracefully when the parent process exists or when sys:terminate/2,3 is called.
  • Automatically ignore the boundary parameter of multipart media types when using REST handlers. This is a special parameter that may change with all requests and cannot be predicted.
  • Fix parsing of the accept header when it contains charset parameters. They are case insensitive and will now be lowercased, like for accept-charset and content-type.
  • Handle the charset parameter using charsets_provided when it is present in the accept header when using REST handlers.
  • Don’t select charsets when the q-value is 0 in REST handlers.
  • Handle accept-charset headers that include a wildcard in REST handlers.
  • Only send a charset header when the content-type negotiated is of type text in REST handlers.
  • Remove the default charset iso-8859-1 from REST handlers when no other is provided. This has been removed from the HTTP specifications for a long time.
  • Many cases where a content-type header was sent unnecessarily in the REST handlers response have been fixed.
  • Handle error_response commands in cowboy_metrics_h.
  • A number of types and function specifications were fixed or improved. Dialyzer is now run against both the code and tests to help uncover issues.
  • An undefined cowboy_router behavior has been documented.
Prev Up Next
 Home