kuzzle 2.56.0 → 2.57.0-beta.2

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

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,26 +19,81 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const path = require("path");
-const fs = require("fs");
-const semver = require("semver");
-const { PluginContext } = require("./pluginContext");
-const PrivilegedPluginContext = require("./privilegedContext");
-const kerror = require("../../kerror");
-const errorCodes = require("../../kerror/codes");
-const Manifest = require("./pluginManifest");
-const { has, isPlainObject } = require("../../util/safeObject");
-const defaultConfig = require("../../config/default.config");
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const semver = __importStar(require("semver"));
+const default_config_1 = __importDefault(require("../../config/default.config"));
+const kerror = __importStar(require("../../kerror"));
+const errorCodes = __importStar(require("../../kerror/codes"));
+const safeObject_1 = require("../../util/safeObject");
+const pluginManifest_1 = __importDefault(require("./pluginManifest"));
+const pluginContext_1 = require("./pluginContext");
+const privilegedContext_1 = __importDefault(require("./privilegedContext"));
 const assertionError = kerror.wrap("plugin", "assert");
 const runtimeError = kerror.wrap("plugin", "runtime");
 const PLUGIN_NAME_REGEX = /^[a-z-\d]+$/;
-const HTTP_VERBS = ["get", "head", "post", "put", "delete", "patch", "options"];
+const HTTP_VERBS = new Set([
+    "get",
+    "head",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "options",
+]);
+/**
+ * Kuzzle's own wrapper around a plugin: its name, config, context and manifest,
+ * plus the assertions a plugin must satisfy before it is loaded.
+ *
+ * Not to be confused with `lib/types/Plugin.ts`'s `Plugin`, which is the
+ * abstract class a plugin author extends. This one wraps an instance of that.
+ */
 class Plugin {
-    constructor(instance, { name, application = false, deprecationWarning = true } = {}) {
+    constructor(instance, { name, application = false, deprecationWarning = true, } = {}) {
+        /**
+         * Set by `PluginsManager` once the plugin's own `init` has resolved.
+         *
+         * The JavaScript declared a `_initCalled` in the constructor and never read
+         * it: what the manager actually sets, and what the specs assert, is this
+         * public `initCalled`, created ad hoc on the object. The dead field is gone
+         * and the live one is declared.
+         */
+        this.initCalled = false;
+        /**
+         * Set from the outside by `Backend`, which reads it from the git tree — the
+         * wrapper has no way to derive it. `info()` reports it for an application.
+         */
+        this.commit = null;
+        /** Set from the outside by `Backend`, like `commit`. */
+        this.openApi = null;
         this._instance = instance;
         this._application = application;
-        this._initCalled = false;
         this._config = {};
         this._context = null;
         this._version = instance.version || "";
@@ -50,27 +106,31 @@ class Plugin {
     }
     init(name) {
         this.name = name;
-        if (global.kuzzle.config.plugins[this.name]) {
-            this.config = JSON.parse(JSON.stringify(global.kuzzle.config.plugins[this.name]));
+        const configured = global.kuzzle.config.plugins[this.name];
+        if (configured) {
+            // structuredClone is not equivalent: a plugin's configuration is user
+            // data that has been through JSON, and swapping clone semantics in a
+            // conversion is out of scope.
+            this.config = JSON.parse(JSON.stringify(configured)); // NOSONAR
         }
         // check plugin privileged prerequisites
         // user need to acknowledge privileged mode in plugin configuration
         if (this.config.privileged) {
-            if (!this.manifest || !this.manifest.privileged) {
+            if (!this.manifest?.privileged) {
                 throw assertionError.get("privileged_not_supported", this.name);
             }
         }
-        else if (this.manifest && this.manifest.privileged) {
+        else if (this.manifest?.privileged) {
             throw assertionError.get("privileged_not_set", this.name);
         }
-        if (this.manifest && this.manifest.kuzzleVersion) {
+        if (this.manifest?.kuzzleVersion) {
             if (!semver.satisfies(global.kuzzle.config.version, this.manifest.kuzzleVersion, { includePrerelease: true })) {
                 throw kerror.get("plugin", "manifest", "version_mismatch", this.name, global.kuzzle.config.version, this.manifest.kuzzleVersion);
             }
         }
         this._context = this.config.privileged
-            ? new PrivilegedPluginContext(this.name)
-            : new PluginContext(this.name);
+            ? new privilegedContext_1.default(this.name)
+            : new pluginContext_1.PluginContext(this.name);
     }
     info() {
         /* eslint-disable sort-keys */
@@ -80,8 +140,8 @@ class Plugin {
                 version: this.version,
                 commit: this.commit,
                 controllers: this.instance.api,
-                pipes: Object.keys(this.instance.pipes),
-                hooks: Object.keys(this.instance.hooks),
+                pipes: Object.keys(this.instance.pipes ?? {}),
+                hooks: Object.keys(this.instance.hooks ?? {}),
             };
         }
         const description = {
@@ -95,23 +155,23 @@ class Plugin {
             imports: {},
         };
         /* eslint-enable sort-keys */
-        if (has(this.instance, "imports")) {
-            description.imports = Object.keys(this.instance.imports);
+        if ((0, safeObject_1.has)(this.instance, "imports")) {
+            description.imports = Object.keys(this.instance.imports ?? {});
         }
-        if (has(this.instance, "hooks")) {
-            description.hooks = Object.keys(this.instance.hooks);
+        if ((0, safeObject_1.has)(this.instance, "hooks")) {
+            description.hooks = Object.keys(this.instance.hooks ?? {});
         }
-        if (has(this.instance, "pipes")) {
-            description.pipes = Object.keys(this.instance.pipes);
+        if ((0, safeObject_1.has)(this.instance, "pipes")) {
+            description.pipes = Object.keys(this.instance.pipes ?? {});
         }
-        if (has(this.instance, "controllers")) {
-            description.controllers = Object.keys(this.instance.controllers).map((controller) => `${this.name}/${controller}`);
+        if ((0, safeObject_1.has)(this.instance, "controllers")) {
+            description.controllers = Object.keys(this.instance.controllers ?? {}).map((controller) => `${this.name}/${controller}`);
         }
-        if (has(this.instance, "routes")) {
-            description.routes = this.instance.routes;
+        if ((0, safeObject_1.has)(this.instance, "routes")) {
+            description.routes = this.instance.routes ?? [];
         }
-        if (has(this.instance, "strategies")) {
-            description.strategies = Object.keys(this.instance.strategies);
+        if ((0, safeObject_1.has)(this.instance, "strategies")) {
+            description.strategies = Object.keys(this.instance.strategies ?? {});
         }
         return description;
     }
@@ -155,7 +215,10 @@ class Plugin {
         return this._name;
     }
     set name(name) {
-        if (!this.constructor.checkName(name)) {
+        // `Plugin.checkName` rather than `this.constructor.checkName`: nothing
+        // extends this class, and the static-through-instance form is not typable
+        // without an assertion.
+        if (!Plugin.checkName(name)) {
             this.printDeprecation("Plugin names should be in kebab-case. This behavior will be enforced in futur versions of Kuzzle.");
         }
         this._name = name;
@@ -168,49 +231,43 @@ class Plugin {
     }
     // static methods ============================================================
     static loadFromDirectory(pluginPath) {
-        if (!fs.statSync(pluginPath).isDirectory()) {
+        if (!node_fs_1.default.statSync(pluginPath).isDirectory()) {
             throw assertionError.get("cannot_load", pluginPath, "Not a directory.");
         }
         let plugin;
-        let PluginClass = {};
+        // Captured before the instantiation that may fail, because the catch
+        // below names it — the class itself used to be held in a `let` seeded with
+        // `null`, which is what the error path would have read on a failed require.
+        let pluginClassName;
         try {
-            PluginClass = require(pluginPath);
-            const pluginInstance = new PluginClass();
-            plugin = new Plugin(pluginInstance);
+            // A plugin is loaded from disk at runtime: the path is only known then,
+            // so this require is the feature, not an unconverted import.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const PluginClass = require(pluginPath);
+            pluginClassName = PluginClass.name;
+            plugin = new Plugin(new PluginClass());
         }
         catch (error) {
-            if (error.message.match(/not a constructor/i)) {
-                throw assertionError.get("not_a_constructor", PluginClass.name);
+            const cause = error instanceof Error ? error : new Error(String(error));
+            if (/not a constructor/i.exec(cause.message)) {
+                throw assertionError.get("not_a_constructor", pluginClassName);
             }
-            throw runtimeError.getFrom(error, "unexpected_error", error.message);
+            throw runtimeError.getFrom(cause, "unexpected_error", cause.message);
         }
         // load manifest
-        plugin.manifest = new Manifest(pluginPath);
+        plugin.manifest = new pluginManifest_1.default(pluginPath);
         plugin.manifest.load();
-        plugin.name = plugin.manifest.name;
+        const manifest = plugin.manifest;
+        // `load()` above throws `missing_name` rather than leave it unset.
+        plugin.name = manifest.name ?? "";
         // load plugin version if exists
-        const packageJsonPath = path.join(pluginPath, "package.json");
-        if (fs.existsSync(packageJsonPath) && !plugin.version) {
+        const packageJsonPath = node_path_1.default.join(pluginPath, "package.json");
+        if (node_fs_1.default.existsSync(packageJsonPath) && !plugin.version) {
+            // Same as the plugin's own module above: a path known only at runtime.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
             plugin.version = require(packageJsonPath).version;
         }
-        // load customs errors configuration file
-        if (plugin.manifest.raw.errors) {
-            try {
-                // we use the manifest name instead of the lowerCased plugin name
-                // to ensure to match the plugin original name in the configuration
-                const config = global.kuzzle.config[plugin.manifest.name];
-                const pluginCode = config && config._pluginCode ? config._pluginCode : 0x00;
-                errorCodes.loadPluginsErrors(plugin.manifest.raw, pluginCode);
-                global.kuzzle.log.info(`${plugin.logPrefix} Custom errors successfully loaded.`);
-            }
-            catch (err) {
-                if (err.message.match(/Error configuration file/i) ||
-                    err instanceof SyntaxError) {
-                    throw kerror.getFrom(err, "plugin", "manifest", "invalid_errors", plugin.manifest.name, err.message);
-                }
-                throw err;
-            }
-        }
+        loadPluginErrors(plugin);
         // check if the plugin exposes a "init" method
         if (typeof plugin.instance.init !== "function") {
             throw assertionError.get("init_not_found", plugin.name);
@@ -224,51 +281,109 @@ class Plugin {
         if (typeof name !== "string") {
             throw assertionError.get("invalid_controller_definition", "Controller name must be a string");
         }
-        if (!isPlainObject(definition)) {
+        if (!(0, safeObject_1.isPlainObject)(definition)) {
             throw assertionError.get("invalid_controller_definition", name, "Controller definition must be an object");
         }
-        if (!isPlainObject(definition.actions)) {
+        if (!(0, safeObject_1.isPlainObject)(definition.actions)) {
             throw assertionError.get("invalid_controller_definition", name, 'Controller definition "actions" property must be an object');
         }
         for (const [action, actionDefinition] of Object.entries(definition.actions)) {
-            if (!global.app.config.content.controllers?.definition
-                ?.allowAdditionalActionProperties ??
-                defaultConfig.controllers.definition.allowAdditionalActionProperties) {
-                const actionProperties = Object.keys(actionDefinition).filter((prop) => prop !== "handler" && prop !== "http");
-                if (actionProperties.length > 0) {
-                    throw assertionError.get("invalid_controller_definition", name, `action "${action}" has invalid properties: ${actionProperties.join(", ")}`);
-                }
-            }
-            if (typeof action !== "string") {
-                throw assertionError.get("invalid_controller_definition", name, "action names must be strings");
-            }
-            if (typeof actionDefinition.handler !== "function") {
-                throw assertionError.get("invalid_controller_definition", name, `action "${action}" handler must be a function`);
-            }
-            if (actionDefinition.http) {
-                if (!Array.isArray(actionDefinition.http)) {
-                    throw assertionError.get("invalid_controller_definition", name, `action "${action}" http definition must be an array`);
-                }
-                for (const route of actionDefinition.http) {
-                    if (typeof route.verb !== "string" || route.verb.length === 0) {
-                        throw assertionError.get("invalid_controller_definition", name, `action "${action}" http "verb" property must be a non-empty string`);
-                    }
-                    if (!HTTP_VERBS.includes(route.verb.toLowerCase())) {
-                        throw assertionError.get("invalid_controller_definition", name, `action "${action}" http verb "${route.verb}" is not a valid http verb`);
-                    }
-                    checkHttpRouteProperties(route, action, name, application);
-                    const routeProperties = Object.keys(route);
-                    if (routeProperties.length > 3) {
-                        routeProperties.splice(routeProperties.indexOf("url"), 1);
-                        routeProperties.splice(routeProperties.indexOf("path"), 1);
-                        routeProperties.splice(routeProperties.indexOf("verb"), 1);
-                        routeProperties.splice(routeProperties.indexOf("openapi"), 1);
-                        throw assertionError.get("invalid_controller_definition", name, `action "${action}" has invalid http properties: ${routeProperties.join(", ")}`);
-                    }
-                }
+            checkActionDefinition(name, action, actionDefinition, application);
+        }
+    }
+}
+/**
+ * Checks one action of a controller definition. Lifted verbatim out of
+ * `Plugin.checkControllerDefinition`, whose cognitive complexity the
+ * `.js` → `.ts` rename re-scored as new code.
+ */
+/**
+ * Loads a plugin's custom error definitions, if its manifest declares any.
+ * Lifted verbatim out of `Plugin.loadFromDirectory` for the same gate reason.
+ */
+function loadPluginErrors(plugin) {
+    // A plugin loaded from a directory always has one: `loadFromDirectory`
+    // builds it two lines before calling this.
+    const manifest = plugin.manifest;
+    if (manifest?.raw?.errors) {
+        try {
+            // we use the manifest name instead of the lowerCased plugin name
+            // to ensure to match the plugin original name in the configuration
+            // A plugin's section is keyed by its own name, which no declared
+            // configuration shape can carry — `get` is the prototype-safe read the
+            // rest of the codebase uses for exactly this.
+            const config = (0, safeObject_1.get)(global.kuzzle.config, manifest.name ?? "");
+            const configuredCode = (0, safeObject_1.isPlainObject)(config)
+                ? config._pluginCode
+                : undefined;
+            const pluginCode = typeof configuredCode === "number" ? configuredCode : 0x00;
+            // The two properties `loadPluginsErrors` reads, named explicitly:
+            // `raw` is a JSONObject and cannot be narrowed to the shape it wants
+            // without an assertion. Same values, same call.
+            errorCodes.loadPluginsErrors({
+                errors: manifest.raw.errors,
+                name: manifest.raw.name,
+            }, pluginCode);
+            global.kuzzle.log.info(`${plugin.logPrefix} Custom errors successfully loaded.`);
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err : new Error(String(err));
+            if (/Error configuration file/i.exec(cause.message) ||
+                err instanceof SyntaxError) {
+                throw kerror.getFrom(cause, "plugin", "manifest", "invalid_errors", manifest.name, cause.message);
             }
+            throw err;
+        }
+    }
+}
+function checkActionDefinition(name, action, actionDefinition, application) {
+    // Parenthesised: `!a?.b ?? c` parses as `(!a?.b) ?? c`, and `!x` is never
+    // nullish, so the fallback was dead code. It happens to be equivalent
+    // today only because the packaged default is `false` — it would not be if
+    // that default ever became `true`.
+    if (!(global.app.config.content.controllers?.definition
+        ?.allowAdditionalActionProperties ??
+        default_config_1.default.controllers.definition.allowAdditionalActionProperties)) {
+        const actionProperties = Object.keys(actionDefinition).filter((prop) => prop !== "handler" && prop !== "http");
+        if (actionProperties.length > 0) {
+            throw assertionError.get("invalid_controller_definition", name, `action "${action}" has invalid properties: ${actionProperties.join(", ")}`);
         }
     }
+    if (typeof action !== "string") {
+        throw assertionError.get("invalid_controller_definition", name, "action names must be strings");
+    }
+    if (typeof actionDefinition.handler !== "function") {
+        throw assertionError.get("invalid_controller_definition", name, `action "${action}" handler must be a function`);
+    }
+    if (actionDefinition.http) {
+        if (!Array.isArray(actionDefinition.http)) {
+            throw assertionError.get("invalid_controller_definition", name, `action "${action}" http definition must be an array`);
+        }
+        for (const route of actionDefinition.http) {
+            checkHttpRoute(route, action, name, application);
+        }
+    }
+}
+/**
+ * Checks one HTTP route of an action definition. Second half of the same
+ * gate-driven split as `checkActionDefinition`.
+ */
+function checkHttpRoute(route, action, name, application) {
+    if (typeof route.verb !== "string" || route.verb.length === 0) {
+        throw assertionError.get("invalid_controller_definition", name, `action "${action}" http "verb" property must be a non-empty string`);
+    }
+    if (!HTTP_VERBS.has(route.verb.toLowerCase())) {
+        throw assertionError.get("invalid_controller_definition", name, `action "${action}" http verb "${route.verb}" is not a valid http verb`);
+    }
+    checkHttpRouteProperties(route, action, name, application);
+    const routeProperties = Object.keys(route);
+    if (routeProperties.length > 3) {
+        routeProperties.splice(routeProperties.indexOf("url"), 1);
+        routeProperties.splice(routeProperties.indexOf("path"), 1);
+        routeProperties.splice(routeProperties.indexOf("verb"), 1);
+        routeProperties.splice(routeProperties.indexOf("openapi"), 1);
+        throw assertionError.get("invalid_controller_definition", name, `action "${action}" has invalid http properties: ${routeProperties.join(", ")}`);
+    }
 }
 function checkHttpRouteProperties(route, action, name, application) {
     if (typeof route.path !== "string" || route.path.length === 0) {

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

@@ -1,10 +1,11 @@
 import { Koncorde } from "../shared/KoncordeWrapper";
-import { JSONObject } from "kuzzle-sdk";
-import { KuzzleRequest, RequestContext, RequestInput } from "../../../index";
+import type { JSONObject } from "../../types/JSONObject";
+import { KuzzleRequest, RequestContext, RequestInput } from "../../api/request";
 import { Mutex } from "../../util/mutex";
-import { BackendCluster } from "../backend";
+import { BackendCluster } from "../backend/backendCluster";
 import { EmbeddedSDK } from "../shared/sdk/embeddedSdk";
-import { KuzzleLogger } from "kuzzle-logger/dist";
+import type { KuzzleLogger } from "kuzzle-logger/dist";
+import type { Kuzzle } from "../../kuzzle";
 export interface Repository {
     create(document: JSONObject, options: any): Promise<any>;
     createOrReplace(document: JSONObject, options: any): Promise<any>;
@@ -50,7 +51,11 @@ export declare class PluginContext {
          *
          * @deprecated use "accessors.sdk" instead (unless you need the original context)
          */
-        execute: (request: KuzzleRequest, callback?: any) => Promise<KuzzleRequest>;
+        /**
+         * Declared as returning a promise, as v2.56.0 declared it — see
+         * {@link PluginExecute}.
+         */
+        execute: PluginExecute;
         /**
          * Adds or removes realtime subscriptions from the backend.
          */
@@ -88,6 +93,13 @@ export declare class PluginContext {
          * Current Kuzzle node unique identifier
          */
         nodeId: string;
+        /**
+         * The Kuzzle instance itself.
+         *
+         * Only present for plugins declared `privileged` in their manifest:
+         * `PrivilegedPluginContext` is what sets it.
+         */
+        kuzzle?: Kuzzle;
     };
     config: JSONObject;
     constructors: {
@@ -98,7 +110,7 @@ export declare class PluginContext {
         /**
          * @deprecated import directly: `import { Koncorde } from 'kuzzle'`
          */
-        Koncorde: Koncorde;
+        Koncorde: typeof Koncorde;
         /**
          * Mutex class
          */
@@ -108,17 +120,17 @@ export declare class PluginContext {
          */
         Repository: new (collection: string, objectConstructor: any) => Repository;
         /**
-         * Instantiate a new Request from the original one.
+         * Instantiate a new Request from the original one, or from raw data.
          */
-        Request: KuzzleRequest;
+        Request: PluginRequestConstructor;
         /**
          * @deprecated import directly: `import { RequestContext } from 'kuzzle'`
          */
-        RequestContext: RequestContext;
+        RequestContext: typeof RequestContext;
         /**
          * @deprecated import directly: `import { RequestInput } from 'kuzzle'`
          */
-        RequestInput: RequestInput;
+        RequestInput: typeof RequestInput;
         /**
          * Constructor for Elasticsearch SDK Client
          */
@@ -155,5 +167,36 @@ export declare class PluginContext {
         verbose: (message: any) => void;
         warn: (message: any) => void;
     };
-    constructor(pluginName: any);
+    constructor(pluginName: string);
 }
+/**
+ * `context.accessors.execute`, as v2.56.0 declared it.
+ *
+ * Without a callback (or with `null`), the answer is a promise of the
+ * request. With a callback — called as `callback(error, request)` — the
+ * answer goes there, and **nothing is returned at runtime** (`null`): the
+ * declared promise does not exist in that form, so do not chain on it. It is
+ * declared all the same because v2.56.0 declared it so, and code compiled
+ * against that (`execute(request, callback).then(...)`) must still compile;
+ * a `Promise | null` return made every `await execute(request)` of a
+ * `strict` plugin a compile error.
+ */
+export type PluginExecute = (request: KuzzleRequest, callback?: unknown) => Promise<KuzzleRequest>;
+/**
+ * Instantiates a new Request object, using the provided one
+ * to set the context informations
+ *
+ * @throws
+ * @param {Request} request
+ * @param {Object} data
+ * @param {Object} [options]
+ * @returns {Request}
+ */
+/**
+ * `context.constructors.Request`'s two call shapes: from an original request,
+ * whose context and input the new one inherits, or from raw request data.
+ */
+export type PluginRequestConstructor = {
+    new (request: KuzzleRequest, data?: JSONObject, options?: JSONObject): KuzzleRequest;
+    new (data: JSONObject, options?: JSONObject): KuzzleRequest;
+};