micro-rpc

Async RPC microservices made easy

Made with Micro

Quickstart

Create a RPC method to add 2 numbers:

// index.js
const { rpc, method, createError } = require('@bufferapp/micro-rpc');
module.exports = rpc(
  method('add', (a, b) => a + b)
);

Start the server

micro

Use the Micro RPC Client: https://github.com/bufferapp/micro-rpc-client to run the add method

const RPCClient = require('@bufferapp/micro-rpc-client');

const rpc = new RPCClient({
  serverUrl: 'https://localhost:3000',
});

rpc.call('add', 2, 2)
  .then(result => console.log(result)); // output: 4

Or you can use curl to call the add method:

curl -H "Content-Type: application/json" -X POST -d '{"name": "add", "args": "[2, 3]"}' localhost:3000 | python -m json.tool

# {
#    "result": 5
# }

To see a list of all available methods use the methods call:

curl -H "Content-Type: application/json" -X POST -d '{"name": "methods"}' localhost:3000 | python -m json.tool

# {
#   result: [
#     {
#       "docs": "add two numbers"
#       "name": "add"
#     },
#     {
#       "docs": "list all available methods",
#       "name": "methods"
#     }
#   ]
# }

Usage

Here's a few examples of how to hook up the handler methods:

const { rpc, method, createError } = require('@bufferapp/micro-rpc');
module.exports = rpc(
  method('add', (a, b) => a + b),
  method('addAsync', (a, b) => new Promise((resolve) => {
    resolve(a + b);
  })),
  method('addItems', ({ a, b }) => a + b),
  method('addItemsAsync', ({ a, b }) => new Promise((resolve) => {
    resolve(a + b);
  })),
  method('throwError', () => {
    throw createError({ message: 'I\'m sorry I can\'t do that'});
  }),

  method('throwErrorAsync', () => new Promise((resolve, reject) => {
    reject(createError({ message: 'Something is broke internally', statusCode: 500 }));
  })),
  method('documentation',
  `
  # documentation

  Document what a method does.
  `,
  () => new Promise((resolve, reject) => {
    reject(createError({ message: 'Something is broke internally', statusCode: 500 }));
  }))
);

API

rpc

An async function that can be served by Micro, takes a bunch of methods as arguments.

rpc(...methods)

...methods - method - micro rpc method (see below)

method

add a remote method

method(name, [docs], fn)

name - string - the name of the method
docs - string - documentation about a method
fn - function - the function to call and apply parameters the method is requested

createError

create an error to be thrown, optionally set the status code

createError({ message, statusCode = 400})

message - string - error message to return
statusCode - string - optional HTTP status code (default to 400)

Request and Response Objects

Request and response objects are always passed along as the last two arguments in case they're needed.

method('addWithSession', (a, b, req, res) => {
  if (!req.session) {
    throw createError({ message: 'a session is needed to add numbers', statusCode: 401});
  }
  return a + b;
};