iotagent-node-lib 3.3.0 → 3.4.0

package/doc/{northboundinteractions.md → devel/northboundinteractions.md}

@@ -145,7 +145,7 @@ This **NGSI-v2** payload is associated to an update operation (POST `/v2/op/upda
             }
         }
     ],
-    "actionType": "update"
+    "actionType": "append"
 }
 ```
 
@@ -155,9 +155,8 @@ As it can be seen in the example, the payload is a JSON Object with the followin
     with the information needed to identify the target entity `id` and `type` attributes. The `entities` attribute is an
     array, so a single update context batch operation can be used to update multiple devices
 
--   An `actionType` indicating the type of update: if this attribute has the value `"append"` the appropriate entity and
-    attributes will be created if the don't exist; if the value is `"update"`, an error will be thrown if the target
-    resources don't exist.
+-   An `actionType` indicating the type of update. It has the value `"append"` the appropriate entity and attributes
+    will be created if the don't exist.
 
 The equivalent **NGSI-LD** payload is associated to an update operation (PATCH `/ngsi-ld/v1/entities/<entity>/attrs/`).
 
@@ -427,7 +426,7 @@ Be sure to understand how each scenario works (as shown in the theory section) b
 Along this document, IP addresses and passwords will be concealed. Substitute the concealed passwords by your own.
 
 A postman collection is available alongside this document to help in reproducing this examples. It can be found
-[here](./doc/NorthboundInteractions.postman_collection).
+[here](NorthboundInteractions.postman_collection).
 
 ### Retrieving a token
 
@@ -507,8 +506,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "actionType": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "actionType": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 If the request is correct, the Context Broker will reply with the following R1 response (200 OK):
@@ -554,7 +553,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "attrs": ["temperature","pressure"]
-}' "https://<platform-ip>:10027/v2/op/query"
+}' "https://<platform-ip>:1026/v2/op/query"
 ```
 
 The Context Broker will reply with the updated data values in R2 format (200 OK):
@@ -600,20 +599,6 @@ It is worth mentioning that the Context Broker will reply with a 200 OK status c
 refer to transport protocol level errors, while the status codes inside of a payload give information about the
 application level protocol.
 
-The example shows an error updating an non-existent attribute (due to the use of UPDATE instead of APPEND).
-
-The following error payload is also valid in standard NGSI:
-
-```json
-{
-    "error": "NotFound",
-    "description": "The requested entity has not been found. Check type and id"
-}
-```
-
-Different kinds of errors can return their information in different formats, so NGSI implementations should check for
-the existence of both.
-
 ### Scenario 2: lazy attributes (happy path)
 
 Scenario 2 relies on the Context Provider mechanism of the Context Broker. For this scenario to work, the IoTAgent must
@@ -639,7 +624,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     }
 }
-' "https://<platform-ip>:10027/v2/registrations"
+' "https://<platform-ip>:1026/v2/registrations"
 ```
 
 If everything has gone OK, the Context Broker will return the following payload:
@@ -669,7 +654,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "attrs": ["batteryLevel"]
-}' "https://<platform-ip>:10027/v2/op/query"
+}' "https://<platform-ip>:1026/v2/op/query"
 ```
 
 The Context Broker receives this request and detects that it can be served by a Context Provider (the IoT Agent), so it
@@ -772,7 +757,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         }
     ],
     "duration": "P1M"
-}' "https://<platform-ip>:10027/v2/registrations"
+}' "https://<platform-ip>:1026/v2/registrations"
 ```
 
 If everything has gone OK, the Context Broker will return the following payload:
@@ -806,8 +791,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "updateAction": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "updateAction": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 The Context Broker receives this command and detects that it can be served by a Context Provider (the IoT Agent), so it
@@ -836,7 +821,7 @@ Fiware-Correlator: 9cae9496-8ec7-11e6-80fc-fa163e734aab
       }
     }
   ],
-  "updateAction" : "update"
+  "updateAction" : "append"
 }
 ```
 
@@ -900,8 +885,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "actionType": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "actionType": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 This update does not modify the original command attribute, but two auxiliary attributes, that are not provided by the
@@ -948,7 +933,7 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
         "switch_info",
         "switch_status"
     ]
-}' "https://<platform-ip>:10027/v2/op/query"
+}' "https://<platform-ip>:1026/v2/op/query"
 ```
 
 The Context Broker replies with all the desired data, in R2 format (200 OK):
@@ -994,8 +979,8 @@ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -
             }
         }
     ],
-    "actionType": "update"
-} ' "https://<platform-ip>:10027/v2/op/update"
+    "actionType": "append"
+} ' "https://<platform-ip>:1026/v2/op/update"
 ```
 
 In this case, the Context Broker reply with the following response (200 OK):

package/doc/index.md

@@ -11,8 +11,8 @@ Broker using their own native protocols. IoT Agents should also be able to deal
 platform (authentication and authorization of the channel) and provide other common services to the device programmer.
 
 Github's [README.md](https://github.com/telefonicaid/iotagent-node-lib/blob/master/README.md) provides a good
-documentation summary. The [User Manual](usermanual.md) and the [Admin Guide](installationguide.md) cover more advanced
-topics.
+documentation summary. The [API reference](doc/api.md) and the [Development documentation](devel/development.md) cover
+more advanced topics.
 
 ## Background
 
@@ -26,8 +26,6 @@ functions.
     communications are left to the library.
 -   Standardized OAuth2-based security is available to enable each IoT Agent to connect to several common Identity
     Managers (e.g. Keystone and Keyrock) so that communications can be restricted to trusted components.
--   A series of additional plugins are offered where necessary to allow for expression parsing, attribute aliasing and
-    the processing of timestamp metadata.
 
 Each individual IoT Agent offers is driven by a `config.js` configuration file contains explicit custom settings based
 on the protocol and payload the IoT Agent is translating. It will also contain some common flags for common
@@ -51,5 +49,5 @@ IoT Agent
 In order to use the library within your own IoT Agent, you must first you require it before use:
 
 ```javascript
-const iotagentLib = require("iotagent-node-lib");
+const iotagentLib = require('iotagent-node-lib');
 ```

package/docker/Mosquitto/README.md

@@ -2,6 +2,7 @@ Thi directory containts the Dockerfile (and associated files) for a container of
 This container is provide as a help for users to test with MQTT, but it is just an auxiliary material in this repository.
 
 The following releases matches with eclipse-mosquitto version:
+- 2.1.0 uses mosquitto-2.0.11 from Debian 12
 - 2.0.0 uses mosquitto-2.0.11 from Debian 11
 - 1.6.0 uses mosquitto-1.6.10-1.el7.x86_64 (from Centos7)
 - 1.5.0 uses mosquitto-1.6.10-1.el7.x86_64 (from Centos7)

package/lib/commonConfig.js

@@ -149,7 +149,6 @@ function processEnvironmentVariables() {
         'IOTA_MONGO_USER',
         'IOTA_MONGO_RETRY_TIME',
         'IOTA_SINGLE_MODE',
-        'IOTA_APPEND_MODE',
         'IOTA_POLLING_EXPIRATION',
         'IOTA_POLLING_DAEMON_FREQ',
         'IOTA_MULTI_CORE',
@@ -450,10 +449,6 @@ function processEnvironmentVariables() {
         config.singleConfigurationMode = process.env.IOTA_SINGLE_MODE === 'true';
     }
 
-    if (process.env.IOTA_APPEND_MODE) {
-        config.appendMode = process.env.IOTA_APPEND_MODE === 'true';
-    }
-
     if (process.env.IOTA_POLLING_EXPIRATION) {
         config.pollingExpiration = process.env.IOTA_POLLING_EXPIRATION;
     }

package/lib/fiware-iotagent-lib.js

@@ -302,6 +302,7 @@ exports.update = ngsi.update;
 exports.setCommandResult = ngsi.setCommandResult;
 exports.listDevices = deviceService.listDevices;
 exports.getDevice = deviceService.getDevice;
+exports.updateDevice = deviceService.updateDevice;
 exports.getDeviceSilently = deviceService.getDeviceSilently;
 exports.getDeviceByName = deviceService.getDeviceByName;
 exports.getDeviceByNameAndType = deviceService.getDeviceByNameAndType;
@@ -349,7 +350,6 @@ exports.middlewares = middlewares;
 
 exports.dataPlugins = {
     expressionTransformation: require('./plugins/expressionPlugin'),
-    bidirectionalData: require('./plugins/bidirectionalData'),
     utils: require('./plugins/pluginUtils')
 };
 

package/lib/jexlTranformsMap.js

@@ -79,7 +79,8 @@ const map = {
     // https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString
     localestring: (d, timezone, options) => new Date(d).toLocaleString(timezone, options),
     now: () => Date.now(),
-    hextostring: (val) => new TextDecoder().decode(new Uint8Array(val.match(/.{1,2}/g).map(byte => parseInt(byte, 16))))
+    hextostring: (val) =>
+        new TextDecoder().decode(new Uint8Array(val.match(/.{1,2}/g).map((byte) => parseInt(byte, 16))))
 };
 
 exports.map = map;

package/lib/request-shim.js

@@ -59,7 +59,7 @@ function getOptions(options) {
     // got library is not properly documented, so it is not clear which takes precedence
     // among body, json and form (see https://stackoverflow.com/q/70754880/1485926).
     // Thus, we are enforcing our own precedence with the "else if" chain below.
-    // Behaviour is consistent with the one described at usermanual.md#iotagentlibrequest
+    // Behaviour is consistent with the one described at development.md#iotagentlibrequest
 
     if (options.method === 'GET' || options.method === 'HEAD' || options.method === 'OPTIONS') {
         // Do nothing - Never add a body
@@ -70,7 +70,7 @@ function getOptions(options) {
         // json takes precedence over form
         httpOptions.json = options.json;
     } else if (options.form) {
-        // Note that we don't consider 'form' part of the function API (check usermanual.md#iotagentlibrequest)
+        // Note that we don't consider 'form' part of the function API (check development.md#iotagentlibrequest)
         // but we are preparing the code anyway as a safe measure
         httpOptions.form = options.form;
     }

package/lib/services/commands/commandService.js

@@ -120,7 +120,7 @@ function markAsExpired(command) {
 
     async.waterfall(
         [
-            apply(deviceService.getDevice, command.deviceId, command.service, command.subservice),
+            apply(deviceService.getDevice, command.deviceId, null, command.service, command.subservice),
             getGroup,
             calculateTypeInformation,
             updateExpiredCommand

package/lib/services/common/genericMiddleware.js

@@ -56,7 +56,7 @@ function handleError(error, req, res, next) {
  *  Express middleware for tracing the complete request arriving to the IoTA in debug mode.
  */
 function traceRequest(req, res, next) {
-    logger.debug(context, 'Request for path [%s] from [%s]', req.path, req.get('host'));
+    logger.debug(context, 'Request for path [%s] query [%j] from [%s]', req.path, req.query, req.get('host'));
 
     if (req.is('json') || req.is('application/ld+json')) {
         logger.debug(context, 'Body:\n\n%s\n\n', JSON.stringify(req.body, null, 4));

package/lib/services/devices/deviceRegistryMemory.js

@@ -71,7 +71,7 @@ function storeDevice(newDevice, callback) {
  * @param {String} service      Service of the device to remove.
  * @param {String} subservice   Subservice inside the service for the removed device.
  */
-function removeDevice(id, service, subservice, callback) {
+function removeDevice(id, apikey, service, subservice, callback) {
     const services = Object.keys(registeredDevices);
 
     for (let i = 0; i < services.length; i++) {
@@ -141,7 +141,7 @@ function listDevices(type, service, subservice, limit, offset, callback) {
     });
 }
 
-function getDevice(id, service, subservice, callback) {
+function getDevice(id, apikey, service, subservice, callback) {
     if (registeredDevices[service] && registeredDevices[service][id]) {
         callback(null, registeredDevices[service][id]);
     } else {

package/lib/services/devices/deviceRegistryMongoDB.js

@@ -119,13 +119,15 @@ function storeDevice(newDevice, callback) {
  * @param {String} service      Service of the device to remove.
  * @param {String} subservice   Subservice inside the service for the removed device.
  */
-function removeDevice(id, service, subservice, callback) {
+function removeDevice(id, apikey, service, subservice, callback) {
     const condition = {
         id,
         service,
         subservice
     };
-
+    if (apikey) {
+        condition.apikey = apikey;
+    }
     logger.debug(context, 'Removing device with id [%s]', id);
 
     Device.model.deleteOne(condition, function (error) {
@@ -211,17 +213,21 @@ function findOneInMongoDB(queryParams, id, callback) {
  * Internal function used to find a device in the DB.
  *
  * @param {String} id           ID of the Device to find.
+ * @param {String} Apikey       Apikey of the Device to find.
  * @param {String} service      Service the device belongs to (optional).
  * @param {String} subservice   Division inside the service (optional).
  */
-function getDeviceById(id, service, subservice, callback) {
-    const queryParams = {
+function getDeviceById(id, apikey, service, subservice, callback) {
+    let queryParams = {
         id,
         service,
         subservice
     };
+    if (apikey) {
+        queryParams.apikey = apikey;
+    }
     context = fillService(context, queryParams);
-    logger.debug(context, 'Looking for device with id [%s].', id);
+    logger.debug(context, 'Looking for device with id [%s] and queryParams [%j].', id, queryParams);
     findOneInMongoDB(queryParams, id, callback);
 }
 
@@ -232,10 +238,17 @@ function getDeviceById(id, service, subservice, callback) {
  * @param {String} service      Service the device belongs to.
  * @param {String} subservice   Division inside the service.
  */
-function getDevice(id, service, subservice, callback) {
-    getDeviceById(id, service, subservice, function (error, data) {
+function getDevice(id, apikey, service, subservice, callback) {
+    getDeviceById(id, apikey, service, subservice, function (error, data) {
         if (error) {
-            callback(error);
+            // Try without apikey: apikey will be added to device later
+            getDeviceById(id, null, service, subservice, function (error, data) {
+                if (error) {
+                    callback(error);
+                } else {
+                    callback(null, data);
+                }
+            });
         } else {
             callback(null, data);
         }
@@ -284,7 +297,7 @@ function getByName(name, service, servicepath, callback) {
  */
 function update(device, callback) {
     logger.debug(context, 'Storing updated values for device [%s]:\n%s', device.id, JSON.stringify(device, null, 4));
-    getDeviceById(device.id, device.service, device.subservice, function (error, data) {
+    getDevice(device.id, device.apikey, device.service, device.subservice, function (error, data) {
         if (error) {
             callback(error);
         } else {

package/lib/services/devices/deviceService.js

@@ -64,22 +64,6 @@ function init() {
     }
 }
 
-/**
- * Creates the initial entity representing the device in the Context Broker. This is important mainly to allow the
- * rest of the updateContext operations to be performed using an UPDATE action instead of an APPEND one.
- *
- * @param {Object} deviceData       Object containing all the deviceData needed to send the registration.
- * @param {Object} newDevice        Device object that will be stored in the database.
- */
-function createInitialEntity(deviceData, newDevice, callback) {
-    if (config.getConfig().appendMode === false || config.ngsiVersion() === 'ld' || deviceData.ngsiVersion === 'ld') {
-        deviceHandler.createInitialEntity(deviceData, newDevice, callback);
-    } else {
-        logger.debug(context, 'Skip create initial entity due appendMode is false or ngsiLD.');
-        callback(null, newDevice);
-    }
-}
-
 /**
  * If the object_id or the name of the attribute is missing, complete it with the other piece of data.
  *
@@ -253,6 +237,7 @@ function registerDevice(deviceObj, callback) {
     function checkDuplicates(deviceObj, innerCb) {
         config.getRegistry().getSilently(
             deviceObj.id,
+            deviceObj.apikey,
             deviceObj.service,
             deviceObj.subservice,
             /* eslint-disable-next-line no-unused-vars */
@@ -354,8 +339,7 @@ function registerDevice(deviceObj, callback) {
         async.waterfall(
             [
                 apply(registrationUtils.sendRegistrations, false, deviceData),
-                apply(registrationUtils.processContextRegistration, deviceData),
-                apply(createInitialEntity, deviceData)
+                apply(registrationUtils.processContextRegistration, deviceData)
             ],
             function (error, results) {
                 if (error) {
@@ -419,7 +403,7 @@ function removeAllSubscriptions(device, callback) {
  * @param {String} service      Service of the device to unregister.
  * @param {String} subservice   Subservice inside the service for the unregisterd device.
  */
-function unregisterDevice(id, service, subservice, callback) {
+function unregisterDevice(id, apikey, service, subservice, callback) {
     function processContextUnregister(body, innerCallback) {
         innerCallback(null);
     }
@@ -428,9 +412,9 @@ function unregisterDevice(id, service, subservice, callback) {
         innerCallback(null);
     }
 
-    logger.debug(context, 'Removing device register in Device Service');
+    logger.debug(context, 'Removing device %j %j %j %j register in Device Service', id, apikey, service, subservice);
 
-    config.getRegistry().get(id, service, subservice, function (error, device) {
+    config.getRegistry().get(id, apikey, service, subservice, function (error, device) {
         if (error) {
             callback(error);
         } else {
@@ -454,7 +438,7 @@ function unregisterDevice(id, service, subservice, callback) {
                                 processUnsubscribes,
                                 apply(registrationUtils.sendRegistrations, true, mergedDevice),
                                 processContextUnregister,
-                                apply(config.getRegistry().remove, id, service, subservice)
+                                apply(config.getRegistry().remove, id, apikey, service, subservice)
                             ],
                             callback
                         );
@@ -529,8 +513,17 @@ function listDevices(service, subservice, limit, offset, callback) {
  * @param {String} service          Service for which the requested device.
  * @param {String} subservice       Subservice inside the service for which the device is requested.
  */
-function getDevice(deviceId, service, subservice, callback) {
-    config.getRegistry().get(deviceId, service, subservice, callback);
+function getDevice(deviceId, apikey, service, subservice, callback) {
+    config.getRegistry().get(deviceId, apikey, service, subservice, callback);
+}
+
+/**
+ * Update a device from the device registry.
+ *
+ * @param {String} device           JSON object contain the device to update.
+ */
+function updateDevice(device, callback) {
+    config.getRegistry().update(device, callback);
 }
 
 /**
@@ -540,8 +533,8 @@ function getDevice(deviceId, service, subservice, callback) {
  * @param {String} service          Service for which the requested device.
  * @param {String} subservice       Subservice inside the service for which the device is requested.
  */
-function getDeviceSilently(deviceId, service, subservice, callback) {
-    config.getRegistry().getSilently(deviceId, service, subservice, callback);
+function getDeviceSilently(deviceId, apikey, service, subservice, callback) {
+    config.getRegistry().getSilently(deviceId, apikey, service, subservice, callback);
 }
 
 /**
@@ -608,10 +601,22 @@ function checkRegistry(fn) {
     };
 }
 
-function findOrCreate(deviceId, group, callback) {
-    getDeviceSilently(deviceId, group.service, group.subservice, function (error, device) {
+function findOrCreate(deviceId, apikey, group, callback) {
+    getDeviceSilently(deviceId, apikey, group.service, group.subservice, function (error, device) {
         if (!error && device) {
-            callback(null, device, group);
+            if (
+                (!('apikey' in device) || device.apikey === undefined) &&
+                'apikey' in group &&
+                group.apikey !== undefined
+            ) {
+                logger.info(context, 'Update provisioned device %j with measure/group apikey %j', device, group.apikey);
+                device.apikey = group.apikey; // group apikey is the same of current measure apikey
+                updateDevice(device, function (error) {
+                    callback(error, device, group);
+                });
+            } else {
+                callback(null, device, group);
+            }
         } else if (error.name === 'DEVICE_NOT_FOUND') {
             const newDevice = {
                 id: deviceId,
@@ -678,7 +683,7 @@ function retrieveDevice(deviceId, apiKey, callback) {
         async.waterfall(
             [
                 apply(groupService.get, config.getConfig().defaultResource || '', apiKey),
-                apply(findOrCreate, deviceId),
+                apply(findOrCreate, deviceId, apiKey),
                 apply(
                     mergeDeviceWithConfiguration,
                     ['lazy', 'active', 'staticAttributes', 'commands', 'subscriptions'],
@@ -693,6 +698,7 @@ function retrieveDevice(deviceId, apiKey, callback) {
 exports.listDevices = intoTrans(context, checkRegistry)(listDevices);
 exports.listDevicesWithType = intoTrans(context, checkRegistry)(listDevicesWithType);
 exports.getDevice = intoTrans(context, checkRegistry)(getDevice);
+exports.updateDevice = intoTrans(context, checkRegistry)(updateDevice);
 exports.getDeviceSilently = intoTrans(context, checkRegistry)(getDeviceSilently);
 exports.getDevicesByAttribute = intoTrans(context, checkRegistry)(getDevicesByAttribute);
 exports.getDeviceByName = intoTrans(context, checkRegistry)(getDeviceByName);

package/lib/services/devices/devices-NGSI-LD.js

@@ -369,7 +369,13 @@ function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
     if (entityInfoUpdated) {
         async.waterfall(
             [
-                apply(config.getRegistry().get, deviceObj.id, deviceObj.service, deviceObj.subservice),
+                apply(
+                    config.getRegistry().get,
+                    deviceObj.id,
+                    deviceObj.apikey,
+                    deviceObj.service,
+                    deviceObj.subservice
+                ),
                 apply(extractDeviceDifference, deviceObj),
                 createInitialEntityNgsiLD,
                 apply(combineWithNewDevice, deviceObj),
@@ -382,7 +388,13 @@ function updateRegisterDeviceNgsiLD(deviceObj, entityInfoUpdated, callback) {
     } else {
         async.waterfall(
             [
-                apply(config.getRegistry().get, deviceObj.id, deviceObj.service, deviceObj.subservice),
+                apply(
+                    config.getRegistry().get,
+                    deviceObj.id,
+                    deviceObj.apikey,
+                    deviceObj.service,
+                    deviceObj.subservice
+                ),
                 apply(extractDeviceDifference, deviceObj),
                 updateEntityNgsiLD,
                 apply(combineWithNewDevice, deviceObj),

package/lib/services/devices/devices-NGSI-mixed.js

@@ -37,8 +37,6 @@ const deviceHandlerV2 = require('./devices-NGSI-v2');
 function createInitialEntityNgsiMixed(deviceData, newDevice, callback) {
     if (config.checkNgsiLD(deviceData)) {
         deviceHandlerLD.createInitialEntity(deviceData, newDevice, callback);
-    } else {
-        deviceHandlerV2.createInitialEntity(deviceData, newDevice, callback);
     }
 }