websocket-extensions
Advanced tools
The websocket-extensions npm package is a framework for managing extensions to the WebSocket protocol. It allows for the negotiation and processing of protocol extensions between a client and server. This package is typically used in conjunction with WebSocket servers and clients to enhance the capabilities of the WebSocket connection with additional features such as compression.
Extension negotiation
This feature allows the server to negotiate which extensions will be used in the WebSocket connection. The 'generateOffer' method is used to create an offer that can be sent in the 'Sec-WebSocket-Extensions' header.
const Extensions = require('websocket-extensions'),
exts = new Extensions();
exts.add('permessage-deflate');
let offer = exts.generateOffer();
console.log(offer); // logs string to send in the 'Sec-WebSocket-Extensions' headerExtension parsing
This feature parses the 'Sec-WebSocket-Extensions' header from the client or server to determine which extensions have been agreed upon. The 'parseHeader' method processes the header string.
const Extensions = require('websocket-extensions'),
exts = new Extensions();
exts.add('permessage-deflate');
let response = 'permessage-deflate; server_max_window_bits=10';
exts.parseHeader(response);Extension processing
This feature processes incoming and outgoing messages using the agreed-upon extensions. The 'incoming' and 'outgoing' methods are used to define how messages should be transformed.
const Extensions = require('websocket-extensions'),
exts = new Extensions();
exts.add('permessage-deflate', {
incoming: function(message, callback) {
// Decompress message.data if needed
callback(null, message);
},
outgoing: function(message, callback) {
// Compress message.data if needed
callback(null, message);
}
});The 'ws' package is a popular WebSocket library for Node.js. It provides the basic framework for working with WebSockets, including handling the WebSocket protocol, sending and receiving messages, and managing connections. It does not focus specifically on extensions but supports them.
Socket.IO is a library that enables real-time, bidirectional and event-based communication between web clients and servers. It uses WebSocket as a transport mechanism when possible but provides fallbacks to other methods. It offers a higher-level API than websocket-extensions and includes features like broadcasting and rooms.
Faye-websocket is a WebSocket client and server implementation that also provides an event-driven API for managing WebSocket connections. It is similar to websocket-extensions in that it supports extensions, but it is a more comprehensive solution that includes the WebSocket protocol implementation.
Engine.IO is the lower-level component of Socket.IO that provides the real-time engine on top of which Socket.IO is built. It offers a similar WebSocket-like API and supports multiple transports for compatibility with different browsers and network conditions, not focusing solely on WebSocket extensions.
A minimal framework that supports the implementation of WebSocket extensions in a way that's decoupled from the main protocol. This library aims to allow a WebSocket extension to be written and used with any protocol library, by defining abstract representations of frames and messages that allow modules to co-operate.
websocket-extensions provides a container for registering extension plugins,
and provides all the functions required to negotiate which extensions to use
during a session via the Sec-WebSocket-Extensions header. By implementing the
APIs defined in this document, an extension may be used by any WebSocket library
based on this framework.
$ npm install websocket-extensions
There are two main audiences for this library: authors implementing the
WebSocket protocol, and authors implementing extensions. End users of a
WebSocket library or an extension should be able to use any extension by passing
it as an argument to their chosen protocol library, without needing to know how
either of them work, or how the websocket-extensions framework operates.
The library is designed with the aim that any protocol implementation and any extension can be used together, so long as they support the same abstract representation of frames and messages.
The APIs provided by the framework rely on two data types; extensions will expect to be given data and to be able to return data in these formats:
Frame is a structure representing a single WebSocket frame of any type. Frames are simple objects that must have at least the following properties, which represent the data encoded in the frame:
| property | description |
|---|---|
final | true if the FIN bit is set, false otherwise |
rsv1 | true if the RSV1 bit is set, false otherwise |
rsv2 | true if the RSV2 bit is set, false otherwise |
rsv3 | true if the RSV3 bit is set, false otherwise |
opcode | the numeric opcode (0, 1, 2, 8, 9, or 10) of the frame |
masked | true if the MASK bit is set, false otherwise |
maskingKey | a 4-byte Buffer if masked is true, otherwise null |
payload | a Buffer containing the (unmasked) application data |
A Message represents a complete application message, which can be formed from text, binary and continuation frames. It has the following properties:
| property | description |
|---|---|
rsv1 | true if the first frame of the message has the RSV1 bit set |
rsv2 | true if the first frame of the message has the RSV2 bit set |
rsv3 | true if the first frame of the message has the RSV3 bit set |
opcode | the numeric opcode (1 or 2) of the first frame of the message |
data | the concatenation of all the frame payloads in the message |
A driver author is someone implementing the WebSocket protocol proper, and who wishes end users to be able to use WebSocket extensions with their library.
At the start of a WebSocket session, on both the client and the server side, they should begin by creating an extension container and adding whichever extensions they want to use.
var Extensions = require('websocket-extensions'),
deflate = require('permessage-deflate');
var exts = new Extensions();
exts.add(deflate);
In the following examples, exts refers to this Extensions instance.
Clients will use the methods generateOffer() and activate(header).
As part of the handshake process, the client must send a
Sec-WebSocket-Extensions header to advertise that it supports the registered
extensions. This header should be generated using:
request.headers['sec-websocket-extensions'] = exts.generateOffer();
This returns a string, for example "permessage-deflate; client_max_window_bits", that represents all the extensions the client is
offering to use, and their parameters. This string may contain multiple offers
for the same extension.
When the client receives the handshake response from the server, it should pass
the incoming Sec-WebSocket-Extensions header in to exts to activate the
extensions the server has accepted:
exts.activate(response.headers['sec-websocket-extensions']);
If the server has sent any extension responses that the client does not
recognize, or are in conflict with one another for use of RSV bits, or that use
invalid parameters for the named extensions, then exts.activate() will
throw. In this event, the client driver should fail the connection with
closing code 1010.
Servers will use the method generateResponse(header).
A server session needs to generate a Sec-WebSocket-Extensions header to send
in its handshake response:
var clientOffer = request.headers['sec-websocket-extensions'],
extResponse = exts.generateResponse(clientOffer);
response.headers['sec-websocket-extensions'] = extResponse;
Calling exts.generateResponse(header) activates those extensions the client
has asked to use, if they are registered, asks each extension for a set of
response parameters, and returns a string containing the response parameters for
all accepted extensions.
Both clients and servers will use the methods validFrameRsv(frame),
processIncomingMessage(message) and processOutgoingMessage(message).
The WebSocket protocol requires that frames do not have any of the RSV bits
set unless there is an extension in use that allows otherwise. When processing
an incoming frame, sessions should pass a Frame object to:
exts.validFrameRsv(frame)
If this method returns false, the session should fail the WebSocket connection
with closing code 1002.
To pass incoming messages through the extension stack, a session should construct a Message object according to the above datatype definitions, and call:
exts.processIncomingMessage(message, function(error, msg) {
// hand the message off to the application
});
If any extensions fail to process the message, then the callback will yield an
error and the session should fail the WebSocket connection with closing code
1010. If error is null, then msg should be passed on to the application.
To pass outgoing messages through the extension stack, a session should construct a Message as before, and call:
exts.processOutgoingMessage(message, function(error, msg) {
// write message to the transport
});
If any extensions fail to process the message, then the callback will yield an
error and the session should fail the WebSocket connection with closing code
1010. If error is null, then message should be converted into frames
(with the message's rsv1, rsv2, rsv3 and opcode set on the first frame)
and written to the transport.
At the end of the WebSocket session (either when the protocol is explicitly ended or the transport connection disconnects), the driver should call:
exts.close(function() {})
The callback is invoked when all extensions have finished processing any messages in the pipeline and it's safe to close the socket.
An extension author is someone implementing an extension that transforms WebSocket messages passing between the client and server. They would like to implement their extension once and have it work with any protocol library.
Extension authors will not install websocket-extensions or call it directly.
Instead, they should implement the following API to allow their extension to
plug into the websocket-extensions framework.
An Extension is any object that has the following properties:
| property | description |
|---|---|
name | a string containing the name of the extension as used in negotiation headers |
type | a string, must be "permessage" |
rsv1 | either true if the extension uses the RSV1 bit, false otherwise |
rsv2 | either true if the extension uses the RSV2 bit, false otherwise |
rsv3 | either true if the extension uses the RSV3 bit, false otherwise |
It must also implement the following methods:
ext.createClientSession()
This returns a ClientSession, whose interface is defined below.
ext.createServerSession(offers)
This takes an array of offer params and returns a ServerSession, whose interface is defined below. For example, if the client handshake contains the offer header:
Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
permessage-deflate; server_max_window_bits=15
then the permessage-deflate extension will receive the call:
ext.createServerSession([
{server_no_context_takeover: true, server_max_window_bits: 8},
{server_max_window_bits: 15}
]);
The extension must decide which set of parameters it wants to accept, if any,
and return a ServerSession if it wants to accept the parameters and null
otherwise.
A ClientSession is the type returned by ext.createClientSession(). It must
implement the following methods, as well as the Session API listed below.
clientSession.generateOffer()
// e.g. -> [
// {server_no_context_takeover: true, server_max_window_bits: 8},
// {server_max_window_bits: 15}
// ]
This must return a set of parameters to include in the client's
Sec-WebSocket-Extensions offer header. If the session wants to offer multiple
configurations, it can return an array of sets of parameters as shown above.
clientSession.activate(params) // -> true
This must take a single set of parameters from the server's handshake response
and use them to configure the client session. If the client accepts the given
parameters, then this method must return true. If it returns any other value,
the framework will interpret this as the client rejecting the response, and will
throw.
A ServerSession is the type returned by ext.createServerSession(offers). It
must implement the following methods, as well as the Session API listed below.
serverSession.generateResponse()
// e.g. -> {server_max_window_bits: 8}
This returns the set of parameters the server session wants to send in its
Sec-WebSocket-Extensions response header. Only one set of parameters is
returned to the client per extension. Server sessions that would confict on
their use of RSV bits are not activated.
The Session API must be implemented by both client and server sessions. It
contains two methods, processIncomingMessage(message) and
processOutgoingMessage(message).
session.processIncomingMessage(message, function(error, msg) { ... })
The session must implement this method to take an incoming Message as defined above, transform it in any way it needs, then return it via the callback. If there is an error processing the message, this method should yield an error as the first argument.
session.processOutgoingMessage(message, function(error, msg) { ... })
The session must implement this method to take an outgoing Message as defined above, transform it in any way it needs, then return it via the callback. If there is an error processing the message, this method should yield an error as the first argument.
Note that both processIncomingMessage() and processOutgoingMessage() can
perform their logic asynchronously, are allowed to process multiple messages
concurrently, and are not required to complete working on messages in the same
order the messages arrive. websocket-extensions will reorder messages as your
extension emits them and will make sure every extension is given messages in the
order they arrive from the driver. This allows extensions to maintain state that
depends on the messages' wire order, for example keeping a DEFLATE compression
context between messages.
session.close()
The framework will call this method when the WebSocket session ends, allowing the session to release any resources it's using.
0.1.2 / 2017-09-10
close() to return if a message that's queued after one that
produces an error never finishes being processedFAQs
Generic extension manager for WebSocket connections
The npm package websocket-extensions receives a total of 6,395,339 weekly downloads. As such, websocket-extensions popularity was classified as popular.
We found that websocket-extensions demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.