cirruswave

cirruswave

Comprehensive framework for cloud based REST enabled microservices development

The cirruswave is a platform that enables development, testing and deployment of microservices in the enterprise.

Customize web services to your enterprise needs by specifying easy to read configuration files.

• npm enabled microservices platform
• Declarative routes for REST API
• Optional JSON Schema based validation of url params, query params, request body and response
• Optional accesskey based security with built in validation of keys
• KeyMgr service to help with issuing developer accesskey and secret key.
• Automatic documentation of the services
• Test framework to enable easy testing of the microservices

cirruswave package does REST for you.

Installation instructions

Getting Started

Usage instructions

System Services

Auto Documentation for Micro-Services

Frequently asked questions

Schematized Micro-Services

License

Installation

npm install cirruswave

Getting Started

The package cirruswave is used to create webservices with configuration files and business logic specific to your needs.

The configurations files allow you to specify service instance, the paramters and their validation along with the security options.

To run a sample webservice, you would need

• a service configuration file ( example: appserviceconfig.json )

• an app configuration file ( example: appconfig.json )

• a custom business logic for each route you expose ( example: sampleservice.js )

• your primary file ( example: index.js )

• in addition to this cirruswave comes with some default certificates if you want to specify a secure way to publish your webservice. These certifcates should be replaced by your organizations certificates if you want to deploy these webservices for external use.

• The package allows your services to be tested at:

http[s]://localhost:[port]/test

The testing framework can be customized to your enterprise needs (logo, look and feel with configuration changes)

• The package allows your services to be documented for use at:

http[s]://localhost:[port]/Documentation

Usage

• Application Service Config

• Application Config

• Sample Service Implementation

• Code to start the sample service

• Run the sample service

Create appserviceconfig.json which contains the sampleservice configuration information

{
  "services": 
  {
    "sampleservice": {
      "protocol": "http",
      "port": 8888,
      "hostname": "localhost",
      "description": "REST END POINT For Sample Service.",
      "configfilepath": "./appconfig.json",
      "security": "nokey"
    }
  }
}

Create appconfig.json to declare the routes.

Each route configuration section has a name, route url path, description, examples, param and body schema sections etc. Most importantly it contains the type which tells what method is supported. Method values supported are 'get', 'post', 'put', 'delete', and 'static'. All methods except 'static' conform to the standard http methods and follow REST API guidelines.

The 'static' method in particular is used to server static files like css, html, client-side javascript files, images etc. The 'routeclass' in this case describes the path to the location of static files. The 'routefunction' 'paramschema', 'bodyschema', 'responseschema' are ignored for this type.

Below is a sample configuration file with a route with 'get', 'post', and 'static' methods. This configuration file could include paramschema, bodyschema and responseschema

{
    "servicename": "sampleservice",
    "routes": [
        {
          "route": "/sampleservice/images",
          "type": "static",
          "configured": true,
          "routeclass": "../examples/images",
          "description": "app specific images are served from the directory ../examples/images under route /sampleservice/images"
        },
        {
        "route": "/sampleservice/something/:value1/:value2",
        "type": "get",
        "configured": true,
        "routeclass": "./sampleservice.js",
        "routefunction": "RouteGetSomething",
        "description": "Hello world",
        "examples": [
          {
            "param": "/sampleservice/something/foo/100"
          }
        ],
        "paramschema": {
          "type": "object",
          "required": [
            "value1",
            "value2"
          ],
          "properties": {
            "value1": {
              "description": "value1 is string e.g. foo",
              "type": "string"
            },
            "value2": {
              "description": "value2 is number e.g. 100",
              "type": "integer"
            }
          }
        }
      },
      
      {
        "route": "/sampleservice/something/:value1/:value2",
        "type": "post",
        "configured": true,
        "routeclass": "./sampleservice.js",
        "routefunction": "RoutePostSomething",
        "description": "Hello world",
        "examples": [
            {
            "param": "/sampleservice/something/foo/100",
            "payload":{
              "value3":{"value5":"bar"},
              "value4":"blah"
            }
          }
        ],
        "paramschema": {
          "type": "object",
          "required": [
            "value1",
            "value2"
          ],
          "properties": {
            "value1": {
              "description": "value1 is string e.g. foo",
              "type": "string"
            },
            "value2": {
              "description": "value2 is number e.g. 100",
              "type": "integer"
            }
          }
        },
        "bodyschema": {
          "type": "object",
          "required": [
            "value3",
            "value4"
          ],
          "properties": {
            "value3": {
              "description": "value3 is an object e.g. {'value5':'bar'}",
              "type": "object",
              "required":[
              "value5" 
              ],
              "properties":{
                "value5":{
                  "description":"value5 is a string inside the value3 object e.g. bar",
                  "type":"string"
                }
              }
            },
            "value4": {
              "description": "value4 is string e.g. blah",
              "type": "string"
            }
          }
        }
      }
    ]
  
}

Create a file sampleservice.js that implements this route.

exports.RouteGetSomething = function(req,res)
{
    res.status(200).json({"value":"hello world"});
}
exports.RoutePostSomething = function(req,res)
{
    res.status(200).json({"params=":req.params,"body":req.body});
}

Create a file index.js to initialized and start cirruswave

var app = require('cirruswave');
app.startservice("sampleservice", __dirname, "./appserviceconfig.json");

Now execute the service

node index.js

You can then access this sampleservice in your browser

http://localhost:8888/sampleservice/something/foo/100 

will return

{"value":"hello world"}

In addition a POST route will be enabled

http://localhost:8888/sampleservice/something/foo/100 that takes a post with body json like this:
{
  "value3":{"value5":"bar"},
  "value4":"blah"
}

System services

Key Manager(keymgr) is one of the services that's shipped by default with the wave platform. Key Manager service provides routes for generating access and secret keys, provision access to various services which have security set as "acckey"

To see the full documentation on system services, please run the keymgr service.

To run the system services, copy the code below into a file called systemservicesindex.js

const app = require('cirruswave');
const initoptions={
 "aclconfig":"aclconfig.json",
 "secret":"helloworld",
 "appserviceconfig":"appserviceconfig.json",
 "appdir":__dirname
}

app.startsystemservice("keymgr",initoptions);

after this run the systemservice by invoking

node systemservicesindex.js

Note that the keys are stored encrypted in the file pointed to by aclconfigpath (in this case it's ./aclconfig.json).

FAQ

• Installation and Setup
• General questions
• Support

Installation and Setup --

How do I install cirruswave package

npm install cirruswave

Can you point me to some detailed instructions to get me started 

<a href=https://www.npmjs.com/package/cirruswave>README.md file can get you on to your first project

Which operating systems do you support

Current version is tested on MacOS, Ubuntu 18.04 and Windows 10, but we work with any operating systems that support Node.js

General questions --

What are the prerequisites to use cirruswave

cirruswave is a microservices platform for NodeJS. If your code is written in javascript for NodeJS and you want to develop webservices expose REST API in a robust and secure manner, you should use cirruswave.

I am ready. Where is CirrusWave available?

CirrusWave is available as a machine image(AMI) in AWS mrketplace. You can get more information on CirrusWave AMI

I read all the information, I am ready to develop, and test robust microservices, connect to multiple datasources and deploy them to containers in secure and sclable manner. How do I get started?

Goto AWS console , Launch ec2 instance, choose AWS Marketplace, search for cirruswave, select CirrusWave-Enterprise, ssh to the machine

I launched an ec2 instance using CirrusWave-Enterprise image. How can create my first microservice

ssh to the cirruswave machine instance, cirruswave will give you the help. Also see CirrusWae Documentation to get started

Support --

Where can I get support for the product

Please select the support icon on this web page and submit your ticket

Microservice Documentation

Detailed documentation for each app services started on localhost is available at the localhost: port# can be any of the app services started.

https://localhost:8888/documentation has documentation available for all app services. https://localhost:8888/services will listout each service https://localhost:8888/service/sampleservice will list each route for the sample service with detailed documentation

You can also use https://localhost:8888/test to get a form where you can test your sample service.

Documentation for the system services like keymgr are available at any port of a running system service. "keymgr" service uses port 4003 and https://localhost:4003/documentation has the documentation for the system services.

Schematized Micro-Services

json-schema is an IETF standard for defining json payloads. cirrus-wire uses json schema in defining various objects. All usage of schema is optional and is used to validate the routes, responses etc. Use of json-schema is encouraged as it makes the code more robust and also serves as documentation.

The following are some of the places where json-schema is expected to be provided by the developer of micro-services:

• Request parameter schmea
• Request body schema
• Response schema
• initilization option schema

Example of json-schema

Example use of Request schmeas are in the sampleservice in examples directory. keymgr system service uses init options schema Full json-schema sepcification can be found at https://json-schema.org/ Examples can be found at https://json-schema.org/learn/getting-started-step-by-step.html

License

MIT Licensed. Copyright (c) CirrusWave Inc. 2019