Overview

This is a JSON-RPC protocol implementation in NodeJS that follows JSON-RPC 2.0 specs. The good and also bad thing about this library is that it enforces method handler modules to have a certain convention/design pattern. However, it allows the server to automatically extract documentation from the handler (Introspection). This library is still under development.

Features

• Handles GET/POST requests
• Better error feedback
• Allows method namespacing (Module.method)
• Allows exposure of all methods inside a module
• Authentication can be achieved by giving a preHandle function
• Introspection (in progress)

Installation

The usual npm install njrpc or if you prefer, you can grab the source/fork it and make changes yourself.

Usage

Handlers that can be registered with njrpc should have a name attribute in the instance. A sample handler can be found in handler.js.

The best design pattern to use with this server is the Module design pattern.

njrpc.register(modules)

Registers an array of modules/a single module, which should have name as the namespace of the module.

njrpc.addCustomPath(url, handlerFn)

Add handlerFn to a custom path, for example '/version' can return the version number as plain text instead of a JSON request. handlerFn will have 2 arguments:

• req: Request object
• res: Response object to write to

njrpc.output(res, [jsonResponse])

Actually write the JSON response out to the pipe. This can also be overridden to write something else.

njrpc.handle(req, res, [preHandleFn])

Handles a request & response, JSON-RPC style. preHandleFn is used to manipulate the JSON request before it gets pushed down to the Handler level. preHandleFn takes a single JSON request object as the argument (after parsing and whitelisting)

Examples

Simple EchoHandler that echoes whatever it receives

var EchoHandler = function () {
        return {
            name : 'EchoHandler',
            echo : function (str) {
                return str;
            }
        };
    },
    jrpcServer = require('./njrpc'),
    http = require('http');

jrpcServer.registerModule(new EchoHandler());
http.createServer(function(req, res) {
    jrpcServer.handle(req, res);	
}).listen(8080);

Authenticated Echo Handler that still echoes, but needs a user & token

var AuthenticatedEchoHandler = function () {
        return {
            name : 'AuthenticatedEchoHandler',
            echo : function(context, str) {
                if (!context.user || !context.token) {
                    throw new Error("This call is unauthenticated");
                }
                return str;
            }
        };
    },
    preHandler = function (jsonReq) {
        if (jsonReq.headers) {
            if (Array.isArray(jsonReq.params)) {
                jsonReq.params.unshift(jsonReq.headers);
            } else {
                jsonReq.params.context = jsonReq.headers;
            }
        }
    },
    jrpcServer = require('./njrpc'),
    http = require('http');

jrpcServer.registerModule(new AuthenticatedEchoHandler());
http.createServer(function(req, res) {
    jrpcServer.handle(req, res, preHandler);	
}).listen(8080);