noderpc

This is a framework for building distributed services with NodeJS very easily. All you need is

• a CommonJS module that exports a single constructor function
• a very simple service descriptions
• a few lines to expose that object as a service reachable via http
• a few more lines to address that object from JS or PHP (so far)
• this library

Demo

node exampleServer.js

Features

A service can be transparently called

• locally
• remotely
• remotely sharded

Service definition

A service needs

• a local module to bind to
• a service description that defines methods and parameters
• services + desription are looked at in any directory called "service" in the require pathes

Example:

service/example.js

function example() {

    this.add = function(operand1, operand2) {
        return operand1 + operand2;
    }

}

module.exports = function() {
    return new example();
}

service/example_description.js

module.exports = {
    name: 'example',
    methods: {
        'add': {
            params: [
                {name: 'operand1', type: 'number'},
                {name: 'operand2', type: 'number'}
            ],
            description: 'Adds two numbers'
        }
    }
};

Accessing services

Service-Proxies are created with require('noderpc').createProxy(serviceName, config) The config says, where the service is located.

Example:

// Local invocation
config = {
    location: 'local',
    implementation: 'myservice' // Optional property, if the servicename differs from the requirename
    // E.g. servicename is example but the implementation is
    // 'example' but the require is 'service/myservice'
    // Servicedescription still is serviceName + '_description.js'
}

// Remote invocation
config = {
    location: 'remote',
    hostname: '127.0.0.1',
    port: 8080
}

// Sharded environment
config = {
    location: 'shard',
    // Parameter by which the call is sharded
    shardBy: 'operand1',
    shard: {
        [
            {
                location: 'local'
            },
            {
                location: 'remote',
                hostname: '127.0.0.1',
                port: 8080
            },
            {
                location: 'remote',
                hostname: '127.0.0.1',
                port: 8081
            }
        ]
    }
}

Exposing Services

Its simply a few lines.

• Create a proxy service
• Create server
• Bind proxy to server

The server exposes its own API on the route /api. In /public is a simple demo page, that uses the self exposing API to create HTML forms that represent the exposed services.

See exampleServer.js

Access services via PHP

Execute bindings/php/generateApi.php to create stub classes that access the API.

See bindings/php/example.php

Sharding

Sharding works by creating many proxy objects (remote or local) and defining a parameter name by which the call is sharded. Currently for sharding string and numerical parameters can be used.

API

Main

• createServer(connect): Creates a RPC server. Requires a connect object
• createProxy(): Convenience function to factory.createProxy()
• factory: Reference to proxy factory

Server invoked by createServer()

• start(port, [hostname]) : starts server on port and binds optional to an IP Adres
• stop() : stops server
• bindService(proxy): serves a proxy service. See above for service description
• unbindService(serviceName): Unbinds a service
• setLogger(log4js, level, format): Uses log4js for logging and uses "level" as loglevel. A connect.logger format can be specified

Proxy Factory

• createProxy(serviceName, config): See above for detailed description
• getLocalService(serviceName): Returns the local object for that service, returns undefined if not set
• removeLocalService(serviceName): Deletes object from factory registry
• getProxy(serviceName): Returns proxy object for serviceName, returns undefined if not set
• removeProxy(serviceName): Deletes proxy object from factory registry