aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide/migrating_from_2.0.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/guide/migrating_from_2.0.asciidoc')
-rw-r--r--doc/src/guide/migrating_from_2.0.asciidoc107
1 files changed, 107 insertions, 0 deletions
diff --git a/doc/src/guide/migrating_from_2.0.asciidoc b/doc/src/guide/migrating_from_2.0.asciidoc
new file mode 100644
index 0000000..c76430c
--- /dev/null
+++ b/doc/src/guide/migrating_from_2.0.asciidoc
@@ -0,0 +1,107 @@
+[appendix]
+== 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.