API Server for JSON-RPC protocol other HTTP and Nats
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo
src
.gitignore
LICENSE
README.md
package-lock.json
package.json

README.md

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();