1 # websocket-extensions [![Build status](https://secure.travis-ci.org/faye/websocket-extensions-node.svg)](http://travis-ci.org/faye/websocket-extensions-node)
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
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.
18 $ npm install websocket-extensions
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.
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.
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:
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:
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 |
57 A *Message* represents a complete application message, which can be formed from
58 text, binary and continuation frames. It has the following properties:
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 |
68 ### For driver authors
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.
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.
78 var Extensions = require('websocket-extensions'),
79 deflate = require('permessage-deflate');
81 var exts = new Extensions();
85 In the following examples, `exts` refers to this `Extensions` instance.
89 Clients will use the methods `generateOffer()` and `activate(header)`.
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:
96 request.headers['sec-websocket-extensions'] = exts.generateOffer();
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.
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:
109 exts.activate(response.headers['sec-websocket-extensions']);
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
120 Servers will use the method `generateResponse(header)`.
122 A server session needs to generate a `Sec-WebSocket-Extensions` header to send
123 in its handshake response:
126 var clientOffer = request.headers['sec-websocket-extensions'],
127 extResponse = exts.generateResponse(clientOffer);
129 response.headers['sec-websocket-extensions'] = extResponse;
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.
137 #### In both directions
139 Both clients and servers will use the methods `validFrameRsv(frame)`,
140 `processIncomingMessage(message)` and `processOutgoingMessage(message)`.
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:
147 exts.validFrameRsv(frame)
150 If this method returns `false`, the session should fail the WebSocket connection
151 with closing code `1002`.
153 To pass incoming messages through the extension stack, a session should
154 construct a *Message* object according to the above datatype definitions, and
158 exts.processIncomingMessage(message, function(error, msg) {
159 // hand the message off to the application
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.
167 To pass outgoing messages through the extension stack, a session should
168 construct a *Message* as before, and call:
171 exts.processOutgoingMessage(message, function(error, msg) {
172 // write message to the transport
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.
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:
186 exts.close(function() {})
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.
192 ### For extension authors
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.
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.
202 An `Extension` is any object that has the following properties:
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 |
212 It must also implement the following methods:
215 ext.createClientSession()
218 This returns a *ClientSession*, whose interface is defined below.
221 ext.createServerSession(offers)
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
229 Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
230 permessage-deflate; server_max_window_bits=15
233 then the `permessage-deflate` extension will receive the call:
236 ext.createServerSession([
237 {server_no_context_takeover: true, server_max_window_bits: 8},
238 {server_max_window_bits: 15}
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`
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.
252 clientSession.generateOffer()
254 // {server_no_context_takeover: true, server_max_window_bits: 8},
255 // {server_max_window_bits: 15}
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.
264 clientSession.activate(params) // -> true
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
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.
279 serverSession.generateResponse()
280 // e.g. -> {server_max_window_bits: 8}
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.
290 The *Session* API must be implemented by both client and server sessions. It
291 contains two methods, `processIncomingMessage(message)` and
292 `processOutgoingMessage(message)`.
295 session.processIncomingMessage(message, function(error, msg) { ... })
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
304 session.processOutgoingMessage(message, function(error, msg) { ... })
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
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.
325 The framework will call this method when the WebSocket session ends, allowing
326 the session to release any resources it's using.
330 * Consumer: [websocket-driver](https://github.com/faye/websocket-driver-node)
331 * Provider: [permessage-deflate](https://github.com/faye/permessage-deflate-node)
337 Copyright (c) 2014-2015 James Coglan
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:
346 The above copyright notice and this permission notice shall be included in all
347 copies or substantial portions of the Software.
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.