koa-json-rpc

JSON-RPC 2.0 middleware for Koa.js which implements the https://www.jsonrpc.org/specification

• Batch support
• Parallel handling

Installation

Install using npm:

npm i @koalex/koa-json-rpc --save

API Reference

• koa-json-rpc
  • Jsonrpc
    • new Jsonrpc([opts])
    • instance
      • .method(method, middleware) ⇒ Jsonrpc
      • .methods [[Get]] ⇒ Array
      • .middleware [[Get]] ⇒ Function
    • static

      • .parseError [[Gett]] ⇒ Object

Jsonrpc ⏏

Kind: Exported class

new Jsonrpc([opts])

Create a new JSON-RPC

| Param | Type | Description | | --- | --- | --- | | [opts] | Object | | | [opts.onerror] | Function | | | [opts.parallel] | Boolean | default is true | | [opts.bodyParser] | Function | koa-bodyparser or async-busboy or some another. |

Examples
Basic usage:

const Koa        = require('koa');
const Router     = require('koa-router');
const bodyParser = require('koa-bodyparser');
const Jsonrpc    = require('@koalex/koa-json-rpc');

const app     = new Koa();
const router  = new Router();

const jsonrpc = new Jsonrpc({
    bodyParser: bodyParser({
        onerror: (err, ctx) => {
            ctx.status = 200;
            ctx.body = Jsonrpc.parseError;
        }
    })
});

jsonrpc.method('someMethod', (ctx, next) => {
    // ctx.jsonrpc available
    /*
        ctx.jsonrpc.request
        ctx.jsonrpc.id
        ctx.jsonrpc.method [[Get]]
        ctx.jsonrpc.params [[Get]]
        ctx.jsonrpc.response
        ctx.jsonrpc.result
        ctx.jsonrpc.error
        ctx.jsonrpc.code
        ctx.jsonrpc.message
        ctx.jsonrpc.data
    */
    ctx.body = 'Hello world!';
});

router.post('/api', jsonrpc.middleware);

app.use(router.routes());
/*
    REQUEST -> {id: 987, jsonrpc: '2.0', method: 'someMethod'}
    RESPONSE <- {jsonrpc: '2.0', id: 987, result: 'Hello world!'}
*/

Additional usage examples:

jsonrpc.method('sum', (ctx, next) => {
    let sum = 0;
    ctx.jsonrpc.params.forEach(num => sum += num);
    ctx.body = sum;
    /*
        also you can:
        ctx.jsonrpc.result = sum;
        ctx.body = ctx.jsonrpc.response;
    */
});
jsonrpc.method('someErrMethod', (ctx, next) => {
    throw new Error('Crash...');
});
jsonrpc.method('someHttpErrMethod', (ctx, next) => {
    ctx.throw(500);
});
/*
    REQUEST -> {id: 1, jsonrpc: '2.0', method: 'sum', params: [1, 2, 3]}
    RESPONSE <- {jsonrpc: '2.0', id: 1, result: 6}
*/
/*
    REQUEST -> {id: 2, jsonrpc: '2.0', method: 'someErrMethod', params: [1, 2, 3]}
    RESPONSE <- {jsonrpc: '2.0', id: 2, error: {code: -32000: message: 'Server error', data: 'Error: Crash...'}}
*/
/*
    REQUEST -> {id: 3, jsonrpc: '2.0', method: 'someHttpErrMethod', params: [1, 2, 3]}
    RESPONSE <- {jsonrpc: '2.0', id: 3, error: {code: -32000: message: 'Server error', data: {message: 'Internal Server Error'}}}
*/

Batch:

const Koa        = require('koa');
const Router     = require('koa-router');
const bodyParser = require('koa-bodyparser');
const Jsonrpc    = require('@koalex/koa-json-rpc');

const app    = new Koa();
const router = new Router();

const jsonrpc = new Jsonrpc({
    bodyParser: bodyParser({
        onerror: (err, ctx) => {
            ctx.status = 200;
            ctx.body = Jsonrpc.parseError;
        }
    })
});

jsonrpc.method('sum', (ctx, next) => {
    let sum = 0;
    ctx.jsonrpc.params.forEach(num => sum += num);
    ctx.body = sum;
});
jsonrpc.method('subtract', (ctx, next) => {
    ctx.body = ctx.jsonrpc.params.minuend - ctx.jsonrpc.params.subtrahend;
});

router.post('/api', jsonrpc.middleware);

app.use(router.routes());

/* 
    REQUEST ->
    [
        {id: 123, jsonrpc: '2.0', method: 'sum', params: [1, 2, 3]},
        {id: 456, jsonrpc: '2.0', method: 'subtract', params: {minuend: 10, subtrahend: 3}}
    ]

    RESPONSE <-
    [
        {id: 123, jsonrpc: '2.0', result: 6},
        {id: 456, jsonrpc: '2.0', result: 7}
    ]
*/

Batch with different instances of Jsonrpc:

const Koa           = require('koa');
const Router        = require('koa-router');
const koaBodyParser = require('koa-bodyparser');
const Jsonrpc       = require('@koalex/koa-json-rpc');

const app     = new Koa();
const router  = new Router();

const bodyParser = koaBodyParser({
    onerror: (err, ctx) => {
        ctx.status = 200;
        ctx.body = Jsonrpc.parseError;
    }
});

const jsonrpc1 = new Jsonrpc();
const jsonrpc2 = new Jsonrpc();

jsonrpc1.method('sum', (ctx, next) => {
    let sum = 0;
    ctx.jsonrpc.params.forEach(num => sum += num);
    ctx.body = sum;
});
jsonrpc2.method('subtract', (ctx, next) => {
    ctx.body = ctx.jsonrpc.params.minuend - ctx.jsonrpc.params.subtrahend;
});

router.post('/api', bodyParser, jsonrpc.middleware, jsonrpc2.middleware);

app.use(router.routes());

/* 
    REQUEST ->
    [
        {id: 1234, jsonrpc: '2.0', method: 'sum', params: [1, 2, 3]},
        {id: 4567, jsonrpc: '2.0', method: 'subtract', params: {minuend: 10, subtrahend: 3}}
    ]

    RESPONSE <-
    [
        {id: 1234, jsonrpc: '2.0', result: 6},
        {id: 4567, jsonrpc: '2.0', result: 7}
    ]
*/

jsonrpc.method(methodName, middleware [,...middleware]) ⇒ Jsonrpc

| Param | Type | Description | | --- | --- | --- | | methodName | String | A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else. | | middleware | Function | middleware |

jsonrpc.methods [[Get]]⇒ Array

Returns a list of registered methods.

jsonrpc.method('sum', (ctx, next) => {
    // Some code...
});
jsonrpc.method('subtract', (ctx, next) => {
    // Some code...
});

console.log( jsonrpc.methods ); // ['sum', 'subtract']

jsonrpc.middleware [[Get]]⇒ Function

Returns a middleware function which takes arguments ctx and next

Jsonrpc.parseError ⇒ Object

Returns error reponse object: { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error', } }

Kind: static method of Jsonrpc

Example

const Koa        = require('koa');
const Router     = require('koa-router');
const bodyParser = require('koa-bodyparser');
const Jsonrpc    = require('@koalex/koa-json-rpc');

const app    = new Koa();
const router = new Router();

const jsonrpc = new Jsonrpc({
    bodyParser: bodyParser({
        onerror: (err, ctx) => {
            ctx.status = 200;
            ctx.body = Jsonrpc.parseError;
        }
    })
});

jsonrpc.method('someMethod', (ctx, next) => {
    // ctx.jsonrpc available
});

router.post('/api', jsonrpc.middleware);

app.use(router.routes());

Contributing

Please submit all issues and pull requests to the koalex/koa-json-rpc repository!

Tests

Run tests using npm test.

This project using SemVer for versioning. For the versions available, see the tags on this repository.

This project is licensed under the MIT License - see the LICENSE file for details