rpc-websockets

What is rpc-websockets?

The rpc-websockets package provides a simple way to implement JSON-RPC 2.0 over WebSockets. It allows for both client and server implementations, enabling remote procedure calls (RPC) and event-based communication between clients and servers.

What are rpc-websockets's main functionalities?

Creating a WebSocket Server

This code demonstrates how to create a WebSocket server using rpc-websockets. The server listens on port 8080 and registers a 'sum' method that takes an array of parameters and returns their sum.

const WebSocketServer = require('rpc-websockets').Server;
const server = new WebSocketServer({ port: 8080 });

server.register('sum', (params) => {
  return params[0] + params[1];
});

console.log('WebSocket server is running on ws://localhost:8080');

Creating a WebSocket Client

This code demonstrates how to create a WebSocket client using rpc-websockets. The client connects to the server at ws://localhost:8080 and calls the 'sum' method with parameters 5 and 3, then logs the result.

const WebSocketClient = require('rpc-websockets').Client;
const client = new WebSocketClient('ws://localhost:8080');

client.on('open', () => {
  client.call('sum', [5, 3]).then((result) => {
    console.log('Sum:', result);
  }).catch((error) => {
    console.error('Error:', error);
  });
});

Subscribing to Events

This code demonstrates how to create a WebSocket server that emits events. The server defines an 'update' event and emits it every second with the current timestamp.

const WebSocketServer = require('rpc-websockets').Server;
const server = new WebSocketServer({ port: 8080 });

server.event('update');

setInterval(() => {
  server.emit('update', { timestamp: new Date() });
}, 1000);

console.log('WebSocket server is running on ws://localhost:8080');

Listening to Events on Client

This code demonstrates how to create a WebSocket client that listens to events. The client connects to the server at ws://localhost:8080, subscribes to the 'update' event, and logs any received updates.

const WebSocketClient = require('rpc-websockets').Client;
const client = new WebSocketClient('ws://localhost:8080');

client.on('open', () => {
  client.subscribe('update');
  client.on('update', (data) => {
    console.log('Update received:', data);
  });
});

Other packages similar to rpc-websockets

ws

The ws package is a simple to use, blazing fast, and thoroughly tested WebSocket client and server for Node.js. Unlike rpc-websockets, ws does not provide built-in support for JSON-RPC, but it offers a more flexible and lower-level API for WebSocket communication.

socket.io

Socket.IO is a library that enables real-time, bidirectional, and event-based communication between web clients and servers. It provides higher-level abstractions compared to rpc-websockets, including automatic reconnection, multiplexing, and broadcasting, but does not natively support JSON-RPC.

README

WebSockets for node with JSON RPC 2.0 support on top.

Installation

npm install rpc-websockets

Examples

var WebSocket = require('rpc-websockets').Client
var WebSocketServer = require('rpc-websockets').Server

// instantiate Server and start listening for requests
var server = new WebSocketServer({
  port: 8080,
  host: 'localhost'
})

// register an RPC method
server.register('sum', function(params) {
  return params[0] + params[1]
})

// create an event
server.event('feedUpdated')

// get events (getter method)
console.log(server.eventList)

// emit an event to subscribers
server.emit('feedUpdated')

// close the server
server.close()

// instantiate Client and connect to an RPC server
var ws = new WebSocket('ws://localhost:8080')

ws.on('open', function() {
  // call an RPC method with parameters
  ws.call('sum', [5, 3]).then(function(result) {
    require('assert').equal(result, 8)
  })

  // send a notification to an RPC server
  ws.notify('openedNewsModule')

  // subscribe to receive an event
  ws.subscribe('feedUpdated')

  ws.on('feedUpdated', function() {
    updateLogic()
  })

  // unsubscribe from an event
  ws.unsubscribe('feedUpdated')

  // close a websocket connection
  ws.close()
})

Migrating to 3.x

Departing from version 2.x, there's been some minor API changes. A breaking change is a server.eventList method, which is not a getter method anymore, because of the inclusion of a namespaces system throughout the library. Other methods will work seamlessly.

Starting from version 3.1.0, we have also switched from ws to uWebSockets, because of a huge performance boost.

Client

var WebSocket = require('rpc-websockets').Client
var ws = new WebSocket('ws://localhost:8080')

new WebSocket(address[, options]) -> Client

Instantiate a WebSocket client.

Parameters:

• address {String}: The URL of the WebSocket server. Defaults to 'ws://localhost:8080'.
• options {Object}: Client options that are also forwarded to μws.
  • autoconnect {Boolean}: Client autoconnect upon Client class instantiation. Defaults to true.
  • reconnect {Boolean}: Whether client should reconnect automatically once the connection is down. Defaults to true.
  • reconnect_interval {Number}: Time between adjacent reconnects. Defaults to 1000.
  • max_reconnects {Number}: Maximum number of times the client should try to reconnect. Defaults to 5.

ws.call(method[, params[, timeout[, μws_options]]]) -> Promise

Calls a registered RPC method on server. Resolves once the response is ready. Throws if an RPC error was received.

Parameters:

• method {String}: An RPC method name to run on server-side.
• params {Object|Array}: Optional parameter(s) to be sent along the request.
• timeout {Number}: Optional RPC reply timeout in milliseconds.
• μws_options {Object}: Optional parameters passed to μws.
  • compress {Boolean}: Specifies whether data should be compressed or not. Defaults to true when permessage-deflate is enabled.
  • binary {Boolean}: Specifies whether data should be sent as a binary or not. Default is autodetected.
  • mask {Boolean} Specifies whether data should be masked or not. Defaults to true when websocket is not a server client.
  • fin {Boolean} Specifies whether data is the last fragment of a message or not. Defaults to true.

ws.notify(method[, params])

Sends a JSON-RPC 2.0 notification to server.

Parameters:

• method {String}: An RPC method name to run on server-side.
• params {Object|Array}: Optional parameter(s) to be sent along the request.

ws.subscribe(event) -> Promise

Subscribes for a defined event.

Parameters:

• event {String}: Event name.

ws.unsubscribe(event) -> Promise

Unsubscribes from a defined event.

Parameters:

• event {String}: Event name.

ws.close([code[, data]])

Closes a WebSocket connection gracefully.

Parameters:

• code {Number}: Socket close code.
• data {String}: Optional data to be sent to socket before closing.

Event: 'open'

Emits when the connection is opened and ready for use.

Event: 'error'

• <Error>

Emits when a socket error is raised.

Event: 'close'

Emits when the connection is closed.

Event: <Notification>

• <Object>

Emits a notification event with possible parameters a client has subscribed to once the server sends it.

Example:

ws.subscribe('feedUpdated')

ws.on('feedUpdated', handlerFunction)

Server

var WebSocketServer = require('rpc-websockets').Server

var server = new WebSocketServer({
  port: 8080,
  host: 'localhost'
})

new WebSocketServer([options]) -> Server

Instantiate a WebSocket server.

Parameters:

• options {Object}: Server options that are also forwarded to μws.
  • port {Number}: Port number on which the server will listen for incoming requests.
  • host {String}: Address on which the server will listen for incoming requests.

Once the Server class is instantiated, you can use a μws library's instance via server.wss object.

server.register(method, handler[, namespace])

Registers an RPC method.

Parameters:

• method {String}: RPC method name.
• handler {Function}: RPC function that will be fired with a possible parameter object once the method is called.
• namespace {String}: Namespace identifier. Defaults to /.

server.event(name[, namespace])

Creates a new event that can be emitted to clients.

Parameters:

• name {String}: Name of the event.
• namespace {String}: Namespace identifier. Defaults to /.

server.emit(name[, ...params])

Emits a created event to clients.

Parameters:

• name {String}: Name of the event.
• ...params: Parameters forwarded to clients.

server.eventList([namespace]) -> Array

Lists all created events.

Parameters:

• namespace: Namespace identifier. Defaults to /.

server.of(name) -> Namespace

Returns a Namespace object initialized by the provided pathname upon connecting (eg: /chat). Defaults to /.

Parameters:

• name {String}: Namespace identifier.

More information on Namespaces below.

server.createError(code, message[, data]) -> Object

Creates a structured error that can be thrown in a .register callback.

Parameters:

• code {Number}: Indicates the error type that occurred.
• message {String}: Provides a short description of the error.
• data {String|Object}: Details containing additional information about the error.

server.close() -> Promise

Closes the server and terminates all clients.

Event: 'listening'

Emits when the server has started listening for requests.

Event: 'error'

• <Error>

Emits when a server error is raised.

Namespaces

Namespace represents a pool of sockets connected under a given scope identified by a pathname (eg: /chat). Basically borrows ideas from socket.io.

namespace.register(method, handler)

A convenience method for server.register using this namespace.

namespace.event(name)

A convenience method for server.event using this namespace.

get namespace.name -> String

Returns a namespace identifier.

namespace.connected() -> Object

Returns a hash of websocket objects connected to this namespace, identified by id.

namespace.emit(name[, ...params])

Emits a created event to clients connected to this namespace.

Parameters:

• name {String}: Name of the event.
• ...params: Parameters forwarded to clients in this namespace.

get namespace.eventList -> Array

A convenience getter method that lists all created events in this namespace.

namespace.clients() -> Array

Returns a list of client unique identifiers connected to this namespace.

License

MIT