JsonRPC Server

Легковесный сервер для создания API по спецификации JsonRPC. Взаимодействие с сервером доступно через HTTP и(или) через брокер сообщений Nats

Кратенько о протоколе JsonRPC 2.0

В запросах к серверу всегда отправляется POST сообщение, в теле которого содержится json-запрос типа:

{
    "jsonrpc": "2.0",       // Признак спецификации (обязательный)
    "method": "subtract",   // Название метода, который должен быть выполнен на сервере (обязательный)
    "params": [42, 23],     // Параметры метода (не обязательное поле), массив, объект или простые типы
    "id": 1                 // Идентификатор запроса. Может отсутствовать, но в это случае сервер выполнит метод, но не вернет ответ (согласно спецификации)
}

и в ответ сервер отправляет json-ответ типа:

{
    "jsonrpc": "2.0",       // Признак спецификации (обязательный)
    "result": 19,           // Результат - может быть любого типа
    "id": 1                 // Идентификатор ответа - всегда равен идентификатору запроса.
}

или ошибку

{
    "jsonrpc": "2.0",       // Признак спецификации (обязательный)
    "error": {              // Объект ошибки (обязательный)
        "code": -32601,                 // Код ошибки (обязательный, см. описание ошибок протокола)
        "message": "Method not found"   // Сообщение об ошибке (обязательный, см. описание ошибок протокола)
        "data": "nothing"               // Дополнительные данные об ошибке любого типа (не обязательный)
    },
    "id": "1"               // Идентификатор ответа - всегда равен идентификатору запроса.
}

API

Конструктор

• new JsonRPCServer([httpServer]) - создание экземпляра JSONRPC сервера. Если планируется использовать HTTP сервер совместно с чем-то еще (например ws), его необходимо создать вручную и передать в качестве аргумета.

Основные методы

• .on(method, [validator,] onRequestCallback) - установка рекации запрос выполнения по метода JsonRPC. Аргументы:

  • method - Навание метода, как в как в свойстве method запроса JsonRPC.
  • validator - не обязательная функция проверки параметров запроса. В качестве аргумента ей передается значение свойства parametr параметры JsonRPC. Функция должна возвращать проверенные параметры или вызывать исключение (throw new Error(text)). Если исключение произошло - сервер автоматически вернет ошибку -32602(invalid params), дописав в свойство data текст ошибки.
  • onRequestCallback - функция вида ([params,] [channel, ], response)=>{}, которая будет вызвана при входящем запросе с соответствующим методом. В функцию передаются до трех аргументов:
    • params - параметры (после выполнения функции валидации или напрямую, если ее нет)
    • channel - канал запроса: http - если запрос через HTTP-сервер или канал Nats'a. Если используется обязательно должет быть аргумент params
    • response - функция, вызвав которую, отправляется ответ в канал. Передается всегда. Данная функция принимает два параметра:

      • error - ошибка в формате JsonRPC

      • result - результат, который будет подствлен в свойство result ответа, если нет ошибки.

• .listenHttp ([options,] [callback]) - запуск прослушивания HTTP запросов. Аргументы:

  • options - стандартные опции для .listen экземпляра HTTP сервера NodeJS, по умолчанию { host: '127.0.0.1', port: 8080 }
  • callback - функция, которая будет вызвана при начале прослушивания или ошибке. Ошибка передается в нее аргументом.

• .listenNats (options, channel, [callback]) - запуск прослушивания запросов через Nats. Аргументы:

  • options - URL подключения (строка) или объект стандартных опции подключения к серверу Nats.
  • channel - канал, который будет прослушиваться
  • callback - функция, которая будет вызвана при начале прослушивания или ошибке. Ошибка передается в нее аргументом.

Методы (дополнительные)

• .setHeaders(header) - устанваливает заголовки, которые будут отправляться при ответе HTTP сервера. По умочанию передаются:

{
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "OPTIONS, POST",
   "Access-Control-Allow-Headers": "Origin, Accept, Content-Type",
   "Content-Type": "application/json", // Передается всегда
   "Content-Length": 12345             // Передается всегда
}

Пример

1. Установите пакет сервера: npm install jsonrpc-server-http-nats --save
2. Напишите код:

// Подключаем модуль
const JsonRPCServer = require('jsonrpc-server-http-nats');

// Создаем экземпляр сервера
var server = new JsonRPCServer();

// Обработчик на метод Ping
server.on('Ping', (response) => {
    let error = null;
    let result = 'Pong';
    response(error, result);
});

// Валидатор и обработчик на метод Hello, с проверкой параметра
var validator = function(param) {
    if (typeof(param) !== 'string') {
        throw new Error('Ожидается строка');
    }
    return param;
}

server.on('Hello', validator, (params, channel, response) => {
    let error = null;
    let result = `Hello ${params} on channel ${channel}!`;
    response(error, result);
});


// Возврат ошибки с информацие о канале
server.on('ItIsNotWork', (params, response)=>{
    let error = {
        code: 1,
        message: 'Custom error'
    }
    response(error);
});


// Запустим сервер
server.listenHttp();