added unit testing, and started implementing unit tests...phew
This commit is contained in:
Josh Burman
276
node_modules/websocket/README.md
generated
vendored
Normal file
276
node_modules/websocket/README.md
generated
vendored
Normal file
@ -0,0 +1,276 @@
|
||||
WebSocket Client & Server Implementation for Node
|
||||
=================================================
|
||||
|
||||
[](http://badge.fury.io/js/websocket)
|
||||
|
||||
[](https://www.npmjs.com/package/websocket)
|
||||
|
||||
[](https://nodei.co/npm/websocket/)
|
||||
|
||||
[](https://nodei.co/npm/websocket/)
|
||||
|
||||
[ ](https://codeship.com/projects/61106)
|
||||
|
||||
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](https://github.com/theturtle32/AS3WebSocket) project.
|
||||
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
[You can read the full API documentation in the docs folder.](docs/index.md)
|
||||
|
||||
|
||||
Changelog
|
||||
---------
|
||||
|
||||
***Current Version: 1.0.28*** — Released 2018-09-19
|
||||
|
||||
* Updated to latest version of [nan](https://github.com/nodejs/nan)
|
||||
* Plus changes published in 1.0.27:
|
||||
* Allowing additional request `headers` to be specified in the `tlsOptions` config parameter for WebSocketClient. See pull request #323
|
||||
* Resolving deprecation warnings relating to usage of `new Buffer`
|
||||
|
||||
[View the full changelog](CHANGELOG.md)
|
||||
|
||||
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](http://theturtle32.github.com/WebSocket-Node/benchmarks/) 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](http://autobahn.ws/testsuite/) is used by most WebSocket implementations to test spec compliance and interoperability.
|
||||
|
||||
- [View Server Test Results](http://theturtle32.github.com/WebSocket-Node/test-report/servers/)
|
||||
|
||||
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:
|
||||
|
||||
```javascript
|
||||
var WebSocketServer = require('websocket').server;
|
||||
var WebSocketClient = require('websocket').client;
|
||||
var WebSocketFrame = require('websocket').frame;
|
||||
var WebSocketRouter = require('websocket').router;
|
||||
var W3CWebSocket = 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++](http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express)
|
||||
- [Python 2.7](http://www.python.org/download/) (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](https://github.com/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](http://www.w3.org/TR/websockets/) 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.
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
var WebSocketServer = require('websocket').server;
|
||||
var http = require('http');
|
||||
|
||||
var server = http.createServer(function(request, response) {
|
||||
console.log((new Date()) + ' Received request for ' + request.url);
|
||||
response.writeHead(404);
|
||||
response.end();
|
||||
});
|
||||
server.listen(8080, function() {
|
||||
console.log((new Date()) + ' Server is listening on port 8080');
|
||||
});
|
||||
|
||||
wsServer = new WebSocketServer({
|
||||
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
|
||||
});
|
||||
|
||||
function originIsAllowed(origin) {
|
||||
// put logic here to detect whether the specified origin is allowed.
|
||||
return true;
|
||||
}
|
||||
|
||||
wsServer.on('request', function(request) {
|
||||
if (!originIsAllowed(request.origin)) {
|
||||
// Make sure we only accept requests from an allowed origin
|
||||
request.reject();
|
||||
console.log((new Date()) + ' Connection from origin ' + request.origin + ' rejected.');
|
||||
return;
|
||||
}
|
||||
|
||||
var connection = request.accept('echo-protocol', request.origin);
|
||||
console.log((new Date()) + ' Connection accepted.');
|
||||
connection.on('message', function(message) {
|
||||
if (message.type === 'utf8') {
|
||||
console.log('Received Message: ' + message.utf8Data);
|
||||
connection.sendUTF(message.utf8Data);
|
||||
}
|
||||
else if (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((new Date()) + ' 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*
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
var WebSocketClient = require('websocket').client;
|
||||
|
||||
var client = new WebSocketClient();
|
||||
|
||||
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 + "'");
|
||||
}
|
||||
});
|
||||
|
||||
function sendNumber() {
|
||||
if (connection.connected) {
|
||||
var number = 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](http://www.w3.org/TR/websockets/).
|
||||
|
||||
```javascript
|
||||
var W3CWebSocket = require('websocket').w3cwebsocket;
|
||||
|
||||
var client = new W3CWebSocket('ws://localhost:8080/', 'echo-protocol');
|
||||
|
||||
client.onerror = function() {
|
||||
console.log('Connection Error');
|
||||
};
|
||||
|
||||
client.onopen = function() {
|
||||
console.log('WebSocket Client Connected');
|
||||
|
||||
function sendNumber() {
|
||||
if (client.readyState === client.OPEN) {
|
||||
var number = 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 (typeof e.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](http://www.scribd.com/doc/60898569/WebSockets-The-Real-Time-Web-Delivered)
|
||||
Reference in New Issue
Block a user