@ti-engine/core 1.8.1 → 1.9.0

package/types/components/exchange/message-exchange.d.ts

@@ -0,0 +1,306 @@
+export = MessageExchange;
+import MessageObserver = require("#message-observer");
+import type { Message } from "#definitions";
+import type MessageReceiver from "#message-receiver";
+import type MessageSender from "#message-sender";
+/** @import { Message } from "#definitions" */
+/** @import MessageReceiver from "#message-receiver" */
+/** @import MessageSender from "#message-sender" */
+/**
+ * An abstract class that defines a message exchange behavior.
+ * <br/>
+ * NOTE: While this sets the basis frame for the message-based communication between microservices, it has to be inherited and
+ * extended with additional logic that is NOT implemented here. For a working example please see {@link DefaultMessageExchange} class.
+ * <br/>
+ * NOTE: This class and its children are designed to be used internally by the {@link MessageDispatcher} and its related classes.
+ *
+ * @class MessageExchange
+ * @extends MessageObserver
+ * @abstract
+ * @public
+ */
+declare class MessageExchange extends MessageObserver {
+    #private;
+    /**
+     * @constructor
+     * @param {string} instanceID The unique identifier of the microservice instance using the message exchange.
+     * @param {string} serviceDomainName The domain name of the microservice using the message exchange.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(instanceID: string, serviceDomainName: string);
+    /**
+     * Property returning the configured connection name for the outgoing message requests.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get connectionNameRequestsOut(): string;
+    /**
+     * Used to set the connection name for the outgoing message requests.
+     *
+     * @property
+     * @param {string} value
+     * @public
+     */
+    static set connectionNameRequestsOut(value: string);
+    /**
+     * Property returning the configured connection name for the incoming message requests.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get connectionNameRequestsIn(): string;
+    /**
+     * Used to set the connection name for the incoming message requests.
+     *
+     * @property
+     * @param {string} value
+     * @public
+     */
+    static set connectionNameRequestsIn(value: string);
+    /**
+     * Property returning the configured connection name for the outgoing message responses.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get connectionNameResponsesOut(): string;
+    /**
+     * Used to set the connection name for the outgoing message responses.
+     *
+     * @property
+     * @param {string} value
+     * @public
+     */
+    static set connectionNameResponsesOut(value: string);
+    /**
+     * Property returning the configured connection name for the incoming message responses.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get connectionNameResponsesIn(): string;
+    /**
+     * Used to set the connection name for the incoming message responses.
+     *
+     * @property
+     * @param {string} value
+     * @public
+     */
+    static set connectionNameResponsesIn(value: string);
+    /**
+     * Property returning the identifier of the pending messages queue.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get pendingQueue(): string;
+    /**
+     * Property returning the identifier of the processed messages queue.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get processedQueue(): string;
+    /**
+     * Property returning the configured service instance ID.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get instanceID(): string;
+    /**
+     * Property returning the configured service domain name.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get serviceDomainName(): string;
+    /**
+     * Returns the currently configured {@link MessageSender} for outbound message requests.
+     *
+     * @property
+     * @returns {MessageSender}
+     * @public
+     */
+    get messageRequestsOut(): MessageSender;
+    /**
+     * Returns the currently configured {@link MessageSender} for outbound message responses.
+     *
+     * @property
+     * @returns {MessageSender}
+     * @public
+     */
+    get messageResponsesOut(): MessageSender;
+    /**
+     * Returns the currently configured {@link MessageReceiver} for inbound message requests.
+     *
+     * @property
+     * @returns {MessageReceiver}
+     * @public
+     */
+    get messageRequestsIn(): MessageReceiver;
+    /**
+     * Returns the currently configured {@link MessageReceiver} for inbound message responses.
+     *
+     * @property
+     * @returns {MessageReceiver}
+     * @public
+     */
+    get messageResponsesIn(): MessageReceiver;
+    /**
+     * Returns a flag indicating if the message exchange is configured for outbound communication.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get configuredOutbound(): boolean;
+    /**
+     * Returns a flag indicating if the message exchange is configured for inbound communication.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get configuredInbound(): boolean;
+    /**
+     * Should be used to enable all communication channels for messaging.
+     * <br/>
+     * NOTE: Override this to implement messaging initialization.
+     *
+     * @method
+     * @param {boolean} configureInbound If set to 'true' it tells the message exchange to set up inbound messaging.
+     * @param {boolean} configureOutbound If set to 'true' it tells the message exchange to set up outbound messaging.
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    enableMessaging(configureInbound: boolean, configureOutbound: boolean): Promise<any>;
+    /**
+     * Should be used to gracefully disable all communication channels for messaging.
+     * <br/>
+     * NOTE: Override this to implement graceful messaging shut down.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    disableMessaging(): Promise<any>;
+    /**
+     * Used to configure the message exchange for receiving inbound messages and returning responses to them.
+     * Should typically be called from an implemented {@link enableMessaging} method.
+     *
+     * @method
+     * @param {MessageReceiver} messageReceiverRequestsIn A message receiver that will handle the inbound messages.
+     * @param {MessageSender} messageSenderResponsesOut A message sender that will handle the sending of responses for the inbound messages.
+     * @public
+     */
+    configureInboundMessaging(messageReceiverRequestsIn: MessageReceiver, messageSenderResponsesOut: MessageSender): void;
+    /**
+     * Used to configure message exchange for sending messages and receiving responses to them.
+     * Should typically be called from an implemented {@link enableMessaging} method.
+     *
+     * @method
+     * @param {MessageSender} messageSenderRequestsOut A message sender that will handle the outbound messages.
+     * @param {MessageReceiver} messageReceiverResponsesIn A message receiver that will handle the returned responses for the outbound messages.
+     * @public
+     */
+    configureOutboundMessaging(messageSenderRequestsOut: MessageSender, messageReceiverResponsesIn: MessageReceiver): void;
+    /**
+     * Used to add an additional {@link MessageObserver} to the connection for the incoming message requests.
+     *
+     * @method
+     * @param {MessageObserver} messageObserver
+     * @public
+     */
+    addMessageObserverRequestsIn(messageObserver: MessageObserver): void;
+    /**
+     * Used to add an additional {@link MessageObserver} to the connection for the incoming message responses.
+     *
+     * @method
+     * @param {MessageObserver} messageObserver
+     * @public
+     */
+    addMessageObserverResponsesIn(messageObserver: MessageObserver): void;
+    /**
+     * Used to mark the connection with the provided identifier as disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionDisrupted(identifier: string): void;
+    /**
+     * Used to mark the connection with the provided identifier as recovered.
+     * <br/>
+     * NOTE: This will also result in enabling the message exchange if no connections are currently disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionRecovered(identifier: string): void;
+    /**
+     * Used to mark the connection with the provided identifier as disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionLost(identifier: string): void;
+    /**
+     * Used only for the message tracer.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {Message} message The message for processing.
+     * @returns {Message} The message that was received.
+     * @override
+     * @public
+     */
+    onMessage(identifier: string, message: Message): Message;
+    /**
+     * Used to check whether the connection with the provided identifier is currently in recovery mode.
+     *
+     * @method
+     * @param {string} identifier The identifier of the connection.
+     * @returns {boolean} Will return 'true' if the connection is currently disrupted and not yet recovered.
+     * @public
+     */
+    isConnectionInRecovery(identifier: string): boolean;
+    /**
+     * Used to send a message request. Override of this method assumes that the message itself contains enough
+     * information to determine the sending destination.
+     *
+     * @method
+     * @param {Message} message The message request to send.
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    sendMessageRequest(message: Message): Promise<any>;
+    /**
+     * Used to send a message response. Override of this method assumes that the message itself contains enough
+     * information to determine the sending destination.
+     *
+     * @method
+     * @param {Message} message The message response to send.
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    sendMessageResponse(message: Message): Promise<any>;
+}

package/types/components/exchange/message-handler.d.ts

@@ -0,0 +1,132 @@
+export = MessageHandler;
+import ConnectionObserver = require("#connection-observer");
+import type { Message } from "#definitions";
+import type MessageObserver from "#message-observer";
+/**
+ * An abstract class that defines a basic message handler behavior.
+ * <br/>
+ * NOTE: This class and its children are designed to be used internally by classes extending the {@link MessageObserver} class.
+ *
+ * @class MessageHandler
+ * @extends ConnectionObserver
+ * @abstract
+ * @public
+ */
+declare class MessageHandler extends ConnectionObserver {
+    #private;
+    /**
+     * @constructor
+     * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(identifier: string);
+    /**
+     * Indicates whether the message handler is currently available.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get isAvailable(): boolean;
+    /**
+     * Used to set the isAvailable flag.
+     * <br/>
+     * NOTE: For use by implementing classes only!
+     *
+     * @property
+     * @param {boolean} value
+     * @public
+     */
+    set isAvailable(value: boolean);
+    /**
+     * Returns the connection identifier.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get connectionIdentifier(): string;
+    /**
+     * Used to initialize and enable the communication capabilities of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    enable(): Promise<any>;
+    /**
+     * Used to shut down and disable the communication behavior of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    disable(): Promise<any>;
+    /**
+     * Used to create a security hash from the message.
+     *
+     * @method
+     * @param {Message} message
+     * @returns {string}
+     * @public
+     */
+    createMessageHash(message: Message): string;
+    /**
+     * Used to register a new {@link MessageObserver} for events related to the messages passing through this handler.
+     *
+     * @method
+     * @param {MessageObserver} messageObserver The {@link MessageObserver} that will be notified of any changes.
+     * @public
+     */
+    addMessageObserver(messageObserver: MessageObserver): void;
+    /**
+     * An event-triggered method that will notify any observers about a new message for handling.
+     * <br/>
+     * NOTE: Each observer will be notified in the order of their priority via their {@link MessageObserver.onMessage} method. Additionally, the message will be
+     * passed through each observer in the order of their priority. If the observer returns a modified message, it will be used instead of the original message!
+     *
+     * @method
+     * @param {Message} message
+     * @public
+     */
+    notifyMessageObservers(message: Message): void;
+    /**
+     * An event-triggered method that will notify any observers about the primary connection recovered state.
+     * <br/>
+     * NOTE: You can override this to add custom functionality but make sure to also call the base method
+     * using: super.onConnectionRecovered( identifier )
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     */
+    onConnectionRecovered(identifier: string): void;
+    /**
+     * An event-triggered method that will notify any observers about the primary connection disrupted state.
+     * <br/>
+     * NOTE: You can override this to add custom functionality but make sure to also call the base method
+     * using: super.onConnectionDisrupted( identifier )
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     */
+    onConnectionDisrupted(identifier: string): void;
+    /**
+     * An event-triggered method that will notify any observers about the primary connection having been lost.
+     * <br/>
+     * NOTE: You can override this to add custom functionality but make sure to also call the base method
+     * using: super.onConnectionLost( identifier )
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     */
+    onConnectionLost(identifier: string): void;
+}

package/types/components/exchange/message-memory-cache.d.ts

@@ -0,0 +1,84 @@
+export declare var create: (identifier: string) => MessageMemoryCache;
+import type ConnectionObserver from "#connection-observer";
+import type { Message } from "#definitions";
+/** @import ConnectionObserver from "#connection-observer" */
+/** @import { Message } from "#definitions" */
+/**
+ * Used to create a Redis Cache client wrapped in a specialized message memory cache interface.
+ *
+ * @class MessageMemoryCache
+ * @public
+ */
+declare class MessageMemoryCache {
+    #private;
+    /**
+     * @constructor
+     * @param {string} identifier The connection identifier for the Redis connection.
+     * @returns {MessageMemoryCache}
+     */
+    constructor(identifier: string);
+    /**
+     * Used to initialize the cache service.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    initialize(): Promise<any>;
+    /**
+     * Used to gracefully shut down the cache service.
+     *
+     * @method
+     * @param {number} [timeoutMs]
+     * @returns {Promise}
+     * @public
+     */
+    shutDown(timeoutMs?: number): Promise<any>;
+    /**
+     * Used to register a new {@link ConnectionObserver} for events related to the Redis connection state.
+     *
+     * @method
+     * @param {ConnectionObserver} connectionObserver The {@link ConnectionObserver} that will be notified of any changes.
+     * @public
+     */
+    addConnectionObserver(connectionObserver: ConnectionObserver): void;
+    /**
+     * Used to send a message to the specified route.
+     *
+     * @method
+     * @param {Message} message The message to send.
+     * @param {string} queue The destination queue for the message as recognized by the {@link MessageExchange} implementation.
+     * @returns {Promise<number>} Will return the destination queue length after adding the current message to it.
+     * @public
+     */
+    sendMessage(message: Message, queue: string): Promise<number>;
+    /**
+     * Used to store a message payload.
+     *
+     * @method
+     * @param {Object} payload
+     * @param {string} storeLocation
+     * @returns {Promise<string>} Will return a unique ID of the storage location for the payload.
+     * @public
+     */
+    storeMessagePayload(payload: Object, storeLocation: string): Promise<string>;
+    /**
+     * Used to receive a message from the specified queue.
+     *
+     * @method
+     * @param {string} queue
+     * @returns {Promise<Message>}
+     * @public
+     */
+    receiveMessage(queue: string): Promise<Message>;
+    /**
+     * Used to retrieve a message payload by its store ID.
+     *
+     * @method
+     * @param {Message} message
+     * @param {string} storeLocation
+     * @returns {Promise<Message>} Will return the message with its payload populated if such is found.
+     * @public
+     */
+    retrieveMessagePayload(message: Message, storeLocation: string): Promise<Message>;
+}

package/types/components/exchange/message-observer.d.ts

@@ -0,0 +1,87 @@
+export = MessageObserver;
+import ConnectionObserver = require("#connection-observer");
+import type { Message } from "#definitions";
+/** @import { Message } from "#definitions" */
+/**
+ * An abstract class that allows the child class to observe and take action on message events.
+ * <br/>
+ * NOTE: This class inherits {@link ConnectionObserver} so it can also act in that capacity.
+ *
+ * @class MessageObserver
+ * @extends ConnectionObserver
+ * @abstract
+ * @public
+ */
+declare class MessageObserver extends ConnectionObserver {
+    #private;
+    /**
+     * @constructor
+     * @param {number} [priority=0] The priority of this observer. Higher values indicate higher priority.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(priority?: number);
+    /**
+     * Returns the priority of this observer.
+     * <br/>
+     * NOTE: Higher values indicate higher priority.
+     *
+     * @property
+     * @returns {number}
+     */
+    get priority(): number;
+    /**
+     * Used to set the priority of this observer.
+     * <br/>
+     * NOTE: Higher values indicate higher priority.
+     *
+     * @property
+     * @param {number} value
+     */
+    set priority(value: number);
+    /**
+     * Needs to be invoked by the message handler once a message enters its logic for processing.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {Message} message The message for processing.
+     * @returns {Message} The message that was received.
+     * @virtual
+     * @public
+     */
+    onMessage(identifier: string, message: Message): Message;
+    /**
+     * Needs to be invoked by the connection handler when the connection is disrupted.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionDisrupted(identifier: string): void;
+    /**
+     * Needs to be invoked by the connection handler when the connection is recovered.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionRecovered(identifier: string): void;
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionLost(identifier: string): void;
+}

package/types/components/exchange/message-receiver.d.ts

@@ -0,0 +1,91 @@
+export = MessageReceiver;
+import MessageHandler = require("#message-handler");
+import type { Message } from "#definitions";
+/** @import { Message } from "#definitions" */
+/**
+ * An abstract class that defines a basic message receiver behavior.
+ *
+ * @class MessageReceiver
+ * @extends MessageHandler
+ * @abstract
+ * @public
+ */
+declare class MessageReceiver extends MessageHandler {
+    #private;
+    /**
+     * @constructor
+     * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
+     * @param {string} receiveQueue The queue from which the messages will be received.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(identifier: string, receiveQueue: string);
+    /**
+     * Property returning the configured receiving queue.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get receiveQueue(): string;
+    /**
+     * Indicates whether the receiver is currently receiving messages.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get isReceiving(): boolean;
+    /**
+     * Used to set the value of the {@link MessageReceiver#isReceiving} property.
+     *
+     * @property
+     * @param {boolean} value
+     * @public
+     */
+    set isReceiving(value: boolean);
+    /**
+     * Used to initialize and enable the communication capabilities of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    enable(): Promise<any>;
+    /**
+     * Used to shut down and disable the communication behavior of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    disable(): Promise<any>;
+    /**
+     * Used to receive messages.
+     * <br/>
+     * NOTE: This method will start a recursion of subsequent receive calls that will continue even if an individual message fetch fails.
+     *
+     * @method
+     * @recursion
+     * @public
+     */
+    receive(): void;
+    /**
+     * Used to receive messages.
+     * <br/>
+     * NOTE: This method will be called automatically even if overridden.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise<Message>}
+     * @abstract
+     * @public
+     */
+    onReceive(): Promise<Message>;
+}