Allow passing options to sub protocols

Before this commit we had an issue where configuring a
Websocket connection was simply not possible without
doing magic, adding callbacks or extra return values.
The init/2 function only allowed setting hibernate
and timeout options.

After this commit, when switching to a different
type of handler you can either return

  {module, Req, State}

or

  {module, Req, State, Opts}

where Opts is any value (as far as the sub protocol
interface is concerned) and is ultimately checked
by the custom handlers.

A large protocol like Websocket would accept only
a map there, with many different options, while a
small interface like loop handlers would allow
passing hibernate and nothing else.

For Websocket, hibernate must be set from the
websocket_init/1 callback, because init/2 executes
in a separate process.

Sub protocols now have two callbacks: one with the
Opts value, one without.

The loop handler code was largely reworked and
simplified. It does not need to manage a timeout
or read from the socket anymore, it's the job of
the protocol code. A lot of unnecessary stuff was
therefore removed.

Websocket compression must now be enabled from
the handler options instead of per listener. This
means that a project can have two separate Websocket
handlers with different options. Compression is
still disabled by default, and the idle_timeout
value was changed from inifnity to 60000 (60 seconds),
as that's safer and is also a good value for mobile
devices.

1 files changed, 19 insertions, 16 deletions

diff --git a/doc/src/guide/sub_protocols.asciidoc b/doc/src/guide/sub_protocols.asciidoc
index 2ab96bc..83fa975 100644
--- a/doc/src/guide/sub_protocols.asciidoc
+++ b/doc/src/guide/sub_protocols.asciidoc
@@ -20,31 +20,31 @@ init(Req, State) ->
     {cowboy_websocket, Req, State}.
 ----
 
-The return value may also have a `Timeout` value and/or the
-atom `hibernate`. These options are useful for long living
-connections. When they are not provided, the timeout value
-defaults to `infinity` and the hibernate value to `run`.
+The returned tuple may also have a fourth element containing
+options for the sub protocol. No option is universal. While
+it will usually be a map of options, it doesn't have to be.
+For example loop handlers accept the atom `hibernate`.
 
 The following snippet switches to the `my_protocol` sub
 protocol, sets the timeout value to 5 seconds and enables
 hibernation:
 
-// @todo Yeah maybe what we really need is an Opts map.
-
 [source,erlang]
 ----
 init(Req, State) ->
-    {my_protocol, Req, State, 5000, hibernate}.
+    {my_protocol, Req, State, #{
+        timeout => 5000,
+        compress => true}}.
 ----
 
-If a sub protocol does not make use of these options, it should
-crash if it receives anything other than the default values.
+Sub protocols should ignore unknown options so as to not waste
+resources doing unnecessary validation.
 
 === Upgrade
 
-After the `init/2` function returns, Cowboy will then call the
-`upgrade/6` function. This is the only callback defined by the
-`cowboy_sub_protocol` behavior.
+After the `init/2` function returns, Cowboy will call either
+the `upgrade/4` or the `upgrade/5` function. The former is called
+when no options were given; the latter when they were given.
 
 The function is named `upgrade` because it mimics the mechanism
 of HTTP protocol upgrades. For some sub protocols, like Websocket,
@@ -53,16 +53,19 @@ only an upgrade at Cowboy's level and the client has nothing to
 do about it.
 
 The upgrade callback receives the Req object, the middleware
-environment, the handler and its options, and the aforementioned
-timeout and hibernate values.
+environment, the handler and its state, and for `upgrade/5`
+also the aformentioned options.
 
 [source,erlang]
 ----
-upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
+upgrade(Req, Env, Handler, State) ->
+    %% Sub protocol code here.
+
+upgrade(Req, Env, Handler, State, Opts) ->
     %% Sub protocol code here.
 ----
 
-This callback is expected to behave like a middleware and to
+These callbacks are expected to behave like middlewares and to
 return an updated environment and Req object.
 
 Sub protocols are expected to call the `cowboy_handler:terminate/4`