dl-rpc-server v0.1.0

dl-rpc-server

JSON-RPC Middleware for cloud applications that makes your life easier.

Table of contents

• Features
• Example
• Usage
  • Manifest file
  • Routing
    • Default
    • Custom
  • Error handling
    • Default
    • Custom
  • APIs
  • Server handler
  • Exporting

Features

• simple to use as middleware
• custom routings
• custom error handling

Example

If you want to use the dl-rpc-server in the simple version, all you need to do is:

• create express application
• use middleware

const express = require('express');
const rpc = require('dl-rpc-server');

var app = express();
app.use(rpc.server(app));

module.exports = {
    Server: rpc.handler(app)
}

If you want to see full example, checkout example application

Usage

Manifest file

If you want to run your application in the Dreamlab Cloud, you have to create a manifest file called app.yaml for your application. It should looks like following:

handler: lib/Server.js#Server
appname: ApplicationName
servicename: myservice
sdk_version: node_6.3.0.1
version: 1.0
interfaces:
  someifc:
    authentication: false
    authorisation: false
    ssl: false

• handler entry point to your application
• appname name of application in the Dreamlab Cloud Panel
• servicename OPAL service name that application belongs to
• sdk_version version of node sdk
• version version of application
• interfaces routing structure

Routing

Default

As default, dl-rpc-server router reads methods from lib/interfaces directory. You have to meet folowing requirements:

• lib/interfaces directory created, it contains interfaces
• an interface is represented by subdirectory in the lib/interfaces
• a method is a file containing class in some interface's directory
• a method has fixed filename format: methodnameMethod.js
• a method contains class/function that gets params and callback as an input
• a method calls input callback (standard format: callback(error,success)) with an error ({code: xxx, message: xxx}) or success

Custom

It's possible to pass your own router that returns map of available methods. To do this, you have to extend ./lib/routers/AbstractRouter.js class. Your implementation should contain class with a load method that returns map of methods in following format:

{ 
      "interface:method" : [Function]
}

For example:

{
    "ro.get": function (callback) {
        callback (null, "ok")
    },
    "ro.callSomeApi": class {
        constructor (callback) {
            callback(null, "ok")
        }  
    }
}

If you have your class, pass it as router option to a middleware:

app.use(rpc.server(app, {
    router: myCustomClass
});

Error handling

You already know how to response with error and certain error code, but what if there is a bug in your code and your application hangs because of broken code? Good news is that you do not have to do nothing, just use middleware.

Default

When your code breaks, default express error handling procedure is executed: it sends error with http 400 to a client. It's problematic if client is an application that communicates via json-rpc protocol.

If you want to receive pretty formated, rfc-compatible response, just use our middleware:

app.use(rpc.errors);

It sends a response in format compatible with JSON-RPC RFC

Custom

TODO

APIs

To call external APIs in your application, just use dl-opal-client library

Server handler

dl-rpc-server exports following modules:

• server - it's json-rpc server that knows how to handle requests
• errors - default way to deal with unexpected errors
• handler - handler of native server that is used by external software, for example by node-server. It has a listen method, so you can run it without export for debugging purposes.

Exporting

As you know, your app.yaml manifest file contains handler property. Your server class have to export handler provided by dl-rpc-server module to make it available for software that runs your application in the Dreamlab Cloud.

Example export:

module.exports = {
    Server: rpc.handler(app)
}