kuzzle-device-manager 0.4.8 → 0.4.9

package/lib/core-classes/BatchProcessing/BatchWriter.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchWriter = exports.BatchBuffer = void 0;
+const BatchController_1 = require("./BatchController");
+const InstrumentablePromise_1 = require("./InstrumentablePromise");
+class BatchBuffer {
+    constructor() {
+        this.indexes = {};
+    }
+    /**
+     * Add a document to the buffer of a specific collection
+     *
+     * @param index Index name
+     * @param collection Collection name
+     * @param body Document content
+     * @param _id Document ID
+     * @param options Option object passed to the m* action
+     *
+     * @returns An object containing the index of the array of results and a promise resolving to the array of results
+     */
+    add(index, collection, body, _id = undefined, options) {
+        if (!this.indexes[index]) {
+            this.indexes[index] = {};
+        }
+        if (!this.indexes[index][collection]) {
+            this.indexes[index][collection] = {
+                documents: [],
+                promise: new InstrumentablePromise_1.InstrumentablePromise(),
+                options,
+            };
+        }
+        const idx = this.indexes[index][collection].documents.length;
+        this.indexes[index][collection].options = { ...this.indexes[index][collection].options, ...options };
+        this.indexes[index][collection].documents.push({
+            _id,
+            body
+        });
+        return {
+            idx,
+            promise: this.indexes[index][collection].promise,
+        };
+    }
+}
+exports.BatchBuffer = BatchBuffer;
+/**
+ * This class handle buffers for every supported API action of the document controller:
+ *  - create, update, createOrReplace, replace, get, exists, delete
+ *
+ * Each buffer is filled with documents to be write/get/delete into a collection.
+ *
+ * A timer will regularly execute the m* actions with the documents inside the buffers.
+ *
+ * If the interval is too big, buffers may contain too much documents for Kuzzle limits.
+ * (e.g. "limits.documentsWriteCount" is 200 by default)
+ */
+class BatchWriter {
+    /**
+     * @param sdk Connected SDK
+     * @param options.interval Timer interval in ms (50). Actions will be executed every {interval} ms
+     * @param options.maxWriteBufferSize Max write buffer size (200). (Should match "limits.documentsWriteCount")
+     * @param options.maxReadBufferSize Max read buffer size. (Should match "limits.documentsReadCount")
+     */
+    constructor(sdk, { interval = 50, maxWriteBufferSize = 200, maxReadBufferSize = 200 } = {}) {
+        // Buffers
+        this.buffers = {
+            create: new BatchBuffer(),
+            update: new BatchBuffer(),
+            get: new BatchBuffer(),
+            exists: new BatchBuffer(),
+            delete: new BatchBuffer(),
+            replace: new BatchBuffer(),
+            createOrReplace: new BatchBuffer(),
+        };
+        this.sdk = sdk;
+        this.interval = interval;
+        this.maxWriteBufferSize = maxWriteBufferSize;
+        this.maxReadBufferSize = maxReadBufferSize;
+        this.document = new BatchController_1.BatchController(this.sdk, this);
+    }
+    get addCreate() {
+        // @todo implements the send of buffer if approaching the limit
+        return this.buffers.create.add.bind(this.buffers.create);
+    }
+    get addUpdate() {
+        return this.buffers.update.add.bind(this.buffers.update);
+    }
+    get addGet() {
+        return this.buffers.get.add.bind(this.buffers.get);
+    }
+    get addExists() {
+        return this.buffers.exists.add.bind(this.buffers.exists);
+    }
+    get addDelete() {
+        return this.buffers.delete.add.bind(this.buffers.delete);
+    }
+    get addReplace() {
+        return this.buffers.replace.add.bind(this.buffers.replace);
+    }
+    get addCreateOrReplace() {
+        return this.buffers.createOrReplace.add.bind(this.buffers.createOrReplace);
+    }
+    /**
+     * Execute API actions with documents stored in the buffers.
+     */
+    async execute() {
+        const buffers = {};
+        // make a copy of the buffers
+        for (const [name, buffer] of Object.entries(this.buffers)) {
+            buffers[name] = buffer;
+        }
+        // prepare to enqueue documents in buffers
+        this.prepareRound();
+        await Promise.all([
+            this.sendCreateBuffer(buffers.create),
+            this.sendUpdateBuffer(buffers.update),
+            this.sendCreateOrReplaceBuffer(buffers.createOrReplace),
+            this.sendDeleteBuffer(buffers.delete),
+            this.sendExistsBuffer(buffers.exists),
+            this.sendGetBuffer(buffers.get),
+            this.sendReplaceBuffer(buffers.replace),
+        ]);
+    }
+    /**
+     * Initialize the buffers and start the timer
+     */
+    begin() {
+        this.prepareRound();
+        this.timer = setInterval(async () => {
+            await this.execute();
+        }, this.interval);
+    }
+    /**
+     * Execute pending actions from the buffers and stop the timer.
+     */
+    async end() {
+        await this.execute();
+        clearInterval(this.timer);
+    }
+    /**
+     * Reset all the buffers
+     */
+    prepareRound() {
+        for (const name of Object.keys(this.buffers)) {
+            this.buffers[name] = new BatchBuffer();
+        }
+    }
+    async sendCreateBuffer(buffer, options) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                promises.push(this.sdk.document.mCreate(index, collection, documents, { ...options, strict: true })
+                    .then(promise.resolve)
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+    async sendUpdateBuffer(buffer, options) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                promises.push(this.sdk.document.mUpdate(index, collection, documents, { ...options })
+                    .then(promise.resolve)
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+    async sendReplaceBuffer(buffer, options) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                promises.push(this.sdk.document.mReplace(index, collection, documents, { ...options })
+                    .then(promise.resolve)
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+    async sendCreateOrReplaceBuffer(buffer, options) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                promises.push(this.sdk.document.mCreateOrReplace(index, collection, documents, { ...options })
+                    .then(promise.resolve)
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+    async sendGetBuffer(buffer) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                const ids = documents.map(({ _id }) => _id);
+                promises.push(this.sdk.document.mGet(index, collection, ids)
+                    .then(promise.resolve)
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+    async sendExistsBuffer(buffer) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                const ids = documents.map(({ _id }) => _id);
+                promises.push(this.sdk.document.mGet(index, collection, ids)
+                    .then(({ successes }) => {
+                    const successesId = successes.map(({ _id }) => _id);
+                    const exists = new Array(ids.length);
+                    for (let i = 0; i < exists.length; i++) {
+                        exists[i] = successesId.includes(ids[i]);
+                    }
+                    promise.resolve({ successes: exists });
+                })
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+    async sendDeleteBuffer(buffer) {
+        const promises = [];
+        for (const [index, collectionBuffer] of Object.entries(buffer.indexes)) {
+            for (const [collection, { promise, documents }] of Object.entries(collectionBuffer)) {
+                if (documents.length === 0) {
+                    promise.resolve();
+                    continue;
+                }
+                const ids = documents.map(({ _id }) => _id);
+                promises.push(this.sdk.document.mDelete(index, collection, ids)
+                    .then(promise.resolve)
+                    .catch(promise.reject));
+            }
+        }
+        await Promise.all(promises);
+    }
+}
+exports.BatchWriter = BatchWriter;
+//# sourceMappingURL=BatchWriter.js.map

package/lib/core-classes/BatchProcessing/InstrumentablePromise.d.ts

@@ -0,0 +1,6 @@
+export declare class InstrumentablePromise {
+    promise: Promise<any>;
+    resolve: (...any: any[]) => any;
+    reject: (...any: any[]) => any;
+    constructor();
+}

package/lib/core-classes/BatchProcessing/InstrumentablePromise.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstrumentablePromise = void 0;
+class InstrumentablePromise {
+    constructor() {
+        this.promise = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+}
+exports.InstrumentablePromise = InstrumentablePromise;
+//# sourceMappingURL=InstrumentablePromise.js.map

package/lib/core-classes/BatchProcessing/index.d.ts

@@ -0,0 +1,3 @@
+export * from './BatchController';
+export * from './BatchWriter';
+export * from './InstrumentablePromise';

package/lib/core-classes/BatchProcessing/index.js

@@ -0,0 +1,16 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./BatchController"), exports);
+__exportStar(require("./BatchWriter"), exports);
+__exportStar(require("./InstrumentablePromise"), exports);
+//# sourceMappingURL=index.js.map

package/lib/core-classes/CustomMappings/AssetMappingsManager.d.ts

@@ -0,0 +1,31 @@
+import { JSONObject } from 'kuzzle';
+import { DeviceMappingsManager } from './DeviceMappingsManager';
+export declare class AssetMappingsManager {
+    private baseMappings;
+    private deviceMappings;
+    private assetByName;
+    private assetByGroup;
+    constructor(baseMappings: JSONObject, deviceMappings: DeviceMappingsManager);
+    /**
+     * Register an asset type with custom metadata.
+     *
+     * If a "group" is provided, this asset type metadata will only be injected when
+     * creating an engine of the same group.
+     *
+     * @param name Asset type name
+     * @param metadata Asset type custom metadata
+     * @param options.group Only inject this asset type to engine of this group
+     *
+     * @example
+     *
+     * plugin.assets.register('container', {
+     *   size: { type: 'integer' },
+     *   serial: { type: 'keyword' },
+     * });
+     *
+     */
+    register(name: string, metadata: JSONObject, { group }?: {
+        group?: string;
+    }): void;
+    get(group?: string): JSONObject;
+}

package/lib/core-classes/CustomMappings/AssetMappingsManager.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetMappingsManager = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const kuzzle_1 = require("kuzzle");
+class AssetMappingsManager {
+    constructor(baseMappings, deviceMappings) {
+        this.assetByName = new Map();
+        this.assetByGroup = new Map();
+        this.baseMappings = baseMappings;
+        this.deviceMappings = deviceMappings;
+        this.assetByGroup.set('commons', []);
+    }
+    /**
+     * Register an asset type with custom metadata.
+     *
+     * If a "group" is provided, this asset type metadata will only be injected when
+     * creating an engine of the same group.
+     *
+     * @param name Asset type name
+     * @param metadata Asset type custom metadata
+     * @param options.group Only inject this asset type to engine of this group
+     *
+     * @example
+     *
+     * plugin.assets.register('container', {
+     *   size: { type: 'integer' },
+     *   serial: { type: 'keyword' },
+     * });
+     *
+     */
+    register(name, metadata, { group = 'commons' } = {}) {
+        if (this.assetByName.has(name)) {
+            throw new kuzzle_1.PluginImplementationError(`Asset of type "${name}" has already been registered.`);
+        }
+        const definition = {
+            name,
+            group,
+            metadata,
+        };
+        this.assetByName.set(name, definition);
+        if (!this.assetByGroup.has(group)) {
+            this.assetByGroup.set(group, []);
+        }
+        this.assetByGroup.get(group).push(definition);
+    }
+    get(group = 'commons') {
+        const mappings = JSON.parse(JSON.stringify(this.baseMappings));
+        const deviceMappings = this.deviceMappings.get();
+        mappings.properties.measures.dynamic = 'false';
+        for (const [name, measure] of Object.entries(deviceMappings.properties.measures.properties)) {
+            mappings.properties.measures.properties[name] = {
+                properties: {
+                    id: { type: 'keyword' },
+                    model: { type: 'keyword' },
+                    reference: { type: 'keyword' },
+                    qos: deviceMappings.properties.qos,
+                    ...measure.properties,
+                }
+            };
+        }
+        if (this.assetByGroup.has('commons')) {
+            for (const definition of this.assetByGroup.get('commons')) {
+                mappings.properties.metadata.properties = lodash_1.default.merge({}, mappings.properties.metadata.properties, definition.metadata);
+            }
+        }
+        if (group !== 'commons' && this.assetByGroup.has(group)) {
+            for (const definition of this.assetByGroup.get(group)) {
+                mappings.properties.metadata.properties = lodash_1.default.merge({}, mappings.properties.metadata.properties, definition.metadata);
+            }
+        }
+        return mappings;
+    }
+}
+exports.AssetMappingsManager = AssetMappingsManager;
+//# sourceMappingURL=AssetMappingsManager.js.map

package/lib/core-classes/CustomMappings/DeviceMappingsManager.d.ts

@@ -0,0 +1,43 @@
+import { JSONObject } from 'kuzzle';
+export declare class DeviceMappingsManager {
+    private mappings;
+    constructor(baseMappings: JSONObject);
+    /**
+     * Register custom metadata for devices
+     *
+     * @param metadata Device custom metadata mappings
+     *
+     * @example
+     *
+     * plugin.devices.registerMetadata({
+     *   serial: { type: 'keyword' },
+     * });
+     *
+     */
+    registerMetadata(metadata: any): void;
+    /**
+     * Register custom QoS for devices
+     *
+     * @param qos Device custom QoS mappings
+     *
+     * @example
+     *
+     * plugin.devices.registerQoS({
+     *   battery: { type: 'integer' },
+     * });
+     */
+    registerQoS(qos: JSONObject): void;
+    /**
+     * Register custom measure for devices mappings
+     *
+     * @param qos Device custom measure
+     *
+     * @example
+     *
+     * plugin.devices.registerMeasure('humidity', {
+     *   value: { type: 'float' },
+     * });
+     */
+    registerMeasure(name: string, measure: JSONObject): void;
+    get(): JSONObject;
+}

package/lib/core-classes/CustomMappings/DeviceMappingsManager.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceMappingsManager = void 0;
+const kuzzle_1 = require("kuzzle");
+class DeviceMappingsManager {
+    constructor(baseMappings) {
+        this.mappings = JSON.parse(JSON.stringify(baseMappings));
+    }
+    /**
+     * Register custom metadata for devices
+     *
+     * @param metadata Device custom metadata mappings
+     *
+     * @example
+     *
+     * plugin.devices.registerMetadata({
+     *   serial: { type: 'keyword' },
+     * });
+     *
+     */
+    registerMetadata(metadata) {
+        for (const [name, value] of Object.entries(metadata)) {
+            this.mappings.properties.metadata.properties[name] = value;
+        }
+    }
+    /**
+     * Register custom QoS for devices
+     *
+     * @param qos Device custom QoS mappings
+     *
+     * @example
+     *
+     * plugin.devices.registerQoS({
+     *   battery: { type: 'integer' },
+     * });
+     */
+    registerQoS(qos) {
+        for (const [name, value] of Object.entries(qos)) {
+            this.mappings.properties.qos.properties[name] = value;
+        }
+    }
+    /**
+     * Register custom measure for devices mappings
+     *
+     * @param qos Device custom measure
+     *
+     * @example
+     *
+     * plugin.devices.registerMeasure('humidity', {
+     *   value: { type: 'float' },
+     * });
+     */
+    registerMeasure(name, measure) {
+        if (this.mappings.properties.measures.properties[name]) {
+            throw new kuzzle_1.PluginImplementationError(`Measure "${name}" already exists.`);
+        }
+        const newMeasure = {
+            ...measure,
+            payloadUuid: { type: 'keyword' },
+            updatedAt: { type: 'date' },
+        };
+        this.mappings.properties.measures.properties[name] = {
+            properties: newMeasure
+        };
+    }
+    get() {
+        return this.mappings;
+    }
+}
+exports.DeviceMappingsManager = DeviceMappingsManager;
+//# sourceMappingURL=DeviceMappingsManager.js.map

package/lib/core-classes/Decoder.d.ts

@@ -0,0 +1,133 @@
+import { JSONObject, KuzzleRequest, HttpRoute } from 'kuzzle';
+import { Device, BaseAsset } from '../models';
+import { AssetMeasures, DeviceContent } from '../types';
+/**
+ * Base class to implement a decoder for a device model.
+ * The device model must be passed to the parent constructor.
+ * The abstract "decode" method must be implemented.
+ */
+export declare abstract class Decoder {
+    private _http?;
+    /**
+     * Device model name
+     */
+    deviceModel: string;
+    /**
+     * Custom name for the associated API action in the "payload" controller
+     */
+    action?: string;
+    /**
+     * Custom mappings for the payload collection.
+     * It will be injected in the "payload" property and it should allows to index
+     * the device model unique identifier field.
+     *
+     * @example
+     * this.payloadsMappings = {
+     *   device_properties: {
+     *     properties: {
+     *       deveui: { type: 'keyword' }
+     *     }
+     *   }
+     * }
+     */
+    payloadsMappings?: JSONObject;
+    /**
+     * Define custom HTTP routes
+     *
+     * @param http HttpRoute array
+     */
+    set http(http: HttpRoute[]);
+    get http(): HttpRoute[];
+    /**
+     * @param deviceModel Device model for this decoder
+     */
+    constructor(deviceModel: string);
+    /**
+     * Validate the payload format before processing.
+     *
+     * If the method:
+     *   - return true: the payload will be processed (status 200)
+     *   - return false: the payload will be skipped (status 200)
+     *   - throw an error: the payload will be skipped (status 4** or 5**)
+     *
+     * @param payload Raw payload received in the API action body
+     * @param request Original request
+     *
+     * @return A boolean indicating if the payload is valid
+     */
+    validate(payload: JSONObject, request: KuzzleRequest): Promise<boolean> | never;
+    /**
+     * Decode the payload:
+     *  - set "reference"
+     *  - fetch measures
+     *  - fetch qos
+     *
+     * @param payload Raw payload received in the API action body
+     * @param request Original request
+     *
+     * @returns Device content to save
+     */
+    abstract decode(payload: JSONObject, request: KuzzleRequest): Promise<DeviceContent>;
+    /**
+     * Hook executed before processing the payload but after validation
+     *
+     * @param payload Raw payload received in the API action body
+     * @param request Original request
+     */
+    beforeProcessing(payload: JSONObject, request: KuzzleRequest): Promise<void>;
+    /**
+     * Enrichment hook executed before registering a device
+     *
+     * @param device Densor before being persisted
+     * @param request Original request
+     *
+     * @returns Enriched device
+     */
+    beforeRegister(device: Device, request: KuzzleRequest): Promise<Device>;
+    /**
+     * Hook executed after registering a device.
+     * Return value of this method will be returned in the API action result.
+     *
+     * @param device Device after being persisted
+     * @param request Original request
+     *
+     * @returns Result of the corresponding API action
+     */
+    afterRegister(device: Device, request: KuzzleRequest): Promise<any>;
+    /**
+    * Enrichment hook executed before updating a device
+    *
+    * @param device Device before being updated
+    * @param request Original request
+    *
+    * @returns Enriched device
+    */
+    beforeUpdate(device: Device, request: KuzzleRequest): Promise<Device>;
+    /**
+     * Hook executed after updating a device.
+     * Return value of this method will be returned in the API action result.
+     *
+     * @param device Device after being updated
+     * @param request Original request
+     *
+     * @returns Result of the corresponding API action
+     */
+    afterUpdate(device: Device, asset: BaseAsset, request: KuzzleRequest): Promise<any>;
+    /**
+     * Build the "measures" property that will be persisted in the asset document
+     *
+     * @param device Device after being updated
+     *
+     * @returns Content of the "measures" property
+     */
+    copyToAsset(device: Device): Promise<AssetMeasures>;
+    /**
+     * Checks if the provided properties are present in the payload
+     *
+     * @param payload Raw payload received in the API action body
+     * @param paths Paths of properties (lodash style)
+     *
+     * @throws
+     */
+    ensureProperties(payload: JSONObject, paths: string[]): void | never;
+}