source: trip-planner-front/node_modules/websocket-extensions/README.md@ bdd6491

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

initial commit

  • Property mode set to 100644
File size: 12.8 KB
Line 
1# websocket-extensions [![Build status](https://secure.travis-ci.org/faye/websocket-extensions-node.svg)](http://travis-ci.org/faye/websocket-extensions-node)
2
3A minimal framework that supports the implementation of WebSocket extensions in
4a way that's decoupled from the main protocol. This library aims to allow a
5WebSocket extension to be written and used with any protocol library, by
6defining abstract representations of frames and messages that allow modules to
7co-operate.
8
9`websocket-extensions` provides a container for registering extension plugins,
10and provides all the functions required to negotiate which extensions to use
11during a session via the `Sec-WebSocket-Extensions` header. By implementing the
12APIs defined in this document, an extension may be used by any WebSocket library
13based on this framework.
14
15## Installation
16
17```
18$ npm install websocket-extensions
19```
20
21## Usage
22
23There are two main audiences for this library: authors implementing the
24WebSocket protocol, and authors implementing extensions. End users of a
25WebSocket library or an extension should be able to use any extension by passing
26it as an argument to their chosen protocol library, without needing to know how
27either of them work, or how the `websocket-extensions` framework operates.
28
29The library is designed with the aim that any protocol implementation and any
30extension can be used together, so long as they support the same abstract
31representation of frames and messages.
32
33### Data types
34
35The APIs provided by the framework rely on two data types; extensions will
36expect to be given data and to be able to return data in these formats:
37
38#### *Frame*
39
40*Frame* is a structure representing a single WebSocket frame of any type. Frames
41are simple objects that must have at least the following properties, which
42represent the data encoded in the frame:
43
44| property | description |
45| ------------ | ------------------------------------------------------------------ |
46| `final` | `true` if the `FIN` bit is set, `false` otherwise |
47| `rsv1` | `true` if the `RSV1` bit is set, `false` otherwise |
48| `rsv2` | `true` if the `RSV2` bit is set, `false` otherwise |
49| `rsv3` | `true` if the `RSV3` bit is set, `false` otherwise |
50| `opcode` | the numeric opcode (`0`, `1`, `2`, `8`, `9`, or `10`) of the frame |
51| `masked` | `true` if the `MASK` bit is set, `false` otherwise |
52| `maskingKey` | a 4-byte `Buffer` if `masked` is `true`, otherwise `null` |
53| `payload` | a `Buffer` containing the (unmasked) application data |
54
55#### *Message*
56
57A *Message* represents a complete application message, which can be formed from
58text, binary and continuation frames. It has the following properties:
59
60| property | description |
61| -------- | ----------------------------------------------------------------- |
62| `rsv1` | `true` if the first frame of the message has the `RSV1` bit set |
63| `rsv2` | `true` if the first frame of the message has the `RSV2` bit set |
64| `rsv3` | `true` if the first frame of the message has the `RSV3` bit set |
65| `opcode` | the numeric opcode (`1` or `2`) of the first frame of the message |
66| `data` | the concatenation of all the frame payloads in the message |
67
68### For driver authors
69
70A driver author is someone implementing the WebSocket protocol proper, and who
71wishes end users to be able to use WebSocket extensions with their library.
72
73At the start of a WebSocket session, on both the client and the server side,
74they should begin by creating an extension container and adding whichever
75extensions they want to use.
76
77```js
78var Extensions = require('websocket-extensions'),
79 deflate = require('permessage-deflate');
80
81var exts = new Extensions();
82exts.add(deflate);
83```
84
85In the following examples, `exts` refers to this `Extensions` instance.
86
87#### Client sessions
88
89Clients will use the methods `generateOffer()` and `activate(header)`.
90
91As part of the handshake process, the client must send a
92`Sec-WebSocket-Extensions` header to advertise that it supports the registered
93extensions. This header should be generated using:
94
95```js
96request.headers['sec-websocket-extensions'] = exts.generateOffer();
97```
98
99This returns a string, for example `"permessage-deflate;
100client_max_window_bits"`, that represents all the extensions the client is
101offering to use, and their parameters. This string may contain multiple offers
102for the same extension.
103
104When the client receives the handshake response from the server, it should pass
105the incoming `Sec-WebSocket-Extensions` header in to `exts` to activate the
106extensions the server has accepted:
107
108```js
109exts.activate(response.headers['sec-websocket-extensions']);
110```
111
112If the server has sent any extension responses that the client does not
113recognize, or are in conflict with one another for use of RSV bits, or that use
114invalid parameters for the named extensions, then `exts.activate()` will
115`throw`. In this event, the client driver should fail the connection with
116closing code `1010`.
117
118#### Server sessions
119
120Servers will use the method `generateResponse(header)`.
121
122A server session needs to generate a `Sec-WebSocket-Extensions` header to send
123in its handshake response:
124
125```js
126var clientOffer = request.headers['sec-websocket-extensions'],
127 extResponse = exts.generateResponse(clientOffer);
128
129response.headers['sec-websocket-extensions'] = extResponse;
130```
131
132Calling `exts.generateResponse(header)` activates those extensions the client
133has asked to use, if they are registered, asks each extension for a set of
134response parameters, and returns a string containing the response parameters for
135all accepted extensions.
136
137#### In both directions
138
139Both clients and servers will use the methods `validFrameRsv(frame)`,
140`processIncomingMessage(message)` and `processOutgoingMessage(message)`.
141
142The WebSocket protocol requires that frames do not have any of the `RSV` bits
143set unless there is an extension in use that allows otherwise. When processing
144an incoming frame, sessions should pass a *Frame* object to:
145
146```js
147exts.validFrameRsv(frame)
148```
149
150If this method returns `false`, the session should fail the WebSocket connection
151with closing code `1002`.
152
153To pass incoming messages through the extension stack, a session should
154construct a *Message* object according to the above datatype definitions, and
155call:
156
157```js
158exts.processIncomingMessage(message, function(error, msg) {
159 // hand the message off to the application
160});
161```
162
163If any extensions fail to process the message, then the callback will yield an
164error and the session should fail the WebSocket connection with closing code
165`1010`. If `error` is `null`, then `msg` should be passed on to the application.
166
167To pass outgoing messages through the extension stack, a session should
168construct a *Message* as before, and call:
169
170```js
171exts.processOutgoingMessage(message, function(error, msg) {
172 // write message to the transport
173});
174```
175
176If any extensions fail to process the message, then the callback will yield an
177error and the session should fail the WebSocket connection with closing code
178`1010`. If `error` is `null`, then `message` should be converted into frames
179(with the message's `rsv1`, `rsv2`, `rsv3` and `opcode` set on the first frame)
180and written to the transport.
181
182At the end of the WebSocket session (either when the protocol is explicitly
183ended or the transport connection disconnects), the driver should call:
184
185```js
186exts.close(function() {})
187```
188
189The callback is invoked when all extensions have finished processing any
190messages in the pipeline and it's safe to close the socket.
191
192### For extension authors
193
194An extension author is someone implementing an extension that transforms
195WebSocket messages passing between the client and server. They would like to
196implement their extension once and have it work with any protocol library.
197
198Extension authors will not install `websocket-extensions` or call it directly.
199Instead, they should implement the following API to allow their extension to
200plug into the `websocket-extensions` framework.
201
202An `Extension` is any object that has the following properties:
203
204| property | description |
205| -------- | ---------------------------------------------------------------------------- |
206| `name` | a string containing the name of the extension as used in negotiation headers |
207| `type` | a string, must be `"permessage"` |
208| `rsv1` | either `true` if the extension uses the RSV1 bit, `false` otherwise |
209| `rsv2` | either `true` if the extension uses the RSV2 bit, `false` otherwise |
210| `rsv3` | either `true` if the extension uses the RSV3 bit, `false` otherwise |
211
212It must also implement the following methods:
213
214```js
215ext.createClientSession()
216```
217
218This returns a *ClientSession*, whose interface is defined below.
219
220```js
221ext.createServerSession(offers)
222```
223
224This takes an array of offer params and returns a *ServerSession*, whose
225interface is defined below. For example, if the client handshake contains the
226offer header:
227
228```
229Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
230 permessage-deflate; server_max_window_bits=15
231```
232
233then the `permessage-deflate` extension will receive the call:
234
235```js
236ext.createServerSession([
237 { server_no_context_takeover: true, server_max_window_bits: 8 },
238 { server_max_window_bits: 15 }
239]);
240```
241
242The extension must decide which set of parameters it wants to accept, if any,
243and return a *ServerSession* if it wants to accept the parameters and `null`
244otherwise.
245
246#### *ClientSession*
247
248A *ClientSession* is the type returned by `ext.createClientSession()`. It must
249implement the following methods, as well as the *Session* API listed below.
250
251```js
252clientSession.generateOffer()
253// e.g. -> [
254// { server_no_context_takeover: true, server_max_window_bits: 8 },
255// { server_max_window_bits: 15 }
256// ]
257```
258
259This must return a set of parameters to include in the client's
260`Sec-WebSocket-Extensions` offer header. If the session wants to offer multiple
261configurations, it can return an array of sets of parameters as shown above.
262
263```js
264clientSession.activate(params) // -> true
265```
266
267This must take a single set of parameters from the server's handshake response
268and use them to configure the client session. If the client accepts the given
269parameters, then this method must return `true`. If it returns any other value,
270the framework will interpret this as the client rejecting the response, and will
271`throw`.
272
273#### *ServerSession*
274
275A *ServerSession* is the type returned by `ext.createServerSession(offers)`. It
276must implement the following methods, as well as the *Session* API listed below.
277
278```js
279serverSession.generateResponse()
280// e.g. -> { server_max_window_bits: 8 }
281```
282
283This returns the set of parameters the server session wants to send in its
284`Sec-WebSocket-Extensions` response header. Only one set of parameters is
285returned to the client per extension. Server sessions that would confict on
286their use of RSV bits are not activated.
287
288#### *Session*
289
290The *Session* API must be implemented by both client and server sessions. It
291contains two methods, `processIncomingMessage(message)` and
292`processOutgoingMessage(message)`.
293
294```js
295session.processIncomingMessage(message, function(error, msg) { ... })
296```
297
298The session must implement this method to take an incoming *Message* as defined
299above, transform it in any way it needs, then return it via the callback. If
300there is an error processing the message, this method should yield an error as
301the first argument.
302
303```js
304session.processOutgoingMessage(message, function(error, msg) { ... })
305```
306
307The session must implement this method to take an outgoing *Message* as defined
308above, transform it in any way it needs, then return it via the callback. If
309there is an error processing the message, this method should yield an error as
310the first argument.
311
312Note that both `processIncomingMessage()` and `processOutgoingMessage()` can
313perform their logic asynchronously, are allowed to process multiple messages
314concurrently, and are not required to complete working on messages in the same
315order the messages arrive. `websocket-extensions` will reorder messages as your
316extension emits them and will make sure every extension is given messages in the
317order they arrive from the driver. This allows extensions to maintain state that
318depends on the messages' wire order, for example keeping a DEFLATE compression
319context between messages.
320
321```js
322session.close()
323```
324
325The framework will call this method when the WebSocket session ends, allowing
326the session to release any resources it's using.
327
328## Examples
329
330- Consumer: [websocket-driver](https://github.com/faye/websocket-driver-node)
331- Provider: [permessage-deflate](https://github.com/faye/permessage-deflate-node)
Note: See TracBrowser for help on using the repository browser.