json-rpc-utils
Let your client and server talk over function calls under JSON-RPC 2.0 spec.
This library is protocol agnostic, which is convienient if you're already using an http
server like Express or Fastify, and you want to control how the request is passed off to this RPC system. If you want to re-use your authentication middleware, or your fancy JSON parser/serializer, or your tracing system, this is the library for you!
Features:
- Use over HTTP, WebSocket, TCP, UDP, inter-process, whatever else
- Easy migration from HTTP to WebSocket, for example
- No external dependencies
- Keep your package small
- Stay away from dependency hell
- First-class TypeScript support (written in TypeScript)
Install
npm install --save json-rpc-utils
Example
The example uses HTTP for communication protocol, but it can be anything.
Server
const express = require("express");
const bodyParser = require("body-parser");
const { JSONRPCServer } = require("json-rpc-utils");
const server = new JSONRPCServer();
server.addMethod("echo", ({ text }) => text);
server.addMethod("log", ({ message }) => console.log(message));
const app = express();
app.use(bodyParser.json());
app.post("/json-rpc", async (req, res) => {
const jsonRPCRequest = req.body;
const jsonRPCResponse = await server.process(jsonRPCRequest);
if (jsonRPCResponse) {
res.json(jsonRPCResponse);
} else {
res.sendStatus(204);
}
});
app.listen(80);
With authentication
To hook authentication into the API, inject custom params:
const server = new JSONRPCServer();
server.addMethod(
"echo",
(params, context) => `${context.userID} said ${params.text}`
);
app.post("/json-rpc", async (req, res) => {
const jsonRPCRequest = req.body;
const userID = getUserID(req);
const response = await server.process(jsonRPCRequest, { userID });
if (jsonRPCResponse) {
res.json(jsonRPCResponse);
} else {
res.sendStatus(204);
}
});
const getUserID = (req) => {
};
Client
import { JSONRPCClient } from "json-rpc-utils";
const client = new JSONRPCClient(async (jsonRPCRequest) =>
const response = await fetch("http://localhost/json-rpc", {
method: "POST",
headers: {
"content-type": "application/json",
},
body: JSON.stringify(jsonRPCRequest),
})
if (response.status === 200) {
return await response.json()
} else if (jsonRPCRequest.id !== undefined) {
return Promise.reject(new Error(response.statusText));
}
})
);
client
.request("echo", { text: "Hello, World!" })
.then((result) => console.log(result));
client.notify("log", { message: "Hello, World!" });
With authentication
Just like JSONRPCServer
, you can inject custom context to JSONRPCClient
as well:
const client = new JSONRPCClient(
(jsonRPCRequest, context) =>
return await fetch("http://localhost/json-rpc", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${context.token}`,
},
body: JSON.stringify(jsonRPCRequest),
}).json()
);
client.request("echo", { text: "Hello, World!" }, { token: "foo's token" });
client.notify("log", { message: "Hello, World!" }, { token: "foo's token" });
Error handling
To respond an error, reject with an Error
. On the client side, the promise will be rejected with an Error
object with the same message.
server.addMethod("fail", () =>
Promise.reject(new Error("This is an error message."))
);
client.request("fail").then(
() => console.log("This does not get called"),
(error) => console.error(error.message)
);
The error
object thrown by the client will be a JSONRPCRemoteError
object if the server replies with a spec conforming JSON-RPC error response. If the server fails to reply with an appropriate response or any other internal error occurs, the error will be a plain old Error
object.
JSONRPCRemoteError
are a subclass of the standard Error
object, so they have a message
like normal errors, and the message will come from the server side error. The stack of a JSONRPCRemoteError
object will be the client side local stack. These custom error objects also have the following properties:
code
, containing the JSON-RPC error codedata
, which if set on the server will contain auxiliary data for the error. This is supported by the JSON-RPC spec, but isn't set automatically. Users of this library on the server ust use the server's getErrorData
option to send data
with errors.isJSONRPCRemoteError
, which is always true
.
There's also an isJSONRPCRemoteError
function exported from this package for detecting these errors in a forward compatible (and TypeScript type assert-y) way.
Server side error data
The JSONRPCServer
class can be configured to send custom data
alongside error responses. Pass a getErrorData
function in the constructor options to the server. The function is passed any error
s thrown by handlers, and should reply with a JSON serializable object.
const server = new JSONRPCServer({
getErrorData: (error) => {
return {
customData: true,
errorStack: error.stack,
};
},
});
client.request("fail").then(
() => {},
(error) => console.error(error.data.stack)
);
Build
npm run build
Test
npm test
Credits
This project started as a fork of json-rpc-utils
by Shogo Wada! We forked to change how we handle error,s drop some backwards compatability, and improve performance by using async/await
. Thanks Shogo for all the hard work!