@alius/rpc

JSON-RPC 2.0 implementation configured with OpenRPC.

This implemetation is not tied to any specific transport.

Installation

npm install @alius/rpc

Usage

Create configuration file config.openrpc.json

{
  "openrpc": "1.2.6",
  "info": {
    "version": "1.0.0",
    "title": "Calc"
  },
  "methods": [
    {
      "name": "add",
      "params": [
        {
          "name": "a",
          "required": true,
          "schema": {
            "type": "number"
          }
        },
        {
          "name": "b",
          "required": true,
          "schema": {
            "type": "number"
          }
        },
        {
          "name": "c",
          "schema": {
            "type": "number"
          }
        }
      ],
      "result": {
        "name": "addition of provided params",
        "schema": {
          "type": "number"
        }
      }
    },
    {
      "name": "subtract",
      "params": [
        {
          "name": "a",
          "required": true,
          "schema": {
            "type": "number"
          }
        },
        {
          "name": "b",
          "required": true,
          "schema": {
            "type": "number"
          }
        }
      ],
      "result": {
        "name": "subtraction of provided params",
        "schema": {
          "type": "number"
        }
      }
    }
  ]
}

import { RPC } from "@alius/rpc";
// load config
import config from "./config.openrpc.json" assert { type: "json" };

// create and init RPC provider
// with loaded config and provided method implementations
const rpc = await (new RPC(config, {
  add: (a, b, c = 0) => a + b + c,
  subtract: (a, b) => a - b
})).init();

// create request object
// {
//  jsonrpc: "2.0",
//  id: 1,
//  method: "add",
//  params: {
//    a: 1,
//    b: 2,
//    c: 3
//  }
// }
const req1 = RPC.request(1, "add", {
  a: 1,
  b: 2,
  c: 3
});

// resulting response object
// {
//  jsonrpc: "2.0",
//  id: 1,
//  result: 6
// }
const res = await rpc.execute(req1);

const req2 = RPC.request(2, "subtract", {
  a: 10,
  b: 2
});

// resulting array of reponse objects
// [
//  {
//    jsonrpc: "2.0",
//    id: 1,
//    result: 6
//  },
//  {
//    jsonrpc: "2.0",
//    id: 2,
//    result: 8
//  }
// ]
const multiRes = await rpc.execute([req1, req2]);

API

RPC

Constructors

RPC()

Creates new RPC provider with empty configuration.

RPC(config, handlers)

Creates new RPC provider with provided configuration and handlers.

RPC(config, handlers, options)

Creates new RPC provider with provided configuration, handlers and options.

Options can specify list of preProcessors and postProcessors functions. Specified pre-processor functions will be executed before handler execution. Specified post-processor functions will be executed after handler execution.

Properties

initialized

Returns true if RPC provider already initialized.

ajv

Holds Ajv validator.

json

Holds JSON request object beeing processed.

Methods

init()

Initializes RPC provider. Must be run once.

configure(config, handlers?, options?)

Re-configures RPC provider with new configuration.

serviceDiscover()

Handler for 'rpc.discover' method.

putMethod(config, handler)

Adds new method to existing live configuration.

removeMethod(name)

Removes specified method from live configuration.

getMethodConfig(name)

Returns method config.

execute(json, options = {})

Executes single JSON-RPC request or batch of requests.

executeSingle(json, options = {})

Executes single JSON-RPC request.

Static properties

VERSION

"2.0"

JSONRPC

"jsonrpc"

ID

"id"

METHOD

"method"

PARAMS

"params"

RESULT

"result"

ERROR

"error"

ERROR_CODE

"code"

ERROR_MESSAGE

"message"

ERROR_DATA

"data"

ERROR_32000

Response for JSON stringify error.

ERROR_32010

Response for Pre-processor execution error.

ERROR_32020

Response for Method execution error.

ERROR_32030

Response for Invalid result error.

ERROR_32040

Response for General security error.

ERROR_32041

Response for Credentials expired error.

ERROR_32050

Response for Post-processor execution error.

ERROR_32600

Response for Invalid request error.

ERROR_32601

Response for Method not found error.

ERROR_32602

Response for Invalid params error.

ERROR_32603

Response for Internal error.

ERROR_32700

Response for JSON parse error.

SPEC_ERRORS

List of error objects defined in specs.

IMPL_ERRORS

List of all error objects defined in this implementation (including spec errors).

RPC_DISCOVER

Service discovery method name as specified in OpenRPC ("rpc.discover").

RPC_DISCOVER_SCHEMA

Service discovery method schema as specified in OpenRPC.

Static methods

request(id, method, params)

Creates JSON-RPC request object.

notification(method, params)

Creates JSON-RPC notification object.

errorResponse(error, id?)

Creates JSON-RPC error response object.

findError(err, defaultError?, errors?)

Finds corresponding JSONRPCErrorObject among implementation defined and among additional errors (if provided).

RPCException

Constructors

RPCException(code? = -32603, message? = "RPCError", cause? = null, data? = null)

Creates new RPC error