@db3.ai/app 0.1.0-beta.1

package/src/scheduler/ScheduledJob.ts

@@ -0,0 +1,58 @@
+import { isQueueableJob, isQueueableJobClass, queueableJobName, type QueueableJob } from '../queue';
+import type * as scheduler from './contracts';
+import { ScheduledEvent } from './ScheduledEvent';
+
+/**
+ * Fluent daily schedule that creates a fresh QueueableJob when due.
+ */
+export class ScheduledJob extends ScheduledEvent {
+	readonly kind = 'job' as const;
+
+	/**
+	 * Creates a scheduled job definition.
+	 *
+	 * @param source - Zero-argument QueueableJob class or fresh-job factory.
+	 */
+	constructor(
+		private readonly source: scheduler.ScheduledJobSource,
+	) {
+		super();
+	}
+
+	/**
+	 * Creates the QueueableJob for one claimed occurrence.
+	 *
+	 * @returns Fresh serializable queue job.
+	 */
+	createJob(): QueueableJob {
+		const job = isQueueableJobClass(this.source)
+			? new this.source()
+			: this.source();
+
+		if (!isQueueableJob(job)) {
+			throw new Error(`Scheduled job "${this.resolvedName()}" did not create a QueueableJob.`);
+		}
+
+		return job;
+	}
+
+	/**
+	 * Returns the class job name when no factory invocation is required.
+	 *
+	 * @returns Durable queue job name, or null for factories.
+	 */
+	override resolvedJobName(): string | null {
+		if (!isQueueableJobClass(this.source)) return null;
+
+		return queueableJobName(this.source);
+	}
+
+	/**
+	 * Uses the durable class job name as the default schedule identity.
+	 *
+	 * @returns Default job name, or null for parameterised factories.
+	 */
+	protected override defaultName(): string | null {
+		return this.resolvedJobName();
+	}
+}

package/src/scheduler/ScheduledOccurrence.ts

@@ -0,0 +1,250 @@
+import { ulid } from '@db3.ai/pure/ulid';
+import { ActiveRecord, type FieldBuilder } from '../db';
+import { SCHEDULED_OCCURRENCE_STATUSES, SCHEDULED_TASK_KINDS } from './constants';
+import type * as scheduler from './contracts';
+
+const NAME_SCHEDULED_FOR_UNIQUE = 'scheduled_occurrences_name_scheduled_for_unique';
+const STATUS_SCHEDULED_FOR_INDEX = 'scheduled_occurrences_status_scheduled_for_index';
+
+/**
+ * Values required to atomically claim one due scheduled occurrence.
+ */
+interface ScheduledOccurrenceClaim {
+	/** Stable registered schedule name. */
+	name: string;
+	/** Scheduled task kind. */
+	kind: scheduler.ScheduledTaskKind;
+	/** Canonical UTC minute represented by the occurrence. */
+	scheduledFor: Date;
+	/** Queue job name when known before a factory is invoked. */
+	jobName?: string;
+}
+
+/**
+ * Durable claim, execution state, and queue correlation for one scheduled task.
+ */
+export class ScheduledOccurrence extends ActiveRecord {
+	static override table = 'scheduled_occurrences';
+	static override primaryKey = 'id';
+	static override labelFields = ['name', 'status'];
+	static override comment = 'Durable scheduler claims and lifecycle state for registered task occurrences.';
+
+	/**
+	 * Defines scheduler claim, queue correlation, lifecycle, and timing fields.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Scheduled occurrence field definitions.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable scheduled occurrence ULID.',
+			}),
+
+			name: field.string({
+				required: true,
+				length: 255,
+				maxLength: 255,
+				indexes: [{
+					name: NAME_SCHEDULED_FOR_UNIQUE,
+					columns: ['name', 'scheduled_for'],
+					unique: true,
+				}],
+				comment: 'Stable registered schedule name used for deduplication.',
+			}),
+
+			kind: field.choice({
+				required: true,
+				choices: SCHEDULED_TASK_KINDS,
+				length: 20,
+				maxLength: 20,
+				comment: 'Whether this occurrence dispatches a job or runs an inline call.',
+			}),
+
+			jobName: field.string({
+				column: 'job_name',
+				required: false,
+				length: 255,
+				maxLength: 255,
+				index: true,
+				comment: 'Durable queue job name for job occurrences.',
+			}),
+
+			scheduledFor: field.timestamp({
+				column: 'scheduled_for',
+				required: true,
+				precision: 0,
+				index: true,
+				comment: 'Canonical UTC minute represented by this occurrence.',
+			}),
+
+			status: field.choice({
+				required: true,
+				choices: SCHEDULED_OCCURRENCE_STATUSES,
+				default: 'claimed',
+				length: 20,
+				maxLength: 20,
+				indexes: [{
+					name: STATUS_SCHEDULED_FOR_INDEX,
+					columns: ['status', 'scheduled_for'],
+				}],
+				comment: 'Current scheduler or queue lifecycle state.',
+			}),
+
+			queueJobId: field.string({
+				column: 'queue_job_id',
+				required: false,
+				length: 255,
+				maxLength: 255,
+				index: true,
+				comment: 'Driver-owned queue job id after dispatch.',
+			}),
+
+			queueJobUuid: field.charUuid({
+				column: 'queue_job_uuid',
+				required: false,
+				index: true,
+				comment: 'Stable queue UUID retained across job attempts.',
+			}),
+
+			attempts: field.integer({
+				required: true,
+				unsigned: true,
+				min: 0,
+				default: 0,
+				comment: 'Number of queue processing attempts observed.',
+			}),
+
+			maxTries: field.integer({
+				column: 'max_tries',
+				required: false,
+				unsigned: true,
+				min: 1,
+				comment: 'Maximum queue attempts configured for this job.',
+			}),
+
+			lastError: field.longText({
+				column: 'last_error',
+				required: false,
+				comment: 'Most recent dispatch, callback, retry, or terminal failure.',
+			}),
+
+			nextAttemptAt: field.timestamp({
+				column: 'next_attempt_at',
+				required: false,
+				precision: 0,
+				comment: 'Expected availability time after a retry or deferral.',
+			}),
+
+			claimedAt: field.timestamp({
+				column: 'claimed_at',
+				required: true,
+				precision: 3,
+				comment: 'Time at which a scheduler process won this occurrence claim.',
+			}),
+
+			dispatchedAt: field.timestamp({
+				column: 'dispatched_at',
+				required: false,
+				precision: 3,
+				comment: 'Time at which the queue accepted the scheduled job.',
+			}),
+
+			startedAt: field.timestamp({
+				column: 'started_at',
+				required: false,
+				precision: 3,
+				comment: 'First worker claim or inline callback start time.',
+			}),
+
+			finishedAt: field.timestamp({
+				column: 'finished_at',
+				required: false,
+				precision: 3,
+				comment: 'Terminal scheduler or queue completion time.',
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				required: true,
+				precision: 3,
+				auto: 'update',
+				comment: 'Most recent lifecycle state change.',
+			}),
+		};
+	}
+
+	/**
+	 * Atomically claims one scheduled minute using the model's unique index.
+	 *
+	 * @param claim - Due schedule identity and task metadata.
+	 * @returns Newly claimed occurrence, or null when another process won.
+	 */
+	static async claim(claim: ScheduledOccurrenceClaim): Promise<ScheduledOccurrence | null> {
+		const claimedAt = new Date();
+		const occurrence = this.create({
+			id: ulid(claimedAt),
+			name: claim.name,
+			kind: claim.kind,
+			jobName: claim.jobName,
+			scheduledFor: claim.scheduledFor,
+			status: 'claimed',
+			attempts: 0,
+			claimedAt,
+			updatedAt: claimedAt,
+		});
+
+		try {
+			await occurrence.save();
+			return occurrence;
+		} catch (error) {
+			if (!isUniqueConstraintError(error)) throw error;
+
+			const existing = await this
+				.where({
+					name: claim.name,
+					scheduledFor: claim.scheduledFor,
+				})
+				.first();
+
+			if (existing) return null;
+
+			throw error;
+		}
+	}
+
+	declare id: string | null;
+	declare name: string | null;
+	declare kind: scheduler.ScheduledTaskKind | null;
+	declare jobName: string | null;
+	declare scheduledFor: Date | null;
+	declare status: scheduler.ScheduledOccurrenceStatus | null;
+	declare queueJobId: string | null;
+	declare queueJobUuid: string | null;
+	declare attempts: number | null;
+	declare maxTries: number | null;
+	declare lastError: string | null;
+	declare nextAttemptAt: Date | null;
+	declare claimedAt: Date | null;
+	declare dispatchedAt: Date | null;
+	declare startedAt: Date | null;
+	declare finishedAt: Date | null;
+	declare updatedAt: Date | null;
+}
+
+/**
+ * Returns whether a database error represents a unique-constraint conflict.
+ *
+ * @param error - Unknown database failure.
+ * @returns True for MariaDB, PostgreSQL, or SQLite unique conflicts.
+ */
+function isUniqueConstraintError(error: unknown): boolean {
+	if (!error || typeof error !== 'object') return false;
+
+	const code = String((error as { code?: unknown }).code ?? '');
+
+	return code === 'ER_DUP_ENTRY'
+		|| code === '23505'
+		|| code === 'SQLITE_CONSTRAINT'
+		|| code === 'SQLITE_CONSTRAINT_UNIQUE';
+}

package/src/scheduler/ScheduledOccurrenceRecorder.ts

@@ -0,0 +1,125 @@
+import { ActiveRecord, type Database } from '../db';
+import type { QueueLifecycleEvent } from '../queue';
+import { SCHEDULED_OCCURRENCE_ORIGIN } from './constants';
+import { ScheduledOccurrence } from './ScheduledOccurrence';
+
+const TERMINAL_STATUSES = new Set(['succeeded', 'failed']);
+
+/**
+ * Persists queue lifecycle events that originated from scheduled occurrences.
+ */
+export class ScheduledOccurrenceRecorder {
+	/**
+	 * Creates a recorder bound to one application database.
+	 *
+	 * @param database - Database containing scheduled occurrence records.
+	 */
+	constructor(
+		private readonly database: Database,
+	) {}
+
+	/**
+	 * Applies one queue event when it references a scheduled occurrence.
+	 *
+	 * @param event - Queue lifecycle event emitted by the worker or dispatcher.
+	 */
+	async record(event: QueueLifecycleEvent): Promise<void> {
+		if (event.origin?.type !== SCHEDULED_OCCURRENCE_ORIGIN) return;
+
+		await ActiveRecord.withDb(this.database.knex, async () => {
+			const occurrence = await ScheduledOccurrence.findByPk(event.origin?.id);
+
+			if (!occurrence) {
+				throw new Error(`Scheduled occurrence "${event.origin?.id}" was not found.`);
+			}
+
+			if (occurrence.status && TERMINAL_STATUSES.has(occurrence.status)) return;
+
+			this.applyEvent(occurrence, event);
+			await occurrence.save();
+		});
+	}
+
+	/**
+	 * Maps one queue lifecycle event onto its persisted occurrence.
+	 *
+	 * @param occurrence - Scheduled occurrence being updated.
+	 * @param event - Queue lifecycle event to apply.
+	 */
+	private applyEvent(
+		occurrence: ScheduledOccurrence,
+		event: QueueLifecycleEvent,
+	): void {
+		if (event.action === 'lease_lost') return;
+
+		const timestamp = new Date(event.timestamp);
+
+		occurrence.jobName = event.jobName;
+		occurrence.queueJobId = String(event.jobId);
+		occurrence.queueJobUuid = event.jobUuid;
+		occurrence.attempts = event.attempts;
+		occurrence.maxTries = event.maxTries;
+
+		if (event.error !== undefined) {
+			occurrence.lastError = errorDetails(event.error);
+		}
+
+		switch (event.action) {
+			case 'dispatched':
+				occurrence.status = 'queued';
+				occurrence.dispatchedAt ??= timestamp;
+				break;
+
+			case 'claimed':
+				occurrence.status = 'running';
+				occurrence.startedAt ??= timestamp;
+				occurrence.nextAttemptAt = null;
+				break;
+
+			case 'released':
+				occurrence.status = 'retrying';
+				occurrence.nextAttemptAt = delayedDate(timestamp, event.delaySeconds);
+				break;
+
+			case 'deferred':
+				occurrence.status = 'deferred';
+				occurrence.nextAttemptAt = delayedDate(timestamp, event.delaySeconds);
+				break;
+
+			case 'succeeded':
+				occurrence.status = 'succeeded';
+				occurrence.nextAttemptAt = null;
+				occurrence.finishedAt = timestamp;
+				break;
+
+			case 'failed':
+				occurrence.status = 'failed';
+				occurrence.nextAttemptAt = null;
+				occurrence.finishedAt = timestamp;
+				break;
+		}
+	}
+}
+
+/**
+ * Calculates the expected next-attempt time for a delayed queue event.
+ *
+ * @param timestamp - Time at which the queue transition occurred.
+ * @param delaySeconds - Delay before the next attempt.
+ * @returns Expected next attempt time.
+ */
+function delayedDate(timestamp: Date, delaySeconds = 0): Date {
+	return new Date(timestamp.getTime() + Math.max(0, delaySeconds) * 1000);
+}
+
+/**
+ * Formats an unknown error for durable scheduler diagnostics.
+ *
+ * @param error - Unknown thrown value.
+ * @returns Stack or human-readable error text.
+ */
+export function errorDetails(error: unknown): string {
+	if (error instanceof Error) return error.stack ?? error.message;
+
+	return String(error);
+}

package/src/scheduler/Scheduler.ts

@@ -0,0 +1,225 @@
+import { ActiveRecord, type Database } from '../db';
+import { isQueueableJobClass, queueableJobName, type Queue } from '../queue';
+import { SCHEDULED_OCCURRENCE_ORIGIN } from './constants';
+import type * as scheduler from './contracts';
+import { ScheduledCall } from './ScheduledCall';
+import { ScheduledEvent } from './ScheduledEvent';
+import { ScheduledJob } from './ScheduledJob';
+import { ScheduledOccurrence } from './ScheduledOccurrence';
+import { ScheduledOccurrenceRecorder, errorDetails } from './ScheduledOccurrenceRecorder';
+import { utcMinute } from './scheduleTime';
+
+/**
+ * Registers daily tasks, atomically claims due occurrences, and dispatches work.
+ */
+export class Scheduler {
+	readonly #events: ScheduledEvent[] = [];
+	readonly #unsubscribeQueueEvents: () => void;
+
+	/**
+	 * Creates a scheduler and attaches durable queue lifecycle recording.
+	 *
+	 * @param database - Application database containing occurrence history.
+	 * @param queue - Queue used to dispatch scheduled jobs.
+	 */
+	constructor(
+		private readonly database: Database,
+		private readonly queue: Queue,
+	) {
+		const recorder = new ScheduledOccurrenceRecorder(database);
+
+		this.#unsubscribeQueueEvents = queue.events.subscribe(event => {
+			return recorder.record(event);
+		});
+	}
+
+	/**
+	 * Registers a QueueableJob class or fresh-job factory.
+	 *
+	 * @param source - Zero-argument job class or parameterised factory.
+	 * @returns Fluent scheduled job definition.
+	 */
+	job(source: scheduler.ScheduledJobSource): ScheduledJob {
+		const event = new ScheduledJob(source);
+
+		this.#events.push(event);
+
+		return event;
+	}
+
+	/**
+	 * Registers a short inline callback.
+	 *
+	 * @param callback - Callback executed directly by the scheduler worker.
+	 * @returns Fluent scheduled call definition.
+	 */
+	call(callback: scheduler.ScheduledCallHandler): ScheduledCall {
+		const event = new ScheduledCall(callback);
+
+		this.#events.push(event);
+
+		return event;
+	}
+
+	/**
+	 * Returns validated normalized definitions in registration order.
+	 *
+	 * @returns Registered scheduler definitions.
+	 */
+	definitions(): scheduler.ScheduledTaskDefinition[] {
+		const definitions = this.#events.map(event => event.definition());
+		const names = new Set<string>();
+
+		for (const definition of definitions) {
+			if (names.has(definition.name)) {
+				throw new Error(`Duplicate scheduled event name "${definition.name}".`);
+			}
+
+			names.add(definition.name);
+		}
+
+		return definitions;
+	}
+
+	/**
+	 * Evaluates and handles every task due for one canonical UTC minute.
+	 *
+	 * Due tasks run sequentially in registration order. Immediate failures are
+	 * recorded and aggregated so one task cannot prevent later tasks from being
+	 * considered.
+	 *
+	 * @param now - Instant whose UTC minute should be evaluated.
+	 * @returns Structured evaluation summary.
+	 */
+	async runDue(now: Date = new Date()): Promise<scheduler.SchedulerRunResult> {
+		const startedAt = new Date();
+		const evaluatedFor = utcMinute(now);
+
+		this.definitions();
+
+		const dueEvents = this.#events.filter(event => event.isDue(evaluatedFor));
+		const result: scheduler.SchedulerRunResult = {
+			evaluatedFor,
+			startedAt,
+			finishedAt: startedAt,
+			due: dueEvents.length,
+			claimed: 0,
+			dispatched: 0,
+			completed: 0,
+			skipped: 0,
+			failures: [],
+		};
+
+		for (const event of dueEvents) {
+			const definition = event.definition();
+			const occurrence = await ActiveRecord.withDb(this.database.knex, () => {
+				return ScheduledOccurrence.claim({
+					name: definition.name,
+					kind: definition.kind,
+					scheduledFor: evaluatedFor,
+					jobName: definition.jobName,
+				});
+			});
+
+			if (!occurrence) {
+				result.skipped += 1;
+				continue;
+			}
+
+			result.claimed += 1;
+
+			try {
+				if (event instanceof ScheduledJob) {
+					await this.dispatchJob(event, occurrence);
+					result.dispatched += 1;
+				} else if (event instanceof ScheduledCall) {
+					await this.runCall(event, occurrence);
+					result.completed += 1;
+				}
+			} catch (error) {
+				await this.failOccurrence(occurrence, error);
+				result.failures.push({
+					name: definition.name,
+					error: errorDetails(error),
+				});
+			}
+		}
+
+		result.finishedAt = new Date();
+
+		return result;
+	}
+
+	/**
+	 * Detaches queue lifecycle recording owned by this scheduler instance.
+	 */
+	close(): void {
+		this.#unsubscribeQueueEvents();
+	}
+
+	/**
+	 * Creates and dispatches one job with occurrence origin metadata.
+	 *
+	 * @param event - Claimed scheduled job definition.
+	 * @param occurrence - Durable occurrence receiving queue events.
+	 */
+	private async dispatchJob(
+		event: ScheduledJob,
+		occurrence: ScheduledOccurrence,
+	): Promise<void> {
+		const job = event.createJob();
+		const Job = job.constructor;
+
+		occurrence.jobName = isQueueableJobClass(Job)
+			? queueableJobName(Job)
+			: Job.name;
+		await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+
+		await this.queue.dispatch(job, {
+			origin: {
+				type: SCHEDULED_OCCURRENCE_ORIGIN,
+				id: occurrence.id as string,
+			},
+		});
+	}
+
+	/**
+	 * Runs one short inline callback and records its terminal state.
+	 *
+	 * @param event - Claimed scheduled callback.
+	 * @param occurrence - Durable occurrence to update.
+	 */
+	private async runCall(
+		event: ScheduledCall,
+		occurrence: ScheduledOccurrence,
+	): Promise<void> {
+		const startedAt = new Date();
+
+		occurrence.status = 'running';
+		occurrence.startedAt = startedAt;
+		await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+		await event.run();
+
+		occurrence.status = 'succeeded';
+		occurrence.finishedAt = new Date();
+		await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+	}
+
+	/**
+	 * Records an immediate dispatch, factory, or inline callback failure.
+	 *
+	 * @param occurrence - Claimed occurrence that failed.
+	 * @param error - Immediate scheduler error.
+	 */
+	private async failOccurrence(
+		occurrence: ScheduledOccurrence,
+		error: unknown,
+	): Promise<void> {
+		occurrence.status = 'failed';
+		occurrence.lastError = errorDetails(error);
+		occurrence.nextAttemptAt = null;
+		occurrence.finishedAt = new Date();
+
+		await ActiveRecord.withDb(this.database.knex, () => occurrence.save());
+	}
+}