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