rpc-websockets

rpc-websockets wraps ws library providing 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',
  rpc: {
    root_path: '/rpc',
    version: '1.0'
  }
})

// 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/rpc/1.0')

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()
})

Client

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

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

Instantiate a WebSocket client.

Parameters:

• address {String}: The URL of the WebSocket server. Defaults to 'ws://localhost:8080/rpc/1.0'.
• 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]) -> 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.

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',
  rpc: {
    root_path: '/rpc',
    version: '1.0'
  }
})

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.
  • rpc {Object}:
    • root_path {String}: RPC server endpoint.
    • version {String}: RPC API version.

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

server.register(method, callback)

Registers an RPC method.

Parameters:

• method {String}: RPC method name.
• callback {Function}: RPC function that will be fired with a possible parameter object once the method is called.

server.event(name)

Creates a new event that can be emitted to clients.

Parameters:

• name {String}: Name of the event.

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

Emits a created event to clients.

Parameters:

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

get server.eventList -> Array

Lists all created events.

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.