@mdf.js/core
Version:
MMS - API Core - Common types, classes and functions
207 lines • 8.73 kB
TypeScript
/**
* Copyright 2024 Mytra Control S.L. All rights reserved.
*
* Use of this source code is governed by an MIT-style license that can be found in the LICENSE file
* or at https://opensource.org/licenses/MIT.
*/
import { Crash, Multi } from '@mdf.js/crash';
import { LoggerInstance } from '@mdf.js/logger';
import { EventEmitter } from 'events';
import { Health } from '../..';
import { Resource } from '../App';
import { Port } from './Port';
import { ProviderOptions, ProviderState, ProviderStatus } from './types';
export declare interface Manager<PortClient, PortConfig, PortInstance extends Port<PortClient, PortConfig>> {
/**
* Add a listener for the `error` event, emitted when the component detects an error.
* @param event - `error` event
* @param listener - Error event listener
* @event
*/
on(event: 'error', listener: (error: Crash | Multi) => void): this;
/**
* Add a listener for the `error` event, emitted when the component detects an error.
* @param event - `error` event
* @param listener - Error event listener
* @event
*/
addListener(event: 'error', listener: (error: Crash | Multi) => void): this;
/**
* Add a listener for the `error` event, emitted when the component detects an error. This is a
* one-time event, the listener will be removed after the first emission.
* @param event - `error` event
* @param listener - Error event listener
* @event
*/
once(event: 'error', listener: (error: Crash | Multi) => void): this;
/**
* Removes the specified listener from the listener array for the `error` event.
* @param event - `error` event
* @param listener - Error event listener
* @event
*/
off(event: 'error', listener: (error: Crash | Multi) => void): this;
/**
* Removes the specified listener from the listener array for the `error` event.
* @param event - `error` event
* @param listener - Error event listener
* @event
*/
removeListener(event: 'error', listener: (error: Crash | Multi) => void): this;
/**
* Removes all listeners, or those of the specified event.
* @param event - `error` event
*/
removeAllListeners(event?: 'error'): this;
/**
* Add a listener for the `status` event, emitted when the component changes its status.
* @param event - `status` event
* @param listener - Status event listener
* @event
*/
on(event: 'status', listener: (status: ProviderStatus) => void): this;
/**
* Add a listener for the `status` event, emitted when the component changes its status.
* @param event - `status` event
* @param listener - Status event listener
* @event
*/
addListener(event: 'status', listener: (status: ProviderStatus) => void): this;
/**
* Add a listener for the `status` event, emitted when the component changes its status. This is a
* one-time event, the listener will be removed after the first emission.
* @param event - `status` event
* @param listener - Status event listener
* @event
*/
once(event: 'status', listener: (status: ProviderStatus) => void): this;
/**
* Removes the specified listener from the listener array for the `status` event.
* @param event - `status` event
* @param listener - Status event listener
* @event
*/
off(event: 'status', listener: (status: ProviderStatus) => void): this;
/**
* Removes the specified listener from the listener array for the `status` event.
* @param event - `status` event
* @param listener - Status event listener
* @event
*/
removeListener(event: 'status', listener: (status: ProviderStatus) => void): this;
}
/**
* Provider Manager wraps a specific port created by the extension of the {@link Port} abstract
* class, instrumenting it with the necessary logic to manage:
*
* - The state of the provider, represented by the {@link Manager.state} property, and managed by
* the {@link Manager.start}, {@link Manager.stop} and {@link Manager.fail} methods.
*
* 
*
* - Merge and validate the configuration of the provider represented by the generic type
* _**PortConfig**_. The manager configuration object {@link ProviderOptions} has a _**validation**_
* property that represent a structure of type {@link PortConfigValidationStruct} where default
* values, environment based and a [Joi validation object](https://joi.dev/api/?v=17.7.0) are
* defined. During the initialization process, the manager will merge all the sources of
* configuration (default, environment and specific) and validate the result against the Joi schema.
* So, the order of priority of the configuration sources is: specific, environment and default.
* If the validation fails, the manager will use the default values and emit an error that will be
* managed by the observability layer.
*
* @category Provider
*
* @param PortClient - Underlying client type, this is, the real client of the wrapped provider
* @param PortConfig - Port configuration object, could be an extended version of the client config
* @param T - Port class, this is, the class that extends the {@link Port} abstract class
* @public
*/
export declare class Manager<PortClient, PortConfig, PortInstance extends Port<PortClient, PortConfig>> extends EventEmitter implements Resource {
private readonly options;
/** Provider unique identifier for trace purposes */
readonly componentId: string;
/** Debug logger*/
private readonly logger;
/** Error in error state */
private _error?;
/** Provider actual state */
private _state;
/** Timestamp of actual state */
private _date;
/** Port instance */
private readonly port;
/** Port configuration */
readonly config: PortConfig;
/**
* Implementation of base functionalities of a provider manager
* @param port - Port wrapper class
* @param config - Port configuration options
* @param options - Manager configuration options
*/
constructor(port: new (portConfig: PortConfig, logger: LoggerInstance, name: string) => PortInstance, options: ProviderOptions<PortConfig>, config?: Partial<PortConfig>);
/** Return the errors in the provider */
get error(): Multi | Crash | undefined;
/** Provider state */
get state(): ProviderState;
/**
* Return the status of the connection in a standard format
* @returns _check object_ as defined in the draft standard
* https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check-05
*/
get checks(): Health.Checks;
/** Provider status */
get status(): Health.Status;
/** Port client */
get client(): PortClient;
/** Provider name */
get name(): string;
/** Timestamp of actual state in ISO format, when the current state was reached */
get date(): string;
/** Initialize the process: internal jobs, external dependencies connections ... */
start(): Promise<void>;
/** Stop the process: internal jobs, external dependencies connections ... */
stop(): Promise<void>;
/** Close the provider: release resources, connections ... */
close(): Promise<void>;
/**
* Error state: wait for new state of to fix the actual degraded stated
* @param error - Cause ot this fail transition
* @returns
*/
fail(error: Crash | Error): Promise<void>;
/**
* Change the provider state
* @param newState - state to which it transitions
*/
private readonly changeState;
/**
* Format the error to a manageable error format
* @param error - error to be formatted
* @returns
*/
private formatError;
/**
* Manage the errors in the provider (logging, emitting, last error ...)
* @param error - Error from wrapper instance
*/
private readonly manageError;
/**
* Manage the actual stored error (last error), to create a human readable output used in the
* observability (SubcomponentDetail)
*/
private detailedOutput;
/**
* Merge the configuration with the default values and environment values and perform the
* validation of the new configuration against the schema
* @param options - validation configuration options
*/
private validateConfig;
/**
* Merge the environment configuration and the default configuration with the specific
* configuration
* @param config - specific configuration for the provider instances
* @returns
*/
private mergeConfigSources;
}
//# sourceMappingURL=Manager.d.ts.map