@rebasepro/server-core 0.7.0 → 0.9.0

package/src/cron/cron-scheduler.ts

@@ -1,581 +0,0 @@
-import type {
-    CronJobDefinition,
-    CronJobStatus,
-    CronJobLogEntry,
-    CronJobRunState,
-    CronJobContext
-} from "@rebasepro/types";
-import type { RebaseClient } from "@rebasepro/types";
-import type { LoadedCronJob } from "./cron-loader";
-import type { CronStore } from "./cron-store";
-import { logger } from "../utils/logger.js";
-
-// ─── Cron expression parser (minimal, no external dependency) ────────
-// Supports standard 5-field cron (minute hour dom month dow).
-// Returns the next Date after `after` that matches the expression.
-
-/**
- * Expand a single cron field into an ordered array of allowed values.
- * Supports: `*`, `N`, `N-M`, `N/S`, `N-M/S`, `*\/S`, and comma-separated combinations.
- */
-function expandCronField(field: string, min: number, max: number): number[] {
-    const results = new Set<number>();
-    for (const segment of field.split(",")) {
-        const trimmed = segment.trim();
-        if (trimmed === "*") {
-            for (let i = min; i <= max; i++) results.add(i);
-        } else if (trimmed.includes("/")) {
-            const [rangeStr, stepStr] = trimmed.split("/");
-            const step = parseInt(stepStr, 10);
-            if (isNaN(step) || step <= 0) {
-                throw new Error(`Invalid step value "${stepStr}" in cron field "${field}"`);
-            }
-            let start = min;
-            let end = max;
-            if (rangeStr !== "*") {
-                if (rangeStr.includes("-")) {
-                    const [a, b] = rangeStr.split("-").map(Number);
-                    start = a;
-                    end = b;
-                } else {
-                    start = parseInt(rangeStr, 10);
-                }
-            }
-            for (let i = start; i <= end; i += step) results.add(i);
-        } else if (trimmed.includes("-")) {
-            const [a, b] = trimmed.split("-").map(Number);
-            for (let i = a; i <= b; i++) results.add(i);
-        } else {
-            const val = parseInt(trimmed, 10);
-            if (isNaN(val)) {
-                throw new Error(`Invalid value "${trimmed}" in cron field "${field}"`);
-            }
-            results.add(val);
-        }
-    }
-    return [...results].sort((a, b) => a - b);
-}
-
-/**
- * Validates a standard 5-field cron expression structurally and semantically.
- * Returns `{ valid: true }` or `{ valid: false, reason: string }`.
- */
-export function validateCronExpression(schedule: string): { valid: true } | { valid: false; reason: string } {
-    if (!schedule || typeof schedule !== "string") {
-        return { valid: false,
-reason: "Schedule must be a non-empty string" };
-    }
-    const parts = schedule.trim().split(/\s+/);
-    if (parts.length !== 5) {
-        return { valid: false,
-reason: `Expected 5 fields, got ${parts.length}` };
-    }
-    const fieldRanges: [string, number, number][] = [
-        ["minute", 0, 59],
-        ["hour", 0, 23],
-        ["day of month", 1, 31],
-        ["month", 1, 12],
-        ["day of week", 0, 6]
-    ];
-    for (let i = 0; i < 5; i++) {
-        const [name, min, max] = fieldRanges[i];
-        try {
-            const values = expandCronField(parts[i], min, max);
-            if (values.length === 0) {
-                return { valid: false,
-reason: `${name} field "${parts[i]}" produces no values` };
-            }
-            for (const v of values) {
-                if (v < min || v > max) {
-                    return { valid: false,
-reason: `${name} field value ${v} out of range [${min}–${max}]` };
-                }
-            }
-        } catch (err) {
-            return { valid: false,
-reason: `${name} field: ${err instanceof Error ? err.message : String(err)}` };
-        }
-    }
-    return { valid: true };
-}
-
-/**
- * Calculate the next Date after `after` that matches the cron expression.
- * Throws on invalid expressions.
- */
-function parseCronExpression(expression: string, after: Date): Date {
-    const parts = expression.trim().split(/\s+/);
-    if (parts.length < 5) {
-        throw new Error(`Invalid cron expression: "${expression}". Expected 5 fields.`);
-    }
-
-    const [minField, hourField, domField, monField, dowField] = parts;
-
-    const minutes = expandCronField(minField, 0, 59);
-    const hours = expandCronField(hourField, 0, 23);
-    const doms = expandCronField(domField, 1, 31);
-    const months = expandCronField(monField, 1, 12);
-    const dows = expandCronField(dowField, 0, 6); // 0=Sunday
-
-    // Forward-search from `after + 1 minute`
-    const candidate = new Date(after);
-    candidate.setSeconds(0, 0);
-    candidate.setMinutes(candidate.getMinutes() + 1);
-
-    const maxIterations = 525960; // ~1 year in minutes
-    for (let i = 0; i < maxIterations; i++) {
-        const month = candidate.getMonth() + 1; // 1-12
-        const dom = candidate.getDate();
-        const dow = candidate.getDay(); // 0=Sunday
-        const hour = candidate.getHours();
-        const minute = candidate.getMinutes();
-
-        if (
-            months.includes(month) &&
-            doms.includes(dom) &&
-            dows.includes(dow) &&
-            hours.includes(hour) &&
-            minutes.includes(minute)
-        ) {
-            return candidate;
-        }
-        candidate.setMinutes(candidate.getMinutes() + 1);
-    }
-
-    // Fallback — should not happen with valid expressions
-    const fallback = new Date(after);
-    fallback.setMinutes(fallback.getMinutes() + 1);
-    return fallback;
-}
-
-// ─── In-memory ring buffer for logs ──────────────────────────────────
-
-const MAX_LOGS_PER_JOB = 50;
-
-/**
- * Minimum milliseconds between scheduled executions of the same job.
- * Prevents tight re-execution loops caused by jitter or clock drift.
- */
-const MIN_SCHEDULE_INTERVAL_MS = 5_000; // 5 seconds
-
-// ─── CronScheduler ───────────────────────────────────────────────────
-
-interface RegisteredJob {
-    id: string;
-    definition: CronJobDefinition;
-    enabled: boolean;
-    state: CronJobRunState;
-    lastRunAt?: Date;
-    nextRunAt?: Date;
-    lastDurationMs?: number;
-    lastError?: string;
-    totalRuns: number;
-    totalFailures: number;
-    timerId?: ReturnType<typeof setTimeout>;
-    logs: CronJobLogEntry[];
-    /** True while a handler is actively executing (prevents concurrent runs). */
-    executing: boolean;
-}
-
-export class CronScheduler {
-    private jobs = new Map<string, RegisteredJob>();
-    private started = false;
-    private store?: CronStore;
-    private client?: RebaseClient;
-
-    /**
-     * Set the RebaseClient instance to make it available to cron job handlers.
-     */
-    setClient(client: RebaseClient): void {
-        this.client = client;
-    }
-
-    /**
-     * Attach a persistence store for cron logs.
-     * When set, execution logs are written to the database after each run,
-     * and counters are seeded from the database on start.
-     */
-    setStore(store: CronStore): void {
-        this.store = store;
-    }
-
-    /**
-     * Register a batch of loaded cron jobs.
-     *
-     * If the scheduler is already started, newly registered jobs are
-     * automatically scheduled (so late-registered jobs don't sit idle).
-     *
-     * Validates the cron schedule on registration — invalid schedules
-     * are rejected with a warning and the job is NOT registered.
-     */
-    registerJobs(loadedJobs: LoadedCronJob[]): void {
-        for (const loaded of loadedJobs) {
-            // Validate schedule up-front — reject invalid schedules
-            const validation = validateCronExpression(loaded.definition.schedule);
-            if (!validation.valid) {
-                logger.error(`[cron] Rejecting job "${loaded.id}": invalid schedule "${loaded.definition.schedule}" — ${validation.reason}`);
-                continue;
-            }
-
-            const existing = this.jobs.get(loaded.id);
-            if (existing) {
-                logger.warn(`[cron] Duplicate cron job id: "${loaded.id}". Overwriting.`);
-                this.stopJob(loaded.id);
-            }
-
-            const enabled = loaded.definition.enabled !== false;
-
-            this.jobs.set(loaded.id, {
-                id: loaded.id,
-                definition: loaded.definition,
-                enabled,
-                state: enabled ? "idle" : "disabled",
-                totalRuns: 0,
-                totalFailures: 0,
-                logs: [],
-                executing: false
-            });
-
-            // If the scheduler is already running, auto-schedule new jobs
-            if (this.started && enabled) {
-                this.scheduleNext(loaded.id);
-            }
-        }
-    }
-
-    /**
-     * Start the scheduler — begins ticking all enabled jobs.
-     */
-    start(): void {
-        if (this.started) return;
-        this.started = true;
-
-        // Seed counters from DB (non-blocking — scheduler starts immediately)
-        if (this.store) {
-            this.store.fetchJobStats().then((stats) => {
-                for (const [jobId, data] of stats) {
-                    const job = this.jobs.get(jobId);
-                    if (job) {
-                        job.totalRuns = data.totalRuns;
-                        job.totalFailures = data.totalFailures;
-                        if (data.lastRunAt) {
-                            job.lastRunAt = new Date(data.lastRunAt);
-                        }
-                    }
-                }
-            }).catch((err) => {
-                logger.warn("[cron] Failed to seed job stats from database", { error: err });
-            });
-        }
-
-        for (const [id, job] of this.jobs) {
-            if (job.enabled) {
-                this.scheduleNext(id);
-            }
-        }
-        logger.info(`⏰ Cron scheduler started with ${this.jobs.size} job(s)`);
-    }
-
-    /**
-     * Stop the scheduler and clear all timers.
-     *
-     * Currently-executing handlers run to completion (they are async),
-     * but no further scheduling occurs after stop.
-     */
-    stop(): void {
-        this.started = false;
-        for (const [id] of this.jobs) {
-            this.stopJob(id);
-        }
-    }
-
-    /**
-     * List all registered jobs with their current status.
-     */
-    listJobs(): CronJobStatus[] {
-        return [...this.jobs.values()].map((job) => this.toStatus(job));
-    }
-
-    /**
-     * Get a single job status by ID.
-     */
-    getJob(id: string): CronJobStatus | undefined {
-        const job = this.jobs.get(id);
-        return job ? this.toStatus(job) : undefined;
-    }
-
-    /**
-     * Get log entries for a job.
-     */
-    getJobLogs(id: string, limit?: number): CronJobLogEntry[] {
-        const job = this.jobs.get(id);
-        if (!job) return [];
-        const logs = [...job.logs].reverse(); // newest first
-        return limit ? logs.slice(0, limit) : logs;
-    }
-
-    /**
-     * Get log entries for a job from the database (if store is available).
-     * Falls back to in-memory logs if no store is configured.
-     */
-    async getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]> {
-        if (this.store) {
-            const dbLogs = await this.store.fetchLogs(id, limit);
-            if (dbLogs.length > 0) return dbLogs;
-        }
-        // Fallback to in-memory
-        return this.getJobLogs(id, limit);
-    }
-
-    /**
-     * Enable or disable a job at runtime.
-     */
-    setJobEnabled(id: string, enabled: boolean): CronJobStatus | undefined {
-        const job = this.jobs.get(id);
-        if (!job) return undefined;
-
-        job.enabled = enabled;
-
-        if (enabled && this.started) {
-            job.state = "idle";
-            this.scheduleNext(id);
-        } else if (!enabled) {
-            this.stopJob(id);
-            job.state = "disabled";
-        }
-
-        return this.toStatus(job);
-    }
-
-    /**
-     * Manually trigger a job execution immediately.
-     *
-     * Returns `undefined` if the job doesn't exist.
-     * If the job is currently executing, returns the log entry with
-     * a `skipped: true` result rather than running concurrently.
-     */
-    async triggerJob(id: string): Promise<CronJobLogEntry | undefined> {
-        const job = this.jobs.get(id);
-        if (!job) return undefined;
-
-        // Concurrency guard — don't run two instances simultaneously
-        if (job.executing) {
-            logger.warn(`[cron] Skipping manual trigger of "${id}" — already executing`);
-            const logEntry: CronJobLogEntry = {
-                jobId: id,
-                startedAt: new Date().toISOString(),
-                finishedAt: new Date().toISOString(),
-                durationMs: 0,
-                success: true,
-                result: { skipped: true,
-reason: "already_executing" },
-                logs: ["Skipped: job is already running"],
-                manual: true
-            };
-            job.logs.push(logEntry);
-            if (job.logs.length > MAX_LOGS_PER_JOB) job.logs.shift();
-            return logEntry;
-        }
-
-        return this.executeJob(job, true);
-    }
-
-    // ─── Internal ────────────────────────────────────────────────────
-
-    /**
-     * Schedule the next execution for a job.
-     *
-     * Safety guarantees:
-     * 1. Clears any existing timer first (prevents leaked/duplicate timers)
-     * 2. Enforces a minimum delay to prevent tight loops from jitter
-     * 3. Unref's the timer so it doesn't prevent process exit
-     * 4. Re-checks enabled & started state before executing
-     * 5. Concurrency guard prevents overlapping handler executions
-     */
-    private scheduleNext(id: string): void {
-        const job = this.jobs.get(id);
-        if (!job || !job.enabled || !this.started) return;
-
-        // Clear any previously scheduled timer to prevent double-firing
-        this.stopJob(id);
-
-        try {
-            const now = new Date();
-            const nextRun = parseCronExpression(job.definition.schedule, now);
-            job.nextRunAt = nextRun;
-
-            const rawDelay = nextRun.getTime() - now.getTime();
-            // Enforce a minimum delay to prevent tight re-execution loops
-            // from event loop jitter or near-zero setTimeout drift
-            const delay = Math.max(rawDelay, MIN_SCHEDULE_INTERVAL_MS);
-
-            const timer = setTimeout(async () => {
-                // Re-check state: scheduler may have been stopped or job disabled
-                // between when we scheduled and when we fire
-                if (!job.enabled || !this.started) return;
-
-                // Concurrency guard: if somehow we're already executing, skip
-                if (job.executing) {
-                    logger.warn(`[cron] Skipping scheduled run of "${id}" — still executing from previous run`);
-                    // Re-schedule to try again later
-                    this.scheduleNext(id);
-                    return;
-                }
-
-                await this.executeJob(job, false);
-
-                // Schedule the next tick (only if still started + enabled)
-                if (this.started && job.enabled) {
-                    this.scheduleNext(id);
-                }
-            }, delay);
-
-            // Unref the timer so it doesn't prevent Node.js from exiting
-            // during graceful shutdown
-            if (timer && typeof timer === "object" && "unref" in timer) {
-                timer.unref();
-            }
-
-            job.timerId = timer;
-        } catch (err: unknown) {
-            logger.error(`[cron] Failed to schedule "${id}"`, { error: err });
-            job.state = "error";
-            job.lastError = err instanceof Error ? err.message : String(err);
-        }
-    }
-
-    /**
-     * Stop a single job's timer and clear its next run state.
-     */
-    private stopJob(id: string): void {
-        const job = this.jobs.get(id);
-        if (job?.timerId) {
-            clearTimeout(job.timerId);
-            job.timerId = undefined;
-            job.nextRunAt = undefined;
-        }
-    }
-
-    /**
-     * Execute a job's handler with full isolation and safety.
-     *
-     * - Sets a concurrency flag to prevent overlapping runs
-     * - Wraps handler in a timeout race
-     * - Captures all logs, errors, and results
-     * - Persists to store (non-blocking) if available
-     * - Always restores state even on catastrophic errors
-     */
-    private async executeJob(
-        job: RegisteredJob,
-        manual: boolean
-    ): Promise<CronJobLogEntry> {
-        const startedAt = new Date();
-        const capturedLogs: string[] = [];
-
-        // Set executing flag — prevents concurrent runs
-        job.executing = true;
-
-        const ctx: CronJobContext = {
-            jobId: job.id,
-            scheduledAt: startedAt,
-            log: (...args: unknown[]) => {
-                const line = args.map((a) =>
-                    typeof a === "string" ? a : JSON.stringify(a)
-                ).join(" ");
-                capturedLogs.push(line);
-            },
-            client: this.client!
-        };
-
-        job.state = "running";
-        job.lastRunAt = startedAt;
-        job.totalRuns++;
-
-        let success = true;
-        let error: string | undefined;
-        let result: unknown;
-
-        try {
-            // Race with timeout
-            const timeout = (job.definition.timeoutSeconds ?? 300) * 1000;
-            const handlerPromise = Promise.resolve(job.definition.handler(ctx));
-            let timeoutHandle: ReturnType<typeof setTimeout>;
-            const timeoutPromise = new Promise<never>((_, reject) => {
-                timeoutHandle = setTimeout(
-                    () => reject(new Error(`Cron job "${job.id}" timed out after ${timeout}ms`)),
-                    timeout
-                );
-            });
-
-            try {
-                result = await Promise.race([handlerPromise, timeoutPromise]);
-            } finally {
-                clearTimeout(timeoutHandle!);
-            }
-        } catch (err: unknown) {
-            success = false;
-            error = err instanceof Error ? err.message : String(err);
-            job.totalFailures++;
-        } finally {
-            // Always clear executing flag — even on catastrophic errors
-            job.executing = false;
-        }
-
-        const finishedAt = new Date();
-        const durationMs = finishedAt.getTime() - startedAt.getTime();
-
-        job.state = success ? (job.enabled ? "idle" : "disabled") : "error";
-        job.lastDurationMs = durationMs;
-        job.lastError = error;
-
-        const logEntry: CronJobLogEntry = {
-            jobId: job.id,
-            startedAt: startedAt.toISOString(),
-            finishedAt: finishedAt.toISOString(),
-            durationMs,
-            success,
-            error,
-            result: result !== undefined ? result : undefined,
-            logs: capturedLogs,
-            manual
-        };
-
-        // Push to ring buffer
-        job.logs.push(logEntry);
-        if (job.logs.length > MAX_LOGS_PER_JOB) {
-            job.logs.shift();
-        }
-
-        // Persist to database (non-blocking)
-        if (this.store) {
-            this.store.insertLog(logEntry).catch((persistErr) => {
-                logger.error(`[cron] Failed to persist log for "${job.id}"`, { error: persistErr });
-            });
-        }
-
-        if (success) {
-            logger.info(`✅ [cron] "${job.id}" completed in ${durationMs}ms`);
-        } else {
-            logger.error(`❌ [cron] "${job.id}" failed in ${durationMs}ms: ${error}`);
-        }
-
-        return logEntry;
-    }
-
-    private toStatus(job: RegisteredJob): CronJobStatus {
-        return {
-            id: job.id,
-            name: job.definition.name,
-            description: job.definition.description,
-            schedule: job.definition.schedule,
-            enabled: job.enabled,
-            state: job.state,
-            lastRunAt: job.lastRunAt?.toISOString(),
-            nextRunAt: job.nextRunAt?.toISOString(),
-            lastDurationMs: job.lastDurationMs,
-            lastError: job.lastError,
-            totalRuns: job.totalRuns,
-            totalFailures: job.totalFailures
-        };
-    }
-}