/wsock

A library for building WebSocket clients and servers

Primary LanguageErlang

WSOCK

Library for building WebSocket clients and servers in Erlang.

Still in beta state but you can see an example at wsserver WSOCK

About

Wsock are a set of modules that can be used to build Websockets (RFC 6455) clients an servers.

It's still in beta state (not valid for something serious. Yet)

Writing clients

There's an example of a client wrote using wsock at https://github.com/madtrick/wsecli

Don't forguet to include the wsock headers file:

-include_lib("wsock/include/wsock.hrl").

Opening a connection

Build a handshake request:

HandshakeRequest = wsock_handshake:open(Resource, Host, Port)

And encode it to send it through the wire:

BinaryData = wsock_http:encode(HandshakeRequest#handshake.message)

Receive and validate handshake response:

{ok, HandshakeResponse} = wsock_http:decode(Data, response)
wsock_handshake:handle_response(HandshakeResponse, HandshakeRequest)

Sending data

Once the connection has been stablished you can send data through it:

Message = wsock_message:encode(Data, [mask, text]) %text data
Message = wsock_message:encode(Data, [mask, binary]) %binary data

Receiving data

If there is no previous fragmented message:

ListOfMessages = wsock_message:decode(Data, [])

If the previously received message was fragmented pass it as parameter:

ListOfMessages = wsock_message:decode(Data, FragmentedMessage, [])

Check wsock.hrl for a description of the message record.

Closing the connection

Once you are done close the connection following the closing handshake.

Init closing:

Message = wsock_message:encode([], [mask, close])

Then you'll have to wait for a close message and a the closing of the server socket before closing your socket (read the RFC).

Writing servers

There's an example of a dummy-server using wsock at https://github.com/madtrick/wsserver

Don't forget to include the wsock headers file:

-include_lib("wsock/include/wsock.hrl").

Accepting

Accept openning handshakes from your clients (gen_tcp).

Decode the http-handshake request:

{ok, OpenHttpMessage}   = wsock_http:decode(Data, request),
{ok, OpenHandshake}     = wsock_handshake:handle_open(OpenHttpMessage)

Get handshake key to generate a handshake response:

ClientWSKey             = wsock_http:get_header_value("sec-websocket-key", OpenHandshake#handshake.message),
{ok, HandshakeResponse} = wsock_handshake:response(ClientWSKey)

Encode the http-handshake response:

ResponseHttpMessage     = wsock_http:encode(HandshakeResponse#handshake.message)

Now you all have to do is send it over the wire.

Receiving data 

ListOfMessages = wsock_message:decode(Data, [masked]) % messages from clients are masked

Sending data 

ListOfMessages = wsock_message:encode(Data, [text]) % text data, servers don't mask data
ListOfMessages = wsock_message:encode(Data, [binary]) % binary data

Closing the connection 

CloseMessage = wsock_message:encode(Reason, [close])

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/

Contribute

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

Pull requests and patches (with tests) are welcome.

Author

This stuff has been writen by Farruco sanjurjo

License

Copyright [2012] [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.