Fiqare perseo-fe improvements

CHANGES_NEXT_RELEASE

@@ -0,0 +1,2 @@
+- Add: /api-docs endpoint providing swagger-based documentation of the HTTP endpoints exposed by Perseo FE
+- Hardening: software quality improvement based on ISO25010 recommendations

documentation/development.md

@@ -108,3 +108,31 @@ To ensure consistent Markdown formatting run the following:
 # Use git-bash on Windows
 npm run prettier:text
 ```
+
+## User & Programmers Manual
+
+### Swagger
+
+In order to run Swagger, you need to execute the Perseo FE (as explained [here](deployment.md) and then you can access
+to: <server_host>:9090/api-docs
+
+The swagger documentation provided at /api-docs covers all the HTTP endpoint exposed by Perseo FE.
+
+#### Instalation
+
+To run Swagger in Perseo we have to install two NPM packages for NodeJs:
+
+-   Swagger-jsdoc: allows us to document our application's endpoints with notations.
+-   Swagger-ui-express: generates an interface with endpoints definitions. We have to specify our swagger's version, our
+    API's information and the route where we can find the endpoints in the project.
+    <pre><code>
+     definition: {
+                    swagger: '2.0', // Specification (optional, defaults to swagger: '2.0')
+                    info: {
+                        title: 'Perseo Front-End', // Title (required)
+                        version: '1.7.0-fiqare' // Version (required)
+                    }
+                },
+    </code></pre>
+    Once the project is deployed (port 9090 by default), we can access to the interface by the following link:
+    <http://localhost:9090/api-docs>.

documentation/plain_rules.md

@@ -19,7 +19,9 @@
 
 There are two kind of rules:
 
-* Esper-based rules, which include the final EPL statement used by the Esper engine inside perseo-core. In order to work with perseo (front-end) properly, the EPL statement must fulfill several conventions for the rule to be able to operate on the incoming events and trigger adequate actions. Example:
+-   Esper-based rules, which include the final EPL statement used by the Esper engine inside perseo-core. In order to
+    work with perseo (front-end) properly, the EPL statement must fulfill several conventions for the rule to be able to
+    operate on the incoming events and trigger adequate actions. Example:
 
 ```json
 {
@@ -40,9 +42,8 @@ There are two kind of rules:
 }
 ```
 
-* No signal rules. They are triggered when a given attribute is not updated in a given interval of time. They
-don't use Esper at persero-core (they are checked and triggered by perseo frontend). Example:
-
+-   No signal rules. They are triggered when a given attribute is not updated in a given interval of time. They don't
+    use Esper at persero-core (they are checked and triggered by perseo frontend). Example:
 
 ```json
 {
@@ -127,15 +128,16 @@ information on how to scape characters at
 
 ## No signal conditions
 
-The no signal condition is specified in the `nosignal` configuration element, which is an object with the following fields:
+The no signal condition is specified in the `nosignal` configuration element, which is an object with the following
+fields:
 
 -   **checkInterval**: _mandatory_, time in minutes for checking the attribute
 -   **attribute**: _mandatory_, attribute for watch
 -   **reportInterval**: _mandatory_, time in seconds to see an entity as silent
 -   **id** or **idRegexp**: _mandatory_ (but not both at the same time), id or regex of the entity to watch
 -   type: _optional_, type of entities to watch
 
-Is recommended to set checkInterval at least double of reportInterval. Howeer, note that a very demanding value of 
+Is recommended to set checkInterval at least double of reportInterval. Howeer, note that a very demanding value of
 checkInterval could impact on performance.
 
 <a name="actions"></a>

lib/alarm.js

@@ -30,6 +30,7 @@ var util = require('util'),
 function raise(alarm, context, message) {
     var state = alarms[alarm];
     context = (process.domain && process.domain.context) || {};
+
     if (typeof message === 'object' && message) {
         message = util.format('%j', message);
     }
@@ -43,6 +44,7 @@ function raise(alarm, context, message) {
 function release(alarm, context, message) {
     var state = alarms[alarm];
     context = (process.domain && process.domain.context) || {};
+
     if (typeof message === 'object' && message) {
         message = util.format('%j', message);
     }

lib/models/actions.js

@@ -81,6 +81,9 @@ function validateAction(axn) {
                 return new errors.IdAsAttribute(JSON.stringify(axnElem.parameters));
             } else if (axnElem.parameters.name === 'type') {
                 return new errors.IdAsAttribute(JSON.stringify(axnElem.parameters));
+            } else {
+                //Added default else clause
+                return null;
             }
         }
     }
@@ -227,6 +230,7 @@ function DoAction(event, callback) {
 
     actionStore.Find(service, subservice, ruleName, function(err, actions) {
         var localError, queue;
+
         if (err) {
             return callback(err, null);
         }

lib/models/actionsStore.js

@@ -40,8 +40,10 @@ module.exports = {
                 localError = new errors.NotFoundAction(data);
                 myutils.logErrorIf(localError);
                 return callback(localError, null);
+            } else {
+                //Added default else clause
+                return callback(null, data.action);
             }
-            return callback(null, data.action);
         });
     }
 };

lib/models/emailAction.js

@@ -25,13 +25,12 @@
 var util = require('util'),
     nodemailer = require('nodemailer'),
     logger = require('logops'),
-    smtpTransport = require('nodemailer-smtp-transport'),
     config = require('../../config'),
     myutils = require('../myutils'),
     alarm = require('../alarm'),
     metrics = require('./metrics');
 
-var transporter = nodemailer.createTransport(smtpTransport(config.smtp));
+var transporter = nodemailer.createTransport(config.smtp);
 
 function buildMailOptions(action, event) {
     return {

lib/models/entitiesStore.js

@@ -52,6 +52,9 @@ function findSilentEntities(service, subservice, ruleData, func, callback) {
         } catch (e) {
             return callback(e, null);
         }
+    } else {
+        //Added default else clause
+        logger.debug('findSilentEntities() - Default else clause');
     }
     if (ruleData.type) {
         criterion['_id.type'] = ruleData.type;

lib/models/paths.js

@@ -38,6 +38,10 @@ function validComponent(component) {
     } else if (!componentPattern.test(component)) {
         err = new errors.InvalidCharacter(component);
     }
+    else {
+    	//Added default else clause
+    	return err;
+    }
     return err;
 }
 function validService(service) {

lib/models/postAction.js

@@ -39,6 +39,10 @@ function buildPostOptions(action, event) {
     } else if (action.template) {
         options.text = myutils.expandVar(action.template, event, true);
     }
+    else {
+    	//Added default else clause
+    	return options;
+    }
 
     return options;
 }
@@ -58,6 +62,10 @@ function doIt(action, event, callback) {
         } else if (options.text) {
             requestOptions.body = options.text;
         }
+        else {
+            //Added default else clause
+            logger.debug('doIt() - Default else clause');	
+        }
 
         metrics.IncMetrics(event.service, event.subservice, metrics.actionHttpPost);
 

lib/models/rules.js

@@ -31,6 +31,7 @@ var util = require('util'),
     myutils = require('../myutils'),
     noSignal = require('./noSignal'),
     actions = require('./actions'),
+    logger = require('logops'),
     namePattern = /^[a-zA-Z0-9_-]+$/,
     MaxNameLength = 50,
     errors = {};
@@ -58,6 +59,9 @@ function validRule(rule) {
         return new errors.InvalidRuleName(rule.name);
     } else if (!rule.text && !rule.nosignal) {
         return new errors.EmptyRule(JSON.stringify(rule));
+    } else {
+        //Added default else clause
+        logger.debug('validRule() - Default else clause');
     }
     if (rule.nosignal) {
         //Specific checks for no-signal rules
@@ -218,6 +222,7 @@ module.exports = {
     },
     Save: function(rule, callback) {
         var localError;
+
         localError = validRule(rule);
         if (localError !== null) {
             myutils.logErrorIf(localError);
@@ -244,7 +249,12 @@ module.exports = {
                 rulesStore.Save.bind(null, rule),
                 function(cb) {
                     if (rule.nosignal) {
-                        noSignal.AddNSRule(rule.service, rule.subservice, rule.name, rule.nosignal);
+                        noSignal.AddNSRule(
+                            rule.service,
+                            rule.subservice,
+                            rule.name,
+                            rule.nosignal
+                        );
                     }
                     cb(null);
                 }
@@ -294,14 +304,23 @@ module.exports = {
                 delR2core.bind(null, rule),
                 function(cb) {
                     if (rule.nosignal) {
-                        noSignal.DeleteNSRule(rule.service, rule.subservice, rule.name);
+                        noSignal.DeleteNSRule(
+                            rule.service,
+                            rule.subservice,
+                            rule.name
+                        );
                     }
                     cb(null);
                 },
                 postR2core.bind(null, rule),
                 function(cb) {
                     if (rule.nosignal) {
-                        noSignal.AddNSRule(rule.service, rule.subservice, rule.name, rule.nosignal);
+                        noSignal.AddNSRule(
+                            rule.service,
+                            rule.subservice,
+                            rule.name,
+                            rule.nosignal
+                        );
                     }
                     cb(null);
                 },

lib/models/updateAction.js

@@ -266,6 +266,8 @@ function processOptionParams(action, event) {
                 case 'None':
                     theValue = null;
                     break;
+                default:
+                //Nothing to do
             }
         }
         var key = myutils.expandVar(attr.name, event);

lib/models/visualRules.js

@@ -35,7 +35,8 @@ var util = require('util'),
         MINOR_OR_EQUAL_THAN: ' <= ',
         MATCH: ' regexp '
     },
-    errors = {};
+    errors = {},
+    logger = require('logops');
 
 function errorOperator(op) {
     if (operatorMap[op] === undefined) {
@@ -118,7 +119,6 @@ function vr2rule(cardRule) {
                                     false
                                 )
                             );
-
                             break;
                         case 'XPATH':
                             errOp = errorOperator(card.conditionList[0].operator);
@@ -143,18 +143,27 @@ function vr2rule(cardRule) {
                                 }
                             } else if (card.conditionList[0].parameterName === 'type') {
                                 type = card.conditionList[0].parameterValue;
+                            } else {
+                                //Added default else clause
+                                logger.debug('vr2rule() - Default else clause');
                             }
                             break;
                         case 'OBSERVATION':
                             errOp = errorOperator(card.conditionList[0].operator);
+
                             if (errOp) {
                                 return errOp;
                             }
+
                             if (card.sensorData.measureName === 'id') {
                                 return new errors.IdAsAttribute('');
                             } else if (card.sensorData.measureName === 'type') {
                                 return new errors.TypeAsAttribute('');
+                            } else {
+                                //Added default else clause
+                                logger.debug('vr2rule() - Default else clause');
                             }
+
                             conditions.push(
                                 makeObservationCondition(
                                     card.sensorData.measureName,
@@ -163,6 +172,7 @@ function vr2rule(cardRule) {
                                     card.sensorData.dataType === 'Quantity'
                                 )
                             );
+
                             break;
                         case 'LAST_MEASURE':
                             checkInterval = parseInt(card.timeData.interval, 10);
@@ -225,10 +235,15 @@ function vr2rule(cardRule) {
                             case 'timeElapsed': // Minimal interval for actions
                                 action.interval = card.timeData.interval;
                                 break;
+                            default:
+                            //nothing to do
                         }
                     } else {
                         return new errors.MissingConfigDataInTimeCard(JSON.stringify(card));
                     }
+                    break;
+                default:
+                //nothing to do
             }
         }
 

lib/myutils.js

@@ -88,6 +88,9 @@ function expandObject(templateObj, dictionary) {
                 res[expandVar(key, dictionary)] = expandVar(templateObj[key], dictionary);
             } else if (typeof templateObj[key] === 'object') {
                 res[expandVar(key, dictionary)] = expandObject(templateObj[key], dictionary);
+            } else {
+                //Added default else clause
+                logger.debug('expandObject() - Default else clause');
             }
         });
     }

lib/perseo.js

@@ -48,7 +48,10 @@ var domain = require('domain'),
     serviceMiddleware = require('./middleware/service'),
     errorMiddleware = require('./middleware/error'),
     myutils = require('./myutils'),
-    d = domain.create();
+    d = domain.create(),
+    swaggerJsdoc = require('swagger-jsdoc'),
+    swaggerUi = require('swagger-ui-express'),
+    pjson = require('../package.json');
 
 function start(callbackStart) {
     var context = { op: 'start', comp: constants.COMPONENT_NAME };
@@ -98,6 +101,22 @@ function start(callbackStart) {
         versionRoutes.AddTo(app);
         metricsRoutes.AddTo(app);
 
+        const options = {
+            definition: {
+                swagger: '2.0', // Specification (optional, defaults to swagger: '2.0')
+                info: {
+                    title: pjson.name, // Title (required)
+                    version: pjson.version // Version (required)
+                }
+            },
+            // Path to the API docs
+            apis: ['./lib/routes/*.js']
+        };
+
+        const specs = swaggerJsdoc(options);
+
+        app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
+
         async.series(
             [
                 function(callback) {