WebSocket Client & Server Implementation for Node

Overview

This is a (mostly) pure JavaScript implementation of the WebSocket protocol versions 8 and 13 for Node. There are some example client and server applications that implement various interoperability testing protocols in the "test/scripts" folder.

For a WebSocket client written in ActionScript 3, see my AS3WebScocket project.

Documentation

You can read the full API documentation in the docs folder.

Changelog

Current Version: 1.0.31 — Released 2019-12-06

• Fix infinite loop in error handling (Thanks, @apirila)
• Fix memory leak with multiple WebSocket servers on the same HTTP server (Thanks, @nazar-pc)
• Use es5-ext/global as a more robust way to resolve browser's window object (Thanks, @michaelsbradleyjr)
• Adding compatibility with V8 release greater than v7.6 (node and electron engines) (Thanks, @artynet)

View the full changelog

Browser Support

All current browsers are fully supported.

• Firefox 7-9 (Old) (Protocol Version 8)
• Firefox 10+ (Protocol Version 13)
• Chrome 14,15 (Old) (Protocol Version 8)
• Chrome 16+ (Protocol Version 13)
• Internet Explorer 10+ (Protocol Version 13)
• Safari 6+ (Protocol Version 13)

Safari older than 6.0 is not supported since it uses a very old draft of WebSockets

If you need to simultaneously support legacy browser versions that had implemented draft-75/draft-76/draft-00, take a look here: https://gist.github.com/1428579

Benchmarks

There are some basic benchmarking sections in the Autobahn test suite. I've put up a benchmark page that shows the results from the Autobahn tests run against AutobahnServer 0.4.10, WebSocket-Node 1.0.2, WebSocket-Node 1.0.4, and ws 0.3.4.

Autobahn Tests

The very complete Autobahn Test Suite is used by most WebSocket implementations to test spec compliance and interoperability.

• View Server Test Results

Installation

A few users have reported difficulties building the native extensions without first manually installing node-gyp. If you have trouble building the native extensions, make sure you've got a C++ compiler, and have done npm install -g node-gyp first.

Native extensions are optional, however, and WebSocket-Node will work even if the extensions cannot be compiled.

In your project root:

$ npm install websocket

Then in your code:

varWebSocketServer=require('websocket').server;varWebSocketClient=require('websocket').client;varWebSocketFrame=require('websocket').frame;varWebSocketRouter=require('websocket').router;varW3CWebSocket=require('websocket').w3cwebsocket;

Note for Windows Users

Because there is a small C++ component used for validating UTF-8 data, you will need to install a few other software packages in addition to Node to be able to build this module:

• Microsoft Visual C++
• Python 2.7 (NOT Python 3.x)

Current Features:

• Licensed under the Apache License, Version 2.0
• Protocol version "8" and "13" (Draft-08 through the final RFC) framing and handshake
• Can handle/aggregate received fragmented messages
• Can fragment outgoing messages
• Router to mount multiple applications to various path and protocol combinations
• TLS supported for outbound connections via WebSocketClient
• TLS supported for server connections (use https.createServer instead of http.createServer)
  • Thanks to pors for confirming this!
• Cookie setting and parsing
• Tunable settings
  • Max Receivable Frame Size
  • Max Aggregate ReceivedMessage Size
  • Whether to fragment outgoing messages
  • Fragmentation chunk size for outgoing messages
  • Whether to automatically send ping frames for the purposes of keepalive
  • Keep-alive ping interval
  • Whether or not to automatically assemble received fragments (allows application to handle individual fragments directly)
  • How long to wait after sending a close frame for acknowledgment before closing the socket.
• W3C WebSocket API for applications running on both Node and browsers (via the W3CWebSocket class).

Known Issues/Missing Features:

• No API for user-provided protocol extensions.

Usage Examples

Server Example

Here's a short example showing a server that echos back anything sent to it, whether utf-8 or binary.

#!/usr/bin/env node
varWebSocketServer=require('websocket').server;varhttp=require('http');varserver=http.createServer(function(request,response){console.log((newDate())+' Received request for '+request.url);response.writeHead(404);response.end();});server.listen(8080,function(){console.log((newDate())+' Server is listening on port 8080');});wsServer=newWebSocketServer({httpServer: server,// You should not use autoAcceptConnections for production// applications, as it defeats all standard cross-origin protection// facilities built into the protocol and the browser. You should// *always* verify the connection's origin and decide whether or not// to accept it.autoAcceptConnections: false});functionoriginIsAllowed(origin){// put logic here to detect whether the specified origin is allowed.returntrue;}wsServer.on('request',function(request){if(!originIsAllowed(request.origin)){// Make sure we only accept requests from an allowed originrequest.reject();console.log((newDate())+' Connection from origin '+request.origin+' rejected.');return;}varconnection=request.accept('echo-protocol',request.origin);console.log((newDate())+' Connection accepted.');connection.on('message',function(message){if(message.type==='utf8'){console.log('Received Message: '+message.utf8Data);connection.sendUTF(message.utf8Data);}elseif(message.type==='binary'){console.log('Received Binary Message of '+message.binaryData.length+' bytes');connection.sendBytes(message.binaryData);}});connection.on('close',function(reasonCode,description){console.log((newDate())+' Peer '+connection.remoteAddress+' disconnected.');});});

Client Example

This is a simple example client that will print out any utf-8 messages it receives on the console, and periodically sends a random number.

This code demonstrates a client in Node.js, not in the browser

#!/usr/bin/env node
varWebSocketClient=require('websocket').client;varclient=newWebSocketClient();client.on('connectFailed',function(error){console.log('Connect Error: '+error.toString());});client.on('connect',function(connection){console.log('WebSocket Client Connected');connection.on('error',function(error){console.log("Connection Error: "+error.toString());});connection.on('close',function(){console.log('echo-protocol Connection Closed');});connection.on('message',function(message){if(message.type==='utf8'){console.log("Received: '"+message.utf8Data+"'");}});functionsendNumber(){if(connection.connected){varnumber=Math.round(Math.random()*0xFFFFFF);connection.sendUTF(number.toString());setTimeout(sendNumber,1000);}}sendNumber();});client.connect('ws://localhost:8080/','echo-protocol');

Client Example using the W3C WebSocket API

Same example as above but using the W3C WebSocket API.

varW3CWebSocket=require('websocket').w3cwebsocket;varclient=newW3CWebSocket('ws://localhost:8080/','echo-protocol');client.onerror=function(){console.log('Connection Error');};client.onopen=function(){console.log('WebSocket Client Connected');functionsendNumber(){if(client.readyState===client.OPEN){varnumber=Math.round(Math.random()*0xFFFFFF);client.send(number.toString());setTimeout(sendNumber,1000);}}sendNumber();};client.onclose=function(){console.log('echo-protocol Client Closed');};client.onmessage=function(e){if(typeofe.data==='string'){console.log("Received: '"+e.data+"'");}};

Request Router Example

For an example of using the request router, see libwebsockets-test-server.js in the test folder.

Resources

A presentation on the state of the WebSockets protocol that I gave on July 23, 2011 at the LA Hacker News meetup. WebSockets: The Real-Time Web, Delivered