@db3.ai/app 0.1.0-beta.1

package/src/scheduler/SchedulerWorker.ts

@@ -0,0 +1,151 @@
+import type * as scheduler from './contracts';
+import { Scheduler } from './Scheduler';
+
+const DEFAULT_SLOW_TICK_WARNING_MS = 50_000;
+
+/**
+ * Long-running minute-aligned process adapter around Scheduler.runDue().
+ */
+export class SchedulerWorker {
+	#running = false;
+	#abortController: AbortController | null = null;
+	readonly #now: () => Date;
+	readonly #sleep: scheduler.SchedulerSleep;
+	readonly #logger: scheduler.SchedulerLogger;
+	readonly #slowTickWarningMs: number;
+
+	/**
+	 * Creates a scheduler worker with injectable timing dependencies.
+	 *
+	 * @param schedulerService - Scheduler core evaluated on every tick.
+	 * @param options - Clock, sleeper, logger, and warning overrides.
+	 */
+	constructor(
+		private readonly schedulerService: Scheduler,
+		options: scheduler.SchedulerWorkerOptions = {},
+	) {
+		this.#now = options.now ?? (() => new Date());
+		this.#sleep = options.sleep ?? schedulerSleep;
+		this.#logger = options.logger ?? consoleSchedulerLogger();
+		this.#slowTickWarningMs = options.slowTickWarningMs
+			?? DEFAULT_SLOW_TICK_WARNING_MS;
+	}
+
+	/**
+	 * Runs immediately, then evaluates at each subsequent wall-clock minute.
+	 *
+	 * @throws Error when the same worker instance is started twice.
+	 */
+	async start(): Promise<void> {
+		if (this.#running) {
+			throw new Error('SchedulerWorker is already running.');
+		}
+
+		this.#running = true;
+		this.#abortController = new AbortController();
+
+		try {
+			while (this.#running) {
+				await this.runTick();
+
+				if (!this.#running) break;
+
+				await this.#sleep(
+					millisecondsUntilNextMinute(this.#now()),
+					this.#abortController.signal,
+				);
+			}
+		} finally {
+			this.#running = false;
+			this.#abortController = null;
+		}
+	}
+
+	/**
+	 * Requests graceful shutdown and interrupts the current minute wait.
+	 */
+	stop(): void {
+		this.#running = false;
+		this.#abortController?.abort();
+	}
+
+	/**
+	 * Evaluates one scheduler minute and reports failures without ending work.
+	 */
+	private async runTick(): Promise<void> {
+		const startedAt = performance.now();
+
+		try {
+			const result = await this.schedulerService.runDue(this.#now());
+
+			if (result.due > 0 || result.failures.length > 0) {
+				this.#logger.info(
+					`[scheduler] ${result.evaluatedFor.toISOString()} due=${result.due} claimed=${result.claimed} dispatched=${result.dispatched} completed=${result.completed} skipped=${result.skipped} failed=${result.failures.length}.`,
+				);
+			}
+
+			for (const failure of result.failures) {
+				this.#logger.error(
+					`[scheduler] Scheduled event "${failure.name}" failed: ${failure.error}`,
+				);
+			}
+		} catch (error) {
+			this.#logger.error('[scheduler] Tick failed; the worker will continue.', error);
+		}
+
+		const durationMs = performance.now() - startedAt;
+
+		if (durationMs >= this.#slowTickWarningMs) {
+			this.#logger.warn(
+				`[scheduler] Tick took ${Math.round(durationMs)}ms; inline calls should remain short.`,
+			);
+		}
+	}
+}
+
+/**
+ * Calculates the delay from one instant to the next UTC minute boundary.
+ *
+ * @param now - Current clock time.
+ * @returns Delay in milliseconds, always between one and sixty seconds.
+ */
+export function millisecondsUntilNextMinute(now: Date): number {
+	const remainder = now.getTime() % 60_000;
+
+	return remainder === 0 ? 60_000 : 60_000 - remainder;
+}
+
+/**
+ * Sleeps until a timeout expires or the worker aborts its wait.
+ *
+ * @param delayMs - Milliseconds to wait.
+ * @param signal - Worker shutdown signal.
+ */
+async function schedulerSleep(
+	delayMs: number,
+	signal: AbortSignal,
+): Promise<void> {
+	await new Promise<void>(resolve => {
+		const timeout = setTimeout(resolve, delayMs);
+
+		signal.addEventListener('abort', () => {
+			clearTimeout(timeout);
+			resolve();
+		}, {
+			once: true,
+		});
+	});
+}
+
+/**
+ * Creates the default console-backed scheduler logger.
+ *
+ * @returns Scheduler logger writing to standard console methods.
+ */
+function consoleSchedulerLogger(): scheduler.SchedulerLogger {
+	return {
+		info: message => console.log(message),
+		warn: message => console.warn(message),
+		error: (message, error) => console.error(message, error ?? ''),
+	};
+}

package/src/scheduler/console.ts

@@ -0,0 +1,368 @@
+import { unknownErrorMessage } from '@db3.ai/pure';
+
+import { SCHEDULED_OCCURRENCE_STATUSES } from './constants';
+import type * as scheduler from './contracts';
+import { ScheduledOccurrence } from './ScheduledOccurrence';
+import type { Scheduler } from './Scheduler';
+import { SchedulerWorker } from './SchedulerWorker';
+
+/**
+ * Runs one framework scheduler console command.
+ *
+ * `scheduler:work` remains alive and evaluates schedules every minute. The
+ * other commands bootstrap, execute once, and close application resources.
+ *
+ * @param options - Application factory, bootstrap hook, and help overrides.
+ * @param argv - Command arguments without the Node executable or script path.
+ */
+export async function runSchedulerConsole(
+	options: scheduler.SchedulerConsoleOptions,
+	argv = process.argv.slice(2),
+): Promise<void> {
+	const parsed = parseSchedulerConsoleArgs(argv);
+
+	switch (parsed.command) {
+		case 'scheduler:work':
+			await bootstrap(options);
+			await workScheduler(options);
+			return;
+
+		case 'scheduler:run':
+			await runWithApp(options, async app => {
+				const result = await app.scheduler.runDue();
+
+				logRunResult(result);
+
+				if (result.failures.length > 0) {
+					throw new Error(`${result.failures.length} scheduled event(s) failed.`);
+				}
+			});
+			return;
+
+		case 'scheduler:list':
+			await runWithApp(options, app => {
+				for (const definition of app.scheduler.definitions()) {
+					console.log(
+						`${definition.name}\t${definition.kind}\tdaily at ${definition.frequency.time}\t${definition.timezone}${definition.jobName ? `\t${definition.jobName}` : ''}`,
+					);
+				}
+			});
+			return;
+
+		case 'scheduler:history':
+			await runWithApp(options, async () => {
+				await printHistory(parsed);
+			});
+			return;
+
+		case 'scheduler:help':
+		case 'help':
+		case '':
+			printHelp(options);
+			return;
+	}
+
+	throw new Error(
+		options.unknownCommandMessage?.(parsed.command)
+			?? `Unknown scheduler command "${parsed.command}".`,
+	);
+}
+
+/**
+ * Parses scheduler console positional arguments and long options.
+ *
+ * @param argv - Command arguments without the executable or script path.
+ * @returns Parsed command input.
+ */
+export function parseSchedulerConsoleArgs(
+	argv: string[],
+): scheduler.ParsedSchedulerConsoleArgs {
+	const [command = '', ...rest] = argv;
+	const args: string[] = [];
+	const options: Record<string, string | boolean> = {};
+
+	for (let index = 0; index < rest.length; index += 1) {
+		const value = rest[index];
+
+		if (!value.startsWith('--')) {
+			args.push(value);
+			continue;
+		}
+
+		const [rawKey, inlineValue] = value.slice(2).split('=', 2);
+		const key = rawKey.trim();
+
+		if (!key) continue;
+
+		if (inlineValue !== undefined) {
+			options[key] = inlineValue;
+			continue;
+		}
+
+		const next = rest[index + 1];
+
+		if (next && !next.startsWith('--')) {
+			options[key] = next;
+			index += 1;
+			continue;
+		}
+
+		options[key] = true;
+	}
+
+	return {
+		command,
+		args,
+		options,
+	};
+}
+
+/**
+ * Runs a one-off command against a bootstrapped application and closes it.
+ *
+ * @param options - Scheduler console options.
+ * @param callback - Command body receiving the active application.
+ */
+async function runWithApp(
+	options: scheduler.SchedulerConsoleOptions,
+	callback: (app: scheduler.SchedulerConsoleApp) => void | Promise<void>,
+): Promise<void> {
+	await bootstrap(options);
+
+	const app = options.app();
+
+	try {
+		await callback(app);
+	} finally {
+		await app.close();
+	}
+}
+
+/**
+ * Starts the dedicated scheduler worker until the process receives a signal.
+ *
+ * @param options - Scheduler console options with a bootstrapped app factory.
+ */
+async function workScheduler(
+	options: scheduler.SchedulerConsoleOptions,
+): Promise<void> {
+	process.title = process.env.SCHEDULER_NAME?.trim() || 'scheduler';
+
+	const app = options.app();
+
+	app.scheduler.definitions();
+
+	const worker = new SchedulerWorker(app.scheduler, {
+		logger: app.log ? schedulerLogger(app.log) : undefined,
+	});
+	let shuttingDown = false;
+
+	/**
+	 * Requests an orderly worker stop for an operating-system signal.
+	 *
+	 * @param signal - Signal received by the scheduler process.
+	 */
+	const shutdown = (signal: string): void => {
+		if (shuttingDown) return;
+
+		shuttingDown = true;
+		console.log(`[scheduler] Received ${signal}; stopping worker.`);
+		worker.stop();
+	};
+
+	/**
+	 * Stops the scheduler after SIGINT.
+	 */
+	const onSigint = (): void => {
+		shutdown('SIGINT');
+	};
+
+	/**
+	 * Stops the scheduler after SIGTERM.
+	 */
+	const onSigterm = (): void => {
+		shutdown('SIGTERM');
+	};
+
+	process.once('SIGINT', onSigint);
+	process.once('SIGTERM', onSigterm);
+
+	try {
+		await worker.start();
+	} finally {
+		process.removeListener('SIGINT', onSigint);
+		process.removeListener('SIGTERM', onSigterm);
+		await app.close();
+	}
+}
+
+/**
+ * Adapts the structured application logger to scheduler worker semantics.
+ *
+ * @param logger - Application logger shared by the scheduler process.
+ * @returns Scheduler logger with component context and structured errors.
+ */
+function schedulerLogger(
+	logger: NonNullable<scheduler.SchedulerConsoleApp['log']>,
+): scheduler.SchedulerLogger {
+	const child = logger.child({
+		component: 'scheduler-worker',
+	});
+
+	return {
+		info: message => child.info(message),
+		warn: message => child.warn(message),
+		error: (message, error) => {
+			if (error === undefined) {
+				child.error(message);
+				return;
+			}
+
+			child.error({
+				err: error,
+			}, message);
+		},
+	};
+}
+
+/**
+ * Prints recent scheduled occurrence history in newest-first order.
+ *
+ * @param parsed - Parsed command options containing an optional limit.
+ */
+async function printHistory(
+	parsed: scheduler.ParsedSchedulerConsoleArgs,
+): Promise<void> {
+	const limit = schedulerConsoleLimit(parsed);
+	let query = ScheduledOccurrence.query()
+		.orderBy('scheduledFor', 'desc')
+		.limit(limit);
+	const status = schedulerConsoleOptionString(parsed, 'status');
+
+	if (status) {
+		query = query.where('status', schedulerStatus(status));
+	}
+
+	const occurrences = await query.all();
+
+	if (occurrences.length === 0) {
+		console.log('[scheduler] No scheduled occurrences found.');
+		return;
+	}
+
+	for (const occurrence of occurrences) {
+		console.log([
+			occurrence.scheduledFor?.toISOString() ?? '-',
+			occurrence.name ?? '-',
+			occurrence.kind ?? '-',
+			occurrence.status ?? '-',
+			occurrence.queueJobId ?? '-',
+			occurrence.attempts ?? 0,
+			occurrence.lastError?.split('\n', 1)[0] ?? '-',
+		].join('\t'));
+	}
+}
+
+/**
+ * Resolves and validates the bounded scheduler history limit.
+ *
+ * @param parsed - Parsed scheduler command options.
+ * @returns History row limit between one and two hundred.
+ */
+function schedulerConsoleLimit(
+	parsed: scheduler.ParsedSchedulerConsoleArgs,
+): number {
+	const rawValue = schedulerConsoleOptionString(parsed, 'limit') ?? '25';
+	const limit = Number(rawValue);
+
+	if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+		throw new Error('Scheduler history limit must be an integer from 1 to 200.');
+	}
+
+	return limit;
+}
+
+/**
+ * Validates a scheduler occurrence status filter.
+ *
+ * @param value - Raw console option value.
+ * @returns Validated occurrence status.
+ */
+function schedulerStatus(value: string): scheduler.ScheduledOccurrenceStatus {
+	if (!SCHEDULED_OCCURRENCE_STATUSES.includes(value as scheduler.ScheduledOccurrenceStatus)) {
+		throw new Error(`Invalid scheduler status "${value}".`);
+	}
+
+	return value as scheduler.ScheduledOccurrenceStatus;
+}
+
+/**
+ * Returns a trimmed string option when present.
+ *
+ * @param parsed - Parsed command input.
+ * @param name - Option name without leading dashes.
+ * @returns Trimmed string option or undefined.
+ */
+function schedulerConsoleOptionString(
+	parsed: scheduler.ParsedSchedulerConsoleArgs,
+	name: string,
+): string | undefined {
+	const value = parsed.options[name];
+
+	return typeof value === 'string' && value.trim()
+		? value.trim()
+		: undefined;
+}
+
+/**
+ * Runs an optional application bootstrap hook.
+ *
+ * @param options - Scheduler console options.
+ */
+async function bootstrap(options: scheduler.SchedulerConsoleOptions): Promise<void> {
+	await options.bootstrap?.();
+}
+
+/**
+ * Prints the configured or framework-default scheduler help.
+ *
+ * @param options - Scheduler console options.
+ */
+function printHelp(options: scheduler.SchedulerConsoleOptions): void {
+	console.log(options.helpText ?? defaultHelpText());
+}
+
+/**
+ * Builds the default scheduler command help.
+ *
+ * @returns Framework scheduler help text.
+ */
+function defaultHelpText(): string {
+	return `Scheduler commands
+
+  scheduler:work
+  scheduler:run
+  scheduler:list
+  scheduler:history [--limit=25] [--status=failed]
+  scheduler:help
+`;
+}
+
+/**
+ * Prints a concise result from one scheduler evaluation.
+ *
+ * @param result - Completed scheduler evaluation.
+ */
+function logRunResult(
+	result: Awaited<ReturnType<Scheduler['runDue']>>,
+): void {
+	console.log(
+		`[scheduler] ${result.evaluatedFor.toISOString()} due=${result.due} claimed=${result.claimed} dispatched=${result.dispatched} completed=${result.completed} skipped=${result.skipped} failed=${result.failures.length}.`,
+	);
+
+	for (const failure of result.failures) {
+		console.error(
+			`[scheduler] Scheduled event "${failure.name}" failed: ${unknownErrorMessage(failure.error)}`,
+		);
+	}
+}

package/src/scheduler/constants.ts

@@ -0,0 +1,27 @@
+import type * as scheduler from './contracts';
+
+/**
+ * Stable origin type persisted on queue jobs dispatched by the scheduler.
+ */
+export const SCHEDULED_OCCURRENCE_ORIGIN = 'scheduled-occurrence';
+
+/**
+ * Supported scheduled occurrence status values.
+ */
+export const SCHEDULED_OCCURRENCE_STATUSES: scheduler.ScheduledOccurrenceStatus[] = [
+	'claimed',
+	'queued',
+	'running',
+	'retrying',
+	'deferred',
+	'succeeded',
+	'failed',
+];
+
+/**
+ * Supported scheduled task kinds.
+ */
+export const SCHEDULED_TASK_KINDS: scheduler.ScheduledTaskKind[] = [
+	'job',
+	'call',
+];

package/src/scheduler/contracts/Scheduler.ts

@@ -0,0 +1,123 @@
+import type { QueueableJob } from '../../queue';
+
+/**
+ * Supported scheduled task kinds.
+ */
+export type ScheduledTaskKind = 'job' | 'call';
+
+/**
+ * Durable lifecycle states recorded for one scheduled occurrence.
+ */
+export type ScheduledOccurrenceStatus =
+	| 'claimed'
+	| 'queued'
+	| 'running'
+	| 'retrying'
+	| 'deferred'
+	| 'succeeded'
+	| 'failed';
+
+/**
+ * Daily frequency supported by the initial scheduler implementation.
+ */
+export interface DailyScheduleFrequency {
+	/** Frequency discriminator reserved for future schedule types. */
+	type: 'daily';
+	/** Local wall-clock time in 24-hour HH:mm format. */
+	time: string;
+}
+
+/**
+ * Normalized public description of one registered schedule.
+ */
+export interface ScheduledTaskDefinition {
+	/** Stable task name used for deduplication and history. */
+	name: string;
+	/** Whether the task dispatches a job or executes an inline callback. */
+	kind: ScheduledTaskKind;
+	/** Daily frequency and local wall-clock time. */
+	frequency: DailyScheduleFrequency;
+	/** IANA timezone used to interpret the frequency. */
+	timezone: string;
+	/** Durable queue job name when known without invoking a factory. */
+	jobName?: string;
+}
+
+/**
+ * Zero-argument QueueableJob class accepted directly by Scheduler.job().
+ *
+ * Jobs with constructor parameters must use a fresh-job factory instead.
+ */
+export interface ScheduledJobClass {
+	/** Runtime class name used as the default durable schedule and queue name. */
+	readonly name: string;
+	/** Optional stable queue job name override. */
+	readonly jobName?: string;
+	/** Creates a fresh job without runtime constructor dependencies. */
+	new(): QueueableJob;
+	/**
+	 * Rehydrates a queued instance from persisted job data.
+	 *
+	 * @param data - JSON-safe queue payload.
+	 * @returns Rehydrated job instance.
+	 */
+	fromJSON(data: Record<string, unknown>): QueueableJob;
+}
+
+/**
+ * Zero-argument class or fresh-job factory accepted by Scheduler.job().
+ */
+export type ScheduledJobSource =
+	| ScheduledJobClass
+	| (() => QueueableJob);
+
+/**
+ * Short synchronous or asynchronous callback accepted by Scheduler.call().
+ */
+export type ScheduledCallHandler = () => unknown | Promise<unknown>;
+
+/**
+ * Immediate scheduler failure raised while dispatching or running a due task.
+ */
+export interface SchedulerFailure {
+	/** Stable schedule name that failed. */
+	name: string;
+	/** Human-readable failure message suitable for logs and CLI output. */
+	error: string;
+}
+
+/**
+ * Summary returned after evaluating all tasks for one UTC minute.
+ */
+export interface SchedulerRunResult {
+	/** UTC minute evaluated by the scheduler. */
+	evaluatedFor: Date;
+	/** Time at which evaluation began. */
+	startedAt: Date;
+	/** Time at which evaluation finished. */
+	finishedAt: Date;
+	/** Registered definitions whose local schedule matched the minute. */
+	due: number;
+	/** Due occurrences atomically claimed by this scheduler process. */
+	claimed: number;
+	/** Claimed jobs successfully accepted by the queue. */
+	dispatched: number;
+	/** Claimed inline calls that completed successfully. */
+	completed: number;
+	/** Due occurrences already claimed by another process. */
+	skipped: number;
+	/** Immediate dispatch or inline-call failures. */
+	failures: SchedulerFailure[];
+}
+
+/**
+ * Logger used by scheduler workers and console adapters.
+ */
+export interface SchedulerLogger {
+	/** Writes normal scheduler progress. */
+	info(message: string): void;
+	/** Writes slow-tick or recoverable scheduler warnings. */
+	warn(message: string): void;
+	/** Writes scheduler failures. */
+	error(message: string, error?: unknown): void;
+}

package/src/scheduler/contracts/SchedulerConsole.ts

@@ -0,0 +1,40 @@
+import type { Scheduler } from '../Scheduler';
+import type { Logger } from '../../logging';
+
+/**
+ * Parsed scheduler command name, positional arguments, and long options.
+ */
+export interface ParsedSchedulerConsoleArgs {
+	/** Command selected by the caller. */
+	command: string;
+	/** Positional command arguments. */
+	args: string[];
+	/** Parsed `--name=value` or `--name value` options. */
+	options: Record<string, string | boolean>;
+}
+
+/**
+ * Minimum application surface required by the framework scheduler console.
+ */
+export interface SchedulerConsoleApp {
+	/** Application scheduler with all application definitions registered. */
+	scheduler: Scheduler;
+	/** Application logger used by the long-running scheduler when available. */
+	log?: Logger;
+	/** Releases database, queue, and other process resources. */
+	close(): void | Promise<void>;
+}
+
+/**
+ * Application hooks and help customisation for scheduler console commands.
+ */
+export interface SchedulerConsoleOptions {
+	/** Resolves the active application instance after bootstrap. */
+	app: () => SchedulerConsoleApp;
+	/** Prepares schema, queue jobs, and schedule definitions. */
+	bootstrap?: () => void | Promise<void>;
+	/** Optional application-specific help text. */
+	helpText?: string;
+	/** Optional application-specific unknown-command message. */
+	unknownCommandMessage?: (command: string) => string;
+}