Lithium

Lithium is a data centric WebSocket library for both Node.js and the Browser.

Installation

Client

<script type="text/javascript" src="lithium.client.js"></script>

Server

npm install lithium

Usage

Below is an example of a simple, JSON based echo server.

Client

var client = lithium.Client(function(client) {

    client.on('message', function(msg) {
        ...
    });

    client.send({
        msg: 'Hello World'
    });

}, JSON.stringify, JSON.parse);

Server

var lithium = require('lithium');

var server = new lithium.Server(function(remote) {

    remote.accept();
    remote.on('message', function(msg) {
        remote.send(msg);
    });

}, JSON.stringify, JSON.parse);

server.listen(8000);

Features

• WebSocket Protocols (v75, v76, hixie and hyby)
• Binary Message Support
• Consistent API on both Server and Client
• No dependencies

API

Server

A http.Server-like interface for managing web socket connections.

Methods

• Constructor - lithium.Server([Function:callback] [, Function:encoder, Function:decoder])

  Creates a new server instance.

  The optional callback argument is shortcut for the connection event.

  If both the encoder and decoder arguments are present, messages will be passed to these functions when being send / received.

  For example, in order to process and treat all messages as JSON objects pass

• listen(Number:port [, String:hostname])

  Makes the server listen for incoming web socket requests on port and - optionally - hostname.

• listen(http(s).Server)

  Makes the server listen for incoming web socket request on an existing instance of http.Server or https.Server.

• Array[Remote] - remotes([Function:filter])

  Returns a array with all remotes that are currently connected to the server (meaning that only accepted remotes will be contained in the array).

  Filter is an optional function behaving much like Array.filter in that it filters the remotes before returning them.

• Integer - send(Any:message [, Function:filter])

  Sends a message to all accepted remotes on the server.

  Filter is an optional function behaving much like Array.filter in that it filters the remotes before messaging them.

  Returns the number of remotes the message was sent to.

• Boolean - close([string:reason])

  Closes the server by preventing any furhter connections to be made and invokes the close method of all the server's remotes.

  The optional reason is only supported in newer versions of the WebSocket protocol and will be available as the reason property on the WebSocket's close event.

  Returns false in case the server is already closed.

Events

• connection(Remote:remote)

  Emitted when a remote connects to the server.

• accepted(Remote:remote)

  Emitted when the server accepts a remote.

• rejected(Remote:remote)

  Emitted when the server rejects a remote.

• closed(Remote:remote, Boolean:closedByRemote)

  Emitted when a remote disconnects from the server.

  closedByRemote will be true in the case that the disconnect was initiated by the remote.

• close()

  Emitted when the server stops listening for new connections.

Remotes

Each remote encapsulate a single web socket connection to a client.

A remote is only recognized as being connected after it was accepted.

Properties

• String - id

• String - address

  Address of the underlying socket connection.

• Intege - port

  Port of the underlying socket connection.

• Integer - bytesSend

  Number of raw bytes (including protocol overhead) send over the socket.

• Integer - bytesReceived

  Number of raw bytes (including protocol overhead) send over the socket.

• Integer - version

  The version of the underlying WebSocket protocol for this remote.

Methods

• Boolean - accept()

  Accepts a pending remote connection, which adds it to the list of connected remotes on the server.

  Once a remote is accepted messages can be send to it.

  Returns true in case the remote was accepted or false in case it could not be accepted.

• Boolean - reject([String:reason])

  Rejects a pending remote and sends an optional reason as a message before closing the connection.

  Returns true in case the remote was rejected or false in case it could not be rejected.

• Boolean - isPending()

  Returns whether or not the connection is pending.

  Pending means that the connection is yet to be either accepted or rejected.

• Object - info()

  Returns a object containing connection specific information:

  {
      ip: "127.0.0.1"
      port: 35758,
      bytesSend: 123,
      bytesReceived: 456
  }
  

  Note: The returned object is a reference.

• Boolean - send(any:message)

  Sends a message to the remote.

  Returns true in case the message was send or false in case it could not be send.

• Boolean - close([Any:reason])

  Closes the connection to the remote.

  The optional reason is only supported in newer versions of the WebSocket protocol and will be available as the reason property on the WebSocket's close event.

  Returns true in case the connection was closed or false in case it was not.

Events

• message(Any:message)

  Emitted when a message is received from a remote.

• close(Boolean:closedByRemote)

  Emitted when the remote is disconnected from the server.

  closedByRemote will be true in the case that the disconnect was initiated by the remote.

Client

A thin wrapper around the browser side WebSocket object, providing a interface that is consistent with the lithium server.

Methods

• Constructor - lithium.Client([Function:callback] [, Function:encoder, Function:decoder]) (Constructor)

  The optional callback argument is shortcut for the connection event.

  If both the encoder and decoder arguments are present, messages will be passed to these functions when being send / received.

  For example, in order to process and treat all messages as JSON objects pass

• Boolean - connect(Integer:port [, String:hostname])

  Connects to the server at port and - optionally - hostname.

• Boolean - isConnected()

  Returns true in case the client is currently connected to the server.

• Boolean - send(any:message)

  Sends a message to the remote.

  Returns true in case the message was send or false in case it could not be send.

• Boolean - close()

  Closes the connection to the server.

  Returns false in case the connection is already closed.

Events

• connection()

  Emitted once the connection to the server is established.

• message(Any:message)

  Emitted when a message is received from the server.

• close(Boolean:closedByServer)

  Emitted when the client is disconnected from the server.

  In the case that the server has initiated the close of the connection, the value of closedByServer will be true.

License

Lithium is licensed under MIT.