@loutrejs/loutre 0.5.0 → 0.7.0

package/dist/tasks/extension.js

@@ -0,0 +1,525 @@
+import { collectInjectedDependencies, defineExecution, defineExecutionExtension, provide, runInInjectionContext, token, validateSchema, } from '../core/index.js';
+import { isValidCronExpression, matchesCronTrigger } from './runtime/cron.js';
+const taskExecutionIdentityKey = Symbol.for('loutre.tasks.task-execution-identity');
+const queueDriverToken = Symbol.for('loutre.tasks.queue-driver');
+export const tasksExtension = defineExecutionExtension({
+    kind: 'execution-extension',
+    abiVersion: '1',
+    name: 'loutre:tasks',
+    compile(definition) {
+        switch (definition.type) {
+            case 'task':
+                return {
+                    kind: 'execution',
+                    id: `task.${definition.name}`,
+                    executionKind: 'task.invocation',
+                    dependencies: collectInjectedDependencies({
+                        kind: 'execution',
+                        id: `task:${definition.name}`,
+                        name: definition.name,
+                    }, () => definition.factory()),
+                    capabilities: [],
+                    compiled: Object.freeze({
+                        type: 'task',
+                        taskExecutionId: definition[taskExecutionIdentityKey],
+                        name: definition.name,
+                        factory: definition.factory,
+                    }),
+                };
+            case 'cron':
+                return {
+                    kind: 'execution',
+                    id: `trigger.${definition.name}`,
+                    executionKind: 'trigger.cron',
+                    dependencies: [],
+                    capabilities: [],
+                    compiled: Object.freeze({
+                        type: 'cron',
+                        name: definition.name,
+                        expression: definition.expression,
+                        timezone: definition.timezone,
+                        overlap: definition.overlap,
+                        taskExecutionId: definition.task[taskExecutionIdentityKey],
+                        taskName: definition.task.name,
+                    }),
+                };
+            case 'fixed-delay':
+                return {
+                    kind: 'execution',
+                    id: `trigger.${definition.name}`,
+                    executionKind: 'trigger.fixed-delay',
+                    dependencies: [],
+                    capabilities: [],
+                    compiled: Object.freeze({
+                        type: 'fixed-delay',
+                        name: definition.name,
+                        delay: definition.delay,
+                        immediate: definition.immediate,
+                        taskExecutionId: definition.task[taskExecutionIdentityKey],
+                        taskName: definition.task.name,
+                    }),
+                };
+            case 'queue-consumer':
+                return {
+                    kind: 'execution',
+                    id: `trigger.${definition.name}`,
+                    executionKind: 'trigger.queue-consumer',
+                    dependencies: [queueRuntimeToken(definition.queue)],
+                    capabilities: [],
+                    compiled: Object.freeze({
+                        type: 'queue-consumer',
+                        name: definition.name,
+                        queueName: definition.queue.name,
+                        queuePayload: definition.queue.payload,
+                        queueDriver: queueRuntimeToken(definition.queue),
+                        taskExecutionId: definition.task[taskExecutionIdentityKey],
+                        taskName: definition.task.name,
+                    }),
+                };
+        }
+    },
+    references(definition) {
+        switch (definition.type) {
+            case 'task':
+                return [];
+            case 'cron':
+            case 'fixed-delay':
+            case 'queue-consumer':
+                return [definition.task];
+        }
+    },
+    validate({ executions }) {
+        const taskExecutionIds = new Set(executions.flatMap((execution) => execution.compiled.type === 'task'
+            ? [execution.compiled.taskExecutionId]
+            : []));
+        const diagnostics = [];
+        for (const execution of executions) {
+            const compiled = execution.compiled;
+            if (compiled.type === 'task')
+                continue;
+            if (!taskExecutionIds.has(compiled.taskExecutionId)) {
+                diagnostics.push({
+                    code: 'LUTRE_TRIGGER_TASK_MISSING',
+                    message: `Trigger ${compiled.name} references a Task that is unavailable in the compiled Tasks execution set.`,
+                    path: execution.id,
+                });
+            }
+            if (compiled.type !== 'cron')
+                continue;
+            if (!isValidCronExpression(compiled.expression)) {
+                diagnostics.push({
+                    code: 'LUTRE_TRIGGER_INVALID_CRON',
+                    message: `Trigger ${compiled.name} must use a portable 5-field cron expression.`,
+                    path: execution.id,
+                });
+            }
+            try {
+                new Intl.DateTimeFormat('en-US', {
+                    timeZone: compiled.timezone,
+                }).format();
+            }
+            catch {
+                diagnostics.push({
+                    code: 'LUTRE_TRIGGER_INVALID_TIMEZONE',
+                    message: `Trigger ${compiled.name} must use a valid IANA timezone.`,
+                    path: execution.id,
+                });
+            }
+        }
+        return diagnostics;
+    },
+    createRuntime({ executions, applicationRuntime }) {
+        return createTasksRuntime(executions, applicationRuntime);
+    },
+    projectGraph: ({ execution }) => {
+        const compiled = execution.compiled;
+        switch (compiled.type) {
+            case 'task':
+                return { type: 'task', name: compiled.name };
+            case 'cron':
+                return {
+                    type: 'cron',
+                    name: compiled.name,
+                    expression: compiled.expression,
+                    timezone: compiled.timezone,
+                    overlap: compiled.overlap,
+                    task: compiled.taskName,
+                };
+            case 'fixed-delay':
+                return {
+                    type: 'fixed-delay',
+                    name: compiled.name,
+                    delay: compiled.delay,
+                    immediate: compiled.immediate,
+                    task: compiled.taskName,
+                };
+            case 'queue-consumer':
+                return {
+                    type: 'queue-consumer',
+                    name: compiled.name,
+                    queue: compiled.queueName,
+                    task: compiled.taskName,
+                };
+        }
+    },
+    host: {
+        namespace: 'tasks',
+        create: ({ runtime }) => ({
+            run: (definition, ...arguments_) => Reflect.apply(runtime.run, runtime, [
+                taskExecutionIdentity(definition),
+                definition.name,
+                ...arguments_,
+            ]),
+            start: () => runtime.startTriggers(),
+            stop: () => runtime.stopTriggers(),
+        }),
+    },
+});
+export function task(definition) {
+    const taskExecutionId = Symbol(`loutre.tasks.execution:${definition.name}`);
+    return defineExecution(tasksExtension, {
+        type: 'task',
+        name: definition.name,
+        factory: definition.factory,
+        [taskExecutionIdentityKey]: taskExecutionId,
+    });
+}
+export function cron(declaration) {
+    return defineExecution(tasksExtension, {
+        type: 'cron',
+        name: declaration.name,
+        expression: declaration.expression,
+        timezone: declaration.timezone,
+        overlap: declaration.overlap ?? 'skip',
+        task: declaration.task,
+    });
+}
+export function fixedDelay(declaration) {
+    if (!Number.isFinite(declaration.delay) ||
+        !Number.isInteger(declaration.delay) ||
+        declaration.delay < 0) {
+        throw new Error('LUTRE_TRIGGER_INVALID_FIXED_DELAY: fixedDelay.delay must be a non-negative finite integer.');
+    }
+    return defineExecution(tasksExtension, {
+        type: 'fixed-delay',
+        name: declaration.name,
+        delay: declaration.delay,
+        immediate: declaration.immediate ?? false,
+        task: declaration.task,
+    });
+}
+export function queue(declaration) {
+    const payload = declaration.payload;
+    if (payload === null ||
+        (typeof payload !== 'object' && typeof payload !== 'function') ||
+        !('~standard' in payload)) {
+        throw new Error('LUTRE_QUEUE_PAYLOAD_SCHEMA: queue.payload must implement Standard Schema.');
+    }
+    return Object.freeze({
+        kind: 'queue',
+        name: declaration.name,
+        payload: declaration.payload,
+        [queueDriverToken]: token(`loutre.tasks.queue-driver.${declaration.name}`),
+    });
+}
+function queueRuntimeToken(descriptor) {
+    return descriptor[queueDriverToken];
+}
+export function bindQueueDriver(descriptor, driver) {
+    return provide(queueRuntimeToken(descriptor)).useValue(driver);
+}
+export function consume(declaration) {
+    return defineExecution(tasksExtension, {
+        type: 'queue-consumer',
+        name: declaration.name,
+        queue: declaration.queue,
+        task: declaration.task,
+    });
+}
+function createTasksRuntime(executions, applicationRuntime) {
+    const runtimes = new Map();
+    const runtimeExecutionIds = new Map();
+    const triggers = [];
+    for (const execution of executions) {
+        const compiled = execution.compiled;
+        if (compiled.type !== 'task') {
+            triggers.push(compiled);
+            continue;
+        }
+        const runtime = runInInjectionContext({
+            consumer: {
+                kind: 'execution',
+                id: `task:${compiled.name}`,
+                name: compiled.name,
+            },
+            resolve: (dependency) => applicationRuntime.resolve(dependency, execution.id),
+        }, () => compiled.factory());
+        runtimes.set(compiled.taskExecutionId, runtime);
+        runtimeExecutionIds.set(compiled.taskExecutionId, execution.id);
+    }
+    let triggerHandles = [];
+    let triggerStartup;
+    let triggerStop;
+    let triggersStarted = false;
+    let state = 'running';
+    const activeInvocations = new Set();
+    const invokeTask = (taskExecutionId, taskName, arguments_) => {
+        if (state !== 'running') {
+            return Promise.reject(new Error(`LUTRE_TASKS_${state.toUpperCase()}`));
+        }
+        const runtime = runtimes.get(taskExecutionId);
+        if (!runtime) {
+            return Promise.reject(new Error(`LUTRE_TASK_NOT_REGISTERED: ${taskName}`));
+        }
+        const invocation = (async () => {
+            const executionId = runtimeExecutionIds.get(taskExecutionId) ?? taskName;
+            const hasInput = arguments_.length > 0;
+            const input = hasInput ? arguments_[0] : undefined;
+            const lease = applicationRuntime.beginExecution({
+                executionId,
+                executionKind: 'task.invocation',
+                graphNodeId: executionId,
+                name: taskName,
+            }, {
+                input,
+                invoke: (nextInput) => invokeTask(taskExecutionId, taskName, hasInput ? [nextInput] : []),
+            });
+            let result;
+            let hasResult = false;
+            try {
+                const invoke = () => Reflect.apply(runtime, undefined, arguments_);
+                result = await (lease.run ? lease.run(invoke) : invoke());
+                hasResult = true;
+                return result;
+            }
+            catch (error) {
+                lease.fail?.(error);
+                throw error;
+            }
+            finally {
+                if (hasResult)
+                    lease.complete(result);
+                else
+                    lease.complete();
+            }
+        })();
+        activeInvocations.add(invocation);
+        void invocation.then(() => activeInvocations.delete(invocation), () => activeInvocations.delete(invocation));
+        return invocation;
+    };
+    const run = (taskExecutionId, taskName, ...arguments_) => invokeTask(taskExecutionId, taskName, arguments_);
+    const stopTriggers = () => {
+        if (triggerStop)
+            return triggerStop;
+        const stopping = (async () => {
+            const startup = triggerStartup;
+            if (startup)
+                await startup.catch(() => undefined);
+            const handles = triggerHandles;
+            const stopOrder = handles.toReversed();
+            const results = await Promise.allSettled(stopOrder.map((handle) => handle.stop()));
+            const failedHandles = [];
+            const errors = [];
+            for (const [index, result] of results.entries()) {
+                if (result.status !== 'rejected')
+                    continue;
+                failedHandles.push(stopOrder[index]);
+                errors.push(result.reason);
+            }
+            triggerHandles = failedHandles.toReversed();
+            triggersStarted = failedHandles.length > 0;
+            if (errors.length > 0) {
+                throw new AggregateError(errors, 'Trigger stop failed');
+            }
+        })();
+        let trackedStop;
+        trackedStop = stopping.finally(() => {
+            if (triggerStop === trackedStop)
+                triggerStop = undefined;
+        });
+        triggerStop = trackedStop;
+        return trackedStop;
+    };
+    const startTriggers = async () => {
+        if (state !== 'running') {
+            throw new Error(`LUTRE_TASKS_${state.toUpperCase()}`);
+        }
+        if (triggersStarted) {
+            throw new Error('LUTRE_TRIGGERS_ALREADY_STARTED: Trigger Engine is already started.');
+        }
+        const lease = applicationRuntime.beginExecution();
+        triggersStarted = true;
+        const started = [];
+        const startup = (async () => {
+            try {
+                for (const trigger of triggers) {
+                    if (trigger.type === 'task')
+                        continue;
+                    const handle = await startTrigger(trigger, run, applicationRuntime);
+                    started.push(handle);
+                    if (state !== 'running') {
+                        throw tasksStateError(state);
+                    }
+                }
+                triggerHandles = started;
+            }
+            catch (error) {
+                const stopOrder = started.toReversed();
+                const cleanupResults = await Promise.allSettled(stopOrder.map((handle) => handle.stop()));
+                const failedHandles = [];
+                const cleanupErrors = [];
+                for (const [index, result] of cleanupResults.entries()) {
+                    if (result.status !== 'rejected')
+                        continue;
+                    failedHandles.push(stopOrder[index]);
+                    cleanupErrors.push(result.reason);
+                }
+                triggerHandles = failedHandles.toReversed();
+                triggersStarted = failedHandles.length > 0;
+                if (cleanupErrors.length > 0) {
+                    throw new AggregateError([error, ...cleanupErrors], 'Trigger startup failed and cleanup also failed.', { cause: error });
+                }
+                throw error;
+            }
+        })();
+        let trackedStartup;
+        trackedStartup = startup.finally(() => {
+            lease.complete();
+            if (triggerStartup === trackedStartup)
+                triggerStartup = undefined;
+        });
+        triggerStartup = trackedStartup;
+        await trackedStartup;
+    };
+    return {
+        run: run,
+        startTriggers,
+        stopTriggers,
+        async drain() {
+            if (state === 'stopped')
+                return;
+            state = 'draining';
+            await stopTriggers();
+            await Promise.allSettled(activeInvocations);
+        },
+        async close() {
+            if (state === 'stopped')
+                return;
+            try {
+                await stopTriggers();
+            }
+            finally {
+                state = 'stopped';
+            }
+        },
+    };
+}
+async function startTrigger(trigger, run, applicationRuntime) {
+    switch (trigger.type) {
+        case 'cron':
+            return startCronTrigger(trigger, run);
+        case 'fixed-delay':
+            return startFixedDelayTrigger(trigger, run);
+        case 'queue-consumer':
+            return startQueueTrigger(trigger, run, applicationRuntime);
+    }
+}
+function startCronTrigger(trigger, run) {
+    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 = Math.floor(now.getTime() / 60_000);
+        if (lastMinute === minute)
+            return;
+        lastMinute = minute;
+        if (trigger.overlap === 'skip' && active.size > 0)
+            return;
+        const execution = run(trigger.taskExecutionId, trigger.taskName).catch(() => undefined);
+        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, run) {
+    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 () => {
+        await run(trigger.taskExecutionId, trigger.taskName).catch(() => undefined);
+    };
+    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, run, applicationRuntime) {
+    const driver = applicationRuntime.resolve(trigger.queueDriver);
+    if (!driver || typeof driver.start !== 'function') {
+        throw new Error(`LUTRE_QUEUE_DRIVER_INVALID: Queue ${trigger.queueName} driver is invalid.`);
+    }
+    const handle = await driver.start({
+        consume: async (payload) => {
+            const validated = await validateSchema(trigger.queuePayload, payload);
+            await run(trigger.taskExecutionId, trigger.taskName, validated);
+        },
+    });
+    if (!handle || typeof handle.stop !== 'function') {
+        throw new Error(`LUTRE_QUEUE_DRIVER_INVALID: Queue ${trigger.queueName} driver returned an invalid handle.`);
+    }
+    return handle;
+}
+function taskExecutionIdentity(definition) {
+    if (taskExecutionIdentityKey in definition &&
+        typeof definition[taskExecutionIdentityKey] === 'symbol') {
+        return definition[taskExecutionIdentityKey];
+    }
+    return Symbol('loutre.tasks.unregistered');
+}
+function tasksStateError(state) {
+    return new Error(`LUTRE_TASKS_${state.toUpperCase()}`);
+}

package/dist/tasks/index.d.ts

@@ -0,0 +1,2 @@
+export { bindQueueDriver, consume, cron, fixedDelay, queue, task, tasksExtension, } from './extension.js';
+export type { CronOverlap, CronTriggerDefinition, CronTriggerDefinitionData, FixedDelayTriggerDefinition, FixedDelayTriggerDefinitionData, QueueConsumerDriver, QueueConsumerHandle, QueueConsumerTriggerDefinition, QueueConsumerTriggerDefinitionData, QueueDescriptor, QueuePayload, TaskArguments, TaskDefinition, TaskDefinitionData, TaskExecutionIdentity, TaskInput, TaskOutput, TaskRuntime, TasksCompiledCronTrigger, TasksCompiledExecution, TasksCompiledFixedDelayTrigger, TasksCompiledQueueConsumerTrigger, TasksCompiledTask, TasksExtensionRuntime, TasksHostApi, TriggerDefinition, TriggerDefinitionData, } from './extension.js';

package/dist/tasks/index.js

@@ -0,0 +1 @@
+export { bindQueueDriver, consume, cron, fixedDelay, queue, task, tasksExtension, } from './extension.js';

package/dist/tasks/runtime/cron.d.ts

@@ -0,0 +1,6 @@
+export interface CronSchedule {
+    readonly expression: string;
+    readonly timezone: string;
+}
+export declare function matchesCronTrigger(trigger: CronSchedule, instant: Date): boolean;
+export declare function isValidCronExpression(expression: string): boolean;

package/dist/tasks/runtime/cron.js

@@ -0,0 +1,89 @@
+export function matchesCronTrigger(trigger, instant) {
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = trigger.expression
+        .trim()
+        .split(/\s+/);
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: trigger.timezone,
+        minute: 'numeric',
+        hour: 'numeric',
+        day: 'numeric',
+        month: 'numeric',
+        weekday: 'short',
+        hourCycle: 'h23',
+    }).formatToParts(instant);
+    const value = (type) => parts.find((part) => part.type === type)?.value ?? '';
+    const weekday = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(value('weekday'));
+    const dayOfMonthMatches = matchesCronField(dayOfMonth, Number(value('day')), 1, 31);
+    const dayOfWeekMatches = matchesCronField(dayOfWeek, weekday, 0, 7, true);
+    const bothDaysRestricted = !dayOfMonth.includes('*') && !dayOfWeek.includes('*');
+    const dayMatches = bothDaysRestricted
+        ? dayOfMonthMatches || dayOfWeekMatches
+        : dayOfMonthMatches && dayOfWeekMatches;
+    return (matchesCronField(minute, Number(value('minute')), 0, 59) &&
+        matchesCronField(hour, Number(value('hour')), 0, 23) &&
+        matchesCronField(month, Number(value('month')), 1, 12) &&
+        dayMatches);
+}
+export function isValidCronExpression(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return false;
+    const ranges = [
+        [0, 59],
+        [0, 23],
+        [1, 31],
+        [1, 12],
+        [0, 7],
+    ];
+    return fields.every((field, index) => {
+        const range = ranges[index];
+        return range !== undefined && isValidCronField(field, range[0], range[1]);
+    });
+}
+function matchesCronField(expression, value, minimum, maximum, sundayAlias = false) {
+    return expression.split(',').some((segment) => {
+        const [rangeExpression, stepExpression] = segment.split('/');
+        const step = stepExpression === undefined ? 1 : Number(stepExpression);
+        if (!Number.isInteger(step) || step <= 0 || !rangeExpression)
+            return false;
+        let start = minimum;
+        let end = maximum;
+        if (rangeExpression !== '*') {
+            const [startExpression, endExpression] = rangeExpression.split('-');
+            start = Number(startExpression);
+            end = endExpression === undefined ? start : Number(endExpression);
+        }
+        const candidates = sundayAlias && value === 0 ? [0, 7] : [value];
+        return (Number.isInteger(start) &&
+            Number.isInteger(end) &&
+            start >= minimum &&
+            end <= maximum &&
+            candidates.some((candidate) => candidate >= start &&
+                candidate <= end &&
+                (candidate - start) % step === 0));
+    });
+}
+function isValidCronField(field, minimum, maximum) {
+    return field.split(',').every((segment) => {
+        const parts = segment.split('/');
+        if (parts.length > 2)
+            return false;
+        const rangeExpression = parts[0];
+        const stepExpression = parts[1];
+        if (!rangeExpression)
+            return false;
+        if (stepExpression !== undefined &&
+            (!/^\d+$/.test(stepExpression) || Number(stepExpression) <= 0)) {
+            return false;
+        }
+        if (rangeExpression === '*')
+            return true;
+        const bounds = rangeExpression.split('-');
+        if (bounds.length > 2 || bounds.some((bound) => !/^\d+$/.test(bound))) {
+            return false;
+        }
+        const start = Number(bounds[0]);
+        const end = bounds[1] === undefined ? start : Number(bounds[1]);
+        return start >= minimum && end <= maximum && start <= end;
+    });
+}

package/dist/websocket/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class WebSocketMessageDecodeError extends Error {
+    constructor(cause?: unknown);
+}
+export declare class WebSocketMessageEncodeError extends Error {
+    constructor(cause?: unknown);
+}
+export declare class WebSocketConnectionNotOpenError extends Error {
+    constructor(cause?: unknown);
+}

package/dist/websocket/errors.js

@@ -0,0 +1,18 @@
+export class WebSocketMessageDecodeError extends Error {
+    constructor(cause) {
+        super('WebSocket message could not be decoded.', { cause });
+        this.name = 'WebSocketMessageDecodeError';
+    }
+}
+export class WebSocketMessageEncodeError extends Error {
+    constructor(cause) {
+        super('WebSocket message could not be encoded.', { cause });
+        this.name = 'WebSocketMessageEncodeError';
+    }
+}
+export class WebSocketConnectionNotOpenError extends Error {
+    constructor(cause) {
+        super('WebSocket connection is not open.', { cause });
+        this.name = 'WebSocketConnectionNotOpenError';
+    }
+}