Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 

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

About

API Server for JSON-RPC protocol other HTTP and Nats

Resources

License

Releases

No releases published

Packages

No packages published