{ "_args": [ [ { "raw": "websocket-driver@>=0.5.1", "scope": null, "escapedName": "websocket-driver", "name": "websocket-driver", "rawSpec": ">=0.5.1", "spec": ">=0.5.1", "type": "range" }, "/home/travis/build/lukesargeant/ember-sparkline/node_modules/faye-websocket" ] ], "_from": "websocket-driver@>=0.5.1", "_id": "websocket-driver@0.7.0", "_inCache": true, "_location": "/websocket-driver", "_nodeVersion": "4.8.4", "_npmOperationalInternal": { "host": "s3://npm-registry-packages", "tmp": "tmp/websocket-driver-0.7.0.tgz_1505163256798_0.4708031218033284" }, "_npmUser": { "name": "jcoglan", "email": "jcoglan@gmail.com" }, "_npmVersion": "2.15.11", "_phantomChildren": {}, "_requested": { "raw": "websocket-driver@>=0.5.1", "scope": null, "escapedName": "websocket-driver", "name": "websocket-driver", "rawSpec": ">=0.5.1", "spec": ">=0.5.1", "type": "range" }, "_requiredBy": [ "/faye-websocket" ], "_resolved": "https://registry.npmjs.org/websocket-driver/-/websocket-driver-0.7.0.tgz", "_shasum": "0caf9d2d755d93aee049d4bdd0d3fe2cca2a24eb", "_shrinkwrap": null, "_spec": "websocket-driver@>=0.5.1", "_where": "/home/travis/build/lukesargeant/ember-sparkline/node_modules/faye-websocket", "author": { "name": "James Coglan", "email": "jcoglan@gmail.com", "url": "http://jcoglan.com/" }, "bugs": { "url": "https://github.com/faye/websocket-driver-node/issues" }, "dependencies": { "http-parser-js": ">=0.4.0", "websocket-extensions": ">=0.1.1" }, "description": "WebSocket protocol handler with pluggable I/O", "devDependencies": { "jstest": "*", "permessage-deflate": "*" }, "directories": {}, "dist": { "shasum": "0caf9d2d755d93aee049d4bdd0d3fe2cca2a24eb", "tarball": "https://registry.npmjs.org/websocket-driver/-/websocket-driver-0.7.0.tgz" }, "engines": { "node": ">=0.8.0" }, "files": [ "lib" ], "gitHead": "8128bec1e03c4eeb3c3bdb250a4356a4c69fe10f", "homepage": "https://github.com/faye/websocket-driver-node", "keywords": [ "websocket" ], "license": "MIT", "main": "./lib/websocket/driver", "maintainers": [ { "name": "jcoglan", "email": "jcoglan@gmail.com" } ], "name": "websocket-driver", "optionalDependencies": {}, "readme": "# websocket-driver [![Build Status](https://travis-ci.org/faye/websocket-driver-node.svg)](https://travis-ci.org/faye/websocket-driver-node)\n\nThis module provides a complete implementation of the WebSocket protocols that\ncan be hooked up to any I/O stream. It aims to simplify things by decoupling the\nprotocol details from the I/O layer, such that users only need to implement code\nto stream data in and out of it without needing to know anything about how the\nprotocol actually works. Think of it as a complete WebSocket system with\npluggable I/O.\n\nDue to this design, you get a lot of things for free. In particular, if you hook\nthis module up to some I/O object, it will do all of this for you:\n\n* Select the correct server-side driver to talk to the client\n* Generate and send both server- and client-side handshakes\n* Recognize when the handshake phase completes and the WS protocol begins\n* Negotiate subprotocol selection based on `Sec-WebSocket-Protocol`\n* Negotiate and use extensions via the\n [websocket-extensions](https://github.com/faye/websocket-extensions-node)\n module\n* Buffer sent messages until the handshake process is finished\n* Deal with proxies that defer delivery of the draft-76 handshake body\n* Notify you when the socket is open and closed and when messages arrive\n* Recombine fragmented messages\n* Dispatch text, binary, ping, pong and close frames\n* Manage the socket-closing handshake process\n* Automatically reply to ping frames with a matching pong\n* Apply masking to messages sent by the client\n\nThis library was originally extracted from the [Faye](http://faye.jcoglan.com)\nproject but now aims to provide simple WebSocket support for any Node-based\nproject.\n\n\n## Installation\n\n```\n$ npm install websocket-driver\n```\n\n\n## Usage\n\nThis module provides protocol drivers that have the same interface on the server\nand on the client. A WebSocket driver is an object with two duplex streams\nattached; one for incoming/outgoing messages and one for managing the wire\nprotocol over an I/O stream. The full API is described below.\n\n\n### Server-side with HTTP\n\nA Node webserver emits a special event for 'upgrade' requests, and this is where\nyou should handle WebSockets. You first check whether the request is a\nWebSocket, and if so you can create a driver and attach the request's I/O stream\nto it.\n\n```js\nvar http = require('http'),\n websocket = require('websocket-driver');\n\nvar server = http.createServer();\n\nserver.on('upgrade', function(request, socket, body) {\n if (!websocket.isWebSocket(request)) return;\n\n var driver = websocket.http(request);\n\n driver.io.write(body);\n socket.pipe(driver.io).pipe(socket);\n\n driver.messages.on('data', function(message) {\n console.log('Got a message', message);\n });\n\n driver.start();\n});\n```\n\nNote the line `driver.io.write(body)` - you must pass the `body` buffer to the\nsocket driver in order to make certain versions of the protocol work.\n\n\n### Server-side with TCP\n\nYou can also handle WebSocket connections in a bare TCP server, if you're not\nusing an HTTP server and don't want to implement HTTP parsing yourself.\n\nThe driver will emit a `connect` event when a request is received, and at this\npoint you can detect whether it's a WebSocket and handle it as such. Here's an\nexample using the Node `net` module:\n\n```js\nvar net = require('net'),\n websocket = require('websocket-driver');\n\nvar server = net.createServer(function(connection) {\n var driver = websocket.server();\n\n driver.on('connect', function() {\n if (websocket.isWebSocket(driver)) {\n driver.start();\n } else {\n // handle other HTTP requests\n }\n });\n\n driver.on('close', function() { connection.end() });\n connection.on('error', function() {});\n\n connection.pipe(driver.io).pipe(connection);\n\n driver.messages.pipe(driver.messages);\n});\n\nserver.listen(4180);\n```\n\nIn the `connect` event, the driver gains several properties to describe the\nrequest, similar to a Node request object, such as `method`, `url` and\n`headers`. However you should remember it's not a real request object; you\ncannot write data to it, it only tells you what request data we parsed from the\ninput.\n\nIf the request has a body, it will be in the `driver.body` buffer, but only as\nmuch of the body as has been piped into the driver when the `connect` event\nfires.\n\n\n### Client-side\n\nSimilarly, to implement a WebSocket client you just need to make a driver by\npassing in a URL. After this you use the driver API as described below to\nprocess incoming data and send outgoing data.\n\n\n```js\nvar net = require('net'),\n websocket = require('websocket-driver');\n\nvar driver = websocket.client('ws://www.example.com/socket'),\n tcp = net.connect(80, 'www.example.com');\n\ntcp.pipe(driver.io).pipe(tcp);\n\ntcp.on('connect', function() {\n driver.start();\n});\n\ndriver.messages.on('data', function(message) {\n console.log('Got a message', message);\n});\n```\n\nClient drivers have two additional properties for reading the HTTP data that was\nsent back by the server:\n\n* `driver.statusCode` - the integer value of the HTTP status code\n* `driver.headers` - an object containing the response headers\n\n\n### HTTP Proxies\n\nThe client driver supports connections via HTTP proxies using the `CONNECT`\nmethod. Instead of sending the WebSocket handshake immediately, it will send a\n`CONNECT` request, wait for a `200` response, and then proceed as normal.\n\nTo use this feature, call `driver.proxy(url)` where `url` is the origin of the\nproxy, including a username and password if required. This produces a duplex\nstream that you should pipe in and out of your TCP connection to the proxy\nserver. When the proxy emits `connect`, you can then pipe `driver.io` to your\nTCP stream and call `driver.start()`.\n\n```js\nvar net = require('net'),\n websocket = require('websocket-driver');\n\nvar driver = websocket.client('ws://www.example.com/socket'),\n proxy = driver.proxy('http://username:password@proxy.example.com'),\n tcp = net.connect(80, 'proxy.example.com');\n\ntcp.pipe(proxy).pipe(tcp, {end: false});\n\ntcp.on('connect', function() {\n proxy.start();\n});\n\nproxy.on('connect', function() {\n driver.io.pipe(tcp).pipe(driver.io);\n driver.start();\n});\n\ndriver.messages.on('data', function(message) {\n console.log('Got a message', message);\n});\n```\n\nThe proxy's `connect` event is also where you should perform a TLS handshake on\nyour TCP stream, if you are connecting to a `wss:` endpoint.\n\nIn the event that proxy connection fails, `proxy` will emit an `error`. You can\ninspect the proxy's response via `proxy.statusCode` and `proxy.headers`.\n\n```js\nproxy.on('error', function(error) {\n console.error(error.message);\n console.log(proxy.statusCode);\n console.log(proxy.headers);\n});\n```\n\nBefore calling `proxy.start()` you can set custom headers using\n`proxy.setHeader()`:\n\n```js\nproxy.setHeader('User-Agent', 'node');\nproxy.start();\n```\n\n\n### Driver API\n\nDrivers are created using one of the following methods:\n\n```js\ndriver = websocket.http(request, options)\ndriver = websocket.server(options)\ndriver = websocket.client(url, options)\n```\n\nThe `http` method returns a driver chosen using the headers from a Node HTTP\nrequest object. The `server` method returns a driver that will parse an HTTP\nrequest and then decide which driver to use for it using the `http` method. The\n`client` method always returns a driver for the RFC version of the protocol with\nmasking enabled on outgoing frames.\n\nThe `options` argument is optional, and is an object. It may contain the\nfollowing fields:\n\n* `maxLength` - the maximum allowed size of incoming message frames, in bytes.\n The default value is `2^26 - 1`, or 1 byte short of 64 MiB.\n* `protocols` - an array of strings representing acceptable subprotocols for use\n over the socket. The driver will negotiate one of these to use via the\n `Sec-WebSocket-Protocol` header if supported by the other peer.\n\nA driver has two duplex streams attached to it:\n\n* `driver.io` - this stream should be attached to an I/O socket like a\n TCP stream. Pipe incoming TCP chunks to this stream for them to be parsed, and\n pipe this stream back into TCP to send outgoing frames.\n* `driver.messages` - this stream emits messages received over the\n WebSocket. Writing to it sends messages to the other peer by emitting frames\n via the `driver.io` stream.\n\nAll drivers respond to the following API methods, but some of them are no-ops\ndepending on whether the client supports the behaviour.\n\nNote that most of these methods are commands: if they produce data that should\nbe sent over the socket, they will give this to you by emitting `data` events on\nthe `driver.io` stream.\n\n#### `driver.on('open', function(event) {})`\n\nAdds a callback to execute when the socket becomes open.\n\n#### `driver.on('message', function(event) {})`\n\nAdds a callback to execute when a message is received. `event` will have a\n`data` attribute containing either a string in the case of a text message or a\n`Buffer` in the case of a binary message.\n\nYou can also listen for messages using the `driver.messages.on('data')` event,\nwhich emits strings for text messages and buffers for binary messages.\n\n#### `driver.on('error', function(event) {})`\n\nAdds a callback to execute when a protocol error occurs due to the other peer\nsending an invalid byte sequence. `event` will have a `message` attribute\ndescribing the error.\n\n#### `driver.on('close', function(event) {})`\n\nAdds a callback to execute when the socket becomes closed. The `event` object\nhas `code` and `reason` attributes.\n\n#### `driver.on('ping', function(event) {})`\n\nAdds a callback block to execute when a ping is received. You do not need to\nhandle this by sending a pong frame yourself; the driver handles this for you.\n\n#### `driver.on('pong', function(event) {})`\n\nAdds a callback block to execute when a pong is received. If this was in\nresponse to a ping you sent, you can also handle this event via the\n`driver.ping(message, function() { ... })` callback.\n\n#### `driver.addExtension(extension)`\n\nRegisters a protocol extension whose operation will be negotiated via the\n`Sec-WebSocket-Extensions` header. `extension` is any extension compatible with\nthe [websocket-extensions](https://github.com/faye/websocket-extensions-node)\nframework.\n\n#### `driver.setHeader(name, value)`\n\nSets a custom header to be sent as part of the handshake response, either from\nthe server or from the client. Must be called before `start()`, since this is\nwhen the headers are serialized and sent.\n\n#### `driver.start()`\n\nInitiates the protocol by sending the handshake - either the response for a\nserver-side driver or the request for a client-side one. This should be the\nfirst method you invoke. Returns `true` if and only if a handshake was sent.\n\n#### `driver.parse(string)`\n\nTakes a string and parses it, potentially resulting in message events being\nemitted (see `on('message')` above) or in data being sent to `driver.io`. You\nshould send all data you receive via I/O to this method by piping a stream into\n`driver.io`.\n\n#### `driver.text(string)`\n\nSends a text message over the socket. If the socket handshake is not yet\ncomplete, the message will be queued until it is. Returns `true` if the message\nwas sent or queued, and `false` if the socket can no longer send messages.\n\nThis method is equivalent to `driver.messages.write(string)`.\n\n#### `driver.binary(buffer)`\n\nTakes a `Buffer` and sends it as a binary message. Will queue and return `true`\nor `false` the same way as the `text` method. It will also return `false` if the\ndriver does not support binary messages.\n\nThis method is equivalent to `driver.messages.write(buffer)`.\n\n#### `driver.ping(string = '', function() {})`\n\nSends a ping frame over the socket, queueing it if necessary. `string` and the\ncallback are both optional. If a callback is given, it will be invoked when the\nsocket receives a pong frame whose content matches `string`. Returns `false` if\nframes can no longer be sent, or if the driver does not support ping/pong.\n\n#### `driver.pong(string = '')`\n\nSends a pong frame over the socket, queueing it if necessary. `string` is\noptional. Returns `false` if frames can no longer be sent, or if the driver does\nnot support ping/pong.\n\nYou don't need to call this when a ping frame is received; pings are replied to\nautomatically by the driver. This method is for sending unsolicited pongs.\n\n#### `driver.close()`\n\nInitiates the closing handshake if the socket is still open. For drivers with no\nclosing handshake, this will result in the immediate execution of the\n`on('close')` driver. For drivers with a closing handshake, this sends a closing\nframe and `emit('close')` will execute when a response is received or a protocol\nerror occurs.\n\n#### `driver.version`\n\nReturns the WebSocket version in use as a string. Will either be `hixie-75`,\n`hixie-76` or `hybi-$version`.\n\n#### `driver.protocol`\n\nReturns a string containing the selected subprotocol, if any was agreed upon\nusing the `Sec-WebSocket-Protocol` mechanism. This value becomes available after\n`emit('open')` has fired.\n", "readmeFilename": "README.md", "repository": { "type": "git", "url": "git://github.com/faye/websocket-driver-node.git" }, "scripts": { "test": "jstest spec/runner.js" }, "version": "0.7.0" }