json-rpc-dual-engine
v0.5.4
Published
JSON-RPC-2.0 client and server protocol-agnostic engine.
Downloads
24
Maintainers
Readme
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