npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

watershed

v0.4.1

Published

simple websockets (RFC6455) client and server

Downloads

8,215

Readme

node-watershed

A simple implementation of WebSockets for use with node.js 'http'-style web server or client. Deals only with RFC6455, ignoring any Browser-specific peculiarities, curiosities, and fallback mechanisms.

API

Watershed

The core of this library is a Factory-style class Watershed. It has several static methods:

Watershed.accept(http.ServerRequest, net.Socket, Buffer[, Boolean[, String[] ]])

Responds to a client's request to Upgrade an HTTP connection to a WebSocket and returns a WatershedConnection, which is also an EventEmitter.

The arguments to this method should ideally come from the 'upgrade' event on a node.js http.Server. For example:

var shed = new Watershed();
var srv = http.createServer();
srv.listen(8080);
srv.on('upgrade', function(req, socket, head) {
        var wsc;
        try {
                wsc = shed.accept(req, socket, head);
        } catch (ex) {
                console.error('error: ' + ex.message);
                return socket.end();
        }
        wsc.on('text', function(text) {
                console.log('received text: ' + text);
        });
        wsc.on('end', function() {
                console.log('end!');
        });
        /* ... etc ... */
});

The additional penultimate boolean argument may be used when implementing a websocket-to-websocket proxy. If set to true, then accept() returns the raw underlying Socket of the connection and does not construct a WatershedConnection instance. No event handlers will be placed on the socket, meaning you are free to continue using it directly (e.g. calling pipe() on it to join it to a backend socket).

The final list-of-strings argument can be optionally provided to allow for the use of WebSocket subprotocol negotiation. It is a list of case-sensitive string names of supported subprotocols. If given, and protocol negotiation takes place, the chosen subprotocol can be found with the getProtocol() method.

Watershed.generateKey()

Returns a random, Base64-encoded 16-byte value suitable for use as the Sec-WebSocket-Key header on an Upgrade request. See Example usage in connect().

Watershed.connect(http.ClientResponse, net.Socket, Buffer, String)

Attaches a new client-side WatershedConnection to this presently Upgraded socket.

The arguments to this method should ideally come from the 'upgrade' event on a node.js http.Client. For example:

var shed = new Watershed();
var wskey = shed.generateKey();
var options = {
    port: 8082,
    hostname: '127.0.0.1',
    headers: {
        'connection': 'upgrade',
        'upgrade': 'websocket',
        'Sec-WebSocket-Key': wskey,
        'Sec-WebSocket-Version': '13'
    }
};
var req = http.request(options);
req.end();
req.on('upgrade', function(res, socket, head) {
        var wsc = shed.connect(res, socket, head, wskey);
        wsc.send('Hi there!');
        wsc.on('end', function() {
                console.log('end!');
        });
        /* ... etc ... */
});

WatershedConnection

Event: 'error'

Emitted once when an error occurs during processing. The socket will be closed and an 'end' event will follow. The only argument will be an instance of Error.

Event: 'connectionReset'

Emitted when the remote peer closes the connection without sending us a CLOSE frame. An 'end' event will follow.

Event: 'end' (code, reason)

Emitted once when the socket is closing. If we received a graceful CLOSE frame from the remote server, we will attempt to process it and pass code and reason -- both of type String.

Event: 'text'

Emitted for each inbound TEXT frame. The only argument will be a String containing the UTF-8 string payload.

Event: 'binary'

Emitted for each inbound BINARY frame. The only argument will be a Buffer containing the binary payload.

Event: 'ping'

Emitted for each inbound PING frame. The only argument will be a Buffer containing the nonce in the ping request. Note that the library presently responds with a PONG frame for each inbound PING frame.

Event: 'pong'

Emitted for each inbound PONG frame. The only argument will be a Buffer containing the nonce in the pong response.

WatershedConnection.getProtocol()

Returns the negotiated subprotocol, if any, for this connection, as a String. If no subprotocol negotiation took place, this method returns null.

WatershedConnection.send(data)

Sends a frame through the socket. The single argument data may be a Buffer, in which case a BINARY frame is sent; or a String, in which case a TEXT frame is sent.

WatershedConnection.end(reason)

Closes the connection. The RFC allows a reason for closing the connection to be send in the CLOSE frame, though this is optional. If passed, reason should be a String.

WatershedConnection.destroy()

Immediately destroy the underlying socket, without sending a CLOSE frame. You generally want end(), rather than this, in order to perform RFC-compliant connection shutdowns.

License

MIT.