Home

Awesome

SockJS family:

SockJS-erlang server

SockJS server written in Erlang. Can run with Cowboy http server. SockJS-erlang is in core web-framework agnostic (up to version v0.2.1 we also supported Misultin). SockJS-erlang is compatible with SockJS client version 0.3. See https://github.com/sockjs/sockjs-client for more information on SockJS.

Show me the code!

A simplistic echo SockJS server using Cowboy may look more or less like this:

main(_) ->
    ok = application:start(xmerl),
    ok = application:start(sockjs),
    ok = application:start(ranch),
    ok = application:start(crypto),
    ok = application:start(cowboy),

    SockjsState = sockjs_handler:init_state(
                    <<"/echo">>, fun service_echo/3, state, []),

    Routes = [{'_',  [{<<"/echo/[...]">>,
                       sockjs_cowboy_handler, SockjsState}]}],
    Dispatch = cowboy_router:compile(Routes),

    cowboy:start_http(cowboy_test_http_listener, 100,
                      [{port, 8081}],
                      [{env, [{dispatch, Dispatch}]}]),
    receive
        _ -> ok
    end.

service_echo(_Conn, init, state)          -> {ok, state};
service_echo(Conn, {recv, Data}, state)   -> Conn:send(Data);
service_echo(_Conn, {info, _Info}, state) -> {ok, state};
service_echo(_Conn, closed, state)        -> {ok, state}.

Dig into the examples directory to get working code:

How to run the examples?

You may need a recent version of Erlang/OTP, at least R14B is recommended.

To run Cowboy example:

cd sockjs-erlang
./rebar get-deps
./rebar compile
./examples/cowboy_echo.erl

This will start a simple /echo SockJS server on http://localhost:8081. Open this link in a browser and play around.

SockJS-erlang API

Except for the web framework-specific API's, SockJS-erlang is rather simple. It has just a couple of methods:

The framework-specific calls are more problematic. Instead of trying to explain how to use them, please take a look at the examples.

Stability

SockJS-erlang is quite new, but should be reasonably stable. Cowboy is passes all the SockJS-protocol tests.

Deployment and load balancing

SockJS servers should work well behind many load balancer setups, but it sometimes requres some additional twaks. For more details, please do take a look at the 'Deployment' section in SockJS-node readme.

Development and testing

You need rebar (instructions). Due to a bug in rebar config handling you need a reasonably recent version - newer than late Oct 2011. Alternatively, SockJS-erlang is bundeled with a recent rebar binary.

SockJS-erlang contains a test_server, a simple server used for testing.

To run Cowboy test_server:

cd sockjs-erlang
./rebar get-deps
./rebar compile
./examples/cowboy_test_server.erl

That should start test_server on port 8081. Currently, there are two separate test suits using test_server.

SockJS-protocol Python tests

Once test_server is listening on http://localhost:8081 you may test it using SockJS-protocol:

cd sockjs-protocol
make test_deps
./venv/bin/python sockjs-protocol-dev.py

For details see SockJS-protocol README.

SockJS-client QUnit tests

You need to start a second web server (by default listening on 8080) that is serving various static html and javascript files:

cd sockjs-client
make test

At that point you should have two web servers running: sockjs-erlang on 8081 and sockjs-client on 8080. When you open the browser on http://localhost:8080/ you should be able run the QUnit tests against your sockjs-node server.

For details see SockJS-client README.

Additionally, if you're doing more serious development consider using make serve, which will automatically the server when you modify the source code.