aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2019-10-06 16:51:27 +0200
committerLoïc Hoguin <[email protected]>2019-10-06 16:51:27 +0200
commit3977f2b96fb8cc2164bfe28ee094b3e661a2fad9 (patch)
treeb709721f8f69a4ee87bbfab8359915bfd201bb10 /doc
parent2b3852635115ad0aeeade9aeb88f285cfcd870b1 (diff)
downloadcowboy-3977f2b96fb8cc2164bfe28ee094b3e661a2fad9.tar.gz
cowboy-3977f2b96fb8cc2164bfe28ee094b3e661a2fad9.tar.bz2
cowboy-3977f2b96fb8cc2164bfe28ee094b3e661a2fad9.zip
Document the commands based Websocket interface
The old interface with ok|reply|stop tuples is deprecated.
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/ws_handlers.asciidoc25
-rw-r--r--doc/src/manual/cowboy_websocket.asciidoc51
2 files changed, 58 insertions, 18 deletions
diff --git a/doc/src/guide/ws_handlers.asciidoc b/doc/src/guide/ws_handlers.asciidoc
index 71165af..5cfdcb1 100644
--- a/doc/src/guide/ws_handlers.asciidoc
+++ b/doc/src/guide/ws_handlers.asciidoc
@@ -105,7 +105,7 @@ the upgrade:
[source,erlang]
----
websocket_init(State) ->
- {reply, {text, <<"Hello!">>}, State}.
+ {[{text, <<"Hello!">>}], State}.
----
=== Receiving frames
@@ -122,7 +122,7 @@ ignores all others:
[source,erlang]
----
websocket_handle(Frame = {text, _}, State) ->
- {reply, Frame, State};
+ {[Frame], State};
websocket_handle(_Frame, State) ->
{ok, State}.
----
@@ -145,7 +145,7 @@ and ignores all others:
[source,erlang]
----
websocket_info({log, Text}, State) ->
- {reply, {text, Text}, State};
+ {[{text, Text}], State};
websocket_info(_Info, State) ->
{ok, State}.
----
@@ -167,24 +167,23 @@ websocket_info(_Info, State) ->
{ok, State}.
----
-To send one frame, return a reply tuple with the frame to send:
+To send one frame, return the frame to be sent:
[source,erlang]
----
websocket_info(_Info, State) ->
- {reply, {text, <<"Hello!">>}, State}.
+ {[{text, <<"Hello!">>}], State}.
----
You can send frames of any type: text, binary, ping, pong
or close frames.
-To send many frames at once, return a reply tuple with the
-list of frames to send:
+You can send many frames at the same time:
[source,erlang]
----
websocket_info(_Info, State) ->
- {reply, [
+ {[
{text, "Hello"},
{text, <<"world!">>},
{binary, <<0:8000>>}
@@ -246,18 +245,18 @@ Cowboy will have a more reasonable default.
The Websocket connection process can be set to hibernate
after the callback returns.
-Simply add an `hibernate` field to the ok or reply tuples:
+Simply add an `hibernate` field to the returned tuple:
[source,erlang]
----
websocket_init(State) ->
- {ok, State, hibernate}.
+ {[], State, hibernate}.
websocket_handle(_Frame, State) ->
- {ok, State, hibernate}.
+ {[], State, hibernate}.
websocket_info(_Info, State) ->
- {reply, {text, <<"Hello!">>}, State, hibernate}.
+ {[{text, <<"Hello!">>}], State, hibernate}.
----
It is highly recommended to write your handlers with
@@ -289,5 +288,5 @@ The following example sends a close frame with a reason message:
[source,erlang]
----
websocket_info(_Info, State) ->
- {reply, {close, 1000, <<"some-reason">>}, State}.
+ {[{close, 1000, <<"some-reason">>}], State}.
----
diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc
index 2f01b8a..3a2264b 100644
--- a/doc/src/manual/cowboy_websocket.asciidoc
+++ b/doc/src/manual/cowboy_websocket.asciidoc
@@ -32,14 +32,18 @@ PartialReq :: map()
State :: any()
Opts :: cowboy_websocket:opts()
InFrame :: ping | pong | {text | binary | ping | pong, binary()}
-OutFrame :: cow_ws:frame() %% see types below
Info :: any()
-CallResult :: {ok, State}
+CallResult :: {commands(), State}
+ | {commands(), State, hibernate}
+ | Deprecated
+
+Deprecated :: {ok, State}
| {ok, State, hibernate}
| {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, State}
+OutFrame :: cow_ws:frame() %% see types below
Reason :: normal | stop | timeout
| remote | {remote, cow_ws:close_code(), binary()}
@@ -69,9 +73,9 @@ frame received. The `websocket_info/2` callback will be
called for every Erlang message received.
All three Websocket callbacks may send one or more frames
-back to the client (by returning a `reply` tuple) or terminate
-the connection (by sending a `close` frame or returning a `stop`
-tuple).
+back to the client, including close frames to terminate
+the connection; enable/disable active mode; enable/disable
+compression for subsequent frames; or change Websocket options.
The optional `terminate/3` callback will ultimately be called
with the reason for the termination of the connection. This
@@ -128,6 +132,41 @@ timeout::
== Types
+=== commands()
+
+[source,erlang]
+----
+commands() :: [Command]
+
+Command :: {active, boolean()}
+ | {deflate, boolean()}
+ | {set_options, #{idle_timeout => timeout()}}
+ | Frame :: cow_ws:frame()
+----
+
+Commands that may be returned from Websocket callbacks.
+
+The following commands are defined:
+
+active::
+
+Whether to disable or enable reading from the socket. This
+can be used to apply flow control to a Websocket connection.
+
+deflate::
+
+Whether the subsequent frames should be compressed. Has no
+effect on connections that did not negotiate compression.
+
+set_options::
+
+Set Websocket options. Currently only the option `idle_timeout`
+may be updated from a Websocket handler.
+
+Frame::
+
+Send the corresponding Websocket frame.
+
=== cow_ws:frame()
[source,erlang]
@@ -224,6 +263,8 @@ normal circumstances if necessary.
== Changelog
+* *2.7*: The commands based interface has been added. The old
+ interface is now deprecated.
* *2.7*: The option `validate_utf8` has been added.
* *2.6*: Deflate options can now be configured via `deflate_opts`.
* *2.0*: The Req object is no longer passed to Websocket callbacks.