@mahsumurebe/jrpc-server

JSONRPC Server

JSONRPC 2.0 NodeJS Server written in TypeScript

Fully tested to comply with the official JSON-RPC 2.0 specification

Quick Overview

It is used to quickly create JSONRPC Server. Method definition is very simple. With the event structure, events can be easily followed.

Install

npm install @mahsumurebe/jrpc-server

Usage

It should not create a JRPCServer instance.

import {JRPCServer, HttpAdapter} from '@mahsumurebe/jrpc-server';

// Create JSONRPC Server with HTTP Adapter
const instance = await new JRPCServer(
    new HttpAdapter({
        hostname: "localhost",
        port: 3000,
    }),
    {
        paramType: 'array'
    }
);
// Start server
await instance.start();

JRPCServer Options

KEY	DEFAULT	DESCRIPTION
paramType	"array"	Parameter type. Specifies the type of params item in the body of the JSONRPC request.
methodManager	undefined	Manager that stores methods and calls them.
routerManager	undefined	The manager that processes the requests forwarded by the adapter, calls the relevant method(s) via the method manager and creates response data.
validator	undefined	The method called to validate each JSONRPC request. Returns InvalidParamException if an invalid JSONRPC body was sent.

Method Definition

Method definitions are after JRPCServer instance is created.

instance.methods.add('help', () => {
    return 'DONE';
});

instance.methods.add('sum', (a: number, b: number) => {
    return a + b;
});

For Testing

You can use the code below to send and test the cURL request.

curl -H "Content-Type: application/json" -d '{"id":2, "jsonrpc":"2.0","method":"sum","params":[1,2]}' http://127.0.0.1:3000

Response:

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": 3
}

Adapters

There are HTTP and Websocket adapters available.

HTTP

HTTP Adapter is used to create to JRPC Server served over HTTP Protocol.

// Adapter Instance
import {JRPCServer, HttpAdapter} from '@mahsumurebe/jrpc-server';

const adapter = new HttpAdapter({
    port: 3000
})

// Create Instance
const instance = new JRPCServer(adapter);

Configuration List

Configurations are defined in the object in the first parameter of the construction method when creating the HttpAdapter.

KEY	DEFAULT	DESCRIPTION	Type
hostname	127.0.0.1	Server listening address	string
port	undefined	Server listening port	number
pathname	"/"	Server listening path	string
keepAlive	false	Activates the keep-alive function on the socket immediately after a new incoming connection is received	boolean
keepAliveInitialDelay	0	If set to a positive number, it sets the initial delay before the first keepalive probe is sent on an idle socket.	number
ssl	undefined	SSL Config	object
ssl.cert	undefined	Cert chains in PEM format	string
ssl.privateKey	undefined	Private keys in PEM format. PEM allows the option of private keys being encrypted.	string

Websocket

Websocket Adapter is used to create to JRPC Server served over Websocket Protocol.

import {JRPCServer, WebsocketAdapter} from '@mahsumurebe/jrpc-server';

// Adapter Instance
const adapter = new WebsocketAdapter({port: 3000})

// Create Instance
const instance = new JRPCServer(adapter);

Configuration List

Configurations are defined in the object in the first parameter of the construction method when creating the WebsocketAdapter.

Configuration List

Configurations are defined in the object in the first parameter of the construction method when creating the HttpAdapter.

KEY	DEFAULT	DESCRIPTION	Type
hostname	127.0.0.1	Server listening address	string
port	undefined	Server listening port	number
pathname	"/"	Server listening path	string
keepAlive	false	Activates the keep-alive function on the socket immediately after a new incoming connection is received	boolean
keepAliveInitialDelay	0	If set to a positive number, it sets the initial delay before the first keepalive probe is sent on an idle socket.	number
ssl	undefined	SSL Config	object
ssl.cert	undefined	Cert chains in PEM format	string
ssl.privateKey	undefined	Private keys in PEM format. PEM allows the option of private keys being encrypted.	string

Custom Adapters

For custom adapters, you need to extend the adapter class with the AdapterAbstract abstract class. You have to create the abstract functions request, connect and destroy inside the class.

listen: A piece of code should be added to this method that enables the creation of a protocol server.

shutdown: A piece of code should be added to this method that enables the protocol server shutdown.

isListening: Checks protocol server is listening.

How to Use Both HTTP Adapter and Web Socket Adapter

If you want the server you created to respond to request both over the HTTP protocol and over the Websocket protocol, it will be sufficient to place an HttpAdapter class inside the WebsocketAdapter class constructor.

import {HttpAdapter, WebsocketAdapter, JRPCServer} from '@mahsumurebe/jrpc-server';

// Create HTTP Adapter
const httpAdapter = new HttpAdapter({
    hostname: "localhost",
    port: 3000,
});
// Create Websocket Adapter with HTTP Adapter
const websocketAdapter = new WebsocketAdapter(httpAdapter);

// Create instance
const instance = new JRPCServer(websocketAdapter);

Resources

• Changelog