diff options
authorLoïc Hoguin <[email protected]>2017-07-19 00:47:55 +0200
committerLoïc Hoguin <[email protected]>2017-07-19 00:47:55 +0200
commitac426c9ed06eed23d0de6c542f709225e00935f4 (patch)
parent7eb0072b06cabf1376a15effc35c5aa4d98efdc9 (diff)
Add a guide appendix on migrating from Cowboy 1.0
3 files changed, 209 insertions, 1 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 458b219..2c1c22e 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -78,7 +78,7 @@ include::sub_protocols.asciidoc[Sub protocols]
= Additional information
-//include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0]
+include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0]
// @todo Maybe history? Could take info from architecture also.
diff --git a/doc/src/guide/migrating_from_1.0.asciidoc b/doc/src/guide/migrating_from_1.0.asciidoc
new file mode 100644
index 0000000..8d5c6d7
--- /dev/null
+++ b/doc/src/guide/migrating_from_1.0.asciidoc
@@ -0,0 +1,207 @@
+== Migrating from Cowboy 1.0 to 2.0
+A lot has changed between Cowboy 1.0 and 2.0. The `cowboy_req`
+interface in particular has seen a massive revamp. Hooks are
+gone, their functionality can now be achieved via stream
+The documentation has seen great work, in particular the
+manual. Each module and each function now has its own dedicated
+manual page with full details and examples.
+=== Compatibility
+Compatibility with Erlang/OTP R16, 17 and 18 has been dropped.
+Erlang/OTP 19.0 or above is required. It is non-trivial to
+make Cowboy 2.0 work with older Erlang/OTP versions.
+Cowboy 2.0 is not compatible with Cowlib versions older than
+2.0. It should be compatible with Ranch 1.0 or above, however
+it has not been tested with Ranch versions older than 1.4.
+Cowboy 2.0 is tested on Arch Linux, Ubuntu, FreeBSD, Windows
+and OSX. It is tested with every point release (latest patch
+release) and also with HiPE on the most recent release.
+Cowboy 2.0 now comes with Erlang.mk templates.
+=== Features added
+* The HTTP/2 protocol is now supported.
+* Cowboy no longer uses only one process per connection.
+ It now uses one process per connection plus one process
+ per request by default. This is necessary for HTTP/2.
+ There might be a slight drop in performance for HTTP/1.1
+ connections due to this change.
+* Cowboy internals have largely been reworked in order to
+ support HTTP/2. This opened the way to stream handlers,
+ which are a chain of modules that are called whenever
+ something happens relating to a request/response.
+* The `cowboy_stream_h` stream handler has been added.
+ It provides most of Cowboy's default behavior.
+* The `cowboy_compress_h` stream handler has been added.
+ It compresses responses when possible. It's worth noting
+ that it compresses in more cases than Cowboy 1.0 ever did.
+* Because of the many changes in the internals of Cowboy,
+ many options have been added or modified. Of note is that
+ the Websocket options are now given per handler rather
+ than for the entire listener.
+* Websocket permessage-deflate compression is now supported
+ via the `websocket_compress` option.
+* Static file handlers will now correctly find files found
+ in '.ez' archives.
+* Constraints have been generalized and are now used not only
+ in the router but also in some `cowboy_req` functions. Their
+ interface has also been modified to allow for reverse
+ operations and formatting of errors.
+=== Features removed
+* SPDY support has been removed. Use HTTP/2 instead.
+* Hooks have been removed. Use xref:streams[stream handlers] instead.
+* The undocumented `waiting_stream` hack has been removed.
+ It allowed disabling chunked transfer-encoding for HTTP/1.1.
+ It has no equivalent in Cowboy 2.0. Open a ticket if necessary.
+* Sub protocols still exist, but their interface has largely changed
+ and they are no longer documented for the time being.
+=== Changed behaviors
+* The handler behaviors have been renamed and are now `cowboy_handler`,
+ `cowboy_loop`, `cowboy_rest` and `cowboy_websocket`.
+* Plain HTTP, loop, REST and Websocket handlers have had their
+ init and terminate callbacks unified. They now all use the
+ `init/2` and `terminate/3` callbacks. The latter is now optional.
+ The terminate reason has now been documented for all handlers.
+* The tuple returned to switch to a different handler type has
+ changed. It now takes the form `{Module, Req, State}` or
+ `{Module, Req, State, Opts}`, where `Opts` is a map of options
+ to configure the handler. The timeout and hibernate options
+ must now be specified using this map, where applicable.
+* All behaviors that used to accept `halt` or `shutdown` tuples
+ as a return value no longer do so. The return value is now
+ a `stop` tuple, consistent across Cowboy.
+* Middlewares can no longer return an `error` tuple. They have
+ to send the response and return a `stop` tuple instead.
+* The `known_content_type` REST handler callback has been removed
+ as it was found unnecessary.
+* Websocket handlers have both the normal `init/2` and
+ an optional `websocket_init/1` function. The reason for
+ that exception is that the `websocket_*` callbacks execute
+ in a separate process from the `init/2` callback, and it
+ was therefore not obvious how timers or monitors should
+ be setup properly. They are effectively initializing the
+ handler before and after the HTTP/1.1 upgrade.
+* Websocket handlers can now send frames directly from
+ `websocket_init/1`. The frames will be sent immediately
+ after the handshake.
+* Websocket handler callbacks no longer receive the Req
+ argument. The `init/2` callback still receives it and
+ can be used to extract relevant information. The `terminate/3`
+ callback, if implemented, may still receive the Req
+ (see next bullet point).
+* Websocket handlers have a new `req_filter` option that
+ can be used to customize how much information should be
+ discarded from the Req object after the handshake. Note
+ that the Req object is only available in `terminate/3`
+ past that point.
+* Websocket handlers have their timeout default changed
+ from infinity to 60 seconds.
+=== New functions
+* The `cowboy_req:scheme/1` function has been added.
+* The `cowboy_req:uri/1,2` function has been added, replacing the
+ less powerful functions `cowboy_req:url/1` and `cowboy_req:host_url/1`.
+* The functions `cowboy_req:match_qs/2` and `cowboy_req:match_cookies/2`
+ allow matching query string and cookies against constraints.
+* The function `cowboy_req:set_resp_cookie/3` has been added to
+ complement `cowboy_req:set_resp_cookie/4`.
+* The functions `cowboy_req:resp_header/2,3` and `cowboy_req:resp_headers/1`
+ have been added. They can be used to retrieve response headers
+ that were previously set.
+* The function `cowboy_req:set_resp_headers/2` has been added. It
+ allows setting many response headers at once.
+* The functions `cowboy_req:push/3,4` can be used to push resources
+ for protocols that support it (by default only HTTP/2).
+=== Changed functions
+* The `cowboy:start_http/4` function was renamed to `cowboy:start_clear/3`.
+* The `cowboy:start_https/4` function was renamed to `cowboy:start_tls/3`.
+* Most, if not all, functions in the `cowboy_req` module have been modified.
+ Please consult the changelog of each individual functions. The changes
+ are mainly about simplifying and clarifying the interface. The Req is no
+ longer returned when not necessary, maps are used wherever possible,
+ and some functions have been renamed.
+* The position of the `Opts` argument for `cowboy_req:set_resp_cookie/4`
+ has changed to improve consistency. It is now the last argument.
+=== Removed functions
+* The functions `cowboy_req:url/1` and `cowboy_req:host_url/1` have been
+ removed in favor of the new function `cowboy_req:uri/1,2`.
+* The functions `cowboy_req:meta/2,3` and `cowboy_req:set_meta/3` have
+ been removed. The Req object is now a public map, therefore they became
+ unnecessary.
+* The functions `cowboy_req:set_resp_body_fun/2,3` have been removed.
+ For sending files, the function `cowboy_req:set_resp_body/2` can now
+ take a sendfile tuple.
+* Remove many undocumented functions from `cowboy_req`, including the
+ functions `cowboy_req:get/2` and `cowboy_req:set/3`.
+=== Other changes
+* The correct percent-decoding algorithm is now used for path elements
+ during routing. It will no longer decode `+` characters.
+* The router will now properly handle path segments `.` and `..`.
+* Routing behavior has changed for URIs containing latin1 characters.
+ They are no longer allowed. URIs are expected to be in UTF-8 once
+ they are percent-decoded.
+* Etag comparison in REST handlers has been fixed. Some requests may
+ now fail when they succeeded in the past.
+* The If-*-Since headers are now ignored in REST handlers if If*-Match
+ headers exist. The former is largely a backward compatible header
+ and this shouldn't create any issue. The new behavior follows the
+ current RFCs more closely.
+* The static file handler has been improved to handle more special
+ characters on systems that accept them.
diff --git a/doc/src/guide/specs.asciidoc b/doc/src/guide/specs.asciidoc
index 1fd5916..3bcd45e 100644
--- a/doc/src/guide/specs.asciidoc
+++ b/doc/src/guide/specs.asciidoc
@@ -1,3 +1,4 @@
== HTTP and other specifications
This chapter intends to list all the specification documents