source: trip-planner-front/node_modules/faye-websocket/README.md@ 188ee53

Last change on this file since 188ee53 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 10.9 KB
Line 
1# faye-websocket
2
3This is a general-purpose WebSocket implementation extracted from the
4[Faye](http://faye.jcoglan.com) project. It provides classes for easily building
5WebSocket servers and clients in Node. It does not provide a server itself, but
6rather makes it easy to handle WebSocket connections within an existing
7[Node](https://nodejs.org/) application. It does not provide any abstraction
8other than the standard [WebSocket
9API](https://html.spec.whatwg.org/multipage/comms.html#network).
10
11It also provides an abstraction for handling
12[EventSource](https://html.spec.whatwg.org/multipage/comms.html#server-sent-events)
13connections, which are one-way connections that allow the server to push data to
14the client. They are based on streaming HTTP responses and can be easier to access
15via proxies than WebSockets.
16
17
18## Installation
19
20```
21$ npm install faye-websocket
22```
23
24
25## Handling WebSocket connections in Node
26
27You can handle WebSockets on the server side by listening for HTTP Upgrade
28requests, and creating a new socket for the request. This socket object exposes
29the usual WebSocket methods for receiving and sending messages. For example this
30is how you'd implement an echo server:
31
32```js
33var WebSocket = require('faye-websocket'),
34 http = require('http');
35
36var server = http.createServer();
37
38server.on('upgrade', function(request, socket, body) {
39 if (WebSocket.isWebSocket(request)) {
40 var ws = new WebSocket(request, socket, body);
41
42 ws.on('message', function(event) {
43 ws.send(event.data);
44 });
45
46 ws.on('close', function(event) {
47 console.log('close', event.code, event.reason);
48 ws = null;
49 });
50 }
51});
52
53server.listen(8000);
54```
55
56`WebSocket` objects are also duplex streams, so you could replace the
57`ws.on('message', ...)` line with:
58
59```js
60 ws.pipe(ws);
61```
62
63Note that under certain circumstances (notably a draft-76 client connecting
64through an HTTP proxy), the WebSocket handshake will not be complete after you
65call `new WebSocket()` because the server will not have received the entire
66handshake from the client yet. In this case, calls to `ws.send()` will buffer
67the message in memory until the handshake is complete, at which point any
68buffered messages will be sent to the client.
69
70If you need to detect when the WebSocket handshake is complete, you can use the
71`onopen` event.
72
73If the connection's protocol version supports it, you can call `ws.ping()` to
74send a ping message and wait for the client's response. This method takes a
75message string, and an optional callback that fires when a matching pong message
76is received. It returns `true` if and only if a ping message was sent. If the
77client does not support ping/pong, this method sends no data and returns
78`false`.
79
80```js
81ws.ping('Mic check, one, two', function() {
82 // fires when pong is received
83});
84```
85
86
87## Using the WebSocket client
88
89The client supports both the plain-text `ws` protocol and the encrypted `wss`
90protocol, and has exactly the same interface as a socket you would use in a web
91browser. On the wire it identifies itself as `hybi-13`.
92
93```js
94var WebSocket = require('faye-websocket'),
95 ws = new WebSocket.Client('ws://www.example.com/');
96
97ws.on('open', function(event) {
98 console.log('open');
99 ws.send('Hello, world!');
100});
101
102ws.on('message', function(event) {
103 console.log('message', event.data);
104});
105
106ws.on('close', function(event) {
107 console.log('close', event.code, event.reason);
108 ws = null;
109});
110```
111
112The WebSocket client also lets you inspect the status and headers of the
113handshake response via its `statusCode` and `headers` properties.
114
115To connect via a proxy, set the `proxy` option to the HTTP origin of the proxy,
116including any authorization information, custom headers and TLS config you
117require. Only the `origin` setting is required.
118
119```js
120var ws = new WebSocket.Client('ws://www.example.com/', [], {
121 proxy: {
122 origin: 'http://username:password@proxy.example.com',
123 headers: { 'User-Agent': 'node' },
124 tls: { cert: fs.readFileSync('client.crt') }
125 }
126});
127```
128
129The `tls` value is an object that will be passed to
130[`tls.connect()`](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
131
132
133## Subprotocol negotiation
134
135The WebSocket protocol allows peers to select and identify the application
136protocol to use over the connection. On the client side, you can set which
137protocols the client accepts by passing a list of protocol names when you
138construct the socket:
139
140```js
141var ws = new WebSocket.Client('ws://www.example.com/', ['irc', 'amqp']);
142```
143
144On the server side, you can likewise pass in the list of protocols the server
145supports after the other constructor arguments:
146
147```js
148var ws = new WebSocket(request, socket, body, ['irc', 'amqp']);
149```
150
151If the client and server agree on a protocol, both the client- and server-side
152socket objects expose the selected protocol through the `ws.protocol` property.
153
154
155## Protocol extensions
156
157faye-websocket is based on the
158[websocket-extensions](https://github.com/faye/websocket-extensions-node)
159framework that allows extensions to be negotiated via the
160`Sec-WebSocket-Extensions` header. To add extensions to a connection, pass an
161array of extensions to the `:extensions` option. For example, to add
162[permessage-deflate](https://github.com/faye/permessage-deflate-node):
163
164```js
165var deflate = require('permessage-deflate');
166
167var ws = new WebSocket(request, socket, body, [], { extensions: [deflate] });
168```
169
170
171## Initialization options
172
173Both the server- and client-side classes allow an options object to be passed in
174at initialization time, for example:
175
176```js
177var ws = new WebSocket(request, socket, body, protocols, options);
178var ws = new WebSocket.Client(url, protocols, options);
179```
180
181`protocols` is an array of subprotocols as described above, or `null`.
182`options` is an optional object containing any of these fields:
183
184- `extensions` - an array of
185 [websocket-extensions](https://github.com/faye/websocket-extensions-node)
186 compatible extensions, as described above
187- `headers` - an object containing key-value pairs representing HTTP headers to
188 be sent during the handshake process
189- `maxLength` - the maximum allowed size of incoming message frames, in bytes.
190 The default value is `2^26 - 1`, or 1 byte short of 64 MiB.
191- `ping` - an integer that sets how often the WebSocket should send ping frames,
192 measured in seconds
193
194The client accepts some additional options:
195
196- `proxy` - settings for a proxy as described above
197- `net` - an object containing settings for the origin server that will be
198 passed to
199 [`net.connect()`](https://nodejs.org/api/net.html#net_socket_connect_options_connectlistener)
200- `tls` - an object containing TLS settings for the origin server, this will be
201 passed to
202 [`tls.connect()`](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback)
203- `ca` - (legacy) a shorthand for passing `{ tls: { ca: value } }`
204
205
206## WebSocket API
207
208Both server- and client-side `WebSocket` objects support the following API.
209
210- **`on('open', function(event) {})`** fires when the socket connection is
211 established. Event has no attributes.
212- **`on('message', function(event) {})`** fires when the socket receives a
213 message. Event has one attribute, **`data`**, which is either a `String` (for
214 text frames) or a `Buffer` (for binary frames).
215- **`on('error', function(event) {})`** fires when there is a protocol error due
216 to bad data sent by the other peer. This event is purely informational, you do
217 not need to implement error recover.
218- **`on('close', function(event) {})`** fires when either the client or the
219 server closes the connection. Event has two optional attributes, **`code`**
220 and **`reason`**, that expose the status code and message sent by the peer
221 that closed the connection.
222- **`send(message)`** accepts either a `String` or a `Buffer` and sends a text
223 or binary message over the connection to the other peer.
224- **`ping(message, function() {})`** sends a ping frame with an optional message
225 and fires the callback when a matching pong is received.
226- **`close(code, reason)`** closes the connection, sending the given status code
227 and reason text, both of which are optional.
228- **`version`** is a string containing the version of the `WebSocket` protocol
229 the connection is using.
230- **`protocol`** is a string (which may be empty) identifying the subprotocol
231 the socket is using.
232
233
234## Handling EventSource connections in Node
235
236EventSource connections provide a very similar interface, although because they
237only allow the server to send data to the client, there is no `onmessage` API.
238EventSource allows the server to push text messages to the client, where each
239message has an optional event-type and ID.
240
241```js
242var WebSocket = require('faye-websocket'),
243 EventSource = WebSocket.EventSource,
244 http = require('http');
245
246var server = http.createServer();
247
248server.on('request', function(request, response) {
249 if (EventSource.isEventSource(request)) {
250 var es = new EventSource(request, response);
251 console.log('open', es.url, es.lastEventId);
252
253 // Periodically send messages
254 var loop = setInterval(function() { es.send('Hello') }, 1000);
255
256 es.on('close', function() {
257 clearInterval(loop);
258 es = null;
259 });
260
261 } else {
262 // Normal HTTP request
263 response.writeHead(200, { 'Content-Type': 'text/plain' });
264 response.end('Hello');
265 }
266});
267
268server.listen(8000);
269```
270
271The `send` method takes two optional parameters, `event` and `id`. The default
272event-type is `'message'` with no ID. For example, to send a `notification`
273event with ID `99`:
274
275```js
276es.send('Breaking News!', { event: 'notification', id: '99' });
277```
278
279The `EventSource` object exposes the following properties:
280
281- **`url`** is a string containing the URL the client used to create the
282 EventSource.
283- **`lastEventId`** is a string containing the last event ID received by the
284 client. You can use this when the client reconnects after a dropped connection
285 to determine which messages need resending.
286
287When you initialize an EventSource with ` new EventSource()`, you can pass
288configuration options after the `response` parameter. Available options are:
289
290- **`headers`** is an object containing custom headers to be set on the
291 EventSource response.
292- **`retry`** is a number that tells the client how long (in seconds) it should
293 wait after a dropped connection before attempting to reconnect.
294- **`ping`** is a number that tells the server how often (in seconds) to send
295 'ping' packets to the client to keep the connection open, to defeat timeouts
296 set by proxies. The client will ignore these messages.
297
298For example, this creates a connection that allows access from any origin, pings
299every 15 seconds and is retryable every 10 seconds if the connection is broken:
300
301```js
302var es = new EventSource(request, response, {
303 headers: { 'Access-Control-Allow-Origin': '*' },
304 ping: 15,
305 retry: 10
306});
307```
308
309You can send a ping message at any time by calling `es.ping()`. Unlike
310WebSocket, the client does not send a response to this; it is merely to send
311some data over the wire to keep the connection alive.
Note: See TracBrowser for help on using the repository browser.