+ +

Migrating from Cowboy 2.0 to 2.1

+ +

Cowboy 2.1 focused on adding features that were temporarily +removed in Cowboy 2.0. A number of bugs found in the 2.0 +release were also fixed.

Features added

+
+It is now possible to obtain the client TLS certificate + and the local IP/port for the connection from the Req object. +
+
+
+Informational responses (1XX responses) can now be sent. + They must be sent before initiating the final response. +
+
+
+The expect: 100-continue header is now handled + automatically. The 100 response will be sent on the + first cowboy_req:read_body/2,3,4 call. This only applies + when using the default cowboy_stream_h stream handler. +
+

Experimental features added

Experimental features are previews of features that will be +added in a future release. They are not documented and their +interface may change at any time. You are welcome to try them +and provide feedback.

+
+The cowboy_metrics_h stream handler can be used to + extract metrics out of Cowboy. It must be used first in + the list of stream handlers, and will record all events + related to requests, responses and spawned processes. + When the stream terminates it will pass this information + to a user-defined callback. +
+
+
+The cowboy_tracer_h stream handler can be used to setup + automatic tracing of specific requests. You can conditionally + enable tracing based on a function, header, path or any other + element from the request and the trace will apply to the + entire connection and any processes created by it. This is + meant to be used for debugging both in tests and production. +
+

Changed behaviors

+
+The cowboy_rest handler now implements a mechanism for + switching to a different type of handler from any callback + where stop is also allowed. Switch by returning + {switch_handler, Module} or {switch_handler, Module, Opts}. + This is especially useful for switching to cowboy_loop + for streaming the request or response body. +
+
+
+REST callbacks that do not allow stop as a return value + are now explicitly listed in the documentation. +
+

New functions

+
+The function cowboy_req:sock/1 returns the IP/port + of the local socket. +
+
+
+The function cowboy_req:cert/1 returns the client + TLS certificate or undefined if it isn’t available. +
+
+
+The function cowboy_req:inform/2,3 sends an + informational response. +
+

Bugs fixed

+
+Ensure HTTP/2 connections are not closed prematurely + when the user code does not read the request body. +
+
+
+Ensure HTTP/1.1 streams are not terminated too early. + Their behavior is now consistent with the HTTP/2 code + where the stream handler is only terminated when the + stop command is returned. +
+
+
+Sending zero-sized data from stream handlers or from + cowboy_req:stream_body/3 could lead to issues with + HTTP/1.1. This has been fixed. +
+
+
+The final chunk sent by Cowboy when it terminates a + chunked body after the handler process exits was not + passed through stream handlers, which could lead to + issues when cowboy_compress_h was being used. This + is now corrected. +
+
+
+The stream handler state was discarded in some cases + where Cowboy had to send a response or response data + automatically when ending a stream. This has now + been corrected. +
+
+
+The stream handler callback terminate/3 will now be + called when switching to another protocol using the + command switch_protocol. This doesn’t apply when + doing upgrades to HTTP/2 as those occur before the + stream is initialized. +
+
+
+Cowlib has been updated to 2.0.1 to fix an issue with + Websocket compression when using Erlang/OTP 20.1. Note + that at the time of writing all 20.1 versions (from + 20.1 to 20.1.4) have issues when compression is enabled. + It is expected to work properly from 20.1.5 onward. In + the meantime it is recommended to run the plain 20.1 + release and disable Websocket compression, or use a + release before 20.1. +
+
+
+Cowboy will no longer crash when the cowboy_clock + process is not running. This can happen when Cowboy + is being restarted during upgrades, for example. +
+

+ + + + + + + + + + + + + + + +

+ +

+ + +

+ Cowboy + 2.4 + + User Guide +

+ +

User Guide
Function Reference

+ +

Navigation

+ +

Version select

+ +