www.aleph1.co.uk Git - yaffs-website/blob - node_modules/websocket-extensions/README.md

   1 # websocket-extensions [![Build status](https://secure.travis-ci.org/faye/websocket-extensions-node.svg)](http://travis-ci.org/faye/websocket-extensions-node)
   2
   3 A minimal framework that supports the implementation of WebSocket extensions in
   4 a way that's decoupled from the main protocol. This library aims to allow a
   5 WebSocket extension to be written and used with any protocol library, by
   6 defining abstract representations of frames and messages that allow modules to
   7 co-operate.
   8
   9 `websocket-extensions` provides a container for registering extension plugins,
  10 and provides all the functions required to negotiate which extensions to use
  11 during a session via the `Sec-WebSocket-Extensions` header. By implementing the
  12 APIs defined in this document, an extension may be used by any WebSocket library
  13 based on this framework.
  14
  15 ## Installation
  16
  17 ```
  18 $ npm install websocket-extensions
  19 ```
  20
  21 ## Usage
  22
  23 There are two main audiences for this library: authors implementing the
  24 WebSocket protocol, and authors implementing extensions. End users of a
  25 WebSocket library or an extension should be able to use any extension by passing
  26 it as an argument to their chosen protocol library, without needing to know how
  27 either of them work, or how the `websocket-extensions` framework operates.
  28
  29 The library is designed with the aim that any protocol implementation and any
  30 extension can be used together, so long as they support the same abstract
  31 representation of frames and messages.
  32
  33 ### Data types
  34
  35 The APIs provided by the framework rely on two data types; extensions will
  36 expect 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
  41 are simple objects that must have at least the following properties, which
  42 represent 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
  57 A *Message* represents a complete application message, which can be formed from
  58 text, 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
  70 A driver author is someone implementing the WebSocket protocol proper, and who
  71 wishes end users to be able to use WebSocket extensions with their library.
  72
  73 At the start of a WebSocket session, on both the client and the server side,
  74 they should begin by creating an extension container and adding whichever
  75 extensions they want to use.
  76
  77 ```js
  78 var Extensions = require('websocket-extensions'),
  79     deflate    = require('permessage-deflate');
  80
  81 var exts = new Extensions();
  82 exts.add(deflate);
  83 ```
  84
  85 In the following examples, `exts` refers to this `Extensions` instance.
  86
  87 #### Client sessions
  88
  89 Clients will use the methods `generateOffer()` and `activate(header)`.
  90
  91 As part of the handshake process, the client must send a
  92 `Sec-WebSocket-Extensions` header to advertise that it supports the registered
  93 extensions. This header should be generated using:
  94
  95 ```js
  96 request.headers['sec-websocket-extensions'] = exts.generateOffer();
  97 ```
  98
  99 This returns a string, for example `"permessage-deflate;
 100 client_max_window_bits"`, that represents all the extensions the client is
 101 offering to use, and their parameters. This string may contain multiple offers
 102 for the same extension.
 103
 104 When the client receives the handshake response from the server, it should pass
 105 the incoming `Sec-WebSocket-Extensions` header in to `exts` to activate the
 106 extensions the server has accepted:
 107
 108 ```js
 109 exts.activate(response.headers['sec-websocket-extensions']);
 110 ```
 111
 112 If the server has sent any extension responses that the client does not
 113 recognize, or are in conflict with one another for use of RSV bits, or that use
 114 invalid parameters for the named extensions, then `exts.activate()` will
 115 `throw`. In this event, the client driver should fail the connection with
 116 closing code `1010`.
 117
 118 #### Server sessions
 119
 120 Servers will use the method `generateResponse(header)`.
 121
 122 A server session needs to generate a `Sec-WebSocket-Extensions` header to send
 123 in its handshake response:
 124
 125 ```js
 126 var clientOffer = request.headers['sec-websocket-extensions'],
 127     extResponse = exts.generateResponse(clientOffer);
 128
 129 response.headers['sec-websocket-extensions'] = extResponse;
 130 ```
 131
 132 Calling `exts.generateResponse(header)` activates those extensions the client
 133 has asked to use, if they are registered, asks each extension for a set of
 134 response parameters, and returns a string containing the response parameters for
 135 all accepted extensions.
 136
 137 #### In both directions
 138
 139 Both clients and servers will use the methods `validFrameRsv(frame)`,
 140 `processIncomingMessage(message)` and `processOutgoingMessage(message)`.
 141
 142 The WebSocket protocol requires that frames do not have any of the `RSV` bits
 143 set unless there is an extension in use that allows otherwise. When processing
 144 an incoming frame, sessions should pass a *Frame* object to:
 145
 146 ```js
 147 exts.validFrameRsv(frame)
 148 ```
 149
 150 If this method returns `false`, the session should fail the WebSocket connection
 151 with closing code `1002`.
 152
 153 To pass incoming messages through the extension stack, a session should
 154 construct a *Message* object according to the above datatype definitions, and
 155 call:
 156
 157 ```js
 158 exts.processIncomingMessage(message, function(error, msg) {
 159   // hand the message off to the application
 160 });
 161 ```
 162
 163 If any extensions fail to process the message, then the callback will yield an
 164 error 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
 167 To pass outgoing messages through the extension stack, a session should
 168 construct a *Message* as before, and call:
 169
 170 ```js
 171 exts.processOutgoingMessage(message, function(error, msg) {
 172   // write message to the transport
 173 });
 174 ```
 175
 176 If any extensions fail to process the message, then the callback will yield an
 177 error 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)
 180 and written to the transport.
 181
 182 At the end of the WebSocket session (either when the protocol is explicitly
 183 ended or the transport connection disconnects), the driver should call:
 184
 185 ```js
 186 exts.close(function() {})
 187 ```
 188
 189 The callback is invoked when all extensions have finished processing any
 190 messages in the pipeline and it's safe to close the socket.
 191
 192 ### For extension authors
 193
 194 An extension author is someone implementing an extension that transforms
 195 WebSocket messages passing between the client and server. They would like to
 196 implement their extension once and have it work with any protocol library.
 197
 198 Extension authors will not install `websocket-extensions` or call it directly.
 199 Instead, they should implement the following API to allow their extension to
 200 plug into the `websocket-extensions` framework.
 201
 202 An `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
 212 It must also implement the following methods:
 213
 214 ```js
 215 ext.createClientSession()
 216 ```
 217
 218 This returns a *ClientSession*, whose interface is defined below.
 219
 220 ```js
 221 ext.createServerSession(offers)
 222 ```
 223
 224 This takes an array of offer params and returns a *ServerSession*, whose
 225 interface is defined below. For example, if the client handshake contains the
 226 offer header:
 227
 228 ```
 229 Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
 230                           permessage-deflate; server_max_window_bits=15
 231 ```
 232
 233 then the `permessage-deflate` extension will receive the call:
 234
 235 ```js
 236 ext.createServerSession([
 237   {server_no_context_takeover: true, server_max_window_bits: 8},
 238   {server_max_window_bits: 15}
 239 ]);
 240 ```
 241
 242 The extension must decide which set of parameters it wants to accept, if any,
 243 and return a *ServerSession* if it wants to accept the parameters and `null`
 244 otherwise.
 245
 246 #### *ClientSession*
 247
 248 A *ClientSession* is the type returned by `ext.createClientSession()`. It must
 249 implement the following methods, as well as the *Session* API listed below.
 250
 251 ```js
 252 clientSession.generateOffer()
 253 // e.g.  -> [
 254 //            {server_no_context_takeover: true, server_max_window_bits: 8},
 255 //            {server_max_window_bits: 15}
 256 //          ]
 257 ```
 258
 259 This 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
 261 configurations, it can return an array of sets of parameters as shown above.
 262
 263 ```js
 264 clientSession.activate(params) // -> true
 265 ```
 266
 267 This must take a single set of parameters from the server's handshake response
 268 and use them to configure the client session. If the client accepts the given
 269 parameters, then this method must return `true`. If it returns any other value,
 270 the framework will interpret this as the client rejecting the response, and will
 271 `throw`.
 272
 273 #### *ServerSession*
 274
 275 A *ServerSession* is the type returned by `ext.createServerSession(offers)`. It
 276 must implement the following methods, as well as the *Session* API listed below.
 277
 278 ```js
 279 serverSession.generateResponse()
 280 // e.g.  -> {server_max_window_bits: 8}
 281 ```
 282
 283 This 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
 285 returned to the client per extension. Server sessions that would confict on
 286 their use of RSV bits are not activated.
 287
 288 #### *Session*
 289
 290 The *Session* API must be implemented by both client and server sessions. It
 291 contains two methods, `processIncomingMessage(message)` and
 292 `processOutgoingMessage(message)`.
 293
 294 ```js
 295 session.processIncomingMessage(message, function(error, msg) { ... })
 296 ```
 297
 298 The session must implement this method to take an incoming *Message* as defined
 299 above, transform it in any way it needs, then return it via the callback. If
 300 there is an error processing the message, this method should yield an error as
 301 the first argument.
 302
 303 ```js
 304 session.processOutgoingMessage(message, function(error, msg) { ... })
 305 ```
 306
 307 The session must implement this method to take an outgoing *Message* as defined
 308 above, transform it in any way it needs, then return it via the callback. If
 309 there is an error processing the message, this method should yield an error as
 310 the first argument.
 311
 312 Note that both `processIncomingMessage()` and `processOutgoingMessage()` can
 313 perform their logic asynchronously, are allowed to process multiple messages
 314 concurrently, and are not required to complete working on messages in the same
 315 order the messages arrive. `websocket-extensions` will reorder messages as your
 316 extension emits them and will make sure every extension is given messages in the
 317 order they arrive from the driver. This allows extensions to maintain state that
 318 depends on the messages' wire order, for example keeping a DEFLATE compression
 319 context between messages.
 320
 321 ```js
 322 session.close()
 323 ```
 324
 325 The framework will call this method when the WebSocket session ends, allowing
 326 the 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)
 332
 333 ## License
 334
 335 (The MIT License)
 336
 337 Copyright (c) 2014-2015 James Coglan
 338
 339 Permission is hereby granted, free of charge, to any person obtaining a copy of
 340 this software and associated documentation files (the 'Software'), to deal in
 341 the Software without restriction, including without limitation the rights to
 342 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 343 the Software, and to permit persons to whom the Software is furnished to do so,
 344 subject to the following conditions:
 345
 346 The above copyright notice and this permission notice shall be included in all
 347 copies or substantial portions of the Software.
 348
 349 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 350 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 351 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 352 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 353 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 354 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.