madtrick / wsecli

Erlang WebSockets client

wsecli

A WebSocket client written in Erlang

• Supported WebSocket version
• Build
• Usage
• Tests
• TODO
• License
• Contribute

Features

• Built using wsock
• Supports both "ws://" and "wss://" schemes.
• Offers callbacks for events that might occur during the client life: on_open, on_close, on_message and on_error.

Supported protocol versions

Only the protocol specificied at RFC6455 (version 13) is supported. Notice that currently, neither subprotocols nor extensions are supported.

Build ###

Add this repo as a dependency to your rebar.config file

{wsecli, ".*", {git, "https://github.com/madtrick/wsecli", {tag, master}}}

and then

./rebar compile

Usage ###

I will demostrate its usage with the echo service at www.websocket.org.

1. Start it, using the function wsecli:start/4

   1>wsecli:start("echo.websocket.org", 80, "/", []).

   or the function wsecli:start/2

   2>wsecli:start("ws://echo.websocket.org/", []).

   The valid options for the client are:

   • {registered, true | false | atom()}. When true the client will be registered using the default name wsecli, when false it will not be registered and any other atom will be used as the name to register with. By default it will not be registered.

2. Add a callback for received messages,

   3>wsecli:on_message(fun(text, Message)-> io:format("Echoed message: ~s ~n", [Message]) end).

3. Send a message that will be echoed,

   4> wsecli:send("Hello").
   ok
   Echoed message: Hello

4. And finally to stop it

   5>wsecli:stop().

Callbacks

Callbacks for the events: on_open, on_error, on_message and on_close can be added. Check the code or the documentation for details.

Tests

Unit tests

Unit test where done with the library espec by lucaspiller.

To run them

rake spec

or, in case you don't have rake installed,

./rebar compile && ERL_LIBS='deps/' ./espec test/spec/

TODO

• Support streaming of data.
• Support subprotocol and extensions.

###Author Farruco Sanjurjo. You can contact me at:

• Twitter @madtrick
• Mail [email protected]

License

Copyright [2013] [Farruco Sanjurjo Arcay]

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contribute

If you find or think that something isn't working properly, just open an issue.

Pull requests and patches (with tests) are welcome.

wsecli's Issues

faulty rebar file?

{deps, [
{espec, ".*", {git, "https://github.com/lucaspiller/espec.git", {branch, "master"}}},
{cucumberl, "0.0.5", {git, "[email protected]:madtrick/cucumberl.git", {branch, master}}}, <---

should this be https://github.com:madtrick/cucumberl.git ?????

since you are trying to use https all the way?

thanks

can not compile project

This is due to not-sync dependencies, and lack of local rebar binary.

wsecli:start

Should really be called start_link to match the gen_fsm:start_link call inside.

The idiomatic way to pass arguments is in a list so [Host, Port, Path] instead of {Host, Port, Path}.

There's no need to pass timeout to gen_fsm. Will post the reason as a separate issue.

By locally registering the created gen_fsm you are limiting users to 1 websocket connection per node. You should not register locally.

closing state

The closing state is superfluous and there's no need to make closing the connection synchronous.

The idiomatic way is to allow for an asynchronous 'stop' message to trigger shutdown.

Once shutdown is triggered, you simply close sockets and clean up any resources in use, then you terminate.

callbacks

You have a very non-Erlang-y and limiting approach to callbacks.

What you want is for wsecli to be a behavior requiring 'on open', 'on message', etc. callbacks from the behavior implementation (callback) module.

This will also enable callback modules to keep their own local data which you can feed to the each callback when you trigger it.

Last but not least, there's no need to create a process for each callback invocation. You should leave the behavior implementation module to create processes as necessary.

Travis build fails form R14B0X

When Travis builds wsecli using releases in the R14B0X range it crashes with this error.

=ERROR REPORT==== 11-Feb-2014::14:27:32 ===
Loading of /home/travis/build/madtrick/wsecli/rebar/rebar/ebin/rebar.beam failed: badfile
escript: exception error: undefined function rebar:main/1
  in function  escript:run/2
  in call from escript:start/1
  in call from init:start_it/1
  in call from init:start_em/1

It seems that the rebar they use is not compatible with those versions of the erl

Race condition and message.type=close

There is race condition sometimes:

17:08:36.501 [error] CRASH REPORT Process <0.9701.0> with 5 neighbours exited with reason: no case clause matching close in wsecli:process_messages/2 line 420 in gen_fsm:terminate/7 line 622
17:08:36.502 [error] gen_fsm <0.9706.0> in state open terminated with reason: no case clause matching close in wsecli:process_messages/2 line 420

This lines are 419-420:

process_messages([Message | Messages], StateData) ->
  case Message#message.type of

wsecli:init

https://github.com/madtrick/wsecli/blob/master/src/wsecli.erl#L127

You seem to be doing connection setup and handshaking in init. This is not the right place to do it. The fix is to move that code out and send yourself a 'connect' event from the init function, e.g. gen_fsm:send_event(self(), 'connect').

This will also eliminate the need for passing gen_fsm:start_link a timeout of 5s.

sending binary is broken

In cowboy log:
Message was {text,<<255,3,0,3,0,0,7,34,67,77>>}

and crashes obviously. Well Cowboy doesn't crash of course but my session do.

In my code: wsecli:send(<<255,3,0,3,0,0,7,34,67,77>>),

I have checked framing opcode with wireshark on the outgoing frame from wsecli and it is (0x01 text) and should be (0x02 binary)

Temporary solution in wsecli.erl:

  open({send, Data}, StateData) ->
  case is_list(Data) of
      true -> Message = wsock_message:encode(Data, [mask, text]), io:format("Data is text: ~p~n",[Data]);
      _ -> Message = wsock_message:encode(Data, [mask, binary]), io:format("Data is binary: ~p~n",[Data])
  end,
  case gen_tcp:send(StateData#data.socket, Message) of
    ok ->
      ok;
    {error, Reason} ->
      (StateData#data.cb#callbacks.on_error)(Reason)
  end,
  {next_state, open, StateData}.

[bug] on_close_callback() ought to take 2 arguments but is called with 1

I'm referring to tag 1.0.0. Given:

-type data_callback()       :: fun((text, string()) -> any()) | fun((binary, binary()) -> any()).
-type on_close_callback()   :: data_callback().

the call at src/wsecli.erl:401 is clearly erroneous:

spawn(fun() -> (StateData#data.cb#callbacks.on_close)(undefined) end).

I was thinking of a PR but gave the idea up since I don't know whether you want to push the idea with typed message for on_close further or not. However, the current situation is problematic since either Dialyzer is happy and the code crashes or Dialyzer bails out while the code runs fine.