json-rpc-peer
JSON-RPC 2 transport-agnostic library
Install
Installation of the npm package:
> npm install --save json-rpc-peer
Usage
This library provides a high-level peer implementation which should
be flexible enough to use in any environments.
var Peer = require("json-rpc-peer")["default"];
import Peer from "json-rpc-peer";
Construction
var peer = new Peer(function onMessage(message) {
});
The onMessage
parameter is optional, it can be omitted if this
peer does not handle notifications and requests.
Note: For security concerns, only exceptions which are instance of
JsonRpcError
will be transmitted to the remote peer, all others
will be substituted by an instance of UnknownError
.
Connection
The peer is now almost ready, but before being usable, it has to be
connected to the transport layer.
The simplest interface, the exec()
method, has some limitations (no
notifications support) but is often good enough.
It is often used with non-connected protocols such as HTTP:
var readAllStream = require("read-all-stream");
require("http").createServer(
{
port: 8081,
},
function onRequest(req, res) {
readAllStream(req, function(err, message) {
if (err) return;
peer.exec(message).then(function(response) {
res.end(response);
});
});
}
);
If you have a connected transport, such as WebSocket, you may want to
use the stream interface: the peer is a duplex stream and can
therefore be connected to other streams via the pipe()
method:
require("websocket-stream").createServer(
{
port: 8080,
},
function onConnection(stream) {
stream.pipe(new Peer(onMessage)).pipe(stream);
}
);
Notification
peer.notify("foo", ["bar"]);
Request
The request()
method returns a promise which will be resolved or
rejected when the response will be received.
peer
.request("add", [1, 2])
.then(function(result) {
console.log(result);
})
.catch(function(error) {
console.error(error.message);
});
Failure
Sometimes it is known that current pending requests will not get
answered (e.g. connection lost), it is therefore necessary to fail
them manually.
peer.request("add", [1, 2]).catch(function(reason) {
console.error(reason);
});
peer.failPendingRequests("connection lost");
Low level interface
json-rpc-peer
also exports everything from json-rpc-protocol
.
var peer = require("json-rpc-peer");
var format = peer.format;
var parse = peer.parse;
var JsonRpcError = peer.JsonRpcError;
var InvalidJson = peer.InvalidJson;
var InvalidRequest = peer.InvalidRequest;
var MethodNotFound = peer.MethodNotFound;
var InvalidParameters = peer.InvalidParameters;
import {
format,
parse,
JsonRpcError,
InvalidJson,
InvalidRequest,
MethodNotFound,
InvalidParameters,
} from "json-rpc-peer";
Development
# Install dependencies
> yarn
# Run the tests
> yarn test
# Continuously compile
> yarn dev
# Continuously run the tests
> yarn dev-test
# Build for production
> yarn build
Contributions
Contributions are very welcomed, either on the documentation or on
the code.
You may:
- report any issue
you've encountered;
- fork and create a pull request.
License
ISC © Julien Fontanet