@loutrejs/loutre 0.1.0

package/dist/application/binding.js

@@ -0,0 +1,292 @@
+import { queueRuntimeToken, validateSchema, } from '../core/index.js';
+import { assertValidCompilation, compileApplication } from '../graph/index.js';
+import { createHttpExecution, } from '../http/index.js';
+import { createMessagePortExecution, } from '../message-port/index.js';
+import { ApplicationRuntime, Logger } from '../runtime/index.js';
+import { bindQueueDriver } from './queue.js';
+import { matchesCronTrigger } from './scheduler.js';
+/** flatなcreateXXX/bindXXX APIを増殖させないため、外部bindingをnamespaceへ集約する。 */
+export const binding = Object.freeze({
+    invocation: createInvocationBinding,
+    host: createHostBinding,
+    queue: bindQueueDriver,
+});
+function createInvocationBinding(options) {
+    const state = createRuntimeState(options);
+    const application = createInvocationApplication(state);
+    return createProtocolBinding(state, application);
+}
+function createHostBinding(options) {
+    const state = createRuntimeState(options);
+    const application = createInvocationApplication(state);
+    let triggersStarted = false;
+    let triggerHandles = [];
+    const stopTriggers = async () => {
+        const handles = triggerHandles;
+        triggerHandles = [];
+        triggersStarted = false;
+        const results = await Promise.allSettled(handles.toReversed().map((handle) => handle.stop()));
+        const errors = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Trigger stop failed');
+    };
+    Object.assign(application, {
+        async close(signal) {
+            state.runtime.stopAcceptingExecutions();
+            const errors = [];
+            try {
+                await stopTriggers();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await state.runtime.shutdown(signal);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            if (errors.length > 0)
+                throw new AggregateError(errors, 'Application shutdown failed');
+        },
+        ...(state.definition.triggers.length > 0
+            ? {
+                triggers: {
+                    async start() {
+                        if (triggersStarted) {
+                            throw new Error('LUTRE_TRIGGERS_ALREADY_STARTED: Trigger Engine is already started.');
+                        }
+                        await state.runtime.initialize();
+                        triggersStarted = true;
+                        const started = [];
+                        try {
+                            for (const trigger of state.definition.triggers) {
+                                started.push(await startTrigger(trigger, state.runtime, state.logger));
+                            }
+                            triggerHandles = started;
+                        }
+                        catch (error) {
+                            await Promise.allSettled(started.toReversed().map((handle) => handle.stop()));
+                            triggersStarted = false;
+                            throw error;
+                        }
+                    },
+                    stop: stopTriggers,
+                },
+            }
+            : {}),
+    });
+    return createProtocolBinding(state, application);
+}
+function createRuntimeState(options) {
+    const definition = options.application;
+    const logger = definition.logger ?? new Logger();
+    const tasks = registeredTasks(definition);
+    const graph = assertValidCompilation(compileApplication({
+        modules: definition.modules,
+        ...(definition.arguments === undefined
+            ? {}
+            : { arguments: definition.arguments }),
+        tasks: definition.tasks,
+        triggers: definition.triggers,
+    }));
+    const runtime = new ApplicationRuntime(definition.modules, {
+        logger,
+        tasks,
+        publicTasks: definition.tasks,
+        ...(definition.arguments === undefined
+            ? {}
+            : {
+                arguments: definition.arguments,
+                argumentsSource: 'arguments' in options ? options.arguments : Object.freeze({}),
+            }),
+        ...('environment' in options
+            ? { environmentSource: options.environment }
+            : {}),
+    });
+    return { definition, logger, runtime, graph };
+}
+function createInvocationApplication(state) {
+    const application = {
+        graph: state.graph,
+        async init() {
+            await state.runtime.initialize();
+            return application;
+        },
+        ...(state.definition.tasks.length > 0
+            ? {
+                run(task, ...args) {
+                    return Reflect.apply(state.runtime.run, state.runtime, [
+                        task,
+                        ...args,
+                    ]);
+                },
+            }
+            : {}),
+        close: (signal) => state.runtime.shutdown(signal),
+    };
+    return application;
+}
+function createProtocolBinding(state, application) {
+    const protocols = new Set(state.graph.pipelines.map((pipeline) => pipeline.protocol));
+    return {
+        application,
+        ...(protocols.has('http')
+            ? {
+                http: createHttpExecution({
+                    runtime: state.runtime,
+                    graph: state.graph,
+                    logger: state.logger,
+                }),
+            }
+            : {}),
+        ...(protocols.has('messagePort')
+            ? {
+                messagePort: createMessagePortExecution({
+                    runtime: state.runtime,
+                    graph: state.graph,
+                    logger: state.logger,
+                }),
+            }
+            : {}),
+    };
+}
+async function startTrigger(trigger, runtime, logger) {
+    switch (trigger.trigger) {
+        case 'cron':
+            return startCronTrigger(trigger, runtime, logger);
+        case 'fixed-delay':
+            return startFixedDelayTrigger(trigger, runtime, logger);
+        case 'queue-consumer':
+            return startQueueTrigger(trigger, runtime);
+    }
+    throw new Error('LUTRE_TRIGGER_UNSUPPORTED: Unsupported trigger type.');
+}
+function startCronTrigger(trigger, runtime, logger) {
+    let stopped = false;
+    let lastMinute;
+    const active = new Set();
+    const tick = () => {
+        if (stopped)
+            return;
+        const now = new Date();
+        if (!matchesCronTrigger(trigger, now))
+            return;
+        const minute = cronMinuteIdentity(trigger.timezone, now);
+        if (lastMinute === minute)
+            return;
+        lastMinute = minute;
+        if (trigger.overlap === 'skip' && active.size > 0) {
+            logger.info('Cron trigger skipped overlapping execution', {
+                event: 'trigger.cron.skipped',
+                trigger: trigger.name,
+            });
+            return;
+        }
+        const execution = runtime.runTask(trigger.task).catch((error) => {
+            logger.error('Cron trigger execution failed', {
+                event: 'trigger.cron.execution.failed',
+                trigger: trigger.name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+        active.add(execution);
+        void execution.finally(() => active.delete(execution));
+    };
+    tick();
+    const timer = setInterval(tick, 1_000);
+    return {
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            await Promise.allSettled(active);
+        },
+    };
+}
+function startFixedDelayTrigger(trigger, runtime, logger) {
+    let stopped = false;
+    let timer;
+    let releaseSleep;
+    const sleep = () => new Promise((resolve) => {
+        releaseSleep = resolve;
+        timer = setTimeout(() => {
+            timer = undefined;
+            releaseSleep = undefined;
+            resolve();
+        }, trigger.delay);
+    });
+    const execute = async () => {
+        try {
+            await runtime.runTask(trigger.task);
+        }
+        catch (error) {
+            logger.error('Fixed-delay trigger execution failed', {
+                event: 'trigger.fixed_delay.execution.failed',
+                trigger: trigger.name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+    const loop = (async () => {
+        if (!trigger.immediate)
+            await sleep();
+        while (true) {
+            if (stopped)
+                break;
+            await execute();
+            if (stopped)
+                break;
+            await sleep();
+        }
+    })();
+    return {
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            releaseSleep?.();
+            releaseSleep = undefined;
+            await loop;
+        },
+    };
+}
+async function startQueueTrigger(trigger, runtime) {
+    const driver = runtime.container.resolve(queueRuntimeToken(trigger.queue));
+    if (!driver || typeof driver.start !== 'function') {
+        throw new Error(`LUTRE_QUEUE_DRIVER_INVALID: Queue ${trigger.queue.name} driver is invalid.`);
+    }
+    const handle = await driver.start({
+        consume: async (payload) => {
+            const validated = await validateSchema(trigger.queue.payload, payload);
+            await runtime.runTask(trigger.task, validated);
+        },
+    });
+    if (!handle || typeof handle.stop !== 'function') {
+        throw new Error(`LUTRE_QUEUE_DRIVER_INVALID: Queue ${trigger.queue.name} driver returned an invalid handle.`);
+    }
+    return handle;
+}
+function registeredTasks(definition) {
+    return [
+        ...new Set([
+            ...definition.tasks,
+            ...definition.triggers.map((trigger) => trigger.task),
+        ]),
+    ];
+}
+function cronMinuteIdentity(timezone, instant) {
+    return new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23',
+    }).format(instant);
+}

package/dist/application/host.d.ts

@@ -0,0 +1,8 @@
+import type { ApplicationDefinition, BootstrapArguments, HostedApplication } from './index.js';
+export interface BootstrapBaseOptions<TDefinition extends ApplicationDefinition> {
+    readonly application: TDefinition;
+    readonly environment?: unknown;
+}
+export type BootstrapOptions<TDefinition extends ApplicationDefinition> = BootstrapBaseOptions<TDefinition> & BootstrapArguments<TDefinition>;
+/** generic hostへruntime固有listenerを持ち込まないため、listener ownershipはruntime adapterへ委ねる。 */
+export declare function bootstrap<const TDefinition extends ApplicationDefinition>(options: BootstrapOptions<TDefinition>): HostedApplication<TDefinition>;

package/dist/application/host.js

@@ -0,0 +1,14 @@
+import { binding } from './binding.js';
+/** generic hostへruntime固有listenerを持ち込まないため、listener ownershipはruntime adapterへ委ねる。 */
+export function bootstrap(options) {
+    const host = binding.host(options);
+    const http = 'http' in host ? host.http : undefined;
+    if (http) {
+        Object.assign(host.application, {
+            fetch(request) {
+                return http.handle(request);
+            },
+        });
+    }
+    return host.application;
+}

package/dist/application/index.d.ts

@@ -0,0 +1,62 @@
+import type { ArgsClass, ModuleProtocols, ModuleInstance, SchemaInput, TaskArguments, TaskDescriptor, TaskOutput, TriggerDescriptor } from '../core/index.js';
+import type { ApplicationGraphIR } from '../graph/index.js';
+import type { Logger } from '../runtime/index.js';
+export interface ApplicationDefinitionOptions<TModules extends readonly ModuleInstance[], TArguments extends ArgsClass | undefined, TTasks extends readonly TaskDescriptor<any, any>[], TTriggers extends readonly TriggerDescriptor[]> {
+    readonly modules: TModules;
+    readonly arguments?: TArguments;
+    readonly tasks?: TTasks;
+    readonly triggers?: TTriggers;
+    readonly logger?: Logger;
+}
+export interface ApplicationDefinition<TModules extends readonly ModuleInstance[] = readonly ModuleInstance[], TArguments extends ArgsClass | undefined = ArgsClass | undefined, TTasks extends readonly TaskDescriptor<any, any>[] = readonly TaskDescriptor<any, any>[], TTriggers extends readonly TriggerDescriptor[] = readonly TriggerDescriptor[]> {
+    readonly kind: 'application-definition';
+    readonly modules: TModules;
+    readonly arguments: TArguments;
+    readonly tasks: TTasks;
+    readonly triggers: TTriggers;
+    readonly logger?: Logger;
+}
+export declare function defineApplication<const TModules extends readonly ModuleInstance[], const TArguments extends ArgsClass | undefined = undefined, const TTasks extends readonly TaskDescriptor<any, any>[] = readonly [], const TTriggers extends readonly TriggerDescriptor[] = readonly []>(options: ApplicationDefinitionOptions<TModules, TArguments, TTasks, TTriggers>): ApplicationDefinition<TModules, TArguments, TTasks, TTriggers>;
+export type ApplicationArgumentsInput<TDefinition extends ApplicationDefinition> = TDefinition['arguments'] extends ArgsClass<infer TSchema> ? SchemaInput<TSchema> : never;
+export type BootstrapArguments<TDefinition extends ApplicationDefinition> = TDefinition['arguments'] extends ArgsClass<infer TSchema> ? {} extends SchemaInput<TSchema> ? {
+    readonly arguments?: SchemaInput<TSchema>;
+} : {
+    readonly arguments: SchemaInput<TSchema>;
+} : {
+    readonly arguments?: never;
+};
+export interface BaseApplication {
+    readonly graph: ApplicationGraphIR;
+    init(): Promise<this>;
+    close(signal?: string): Promise<void>;
+}
+export interface TaskApplicationCapability<TTasks extends readonly TaskDescriptor<any, any>[]> {
+    run<TTask extends TTasks[number]>(task: TTask, ...args: TaskArguments<TTask>): Promise<TaskOutput<TTask>>;
+}
+export interface HttpApplicationCapability {
+    fetch(request: Request): Promise<Response>;
+}
+export interface TriggerApplicationCapability {
+    readonly triggers: {
+        start(): Promise<void>;
+        stop(): Promise<void>;
+    };
+}
+export interface QueueConsumerHandle {
+    stop(): Promise<void>;
+}
+export interface QueueConsumerDriver {
+    start(options: {
+        consume(payload: unknown): Promise<void>;
+    }): Promise<QueueConsumerHandle>;
+}
+export type HasProtocol<TDefinition extends ApplicationDefinition, TProtocol extends string> = Extract<ModuleProtocols<TDefinition['modules'][number]>, TProtocol> extends never ? false : true;
+export type HasHttp<TDefinition extends ApplicationDefinition> = HasProtocol<TDefinition, 'http'>;
+export type HasMessagePort<TDefinition extends ApplicationDefinition> = HasProtocol<TDefinition, 'messagePort'>;
+export type HasTasks<TDefinition extends ApplicationDefinition> = TDefinition['tasks'] extends readonly [] ? false : true;
+export type HasTriggers<TDefinition extends ApplicationDefinition> = TDefinition['triggers'] extends readonly [] ? false : true;
+type TaskCapability<TDefinition extends ApplicationDefinition> = TDefinition['tasks'] extends readonly [] ? {} : TaskApplicationCapability<TDefinition['tasks']>;
+export type HostedApplication<TDefinition extends ApplicationDefinition> = BaseApplication & TaskCapability<TDefinition> & (HasHttp<TDefinition> extends true ? HttpApplicationCapability : {}) & (HasTriggers<TDefinition> extends true ? TriggerApplicationCapability : {});
+export type InvocationApplication<TDefinition extends ApplicationDefinition> = BaseApplication & TaskCapability<TDefinition>;
+export { binding } from './binding.js';
+export type { HostBinding, HostBindingApplication, InvocationBinding, InvocationBindingBaseOptions, InvocationBindingOptions, } from './binding.js';

package/dist/application/index.js

@@ -0,0 +1,11 @@
+export function defineApplication(options) {
+    return Object.freeze({
+        kind: 'application-definition',
+        modules: options.modules,
+        arguments: options.arguments,
+        tasks: options.tasks ?? [],
+        triggers: options.triggers ?? [],
+        ...(options.logger === undefined ? {} : { logger: options.logger }),
+    });
+}
+export { binding } from './binding.js';

package/dist/application/openapi.d.ts

@@ -0,0 +1,28 @@
+import type { ApplicationDefinition } from './index.js';
+export interface OpenApiInfo {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+}
+export interface OpenApiServer {
+    readonly url: string;
+    readonly description?: string;
+}
+export interface GenerateOpenApiOptions {
+    readonly info: OpenApiInfo;
+    readonly servers?: readonly OpenApiServer[];
+}
+export interface OpenApiDocument {
+    readonly openapi: '3.2.0';
+    readonly jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema';
+    readonly info: OpenApiInfo;
+    readonly servers?: readonly OpenApiServer[];
+    readonly paths: Readonly<Record<string, OpenApiPathItem>>;
+    readonly components?: {
+        readonly schemas?: Readonly<Record<string, JsonSchema>>;
+    };
+}
+type JsonSchema = Record<string, unknown>;
+type OpenApiPathItem = Record<string, unknown>;
+export declare function generateOpenApi(application: ApplicationDefinition, options: GenerateOpenApiOptions): OpenApiDocument;
+export {};