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
handlers.
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 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.
cowboy_stream_h
stream handler has been added.
It provides most of Cowboy’s default behavior.
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.
compress
option.
cowboy_req
functions. Their
interface has also been modified to allow for reverse
operations and formatting of errors.
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.
cowboy_handler
,
cowboy_loop
, cowboy_rest
and cowboy_websocket
.
init/2
and terminate/3
callbacks. The latter is now optional.
The terminate reason has now been documented for all handlers.
{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.
halt
or shutdown
tuples
as a return value no longer do so. The return value is now
a stop
tuple, consistent across Cowboy.
error
tuple. They have
to send the response and return a stop
tuple instead.
known_content_type
REST handler callback has been removed
as it was found unnecessary.
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_init/1
. The frames will be sent immediately
after the handshake.
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).
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.
cowboy_req:scheme/1
function has been added.
cowboy_req:uri/1,2
function has been added, replacing the
less powerful functions cowboy_req:url/1
and cowboy_req:host_url/1
.
cowboy_req:match_qs/2
and cowboy_req:match_cookies/2
allow matching query string and cookies against constraints.
cowboy_req:set_resp_cookie/3
has been added to
complement cowboy_req:set_resp_cookie/4
.
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.
cowboy_req:set_resp_headers/2
has been added. It
allows setting many response headers at once.
cowboy_req:push/3,4
can be used to push resources
for protocols that support it (by default only HTTP/2).
cowboy:start_http/4
function was renamed to cowboy:start_clear/3
.
cowboy:start_https/4
function was renamed to cowboy:start_tls/3
.
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.
Opts
argument for cowboy_req:set_resp_cookie/4
has changed to improve consistency. It is now the last argument.
cowboy_req:url/1
and cowboy_req:host_url/1
have been
removed in favor of the new function cowboy_req:uri/1,2
.
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.
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.
cowboy_req
, including the
functions cowboy_req:get/2
and cowboy_req:set/3
.
+
characters.
.
and ..
.
content_types_accepted/2
step
in REST handlers.
If-*-Since
headers are now ignored in REST handlers if
the corresponding If*-Match
header 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.