Update Cowboy to 2.1.0

Also add OTP-20.1.4 to CI.

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.