README.md

Erlang Websocket Client

Existing features

1. Client to Server Masking
2. OTP compliant
3. Callback-driven behaviour
4. Handshake validation
5. TCP and SSL support
6. Handling of text, binary, ping, pong, and close frames
7. Handling of continuation frames
8. Automated ping/pong and keepalive

Usage

For basic usage, see examples/sample_ws_handler.erl:

-module(sample_ws_handler).

-behaviour(websocket_client).

-export([
         start_link/0,
         init/1,
         onconnect/2,
         ondisconnect/2,
         websocket_handle/3,
         websocket_info/3,
         websocket_terminate/3
        ]).

start_link() ->
    crypto:start(),
    ssl:start(),
    websocket_client:start_link("wss://echo.websocket.org", ?MODULE, []).

init([]) ->
    {once, 2}.

onconnect(_WSReq, State) ->
    websocket_client:cast(self(), {text, <<"message 1">>}),
    {ok, State}.

ondisconnect({remote, closed}, State) ->
    {reconnect, State}.

websocket_handle({pong, _}, _ConnState, State) ->
    {ok, State};
websocket_handle({text, Msg}, _ConnState, 5) ->
    io:format("Received msg ~p~n", [Msg]),
    {close, <<>>, "done"};
websocket_handle({text, Msg}, _ConnState, State) ->
    io:format("Received msg ~p~n", [Msg]),
    timer:sleep(1000),
    BinInt = list_to_binary(integer_to_list(State)),
    {reply, {text, <<"hello, this is message #", BinInt/binary >>}, State + 1}.

websocket_info(start, _ConnState, State) ->
    {reply, {text, <<"erlang message received">>}, State}.

websocket_terminate(Reason, _ConnState, State) ->
    io:format("Websocket closed in state ~p wih reason ~p~n",
              [State, Reason]),
    ok.

The above code will send messages to the echo server that count up from 1 through 4. It will also print all replies from the server:

Received msg <<"this is message 1">>
Received msg <<"hello, this is message #2">>
Received msg <<"hello, this is message #3">>
Received msg <<"hello, this is message #4">>

This client implements a cowboy like websocket_client_handler to interact with a websocket server. Currently, it can connect via tcp or ssl via the ws and wss protocols. It can also send and receive contiguous text or binary websocket frames.

TODO

The client has been significantly reworked, now backed by gen_statem. There may still be bugs. Please report them.

1. Stop using verify_none by default
2. Add more complete testing - preferably based on / using Autobahn.