kuzzle 2.56.0 → 2.57.0-beta.2

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

@@ -1,52 +1,91 @@
-export = ClusterSubscriber;
+/// <reference types="node" />
+/// <reference types="node" />
+import Long from "long";
+import type { IKuzzleConfiguration } from "../types/config/KuzzleConfiguration";
+import type State from "./state";
+import type { AddCollectionMessage, AddIndexMessage, ClusterWideEventMessage, DocumentNotificationMessage, DumpRequestMessage, InvalidateProfileMessage, InvalidateRoleMessage, NewAuthStrategyMessage, NewRealtimeRoomMessage, NodeEvictedMessage, NodePreventEvictionMessage, NodeShutdownMessage, RemoveAuthStrategyMessage, RemoveCollectionMessage, RemoveIndexesMessage, RemoveRealtimeRoomMessage, SubscriptionMessage, SyncMessage, SyncMessages, SyncTopic, UnsubscriptionMessage, UserNotificationMessage } from "./protobuf/syncMessages";
+/**
+ * A frame as `protobufjs` hands it back, before `validateMessage()` has
+ * established that it carries the `messageId` every sync message must have.
+ */
+type DecodedMessage = Partial<SyncMessage> & Record<string, unknown>;
+/**
+ * What a subscriber needs from the node that owns it. `node.js` is converted in
+ * J3; this is the part of its surface this file actually reads.
+ */
+type SubscribingNode = {
+    config: IKuzzleConfiguration["cluster"];
+    heartbeatDelay: number;
+    nodeId: string;
+    fullState: State;
+    eventEmitter: {
+        emit(event: string, payload: unknown): void;
+    };
+    evictNode(nodeId: string, options: {
+        broadcast: boolean;
+        reason: string;
+    }): Promise<void>;
+    evictSelf(reason: string, error?: Error): Promise<void>;
+    command: {
+        requestRetransmit(ip: string, from: Long, to: Long): Promise<BufferedFrame[] | null>;
+    };
+};
+/**
+ * A topic's handler, as the dispatch table holds it: each one is declared with
+ * the message type `sync.proto` gives its topic, so registering a handler under
+ * the wrong topic stops compiling.
+ */
+type SyncMessageHandlers = {
+    [T in SyncTopic]: (message: SyncMessages[T]) => void | Promise<void>;
+};
+/** One raw frame as it comes off the socket, before it is decoded. */
+type BufferedFrame = [topic: string, data: Buffer];
 declare class ClusterSubscriber {
-    /**
-     * @constructor
-     * @param {ClusterNode} localNode
-     * @param {string} remoteNodeId - Remote node unique ID
-     * @param {string} remoteNodeIP - address of the distant node
-     */
-    constructor(localNode: ClusterNode, remoteNodeId: string, remoteNodeIP: string);
-    localNode: ClusterNode;
-    remoteNodeIP: string;
-    remoteNodeAddress: string;
-    remoteNodeId: string;
+    static readonly stateEnum: Readonly<{
+        BUFFERING: 1;
+        SANE: 2;
+        MISSING_HEARTBEAT: 3;
+        EVICTED: 4;
+    }>;
+    private readonly localNode;
+    readonly remoteNodeIP: string;
+    private readonly remoteNodeAddress;
+    readonly remoteNodeId: string;
+    /** Used in debug mode when the node might be slower */
     remoteNodeEvictionPrevented: boolean;
-    socket: Subscriber;
-    protoroot: protobuf.Root;
+    private socket;
+    private protoroot;
+    /** keeps track of received message ids from the remote node */
     lastMessageId: Long;
-    state: 1;
-    buffer: any[];
-    heartbeatTimer: NodeJS.Timeout;
+    subscriptionConfirmed: boolean;
+    private readonly subscriptionProof;
+    private confirmSubscription;
+    /**
+     * One of the values of `stateEnum`. Deliberately `number` and not the
+     * literal union `1 | 2 | 3 | 4`: `state` is mutated by other methods while
+     * `listen()` is awaiting a socket read, and TypeScript's control-flow
+     * narrowing does not model that — under the literal union it reports the
+     * deliberate re-checks after an `await` as impossible comparisons. Those
+     * re-checks are the point.
+     */
+    state: number;
+    private buffer;
+    /**
+     * Whether `recover()` is running: waiting for the remote node to retransmit
+     * what was lost, or applying it.
+     */
+    private recovering;
+    private heartbeatTimer;
     lastHeartbeat: number;
-    heartbeatDelay: number;
-    handlers: Readonly<{
-        AddCollection: (message: any) => void;
-        AddIndex: (message: any) => void;
-        ClusterWideEvent: (message: any) => void;
-        DocumentNotification: (message: any) => void;
-        DumpRequest: (message: any) => void;
-        Heartbeat: () => void;
-        InvalidateProfile: (message: any) => void;
-        InvalidateRole: (message: any) => void;
-        NewAuthStrategy: (message: any) => void;
-        NewRealtimeRoom: (message: any) => void;
-        NodeEvicted: (message: any) => void;
-        NodePreventEviction: (message: any) => Promise<void>;
-        NodeShutdown: (message: any) => void;
-        RefreshIndexCache: () => Promise<void>;
-        RefreshValidators: () => void;
-        RemoveAuthStrategy: (message: any) => void;
-        RemoveCollection: (message: any) => void;
-        RemoveIndexes: (message: any) => void;
-        RemoveRealtimeRoom: (message: any) => void;
-        ResetSecurity: () => void;
-        Shutdown: () => void;
-        Subscription: (message: any) => void;
-        Unsubscription: (message: any) => void;
-        UserNotification: (message: any) => void;
-    }>;
-    logger: import("../kuzzle/Logger").Logger;
+    private readonly heartbeatDelay;
+    readonly handlers: Readonly<SyncMessageHandlers>;
+    private readonly logger;
+    /**
+     * @param localNode the cluster node this subscriber belongs to
+     * @param remoteNodeId - Remote node unique ID
+     * @param remoteNodeIP - address of the distant node
+     */
+    constructor(localNode: SubscribingNode, remoteNodeId: string, remoteNodeIP: string);
     /**
      * Initializes this class, establishes a connection to the remote node and
      * starts listening to it.
@@ -58,14 +97,41 @@ declare class ClusterSubscriber {
      * return (unless the remote node has been evicted)
      */
     listen(): Promise<void>;
+    /**
+     * One frame off the sync socket.
+     *
+     * @returns `null` when there is nothing more to read — the socket is gone,
+     *          or the read failed and this node has been evicted for it, which
+     *          is what ends `listen()`'s loop.
+     */
+    private receiveFrame;
+    /**
+     * Resolves once a message has been received from the remote node, which is
+     * the only observable proof that this subscription is live on its side.
+     *
+     * The handshake reads a remote node's `lastMessageId` over the *command*
+     * channel and then resumes this subscription from it. Nothing orders that
+     * snapshot after the subscription taking effect on the *sync* channel — they
+     * are different sockets — so without this wait, anything the remote publishes
+     * in between is dropped by its PUB socket while this node is told to resume
+     * from just before it. That gap is read as a desync. See TD-65 (#2773).
+     *
+     * Every node publishes a heartbeat every `cluster.heartbeat` ms (2s by
+     * default) from before it is discoverable, so this normally costs less than
+     * one round.
+     *
+     * @param timeout - ms to wait before giving up
+     * @return whether the subscription was proven live
+     */
+    waitForSubscription(timeout: number): Promise<boolean>;
     /**
      * Plays all buffered sync messages, and switches this subscriber state from
      * BUFFERING to SANE.
      *
-     * @param  {Long} lastMessageId
-     * @return {void}
+     * @param lastMessageId
+     * @return false if a gap was found while replaying, which evicts this node
      */
-    sync(lastMessageId: Long): void;
+    sync(lastMessageId: Long): Promise<boolean>;
     /**
      * Decodes an incoming message, and dispatches it.
      * The topic name must match a protobuf message.
@@ -75,119 +141,111 @@ declare class ClusterSubscriber {
      * and it also cannot afford to attach a rejection handler everytime a message
      * is received to prevent clogging the event loop with unnecessary promises
      *
-     * @param  {string} topic
-     * @param  {Buffer} data
-     * @return {void}
+     * @param topic
+     * @param data
      */
-    processData(topic: string, data: Buffer): void;
-    handleNodePreventEviction(message: any): Promise<void>;
+    processData(topic: string, data: Buffer): Promise<void>;
+    /**
+     * Set from two places: a `NodePreventEviction` message published by this
+     * peer, and `node.preventEviction()` on this node. The local caller used to
+     * reach the wire handler below with a hand-built `{ evictionPrevented }` —
+     * an object shaped like a sync message that never came off the wire and
+     * carries no `messageId`. The conversion could not type that, and it should
+     * not have to: the two callers want the same effect, not the same envelope.
+     */
+    setEvictionPrevented(evictionPrevented: boolean): void;
+    handleNodePreventEviction(message: NodePreventEvictionMessage): Promise<void>;
     /**
      * Handles a heartbeat from the remote node
      *
-     * @return {void}
      */
     handleHeartbeat(): void;
     /**
      * Handles a node eviction message.
      *
-     * @param  {Object} message - decoded NodeEvicted protobuf message
-     * @return {void}
+     * @param message - decoded NodeEvicted protobuf message
      */
-    handleNodeEviction(message: any): void;
+    handleNodeEviction(message: NodeEvictedMessage): Promise<void>;
     /**
      * Handles a node shutdown.
      *
-     * @param  {Object} message - decoded NodeShutdown protobuf message
-     * @return {void}
+     * @param message - decoded NodeShutdown protobuf message
      */
-    handleNodeShutdown(message: any): void;
+    handleNodeShutdown(message: NodeShutdownMessage): Promise<void>;
     /**
      * Handles messages about realtime room creations
      *
-     * @param  {Object} message - decoded NewRealtimeRoom protobuf message
-     * @return {void}
+     * @param message - decoded NewRealtimeRoom protobuf message
      */
-    handleNewRealtimeRoom(message: any): void;
+    handleNewRealtimeRoom(message: NewRealtimeRoomMessage): void;
     /**
      * Handles messages about realtime subscriptions
      *
-     * @param  {Object} message - decoded Subscription protobuf message
-     * @return {void}
+     * @param message - decoded Subscription protobuf message
      */
-    handleSubscription(message: any): void;
+    handleSubscription(message: SubscriptionMessage): void;
     /**
      * Handles messages about realtime room removal
      *
-     * @param  {Object} message - decoded RemoveRealtimeRoom protobuf message
-     * @return {void}
+     * @param message - decoded RemoveRealtimeRoom protobuf message
      */
-    handleRealtimeRoomRemoval(message: any): void;
+    handleRealtimeRoomRemoval(message: RemoveRealtimeRoomMessage): void;
     /**
      * Handles messages about user unsubscriptions
      *
-     * @param  {Object} message - decoded Unscription protobuf message
-     * @return {void}
+     * @param message - decoded Unsubscription protobuf message
      */
-    handleUnsubscription(message: any): void;
+    handleUnsubscription(message: UnsubscriptionMessage): void;
     /**
      * Handles messages about cluster-wide events
      *
-     * @param {Object} message - decoded ClusterWideEvent protobuf message
-     * @return {void}
+     * @param message - decoded ClusterWideEvent protobuf message
      */
-    handleClusterWideEvent(message: any): void;
+    handleClusterWideEvent(message: ClusterWideEventMessage): void;
     /**
      * Handles messages about document notifications
      *
-     * @param {Object} message - decoded DocumentNotification protobuf message
-     * @return {void}
+     * @param message - decoded DocumentNotification protobuf message
      */
-    handleDocumentNotification(message: any): void;
+    handleDocumentNotification(message: DocumentNotificationMessage): Promise<void>;
     /**
      * Handles messages about user notifications
      *
-     * @param {Object} message - decoded UserNotification protobuf message
-     * @return {void}
+     * @param message - decoded UserNotification protobuf message
      */
-    handleUserNotification(message: any): void;
+    handleUserNotification(message: UserNotificationMessage): Promise<void>;
     /**
      * Handles messages about new authentication strategies
      *
-     * @param  {Object} message - decoded NewAuthStrategy protobuf message
-     * @return {void}
+     * @param message - decoded NewAuthStrategy protobuf message
      */
-    handleNewAuthStrategy(message: any): void;
+    handleNewAuthStrategy(message: NewAuthStrategyMessage): void;
     /**
      * Handles messages about authentication strategy removals
      *
-     * @param  {Object} message - decoded RemoveAuthStrategy protobuf message
-     * @return {void}
+     * @param message - decoded RemoveAuthStrategy protobuf message
      */
-    handleAuthStrategyRemoval(message: any): void;
+    handleAuthStrategyRemoval(message: RemoveAuthStrategyMessage): void;
     /**
      * Handles messages about security resets
      *
-     * @return {void}
      */
-    handleResetSecurity(): void;
+    handleResetSecurity(): Promise<void>;
     /**
      * Handles a cross-nodes dump request
      *
-     * @param {Object} message - decoded DumpRequest protobuf message
-     * @return {void}
+     * @param message - decoded DumpRequest protobuf message
      */
-    handleDumpRequest(message: any): void;
+    handleDumpRequest(message: DumpRequestMessage): void;
     /**
      * Handles cluster-wide shutdown
-     * @return {void}
      */
     handleShutdown(): void;
     /**
      * Handles changes on document validators
      *
-     * @return {void}
      */
-    handleRefreshValidators(): void;
+    handleRefreshValidators(): Promise<void>;
     /**
      * Handles manual refresh of the index cache
      */
@@ -195,45 +253,39 @@ declare class ClusterSubscriber {
     /**
      * Invalidates a profile to force reloading it from the storage space
      *
-     * @param {Object} message - decoded DumpRequest protobuf message
-     * @return {void}
+     * @param message - decoded InvalidateProfile protobuf message
      */
-    handleProfileInvalidation(message: any): void;
+    handleProfileInvalidation(message: InvalidateProfileMessage): Promise<void>;
     /**
      * Invalidates a role to force reloading it from the storage space
      *
-     * @param {Object} message - decoded DumpRequest protobuf message
-     * @return {void}
+     * @param message - decoded InvalidateRole protobuf message
      */
-    handleRoleInvalidation(message: any): void;
+    handleRoleInvalidation(message: InvalidateRoleMessage): Promise<void>;
     /**
      * Adds a new index to the index cache
      *
-     * @param {Object} message - decoded IndexCacheAdd protobuf message
-     * @return {void}
+     * @param message - decoded AddIndex protobuf message
      */
-    handleIndexAddition(message: any): void;
+    handleIndexAddition(message: AddIndexMessage): Promise<void>;
     /**
      * Removes indexes from the index cache
      *
-     * @param {Object} message - decoded IndexCacheAdd protobuf message
-     * @return {void}
+     * @param message - decoded RemoveIndexes protobuf message
      */
-    handleIndexesRemoval(message: any): void;
+    handleIndexesRemoval(message: RemoveIndexesMessage): Promise<void>;
     /**
      * Adds a new collection to the index cache
      *
-     * @param {Object} message - decoded IndexCacheAdd protobuf message
-     * @return {void}
+     * @param message - decoded AddCollection protobuf message
      */
-    handleCollectionAddition(message: any): void;
+    handleCollectionAddition(message: AddCollectionMessage): Promise<void>;
     /**
      * Removes a collection from the index cache
      *
-     * @param {Object} message - decoded IndexCacheAdd protobuf message
-     * @return {void}
+     * @param message - decoded RemoveCollection protobuf message
      */
-    handleCollectionRemoval(message: any): void;
+    handleCollectionRemoval(message: RemoveCollectionMessage): Promise<void>;
     /**
      * Checks that we did receive a heartbeat from the remote node
      * If a heartbeat is missing, we allow 1 heartbeat round for the remote node
@@ -246,24 +298,26 @@ declare class ClusterSubscriber {
     dispose(): void;
     /**
      * Checks that the received message is the one we expect.
-     * @param  {Object} message - decoded protobuf message
-     * @return {boolean} false: the message must be discarded, true otherwise
+     * @param message - decoded protobuf message
+     * @return false: the message must be discarded, true otherwise
      */
-    validateMessage(message: any): boolean;
-    evictNode({ broadcast, reason }: {
-        broadcast: any;
-        reason: any;
+    validateMessage(message: DecodedMessage): Promise<boolean>;
+    /**
+     * Fetches the messages with ids `from` to `upTo - 1` from the remote node,
+     * which keeps its last ones for that purpose, and applies them in order
+     * (#2785).
+     *
+     * Awaited where the gap is found, so nothing that came after it is applied
+     * before it: `listen()` stops reading meanwhile (ZeroMQ queues what arrives)
+     * and `sync()` stops replaying.
+     *
+     * @return whether every missing message was applied; `false` leaves the
+     *         decision — eviction — to the caller
+     */
+    private recover;
+    evictNode({ broadcast, reason, }: {
+        broadcast: boolean;
+        reason: string;
     }): Promise<void>;
 }
-declare namespace ClusterSubscriber {
-    export { stateEnum };
-}
-import { Subscriber } from "zeromq";
-import protobuf = require("protobufjs");
-import Long = require("long/umd/types");
-declare const stateEnum: Readonly<{
-    BUFFERING: 1;
-    SANE: 2;
-    MISSING_HEARTBEAT: 3;
-    EVICTED: 4;
-}>;
+export = ClusterSubscriber;