WSRPC client

Easy to use javascript client for wsrpc-aiohttp or wsrpc-tornado websocket servers.

See online demo and documentation with examples.

• Features
• Installation
• Usage
• API
  • Global configuration
  • Constructor options
  • Methods

Features

• Allows to call server functions from the client side and to call client functions from the server side (e.g. to notify clients about events);
• Async connection protocol: both server or client are able to call multiple functions and get responses as soon as each response would be ready in any order;
• Transfers any exceptions from a client side to the server side and vise versa;
• No dependencies;
• Messaging is based on JsonRPC protocol;
• Provides typescript interface, ES6 module and UMD distribution as well.
• Ability to implement very complex scenarios.

Installation

Install via npm:

npm install @wsrpc/client

Usage

Let's implement application, that tells jokes by request and collects feedback about them (see jsfiddle).

Backend is located at demo.wsrpc.info.

<script type="text/javascript" src="//unpkg.com/@wsrpc/client"></script>
<script>
var RPC = new WSRPC('wss://demo.wsrpc.info/ws/', 5000);

// Register client route, that can be called by server.
// It would be called by server, when server sends a joke.
RPC.addRoute('joke', function (data) {

    // After server sends a joke server waits for an answer, if joke is
    // funny. test.getJoke call is going to be finished only after user
    // sends response.
    return confirm(data.joke + '\n\nThat was funny?');
});
RPC.connect();

// Request server to tell a joke by calling test.getJoke
// Server would call client route 'joke' (registered above) and wait for
// client answer (if joke is funny or not).
RPC.call('test.getJoke', {}).then((result) => {

    // Here you would finally see server reaction on your feedback about
    // joke.
    // If 'joke' client route responds that joke is funny - you would see
    // something like 'Cool!', or 'Hmm... try again' if it's not.
    alert(result);
}, (error) => {
    alert(error.type + '("' + error.message + '")');
});
</script>

API

Global configuration

WSRPC.DEBUG

Static boolean flag, controls whether debug information should be displayed.

Can be enabled/disabled at any moment.

WSRPC.DEBUG = true;
var RPC = new WSRPC(...);
...

WSRPC.TRACE

Static boolean flag, controls whether information about events and errors should be traced.

Can be enabled/disabled at any moment.

WSRPC.TRACE = true;
var RPC = new WSRPC(...);
...

Constructor options

URL, reconnectTimeout = 1000

Parameter	Type	Required	Description
URL	string	Yes	Absolute or relative URL
reconnectTimeout	number	No	Timeout for reconnecting, defaults to 1000 ms

// Url can be relative (schema for websocket would be detected automatically 
// depending on page http/https schema)
var RelativeUrlRPC = new WSRPC('/ws/', 5000);

// Absolute websocket url example
var UnsecureRPC = new WSRPC('ws://example.com/ws', 5000);

// Secure absolute websocket url example
var SecureRPC = new WSRPC('wss://example.com/ws', 5000);

Methods

WSRPC.connect()

Establishes connection with the server.

var RPC = new WSRPC(url);
RPC.connect();

WSRPC.destroy()

Closes socket.

var RPC = new WSRPC(url);

var deferred = RPC.onEvent('onconnect');
deferred.resolve = function() {
    RPC.destroy();
};

RPC.connect();

WSRPC.state()

Get current socket state as a string.

Possible values: CONNECTING, OPEN, CLOSING, CLOSED.

var RPC = new WSRPC(url);
console.log(RPC.state());  // Displays CLOSED

WSRPC.stateCode()

Get current socket state code (integer). Possible values:

Code	State
0	CONNECTING
1	OPEN
2	CLOSING
3	CLOSED

var RPC = new WSRPC(url);
console.log(RPC.stateCode());  // Displays 3

WSRPC.addRoute(name, callback)

Register route on the client with specified name, route added later replaces route added earlier with the same name.

Parameter	Type
name	string
callback	function

Callback would be called with object type parameter data containing parameters from server. Callback return value would be received by server.

var RPC = new WSRPC(url);
RPC.addRoute('askUser', function(data) {
    // Data is object, containing parameters from server.
    // Would display question ask user to enter response and return response 
    // to the server. 
    return { response: prompt(data.question) };
});

WSRPC.deleteRoute(name)

Remove specified client route.

Parameter	Type
name	string

var RPC = new WSRPC(url);
RPC.addRoute('askUser', function() { return {} });
RPC.deleteRoute('askUser');

WSRPC.call(route, params)

Call server function with specified parameters, returns Promise that can be awaited using await syntax.

Parameter	Type
route	string
params	object

var RPC = new WSRPC(url);
RPC.connect();
RPC.call('serverRoute', {
    param1: 'value1', 
    param2: 'value2'
}).then((result) => {
    alert(result);
}, (error) => {
    alert(error.type + '("' + error.message + '")');
});

WSRPC.addEventListener(event, callback)

Add permanent callback for event (see onEvent to register one time event). Returns eventId, that can be used later to remove event.

Parameter	Type
event	string
callback	function

var RPC = new WSRPC(url);
RPC.addEventListener('onconnect', function() {
    console.log('Connected to the server!');
});

WSRPC.removeEventListener(event, eventId)

Remove event listener using eventId (returned by addEventListener).

Parameter	Type
event	string
eventId	integer

var RPC = new WSRPC(url);
var eventId = RPC.addEventListener('onconnect', function() {
    console.log('Connected to the server!');
});
RPC.removeEventListener('onconnect', eventId);

WSRPC.onEvent(event)

Get deferred object, that would execute only once for specified event. deferred.promise is a native Promise and can be awaited using await syntax.

Parameter	Type
event	string

var RPC = new WSRPC(url);

var deferred = RPC.onEvent('onconnect');
deferred.resolve = function() {
    RPC.destroy();
};

RPC.connect();

WSRPC.proxy

Proxy for WSRPC.call method to call the remote functions by dot notation.

Parameter	Type
params	object

var RPC = new WSRPC(url);
RPC.connect();
RPC.proxy.serverRoute({
    param1: 'value1', 
    param2: 'value2'
}).then((result) => {
    alert(result);
}, (error) => {
    alert(error.type + '("' + error.message + '")');
});

Proxy Routes

Function based Proxy example:

Python server code:

from wsrpc_aiohttp import WebSocketAsync

async def subtract(socket: WebSocketAsync, *, a, b):
    return a - b

WebSocketAsync.add_route('subtract', subtract)

Javascript client code:

var RPC = new WSRPC(url);
RPC.connect();
await RPC.proxy.subtract({a: 1, b: 9});

Class based Proxy example:

Python server code:

from wsrpc_aiohttp import decorators, WebSocketAsync

class Storage(Route):
    async def init(self):
        self._internal = dict()

    @decorators.proxy
    async def get(self, key, default=None):
        return self._internal.get(key, default)

    @decorators.proxy
    async def set(self, key, value):
        self._internal[key] = value
        return True

WebSocketAsync.add_route('kv', Storage)

Javascript client code:

var RPC = new WSRPC(url);
RPC.connect();
await RPC.proxy.kv.set({ key: 'foo', value: 'bar' });
await RPC.proxy.kv.get({ key: 'foo' });

Versioning

This software follows Semantic Versioning