json-rpc-dual-engine

This is a zero-dependencies protocol agnostic implementation of the JSON-RPC-2.0 spec to allow remote function calls.

This package includes a client and a server, but you can import either separately without increasing the size of your final build, if you don't need both.

Install

npm install json-rpc-dual-engine

Usage

Server

Create the server and register the methods that can be called from the client:

const JsonRpcServer = require('json-rpc-dual-engine/server');

const server = JsonRpcServer();

server.register('multiply', (a, b) => a * b);

Use the accept method to deliver incoming remote method calls to the server. The server validates the json-rpc message call, calls the appropriate registered method, and generate the appropriate json-rpc response based on the return of the registered handler.

Register a onresponse callback to receive the json-rpc responses generated by the server.

server.onresponse = response => console.log(response);

server.accept('{"jsonrpc":"2.0","method":"multiply","params":[7,11],"id":"1"}');

// Output: '{"jsonrpc":"2.0","result":77,"id":"1"}'

Client

Create the client and setup the onrequest callack to send request made by the client to the server.

const JsonRpcClient = require('json-rpc-dual-engine/client');

const client = JsonRpcClient();

client.onrequest = request => console.log(request);

const resultPromise = client.request('multiply', [7, 11]);

// Output: '{"jsonrpc":"2.0","method":"multiply","params":[7,11],"id":"1"}'

Use the accept method to deliver incoming server responses to the client to resolve request promises.

// Using setTimeout to simulate a future incoming message from the server
setTimeout(100, () => client.accept('{"jsonrpc":"2.0","result":77,"id":"2"}'));

const result = await client.request('multiply', [7, 11]);

console.log(result); // Output: 77

You can also use the remote sugar proxy object to make things simpler:

const remote = client.remote;

const result = await remote.multiply(7, 11);

console.log(result); // Output: 77

Server and Client

Use JsonRpcDualEngine() to create a json-rpc engine that behaves as both client and server. The accept method of the dual engine can accept both rpc requests and responses, and it has both the onresponse and onrequest callbacks.

const { JsonRpcDualEngine } = require('json-rpc-dual-engine');

const engine1 = JsonRpcDualEngine();
const engine2 = JsonRpcDualEngine();

engine1.register('getId', () => '1');
engine2.register('getId', () => '2');

engine1.onrequest = request => engine2.accept(request);
engine1.onresponse = response => engine2.accept(response);
engine2.onrequest = request => engine1.accept(request);
engine2.onresponse = response => engine1.accept(response);

console.log(await engine1.remote.getId()); // Output: '2'
console.log(await engine2.remote.getId()); // Output: '1'

WebSocket Example

On the server side:

const JsonRpcServer = require('json-rpc-dual-engine/server');
const WebSocket = require('ws');

const engine = JsonRpcServer();
const wss = new WebSocket.Server();
const websocket = await new Promise(resolve => wss.on('connection', resolve));

// Incoming messages from the websocket will be handled by the engine
// Whenever the engine has a response to send, send it through the websocket
websocket.onmessage = message => engine.accept(message.data);
engine.onresponse = response => websocket.send(response);

// Register a method to handle incoming json-rpc-2.0 requests from the client
engine.register('multiply', (a, b) => a * b);

On the client side:

const JsonRpcClient = require('json-rpc-dual-engine/client');
const WebSocket = require('ws');

const engine = JsonRpcClient();
const websocket = new WebSocket('ws://remote.example');

await new Promise((resolve, reject) =>
{
	websocket.onopen = resolve;
	websocket.onerror = reject;
});

// Incoming messages from the websocket will be handled by the engine
// Whenever the engine has a request to send, send it through the websocket
websocket.onmessage = message => engine.accept(message.data);
engine.onrequest = request => websocket.send(request);

// Sends a json-rpc-2.0 request through the webscoket to the remote server and waits for the response
const result = await engine.remote.multiply(7, 11);

console.log(result); // Output: 77

Node Streams

You can use the JsonRpcStream to work with Node.js streams. It creates a Duplex streams that sends incoming data to the engine and outputs messages (client requests or server responses) generated by engine. It works with both client and server engines.

const { JsonRpcClient, JsonRpcServer } = require('json-rpc-dual-engine');
const JsonRpcStream = require('json-rpc-dual-engine/stream');

const server = JsonRpcStream(JsonRpcServer());
const client = JsonRpcStream(JsonRpcClient());

// Streams use the dual engine, which can act as both client and server
server.engine.register('multiply', (a, b) => a * b);

// Pipes requests from the client to the server, and responses from the server back to the client
client.pipe(server).pipe(client);

const result = await client.engine.request('multiply', [7, 11]);

console.log(result); // Output: 77

Contributing

Install

npm install

Test

npm test

Coverage

npm run coverage

LICENSE

MIT