@fairwords/websocket 1.0.35

package/README.md

@@ -0,0 +1,255 @@
+WebSocket Client & Server Implementation for Node
+=================================================
+
+[![npm version](https://badge.fury.io/js/websocket.svg)](http://badge.fury.io/js/websocket)
+
+[![NPM Downloads](https://img.shields.io/npm/dm/websocket.svg)](https://www.npmjs.com/package/websocket)
+
+[ ![Codeship Status for theturtle32/WebSocket-Node](https://codeship.com/projects/70458270-8ee7-0132-7756-0a0cf4fe8e66/status?branch=master)](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.
+
+
+Documentation
+=============
+
+[You can read the full API documentation in the docs folder.](docs/index.md)
+
+
+Changelog
+---------
+
+***Current Version: 1.0.34*** - Release 2021-04-14
+
+* Updated browser shim to use the native `globalThis` property when available. See [this MDN page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) for context. Resolves [#415](https://github.com/theturtle32/WebSocket-Node/issues/415)
+
+[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)
+
+(Not all W3C WebSocket features are supported by browsers. More info in the [Full API documentation](docs/index.md))
+
+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.
+
+(These benchmarks are quite a bit outdated at this point, so take them with a grain of salt. Anyone up for running new benchmarks? I'll link to your report.)
+
+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
+------------
+
+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;
+```
+
+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)

package/gulpfile.js

@@ -0,0 +1,14 @@
+/**
+ * Dependencies.
+ */
+var gulp = require('gulp');
+var jshint = require('gulp-jshint');
+
+gulp.task('lint', function() {
+	return gulp.src(['gulpfile.js', 'lib/**/*.js', 'test/**/*.js'])
+		.pipe(jshint('.jshintrc'))
+		.pipe(jshint.reporter('jshint-stylish', {verbose: true}))
+		.pipe(jshint.reporter('fail'));
+});
+
+gulp.task('default', gulp.series('lint'));

package/index.js

@@ -0,0 +1 @@
+module.exports = require('./lib/websocket');

package/lib/Deprecation.js

@@ -0,0 +1,32 @@
+/************************************************************************
+ *  Copyright 2010-2015 Brian McKelvey.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ ***********************************************************************/
+
+var Deprecation = {
+    disableWarnings: false,
+
+    deprecationWarningMap: {
+
+    },
+
+    warn: function(deprecationName) {
+        if (!this.disableWarnings && this.deprecationWarningMap[deprecationName]) {
+            console.warn('DEPRECATION WARNING: ' + this.deprecationWarningMap[deprecationName]);
+            this.deprecationWarningMap[deprecationName] = false;
+        }
+    }
+};
+
+module.exports = Deprecation;

package/lib/W3CWebSocket.js

@@ -0,0 +1,257 @@
+/************************************************************************
+ *  Copyright 2010-2015 Brian McKelvey.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ ***********************************************************************/
+
+var WebSocketClient = require('./WebSocketClient');
+var toBuffer = require('typedarray-to-buffer');
+var yaeti = require('yaeti');
+
+
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSING = 2;
+const CLOSED = 3;
+
+
+module.exports = W3CWebSocket;
+
+
+function W3CWebSocket(url, protocols, origin, headers, requestOptions, clientConfig) {
+    // Make this an EventTarget.
+    yaeti.EventTarget.call(this);
+
+    // Sanitize clientConfig.
+    clientConfig = clientConfig || {};
+    clientConfig.assembleFragments = true;  // Required in the W3C API.
+
+    var self = this;
+
+    this._url = url;
+    this._readyState = CONNECTING;
+    this._protocol = undefined;
+    this._extensions = '';
+    this._bufferedAmount = 0;  // Hack, always 0.
+    this._binaryType = 'arraybuffer';  // TODO: Should be 'blob' by default, but Node has no Blob.
+
+    // The WebSocketConnection instance.
+    this._connection = undefined;
+
+    // WebSocketClient instance.
+    this._client = new WebSocketClient(clientConfig);
+
+    this._client.on('connect', function(connection) {
+        onConnect.call(self, connection);
+    });
+
+    this._client.on('connectFailed', function() {
+        onConnectFailed.call(self);
+    });
+
+    this._client.connect(url, protocols, origin, headers, requestOptions);
+}
+
+
+// Expose W3C read only attributes.
+Object.defineProperties(W3CWebSocket.prototype, {
+    url:            { get: function() { return this._url;            } },
+    readyState:     { get: function() { return this._readyState;     } },
+    protocol:       { get: function() { return this._protocol;       } },
+    extensions:     { get: function() { return this._extensions;     } },
+    bufferedAmount: { get: function() { return this._bufferedAmount; } }
+});
+
+
+// Expose W3C write/read attributes.
+Object.defineProperties(W3CWebSocket.prototype, {
+    binaryType: {
+        get: function() {
+            return this._binaryType;
+        },
+        set: function(type) {
+            // TODO: Just 'arraybuffer' supported.
+            if (type !== 'arraybuffer') {
+                throw new SyntaxError('just "arraybuffer" type allowed for "binaryType" attribute');
+            }
+            this._binaryType = type;
+        }
+    }
+});
+
+
+// Expose W3C readyState constants into the WebSocket instance as W3C states.
+[['CONNECTING',CONNECTING], ['OPEN',OPEN], ['CLOSING',CLOSING], ['CLOSED',CLOSED]].forEach(function(property) {
+    Object.defineProperty(W3CWebSocket.prototype, property[0], {
+        get: function() { return property[1]; }
+    });
+});
+
+// Also expose W3C readyState constants into the WebSocket class (not defined by the W3C,
+// but there are so many libs relying on them).
+[['CONNECTING',CONNECTING], ['OPEN',OPEN], ['CLOSING',CLOSING], ['CLOSED',CLOSED]].forEach(function(property) {
+    Object.defineProperty(W3CWebSocket, property[0], {
+        get: function() { return property[1]; }
+    });
+});
+
+
+W3CWebSocket.prototype.send = function(data) {
+    if (this._readyState !== OPEN) {
+        throw new Error('cannot call send() while not connected');
+    }
+
+    // Text.
+    if (typeof data === 'string' || data instanceof String) {
+        this._connection.sendUTF(data);
+    }
+    // Binary.
+    else {
+        // Node Buffer.
+        if (data instanceof Buffer) {
+            this._connection.sendBytes(data);
+        }
+        // If ArrayBuffer or ArrayBufferView convert it to Node Buffer.
+        else if (data.byteLength || data.byteLength === 0) {
+            data = toBuffer(data);
+            this._connection.sendBytes(data);
+        }
+        else {
+            throw new Error('unknown binary data:', data);
+        }
+    }
+};
+
+
+W3CWebSocket.prototype.close = function(code, reason) {
+    switch(this._readyState) {
+        case CONNECTING:
+            // NOTE: We don't have the WebSocketConnection instance yet so no
+            // way to close the TCP connection.
+            // Artificially invoke the onConnectFailed event.
+            onConnectFailed.call(this);
+            // And close if it connects after a while.
+            this._client.on('connect', function(connection) {
+                if (code) {
+                    connection.close(code, reason);
+                } else {
+                    connection.close();
+                }
+            });
+            break;
+        case OPEN:
+            this._readyState = CLOSING;
+            if (code) {
+                this._connection.close(code, reason);
+            } else {
+                this._connection.close();
+            }
+            break;
+        case CLOSING:
+        case CLOSED:
+            break;
+    }
+};
+
+
+/**
+ * Private API.
+ */
+
+
+function createCloseEvent(code, reason) {
+    var event = new yaeti.Event('close');
+
+    event.code = code;
+    event.reason = reason;
+    event.wasClean = (typeof code === 'undefined' || code === 1000);
+
+    return event;
+}
+
+
+function createMessageEvent(data) {
+    var event = new yaeti.Event('message');
+
+    event.data = data;
+
+    return event;
+}
+
+
+function onConnect(connection) {
+    var self = this;
+
+    this._readyState = OPEN;
+    this._connection = connection;
+    this._protocol = connection.protocol;
+    this._extensions = connection.extensions;
+
+    this._connection.on('close', function(code, reason) {
+        onClose.call(self, code, reason);
+    });
+
+    this._connection.on('message', function(msg) {
+        onMessage.call(self, msg);
+    });
+
+    this.dispatchEvent(new yaeti.Event('open'));
+}
+
+
+function onConnectFailed() {
+    destroy.call(this);
+    this._readyState = CLOSED;
+
+    try {
+        this.dispatchEvent(new yaeti.Event('error'));
+    } finally {
+        this.dispatchEvent(createCloseEvent(1006, 'connection failed'));
+    }
+}
+
+
+function onClose(code, reason) {
+    destroy.call(this);
+    this._readyState = CLOSED;
+
+    this.dispatchEvent(createCloseEvent(code, reason || ''));
+}
+
+
+function onMessage(message) {
+    if (message.utf8Data) {
+        this.dispatchEvent(createMessageEvent(message.utf8Data));
+    }
+    else if (message.binaryData) {
+        // Must convert from Node Buffer to ArrayBuffer.
+        // TODO: or to a Blob (which does not exist in Node!).
+        if (this.binaryType === 'arraybuffer') {
+            var buffer = message.binaryData;
+            var arraybuffer = new ArrayBuffer(buffer.length);
+            var view = new Uint8Array(arraybuffer);
+            for (var i=0, len=buffer.length; i<len; ++i) {
+                view[i] = buffer[i];
+            }
+            this.dispatchEvent(createMessageEvent(arraybuffer));
+        }
+    }
+}
+
+
+function destroy() {
+    this._client.removeAllListeners();
+    if (this._connection) {
+        this._connection.removeAllListeners();
+    }
+}