node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »



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


node exampleServer.js


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



function example() {

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


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


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.


// 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: '',
    port: 8080

// Sharded environment
config = {
    location: 'shard',
    // Parameter by which the call is sharded
    shardBy: 'operand1',
    shard: {
                location: 'local'
                location: 'remote',
                hostname: '',
                port: 8080
                location: 'remote',
                hostname: '',
                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 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.



  • 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