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.29 — Released 2019-07-03
- Updated some dependencies and updated the .gitignore and .npmignore files
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.
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:
var WebSocketServer = server;var WebSocketClient = client;var WebSocketFrame = frame;var WebSocketRouter = router;var W3CWebSocket = 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 nodevar WebSocketServer = server;var http = ; var server = http;server; wsServer = 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; { // put logic here to detect whether the specified origin is allowed. return true;} wsServer;
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 nodevar WebSocketClient = client; var client = ; client; client; client;
Client Example using the W3C WebSocket API
Same example as above but using the W3C WebSocket API.
var W3CWebSocket = w3cwebsocket; var client = 'ws://localhost:8080/' 'echo-protocol'; client { console;}; client { console; { if clientreadyState === clientOPEN var number = Math; client; ; } ;}; client { console;}; client { if typeof edata === 'string' console; };
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