kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/api/request/requestResponse.js

@@ -76,7 +76,8 @@ class Headers {
         if (!name) {
             return;
         }
-        return this.headers[this.namesMap.get(name.toLowerCase())];
+        const storedName = this.namesMap.get(name.toLowerCase());
+        return storedName === undefined ? undefined : this.headers[storedName];
     }
     removeHeader(name) {
         assert.assertString("header name", name);
@@ -185,6 +186,11 @@ class RequestResponse {
     get error() {
         return this[_request].error;
     }
+    /**
+     * Narrower than the getter on purpose: `setError` throws an InternalError on
+     * anything that is not an Error, so assigning null here has never cleared the
+     * error — `KuzzleRequest.clearError()` is what does that.
+     */
     set error(e) {
         this[_request].setError(e);
     }
@@ -249,13 +255,26 @@ class RequestResponse {
      * Configure the response
      *
      * @param [options]
+     * @param [options.result] - Response result. Set only when the key is
+     *   present, so `{ result: null }` clears it; the status is left to the
+     *   `status` option, unlike the `result` setter, which resets it to 200
      * @param [options.headers] - Additional protocol headers
-     * @param [options.status=200] - HTTP status code
+     * @param [options.status] - HTTP status code. When absent, a pending 102
+     *   becomes 200 and any other status is kept
      * @param [options.format] - Response format, standard or raw
      *
+     * @throws {InternalError} if the result is an Error
+     * @throws {api.assert.forbidden_stream} if the result is an HttpStream and
+     *   the protocol is not HTTP
+     *
      * @returns void
      */
     configure(options = {}) {
+        // First, so that a refused result (an Error, a stream outside HTTP)
+        // throws before anything else is changed.
+        if ("result" in options) {
+            this[_request].assignResult(options.result);
+        }
         if (options.headers) {
             this.setHeaders(options.headers);
             for (const key of Object.keys(options.headers)) {
@@ -279,20 +298,32 @@ class RequestResponse {
     }
     /**
      * Gets a header value (case-insensitive)
+     *
+     * A missing header gives `undefined`, as it always has. The declared
+     * `string | null` is v2.56.0's, which code compiled against it assigns to
+     * a `string | null` — so test a result with `== null`, which covers both.
      */
     getHeader(name) {
         return this[_headers].getHeader(name);
     }
     /**
      * Deletes a header (case-insensitive)
+     *
+     * Answers `true`. Declared `any`, as v2.56.0 declared it: a `boolean`
+     * breaks code compiled against that, e.g. `return` of it from a function
+     * declared `void`.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- v2.56.0's public type, kept for compatibility
     removeHeader(name) {
         return this[_headers].removeHeader(name);
     }
     /**
      * Sets a new array. Behaves the same as Node.js' HTTP response.setHeader
      * method (@see https://nodejs.org/api/http.html#http_response_setheader_name_value)
+     *
+     * Answers `true`, declared `any` for the reason given on `removeHeader`.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- v2.56.0's public type, kept for compatibility
     setHeader(name, value) {
         return this[_headers].setHeader(name, value);
     }
@@ -325,7 +356,7 @@ class RequestResponse {
         }
         const filteredHeaders = {};
         for (const name of this[_userHeaders]) {
-            filteredHeaders[name] = this.getHeader(name);
+            filteredHeaders[name] = this[_headers].getHeader(name);
         }
         /**
          * Remove headers that are not allowed to be sent to the client in the response's body

package/dist/lib/cluster/command.d.ts

@@ -1,15 +1,100 @@
-export = ClusterCommand;
+/// <reference types="node" />
+/// <reference types="node" />
+import Long from "long";
+import type { SerializedState } from "./state";
+import type { Activity, Decoded, FullStateResponse, HandshakeResponse } from "./protobuf/commandMessages";
+/**
+ * What the command layer needs from the node that owns it. Declared
+ * structurally rather than as `ClusterNode` because `node.ts` imports this
+ * file: naming the class here would close the cycle.
+ */
+type CommandingNode = {
+    /**
+     * Only the two settings this file reads, not the whole cluster config: the
+     * real `IKuzzleConfiguration["cluster"]` satisfies this structurally, and
+     * stating it this way makes a widening of the coupling visible instead of
+     * silent.
+     */
+    config: {
+        ports: {
+            command: number;
+        };
+        syncTimeout: number;
+    };
+    ip: string;
+    nodeId: string;
+    activity: Activity[];
+    /** Only `serialize()`: the command layer never mutates the state. */
+    fullState: {
+        serialize(): SerializedState;
+    };
+    publisher: {
+        lastMessageId: Long;
+        replay(from: Long, to: Long): Array<{
+            topic: string;
+            data: Uint8Array;
+        }> | null;
+    };
+    remoteNodes: Map<string, {
+        lastMessageId: Long;
+    }>;
+    addNode(id: string, ip: string, lastMessageId: Long): Promise<boolean>;
+};
+/**
+ * The handshake responses `broadcastHandshake()` returns, keyed by node id. A
+ * `null` means the node never answered, and its caller disposes of it.
+ */
+type HandshakeResponses = Record<string, Decoded<HandshakeResponse> | null>;
 declare class ClusterCommand {
+    private readonly node;
+    private _server;
+    private _protoroot;
+    /**
+     * The REP socket and the protobuf schema, both built by `init()`.
+     *
+     * Every method below runs on a command layer that has been initialised —
+     * `listen()` is started by `init()` itself, and the rest answer requests it
+     * received — and all eleven dereferenced them unchecked. Same shape as
+     * `Protocol.entryPoint`: said once, where it can fail.
+     */
+    private get server();
+    private set server(value);
+    private get protoroot();
+    private set protoroot(value);
+    /**
+     * One of `stateEnum`'s values. `number` and not the literal union for the
+     * same reason as `subscriber.ts`'s `state`: `dispose()` moves it to `CLOSED`
+     * while `listen()` is awaiting a socket read, which control-flow narrowing
+     * does not model — it would report the deliberate re-check after the `await`
+     * as an impossible comparison.
+     */
+    private state;
+    private readonly logger;
+    /**
+     * Whether `listen()`'s loop is running: `init()` starts it without awaiting
+     * it, and `dispose()` is what stops it.
+     *
+     * The flag itself stays private — its values are this file's business — but
+     * *whether the command layer is listening* is a legitimate question from
+     * outside, and it is the one the spec was reading `state` to answer. See
+     * docs/adr-001/steps/14-test-program-strict.md (M6).
+     */
+    get running(): boolean;
     /**
-     * @constructor
-     * @param {ClusterNode} localNode
+     * @param localNode the cluster node this command layer belongs to
      */
-    constructor(localNode: ClusterNode);
-    node: ClusterNode;
-    server: Reply;
-    protoroot: protobuf.Root;
-    state: 1;
-    logger: import("../kuzzle/Logger").Logger;
+    constructor(localNode: CommandingNode);
+    /**
+     * Loads the wire schema, and nothing else.
+     *
+     * This class is two things: the **server** every node runs, and the
+     * **client** `getFullState()` and `broadcastHandshake()` use to call its
+     * peers. Both need the codec; only the first needs a bound port. `init()`
+     * did both, so a client-only use had to either bind a port it does not serve
+     * on — the port it means to *dial*, which is already taken — or reach into
+     * `protoroot`, which is what the spec did before step 14's M6.
+     */
+    loadProtobuf(): Promise<void>;
     init(): Promise<void>;
     serve(): Promise<void>;
     /**
@@ -17,57 +102,66 @@ declare class ClusterCommand {
      * Do NOT await this method, it's meant to run indefinitely until the close()
      * method is invoked.
      * This method can (and should) never return a rejected promise.
-     *
-     * @returns {void}
      */
-    listen(): void;
+    listen(): Promise<void>;
     /**
      * Closes opened sockets and marks this server as closed.
-     * @return {void}
      */
     dispose(): void;
     /**
      * Sends back the full state to the requesting node
-     * @return {void}
      */
-    sendFullState(): void;
+    sendFullState(): Promise<void>;
     /**
      * Handles a handshake request from a remote node
-     * @return {void}
      */
-    handleHandshake(data: any): void;
+    handleHandshake(data: Buffer): Promise<void>;
+    /**
+     * Answers a peer that missed messages of this node's sync stream with those
+     * messages, as they were published — or with DISCARDED when they are no
+     * longer kept, which the peer treats as it treats a node that predates
+     * retransmission: it evicts itself (#2785).
+     */
+    handleRetransmit(data: Buffer): Promise<void>;
+    /**
+     * Asks the node at `ip` for the messages of its sync stream with ids `from`
+     * to `to`, both included.
+     *
+     * @returns the messages in order, as `[topic, data]` frames, or `null` if
+     *          the node could not provide all of them: it no longer keeps them,
+     *          predates retransmission (it answers DISCARDED to an unknown
+     *          topic), or did not answer within `cluster.syncTimeout`.
+     */
+    requestRetransmit(ip: string, from: Long, to: Long): Promise<Array<[topic: string, data: Buffer]> | null>;
     /**
      * Request the full state from ONE of the remote nodes of the cluster, AT
      * RANDOM (necessary to make sure we distribute the full state serialization
      * load across all nodes)
      *
-     * @param  {Array.<IdCard>} nodes
-     * @return {Object|null} Returns the fetched full state, or null if no node answered
+     * @returns the fetched full state, or null if no node answered
      */
-    getFullState(nodes: Array<IdCard>): any | null;
+    getFullState(nodes: Array<{
+        id: string;
+        ip: string;
+    }>): Promise<Decoded<FullStateResponse> | null>;
     /**
      * Sends a handshake request to other remote nodes and process their response
-     * Returns an object with the following structure:
      *
-     * {
-     *   [nodeId]: { added: <boolean>, lastMessageId: <number> },
-     *   [nodeId]: null, // no response received, node is probably dead
-     * }
-     *
-     * @param  {Array.<IdCard>} nodes
-     * @return {Object}
+     * @returns one entry per node: its decoded response, or `null` if it never
+     *          answered (the node is probably dead)
      */
-    broadcastHandshake(nodes: Array<IdCard>): any;
+    broadcastHandshake(nodes: Array<{
+        id: string;
+        ip: string;
+    }>): Promise<HandshakeResponses>;
     /**
      * Sends a handshake payload to a remote node, and waits for its response
      *
-     * @param  {string} id      - remote node ID
-     * @param  {string} ip      - remote node IP address
-     * @param  {Buffer} payload - handshake payload (protobuf encoded)
-     * @return {Object|null}    - handshake encoded response, or null if no
-     *                            response was received
+     * @param id      remote node ID
+     * @param ip      remote node IP address
+     * @param payload handshake payload (protobuf encoded)
+     * @returns the handshake encoded response, or null if none was received
      */
-    _sendSingleHandshake(id: string, ip: string, payload: Buffer): any | null;
+    _sendSingleHandshake(id: string, ip: string, payload: Uint8Array): Promise<Buffer | null>;
 }
-import { Reply } from "zeromq";
-import protobuf = require("protobufjs");
+export = ClusterCommand;