Raptor RPC
Raptor RPC is a transport-agnostic RPC server with middleware support and an easy to use api. It will allow you to have a server up and running in a matter of minutes, without limiting you to a specific transport.
It works out of the box with the standard transports provided by Node.js and also with some popular frameworks.
Installation
npm install --save raptor-rpc
Usage
// Raptor libraryconst Raptor = // Example librariesconst fetch = const readJsonFile = const app = app appmethod'ping' { return 'pong'} appmethod'get-package-name' { return } appmethod'random-name' { return } app
API
Raptor
.use(fn)
Add middleware to the server.
fn
: Middleware function with the signature(req, next) => Promise
The middleware function should return a promise of a response. Calling next
will return a promise of the next middleware or, if no other middleware exists,
the method handler.
.method(name, fn)
Register a method with the server.
name
: The method namefn
: Method handler with the signature(req) => Promise
The method handler should return a promise of what to respond with. It's also
acceptable to return the value right away, since the handler is wrapped in a
.then
call. This also means that any errors thrown will be caught correctly.
.handle(...)
Handle a request, accepts a number of different parameters.
Read more under Transports
.
.attach(server)
Attaches Raptor to the server, accepts a number of different parameters.
Read more under Transports
.
.serve(type, port[, cb])
Starts a server and accepts connections.
type
: Which transport to use (dgram
,http
,net
)port
: Which port to listen tocb
: Function to be called when accepting connections
Returns the server instance (dgram.Socket
, http.Server
or net.Server
).
Request
.id
The jsonrpc id of the request, can be undefined
. This variable is read-only.
.method
The method name of the request. This variable is read-only.
.params
The params object as passed from the client. Can be Array
or Object
.
.param(key, defValue)
Helper function to get a parameter or a default value if it wasn't provided.
key
: Key to fetch, can beNumber
orString
defValue
: Value to return ifkey
wasn't provided, isundefined
if not specified.
.require(key, type)
Helper function to require the presence a parameter and optionally check it's
type. Will send an Invalid params
error (-32602) back to the client, and stop
execution, if the parameter is not present. It also returns the value of the
parameter.
key
: Key to require, can beNumber
orString
type
: If specified, also require the parameter to be of this type
Valid values for type
is specified in the
JSON Schema: core definitions and terminology
and RFC 4627.
This is implemented by throwing an Error if the key isn't present, or is of the wrong type.
.source
The source of the connection, i.e. the stream that was piped to the connection.
.remote
Info about the other end of the connection. Includes three keys:
type
: Type of the transport (unknown
,dgram
,http
,net
)address
: Ip address of the remoteport
: The remote port
Error handling
If you reject within a middleware or a method handler, that error will be sent
back to the client. The description will be err.toString()
and the code
err.rpcCode
. If rpcCode
is undefined the code sent will be 0
.
You can also include additional data by providing err.rpcData
. rpcData
can
be of any type.
Transports
Express
const app = const raptor = appapp
Dgram
const raptor = const socket = dgram raptor;socket;
Net
const raptor = const server = net raptor;server;
Http
const raptor = const server = http raptor;server;
License
Copyright © 2014 Linus Unnebäck
Licensed under the MIT License (MIT)