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;
};