kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/types/KuzzleWebSocket.js

@@ -0,0 +1,23 @@
+"use strict";
+/*
+ * Kuzzle, a backend software, self-hostable and ready to use
+ * to power modern apps
+ *
+ * Copyright 2015-2022 Kuzzle
+ * mailto: support AT kuzzle.io
+ * website: http://kuzzle.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=KuzzleWebSocket.js.map

package/dist/lib/types/OpenApiDefinition.d.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "./JSONObject";
 export type OpenApiDefinition = {
     swagger?: string;
     openapi?: string;

package/dist/lib/types/Plugin.d.ts

@@ -1,10 +1,10 @@
-import { JSONObject } from "kuzzle-sdk";
-import { PluginContext } from "../core/plugin/pluginContext";
-import { ControllerDefinition } from "./controllers/ControllerDefinition";
-import { PluginManifest } from "./PluginManifest";
-import { StrategyDefinition } from "./StrategyDefinition";
-import { PipeEventHandler, HookEventHandler } from "./EventHandler";
-import { ImportConfig } from "./Kuzzle";
+import type { JSONObject } from "./JSONObject";
+import type { PluginContext } from "../core/plugin/pluginContext";
+import type { ControllerDefinition } from "./controllers/ControllerDefinition";
+import type { PluginManifest } from "./PluginManifest";
+import type { StrategyDefinition } from "./StrategyDefinition";
+import type { HookEventHandler, PipeEventHandler } from "./EventHandler";
+import type { ImportConfig } from "./Kuzzle";
 /**
  * Allows to define plugins controllers and actions
  */
@@ -14,8 +14,20 @@ export type PluginApiDefinition = {
      */
     [controller: string]: ControllerDefinition;
 };
+/**
+ * A hook or pipe target given as the **name** of one of the plugin's methods
+ * instead of the function itself.
+ *
+ * @deprecated Pass the function. Kuzzle still resolves the name, and prints a
+ * deprecation warning when it registers the handler.
+ */
+export type PluginMethodName = string;
 /**
  * Allows to define hooks on events
+ *
+ * Kuzzle also resolves a {@link PluginMethodName} in place of a handler, but
+ * the type admits only functions, as v2.56.0's did: code compiled against
+ * that reads a value back and calls it, which a `string` in the union breaks.
  */
 export type PluginHookDefinition = {
     /**
@@ -24,7 +36,12 @@ export type PluginHookDefinition = {
     [event: string]: HookEventHandler | HookEventHandler[];
 };
 /**
- * Allows to define pipes on events
+ * Allows to define pipes on events.
+ *
+ * A pipe either returns a promise, or takes a trailing `callback(error,
+ * request)`: both forms are documented, and the runner accepts both — and a
+ * {@link PluginMethodName}. The type is v2.56.0's, for the reason given on
+ * {@link PluginHookDefinition}.
  */
 export type PluginPipeDefinition = {
     /**
@@ -39,10 +56,18 @@ export declare abstract class Plugin {
     _manifest: PluginManifest;
     /**
      * Plugin context.
+     *
+     * Kuzzle hands it to `init(config, context)` and never assigns it here:
+     * storing it is the documented convention plugin authors follow. It is
+     * declared as always present (`!`) because that is what every method but
+     * `init` can rely on, and what v2.56.0 declared — an optional field made
+     * every `this.context.*` of a `strict` plugin a compile error.
      */
     context: PluginContext;
     /**
      * Plugin config.
+     *
+     * Declared as always present for the same reason as {@link context}.
      */
     config: JSONObject;
     /**

package/dist/lib/types/PluginInstance.d.ts

@@ -0,0 +1,67 @@
+import type { JSONObject } from "./JSONObject";
+import type { Logger } from "../kuzzle/Logger";
+import type PluginManifest from "../core/plugin/pluginManifest";
+import type { PluginContext } from "../core/plugin/pluginContext";
+import type { PluginApiDefinition } from "./Plugin";
+import type { HookEventHandler, RegisteredPipeHandler } from "./EventHandler";
+/**
+ * The hooks Kuzzle accepts off a plugin object: the public
+ * `PluginHookDefinition`, plus the (deprecated) name of one of the plugin's
+ * methods in place of a handler — the `string` — which the public type
+ * leaves out (see there).
+ */
+type InstanceHookDefinition = {
+    [event: string]: HookEventHandler | string | Array<HookEventHandler | string>;
+};
+/**
+ * The pipes Kuzzle accepts off a plugin object: either handler form, or a
+ * method name (see `PluginPipeDefinition`).
+ */
+type InstancePipeDefinition = {
+    [event: string]: RegisteredPipeHandler | string | Array<RegisteredPipeHandler | string>;
+};
+/**
+ * What Kuzzle needs of a plugin's own object. The full contract third parties
+ * implement is the abstract `Plugin` in `lib/types/Plugin.ts`; this is the
+ * subset this wrapper reads, and every member is optional because a plugin is
+ * a user-supplied object that may declare none of them.
+ */
+export interface PluginInstance {
+    /**
+     * A plugin is a user-supplied object and may expose any member: the named
+     * ones below are what Kuzzle reads, and handlers are routinely referenced by
+     * name (`controllers.foo.bar = "someMethod"`), which needs this signature.
+     */
+    [member: string]: unknown;
+    init?: (config: JSONObject, context: PluginContext) => unknown;
+    /**
+     * An application's own logger (`Backend.log`). Only an application has one —
+     * a plain plugin does not — and it lives here, on the instance, not on the
+     * `Plugin` wrapper: the shutdown path read it off the wrapper for years and
+     * silently flushed nothing (TD-51).
+     */
+    log?: Logger;
+    authenticators?: JSONObject;
+    version?: string;
+    _manifest?: PluginManifest;
+    api?: PluginApiDefinition;
+    imports?: JSONObject;
+    hooks?: InstanceHookDefinition;
+    pipes?: InstancePipeDefinition;
+    /** The pre-Kaaf controller shape: controller → action → handler or method name. */
+    controllers?: JSONObject;
+    routes?: JSONObject[];
+    /**
+     * `JSONObject`, not `StrategyDefinition`: that type is the *authoring*
+     * contract a plugin writes against, while this interface describes what
+     * Kuzzle reads off a plugin object before anything has validated it.
+     * `PluginsManager.validateStrategy` is what turns one into the other.
+     */
+    strategies?: JSONObject;
+}
+export interface PluginOptions {
+    name?: string;
+    application?: boolean;
+    deprecationWarning?: boolean;
+}
+export {};

package/dist/lib/types/PluginInstance.js

@@ -0,0 +1,23 @@
+"use strict";
+/*
+ * Kuzzle, a backend software, self-hostable and ready to use
+ * to power modern apps
+ *
+ * Copyright 2015-2022 Kuzzle
+ * mailto: support AT kuzzle.io
+ * website: http://kuzzle.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginInstance.js.map

package/dist/lib/types/Policy.d.ts

@@ -1,4 +1,4 @@
-import { PolicyRestrictions, OptimizedPolicyRestrictions } from "./PolicyRestrictions";
+import type { PolicyRestrictions, OptimizedPolicyRestrictions } from "./PolicyRestrictions";
 /**
  * Policy definition for a role
  * and its restrictions

package/dist/lib/types/Target.d.ts

@@ -13,3 +13,11 @@ export type Target = {
     index?: string;
     collections?: string[];
 };
+/**
+ * A target that has been through `BaseController.assertTargetsAreValid`.
+ *
+ * That assertion rejects a target missing `index` or `collections`, so the
+ * storage layer — which is only ever handed validated targets — can read both
+ * without re-checking them.
+ */
+export type ValidatedTarget = Required<Target>;

package/dist/lib/types/Token.d.ts

@@ -1,6 +1,10 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "./JSONObject";
 /**
- * Kuzzle authentication token.
+ * Kuzzle authentication token, as a plain object.
+ *
+ * Not the type of `request.context.token`: that is the server's token model,
+ * exported as `KuzzleToken`, which has every member below except
+ * `connectionId` (ADR-0002 step 02, TD-07).
  */
 export interface Token extends JSONObject {
     /**
@@ -21,6 +25,14 @@ export interface Token extends JSONObject {
     userId: string;
     /**
      * Associated connection ID
+     *
+     * Never set on the tokens Kuzzle builds: a token can serve several
+     * connections, and the token manager keeps those links, not the token. The
+     * connection of a request is `request.context.connection.id`.
+     *
+     * @deprecated Never set, on v2.56.0 or since; kept so that code reading it
+     * still compiles. Use `request.context.connection.id` for a request's
+     * connection. To be removed in the next major (ADR-0002 step 04).
      */
     connectionId: string | null;
     /**

package/dist/lib/types/config/HttpConfiguration.d.ts

@@ -10,6 +10,11 @@ export type HttpConfiguration = {
      * Sets the default Access-Control-Allow-Origin HTTP
      * header used to send responses to the client.
      *
+     * A comma-separated list, or an array of origins. Kuzzle stores the array
+     * once the configuration is loaded — of `RegExp`s with
+     * `accessControlAllowOriginUseRegExp`. Declared `string` all the same, as
+     * v2.56.0 declared it: code compiled against that reads it as one.
+     *
      * @default "*"
      */
     accessControlAllowOrigin: string;

package/dist/lib/types/config/KuzzleConfiguration.d.ts

@@ -1,5 +1,22 @@
-import { DumpConfiguration, HttpConfiguration, LimitsConfiguration, PluginsConfiguration, SecurityConfiguration, ServerConfiguration, ServicesConfiguration } from "../index";
+import type { DumpConfiguration, HttpConfiguration, LimitsConfiguration, PluginsConfiguration, SecurityConfiguration, ServerConfiguration, ServicesConfiguration } from "../index";
+/**
+ * The **merged, runtime** configuration: a user's `.kuzzlerc` applied over the
+ * packaged defaults. Nothing here is optional, because `loadConfig()` always
+ * produces every section — this is what `global.kuzzle.config` holds.
+ *
+ * For what a user may *write*, see {@link KuzzleConfiguration}.
+ */
 export interface IKuzzleConfiguration {
+    /**
+     * Kuzzle version, populated at runtime from `package.json`.
+     *
+     * Optional here, like the other members v2.56.0's declaration did not have
+     * (`cluster.retransmitBuffer`, `internal.allowAllOrigins`, `vault`): a
+     * required new member breaks code that builds this type. The loaded
+     * configuration always has them (the packaged defaults and `loadConfig()`
+     * fill them), so Kuzzle's own readers assert them present.
+     */
+    version?: string;
     realtime: {
         /**
          * @default false
@@ -118,11 +135,43 @@ export interface IKuzzleConfiguration {
          * @default 5000
          */
         syncTimeout: number;
+        /**
+         * How many of its last sync messages a node keeps, so that a peer that
+         * missed some can ask for them again instead of evicting itself. The
+         * oldest are dropped as soon as either bound is exceeded; 0 disables it.
+         *
+         * Optional here for the reason given on {@link IKuzzleConfiguration.version}.
+         */
+        retransmitBuffer?: {
+            /**
+             * @default 1000
+             */
+            messages: number;
+            /**
+             * @default 16777216 (16 MiB)
+             */
+            bytes: number;
+        };
     };
     internal: {
         hash: any;
         notifiableProtocols: string[];
+        /**
+         * Derived at startup from "http.accessControlAllowOrigin": true when the
+         * configured origins contain the "*" wildcard.
+         *
+         * Optional here for the reason given on {@link IKuzzleConfiguration.version}.
+         */
+        allowAllOrigins?: boolean;
     };
+    /**
+     * Collection specifications to apply at startup, by index then collection.
+     * Read when the internal index holds none of its own — the database is not
+     * necessarily prepared when validation first loads.
+     *
+     * Their shape is a `RawSpecification`, which validation reads it as; the
+     * declaration is v2.56.0's, which code compiled against it assigns to.
+     */
     validation: Record<string, unknown>;
     controllers: {
         definition: {
@@ -134,5 +183,57 @@ export interface IKuzzleConfiguration {
             allowAdditionalActionProperties: boolean;
         };
     };
+    /**
+     * The vault section lets you configure the secrets vault behavior.
+     *
+     * Optional here for the reason given on {@link IKuzzleConfiguration.version}.
+     */
+    vault?: {
+        /**
+         * Opt-in for the new vault encryption algorithm (AES-256-GCM) instead
+         * of the legacy one (AES-256-CBC).
+         *
+         * @default false
+         */
+        newAlgorithm: boolean;
+    };
 }
+/**
+ * What `lib/config/default.config.ts` ships: every section except the two
+ * `loadConfig()` derives at startup — `version`, read from `package.json`, and
+ * `internal`, computed from the rest (the hash seed, the notifiable protocols,
+ * the `allowAllOrigins` flag). Declaring the omission is what keeps the defaults
+ * file total — any other missing section is an error, not an oversight.
+ */
+export type PackagedKuzzleConfiguration = Omit<IKuzzleConfiguration, "version" | "internal">;
+/**
+ * Recursively optional. Written out here rather than imported because the user
+ * shape below is its only use: an override is always *partial at every depth*,
+ * and a shallow `Partial` demands the whole of any section it is given.
+ *
+ * Arrays and functions are left alone — a partial array element is not a thing
+ * a config override can express, and `_.merge` replaces arrays wholesale.
+ */
+type DeepPartial<T> = T extends unknown[] ? T : T extends (...args: never[]) => unknown ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * What a **user** may supply: a `.kuzzlerc` file, the object passed to
+ * `app.config.merge()`, an environment override. Everything is optional, at
+ * every depth, because the packaged defaults provide the rest — and because
+ * that is what `rc` and `_.merge` actually accept.
+ *
+ * This is **not** the shape of `global.kuzzle.config`, which is this merged
+ * over `lib/config/default.config.ts` and therefore total — that one is
+ * {@link IKuzzleConfiguration}. One name used for both is what kept every
+ * config reader out of `strict`: see ADR-0001, TD-53 (#2756).
+ */
+export type KuzzleConfigurationOverrides = DeepPartial<IKuzzleConfiguration>;
+/**
+ * v2.56.0's name for a configuration that may omit whole sections — but not
+ * keys within one: `Partial`, not {@link KuzzleConfigurationOverrides}. Kept
+ * as it was, because code compiled against it reads a section it set back
+ * without `?.` (`config.limits!.documentsFetchCount` as a `number`).
+ */
 export type KuzzleConfiguration = Partial<IKuzzleConfiguration>;
+export {};

package/dist/lib/types/config/PluginsConfiguration.d.ts

@@ -1,5 +1,5 @@
-import { JSONObject } from "kuzzle-sdk";
-import { PasswordPolicy } from "../index";
+import type { JSONObject } from "../JSONObject";
+import type { PasswordPolicy } from "../index";
 export type PluginsConfiguration = {
     /**
      * Common configuration for all plugins.
@@ -166,5 +166,6 @@ export type PluginsConfiguration = {
          */
         passwordPolicies: PasswordPolicy[];
     };
+} & {
     [pluginName: string]: JSONObject;
 };

package/dist/lib/types/config/SecurityConfiguration.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
-import { JSONObject } from "kuzzle-sdk";
-import { RoleDefinition, ProfileDefinition } from "../index";
+import type { JSONObject } from "../JSONObject";
+import type { RoleDefinition, ProfileDefinition } from "../index";
 export type SecurityConfiguration = {
     /**
      * Debugger configuration
@@ -22,6 +22,10 @@ export type SecurityConfiguration = {
     restrictedProfileIds: string[];
     /**
      * @deprecated Use `security.authToken` instead.
+     *
+     * `default.config.ts` always ships it, and `authToken`'s readers fall back
+     * to it — `authToken.algorithm ?? jwt.algorithm`. Optional all the same, as
+     * v2.56.0 declared it: a required member breaks code that builds this type.
      */
     jwt?: JSONObject;
     /**

package/dist/lib/types/config/ServerConfiguration.d.ts

@@ -1,5 +1,5 @@
-import { KuzzleLoggerConfig } from "kuzzle-logger";
-import { JSONObject } from "kuzzle-sdk";
+import type { KuzzleLoggerConfig } from "kuzzle-logger";
+import type { JSONObject } from "../JSONObject";
 export type ServerConfiguration = {
     /**
      * The maximum size of an incoming request.

package/dist/lib/types/config/ServicesConfiguration.d.ts

@@ -1,4 +1,4 @@
-import { PublicCacheRedisConfiguration, InternalCacheConfiguration, StorageEngineElasticsearch } from "../index";
+import type { PublicCacheRedisConfiguration, InternalCacheConfiguration, StorageEngineElasticsearch } from "../index";
 export type ServicesConfiguration = {
     common: {
         /**

package/dist/lib/types/config/cache/BaseCacheRedisConfiguration.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The cache service relies on Redis sample settings for Redis service (see also https://github.com/luin/ioredis)
+ *
+ * 1. using a single Redis database:
+ *  * node:
+ *    * host:
+ *        The host on which Redis can be reached.
+ *        Can take an IP address, an URI or a hostname
+ *    * port:
+ *        The port on which Redis is running its database:
+ *          * (optional, deprecated) database:
+ *        ID of the redis database (default: 0)
+ *        NOTE: this option is deprecated and will be removed in Kuzzle v3.
+ *        Use 'options.db' instead. If both options are set, then
+ *        "options.db" will take precedence.
+ *  * (optional) options:
+ *    Redis specific options compatible with IORedis.
+ *    See Redis client constructor available options:
+ *    https://github.com/luin/ioredis/blob/master/API.md#new-redisport-host-options
+ *
+ * 2. using a master/slaves Redis instance with Redis sentinels
+ *   (cf. http://redis.io/topics/sentinel):
+ *  * node:
+ *    * sentinels:
+ *        array of sentinels instances:
+ *          * host:
+ *              Host name/address of the sentinel server
+ *              Can be an IP address, an URI or a hostname
+ *          * port:
+ *              Network port opened by Redis on the sentinel server
+ *    * name:
+ *        Group of Redis instances composed of a master and one
+ *        or more slaves
+ *    * (optional, deprecated) database:
+ *        ID of the redis database (default: 0)
+ *        NOTE: this option is deprecated and will be removed in Kuzzle v3.
+ *              Use 'options.db' instead. If both options are set, then
+ *              "options.db" will take precedence.
+ *  * (optional) options:
+ *      Redis specific options compatible with IORedis.
+ *      See Redis client constructor available options:
+ *      https://github.com/luin/ioredis/blob/master/API.md#redis--eventemitter
+ *
+ * 3. using a redis cluster (cf. http://redis.io/topics/cluster-spec):
+ *   * nodes: array of master nodes of the cluster
+ *     * host:
+ *         Host name/address of a redis cluster node
+ *         Can be an IP address, an URI or a hostname
+ *     * port:
+ *        Network port opened by the redis cluster node
+ *   * (optional, deprecated) database:
+ *       ID of the redis database (default: 0)
+ *       NOTE: this option is deprecated and will be removed in Kuzzle v3.
+ *             Use 'options.db' instead. If both options are set, then
+ *             "options.db" will take precedence.
+ *   * (optional) options:
+ *       Redis specific options compatible with IORedis.
+ *       See Redis client constructor available options:
+ *       https://github.com/luin/ioredis/blob/master/API.md#new-redisport-host-options
+ *   * (optional) clusterOptions:
+ *       Redis Cluster specific options compatible with IORedis.
+ *       See Redis Cluster client constructor available options:
+ *       https://github.com/luin/ioredis/blob/master/API.md#new-clusterstartupnodes-options
+ *   * (optional) overrideDnsLookup:
+ *       Only available when using a Redis Cluster config.
+ *       Use with caution: if set to true, it makes Kuzzle skip DNS validation for TLS certificates
+ *       This is the only way to connect to an AWS Elasticache Cluster with TLS encryption.
+ *       See: https://github.com/luin/ioredis#special-note-aws-elasticache-clusters-with-tls
+ */
+export type BaseCacheRedisConfiguration = {
+    /**
+     * @default 'redis'
+     */
+    backend: "redis";
+    clusterOptions: {
+        /**
+         * @default true
+         */
+        enableReadyCheck: boolean;
+        /**
+         * Custom DNS lookup function, automatically set when `overrideDnsLookup`
+         * is true. Only relevant when using a Redis Cluster config.
+         */
+        dnsLookup?: (address: string, callback: (err: Error | null, address: string) => void) => void;
+    };
+    node: {
+        /**
+         * @default 'localhost'
+         */
+        host: string;
+        /**
+         * @default 6379
+         */
+        port: number;
+    };
+    /**
+     * Array of master nodes of the cluster. Only used when configuring a
+     * Redis Cluster (see option 3 in the docblock above).
+     */
+    nodes?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /**
+     * * (optional) options:
+     *    Redis specific options compatible with IORedis.
+     *    See Redis client constructor available options:
+     *    https://github.com/luin/ioredis/blob/master/API.md#new-redisport-host-options
+     *
+     */
+    options?: Record<string, unknown>;
+    /**
+     * Only available when using a Redis Cluster config.
+     * Use with caution: if set to true, it makes Kuzzle skip DNS validation for TLS certificates
+     * This is the only way to connect to an AWS Elasticache Cluster with TLS encryption.
+     *  See: https://github.com/luin/ioredis#special-note-aws-elasticache-clusters-with-tls
+     * @default false
+     */
+    overrideDnsLookup: boolean;
+    /**
+     * Service initialization timeout, in milliseconds. Falls back to
+     * `config.services.common.defaultInitTimeout` when not set.
+     */
+    initTimeout?: number;
+    /**
+     * Delay, in milliseconds, between application-level pings sent to keep
+     * the connection alive (e.g. required by some managed Redis providers).
+     * Disabled when not set.
+     */
+    pingKeepAlive?: number;
+};

package/dist/lib/types/config/cache/BaseCacheRedisConfiguration.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=BaseCacheRedisConfiguration.js.map