iotagent-node-lib 2.24.0 → 2.26.0

package/lib/services/devices/registrationUtils.js

@@ -310,9 +310,11 @@ function sendRegistrationsNgsiLD(unregister, deviceData, callback) {
         return sendUnregistrationsNgsiLD(deviceData, callback);
     }
 
+    const operations = [];
     const properties = [];
     const lazy = deviceData.lazy || [];
     const commands = deviceData.commands || [];
+    const supportMerge = config.getConfig().server.ldSupport.merge;
 
     lazy.forEach((element) => {
         properties.push(element.name);
@@ -321,6 +323,16 @@ function sendRegistrationsNgsiLD(unregister, deviceData, callback) {
         properties.push(element.name);
     });
 
+    if (lazy.length > 0){
+        operations.push('retrieveOps');  
+    }
+    if (commands.length > 0){
+         operations.push('updateOps'); 
+    }
+    if (supportMerge){
+        operations.push('mergeEntity'); 
+    }
+
     if (properties.length === 0) {
         logger.debug(context, 'Registration with Context Provider is not needed. Device without lazy atts or commands');
         return callback(null, deviceData);
@@ -348,10 +360,18 @@ function sendRegistrationsNgsiLD(unregister, deviceData, callback) {
             information: [
                 {
                     entities: [{ type: deviceData.type, id }],
-                    properties
+                    propertyNames: properties
                 }
             ],
+            mode: 'exclusive',
+            operations,
             endpoint: config.getConfig().providerUrl,
+            contextSourceInfo: [
+                {
+                    'key': 'jsonldContext',
+                    'value': config.getConfig().contextBroker.jsonLdContext
+                }
+            ],
             '@context': config.getConfig().contextBroker.jsonLdContext
         },
         headers: {

package/lib/services/northBound/contextServer-NGSI-LD.js

@@ -31,6 +31,7 @@ const async = require('async');
 const apply = async.apply;
 const logger = require('logops');
 const errors = require('../../errors');
+const constants = require('../../constants');
 const deviceService = require('../devices/deviceService');
 const middlewares = require('../common/genericMiddleware');
 const _ = require('underscore');
@@ -41,11 +42,98 @@ const updateContextTemplateNgsiLD = require('../../templates/updateContextNgsiLD
 const notificationTemplateNgsiLD = require('../../templates/notificationTemplateNgsiLD.json');
 const contextServerUtils = require('./contextServerUtils');
 const ngsiLD = require('../ngsi/entities-NGSI-LD');
+const config = require('../../commonConfig');
 
 const overwritePaths = ['/ngsi-ld/v1/entities/:entity/attrs', '/ngsi-ld/v1/entities/:entity/attrs/:attr'];
 const updatePaths = ['/ngsi-ld/v1/entities/:entity/attrs', '/ngsi-ld/v1/entities/:entity/attrs/:attr'];
 const queryPaths = ['/ngsi-ld/v1/entities/:entity'];
 
+
+/**
+ * Replacement of NGSI-LD Null placeholders with real null values
+ *
+ */
+function replaceNGSILDNull(payload){
+    Object.keys(payload).forEach((key) =>{
+        const value = payload[key];
+        if ( value === constants.NGSI_LD_NULL){
+           payload[key] = null; 
+        } else if (typeof value === 'object' &&
+            !Array.isArray(value) &&
+            value !== null){
+            payload[key] = replaceNGSILDNull(payload[key]);
+        }
+    })
+    return  payload;
+}
+
+/**
+ * Check to see if the payload or its subattributes contain null values
+ *
+ */
+function containsNulls(payload, result){
+    Object.keys(payload).forEach((key) =>{
+        const value = payload[key];
+        if ( value === null){
+           result.nulls = true; 
+        } else if (typeof value === 'object' &&
+            !Array.isArray(value) &&
+            value !== null){
+            containsNulls(payload[key], result);
+        }
+    })
+    return  result;
+}
+
+/**
+ * An Express middleware for preprocessing NGSI-LD payloads. Converts NGSI-LD Nulls
+ * to real nulls and checks for the presence of null and datasetId
+ *
+ */
+function preprocessNGSILD(req, res, next){
+    res.locals.hasDatasetId =  false;
+    const payload = req.body
+    if (payload && typeof payload === 'object'){
+        Object.keys(payload).forEach((key) =>{
+            if (_.isArray(payload[key])){
+                payload[key].forEach((obj) => {
+                    if (obj.datasetId){
+                        res.locals.hasDatasetId = true;
+                    }
+                });
+            } else if (payload[key] && payload[key].datasetId && payload[key].datasetId !== '@none'){
+               res.locals.hasDatasetId = true;
+            } 
+        });
+        req.body = replaceNGSILDNull(payload);
+        const result = { nulls: false }
+        containsNulls(payload, result);
+        res.locals.hasNulls = result.nulls;
+    }
+    next();
+}
+
+/**
+ * A configurable Middleware that makes additional NGSI-LD checks within the payload.
+
+ *
+ * @param {Boolean} supportNull          Whether to support NGSI-LD nulls in the payload
+ * @param {Boolean} supportDatasetId     Whether to support multiattributes in the payload.
+ * @return {Object}            Express middleware used in request validation.
+ */
+function validateNGSILD(supportNull, supportDatasetId) {
+    return function validate(req, res, next) {
+        if (!supportNull && res.locals.hasNulls) {
+            next(new errors.BadRequest('NGSI-LD Null found within the payload. This IoT Agent does not support nulls for this endpoint.'));
+        } else if (!supportDatasetId && res.locals.hasDatasetId) {
+            next(new errors.BadRequest('datasetId found within the payload. This IoT Agent does not support multi-attribute requests.'));
+        } else {
+            next();
+        }
+    };
+}
+
+
 /**
  * Extract metadata attributes from input.
  *
@@ -318,6 +406,104 @@ function defaultQueryHandlerNgsiLD(id, type, service, subservice, attributes, ca
     });
 }
 
+/**
+ * Generate a merge-patch action corresponding to the request using NGSI-LD.
+ * Merge-patch is an NGSI-LD specific action.
+ *
+ * @param {Object} req                  Update request to generate Actions from
+ */
+function generateMergePatchActionNgsiLD(req, callback) {
+ 
+    const entityId = req.params.entity;
+
+       
+    function addAttributes(deviceData, body, attributes){
+        const keys = Object.keys(body);
+
+        for (const j in deviceData) {
+            if (keys.includes(deviceData[j].name)) {
+                const obj = body[deviceData[j].name]
+                if ( obj === null) {
+                    attributes.push({
+                        type: deviceData[j].type,
+                        value: null,
+                        name: deviceData[j].name
+                    });
+                } else {
+                     attributes.push({
+                        type: deviceData[j].type,
+                        value: obj.value,
+                        name: deviceData[j].name
+                    });
+                }
+            } 
+        }
+        return attributes;
+    }
+    
+
+    deviceService.getDeviceByName(
+        entityId,
+        contextServerUtils.getLDTenant(req),
+        contextServerUtils.getLDPath(req),
+        function (error, deviceObj) {
+            if (error) {
+                callback(error);
+            } else {
+                const attributes = [];
+                addAttributes(deviceObj.commands, req.body, attributes)
+                addAttributes(deviceObj.lazy, req.body, attributes)
+                const executeMergePatchHandler = apply(
+                    contextServerUtils.mergePatchHandler,
+                    entityId,
+                    deviceObj.type,
+                    contextServerUtils.getLDTenant(req),
+                    contextServerUtils.getLDPath(req),
+                    attributes
+                );
+                async.waterfall(
+                    [executeMergePatchHandler],
+                    callback()
+        );
+            }
+        }
+    );
+}
+
+/**
+ * Express middleware to manage incoming merge-patch requests using NGSI-LD.
+ *
+ * @param {Object} req              Request that was handled in first place.
+ * @param {Object} res              Response that will be sent.
+ */
+function handleMergePatchNgsiLD(req, res, next) {
+
+    function handleMergePatchRequest(error, result) {
+        if (error) {
+            logger.debug(context, 'There was an error handling the merge-patch: %s.', error);
+            next(error);
+        } else {
+            logger.debug(context, 'Merge-patch from [%s] handled successfully.', req.get('host'));
+            res.status(200).json(result);
+        }
+    }
+
+    logger.debug(context, 'Handling merge-patch from [%s]', req.get('host'));
+    if ((req.is('json') || req.is('application/ld+json')) === false) {
+        return handleMergePatchRequest(new errors.UnsupportedContentType(req.header('content-type')));
+    }
+    
+    if (req.body) {
+        logger.debug(context, JSON.stringify(req.body, null, 4));
+    }
+
+    if (contextServerUtils.mergePatchHandler){
+        generateMergePatchActionNgsiLD(req, handleMergePatchRequest);
+    } else {
+       return handleMergePatchRequest(new errors.MethodNotSupported(req.method, req.path)) 
+    }
+}
+
 /**
  * Express middleware to manage incoming query context requests using NGSI-LD.
  *
@@ -489,19 +675,21 @@ function handleQueryNgsiLD(req, res, next) {
  * @param {Object} req              Request that was handled in first place.
  * @param {Object} res              Response that will be sent.
  */
-function queryErrorHandlingNgsiLD(error, req, res, next) {
-    let code = 500;
+function ErrorHandlingNgsiLD(action) {
+    return function errorHandle(error, req, res, next) {
+        let code = 500;
 
-    logger.debug(context, 'Query NGSI-LD error [%s] handling request: %s', error.name, error.message);
+        logger.debug(context, action + ' NGSI-LD error [%s] handling request: %s', error.name, error.message);
 
-    if (error.code && String(error.code).match(/^[2345]\d\d$/)) {
-        code = error.code;
-    }
+        if (error.code && String(error.code).match(/^[2345]\d\d$/)) {
+            code = error.code;
+        }
 
-    res.status(code).json({
-        error: error.name,
-        description: error.message.replace(/[<>\"\'=;\(\)]/g, '')
-    });
+        res.status(code).json({
+            error: error.name,
+            description: error.message.replace(/[<>\"\'=;\(\)]/g, '')
+        });
+    }
 }
 
 /**
@@ -601,28 +789,6 @@ function handleNotificationNgsiLD(req, res, next) {
     }
 }
 
-/**
- * Error handler for NGSI-LD update requests.
- *
- * @param {Object} error            Incoming error
- * @param {Object} req              Request that was handled in first place.
- * @param {Object} res              Response that will be sent.
- */
-function updateErrorHandlingNgsiLD(error, req, res, next) {
-    let code = 500;
-
-    logger.debug(context, 'Update NGSI-LD error [%s] handing request: %s', error.name, error.message);
-
-    if (error.code && String(error.code).match(/^[2345]\d\d$/)) {
-        code = error.code;
-    }
-
-    res.status(code).json({
-        error: error.name,
-        description: error.message.replace(/[<>\"\'=;\(\)]/g, '')
-    });
-}
-
 /**
  * Load unsupported NGSI-LD entity routes and return proper NGSI-LD not supported responses
  *
@@ -645,36 +811,53 @@ function loadUnsupportedEndpointsNGSILD(router) {
  */
 function loadContextRoutesNGSILD(router) {
     // In a more evolved implementation, more endpoints could be added to queryPathsNgsi2
-    // according to http://fiware.github.io/specifications/ngsiv2/stable.
-
+    // according to https://www.etsi.org/standards-search#page=1&search=GS%20CIM%20009
+    
+    const support = config.getConfig().server.ldSupport;
     let i;
 
     logger.info(context, 'Loading NGSI-LD Context server routes');
+    // Update Patch endpoints - this endpoint may accept NGSI-LD Null
     for (i = 0; i < updatePaths.length; i++) {
         router.patch(updatePaths[i], [
             middlewares.ensureType,
             middlewares.validateJson(updateContextTemplateNgsiLD),
+            preprocessNGSILD,
+            validateNGSILD(support.null, support.datasetId),
             handleUpdateNgsiLD,
-            updateErrorHandlingNgsiLD
+            ErrorHandlingNgsiLD('Partial Update')
         ]);
     }
+    // Merge Patch endpoints - this endpoint may accept NGSI-LD Null
+    router.patch('/ngsi-ld/v1/entities/:entity', [
+        preprocessNGSILD,
+        validateNGSILD(support.null, support.datasetId),
+        handleMergePatchNgsiLD, 
+        ErrorHandlingNgsiLD('Merge-Patch')
+    ]);
 
+    // Overwrite/PUT endpoints - this endpoint does not accept NGSI-LD Null
     for (i = 0; i < overwritePaths.length; i++) {
         router.put(overwritePaths[i], [
             middlewares.ensureType,
             middlewares.validateJson(updateContextTemplateNgsiLD),
+            preprocessNGSILD,
+            validateNGSILD(false, support.datasetId),
             handleUpdateNgsiLD,
-            updateErrorHandlingNgsiLD
+            ErrorHandlingNgsiLD('Overwrite')
         ]);
     }
+    // Query/GET endpoints - no payload to check.
     for (i = 0; i < queryPaths.length; i++) {
-        router.get(queryPaths[i], [handleQueryNgsiLD, queryErrorHandlingNgsiLD]);
+        router.get(queryPaths[i], [handleQueryNgsiLD, ErrorHandlingNgsiLD('Query')]);
     }
     router.post('/notify', [
         middlewares.ensureType,
         middlewares.validateJson(notificationTemplateNgsiLD),
+        preprocessNGSILD,
+        validateNGSILD(false, support.datasetId),
         handleNotificationNgsiLD,
-        queryErrorHandlingNgsiLD
+        ErrorHandlingNgsiLD('Notify')
     ]);
     loadUnsupportedEndpointsNGSILD(router);
 }

package/lib/services/northBound/contextServer.js

@@ -64,7 +64,7 @@ function setUpdateHandler(newHandler) {
 }
 
 /**
- * Sets the new user handler for commadn execution requests. This handler will be called whenever an update request
+ * Sets the new user handler for command execution requests. This handler will be called whenever an update request
  * arrives to a with the following parameters: (id, type, attributes, callback). The callback is in charge of updating
  * the corresponding values in the devices with the appropriate protocol.
  *
@@ -77,6 +77,18 @@ function setCommandHandler(newHandler) {
     contextServerUtils.commandHandler = newHandler;
 }
 
+/**
+ * Sets the new user handler for NGSI-LD merge-patch requests. This handler will be called whenever an update request
+ * arrives to a with the following parameters: (id, type, attributes, callback). The callback is in charge of updating
+ * the corresponding values in the devices with the appropriate protocol.
+ *
+ *
+ * @param {Function} newHandler         User handler for update requests
+ */
+function setMergePatchHandler(newHandler) {
+    contextServerUtils.mergePatchHandler = newHandler;
+}
+
 /**
  * Sets the new user handler for Entity query requests. This handler will be called whenever an update request arrives
  * with the following parameters: (id, type, attributes, callback). The handler must retrieve all the corresponding
@@ -140,6 +152,7 @@ function clear(callback) {
 exports.clear = clear;
 exports.loadContextRoutes = intoTrans(context, loadContextRoutes);
 exports.setUpdateHandler = intoTrans(context, setUpdateHandler);
+exports.setMergePatchHandler = intoTrans(context, setMergePatchHandler);
 exports.setCommandHandler = intoTrans(context, setCommandHandler);
 exports.setNotificationHandler = intoTrans(context, setNotificationHandler);
 exports.addNotificationMiddleware = intoTrans(context, addNotificationMiddleware);

package/lib/services/northBound/northboundServer.js

@@ -110,6 +110,7 @@ function clear(callback) {
     async.series([deviceProvisioning.clear, groupProvisioning.clear, contextServer.clear], callback);
 }
 
+exports.setMergePatchHandler = intoTrans(context, contextServer.setMergePatchHandler);
 exports.setUpdateHandler = intoTrans(context, contextServer.setUpdateHandler);
 exports.setQueryHandler = intoTrans(context, contextServer.setQueryHandler);
 exports.setCommandHandler = intoTrans(context, contextServer.setCommandHandler);

package/lib/services/northBound/restUtils.js

@@ -53,11 +53,9 @@ function checkMandatoryQueryParams(mandatoryAttributes, body, callback) {
     for (const p in mandatoryAttributes) {
         let found = false;
 
-        for (const i in body) {
-            if (body.hasOwnProperty(i)) {
-                if (i === mandatoryAttributes[p]) {
-                    found = true;
-                }
+        if (body.hasOwnProperty(mandatoryAttributes[p])) {
+            if (body[mandatoryAttributes[p]] !== '' && body[mandatoryAttributes[p]] !== null) {
+                found = true;
             }
         }
 

package/lib/templates/deviceGroup.json

@@ -24,7 +24,7 @@
             "description": "token",
             "type": "string"
           },
-          "cbroker": {
+          "cbHost": {
             "description": "uri for the context broker",
             "type": "string"
           },

package/package.json

@@ -2,7 +2,7 @@
   "name": "iotagent-node-lib",
   "license": "AGPL-3.0-only",
   "description": "IoT Agent library to interface with NGSI Context Broker",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "homepage": "https://github.com/telefonicaid/iotagent-node-lib",
   "keywords": [
     "fiware",
@@ -23,7 +23,7 @@
   },
   "main": "lib/fiware-iotagent-lib",
   "engines": {
-    "node": ">=12"
+    "node": ">=14"
   },
   "scripts": {
     "clean": "rm -rf package-lock.json && rm -rf node_modules && rm -rf coverage",

package/test/unit/examples/deviceProvisioningRequests/provisionNewDeviceEmpty.json

@@ -0,0 +1,43 @@
+{
+  "devices": [
+    {
+      "device_id": "",
+      "protocol": "GENERIC_PROTO",
+      "entity_name": "TheFirstLight",
+      "entity_type": "TheLightType",
+      "timezone": "America/Santiago",
+      "endpoint": "http://fakedEndpoint:1234",
+      "transport": "MQTT",
+      "attributes": [
+        {
+          "name": "attr_name",
+          "type": "string"
+        }
+      ],
+      "lazy": [
+        {
+          "name": "luminance",
+          "type": "lumens"
+        }
+      ],
+      "static_attributes": [
+        {
+          "name": "hardcodedAttr",
+          "type": "hardcodedType",
+          "value": "hardcodedValue"
+        }
+      ],
+      "commands": [
+        {
+          "name": "commandAttr",
+          "type": "commandType"
+        }
+      ],
+      "internal_attributes": [
+        {
+          "customField": "customValue"
+        }
+      ]
+    }
+  ]
+}

package/test/unit/examples/mongoCollections/configurations.json

@@ -2,7 +2,7 @@
   {
     "apikey" : "7e5721f478220be21f41f4700e50be2",
     "token" : "e50b7781d5e2d39d577e7c15e4a21f470ed39d5777e7c15e2e2d39d5777e7c1e2",
-    "cbroker" : "http://10.0.0.2:1026",
+    "cbHost" : "http://10.0.0.2:1026",
     "entity_type" : "device",
     "resource" : "/iot/d",
     "service" : "smart_gondor",
@@ -10,7 +10,7 @@
   },
   {
     "apikey" : "gdb13gq3f8q4beuk263besr8eh9ri",
-    "cbroker" : "http://10.0.0.2:1026",
+    "cbHost" : "http://10.0.0.2:1026",
     "entity_type" : "device",
     "resource" : "/iot/d",
     "service" : "dumb_mordor",
@@ -25,7 +25,7 @@
   },
   {
     "apikey" : "hs4h2ke7oerfdvrexbyh54w2",
-    "cbroker" : "http://10.0.0.2:1026",
+    "cbHost" : "http://10.0.0.2:1026",
     "entity_type" : "device",
     "resource" : "/iot/d",
     "service" : "demo",

package/test/unit/expressions/jexlExpression-test.js

@@ -234,6 +234,26 @@ describe('Jexl expression interpreter', function () {
         });
     });
 
+    describe('When an concatarr function is used with an array', function () {
+        it('should work on the expression value', function (done) {
+            expressionParser.parse('array|concatarr(array)', scope, function (error, result) {
+                should.not.exist(error);
+                result.should.deepEqual([1, 2, 1, 2]);
+                done();
+            });
+        });
+    });
+
+    describe('When an joinarrtostr function is used with an array', function () {
+        it('should work on the expression value', function (done) {
+            expressionParser.parse('array|joinarrtostr("_")', scope, function (error, result) {
+                should.not.exist(error);
+                result.should.equal('1_2');
+                done();
+            });
+        });
+    });
+
     describe('When a function is applied to an array', function () {
         it('should work on the expression value', function (done) {
             expressionParser.parse('array[1]+1', scope, function (error, result) {
@@ -313,14 +333,15 @@ describe('Jexl expression interpreter', function () {
 
     describe('When a JSON parse transformation is applied', function () {
         it('should work on the expression value', function (done) {
-            expressionParser.parse('"{\\"name\\":\\"John\\",\\"surname\\":\\"Doe\\"}"|jsonparse', scope, function (
-                error,
-                result
-            ) {
-                should.not.exist(error);
-                result.should.eql(scope.object);
-                done();
-            });
+            expressionParser.parse(
+                '"{\\"name\\":\\"John\\",\\"surname\\":\\"Doe\\"}"|jsonparse',
+                scope,
+                function (error, result) {
+                    should.not.exist(error);
+                    result.should.eql(scope.object);
+                    done();
+                }
+            );
         });
     });