|
|
|
@@ -6,12 +6,11 @@
|
|
|
|
|
[client](http://faye.jcoglan.com/autobahn/clients/)
|
|
|
|
|
|
|
|
|
|
This is a general-purpose WebSocket implementation extracted from the
|
|
|
|
|
[Faye](http://faye.jcoglan.com) project. It provides classes for easily
|
|
|
|
|
building WebSocket servers and clients in Node. It does not provide a server
|
|
|
|
|
itself, but rather makes it easy to handle WebSocket connections within an
|
|
|
|
|
existing [Node](http://nodejs.org/) application. It does not provide any
|
|
|
|
|
abstraction other than the standard [WebSocket
|
|
|
|
|
API](http://dev.w3.org/html5/websockets/).
|
|
|
|
|
[Faye](http://faye.jcoglan.com) project. It provides classes for easily building
|
|
|
|
|
WebSocket servers and clients in Node. It does not provide a server itself, but
|
|
|
|
|
rather makes it easy to handle WebSocket connections within an existing
|
|
|
|
|
[Node](http://nodejs.org/) application. It does not provide any abstraction
|
|
|
|
|
other than the standard [WebSocket API](http://dev.w3.org/html5/websockets/).
|
|
|
|
|
|
|
|
|
|
It also provides an abstraction for handling
|
|
|
|
|
[EventSource](http://dev.w3.org/html5/eventsource/) connections, which are
|
|
|
|
@@ -77,10 +76,9 @@ If you need to detect when the WebSocket handshake is complete, you can use the
|
|
|
|
|
|
|
|
|
|
If the connection's protocol version supports it, you can call `ws.ping()` to
|
|
|
|
|
send a ping message and wait for the client's response. This method takes a
|
|
|
|
|
message string, and an optional callback that fires when a matching pong
|
|
|
|
|
message is received. It returns `true` iff a ping message was sent. If the
|
|
|
|
|
client does not support ping/pong, this method sends no data and returns
|
|
|
|
|
`false`.
|
|
|
|
|
message string, and an optional callback that fires when a matching pong message
|
|
|
|
|
is received. It returns `true` iff a ping message was sent. If the client does
|
|
|
|
|
not support ping/pong, this method sends no data and returns `false`.
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
ws.ping('Mic check, one, two', function() {
|
|
|
|
@@ -169,14 +167,14 @@ array of extensions to the `:extensions` option. For example, to add
|
|
|
|
|
```js
|
|
|
|
|
var deflate = require('permessage-deflate');
|
|
|
|
|
|
|
|
|
|
var ws = new WebSocket(request, null, {extensions: [deflate]});
|
|
|
|
|
var ws = new WebSocket(request, socket, body, null, {extensions: [deflate]});
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Initialization options
|
|
|
|
|
|
|
|
|
|
Both the server- and client-side classes allow an options object to be passed
|
|
|
|
|
in at initialization time, for example:
|
|
|
|
|
Both the server- and client-side classes allow an options object to be passed in
|
|
|
|
|
at initialization time, for example:
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
var ws = new WebSocket(request, socket, body, protocols, options);
|
|
|
|
@@ -193,8 +191,8 @@ var ws = new WebSocket.Client(url, protocols, options);
|
|
|
|
|
be sent during the handshake process
|
|
|
|
|
* `maxLength` - the maximum allowed size of incoming message frames, in bytes.
|
|
|
|
|
The default value is `2^26 - 1`, or 1 byte short of 64 MiB.
|
|
|
|
|
* `ping` - an integer that sets how often the WebSocket should send ping
|
|
|
|
|
frames, measured in seconds
|
|
|
|
|
* `ping` - an integer that sets how often the WebSocket should send ping frames,
|
|
|
|
|
measured in seconds
|
|
|
|
|
|
|
|
|
|
The client accepts some additional options:
|
|
|
|
|
|
|
|
|
@@ -218,19 +216,19 @@ Both server- and client-side `WebSocket` objects support the following API.
|
|
|
|
|
due to bad data sent by the other peer. This event is purely informational,
|
|
|
|
|
you do not need to implement error recover.
|
|
|
|
|
* <b>`on('close', function(event) {})`</b> fires when either the client or the
|
|
|
|
|
server closes the connection. Event has two optional attributes,
|
|
|
|
|
<b>`code`</b> and <b>`reason`</b>, that expose the status code and message
|
|
|
|
|
sent by the peer that closed the connection.
|
|
|
|
|
server closes the connection. Event has two optional attributes, <b>`code`</b>
|
|
|
|
|
and <b>`reason`</b>, that expose the status code and message sent by the peer
|
|
|
|
|
that closed the connection.
|
|
|
|
|
* <b>`send(message)`</b> accepts either a `String` or a `Buffer` and sends a
|
|
|
|
|
text or binary message over the connection to the other peer.
|
|
|
|
|
* <b>`ping(message = '', function() {})`</b> sends a ping frame with an
|
|
|
|
|
optional message and fires the callback when a matching pong is received.
|
|
|
|
|
* <b>`ping(message = '', function() {})`</b> sends a ping frame with an optional
|
|
|
|
|
message and fires the callback when a matching pong is received.
|
|
|
|
|
* <b>`close(code, reason)`</b> closes the connection, sending the given status
|
|
|
|
|
code and reason text, both of which are optional.
|
|
|
|
|
* <b>`version`</b> is a string containing the version of the `WebSocket`
|
|
|
|
|
protocol the connection is using.
|
|
|
|
|
* <b>`protocol`</b> is a string (which may be empty) identifying the
|
|
|
|
|
subprotocol the socket is using.
|
|
|
|
|
* <b>`protocol`</b> is a string (which may be empty) identifying the subprotocol
|
|
|
|
|
the socket is using.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Handling EventSource connections in Node
|
|
|
|
@@ -283,8 +281,8 @@ The `EventSource` object exposes the following properties:
|
|
|
|
|
* <b>`url`</b> is a string containing the URL the client used to create the
|
|
|
|
|
EventSource.
|
|
|
|
|
* <b>`lastEventId`</b> is a string containing the last event ID received by the
|
|
|
|
|
client. You can use this when the client reconnects after a dropped
|
|
|
|
|
connection to determine which messages need resending.
|
|
|
|
|
client. You can use this when the client reconnects after a dropped connection
|
|
|
|
|
to determine which messages need resending.
|
|
|
|
|
|
|
|
|
|
When you initialize an EventSource with ` new EventSource()`, you can pass
|
|
|
|
|
configuration options after the `response` parameter. Available options are:
|
|
|
|
@@ -293,9 +291,9 @@ configuration options after the `response` parameter. Available options are:
|
|
|
|
|
EventSource response.
|
|
|
|
|
* <b>`retry`</b> is a number that tells the client how long (in seconds) it
|
|
|
|
|
should wait after a dropped connection before attempting to reconnect.
|
|
|
|
|
* <b>`ping`</b> is a number that tells the server how often (in seconds) to
|
|
|
|
|
send 'ping' packets to the client to keep the connection open, to defeat
|
|
|
|
|
timeouts set by proxies. The client will ignore these messages.
|
|
|
|
|
* <b>`ping`</b> is a number that tells the server how often (in seconds) to send
|
|
|
|
|
'ping' packets to the client to keep the connection open, to defeat timeouts
|
|
|
|
|
set by proxies. The client will ignore these messages.
|
|
|
|
|
|
|
|
|
|
For example, this creates a connection that allows access from any origin, pings
|
|
|
|
|
every 15 seconds and is retryable every 10 seconds if the connection is broken:
|
|
|
|
@@ -317,22 +315,21 @@ some data over the wire to keep the connection alive.
|
|
|
|
|
|
|
|
|
|
(The MIT License)
|
|
|
|
|
|
|
|
|
|
Copyright (c) 2010-2014 James Coglan
|
|
|
|
|
Copyright (c) 2010-2015 James Coglan
|
|
|
|
|
|
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
|
|
|
this software and associated documentation files (the 'Software'), to deal in
|
|
|
|
|
the Software without restriction, including without limitation the rights to
|
|
|
|
|
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
|
|
|
|
|
of the Software, and to permit persons to whom the Software is furnished to do
|
|
|
|
|
so, subject to the following conditions:
|
|
|
|
|
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|
|
|
|
the Software, and to permit persons to whom the Software is furnished to do so,
|
|
|
|
|
subject to the following conditions:
|
|
|
|
|
|
|
|
|
|
The above copyright notice and this permission notice shall be included in all
|
|
|
|
|
copies or substantial portions of the Software.
|
|
|
|
|
|
|
|
|
|
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
|
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
|
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
|
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
|
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
|
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
|
|
|
SOFTWARE.
|
|
|
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
|
|
|
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
|
|
|
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
|
|
|
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
|
|
|
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
|
|
|