kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/core/plugin/pluginContext.js

@@ -50,14 +50,15 @@ exports.PluginContext = void 0;
 const bluebird_1 = __importDefault(require("bluebird"));
 const lodash_1 = __importDefault(require("lodash"));
 const KoncordeWrapper_1 = require("../shared/KoncordeWrapper");
-const index_1 = require("../../../index");
+const request_1 = require("../../api/request");
+const baseType_1 = __importDefault(require("../validation/baseType"));
 const kerror = __importStar(require("../../kerror"));
 const errors_1 = require("../../kerror/errors");
 const Elasticsearch_1 = require("../../service/storage/Elasticsearch");
 const mutex_1 = require("../../util/mutex");
 const promback_1 = __importDefault(require("../../util/promback"));
 const safeObject_1 = require("../../util/safeObject");
-const backend_1 = require("../backend");
+const backendCluster_1 = require("../backend/backendCluster");
 const embeddedSdk_1 = require("../shared/sdk/embeddedSdk");
 const store_1 = require("../shared/store");
 const storeScopeEnum_1 = require("../storage/storeScopeEnum");
@@ -116,14 +117,16 @@ class PluginContext {
             return Elasticsearch_1.Elasticsearch.buildClient(global.kuzzle.config.services.storageEngine.client);
         }
         this.constructors = {
-            BaseValidationType: require("../validation/baseType"),
+            BaseValidationType: baseType_1.default,
             ESClient: PluginContextESClient,
             Koncorde: KoncordeWrapper_1.Koncorde,
             Mutex: mutex_1.Mutex,
             Repository: PluginContextRepository,
+            // A plain function called with `new`: it returns an object, so `new`
+            // yields that object — which is what plugins have always relied on.
             Request: instantiateRequest,
-            RequestContext: index_1.RequestContext,
-            RequestInput: index_1.RequestInput,
+            RequestContext: request_1.RequestContext,
+            RequestInput: request_1.RequestInput,
         };
         Object.freeze(this.constructors);
         this.logger = globalThis.kuzzle.log.child(`${pluginName}`);
@@ -140,8 +143,8 @@ class PluginContext {
         Object.freeze(this.log);
         /* context.accessors ================================================== */
         this.accessors = {
-            cluster: new backend_1.BackendCluster(),
-            execute: (request, callback) => execute(request, callback),
+            cluster: new backendCluster_1.BackendCluster(),
+            execute,
             nodeId: global.nodeId,
             sdk: new embeddedSdk_1.EmbeddedSDK(),
             storage: {
@@ -154,7 +157,7 @@ class PluginContext {
             },
             subscription: {
                 register: (connectionId, index, collection, filters) => {
-                    const request = new index_1.KuzzleRequest({
+                    const request = new request_1.KuzzleRequest({
                         action: "subscribe",
                         body: filters,
                         collection,
@@ -179,91 +182,129 @@ class PluginContext {
 }
 exports.PluginContext = PluginContext;
 /**
- * @param {KuzzleRequest} request
- * @param {Function} [callback]
+ * The implementation says what it really returns: `null` in callback mode.
+ * The signature above is the declared one — see {@link PluginExecute}.
  */
 function execute(request, callback) {
-    if (callback && typeof callback !== "function") {
+    // `null` means "no callback", as `undefined` does: plugins pass it to ask
+    // for a promise explicitly.
+    if (callback !== undefined &&
+        callback !== null &&
+        !isPrombackCallback(callback)) {
         const error = contextError.get("invalid_callback", typeof callback);
         global.kuzzle.log.error(error);
         return bluebird_1.default.reject(error);
     }
-    const promback = new promback_1.default(callback);
+    const promback = new promback_1.default(isPrombackCallback(callback) ? callback : null);
     if (!request || lodash_1.default.isEmpty(request)) {
-        return promback.reject(contextError.get("missing_request"));
+        return asRequestPromise(promback.reject(contextError.get("missing_request")), request);
     }
     if (request.input.controller === "realtime" &&
+        request.input.action !== null &&
         ["subscribe", "unsubscribe"].includes(request.input.action)) {
-        return promback.reject(contextError.get("unavailable_realtime", request.input.action));
+        return asRequestPromise(promback.reject(contextError.get("unavailable_realtime", request.input.action)), request);
     }
     request.clearError();
     request.status = 102;
     global.kuzzle.funnel
         .executePluginRequest(request)
         .then((result) => {
-        request.setResult(result, {
-            status: request.status === 102 ? 200 : request.status,
-        });
+        // No status: a pending 102 becomes 200, any other is kept.
+        request.response.configure({ result });
         promback.resolve(request);
     })
         .catch((err) => {
         promback.reject(err);
     });
-    return promback.deferred;
+    return asRequestPromise(promback.deferred, request);
+}
+/** Whether a plugin handed `accessors.execute` something callable. */
+function isPrombackCallback(value) {
+    return typeof value === "function";
+}
+/**
+ * What `execute` answers, from a `Promback`'s deferred.
+ *
+ * `deferred` is null in callback mode — the caller gets its answer that way,
+ * and the JavaScript returned that null — and otherwise settles on
+ * `KuzzleRequest | undefined`, because `Promback.resolve()` may be called
+ * with nothing. This one is always settled with the request it was handed,
+ * so mapping through it is what turns the union into the contract.
+ */
+function asRequestPromise(deferred, request) {
+    return deferred === null ? null : deferred.then(() => request);
 }
 /**
- * Instantiates a new Request object, using the provided one
- * to set the context informations
+ * Copies the three routing fields a plugin's request inherits from the one it
+ * was built from.
  *
- * @throws
- * @param {Request} request
- * @param {Object} data
- * @param {Object} [options]
- * @returns {Request}
+ * Through `input.args`, which is what `input.resource`'s own deprecation
+ * notice points at and what those accessors read and write anyway — the loop
+ * this replaces asked `RequestResource` for an index signature it does not
+ * have.
  */
+function inheritResource(target, source) {
+    const to = target.input.args;
+    const from = source.input.args;
+    for (const field of ["_id", "index", "collection"]) {
+        if (!to[field] && from[field]) {
+            to[field] = from[field];
+        }
+    }
+}
 function instantiateRequest(request, data, options = {}) {
-    let _request = request, _data = data, _options = options;
-    if (!_request) {
+    if (!request) {
         throw contextError.get("missing_request_data");
     }
-    if (!(_request instanceof index_1.KuzzleRequest)) {
-        if (_data) {
-            _options = _data;
-        }
-        _data = _request;
-        _request = null;
+    // Two call shapes: `(request, data, options)` and `(data, options)`. The
+    // first argument is what tells them apart, and reassigning it — which is
+    // what the JavaScript did — throws away the narrowing that `instanceof`
+    // had just established.
+    let _request;
+    let _data;
+    let _options;
+    if (request instanceof request_1.KuzzleRequest) {
+        _request = request;
+        _data = data;
+        _options = options;
+        Object.assign(_options, _request.context.toJSON());
     }
     else {
-        Object.assign(_options, _request.context.toJSON());
+        _request = null;
+        _data = request;
+        _options = data ?? options;
     }
-    const target = new index_1.KuzzleRequest(_data, _options);
+    const target = new request_1.KuzzleRequest(_data, _options);
     // forward informations if a request object was supplied
-    if (_request) {
-        for (const resource of ["_id", "index", "collection"]) {
-            if (!target.input.resource[resource]) {
-                target.input.resource[resource] = _request.input.resource[resource];
-            }
-        }
-        for (const arg of Object.keys(_request.input.args)) {
-            if (target.input.args[arg] === undefined) {
-                target.input.args[arg] = _request.input.args[arg];
-            }
-        }
-        if (!_data || _data.jwt === undefined) {
-            target.input.jwt = _request.input.jwt;
-        }
-        if (_data) {
-            target.input.volatile = {
-                ..._request.input.volatile,
-                ..._data.volatile,
-            };
-        }
-        else {
-            target.input.volatile = _request.input.volatile;
-        }
+    if (_request !== null) {
+        inheritInput(target, _request, _data);
     }
     return target;
 }
+/**
+ * Copies onto `target` what it did not receive of its own: the routing
+ * fields, the arguments, the token and the volatile data.
+ */
+function inheritInput(target, source, data) {
+    inheritResource(target, source);
+    for (const arg of Object.keys(source.input.args)) {
+        if (target.input.args[arg] === undefined) {
+            target.input.args[arg] = source.input.args[arg];
+        }
+    }
+    if (data?.jwt === undefined && source.input.jwt !== null) {
+        target.input.jwt = source.input.jwt;
+    }
+    if (data) {
+        target.input.volatile = {
+            ...source.input.volatile,
+            ...data.volatile,
+        };
+    }
+    else if (source.input.volatile !== null) {
+        target.input.volatile = source.input.volatile;
+    }
+}
 /**
  * Returns a currified function of pluginsManager.registerStrategy
  *

package/dist/lib/core/plugin/pluginManifest.d.ts

@@ -1,5 +1,9 @@
-export = PluginManifest;
+import AbstractManifest from "../shared/abstractManifest";
 declare class PluginManifest extends AbstractManifest {
     privileged: boolean;
+    load(): {
+        kuzzleVersion: string;
+        name: string;
+    };
 }
-import AbstractManifest = require("../shared/abstractManifest");
+export = PluginManifest;

package/dist/lib/core/plugin/pluginManifest.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,27 +19,33 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const _ = require("lodash");
-const kerror = require("../../kerror").wrap("plugin", "manifest");
-const AbstractManifest = require("../shared/abstractManifest");
-class PluginManifest extends AbstractManifest {
-    constructor(pluginPath) {
-        super(pluginPath);
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const lodash_1 = require("lodash");
+const kerror_1 = require("../../kerror");
+const abstractManifest_1 = __importDefault(require("../shared/abstractManifest"));
+const kerror = (0, kerror_1.wrap)("plugin", "manifest");
+class PluginManifest extends abstractManifest_1.default {
+    constructor() {
+        super(...arguments);
         this.privileged = false;
     }
     load() {
-        super.load();
-        // Ensure ES will accept the plugin name as index
-        if (!/^[\w-]+$/.test(this.name)) {
+        const loaded = super.load();
+        // Ensure ES will accept the plugin name as index. `super.load()` answers
+        // the name it established, which is what the `String()` here used to
+        // stand in for.
+        if (!/^[\w-]+$/.test(loaded.name)) {
             throw kerror.get("invalid_name", this.path);
         }
-        if (!_.isNil(this.raw) && !_.isNil(this.raw.privileged)) {
+        if (!(0, lodash_1.isNil)(this.raw) && !(0, lodash_1.isNil)(this.raw.privileged)) {
             if (typeof this.raw.privileged !== "boolean") {
                 throw kerror.get("invalid_privileged", this.path, typeof this.raw.privileged);
             }
             this.privileged = this.raw.privileged;
         }
+        return loaded;
     }
 }
 module.exports = PluginManifest;

package/dist/lib/core/plugin/pluginRepository.d.ts

@@ -1,53 +1,44 @@
-export = PluginRepository;
-declare class PluginRepository extends ObjectRepository<any> {
-    constructor(store: any, collection: any);
-    collection: any;
-    ObjectConstructor: ObjectConstructor;
-    init(options: any): void;
+import type { JSONObject } from "../../types/JSONObject";
+import { ObjectRepository } from "../shared/ObjectRepository";
+/**
+ * A plugin's private-storage document.
+ *
+ * `ObjectRepository` requires `_id` on its type parameter, but the plugin-facing
+ * `Repository` contract passes a bare `JSONObject` — a document being created
+ * legitimately has no id yet. The public methods below therefore take
+ * `JSONObject` and assert the shape at the one place the base needs it, which
+ * is also exactly where the runtime has always read `object._id`.
+ */
+type PluginDocument = JSONObject & {
+    _id: string;
+};
+interface PluginRepositoryOptions {
+    ObjectConstructor?: new () => unknown;
+}
+declare class PluginRepository extends ObjectRepository<PluginDocument> {
+    constructor(store: {
+        index: string;
+    }, collection: string);
+    init(options?: PluginRepositoryOptions): void;
     /**
      * Serializes the object before being persisted to database.
-     *
-     * @param {object} data - The object to serialize
-     * @returns {object}
-     */
-    serializeToDatabase(data: object): object;
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
-    create(object: object, options?: object): Promise<any>;
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
-    createOrReplace(object: object, options?: object): Promise<any>;
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
      */
-    replace(object: object, options?: object): Promise<any>;
+    serializeToDatabase(data: PluginDocument): JSONObject;
+    create(object: JSONObject, options?: JSONObject): any;
+    createOrReplace(object: JSONObject, options?: JSONObject): any;
+    replace(object: JSONObject, options?: JSONObject): any;
+    update(object: JSONObject, options?: JSONObject): any;
     /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
-    update(object: object, options?: object): Promise<any>;
-    /**
-     * If we load a user that does not exists, we have to resolve the promise with null
-     * instead of throwing NotFoundError
+     * If we load a user that does not exists, we have to resolve the promise with
+     * null instead of throwing NotFoundError.
      *
-     * @param {string} documentId
-     * @returns {Promise}
+     * Declared `Promise<PluginDocument>` all the same, as the base's `load()`
+     * is — see there.
      */
-    load(documentId: string): Promise<any>;
+    load(documentId: string): Promise<PluginDocument>;
     /**
-     * @param {string} documentId
-     * @param {object} [options]
-     * @returns {Promise}
+     * Unlike its base, this one deletes by id — the shape a plugin holds.
      */
-    delete(documentId: string, options?: object): Promise<any>;
+    delete(documentId: string | PluginDocument, options?: JSONObject): Promise<void>;
 }
-import { ObjectRepository } from "../shared/ObjectRepository";
+export = PluginRepository;

package/dist/lib/core/plugin/pluginRepository.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,14 +19,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const { merge } = require("lodash");
-const { NotFoundError } = require("../../kerror/errors");
-const { ObjectRepository } = require("../shared/ObjectRepository");
-const { cacheDbEnum } = require("../cache/cacheDbEnum");
-class PluginRepository extends ObjectRepository {
+const lodash_1 = require("lodash");
+const errors_1 = require("../../kerror/errors");
+const cacheDbEnum_1 = require("../cache/cacheDbEnum");
+const ObjectRepository_1 = require("../shared/ObjectRepository");
+class PluginRepository extends ObjectRepository_1.ObjectRepository {
     constructor(store, collection) {
-        super({ cache: cacheDbEnum.NONE, store });
+        super({ cache: cacheDbEnum_1.cacheDbEnum.NONE, store });
         this.collection = collection;
         this.ObjectConstructor = Object;
     }
@@ -38,74 +38,59 @@ class PluginRepository extends ObjectRepository {
     }
     /**
      * Serializes the object before being persisted to database.
-     *
-     * @param {object} data - The object to serialize
-     * @returns {object}
      */
     serializeToDatabase(data) {
-        // avoid the data var mutation
-        const result = merge({}, data);
+        // avoid the data var mutation. Typed as JSONObject, not PluginDocument:
+        // dropping `_id` is the whole point, and `_id` is required on the latter.
+        const result = (0, lodash_1.merge)({}, data);
         delete result._id;
         return result;
     }
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
     create(object, options = {}) {
-        const opts = Object.assign({ method: "create" }, options);
-        return this.persistToDatabase(object, opts);
+        return this.persistToDatabase(object, {
+            method: "create",
+            ...options,
+        });
     }
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
     createOrReplace(object, options = {}) {
-        const opts = Object.assign({ method: "createOrReplace" }, options);
-        return this.persistToDatabase(object, opts);
+        return this.persistToDatabase(object, {
+            method: "createOrReplace",
+            ...options,
+        });
     }
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
     replace(object, options = {}) {
-        const opts = Object.assign({ method: "replace" }, options);
-        return this.persistToDatabase(object, opts);
+        return this.persistToDatabase(object, {
+            method: "replace",
+            ...options,
+        });
     }
-    /**
-     * @param {object} object
-     * @param {object} [options]
-     * @returns {Promise}
-     */
     update(object, options = {}) {
-        const opts = Object.assign({ method: "update" }, options);
-        return this.persistToDatabase(object, opts);
+        return this.persistToDatabase(object, {
+            method: "update",
+            ...options,
+        });
     }
     /**
-     * If we load a user that does not exists, we have to resolve the promise with null
-     * instead of throwing NotFoundError
+     * If we load a user that does not exists, we have to resolve the promise with
+     * null instead of throwing NotFoundError.
      *
-     * @param {string} documentId
-     * @returns {Promise}
+     * Declared `Promise<PluginDocument>` all the same, as the base's `load()`
+     * is — see there.
      */
     load(documentId) {
         return super.load(documentId).catch((error) => {
-            if (this.collection === "users" && error instanceof NotFoundError) {
-                return Promise.resolve(null);
+            if (this.collection === "users" && error instanceof errors_1.NotFoundError) {
+                return null;
             }
             throw error;
         });
     }
     /**
-     * @param {string} documentId
-     * @param {object} [options]
-     * @returns {Promise}
+     * Unlike its base, this one deletes by id — the shape a plugin holds.
      */
     delete(documentId, options = {}) {
-        return super.delete({ _id: documentId }, options);
+        const _id = typeof documentId === "string" ? documentId : documentId._id;
+        return super.delete({ _id }, options);
     }
 }
 module.exports = PluginRepository;