@loutrejs/loutre 0.1.0

package/dist/runtime/application.js

@@ -0,0 +1,324 @@
+import { argumentsProvider, loadArgs, loadEnv, normalizeProvider, } from '../core/index.js';
+import { collectRuntimeModuleGraph, Container, } from './di.js';
+import { Logger } from './logger.js';
+const NO_ENVIRONMENT_SOURCE = Symbol('loutre.no-environment-source');
+let currentEnvironmentSource = NO_ENVIRONMENT_SOURCE;
+export function initializeWithEnvironment(application, environmentSource) {
+    const previous = currentEnvironmentSource;
+    currentEnvironmentSource = environmentSource;
+    try {
+        return application.initialize();
+    }
+    finally {
+        currentEnvironmentSource = previous;
+    }
+}
+export class EnvironmentBindingError extends Error {
+    code = 'LUTRE_ENV_003';
+    constructor(environment, cause) {
+        super(`Environment validation failed for ${environment.name}.`, { cause });
+        this.name = 'EnvironmentBindingError';
+    }
+}
+export class ArgumentsBindingError extends Error {
+    code = 'LUTRE_ARGS_003';
+    constructor(argumentsContract, cause) {
+        super(`Arguments validation failed for ${argumentsContract.name}.`, {
+            cause,
+        });
+        this.name = 'ArgumentsBindingError';
+    }
+}
+export class ApplicationRuntime {
+    graph;
+    container;
+    #instancesByModule = new Map();
+    #logger;
+    #environmentSource;
+    #arguments;
+    #argumentsSource;
+    #tasks;
+    #publicTasks;
+    #initialized = false;
+    #initializing;
+    #prepared = false;
+    #state = 'created';
+    #activeExecutions = 0;
+    #idleWaiters = new Set();
+    #shutdown;
+    constructor(roots, options = {}) {
+        this.#logger = options.logger ?? new Logger();
+        this.#environmentSource =
+            'environmentSource' in options
+                ? options.environmentSource
+                : NO_ENVIRONMENT_SOURCE;
+        this.#arguments = options.arguments;
+        this.#argumentsSource =
+            'argumentsSource' in options ? options.argumentsSource : Object.freeze({});
+        this.#tasks = new Set(options.tasks ?? []);
+        this.#publicTasks = new Set(options.publicTasks ?? []);
+        this.graph = collectRuntimeModuleGraph(roots);
+        const providers = [
+            ...this.graph.providers,
+            ...(this.#arguments ? [argumentsProvider(this.#arguments)] : []),
+        ];
+        this.container = new Container(providers, {
+            logger: this.#logger,
+        });
+    }
+    initialize() {
+        if (this.#initialized)
+            return Promise.resolve();
+        if (this.#initializing)
+            return this.#initializing;
+        if (this.#state === 'stopping') {
+            return Promise.reject(applicationStateError('LUTRE_APP_STOPPING'));
+        }
+        if (this.#state === 'stopped') {
+            return Promise.reject(applicationStateError('LUTRE_APP_STOPPED'));
+        }
+        const source = this.#environmentSource === NO_ENVIRONMENT_SOURCE
+            ? currentEnvironmentSource
+            : this.#environmentSource;
+        const initialization = this.#initialize(source).finally(() => {
+            if (this.#initializing === initialization) {
+                this.#initializing = undefined;
+            }
+        });
+        this.#initializing = initialization;
+        return initialization;
+    }
+    async #initialize(environmentSource) {
+        this.#state = 'initializing';
+        try {
+            await this.#bindEnvironment(environmentSource);
+            await this.#bindArguments();
+            this.#prepareRuntime();
+            for (const module of this.graph.modules) {
+                const instances = await this.#resolveModuleProviders(module);
+                this.#instancesByModule.set(module, instances);
+                for (const instance of instances)
+                    await callLifecycle(instance, 'onModuleInit');
+                await this.#runHook(module.definition.lifecycle?.onModuleInit);
+            }
+            for (const module of this.graph.modules) {
+                for (const instance of this.#instancesByModule.get(module) ?? []) {
+                    await callLifecycle(instance, 'onApplicationBootstrap');
+                }
+                await this.#runHook(module.definition.lifecycle?.onApplicationBootstrap);
+            }
+            this.#initialized = true;
+            if (this.#state !== 'stopping')
+                this.#state = 'running';
+        }
+        catch (error) {
+            const cleanupErrors = await this.#rollbackInitialization();
+            this.#state = 'stopped';
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([error, ...cleanupErrors], 'Application initialization failed and rollback cleanup also failed', { cause: error });
+            }
+            throw error;
+        }
+    }
+    async #bindEnvironment(source) {
+        const environmentProviders = this.graph.providers.filter((provider) => provider.kind === 'environment');
+        if (environmentProviders.length === 0)
+            return;
+        if (source === NO_ENVIRONMENT_SOURCE) {
+            throw new Error('LUTRE_ENV_005: Application declares Environment Contracts, but the Runtime did not provide an Environment source.');
+        }
+        for (const provider of environmentProviders) {
+            try {
+                const value = await loadEnv(provider.provide, source);
+                this.container.bindEnvironment(provider.provide, value);
+            }
+            catch (error) {
+                throw new EnvironmentBindingError(provider.provide, error);
+            }
+        }
+    }
+    async #bindArguments() {
+        if (!this.#arguments)
+            return;
+        try {
+            const value = await loadArgs(this.#arguments, this.#argumentsSource);
+            this.container.bindArguments(this.#arguments, value);
+        }
+        catch (error) {
+            throw new ArgumentsBindingError(this.#arguments, error);
+        }
+    }
+    #prepareRuntime() {
+        if (this.#prepared)
+            return;
+        for (const module of this.graph.modules) {
+            for (const implementation of module.definition.implementations ?? []) {
+                this.container.prepareImplementation(implementation);
+            }
+        }
+        for (const pipeline of collectApplicationPipelines(this.graph.modules)) {
+            this.container.preparePipeline(pipeline);
+        }
+        for (const task of this.#tasks) {
+            this.container.prepareTask(task);
+        }
+        this.#prepared = true;
+    }
+    run(task, ...args) {
+        if (!this.#publicTasks.has(task)) {
+            return Promise.reject(new Error(`LUTRE_TASK_002: Task ${task.name} is not registered in Application.tasks.`));
+        }
+        return this.#invokeTask(task, args);
+    }
+    /** public run()ではTrigger専用Taskを拒否するため、Trigger Host専用経路を分ける。 */
+    runTask(task, ...args) {
+        if (!this.#tasks.has(task)) {
+            return Promise.reject(new Error(`LUTRE_TASK_NOT_REGISTERED: Task ${task.name} is not registered in this Application.`));
+        }
+        return this.#invokeTask(task, args);
+    }
+    #invokeTask(task, args) {
+        return this.execute(async () => {
+            const runtime = this.container.taskRuntime(task);
+            return Reflect.apply(runtime, undefined, args);
+        });
+    }
+    async execute(execution) {
+        if (this.#state === 'stopping')
+            throw applicationStateError('LUTRE_APP_STOPPING');
+        if (this.#state === 'stopped')
+            throw applicationStateError('LUTRE_APP_STOPPED');
+        this.#activeExecutions += 1;
+        try {
+            await this.initialize();
+            return await execution();
+        }
+        finally {
+            this.#activeExecutions -= 1;
+            if (this.#activeExecutions === 0) {
+                for (const resolve of this.#idleWaiters)
+                    resolve();
+                this.#idleWaiters.clear();
+            }
+        }
+    }
+    stopAcceptingExecutions() {
+        if (this.#state !== 'stopped')
+            this.#state = 'stopping';
+    }
+    shutdown(signal) {
+        if (this.#state === 'stopped')
+            return Promise.resolve();
+        if (this.#shutdown)
+            return this.#shutdown;
+        this.stopAcceptingExecutions();
+        const shutdown = this.#shutdownRuntime(signal);
+        this.#shutdown = shutdown;
+        return shutdown;
+    }
+    async #shutdownRuntime(signal) {
+        if (this.#initializing) {
+            await this.#initializing.catch(() => undefined);
+        }
+        if (this.#activeExecutions > 0) {
+            await new Promise((resolve) => this.#idleWaiters.add(resolve));
+        }
+        const errors = [];
+        const modules = this.graph.modules.toReversed();
+        try {
+            for (const module of modules) {
+                for (const instance of (this.#instancesByModule.get(module) ?? []).toReversed()) {
+                    await collectCleanupError(() => callLifecycle(instance, 'onModuleDestroy'), errors);
+                }
+                await collectCleanupError(() => this.#runHook(module.definition.lifecycle?.onModuleDestroy), errors);
+            }
+            for (const module of modules) {
+                for (const instance of (this.#instancesByModule.get(module) ?? []).toReversed()) {
+                    await collectCleanupError(() => callLifecycle(instance, 'beforeApplicationShutdown', signal), errors);
+                }
+                await collectCleanupError(() => this.#runHook(module.definition.lifecycle?.beforeApplicationShutdown), errors);
+            }
+            for (const module of modules) {
+                for (const instance of (this.#instancesByModule.get(module) ?? []).toReversed()) {
+                    await collectCleanupError(() => callLifecycle(instance, 'onApplicationShutdown', signal), errors);
+                }
+                await collectCleanupError(() => this.#runHook(module.definition.lifecycle?.onApplicationShutdown), errors);
+            }
+        }
+        finally {
+            this.#state = 'stopped';
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'Application shutdown cleanup failed');
+        }
+    }
+    async #rollbackInitialization() {
+        const errors = [];
+        const modules = [...this.#instancesByModule.keys()].toReversed();
+        for (const module of modules) {
+            await collectCleanupError(() => this.#runHook(module.definition.lifecycle?.onModuleDestroy), errors);
+            for (const instance of (this.#instancesByModule.get(module) ?? []).toReversed()) {
+                await collectCleanupError(() => callLifecycle(instance, 'onModuleDestroy'), errors);
+            }
+        }
+        return errors;
+    }
+    async #resolveModuleProviders(module) {
+        const providers = (module.definition.providers ?? []).map(normalizeProvider);
+        const applicationProviders = providers.filter((provider) => provider.scope === 'application' &&
+            provider.kind !== 'environment' &&
+            provider.kind !== 'arguments');
+        const instances = [];
+        this.#instancesByModule.set(module, instances);
+        for (const provider of applicationProviders) {
+            instances.push(this.container.resolve(provider.provide));
+        }
+        return instances;
+    }
+    async #runHook(hook) {
+        if (!hook)
+            return;
+        const dependencies = hook.inject.map((token) => this.container.resolve(token));
+        await hook.run(...dependencies);
+    }
+}
+function applicationStateError(code) {
+    return new Error(code === 'LUTRE_APP_STOPPING'
+        ? `${code}: Application is stopping and cannot accept new executions.`
+        : `${code}: Application is stopped and cannot accept new executions.`);
+}
+function collectApplicationPipelines(modules) {
+    const pipelines = [];
+    for (const module of modules) {
+        for (const implementation of module.definition.implementations ?? []) {
+            for (const procedureName of implementation.procedures) {
+                const procedure = implementation.contract.procedures[procedureName];
+                const protocol = procedure?.protocols[implementation.protocol];
+                const pipeline = protocol?.pipeline ?? protocol?.definition?.pipeline;
+                if (pipeline)
+                    pipelines.push(pipeline);
+            }
+        }
+    }
+    return pipelines;
+}
+async function collectCleanupError(cleanup, errors) {
+    try {
+        await cleanup();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+}
+export function createApplicationRuntime(roots, options = {}) {
+    return new ApplicationRuntime(roots, options);
+}
+async function callLifecycle(instance, method, signal) {
+    if (!instance ||
+        (typeof instance !== 'object' && typeof instance !== 'function'))
+        return;
+    const candidate = instance[method];
+    if (typeof candidate !== 'function')
+        return;
+    await Reflect.apply(candidate, instance, signal === undefined ? [] : [signal]);
+}

package/dist/runtime/capability.d.ts

@@ -0,0 +1,16 @@
+export type RuntimeCapability = string;
+export interface RuntimeCapabilities {
+    readonly runtime: string;
+    readonly capabilities: ReadonlySet<RuntimeCapability>;
+}
+export interface CapabilityCheck {
+    readonly ok: boolean;
+    readonly required: readonly RuntimeCapability[];
+    readonly supported: readonly RuntimeCapability[];
+    readonly missing: readonly RuntimeCapability[];
+}
+export declare function checkCapabilities(required: Iterable<RuntimeCapability>, runtime: RuntimeCapabilities): CapabilityCheck;
+export declare class MissingCapabilitiesError extends Error {
+    readonly check: CapabilityCheck;
+    constructor(check: CapabilityCheck);
+}

package/dist/runtime/capability.js

@@ -0,0 +1,18 @@
+export function checkCapabilities(required, runtime) {
+    const requirements = [...new Set(required)];
+    const missing = requirements.filter((capability) => !runtime.capabilities.has(capability));
+    return {
+        ok: missing.length === 0,
+        required: requirements,
+        supported: [...runtime.capabilities],
+        missing,
+    };
+}
+export class MissingCapabilitiesError extends Error {
+    check;
+    constructor(check) {
+        super(`Runtimeに必要なCapabilityがありません: ${check.missing.join(', ')}`);
+        this.check = check;
+        this.name = 'MissingCapabilitiesError';
+    }
+}

package/dist/runtime/di.d.ts

@@ -0,0 +1,37 @@
+import { type ArgsClass, type Class, type DependencyConsumer, type EnvClass, type ImplementationConsumer, type ImplementationDescriptor, type LayerConsumer, type LayerDescriptor, type LayerRuntime, type ModuleInstance, type ModuleTemplate, type ProviderDescriptor, type PipelineItem, type TaskConsumer, type TaskDescriptor, type TaskRuntime, type TokenLike } from '../core/index.js';
+import { Logger } from './logger.js';
+export declare class DependencyResolutionError extends Error {
+    constructor(message: string);
+}
+export interface RuntimeModuleGraph {
+    readonly modules: readonly ModuleInstance[];
+    readonly providers: readonly ProviderDescriptor[];
+}
+export interface DependencyRecorder {
+    record(consumer: DependencyConsumer, dependency: TokenLike): void;
+}
+export interface ContainerOptions {
+    readonly logger?: Logger;
+    readonly recorder?: DependencyRecorder;
+    readonly environment?: ReadonlyMap<EnvClass, object>;
+    readonly arguments?: ReadonlyMap<ArgsClass, object>;
+    readonly probe?: boolean;
+}
+export declare function collectRuntimeModuleGraph(roots: readonly (ModuleInstance | ModuleTemplate<void>)[]): RuntimeModuleGraph;
+export declare class Container {
+    #private;
+    constructor(providers: readonly ProviderDescriptor[], options?: Logger | ContainerOptions);
+    bindEnvironment(environment: EnvClass, value: object): void;
+    bindArguments(argumentsContract: ArgsClass, value: object): void;
+    resolve<T>(token: TokenLike<T>): T;
+    probeClass<T>(target: Class<T>): T;
+    prepareImplementation(implementation: ImplementationDescriptor): void;
+    implementationRuntime(implementation: ImplementationDescriptor): object;
+    prepareTask(task: TaskDescriptor): void;
+    taskRuntime<TInput, TOutput>(task: TaskDescriptor<TInput, TOutput>): TaskRuntime<TInput, TOutput>;
+    probeTask(task: TaskDescriptor, consumer: TaskConsumer): void;
+    probeImplementation(implementation: ImplementationDescriptor, consumer: ImplementationConsumer): object;
+    preparePipeline(pipeline: readonly PipelineItem[]): void;
+    layerRuntime(layer: LayerDescriptor): LayerRuntime<object, readonly [], unknown>;
+    probeLayer(layer: LayerDescriptor, consumer: LayerConsumer): void;
+}