Separate message and packet handling for websockets

Improves the readability of websocket handler code by having
two functions: websocket_handle/3 handles the packets received
from the socket, removing the tuple construct that was otherwise
needed, so only websocket_handle(Data, Req, State) is needed now;
websocket_info/3 handles the messages that the websocket handler
process received, as websocket_info(Info, Req, State).

Both functions return values are handled identically by Cowboy
so nothing changes on that end.

1 files changed, 21 insertions, 14 deletions

diff --git a/src/cowboy_http_websocket_handler.erl b/src/cowboy_http_websocket_handler.erl
index b02c28d..90cf7ac 100644
--- a/src/cowboy_http_websocket_handler.erl
+++ b/src/cowboy_http_websocket_handler.erl
@@ -14,12 +14,13 @@
 
 %% @doc Handler for HTTP WebSocket requests.
 %%
-%% WebSocket handlers must implement three callbacks: <em>websocket_init/3</em>,
-%% <em>websocket_handle/3</em> and <em>websocket_terminate/3</em>. These
-%% callbacks will only be called if the connection is upgraded to WebSocket
-%% in the HTTP handler's <em>init/3</em> callback. They are then called in that
-%% order, although <em>websocket_handle/3</em> will be called multiple time,
-%% one time for each message or packet received.
+%% WebSocket handlers must implement four callbacks: <em>websocket_init/3</em>,
+%% <em>websocket_handle/3</em>, <em>websocket_info/3</em> and
+%% <em>websocket_terminate/3</em>. These callbacks will only be called if the
+%% connection is upgraded to WebSocket in the HTTP handler's <em>init/3</em>
+%% callback. They are then called in that order, although
+%% <em>websocket_handle/3</em> will be called for each packet received,
+%% and <em>websocket_info</em> for each message received.
 %%
 %% <em>websocket_init/3</em> is meant for initialization. It receives
 %% information about the transport and protocol used, along with the handler
@@ -27,11 +28,15 @@
 %% If you are going to want to compact the request, you should probably do it
 %% here.
 %%
-%% <em>websocket_handle/3</em> receives messages sent to the process and
-%% also the data sent to the socket. In the later case the information is
-%% given as a tuple <em>{websocket, Data}</em>. It can reply something, do
-%% nothing or close the connection. You can choose to hibernate the process
-%% by returning <em>hibernate</em> to save memory and CPU.
+%% <em>websocket_handle/3</em> receives the data from the socket. It can reply
+%% something, do nothing or close the connection. You can choose to hibernate
+%% the process by returning <em>hibernate</em> to save memory and CPU.
+%%
+%% <em>websocket_info/3</em> receives messages sent to the process. It has
+%% the same reply format as <em>websocket_handle/3</em> described above. Note
+%% that unlike in a <em>gen_server</em>, when <em>websocket_info/3</em>
+%% replies something, it is always to the socket, not to the process that
+%% originated the message.
 %%
 %% <em>websocket_terminate/3</em> is meant for cleaning up. It also receives
 %% the request and the state previously defined, along with a reason for
@@ -41,9 +46,11 @@
 -export([behaviour_info/1]).
 
 %% @private
--spec behaviour_info(_) -> undefined | [{websocket_handle, 3}
-	| {websocket_init, 3} | {websocket_terminate, 3}, ...].
+-spec behaviour_info(_)
+	-> undefined | [{websocket_handle, 3} | {websocket_info, 3}
+		| {websocket_init, 3} | {websocket_terminate, 3}, ...].
 behaviour_info(callbacks) ->
-	[{websocket_init, 3}, {websocket_handle, 3}, {websocket_terminate, 3}];
+	[{websocket_init, 3}, {websocket_handle, 3},
+	 {websocket_info, 3}, {websocket_terminate, 3}];
 behaviour_info(_Other) ->
 	undefined.