rpclib
v0.4.1
Published
Library that simplifies building an JSON-RPC endpoint
Downloads
13
Readme
rpclib
A simple library for building a JSON-RPC 2.0 compliant endpoint using Node.js.
Usage
var RPCLib = require('rpclib');
RPCLib Methods
rpc = new RPCLib()
Creates a new RPC library instance. Should be done at application start up.
rpc.addMethod(name, handler[, params][, flags])
rpc.addMethod(name, options)
Adds a new handler for method name
. options
should be an object that has
handler
, params
, and flags
, as keys. handler
is a callback that is
called with (params, response, httpRequest) when a new request is made for this
method name. params
is the params object sent from the client. response
is
an instance of RPCResponse
. httpRequest
, if this call originated from an
http request, will be an instance of http.IncomingMessage
.
params
should be a hash like this example:
{
email: {type: 'string', optional: false},
password: {type: 'string', optional: false},
name: {type: 'string', optional: false},
phone: {type: 'number', optional: true}
}
flags
are completely optional and will be passed to your pre-processor(s).
If params
is null
(rather than an object or undefined) then the parameters
object sent to the handler
will be an empty object, guaranteed. Normally the
passed object is validated but passed through as originally sent. This could
cause issues if you're expecting an empty object since your method accepts no
parameters but the caller sent extraneous parameters.
rpc.removeMethod(name)
Removes the handler for method name
.
rpc.setPreProcessor(func)
Sets the pre-processor, which is called before the handler but after the request is
validated. The func
is sent (requestObject, response, methodFlags, httpRequest).
requestObject
is the request object sent from the client. response
is an
instance of RPCResponse
. methodFlags
are the flags that were defined with
the method. httpRequest
, if this call originated from an http request, will be
an instance of http.IncomingMessage
.
rpc.handleRequest(requestBody, serverResponse, httpRequest)
Handles a request from a client. requestBody
should the body of the request made and
serverResponse
should be an instance of http.ServerResponse
. httpRequest
should be an instance of http.IncomingMessage
if this call orginated from an
http request.
rpc.call(method[, params][, callback][, httpRequest])
rpc.call(method, callback[, httpRequest])
Calls a method added by addMethod
and sends along the passed params. callback
is
called with result
, which is the full JSON object (containing a result
or error
key) that would've been sent in response to an HTTP request. If this was called
in response to a HTTP request, it should be passed as httpRequest
so methods can
get IP and other information from that request.
rpc.setConfigValue(key, value)
Sets an arbitrary configuration key
to value
that can be retrieved later. This
can be used to set variables in your startup code that later need to be accessed
by methods code without making global variables or something like that.
rpc.getConfigValue(key)
Returns the configuration value for key
that was previously set with
setConfigValue
.
RPCResponse Methods
resp.resolve(result)
Resolves a request with the passed result
.
resp.reject(errorCode[, errorMessage][, errorData])
Rejects a request and responds with an error object containing the passed code, message, and data.
resp.set(name, value)
Set arbitrary data on the response for later use in a post-processor, pre-processor or handler.
resp.get(name)
Get arbitrary data that was previously stored with set
.
Predefined Errors
RPCLib.ERROR_PARSE_ERROR
RPCLib.ERROR_INVALID_REQUEST
RPCLib.ERROR_INVALID_METHOD
RPCLib.ERROR_INVALID_PARAMS
RPCLib.ERROR_INTERNAL_ERROR
RPCLib.ERROR_SERVER_ERROR
RPCClient Methods
Usage
var RPCClient = require('rpclib').RPCClient;
client = new RPCClient([endpoint])
Creates a new RPC client instance. endpoint
should be a url.
client.setEndpoint(endpoint)
endpoint
should be a url.
client.call(name[, params][, callback])
client.call(name[, callback])
Call an RPC method named name
with params
. callback
will be called with
(err, result)
. Returns an instance of RPCClientResult
.
RPCClientResult Methods
RPCClientResult
has then
and catch
methods and behaves like a promise.
Additionally...
res.setTimeout(ms)
timeout the call after ms
milliseconds. The callback passed to call
will
get passed an error with a type
of timeout
after the timeout has passed and
catch
functions will be called.
res.clientURL
Read-only property to get the URL that the request is going to. Useful for logging.