kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/core/network/protocols/protocol.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,40 +19,93 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const assert = require("assert");
-const bytes = require("../../../util/bytes");
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_assert_1 = __importDefault(require("node:assert"));
+const bytes_1 = __importDefault(require("../../../util/bytes"));
+/**
+ * @typeParam TConfig - the shape of `server.protocols.<name>` in the Kuzzle
+ *                      configuration, which is what `init` copies into
+ *                      `this.config`
+ */
 class Protocol {
-    constructor(name) {
-        this.maxRequestSize = null;
-        this.entryPoint = null;
-        this.name = name;
+    /**
+     * The entry point that owns this protocol, and the request size limit it
+     * published. Both are set by `init` and read by everything a protocol does
+     * afterwards — a handler cannot run before the server it is registered on
+     * has been created.
+     *
+     * Declaring them nullable and reading them anyway is what the subclasses
+     * did: 20 unchecked dereferences across the three of them, each one taking
+     * on trust what `init` establishes. These two accessors say it once, where
+     * it can actually fail.
+     */
+    get entryPoint() {
+        if (this._entryPoint === null) {
+            throw new Error(`Protocol "${this.name}" has no entry point: init() has not been called yet`);
+        }
+        return this._entryPoint;
+    }
+    get maxRequestSize() {
+        if (this._maxRequestSize === null) {
+            throw new Error(`Protocol "${this.name}" has no maxRequestSize: init() has not been called yet`);
+        }
+        return this._maxRequestSize;
+    }
+    set maxRequestSize(size) {
+        this._maxRequestSize = size;
+    }
+    /**
+     * Normalises the two `init` call shapes into the entry point they both
+     * carry. Every subclass overriding `init` has to accept both shapes too —
+     * a subclass that only took the live one would not honour the contract its
+     * base class publishes, and `init(null, entryPoint)` on it would throw —
+     * so the normalisation lives here rather than being written out four times.
+     *
+     * The old shape puts the entry point second. Reading `args[1]`
+     * unconditionally is what the first conversion did: `init(entryPoint)`
+     * type-checked and threw on `entryPoint.config` (TD-41).
+     */
+    static entryPointOf(args) {
+        // `||`, not `??`: v2.56.0 took any *falsy* first argument as the old shape
+        // (its assert only needed `!name`), so `init("", entryPoint)` and
+        // `init(false, entryPoint)` worked there. `??` kept `""` as the entry point.
+        const entryPoint = args[0] || args[1]; // NOSONAR: falsy, not nullish, on purpose
+        // Both call shapes crashed on `entryPoint.config` a few lines down when
+        // the entry point was missing. Same outcome, with the reason in the
+        // message — a third-party protocol in JavaScript is not constrained by
+        // the overloads.
+        (0, node_assert_1.default)(entryPoint !== undefined && entryPoint !== null, 'Invalid "entryPoint" parameter value: expected the network entry point');
+        return entryPoint;
+    }
+    constructor(name = "") {
+        this._maxRequestSize = null;
+        this._entryPoint = null;
         this.config = {};
         this.initCalled = false;
+        this.name = name;
         Reflect.defineProperty(this, "_kuzzle", {
             value: null,
             writable: true,
         });
     }
-    /**
-     * @param {string} name - Protocol name (used for accessor) @deprecated
-     * @param {EmbeddedEntryPoint} entryPoint
-     *
-     * @returns {Promise<boolean>}
-     */
-    async init(name, entryPoint) {
-        this.entryPoint = entryPoint;
-        // name should be passed in the constructor
-        assert(this.name && !name, "A name has been given in the constructor and init method. Passing the name in the init method is deprecated.");
-        if (!this.name) {
-            this.name = name;
-        }
-        this.maxRequestSize = bytes(entryPoint.config.maxRequestSize);
-        assert(typeof this.name === "string" && this.name.length > 0, 'Invalid "name" parameter value: expected a non empty string value');
-        if (entryPoint.config.protocols && entryPoint.config.protocols[this.name]) {
-            this.config = entryPoint.config.protocols[this.name];
+    async init(...args) {
+        const entryPoint = Protocol.entryPointOf(args);
+        this._entryPoint = entryPoint;
+        // name should be passed in the constructor. The original condition was
+        // `this.name && !name`; normalisation above proves the first argument is
+        // never a name, so `!name` was constant-true. What remains is the half
+        // that can fail, and it throws the same error it always did.
+        (0, node_assert_1.default)(this.name, "A name has been given in the constructor and init method. Passing the name in the init method is deprecated.");
+        this._maxRequestSize = (0, bytes_1.default)(entryPoint.config.maxRequestSize);
+        (0, node_assert_1.default)(typeof this.name === "string" && this.name.length > 0, 'Invalid "name" parameter value: expected a non empty string value');
+        const protocolsConfig = entryPoint.config.protocols;
+        // the config is keyed by protocol name, which is only known at runtime
+        if (protocolsConfig && Reflect.get(protocolsConfig, this.name)) {
+            this.config = Reflect.get(protocolsConfig, this.name);
         }
-        assert(Number.isInteger(this.maxRequestSize), 'Invalid "maxRequestSize" parameter value: expected a numeric value');
+        (0, node_assert_1.default)(Number.isInteger(this._maxRequestSize), 'Invalid "maxRequestSize" parameter value: expected a numeric value');
         this.initCalled = true;
         return true;
     }
@@ -59,11 +113,13 @@ class Protocol {
         // do nothing by default
     }
     joinChannel(channel, connectionId) {
-        // do nothing by default
+        // do nothing by default, beyond echoing back what it was given — which the
+        // spec pins. The `| void` is what lets an override that registers the
+        // channel and returns nothing satisfy the contract.
         return { channel, connectionId };
     }
     leaveChannel(channel, connectionId) {
-        // do nothing by default
+        // do nothing by default — see joinChannel.
         return { channel, connectionId };
     }
     notify() {

package/dist/lib/core/network/router.d.ts

@@ -1,29 +1,23 @@
-export = Router;
-/**
- * @class Router
- * @property action
- * @param {Kuzzle} kuzzle
- */
+import type { JSONObject } from "../../types/JSONObject";
+import type { RequestContext } from "../../api/request";
+import { Request } from "../../api/request";
+import HttpRouter from "./httpRouter";
+import type { RouteCallback } from "./httpRouter/routeTypes";
 declare class Router {
-    connections: Map<any, any>;
+    connections: Map<string, RequestContext>;
     http: HttpRouter;
-    logger: import("../../kuzzle/Logger").Logger;
+    private readonly logger;
+    constructor();
     /**
      * Declares a new connection attached to a network protocol.
-     *
-     * @param {RequestContext} requestContext
      */
     newConnection(requestContext: RequestContext): void;
     /**
      * Removes a connection from the connection pool.
-     *
-     * @param {RequestContext} requestContext
      */
     removeConnection(requestContext: RequestContext): void;
     /**
      * Check that the provided connection id executing a request is still alive
-     *
-     * @param  {RequestContext} requestContext
      */
     isConnectionAlive(requestContext: RequestContext): boolean;
     /**
@@ -32,18 +26,15 @@ declare class Router {
     init(): void;
     /**
      * Returns the metrics of the router
-     * @returns {Object}
      */
-    metrics(): any;
+    metrics(): JSONObject;
     /**
      * Transmit HTTP requests to the funnel controller and forward its response
      * back to the client
      *
-     * @param {String} verb
-     * @param {Request} request - includes URL and POST query data
-     * @param {function} cb - callback to invoke with the result
+     * @param request - includes URL and POST query data
+     * @param cb - callback to invoke with the result
      */
-    _executeFromHttp(verb: string, request: Request, cb: Function): void;
+    _executeFromHttp(verb: string, request: Request, cb: RouteCallback): void;
 }
-import HttpRouter = require("./httpRouter");
-import { Request } from "../../api/request/kuzzleRequest";
+export = Router;

package/dist/lib/core/network/router.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,27 +19,44 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const { Request } = require("../../api/request");
-const kerror = require("../../kerror");
-const HttpRouter = require("./httpRouter");
-const { removeStacktrace } = require("../../util/stackTrace");
-const kuzzleStateEnum = require("../../kuzzle/kuzzleStateEnum");
-/**
- * @class Router
- * @property action
- * @param {Kuzzle} kuzzle
- */
+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 request_1 = require("../../api/request");
+const kerror = __importStar(require("../../kerror"));
+const kuzzleStateEnum_1 = __importDefault(require("../../kuzzle/kuzzleStateEnum"));
+const httpRouter_1 = __importDefault(require("./httpRouter"));
 class Router {
     constructor() {
-        this.connections = new Map();
-        this.http = new HttpRouter();
         this.logger = global.kuzzle.log.child("core:network:router");
+        this.connections = new Map();
+        this.http = new httpRouter_1.default();
     }
     /**
      * Declares a new connection attached to a network protocol.
-     *
-     * @param {RequestContext} requestContext
      */
     newConnection(requestContext) {
         if (!requestContext.connection.id || !requestContext.connection.protocol) {
@@ -51,13 +69,11 @@ class Router {
     }
     /**
      * Removes a connection from the connection pool.
-     *
-     * @param {RequestContext} requestContext
      */
     removeConnection(requestContext) {
         const connId = requestContext.connection.id;
         if (!connId || !requestContext.connection.protocol) {
-            this.logger.error(kerror.get("protocol", "runtime", "invalid_connection", JSON.stringify(requestContext.context)));
+            this.logger.error(kerror.get("protocol", "runtime", "invalid_connection", JSON.stringify(requestContext)));
             return;
         }
         if (!this.connections.has(connId)) {
@@ -69,8 +85,6 @@ class Router {
     }
     /**
      * Check that the provided connection id executing a request is still alive
-     *
-     * @param  {RequestContext} requestContext
      */
     isConnectionAlive(requestContext) {
         // Check only defined connection identifiers (some protocols might
@@ -90,11 +104,14 @@ class Router {
         this.http.post("_query", (request, cb) => {
             // We need to build a new request from the body
             // and we also need to keep the original request context
-            const requestPayload = request.input.body;
+            // `input.body` is nullable: a POST /_query with no body used to reach
+            // `requestPayload.jwt` and throw a TypeError. `getBody()` answers the
+            // same object and rejects the empty case with api.assert.body_required.
+            const requestPayload = request.getBody();
             if (request.input.jwt && requestPayload.jwt === undefined) {
                 requestPayload.jwt = request.input.jwt;
             }
-            const apiRequest = new Request(requestPayload, request.serialize().options);
+            const apiRequest = new request_1.Request(requestPayload, request.serialize().options);
             this._executeFromHttp("post", apiRequest, cb);
         });
         this.http.get("_healthcheck", (request, cb) => {
@@ -109,12 +126,12 @@ class Router {
         });
         this.http.get("_ready", (request, cb) => {
             let status = 200;
-            if (global.kuzzle.state !== kuzzleStateEnum.RUNNING ||
+            if (global.kuzzle.state !== kuzzleStateEnum_1.default.RUNNING ||
                 global.kuzzle.funnel.overloaded) {
                 status = 503;
             }
             request.response.configure({
-                status: status,
+                status,
             });
             /**
              * By avoiding using the funnel, we avoid the request to be logged
@@ -123,6 +140,7 @@ class Router {
             cb(request);
         });
         for (const route of routes) {
+            // the route table's verbs are the HttpRouter method names, uppercased
             const verb = route.verb.toLowerCase();
             this.http[verb](route.path, (request, cb) => {
                 request.input.controller = route.controller;
@@ -136,24 +154,22 @@ class Router {
         }
         /**
          * Returns inner metrics from the router
-         * @returns {Object}
          */
         global.kuzzle.onAsk("core:network:router:metrics", () => this.metrics());
     }
     /**
      * Returns the metrics of the router
-     * @returns {Object}
      */
     metrics() {
         const connectionsByProtocol = {};
         for (const connection of this.connections.values()) {
-            const protocol = connection.connection.protocol.toLowerCase();
-            if (protocol === "internal") {
+            const protocol = connection.connection.protocol?.toLowerCase();
+            // A request context carries a nullable protocol; one without is not a
+            // client connection to count.
+            if (protocol === undefined || protocol === "internal") {
                 continue;
             }
-            if (connectionsByProtocol[protocol] === undefined) {
-                connectionsByProtocol[protocol] = 0;
-            }
+            connectionsByProtocol[protocol] ?? (connectionsByProtocol[protocol] = 0);
             connectionsByProtocol[protocol]++;
         }
         return {
@@ -164,30 +180,27 @@ class Router {
      * Transmit HTTP requests to the funnel controller and forward its response
      * back to the client
      *
-     * @param {String} verb
-     * @param {Request} request - includes URL and POST query data
-     * @param {function} cb - callback to invoke with the result
+     * @param request - includes URL and POST query data
+     * @param cb - callback to invoke with the result
      */
     _executeFromHttp(verb, request, cb) {
         global.kuzzle.pipe(`http:${verb}`, request, (error, mutatedRequest) => {
             if (error) {
                 request.setError(error);
                 cb(request);
+                return;
             }
-            else {
-                global.kuzzle.funnel.execute(mutatedRequest, (err, result) => {
-                    const _res = result || request;
-                    if (err && !_res.error) {
-                        _res.setError(err);
-                    }
-                    cb(removeStacktrace(_res));
-                });
-            }
+            global.kuzzle.funnel.execute(mutatedRequest, (err, result) => {
+                const _res = result || request;
+                if (err && !_res.error) {
+                    _res.setError(err);
+                }
+                // no sanitisation here: `_res` is a KuzzleRequest, and the stack
+                // is stripped by the protocols, on the serialized response
+                cb(_res);
+            });
         });
     }
 }
-/**
- * @type {RouterController}
- */
 module.exports = Router;
 //# sourceMappingURL=router.js.map

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

@@ -1,56 +1,62 @@
-export = Plugin;
+import type { JSONObject } from "../../types/JSONObject";
+import type { ControllerDefinition } from "../../types";
+import type { PluginInstance, PluginOptions } from "../../types/PluginInstance";
+import Manifest from "./pluginManifest";
+import { PluginContext } from "./pluginContext";
+/**
+ * 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.
+ */
 declare class Plugin {
-    static loadFromDirectory(pluginPath: any): Plugin;
-    static checkName(name: any): boolean;
-    static checkControllerDefinition(name: any, definition: any, { application }?: {
-        application?: boolean;
-    }): void;
-    constructor(instance: any, { name, application, deprecationWarning }?: {
-        name: any;
-        application?: boolean;
-        deprecationWarning?: boolean;
-    });
-    _instance: any;
-    _application: boolean;
-    _initCalled: boolean;
-    _config: {};
-    _context: PluginContext;
-    _version: any;
-    _name: string;
-    _manifest: any;
-    _deprecationWarning: boolean;
-    set name(name: string);
-    get name(): string;
-    init(name: any): void;
-    set config(config: {});
-    get config(): {};
-    info(): {
-        version: any;
-        controllers: any[];
-        hooks: any[];
-        manifest: any;
-        pipes: any[];
-        routes: any[];
-        strategies: any[];
-        imports: {};
-    } | {
-        name: string;
-        version: any;
-        commit: any;
-        controllers: any;
-        pipes: string[];
-        hooks: string[];
-    };
-    printDeprecation(message: any): void;
-    get instance(): any;
-    get context(): PluginContext;
+    private readonly _instance;
+    private readonly _application;
+    private _config;
+    private _context;
+    private _version;
+    private _name;
+    private _manifest;
+    private _deprecationWarning;
+    /**
+     * 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.
+     */
+    initCalled: boolean;
+    /**
+     * 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.
+     */
+    commit: string | null;
+    /** Set from the outside by `Backend`, like `commit`. */
+    openApi: JSONObject | null;
+    constructor(instance: PluginInstance, { name, application, deprecationWarning, }?: PluginOptions);
+    init(name: string): void;
+    info(): JSONObject;
+    printDeprecation(message: string): void;
+    get instance(): PluginInstance;
+    get context(): PluginContext | null;
     get application(): boolean;
     get logPrefix(): string;
-    set version(version: any);
-    get version(): any;
-    set deprecationWarning(value: boolean);
+    get config(): JSONObject;
+    set config(config: JSONObject);
+    get version(): string;
+    set version(version: string);
     get deprecationWarning(): boolean;
-    set manifest(manifest: any);
-    get manifest(): any;
+    set deprecationWarning(value: boolean);
+    get name(): string;
+    set name(name: string);
+    get manifest(): Manifest | null;
+    set manifest(manifest: Manifest | null);
+    static loadFromDirectory(pluginPath: string): Plugin;
+    static checkName(name: string): boolean;
+    static checkControllerDefinition(name: string, definition: ControllerDefinition | undefined, { application }?: {
+        application?: boolean;
+    }): asserts definition is ControllerDefinition;
 }
-import { PluginContext } from "./pluginContext";
+export = Plugin;