-
Notifications
You must be signed in to change notification settings - Fork 1
/
package.json
40 lines (40 loc) · 12.2 KB
/
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"name": "websocket-driver",
"description": "WebSocket protocol handler with pluggable I/O",
"homepage": "http://github.com/faye/websocket-driver-node",
"author": {
"name": "James Coglan",
"email": "jcoglan@gmail.com",
"url": "http://jcoglan.com/"
},
"keywords": [
"websocket"
],
"license": "MIT",
"version": "0.3.2",
"engines": {
"node": ">=0.4.0"
},
"main": "./lib/websocket/driver",
"devDependencies": {
"jstest": ""
},
"scripts": {
"test": "jstest spec/runner.js"
},
"repository": {
"type": "git",
"url": "git://github.com/faye/websocket-driver-node.git"
},
"bugs": {
"url": "http://github.com/faye/websocket-driver-node/issues"
},
"readme": "# websocket-driver [![Build Status](https://travis-ci.org/faye/websocket-driver-node.png)](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\nthe protocol details from the I/O layer, such that users only need to implement\ncode to stream data in and out of it without needing to know anything about how\nthe protocol 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\nhook this 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* 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 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\nserver and on the client. A WebSocket driver is an object with two duplex\nstreams attached; one for incoming/outgoing messages and one for managing the\nwire protocol 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\nwhere you 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\nstream to 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.createConnection(80, 'www.example.com');\n\ntcp.pipe(driver.io).pipe(tcp);\n\ndriver.messages.on('data', function(message) {\n console.log('Got a message', message);\n});\n\ntcp.on('connect', function() {\n driver.start();\n});\n```\n\nClient drivers have two additional properties for reading the HTTP data that\nwas sent 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### 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\nwith masking 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\n use 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* <b>`driver.io`</b> - 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,\n and pipe this stream back into TCP to send outgoing frames.\n* <b>`driver.messages`</b> - 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\non the `driver.io` stream.\n\n#### `driver.on('open', function(event) {})`\n\nSets the callback to execute when the socket becomes open.\n\n#### `driver.on('message', function(event) {})`\n\nSets the 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\nSets the 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\nSets the callback to execute when the socket becomes closed. The `event` object\nhas `code` and `reason` attributes.\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` iff 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\nthe driver 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.close()`\n\nInitiates the closing handshake if the socket is still open. For drivers with\nno closing handshake, this will result in the immediate execution of the\n`on('close')` driver. For drivers with a closing handshake, this sends a\nclosing frame and `emit('close')` will execute when a response is received or a\nprotocol error 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\nafter `emit('open')` has fired.\n\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2010-2013 James Coglan\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the 'Software'), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n",
"readmeFilename": "README.md",
"_id": "websocket-driver@0.3.2",
"dist": {
"shasum": "8eb36273b2078c741ce87794c1e5e8bdaa3ba0bd"
},
"_from": "websocket-driver@>=0.3.0",
"_resolved": "https://registry.npmjs.org/websocket-driver/-/websocket-driver-0.3.2.tgz"
}