websocket-extensions 0.1.4

WebSocket-Extensions is a minimal JavaScript framework that facilitates the implementation of WebSocket extensions. It does so in a manner that is completely independent from the main protocol, essentially making it library-agnostic. The core goal is to allow a WebSocket extension to be written and used with any protocol library. It primarily offers a container in which extension plugins can be registered, and provides the necessary functionalities needed to negotiate the usage of these during a session through the Sec-WebSocket-Extensions header. By implementing protocols defined within this framework, a developer can thus use any WebSocket library that is based on this framework.

To use the WebSocket-Extensions package, you need to first install it via npm using the command npm install websocket-extensions. Following installation, you can use it within your code by requiring the package.

Here's an example usage where we create a new extension container:

var Extensions = require('websocket-extensions');
var exts = new Extensions();

If you're authoring a WebSocket protocol, you would create an extension container at the start of a WebSocket session. From there, add all the desired extensions that you want to use.

var Extensions = require('websocket-extensions'),
    deflate    = require('permessage-deflate');

var exts = new Extensions();
exts.add(deflate);

If you're processing a WebSocket session on a client, you'd generate a Sec-WebSocket-Extensions header during the handshake phase.

request.headers['sec-websocket-extensions'] = exts.generateOffer();

Then, once a server response is received, the client activates the extensions the server has accepted:

exts.activate(response.headers['sec-websocket-extensions']);

For the server side, a Sec-WebSocket-Extensions header must be generated to include in the handshake response:

var clientOffer = request.headers['sec-websocket-extensions'],
    extResponse = exts.generateResponse(clientOffer);

response.headers['sec-websocket-extensions'] = extResponse;

Once extensions have been activated for both clients and servers, sessions should process both incoming and outgoing messages through the extension stack. After the WebSocket session ends, the exts.close() function should be called to safely close the socket.

The documentation for WebSocket-Extensions can be found within the package Readme which is available in the GitHub repository. The Readme provides comprehensive information on how to install the package, implement WebSocket protocols, add extensions, process frames, client and server sessions, message structure, extension registration and the APIs provided by the framework along with numerous usage examples.