Simple WebSockets Client/Server (RFC6455)
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
deps
lib
test
tools
.gitignore
.gitmodules
.npmignore
CHANGES.md
LICENSE
Makefile
README.md
package.json

README.md

node-watershed

A simple implementation of WebSockets for use with node.js 'http'-style web server or client. Deals only with RFC6455, ignoring any Browser-specific peculiarities, curiosities, and fallback mechanisms.

API

Watershed

The core of this library is a Factory-style class Watershed. It has several static methods:

Watershed.accept(http.ServerRequest, net.Socket, Buffer[, Boolean[, String[] ]])

Responds to a client's request to Upgrade an HTTP connection to a WebSocket and returns a WatershedConnection, which is also an EventEmitter.

The arguments to this method should ideally come from the 'upgrade' event on a node.js http.Server. For example:

var shed = new Watershed();
var srv = http.createServer();
srv.listen(8080);
srv.on('upgrade', function(req, socket, head) {
        var wsc;
        try {
                wsc = shed.accept(req, socket, head);
        } catch (ex) {
                console.error('error: ' + ex.message);
                return socket.end();
        }
        wsc.on('text', function(text) {
                console.log('received text: ' + text);
        });
        wsc.on('end', function() {
                console.log('end!');
        });
        /* ... etc ... */
});

The additional penultimate boolean argument may be used when implementing a websocket-to-websocket proxy. If set to true, then accept() returns the raw underlying Socket of the connection and does not construct a WatershedConnection instance. No event handlers will be placed on the socket, meaning you are free to continue using it directly (e.g. calling pipe() on it to join it to a backend socket).

The final list-of-strings argument can be optionally provided to allow for the use of WebSocket subprotocol negotiation. It is a list of case-sensitive string names of supported subprotocols. If given, and protocol negotiation takes place, the chosen subprotocol can be found with the getProtocol() method.

Watershed.generateKey()

Returns a random, Base64-encoded 16-byte value suitable for use as the Sec-WebSocket-Key header on an Upgrade request. See Example usage in connect().

Watershed.connect(http.ClientResponse, net.Socket, Buffer, String)

Attaches a new client-side WatershedConnection to this presently Upgraded socket.

The arguments to this method should ideally come from the 'upgrade' event on a node.js http.Client. For example:

var shed = new Watershed();
var wskey = shed.generateKey();
var options = {
    port: 8082,
    hostname: '127.0.0.1',
    headers: {
        'connection': 'upgrade',
        'upgrade': 'websocket',
        'Sec-WebSocket-Key': wskey,
        'Sec-WebSocket-Version': '13'
    }
};
var req = http.request(options);
req.end();
req.on('upgrade', function(res, socket, head) {
        var wsc = shed.connect(res, socket, head, wskey);
        wsc.send('Hi there!');
        wsc.on('end', function() {
                console.log('end!');
        });
        /* ... etc ... */
});

WatershedConnection

Event: 'error'

Emitted once when an error occurs during processing. The socket will be closed and an 'end' event will follow. The only argument will be an instance of Error.

Event: 'connectionReset'

Emitted when the remote peer closes the connection without sending us a CLOSE frame. An 'end' event will follow.

Event: 'end' (code, reason)

Emitted once when the socket is closing. If we received a graceful CLOSE frame from the remote server, we will attempt to process it and pass code and reason -- both of type String.

Event: 'text'

Emitted for each inbound TEXT frame. The only argument will be a String containing the UTF-8 string payload.

Event: 'binary'

Emitted for each inbound BINARY frame. The only argument will be a Buffer containing the binary payload.

Event: 'ping'

Emitted for each inbound PING frame. The only argument will be a Buffer containing the nonce in the ping request. Note that the library presently responds with a PONG frame for each inbound PING frame.

Event: 'pong'

Emitted for each inbound PONG frame. The only argument will be a Buffer containing the nonce in the pong response.

WatershedConnection.getProtocol()

Returns the negotiated subprotocol, if any, for this connection, as a String. If no subprotocol negotiation took place, this method returns null.

WatershedConnection.send(data)

Sends a frame through the socket. The single argument data may be a Buffer, in which case a BINARY frame is sent; or a String, in which case a TEXT frame is sent.

WatershedConnection.end(reason)

Closes the connection. The RFC allows a reason for closing the connection to be send in the CLOSE frame, though this is optional. If passed, reason should be a String.

WatershedConnection.destroy()

Immediately destroy the underlying socket, without sending a CLOSE frame. You generally want end(), rather than this, in order to perform RFC-compliant connection shutdowns.

License

MIT.