bminer/ws-wrapper

Lightweight WebSocket lib with socket.io-like event handling, requests, and channels

ws-wrapper

Lightweight and isomorphic Web Socket lib with socket.io-like event handling, Promise-based requests, and channels.

What?

Much like Socket.io, this library provides a protocol and API that sits on top of native WebSockets. Rather than passing raw messages through the WebSocket via WebSocket.send(), this library provides an RPC-like API that allows you to pass JSON data over WebSockets and trigger event handlers on the remote end. There is also a Promise-based request/response API, as well.

This library is isomorphic, so it can wrap WebSockets on the client (i.e. browser) or on a Node.js server using the ws library. You can get even fancier on the server side and utilize the ws-server-wrapper library (recommended).

Why?

Because lightweight is sometimes what you want. This library and its dependencies weigh under 3 KB when minified and gzipped!

This lib might be useful if you want some socket.io functionality (i.e. namespaces, event handling, etc.), but you don't want all of the engine.io transports. When using this library in conjunction with a library like ws, your real-time web application can be pretty darn lightweight without giving up some nice bare-bones functionality.

Install

npm install ws-wrapper

Usage

WebSocketWrapper is a CommonJS module, so it works in Node.js and in the browser if you use a bundler like Browserify, Webpack, Parcel.js, or module-concat.

Check out the example-app for a sample chat application (recommended).

Note: This module uses ES6 classes. If you need this to work in IE or another old, decrepit browser, try using a code transpiler like Babel.

Note: This module uses JSON.stringify to serialize data over the raw WebSocket connection. This means that serializing circular references is not supported out of the box.

Client-side

// Use a bundler to make the next line of code "work" on the browser
const WebSocketWrapper = require("ws-wrapper");
// Create a new socket
var socket = new WebSocketWrapper(new WebSocket("ws://" + location.hostname) );
// Now use the WebSocketWrapper API... `socket.emit` for example
// See examples below...

Server-side (Node.js)

Use ws-server-wrapper to wrap the WebSocketServer (recommended). See ws-server-wrapper README for more details.

If you don't want to use ws-server-wrapper, you can wrap the WebSocket once a new WebSocket connects like this:

const WebSocketServer = require("ws").Server
	, WebSocketWrapper = require("ws-wrapper");
var wss = new WebSocketServer({port: 3000});
wss.on("connection", (socket) => {
	socket = new WebSocketWrapper(socket);
	// ...
});

Other servers (i.e. Go)

No such libraries exist yet. :( Please create one, and let me know about it! I'll give you beer!

Event Handling

It's what you'd expect of an event handler API.

Call on or once to bind an event handler to the wrapper or to a channel. Call emit to send an event.

Server-side Example (without using ws-server-wrapper):

const WebSocketServer = require("ws").Server
	, WebSocketWrapper = require("ws-wrapper");
var wss = new WebSocketServer({port: 3000});
var sockets = new Set();
wss.on("connection", (socket) => {
	var socket = new WebSocketWrapper(socket);
	sockets.add(socket);
	socket.on("msg", function(from, msg) {
		// `this` refers to the WebSocketWrapper instance
		console.log(`Received message from ${from}: ${msg}`);
		// Relay message to all clients
		sockets.forEach((socket) => {
			socket.emit("msg", from, msg);
		});
	});
	socket.on("disconnect", () => {
		sockets.delete(socket);
	});
});

Client-side Example:

// Use a bundler to make the next line of code "work" on the browser
const WebSocketWrapper = require("ws-wrapper");
// Establish connection
var socket = new WebSocketWrapper(
	new WebSocket("ws://" + location.host)
);
// Add "msg" event handler
socket.on("msg", function(from, msg) {
	console.log(`Received message from ${from}: ${msg}`);
});
// Emit "msg" event
socket.emit("msg", "my_name", "This is a test message");

Channels

Just like in socket.io, you can "namespace" your events using channels. When sending messages to multiple channels, the same WebSocket connection is reused, but the events are logically separated into their appropriate channels.

By default, calling emit directly on a WebSocketWrapper instance will send the message over the "default" channel. To send a message over a channel named "foo", just call socket.of("foo").emit("eventName", "yourData").

Request / Response

Event handlers can return values or Promises to respond to requests. The response is sent back to the remote end.

The example below shows the client requesting data from the server, but ws-wrapper also allows servers to request data from the client.

Server-side Example (without using ws-server-wrapper):

const fs = require("fs")
	, WebSocketServer = require("ws").Server
	, WebSocketWrapper = require("ws-wrapper");
var wss = new WebSocketServer({port: 3000});
var sockets = new Set();
wss.on("connection", (socket) => {
	socket = new WebSocketWrapper(socket);
	sockets.add(socket);
	socket.on("userCount", () => {
		// Return value is sent back to the client
		return sockets.size;
	});
	socket.on("readFile", (path) => {
		// We can return a Promise that eventually resolves
		return new Promise((resolve, reject) => {
			// `path` should obviously be sanitized, but just go with it...
			fs.readFile(path, (err, data) => {
				// `err` or `data` are now sent back to the client
				if(err)
					reject(err);
				else
					resolve(data.toString("utf8") );
			});
		});
	});
	socket.on("disconnect", () => {
		sockets.delete(socket);
	});
});

Client-side Example:

// Assuming WebSocketWrapper is somehow available to this scope...
var socket = new WebSocketWrapper(
	new WebSocket("ws://" + location.host)
);
var p = socket.request("userCount");
// `p` is a Promise that will resolve when the server responds...
p.then((count) => {
	console.log("User count: " + count);
}).catch((err) => {
	console.error("An error occurred while getting the user count:", err);
});
socket.request("readFile", "/etc/issue").then((data) => {
	console.log("File contents:", data);
}).catch((err) => {
	console.error("Error reading file:", err);
});

API

Class: WebSocketWrapper

A WebSocketWrapper simply wraps around a WebSocket to give you well-deserved functionality. :)

socket = new WebSocketWrapper(webSocketInstance[, options]);

Constructs a new WebSocketWrapper, and binds it to the native WebSocket instance.

• webSocketInstance - the native WebSocket instance
• options
  • debug - set to true to print debugging messages to console.log
  • errorToJSON - function to serialize Errors over the WebSocket. In Node.js, the default is to send only the message property of the Error (for security reasons). Errors that occur on the browser include all properties.
  • requestTimeout - maximum delay in ms. that the WebSocketWrapper will wait until rejecting the Promise of a pending request. Defaults to null, which means that there will be no timeout. This option is recommended for servers because clients who do not fulfill pending requests can cause memory leaks.

Events

• Event: "open" / "connect"
  • event - The (worthless) event from the native WebSocket instance
• Event: "error"
  • event - The Error event from the native WebSocket instance
• Event: "message"
  • event - The Message event from the native WebSocket instance
  • data - The message data (same as event.data)
• Event: "close" / "disconnect"
  • event - The Close event from the native WebSocket instance
  • wasOpen - true if the "open" event was fired on the native WebSocket instance before the "close" event was fired.

Note: The "special" events listed above are not sent over the WebSocket.

The EventEmitter-like API looks like this:

• socket.on(eventName, listener) Adds the listener function to the end of the listeners array for the event named eventName. When an event or request matching the eventName is received by the WebSocket, the listener is called.

  Values returned by the listener callback are used to respond to requests (see socket.request). If the return value of the listener is a Promise, the response to the request will be sent once the Promise is resolved or rejected; otherwise, the return value of the listener is sent back to the remote end immediately.

  If the inbound message is a simple event (see socket.emit), the return value of the listener is ignored. It is also "safe" for the listener to return a Promise even if the inbound message is a "simple" event. If the returned Promise is rejected, an unhandled rejection will not occur; rather, the result of the Promise is just ignored.

  If the listener throws an Error, this Error will propagate up the stack as expected, and if the inbound message was a request, the Error is sent back to the remote end as a response rejection.

• socket.once(eventName, listener) Adds a one time listener function for the event named eventName.

• socket.removeListener(eventName, listener) Removes the specified listener from the listener array for the event named eventName.

• socket.removeAllListeners([eventName]) Removes all listeners, or those of the specified eventName.

• socket.eventNames() Returns an array listing the events for which the emitter has registered listeners.

• socket.listeners(eventName) Returns a copy of the array of listeners for the event named eventName.

• socket.emit(eventName[, ...args]) Sends an event down the WebSocket with the specified eventName calling all listeners for eventName on the remote end, in the order they were registered, passing the supplied arguments to each.

• socket.request(eventName[, ...args]) Sends a request down the WebSocket with the specified eventName and returns a Promise that will resolve once the remote event listener responds.

  Note: While it is common design for only one event listener to exist on the remote end, all listeners for eventName on the remote end are called, in the order they were registered, passing the supplied arguments to each. Since Promises can only be resolved or rejected once, only the data from the first event listener is used to generate the response for this request.

  Note: If a request is sent, but there is no remote event listener to respond to the request, a response rejection is immediately sent back by the remote end.

• socket.use(function fn(eventName, args, next) {...}) Adds a middleware function fn to receive all messages for the channel. The eventName indicates the name of the event or request, and the args are the arguments to be passed to the respective event handler. next([err]) should be called to continue processing to the next middleware function. Once all middleware have processed the event and called next, the event is then processed by the event handler for the eventName.

• socket.timeout(tempTimeoutInMs) Temporarily sets the requestTimeout to tempTimeoutInMs for the next request only. This returns socket to allow chaining. Typical usage:

   // The next request will be rejected if there is no response for 5 secs.
   let promise = socket.timeout(5 * 1000).request("readFile", "/etc/issue");

The above EventEmitter functions like on and once are chainable (as appropriate).

Channel API:

• socket.of(channelName) Returns the channel with the specified channelName. Every channel has the same EventEmitter-like API as described above for sending and handling channel-specific events and requests. A channel also has a read-only name property.

Other methods and properties:

By default, the WebSocketWrapper provides a queue for data to be sent. Once the WebSocket is open, this queue is flushed until the connection is lost. The following methods allow one to re-bind a new WebSocket or clear the send queue.

• socket.abort() Clears the send queue for this WebSocketWrapper and rejects all Promises for pending requests.
• socket.bind(nativeWebSocket) Binds this WebSocketWrapper to a new WebSocket. This can be useful when socket reconnection logic needs to be implemented. Instead of creating a new WebSocketWrapper each time a WebSocket is disconnected, one can simply bind a new WebSocket to the WebSocketWrapper. In this way, data queued to be sent while the connection was dead will be sent over the new WebSocket passed to the bind function.
• socket.isConnecting - checks the native WebSocket readyState and is true if and only if the state is CONNECTING.
• socket.isConnected - checks the native WebSocket readyState is true if and only if the state is CONNECTED.
• socket.send(data) If connected, calls the native WebSocket's send method; otherwise, the data is added to the WebSocketWrapper's send queue.
• socket.disconnect() Closes the native WebSocket
• socket.set(key, value) Saves user data specific to this WebSocketWrapper
• socket.get(key) Retrieves user data. See socket.set(key, value) above.

WebSocketWrapper.MAX_SEND_QUEUE_SIZE The maximum number of items allowed in the send queue. If a user tries to send more messages than this number while a WebSocket is not connected, errors will be thrown. Defaults to 10; changes affect all WebSocketWrapper instances.

Protocol

All data passed over the native WebSocket should be valid JSON, but this is not a hard requirement. ws-wrapper will try to parse a JSON string and determine the message type based on the properties in the parsed Object.

The following message types are defined by ws-wrapper:

1. Event Dispatch - Identified by an Object with a key but no i key. The channel name is optional.

   {
   	"c": "channel_name",
   	"a": ["event_name", "first_arg", "second_arg", "last_arg"]
   }

   The client or server can send events. Events are nothing more than an event name and some data, passed as arguments to the event handler.

2. Request - Identified by an Object with a and i keys where i refers to the unique request identifier. The channel name is optional.

   {
   	"i": 123,
   	"c": "channel_name",
   	"a": ["event_name", "first_arg", "second_arg", "last_arg"]
   }

   The client or server can send a Request, which is essentially an Event that needs some sort of server Response.

3. Response (Resolution) - Identified by an Object with i and d keys where i is the request identifier and d is the response data.

   {
   	"i": 123,
   	"d": {"resolved": "data", "hello": "world"}
   }

4. Response (Rejection) - Identified by an Object with i and e keys where i is the request identifier and e is the error Object to be used when rejecting the response Promise. If _ is set, the e Object is converted into an Error instance upon receipt.

   {
   	"i": 123,
   	"e": {"message": "error message"},
   	"_": 1
   }

If the message received by the WebSocket is not valid JSON or if the parsed Object does not match one of the above message types, then the message is simply ignored by ws-wrapper. Also if the JSON message contains a ws-wrapper property with the value false, the message will be ignored. This allows other libraries to use the same WebSocket and send messages that will not be processed by ws-wrapper.

Auto-Reconnect

ws-wrapper does not implement auto-reconnect functionality out of the box. For those who want it (almost everyone), I have written some sample code to show how easy it is to add.

How to implement auto-reconnect for ws-wrapper

If someone wants to make an npm package for the auto-reconnect feature, I'd be happy to list it here, but it will probably never be a core ws-wrapper feature.

ws-wrapper's Issues

Compile to ES5

React's automatic build script does not work because this project does not provide ES5 code.

See https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#npm-run-build-fails-to-minify

Also, providing ES5 support will make this work on IE 10/11.

whos better this or socket io?

Channel does not have `get()` or `set()` methods

The channel should support these methods, which will simply call get() and set() on the WebSocketWrapper.

Export ES Modules

Could we get some ES module export up in here for this and the server package?

onMessage hook?

First, very nice wrapper! :)

I'm not sure but it seems to me there isn't a hook to catch all received messages.
This would be very useful server side, as it would make rate limiting a lot easier.

Do you have a suggestion on how to best implement this, so that I don't have to check on every socket.on?

The reason I ask here and not in ws-server-wrapper, is because ws-server-wrapper extends ws-wrapper (and therefore also the onMessage event).

node app as client

hi,

great work there, and it works fine on server as "server". but my case is that my client is not a browser but another node app, so if i try this example here it works https://github.com/websockets/ws#sending-and-receiving-text-data
but as soon as i wrap that with ws-wrapper i keep getting a message trying to connect to server.

thanks in advanced.

Protocol mismatch: packets are sent as { "a": { "0": "connect" }} instead of { "a": ["connect"] }

WebSocketChannel emit and request pass the arguments keyword to _wrapper._sendEvent, but the Array-like arguments object gets JSON.stringify-d into an object instead of an array.

For example, socket.emit('event-name', 'foo', 'bar') sends:

{ "a": { "0": "event-name", "1": "foo", "2": "bar" } }

while the protocol states it should be:

{ "a": ["event-name", "foo", "bar"] }

The arguments object could be turned into an array to match the protocol, e.g. using Array.from(arguments) or [...arguments] or Array.prototype.slice.call(arguments).

I only noticed this issue because I decoded the packets in C# instead of JavaScript.

Thanks for the library, I've used it in several projects already.

Change constructor property names to avoid weird issues

To avoid strange problems like #2, freeze some properties after the channel and wrapper have been created

"a" leading sendEvent data

Hi, the wrapper is amazing but I have a question about the _sendEvent function (line 249). I'm trying to implement the same wrapper for this flutter websocket plugin and looking at the raw data sent by your wrapper I noticed the key "a" on the object that will be sent to the other end of the socket. Why is that? I tried removing it and stringify the args object directly also works. Moreover removing it will make it easier for my to parse it on flutter.

Thank you!

ws-wrapper/lib/wrapper.js

Lines 247 to 252 in 0e544c6

	_sendEvent(channel, eventName, args, isRequest) {
	// Serialize data for sending over the socket
	var data = {"a": args};
	if(channel != null) {
	data.c = channel;
	}

Type definitions

Can you make type definitions for this for Typescript?

Hooks

Hey there
Love this wrapper, been using it on a few personal projects. I've had to bend it into working with my specific requirements, and I'm about to bend it some more. I want to implement hooks like beforeReceive beforeSend etc (for things like rate limiting, middleware to check auth, etc).

Is this something you might be interested in having in this wrapper or is that out of scope in your opinion?
Feel free to close the issue if it's not for you :)

Edit: wow my mind is escaping me, looks like I asked this same question almost exactly a year ago... #10 well the question still stands i guess haha

Maybe emit "connect" event in addition to "open" event?

Server fails with error after client emitted event

I faced with strange issue using ws-wrapper. After client emits something server just fails with this error:

[1] /.../node_modules/ws-wrapper/lib/wrapper.js:247
[1]             this.send(JSON.stringify(data) );
[1]                            ^
[1]
[1] TypeError: Converting circular structure to JSON
[1]     at JSON.stringify (<anonymous>)
[1]     at WebSocketWrapper._sendEvent (/.../node_modules/ws-wrapper/lib/wrapper.js:247:18)
[1]     at WebSocketWrapper.emit (/.../node_modules/ws-wrapper/lib/channel.js:85:25)
[1]     at WebSocket.socket.onmessage (/.../node_modules/ws-wrapper/lib/wrapper.js:75:9)
[1]     at WebSocket.onMessage (/.../node_modules/ws/lib/event-target.js:120:16)
[1]     at emitOne (events.js:115:13)
[1]     at WebSocket.emit (events.js:210:7)
[1]     at Receiver.receiverOnMessage (/.../node_modules/ws/lib/websocket.js:718:20)
[1]     at emitOne (events.js:115:13)
[1]     at Receiver.emit (events.js:210:7)

Client (in browser)

  import WebSocketWrapper from 'ws-wrapper'
  const socket = new WebSocketWrapper(new WebSocket('ws://localhost:3000'))
  socket.emit('echo-me', '123')

Server

const WebSocketServer = require("ws").Server
const WebSocketWrapper = require("ws-wrapper")
const wss = new WebSocketServer({port: 3000})

wss.on("connection", (rawSocket) => {
  const socket = new WebSocketWrapper(rawSocket)

  socket.on('echo-me', (data) => {
    console.log('Echo', data)
  })
});

As you can see server just emits nothing.

I'm trying to isolate issue to give you a cleaner reproduction. For some reason I can't reproduce it with node clients.

Option to disable pendingSend globally

It would be good having an option to disable _pendingSend

I have a game that uses this library and sometimes occurs of some connections fail and throw the error "WebSocket is not connected and send queue is full" and cause restart at my server, currently for me to deal with this I have to edit the module manually on server and comment on the function "send(data, ignoreMaxQueueSize)"

Pull Request:
#14