kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/api/funnel.d.ts

@@ -1,23 +1,58 @@
-export = Funnel;
+import Bluebird from "bluebird";
+import Deque from "denque";
+import { KuzzleError } from "../kerror/errors";
+import type { EventAliases } from "../config/documentEventAliases";
+import RateLimiter from "./rateLimiter";
+import type { Logger } from "../kuzzle/Logger";
+import type { BaseController, NativeController } from "./controllers/baseController";
+import type { KuzzleRequest } from "./request";
+type ThrottledFn = (request: KuzzleRequest) => void;
+type ExecuteCallback = (error: Error | null, request: KuzzleRequest) => void;
+/**
+ * @class PendingRequest
+ */
+declare class PendingRequest {
+    request: KuzzleRequest;
+    fn: ThrottledFn;
+    context: unknown;
+    constructor(request: KuzzleRequest, fn: ThrottledFn, context: unknown);
+}
+interface SdkRequirements {
+    min?: number | string;
+    max?: number | string;
+}
+type DocumentEventAliases = EventAliases & {
+    mirrorList: Record<string, string>;
+};
 /**
  * @class Funnel
  */
 declare class Funnel {
     overloaded: boolean;
     concurrentRequests: number;
-    controllers: Map<any, any>;
-    pendingRequestsQueue: Deque<any>;
-    pendingRequestsById: Map<any, any>;
+    controllers: Map<string, NativeController>;
+    pendingRequestsQueue: Deque<string>;
+    pendingRequestsById: Map<string, PendingRequest>;
     lastOverloadTime: number;
     overloadWarned: boolean;
     lastWarningTime: number;
     rateLimiter: RateLimiter;
-    lastDumpedErrors: {};
-    sdkCompatibility: any;
-    logger: import("../kuzzle/Logger").Logger;
-    init(): Bluebird<any[]>;
-    loadDocumentEventAliases(): void;
-    documentEventAliases: import("../config/documentEventAliases").EventAliases;
+    lastDumpedErrors: Record<string, number>;
+    sdkCompatibility: Record<string, SdkRequirements>;
+    documentEventAliases: DocumentEventAliases;
+    logger: Logger;
+    constructor();
+    init(): Bluebird<void[]>;
+    /**
+     * Answers the table rather than assigning it: a field set by a method the
+     * constructor calls is not one the compiler can see being initialised.
+     */
+    loadDocumentEventAliases(): DocumentEventAliases;
+    /**
+     * Emits the "core:overload" event and logs a warning when the pending-request
+     * queue crosses its warning threshold — rate-limited to once per 500ms.
+     */
+    private _warnOverload;
     /**
      * Asks the overload-protection system for an execution slot.
      *
@@ -43,7 +78,7 @@ declare class Funnel {
      * @returns {Boolean} - A boolean telling whether the request has been
      *                      immediately executed or not.
      */
-    throttle(fn: Function, context: any, request: string): boolean;
+    throttle(fn: ThrottledFn, context: unknown, request: KuzzleRequest): boolean;
     /**
      * Execute the API request by
      * 1/ check domain from origin header
@@ -56,22 +91,51 @@ declare class Funnel {
      * @param {Function} callback
      * @returns {Number} -1: request delayed, 0: request processing, 1: error
      */
-    execute(request: Request, callback: Function): number;
+    execute(request: KuzzleRequest, callback: ExecuteCallback): 1 | 0 | -1 | null;
+    /**
+     * Runs a request that has been granted an execution slot by the
+     * overload-protection system. Extracted from `execute` verbatim.
+     *
+     * @param request - the very request `execute` handed to `throttle`
+     */
+    private _executeThrottled;
+    /**
+     * Rights check -> rate limit -> controller action, then reports the outcome
+     * through `callback`. Extracted from `execute` verbatim.
+     *
+     * @param request - the original request (the rate-limit branch inspects it,
+     *                  not the pipe-modified one)
+     * @param modifiedRequest - the "request:beforeExecution" pipe result
+     */
+    private _dispatch;
+    /**
+     * Fires "request:afterExecution" in failure mode, then reports the (possibly
+     * pipe-rewritten) error through `callback`. Extracted from `execute` verbatim
+     * — both of its catch blocks did exactly this.
+     */
+    private _reportExecutionError;
     /**
      * Checks if an error is worth dumping Kuzzle. If so,
      * creates a dump.
      *
      * @param {KuzzleError|*} err
      */
-    handleErrorDump(err: KuzzleError | any): void;
+    handleErrorDump(err: Error | KuzzleError): void;
     /**
      * Checks if a user has the necessary rights to execute the action
      *
      * @param {Request} request
      * @returns {Promise<Request>}
      */
-    checkRights(request: Request): Promise<Request>;
-    _isLogin(request: any): boolean;
+    checkRights(request: KuzzleRequest): Promise<KuzzleRequest>;
+    /**
+     * When cookie authentication is enabled, promotes the request's auth-token
+     * cookie to `request.input.jwt`. Extracted from `checkRights` verbatim.
+     *
+     * @returns whether token verification must be skipped (anonymous check)
+     */
+    private _applyCookieAuthToken;
+    _isLogin(request: KuzzleRequest): boolean;
     /**
      * Executes the request immediately.
      * /!\ To be used only by methods having already passed the overload check.
@@ -79,7 +143,7 @@ declare class Funnel {
      * @param {KuzzleRequest} request
      * @returns {Promise}
      */
-    processRequest(request: KuzzleRequest): Promise<any>;
+    processRequest(request: KuzzleRequest): Promise<KuzzleRequest>;
     /**
      * Triggers generic:document:* events
      *
@@ -103,7 +167,7 @@ declare class Funnel {
      * @returns {Promise}
      */
     executePluginRequest(request: KuzzleRequest): Promise<any>;
-    handleProcessRequestError(modifiedRequest: any, request: any, error: any): Promise<any>;
+    handleProcessRequestError(modifiedRequest: KuzzleRequest, request: KuzzleRequest, error: Error): Promise<any>;
     /**
      * Helper function meant to normalize event names
      * by retrieving controller aliases' original names.
@@ -112,7 +176,7 @@ declare class Funnel {
      * @param {string} prefix - event prefix
      * @returns {string} event name
      */
-    getEventName(request: any, prefix: string): string;
+    getEventName(request: KuzzleRequest, prefix: string): string;
     /**
      * Returns the number of remaining requests
      *
@@ -126,18 +190,26 @@ declare class Funnel {
      * @returns {Object} controller object
      * @throws {BadRequestError} If the asked controller or action is unknown
      */
-    getController(request: Request): any;
+    getController(request: KuzzleRequest): BaseController;
     /**
      * Tell if the controller is a native controller or not
      * @param  {String}  controller
      * @returns {Boolean}
      */
-    isNativeController(controller: string): boolean;
+    /**
+     * `string | null`: the two callers ask it of `request.input.controller`,
+     * which is null until set. A request naming no controller is not a native
+     * one, which is the answer the map already gave.
+     */
+    isNativeController(controller: string | null): boolean;
     /**
      * Returns inner metrics from the Funnel
      * @returns {Object}
      */
-    metrics(): any;
+    metrics(): {
+        concurrentRequests: number;
+        pendingRequests: number;
+    };
     /**
      * If the request is coming from an official SDK,
      * then checks the compatibility of the SDK against current Kuzzle version.
@@ -146,7 +218,7 @@ declare class Funnel {
      *
      * @throws
      */
-    _checkSdkVersion(request: Request): void;
+    _checkSdkVersion(request: KuzzleRequest): void;
     /**
      * Populates the given request with the error and calls the callback
      *
@@ -157,19 +229,52 @@ declare class Funnel {
      * @returns {null}
      * @private
      */
-    private _executeError;
+    _executeError(error: Error, request: KuzzleRequest, asError: boolean, callback: ExecuteCallback): null;
+    /**
+     * Plays the request at the front of the pending queue.
+     *
+     * @returns whether the loop should carry on — false when the queue has
+     *          nothing playable at its head, when the throttle refuses the
+     *          slot, or when it throws.
+     */
+    private _playOnePendingRequest;
     /**
      * Background task. Checks if there are any requests in cache, and replay them
      * if Kuzzle is not overloaded anymore,
      */
     _playPendingRequests(): void;
     /**
-     * Eventually wrap an error into a PluginImplementationError
+     * Eventually wrap an error into a PluginImplementationError.
+     *
+     * Everything that reaches this method comes out of a pipe — the error pipes
+     * of `handleProcessRequestError`, or `processRequest`'s own
+     * `request:onExecution` / before / after pipes — i.e. out of plugin code. A
+     * controller's error is wrapped at its source by `_wrapControllerError` and
+     * arrives here already a KuzzleError, so there is nothing left to guard on:
+     * see TD-27 (https://github.com/kuzzleio/kuzzle/issues/2703), which is why
+     * the previous guard on the controller name is gone rather than fixed.
+     *
      * @param  {Request} request
      * @param  {Error} error
      * @returns {KuzzleError}
      */
-    _wrapError(request: Request, error: Error): KuzzleError;
+    _wrapError(request: KuzzleRequest, error: Error): Error;
+    /**
+     * Normalizes an error thrown by a controller action into a KuzzleError.
+     *
+     * A native controller throwing something that is not a KuzzleError is a
+     * Kuzzle bug, and it is reported as one (`core.fatal.unexpected_error`).
+     * Reporting it as `plugin.runtime.unexpected_error` — which is what happened
+     * for as long as `_wrapError`'s guard was dead — names the wrong culprit,
+     * and letting it through raw is worse still: `KuzzleRequest.setError` then
+     * builds an InternalError with no `id` and no `code`, on a 500 sent to a
+     * client. See TD-27 (https://github.com/kuzzleio/kuzzle/issues/2703).
+     *
+     * @param  {Request} request
+     * @param  {Error} error
+     * @returns {KuzzleError}
+     */
+    _wrapControllerError(request: KuzzleRequest, error: Error): Error;
     /**
      * Verifies if requests sent from a specific origin are allowed
      * @param {string} origin
@@ -177,7 +282,4 @@ declare class Funnel {
      */
     _isOriginAuthorized(origin: string): boolean;
 }
-import Deque = require("denque");
-import RateLimiter = require("./rateLimiter");
-import Bluebird = require("bluebird");
-import { KuzzleError } from "../kerror/errors/kuzzleError";
+export = Funnel;