I have decided not to include a manual page for
cowboy_stream_h at this point because it clashes
with the cowboy_stream manual page. This decision
will be revisited in the future.
They are now cowboy:start_clear/3 and cowboy:start_tls/3.
The NumAcceptors argument can be specified via the
num_acceptor transport option. Ranch has been updated
to 1.4.0 to that effect.
This option allows customizing the compacting of the Req object
when using Websocket. By default it will keep most public fields
excluding headers of course, since those can be large.
The Opts value is put last, to be more consistent with the
rest of the cowboy_req module.
Additionally a test handler was fixed which reduced the number
of errors in http_SUITE.
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.
In particular the cowboy_sub_protocol is subject to change soon.
Also the cowboy_stream behavior is going to be left hidden in
this release and enabled when it becomes easier to chain them.
This commit separates the documentation of the functions into
separate manual pages, with at least one example per function
and a lot more details about parameters, return values and
related functions and modules. It also includes a changelog
indicating when the function was added or changed.
The inspiration for this comes mainly from the PHP documentation
and feedback from users.
