@ti-engine/core 1.8.1 → 1.9.0

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

@@ -0,0 +1,68 @@
+export = MessageSender;
+import MessageHandler = require("#message-handler");
+import type { Message } from "#definitions";
+/** @import { Message } from "#definitions" */
+/**
+ * An abstract class that defines a basic message sender behavior.
+ *
+ * @class MessageSender
+ * @extends MessageHandler
+ * @abstract
+ * @public
+ */
+declare class MessageSender extends MessageHandler {
+    #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);
+    /**
+     * 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 send a {@link Message} via this message handler.
+     *
+     * @method
+     * @param {Message} message The message to send.
+     * @param {string} queue The route to destination (queue) for the message as recognized by the {@link MessageExchange} implementation.
+     * @returns {Promise}
+     * @public
+     */
+    send(message: Message, queue: string): Promise<any>;
+    /**
+     * Used to perform the actual sending of a message.
+     * <br/>
+     * NOTE: This method will be called automatically even if overridden.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @param {Message} message The message to send.
+     * @param {string} queue The route to destination (queue) for the message as recognized by the {@link MessageExchange} implementation.
+     * @returns {Promise<*>}
+     * @abstract
+     * @public
+     */
+    onSend(message: Message, queue: string): Promise<any>;
+}

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

@@ -0,0 +1,84 @@
+export { messageTypeEnum as messageType };
+export { dispatchEventEnum as dispatchEvent };
+export { messageStateEnum as messageState };
+declare const _exported: Readonly<MessageTracer>;
+export { _exported as instance };
+import type { Message } from "#definitions";
+export type TiMessageType = number;
+/**
+ * Enum for listing message types.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiMessageType
+ */
+declare let messageTypeEnum: import("#definitions").TiEnumOf<{
+    MESSAGE_REQUEST: (string | number)[];
+    MESSAGE_RESPONSE: (string | number)[];
+}>;
+export type TiDispatchEvent = number;
+/**
+ * Enum for listing dispatch events.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiDispatchEvent
+ */
+declare let dispatchEventEnum: import("#definitions").TiEnumOf<{
+    DELIVERED: (string | number)[];
+    FAILED: (string | number)[];
+    RECEIVED: (string | number)[];
+    SENT: (string | number)[];
+}>;
+export type TiMessageState = number;
+/**
+ * Enum for listing message states.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiMessageState
+ */
+declare let messageStateEnum: import("#definitions").TiEnumOf<{
+    PENDING: (string | number)[];
+    PROCESSED: (string | number)[];
+}>;
+/**
+ * Used for recording message trace entries.
+ *
+ * @class MessageTracer
+ * @singleton
+ * @public
+ */
+declare class MessageTracer {
+    #private;
+    /**
+     * @constructor
+     * @return {MessageTracer}
+     */
+    constructor();
+    /**
+     * Used to initialize the message tracer.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    initialize(): Promise<any>;
+    /**
+     * Used to create a trace entry for the provided {@link Message} and parameters.
+     * <br/>
+     * NOTE: By default, all trace events are stored in the memory cache for further processing and analysis. The
+     * location is configured in the MESSAGE_EXCHANGE_TRACE_REPOSITORY setting.
+     * <br/>
+     * NOTE: Trace events are logged with severity level NOTICE or ERROR for failed dispatches. They still might be
+     * filtered out if the minimum log level setting is set too high.
+     *
+     * @method
+     * @param {Message} message The message to trace.
+     * @param {TiMessageType} messageType The type of the message.
+     * @param {TiDispatchEvent} dispatchEvent The event in the dispatch system that triggered the trace entry.
+     * @param {TiMessageState} messageState The state of the message processing.
+     * @public
+     */
+    recordTraceEntry(message: Message, messageType: TiMessageType, dispatchEvent: TiDispatchEvent, messageState: TiMessageState): void;
+}

package/types/components/service-caller.d.ts

@@ -0,0 +1,68 @@
+export = ServiceCaller;
+import MessageObserver = require("#message-observer");
+import type { ServiceAddress, ServiceCall, ServiceCallResult, ServiceExecContext } from "#definitions";
+/**
+ * A class defining a service caller behavior.
+ *
+ * @class ServiceCaller
+ * @extends MessageObserver
+ * @public
+ */
+declare class ServiceCaller extends MessageObserver {
+    #private;
+    /**
+     * @constructor
+     */
+    constructor();
+    /**
+     * Used to call a service in the service ecosystem asynchronously.
+     * <br/>
+     * NOTE: This method will time out after specific preconfigured time, in which case it will resolve with {@link E_COM_SERVICE_EXEC_TIMEOUT} error.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress The service address has to define a valid service domain name, service alias, and optionally a service version.
+     * @param {Object} serviceParams Set of named parameters to provide to the called service.
+     * @param {ServiceExecContext} serviceExecContext The context in which the service call is being executed.
+     * @returns {Promise<ServiceCallResult>} Will always return a service call result that can be either successful or not.
+     * @public
+     */
+    executeServiceCall(serviceAddress: ServiceAddress, serviceParams: Object, serviceExecContext: ServiceExecContext): Promise<ServiceCallResult>;
+    /**
+     * Once the proper message is received this method will trigger the completion of the pending {@link ServiceCall} execution started in {@link #executeServiceCall}.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {ServiceCall} serviceCall The service call message for processing.
+     * @returns {ServiceCall} The service call message that was received.
+     * @override
+     * @public
+     */
+    onMessage(identifier: string, serviceCall: ServiceCall): ServiceCall;
+    /**
+     * Needs to be invoked by the connection handler when the connection is disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionDisrupted(identifier: string): void;
+    /**
+     * Needs to be invoked by the connection handler when the connection is recovered.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionRecovered(identifier: string): void;
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionLost(identifier: string): void;
+}

package/types/components/service-consumer.d.ts

@@ -0,0 +1,81 @@
+export = ServiceConsumer;
+import ServiceInstance = require("#service-instance");
+import type { ServiceAddress, ServiceCallResult, ServiceConfiguration, ServiceExecContext } from "#definitions";
+/** @import { ServiceAddress, ServiceCallResult, ServiceConfiguration, ServiceExecContext } from "#definitions" */
+/**
+ * Abstract class used to define a Service Consumer behavior.
+ * <br/>
+ * NOTE: Inherit this to create a module that can be started as a microservice consumer instance.
+ * <br/>
+ * NOTE: A service consumer is a microservice that can invoke named business services in the APIs of other
+ * microservices using {@link ServiceCall} objects. The consumer does not need to know the specifics of
+ * the business logic in these services but only the service address and the inbound parameters (if any).
+ * The result of the execution will be returned to the consumer in a {@link ServiceCallResult} object.
+ *
+ * @class ServiceConsumer
+ * @extends ServiceInstance
+ * @abstract
+ * @public
+ */
+declare class ServiceConsumer extends ServiceInstance {
+    #private;
+    /**
+     * @constructor
+     * @param {string} serviceDomainName The service domain name for this service instance.
+     * @param {ServiceConfiguration} [serviceConfig] The JSON configuration for this service.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(serviceDomainName: string, serviceConfig?: ServiceConfiguration);
+    /**
+     * Perform initialization tasks when the service consumer starts.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStart logic you can override this method but make sure to call it in the
+     * overriding method using: super.onStart()
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStart(): Promise<any>;
+    /**
+     * Perform shut down and cleanup tasks when the service consumer stops.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStop logic you can override this method but make sure to call it in the
+     * overriding method using: super.onStop()
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStop(): Promise<any>;
+    /**
+     * Used to report health status of the service instance for external monitoring.
+     * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
+     * <br/>
+     * NOTE: By default this method will update a Redis key with an expiration timer. You can override this
+     * functionality with something custom like calling an HTTP endpoint.
+     *
+     * @method
+     * @override
+     * @virtual
+     * @public
+     */
+    reportHealthy(): void;
+    /**
+     * Used to invoke a business service in any {@link ServiceInstance}.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress
+     * @param {Object} serviceParams
+     * @param {ServiceExecContext} serviceExecContext
+     * @returns {Promise<ServiceCallResult>}
+     * @public
+     */
+    callService(serviceAddress: ServiceAddress, serviceParams: Object, serviceExecContext: ServiceExecContext): Promise<ServiceCallResult>;
+}

package/types/components/service-executor.d.ts

@@ -0,0 +1,101 @@
+export = ServiceExecutor;
+import MessageObserver = require("#message-observer");
+import ServiceInstance = require("#service-instance");
+import type { ServiceAddress, ServiceCall, ServiceDefinition, ServiceExecContext, ServiceInterface } from "#definitions";
+export type VerifyAccessMethod = (authToken: string, serviceAddress: ServiceAddress) => Promise<any>;
+export type ServiceHandlerMethod = (serviceDefinition: ServiceDefinition, serviceParams: Object, serviceExecContext: ServiceExecContext) => Promise<Object | undefined>;
+/** @import { ServiceAddress, ServiceCall, ServiceDefinition, ServiceExecContext, ServiceInterface } from "#definitions" */
+/**
+ * @callback VerifyAccessMethod
+ * @param {string} authToken
+ * @param {ServiceAddress} serviceAddress
+ * @returns {Promise<*>}
+ */
+/**
+ * @callback ServiceHandlerMethod
+ * @param {ServiceDefinition} serviceDefinition The service definition as provided during the service registration.
+ * @param {Object} serviceParams Set of named parameters provided to the called service.
+ * @param {ServiceExecContext} serviceExecContext The context in which the service call is being executed.
+ * @returns {Promise<Object|undefined>} Optional payload to be returned to the service caller.
+ */
+/**
+ * A class defining a service executor behavior.
+ *
+ * @class ServiceExecutor
+ * @extends MessageObserver
+ * @public
+ */
+declare class ServiceExecutor extends MessageObserver {
+    #private;
+    /**
+     * @constructor
+     */
+    constructor();
+    /**
+     * Property returning the current service interface.
+     *
+     * @property
+     * @returns {ServiceInterface}
+     * @public
+     */
+    get serviceInterface(): ServiceInterface;
+    /**
+     *
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {ServiceCall} serviceCall The service call message for processing.
+     * @returns {ServiceCall} The service call message that was received.
+     * @override
+     * @public
+     */
+    onMessage(identifier: string, serviceCall: ServiceCall): ServiceCall;
+    /**
+     * Needs to be invoked by the connection handler when the connection is disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionDisrupted(identifier: string): void;
+    /**
+     * Needs to be invoked by the connection handler when the connection is recovered.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionRecovered(identifier: string): void;
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionLost(identifier: string): void;
+    /**
+     * Used to set up the method for service access verification.
+     *
+     * @method
+     * @param {VerifyAccessMethod} verifyAccess
+     * @public
+     */
+    configureVerifyAccess(verifyAccess: VerifyAccessMethod): void;
+    /**
+     * Used to add a service handler to the service interface.
+     * <br/>
+     * NOTE: If the same version of the service handler already exists, it will be overridden!
+     *
+     * @method
+     * @param {ServiceHandlerMethod} serviceHandler
+     * @param {ServiceDefinition} serviceDefinition
+     * @param {ServiceInstance} serviceInstance This will be used as context to bind all business services.
+     * @returns {Promise}
+     * @public
+     */
+    addServiceHandler(serviceHandler: ServiceHandlerMethod, serviceDefinition: ServiceDefinition, serviceInstance: ServiceInstance): Promise<any>;
+}

package/types/components/service-instance.d.ts

@@ -0,0 +1,111 @@
+export = ServiceInstance;
+import type { ServiceConfiguration } from "#definitions";
+/** @import { ServiceConfiguration } from "#definitions" */
+/**
+ * Abstract class used to define a Service Instance behavior.
+ * <br/>
+ * NOTE: Inherit this to create a module that can be started as a microservice instance.
+ *
+ * @class ServiceInstance
+ * @abstract
+ * @public
+ */
+declare class ServiceInstance {
+    #private;
+    /**
+     * @constructor
+     * @param {string} serviceDomainName The service domain name for this service instance.
+     * @param {ServiceConfiguration} [serviceConfig={ services: [] }] The JSON configuration for this service.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_FEATURE_UNSUPPORTED} If multiple instances are started in the same process.
+     */
+    constructor(serviceDomainName: string, serviceConfig?: ServiceConfiguration);
+    /**
+     * Property returning the current service instance ID.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get instanceID(): string;
+    /**
+     * Property returning the current service domain name.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    static get serviceDomainName(): string;
+    /**
+     * Property to indicate that this and every child class is a {@link ServiceInstance}.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get isServiceInstance(): boolean;
+    /**
+     * Property returning the service configuration JSON.
+     *
+     * @property
+     * @returns {ServiceConfiguration}
+     * @public
+     */
+    get serviceConfig(): ServiceConfiguration;
+    /**
+     * Initializes the instance.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    start(): Promise<any>;
+    /**
+     * Executes custom logic on instance start.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStart logic, you can override this method but make sure to call it in the
+     * overriding method using: super.onStart()
+     *
+     * @method
+     * @returns {Promise}
+     * @virtual
+     * @public
+     */
+    onStart(): Promise<any>;
+    /**
+     * Shuts down the instance.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    stop(): Promise<any>;
+    /**
+     * Executes custom logic on instance stop.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStop logic, you can override this method but make sure to call it in the
+     * overriding method using: super.onStop()
+     *
+     * @method
+     * @returns {Promise}
+     * @virtual
+     * @public
+     */
+    onStop(): Promise<any>;
+    /**
+     * Used to report health status of the service instance for external monitoring.
+     * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
+     * <br/>
+     * NOTE: By default, this method will update a Redis key with an expiration timer. You can override this
+     * functionality with something custom like calling an HTTP endpoint.
+     *
+     * @method
+     * @virtual
+     * @public
+     */
+    reportHealthy(): void;
+}

package/types/components/service-provider.d.ts

@@ -0,0 +1,120 @@
+export = ServiceProvider;
+import ServiceConsumer = require("#service-consumer");
+import type { ServiceAddress, ServiceConfiguration, ServiceDefinition } from "#definitions";
+import type { ServiceHandlerMethod } from "#service-executor";
+/** @import { ServiceAddress, ServiceConfiguration, ServiceDefinition } from "#definitions" */
+/** @import { ServiceHandlerMethod } from "#service-executor" */
+/**
+ * Abstract class used to define a Service Provider behavior.
+ * <br/>
+ * NOTE: Inherit this to create a module that can be started as a microservice provider instance.
+ * <br/>
+ * NOTE: A service provider is a microservice that offers an API of named business services that can be invoked by other
+ * microservices using {@link ServiceCall} objects. The provider will take care of the actual execution of that service and
+ * therefore acts as a "black box". The only necessary items are the service address and optional inbound parameters to be
+ * used in that service's logic. The result of the service's execution will be bundled in an {@link ServiceCallResult}
+ * object and returned to the caller.
+ *
+ * @class ServiceProvider
+ * @extends ServiceConsumer
+ * @abstract
+ * @public
+ */
+declare class ServiceProvider extends ServiceConsumer {
+    #private;
+    /**
+     * @constructor
+     * @param {string} serviceDomainName The service domain name for this service instance.
+     * @param {ServiceConfiguration} [serviceConfig] The JSON configuration for this service.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(serviceDomainName: string, serviceConfig?: ServiceConfiguration);
+    /**
+     * Perform initialization tasks when the service provider starts.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStart logic, you can override this method but make sure to call it in the
+     * overriding method using: super.onStart()
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStart(): Promise<any>;
+    /**
+     * Perform shut down and cleanup tasks when the service provider stops.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStop logic, you can override this method but make sure to call it in the
+     * overriding method using: super.onStop()
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStop(): Promise<any>;
+    /**
+     * Used to report health status of the service instance for external monitoring.
+     * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
+     * <br/>
+     * NOTE: By default, this method will update a Redis key with an expiration timer. You can override this
+     * functionality with something custom like calling an HTTP endpoint.
+     *
+     * @method
+     * @override
+     * @virtual
+     * @public
+     */
+    reportHealthy(): void;
+    /**
+     * Used to verify whether the service caller has authorization to access the service.
+     * <br/>
+     * NOTE: Override this to implement authorization check. By default, this method simply returns.
+     *
+     * @method
+     * @param {string} authToken
+     * @param {ServiceAddress} serviceAddress
+     * @return {Promise}
+     * @virtual
+     * @public
+     */
+    verifyAccess(authToken: string, serviceAddress: ServiceAddress): Promise<any>;
+    /**
+     * Used to register a single service to the service provider's API. One service can have multiple versions accessible at the same time.
+     * <br/>
+     * NOTE: This will actually bind the serviceDefinition as the first parameter of the service handler function. When creating default service handlers,
+     * keep in mind that your first param must always be the 'serviceDefinition' and the second one will be the general 'serviceParams' object.
+     * <br/>
+     * NOTE: Additionally, if you intend to call another service inside the service handler, then you have to use a normal function for the handler and not
+     * an arrow function! Arrow functions cannot bind the scope of the parent class to themselves, and you won't have access to it and its methods.
+     *
+     * @method
+     * @param {ServiceDefinition} serviceDefinition Full service definition object.
+     * @param {ServiceHandlerMethod} [defaultServiceHandler=undefined] A default service handler in case there is one.
+     * @return {Promise}
+     * @public
+     */
+    registerService(serviceDefinition: ServiceDefinition, defaultServiceHandler?: ServiceHandlerMethod): Promise<any>;
+    /**
+     * Used to register multiple services from the provided service definitions.
+     *
+     * @method
+     * @param {ServiceDefinition[]} serviceDefinitions
+     * @param {ServiceHandlerMethod} [defaultServiceHandler=undefined]
+     * @return {Promise}
+     * @public
+     */
+    registerServices(serviceDefinitions: ServiceDefinition[], defaultServiceHandler?: ServiceHandlerMethod): Promise<any>;
+    /**
+     * Used to get an ordered list of all currently registered services. This does not include the service versions.
+     *
+     * @method
+     * @returns {string[]}
+     * @public
+     */
+    getRegisteredServices(): string[];
+}