@chidchanun/bcp 0.2.18 → 0.3.0

package/packages/server/src/application.ts

@@ -0,0 +1,845 @@
+import {
+    createDeploymentRuntime,
+
+    type DeploymentDiagnosticsReport,
+    type DeploymentMetadata,
+    type DeploymentReadinessReport,
+    type DeploymentResource,
+    type DeploymentRuntime,
+    type DeploymentRuntimeOptions,
+    type DeploymentShutdownOptions,
+    type DeploymentSignalOptions,
+} from "./deployment.js";
+
+import {
+    createPluginHost,
+
+    type PluginDefinition,
+    type PluginHookBus,
+    type PluginHost,
+    type PluginModule,
+    type PluginServiceKey,
+    type PluginServiceRegistry,
+} from "./plugins.js";
+
+import {
+    registerShutdownHook as registerProductionShutdownHook,
+} from "./production-hardening.js";
+
+const DEFAULT_APPLICATION_SIGNALS:
+    readonly NodeJS.Signals[] = [
+        "SIGTERM",
+        "SIGINT",
+    ];
+
+export type ApplicationState =
+    | "created"
+    | "starting"
+    | "ready"
+    | "stopping"
+    | "stopped"
+    | "failed";
+
+export interface ApplicationConfigSchema<TConfig> {
+    parse(value: unknown): TConfig;
+}
+
+export type ApplicationConfigParser<TConfig> =
+    | ApplicationConfigSchema<TConfig>
+    | ((value: unknown) => TConfig);
+
+export interface ApplicationContext<TConfig = unknown> {
+    readonly name: string;
+    readonly version?: string;
+    readonly config: TConfig;
+    readonly services: PluginServiceRegistry;
+    readonly hooks: PluginHookBus;
+    readonly plugins: PluginHost;
+    readonly deployment: DeploymentRuntime;
+    readonly metadata: DeploymentMetadata;
+    readonly state: ApplicationState;
+}
+
+export interface ApplicationDefinition<TConfig = unknown> {
+    name: string;
+    version?: string;
+    config?: unknown;
+    schema?: ApplicationConfigParser<TConfig>;
+    plugins?: readonly PluginDefinition<any>[];
+    modules?: readonly PluginModule[];
+    pluginConfigs?: Record<string, unknown>;
+    services?: Iterable<
+        readonly [PluginServiceKey, unknown]
+    >;
+    resources?: readonly DeploymentResource[];
+    deployment?: Omit<
+        DeploymentRuntimeOptions,
+        "serviceName" | "version" | "resources"
+    >;
+    setup?(
+        context: ApplicationContext<TConfig>
+    ): void | Promise<void>;
+    start?(
+        context: ApplicationContext<TConfig>
+    ): void | Promise<void>;
+    stop?(
+        context: ApplicationContext<TConfig>
+    ): void | Promise<void>;
+    dispose?(
+        context: ApplicationContext<TConfig>
+    ): void | Promise<void>;
+}
+
+export interface Application<TConfig = unknown> {
+    readonly name: string;
+    readonly version?: string;
+    readonly state: ApplicationState;
+    readonly config: TConfig;
+    readonly context: ApplicationContext<TConfig>;
+    readonly services: PluginServiceRegistry;
+    readonly hooks: PluginHookBus;
+    readonly plugins: PluginHost;
+    readonly deployment: DeploymentRuntime;
+    use(
+        extension:
+            | PluginDefinition<any>
+            | PluginModule
+    ): Application<TConfig>;
+    provide<T>(
+        key: PluginServiceKey<T>,
+        value: T,
+        options?: {
+            replace?: boolean;
+        }
+    ): Application<TConfig>;
+    addResource(
+        resource: DeploymentResource
+    ): Application<TConfig>;
+    start(): Promise<void>;
+    stop(
+        options?: DeploymentShutdownOptions
+    ): Promise<void>;
+    shutdown(
+        options?: DeploymentShutdownOptions
+    ): Promise<void>;
+    close(
+        options?: DeploymentShutdownOptions
+    ): Promise<void>;
+    readiness(): Promise<DeploymentReadinessReport>;
+    diagnostics(): Promise<DeploymentDiagnosticsReport>;
+    installSignalHandlers(
+        options?: DeploymentSignalOptions
+    ): () => void;
+    registerShutdownHook(
+        name?: string
+    ): () => void;
+}
+
+export class ApplicationLifecycleError
+extends Error {
+    readonly phase: string;
+    readonly cause: unknown;
+
+    constructor(
+        phase: string,
+        cause: unknown
+    ) {
+        super(
+            `BCP Application: ${phase} failed: ${formatError(cause)}`
+        );
+        this.name =
+            "ApplicationLifecycleError";
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+
+export function defineApp<TConfig = unknown>(
+    definition: ApplicationDefinition<TConfig>
+): ApplicationDefinition<TConfig> {
+    validateDefinition(definition);
+    return definition;
+}
+
+export function createApp<TConfig = unknown>(
+    definition: ApplicationDefinition<TConfig>
+): Application<TConfig> {
+    defineApp(definition);
+
+    const name =
+        normalizeName(
+            definition.name,
+            "application name"
+        );
+    const version =
+        normalizeOptionalText(
+            definition.version
+        );
+    const config =
+        parseConfig(
+            definition.schema,
+            definition.config
+        );
+    const plugins =
+        createPluginHost({
+            plugins:
+                definition.plugins,
+            modules:
+                definition.modules,
+            configs:
+                definition.pluginConfigs,
+            services:
+                definition.services,
+        });
+    const deployment =
+        createDeploymentRuntime({
+            ...(definition.deployment ?? {}),
+            serviceName:
+                name,
+            ...(version
+                ? {
+                    version,
+                }
+                : {}),
+        });
+
+    let state:
+        ApplicationState =
+        "created";
+    let startPromise:
+        Promise<void> | null =
+        null;
+    let stopPromise:
+        Promise<void> | null =
+        null;
+    let setupCompleted = false;
+    let applicationResourceRegistered =
+        false;
+    let disposed = false;
+    let failure:
+        ApplicationLifecycleError | null =
+        null;
+
+    const context:
+        ApplicationContext<TConfig> = {
+        name,
+        ...(version
+            ? {
+                version,
+            }
+            : {}),
+        config,
+        services:
+            plugins.services,
+        hooks:
+            plugins.hooks,
+        plugins,
+        deployment,
+        get metadata() {
+            return deployment.metadata;
+        },
+        get state() {
+            return state;
+        },
+    };
+
+    deployment.addResource({
+        name:
+            "bcp:plugins",
+        async start() {
+            await plugins.start();
+        },
+        ready() {
+            return {
+                ok:
+                    plugins.started,
+                detail:
+                    plugins.started
+                        ? "Plugin host started."
+                        : "Plugin host is not started.",
+            };
+        },
+        async stop() {
+            await plugins.close();
+        },
+        diagnostics() {
+            return {
+                started:
+                    plugins.started,
+                plugins:
+                    plugins.plugins(),
+            };
+        },
+    });
+
+    for (
+        const resource
+        of definition.resources ?? []
+    ) {
+        deployment.addResource(resource);
+    }
+
+    const app:
+        Application<TConfig> = {
+        name,
+        ...(version
+            ? {
+                    version,
+                }
+            : {}),
+        config,
+        context,
+        services:
+            plugins.services,
+        hooks:
+            plugins.hooks,
+        plugins,
+        deployment,
+
+        get state() {
+            return state;
+        },
+
+        use(extension) {
+            assertMutable();
+            plugins.use(extension);
+            return app;
+        },
+
+        provide<T>(
+            key: PluginServiceKey<T>,
+            value: T,
+            options: {
+                replace?: boolean;
+            } = {}
+        ) {
+            assertMutable();
+            plugins.services.provide(
+                key,
+                value,
+                options
+            );
+            return app;
+        },
+
+        addResource(resource) {
+            assertMutable();
+            deployment.addResource(
+                resource
+            );
+            return app;
+        },
+
+        async start() {
+            if (state === "ready") {
+                return;
+            }
+            if (state === "starting") {
+                if (!startPromise) {
+                    throw new Error(
+                        "BCP Application: startup promise is unavailable while starting."
+                    );
+                }
+                return startPromise;
+            }
+            if (state === "stopping") {
+                throw new Error(
+                    "BCP Application: application cannot start while stopping."
+                );
+            }
+            if (state === "stopped") {
+                throw new Error(
+                    "BCP Application: a stopped application cannot be started again."
+                );
+            }
+            if (state === "failed") {
+                throw failure ??
+                    new Error(
+                        "BCP Application: failed application cannot be started again."
+                    );
+            }
+
+            state =
+                "starting";
+            startPromise =
+                startApplication();
+            return startPromise;
+        },
+
+        stop(options = {}) {
+            return shutdownApplication(
+                options
+            );
+        },
+
+        shutdown(options = {}) {
+            return shutdownApplication(
+                options
+            );
+        },
+
+        close(options = {}) {
+            return shutdownApplication(
+                options
+            );
+        },
+
+        readiness() {
+            return deployment.readiness();
+        },
+
+        diagnostics() {
+            return deployment.diagnostics();
+        },
+
+        installSignalHandlers(
+            signalOptions:
+                DeploymentSignalOptions = {}
+        ) {
+            const signals =
+                Array.from(
+                    new Set(
+                        signalOptions.signals ??
+                        DEFAULT_APPLICATION_SIGNALS
+                    )
+                );
+            const handlers =
+                new Map<
+                    NodeJS.Signals,
+                    () => void
+                >();
+
+            for (const signal of signals) {
+                const handler = () => {
+                    void app.shutdown({
+                        reason:
+                            signal,
+                    }).then(
+                        () => {
+                            if (
+                                signalOptions.setExitCode !==
+                                false
+                            ) {
+                                process.exitCode = 0;
+                            }
+                        },
+                        () => {
+                            process.exitCode = 1;
+                        }
+                    );
+                };
+                handlers.set(
+                    signal,
+                    handler
+                );
+                process.on(
+                    signal,
+                    handler
+                );
+            }
+
+            return () => {
+                for (
+                    const [
+                        signal,
+                        handler,
+                    ]
+                    of handlers
+                ) {
+                    process.off(
+                        signal,
+                        handler
+                    );
+                }
+                handlers.clear();
+            };
+        },
+
+        registerShutdownHook(hookName) {
+            return registerProductionShutdownHook(
+                () =>
+                    app.shutdown({
+                        reason:
+                            "framework-shutdown",
+                    }),
+                {
+                    name:
+                        hookName ??
+                        `application:${name}`,
+                }
+            );
+        },
+    };
+
+    return app;
+
+    async function startApplication():
+    Promise<void> {
+        try {
+            if (!setupCompleted) {
+                await runHook(
+                    "setup",
+                    definition.setup
+                );
+                setupCompleted = true;
+            }
+
+            registerApplicationResource();
+            await deployment.start();
+            state =
+                "ready";
+            failure =
+                null;
+        } catch (error) {
+            const lifecycleError =
+                error instanceof ApplicationLifecycleError
+                    ? error
+                    : new ApplicationLifecycleError(
+                        "start",
+                        error
+                    );
+            failure =
+                lifecycleError;
+            state =
+                "failed";
+            await cleanupAfterFailure();
+            throw lifecycleError;
+        } finally {
+            startPromise =
+                null;
+        }
+    }
+
+    async function shutdownApplication(
+        options: DeploymentShutdownOptions
+    ): Promise<void> {
+        if (state === "stopped") {
+            return;
+        }
+        if (state === "stopping") {
+            return stopPromise ??
+                Promise.resolve();
+        }
+
+        if (state === "starting") {
+            try {
+                await startPromise;
+            } catch {
+                // Startup cleanup already preserved the original failure.
+            }
+        }
+
+        state =
+            "stopping";
+        stopPromise =
+            stopApplication(options);
+        return stopPromise;
+    }
+
+    async function stopApplication(
+        options: DeploymentShutdownOptions
+    ): Promise<void> {
+        const errors:
+            unknown[] = [];
+
+        try {
+            if (
+                deployment.state !== "idle" &&
+                deployment.state !== "stopped"
+            ) {
+                try {
+                    await deployment.shutdown(
+                        options
+                    );
+                } catch (error) {
+                    errors.push(error);
+                }
+            } else {
+                try {
+                    await plugins.close();
+                } catch (error) {
+                    errors.push(error);
+                }
+            }
+
+            try {
+                await disposeApplication();
+            } catch (error) {
+                errors.push(error);
+            }
+
+            state =
+                "stopped";
+        } finally {
+            stopPromise =
+                null;
+        }
+
+        if (errors.length > 0) {
+            throw new AggregateError(
+                errors,
+                "BCP Application: one or more shutdown operations failed."
+            );
+        }
+    }
+
+    function registerApplicationResource():
+    void {
+        if (applicationResourceRegistered) {
+            return;
+        }
+
+        deployment.addResource({
+            name:
+                "bcp:application",
+            async start() {
+                await runHook(
+                    "start",
+                    definition.start
+                );
+            },
+            ready() {
+                return true;
+            },
+            async stop() {
+                await runHook(
+                    "stop",
+                    definition.stop
+                );
+            },
+            diagnostics() {
+                return {
+                    name,
+                    ...(version
+                        ? {
+                                version,
+                            }
+                        : {}),
+                    state,
+                    services:
+                        plugins.services
+                            .keys()
+                            .map(
+                                formatServiceKey
+                            ),
+                    pluginCount:
+                        plugins.plugins().length,
+                };
+            },
+        });
+
+        applicationResourceRegistered =
+            true;
+    }
+
+    async function cleanupAfterFailure():
+    Promise<void> {
+        if (
+            deployment.state !== "idle" &&
+            deployment.state !== "stopped"
+        ) {
+            try {
+                await deployment.shutdown({
+                    reason:
+                        "application-start-failed",
+                });
+            } catch {
+                // Preserve the original startup failure.
+            }
+        }
+
+        try {
+            await plugins.close();
+        } catch {
+            // Preserve the original startup failure.
+        }
+
+        try {
+            await disposeApplication();
+        } catch {
+            // Preserve the original startup failure.
+        }
+    }
+
+    async function disposeApplication():
+    Promise<void> {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        await runHook(
+            "dispose",
+            definition.dispose
+        );
+    }
+
+    async function runHook(
+        phase: string,
+        hook:
+            | ((
+                value: ApplicationContext<TConfig>
+            ) => void | Promise<void>)
+            | undefined
+    ): Promise<void> {
+        if (!hook) {
+            return;
+        }
+        try {
+            await hook(context);
+        } catch (error) {
+            throw new ApplicationLifecycleError(
+                phase,
+                error
+            );
+        }
+    }
+
+    function assertMutable(): void {
+        if (state !== "created") {
+            throw new Error(
+                "BCP Application: plugins, services and resources must be registered before start()."
+            );
+        }
+    }
+}
+
+function parseConfig<TConfig>(
+    parser:
+        ApplicationConfigParser<TConfig> |
+        undefined,
+    value: unknown
+): TConfig {
+    if (!parser) {
+        return value as TConfig;
+    }
+    if (typeof parser === "function") {
+        return parser(value);
+    }
+    if (
+        parser &&
+        typeof parser === "object" &&
+        typeof parser.parse === "function"
+    ) {
+        return parser.parse(value);
+    }
+    throw new TypeError(
+        "BCP Application: config schema must be a function or an object with parse()."
+    );
+}
+
+function validateDefinition<TConfig>(
+    definition: ApplicationDefinition<TConfig>
+): void {
+    if (
+        !definition ||
+        typeof definition !== "object"
+    ) {
+        throw new TypeError(
+            "BCP Application: definition must be an object."
+        );
+    }
+
+    normalizeName(
+        definition.name,
+        "application name"
+    );
+    normalizeOptionalText(
+        definition.version
+    );
+
+    if (
+        definition.plugins !== undefined &&
+        !Array.isArray(definition.plugins)
+    ) {
+        throw new TypeError(
+            "BCP Application: plugins must be an array."
+        );
+    }
+    if (
+        definition.modules !== undefined &&
+        !Array.isArray(definition.modules)
+    ) {
+        throw new TypeError(
+            "BCP Application: modules must be an array."
+        );
+    }
+    if (
+        definition.resources !== undefined &&
+        !Array.isArray(definition.resources)
+    ) {
+        throw new TypeError(
+            "BCP Application: resources must be an array."
+        );
+    }
+
+    for (
+        const [phase, hook]
+        of [
+            ["setup", definition.setup],
+            ["start", definition.start],
+            ["stop", definition.stop],
+            ["dispose", definition.dispose],
+        ] as const
+    ) {
+        if (
+            hook !== undefined &&
+            typeof hook !== "function"
+        ) {
+            throw new TypeError(
+                `BCP Application: ${phase} must be a function.`
+            );
+        }
+    }
+}
+
+function normalizeName(
+    value: unknown,
+    label: string
+): string {
+    if (typeof value !== "string") {
+        throw new TypeError(
+            `BCP Application: ${label} must be a string.`
+        );
+    }
+    const normalized =
+        value.trim();
+    if (!normalized) {
+        throw new TypeError(
+            `BCP Application: ${label} cannot be empty.`
+        );
+    }
+    return normalized;
+}
+
+function normalizeOptionalText(
+    value: unknown
+): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new TypeError(
+            "BCP Application: optional text values must be strings."
+        );
+    }
+    return value.trim() || undefined;
+}
+
+function formatServiceKey(
+    key: PluginServiceKey
+): string {
+    return typeof key === "symbol"
+        ? key.description
+            ? `Symbol(${key.description})`
+            : key.toString()
+        : key;
+}
+
+function formatError(
+    value: unknown
+): string {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    return String(value);
+}