@darlean/core/lib/config.d.ts

Darlean core functionality for creating applications that define, expose and host actors

import { IActorRegistrationOptions, IActorSuite, IMigrationState } from '@darlean/base';
import { IConfigEnv } from '@darlean/utils';
import { ActorRunner, ActorRunnerBuilder } from './running';
/**
 * Configuration for when this application acts as a runtime application.
 */
export interface IApplicationRuntimeCfg {
    /**
     * Enables or disables the provided runtime functionalities. Can be overruled by
     * `runtime-enabled` command-line argument or `RUNTIME_ENABLED` environment variable set to `true` or `false`.
     * @default By default, the runtime functionality is *not* enabled.
     */
    enabled?: boolean;
    /**
     * Configuration of the DMB message bus server.
     */
    dmb?: IDmbServerCfg;
}
/**
 * Configuration for runtime apps that provide a DMB (Darlean Message Bus) server.
 */
export interface IDmbServerCfg {
    /**
     * Enables or disables whether this application launches a DMB server. Default is `false`.
     * Can be overruled by `dmb-server-enabled` command-line argument and `DMB_SERVER_ENABLED`
     * environment variable set to `true` or `false`.
     */
    enabled?: boolean;
    /**
     * Port number of the cluster port for the first DMB server on a given host. A cluster port is a port on
     * which other DMB servers in the cluster connect (regular clients do *not* connect to the cluster port).
     * Subsequent DMB servers on the same host are automatically assigned incrementing cluster port numbers.
     * Default value is 5500. Can be uverrules by `dmb-cluster-port-base` command-line argument and `DMB_CLUSTER_PORT_BASE`
     * environment variable set to `true` or `false`.
     */
    clusterPortBase?: number;
}
/**
 * Configuration for apps that want to connect as client to the Darlean Message Bus.
 */
export interface IDmbClientCfg {
    /**
     * List of host names or IP addresses, one for each item in {@link IApplicationCfg.runtimeApps}. Can
     * be overruled by `dmb-hosts` command-line argument and `DMB_HOSTS` environment variable set to a comma-separated
     * list of host names.
     */
    hosts?: string[];
    /**
     * Port number for the first DMB server on a given host. Subsequent DMB servers on the same host
     * are automatically assigned incrementing port numbers. Default value is 4500. Can be overruled by
     * `dmb-base-port` command-line argument and `DMB_BASE_PORT` environment variable.
     */
    basePort?: number;
}
/**
 * Configuration of messaging.
 */
export interface IMessagingCfg {
    /**
     * List of messaging transports that are tried in the order listed. Currently, only an empty array or
     * an array with one element with value 'dmb' is allowed. Can be overruled by the `messaging-transports` command-line
     * argument or the `MESSAGING_TRANSPORTS` environment parameter, that are either a comma-separated list of transports
     * (currently only 'dmb' is allowed) or the word 'none'.
     *
     * @default When explicitly no transports are provided (by means of an empty array or `none` as value for the command-line argument or
     * environment parameter), an {@link InProcessTransport} instance is used which allows in-process communication
     * (but not communication between processes). Otherwise, when the transports are not explicitly assigned and are also not explicitly
     * cleared, the {@link NatsTransport} (on which DMB is currently based) is used.
     */
    transports: Array<'dmb'>;
    /**
     * Client configuration of the Darlean Message Bus.
     */
    dmb?: IDmbClientCfg;
}
/**
 * Root configuration object for the configuration of a Darlean application.
 *
 * Many of the settings can be overruled by command-line arguments or environment variables. See
 * {@link ConfigRunnerBuilder} for more details.
 */
export interface IApplicationCfg {
    /**
     * The id under which this application is known in the cluster. Must either be set here,
     * or overruled by the `app-id` command-line argument or `APP_ID` environment setting.
     * @default `app`.
     */
    appId?: string;
    /**
     * List of application id's that together provide the runtime of the Darlean cluster
     * (that is, provide the actor registry and actor lock, and optionally provide the
     * Darlean Message Bus, persistence and other services).
     * Must either be set here, or overruled by the `runtime-apps` command-line argument or the
     * `RUNTIME_APPS` environment variable with a comma-separated list of application id's.
     * @default an array consisting of just the {@link appId}.
     */
    runtimeApps?: string[];
    /**
     * Optional configuration when this application acts as runtime.
     */
    runtime?: IApplicationRuntimeCfg;
    /**
     * Configuration of the message bus that allows inter-application communication.
     */
    messaging?: IMessagingCfg;
    /**
     * Prefix (including path) of the pidFile for this process. When set, the application creates a pid file
     * and checks during startup whether it is not already running. The value can be overruled
     * with the `pid-file-prefix` command-line argument and the `PID_FILE_PREFIX` environment variable, both of which
     * can be set to `none` to disable the pidFile functionality.
     * @default `'./pid/'`
     */
    pidFilePrefix?: string;
    /**
     * Prefix (including path) of the runFile for this process. When set, the application creates a run file
     * at start up, and automatically stops itself gracefully when the file is no longer present. The value can be overruled
     * with the `run-file-prefix` command-line argument and the `RUN_FILE_PREFIX` environment variable, both of which
     * can be set to `none` to disable the runFile functionality. When not set, the {@link pidFilePrefix} is used as run file prefix.
     */
    runFilePrefix?: string;
    config?: string;
    overrides?: string[];
}
/**
 * Builds an {@link ActorRunner} instance based on configuration settings, command-line
 * arguments and environment variables.
 *
 * Command-line arguments have priority, followed by environment variables, with the provided
 * configuration data as fall-back.
 *
 * **Command-line arguments** must by default be prefixed with `--darlean-`. So, when the documentation
 * mentions a command-line argument `appid`, it must by default be provided as `--darlean-appid`.
 * The value must be provided as after the `=` sign: `--darlean-appid=client03`. When
 * multiple vales are expected, they must be comma-separated.
 *
 * **Environment variables** must by default be prefixed with `DARLEAN_`. So, when the documentation
 * mentions an environment variable `APPID`, it must by default be provided as `DARLEAN_APPID`.
 * When multiple values are expected, they must be comma-separated.
 *
 * The argument and environment variable prefix can be configured in the constructor.
 *
 * @see {@link IApplicationCfg} for an overview of all the available configuration items.
 */
export declare class ConfigRunnerBuilder {
    private actors;
    private overrides;
    private appId;
    private root;
    constructor(scope?: string);
    /**
     * Registers an individual actor that must be hosted by the actor runner.
     * @param options The options for the actor.
     * @returns The builder
     */
    registerActor<T extends object, T2 extends IMigrationState>(options: IActorRegistrationOptions<T, T2>): ConfigRunnerBuilder;
    /**
     * Registers a suite of actors that must be hosted by the actor runner.
     * @param suite The suite to be registered
     * @returns The builder
     */
    registerSuite(suite: IActorSuite): ConfigRunnerBuilder;
    getAppId(): string;
    getConfig(): IConfigEnv<IApplicationCfg>;
    build(): ActorRunner;
    protected configureActors(builder: ActorRunnerBuilder): void;
    protected configureTransports(builder: ActorRunnerBuilder, allInOne: boolean, runtimeApps: string[], appId: string): void;
    protected configureDmbServer(runner: ActorRunner, config: IConfigEnv<IApplicationCfg>, runtimeApps: string[], appId: string): void;
    protected configurePidAndRun(appId: string, runner: ActorRunner): void;
    protected derivePortOffsets(hosts: string[]): number[];
    protected deriveHosts(dmb: IConfigEnv<IDmbClientCfg> | undefined, appIds: string[]): string[];
    protected deriveConfig(scope: string): IConfigEnv<IApplicationCfg>;
    protected loadOverrides(): void;
}