ws-messaging

ws-messaging

Just a really thin abstraction layer on top of WebSocket for Node.js and Web Browsers with Promise and EventEmitter based APIs.

Features

• Send and receive notifications (events) via an EventEmitter API.

• Request-reply API using promises (works in both directions, without any connection blocking during processing).

• Built-in auth via WebSocket messages exchange (no more query strings).

• Auto reconnection is provided.

• Binary messages support via custom encoders/decoders.

• Reasonable client size (also includes a Promise polyfill): around 16KB minified, 5KB gziped.

Table of Contents

• Background
• Installation
• Usage
• API
• Network format description
• Data validation
• Contribute
• License

Background

Read this article for more background information.

Installation

npm i ws-messaging

Usage

On a server:

const Server = require('ws-messaging')

const port = 8000

function connectionHook (client, authData) {
  // check an authData
  // then assign client events handlers
  // return a promise
}

let server = new Server({port}, {connectionHook})

On a client:

const Client = require('ws-messaging/client')

const url = `ws://${HOST}:${PORT}`
const auth = { /* will be authData in connectionHook */ }

let client = new Client(url, auth)

client.on('someEvent', (...data) => { /* do smth */ })

client.register('someMethod', (...args) => { /* do smth, return a promise */ })

client.on('connect', () => {
  /* now this client can send messages */
  client.send('myEvent', ...someData)
  /* or use request-reply (RPC) API */
  client.invoke('myMethod', ...someArgs)
    .then(result => { /* do smth */ })
    .catch(error => { /* do smth */ })
})

Essentially there are two usage patterns that are working in both directions. Fire and forget via send/on, and RPC-style via invoke/register. Unlike on, only a single handler function can be registered per a method name.

API

Server API and Client API documentation is available online.

Network format description

This section describes what data is actually passed to an encoder.

There are only two types of messages. The first one is for normal messages:

{
  name: string,
  args: Array,
  id?: number
}

An id field is present for invoke calls. The second one is for ack (replies for invoke calls) messages:

{
  id: number
  result?: Object
  error?: Object
}

Either a result or an error field is included. Note that an error is the value returned by an errorFormatter, by default String is used as an errorFormatter.

Data validation

All incoming data must be validated on a server side, including errors that are passed to a catch callback. By default only the network format itself is validated. Validation can be made by a custom decoder (useful when a decoder is already using some scheme) or via a receiveHook, or inside a handler itself (useful for registered procedures). When validation is done inside decoder/receiveHook, just throw an error or reject a promise to fail a validation and prevent handlers execution. Also note that a promise returned by invoke can be rejected locally either with Client.ConnectionError or with Client.TimeoutError.

Contribute

If you encounter a bug in this package, please submit a bug report to github repo issues.

PRs are also accepted.

License

MIT

Changelog

0.5.2 (2016-10-27)

Features

• add client socket constructor customisation (b9b76e0)

<a name="0.5.1"></a>