@chidchanun/bcp 0.2.8 → 0.2.10

package/packages/server/src/job-scheduler.ts

@@ -0,0 +1,1144 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+import type {
+    BackgroundJobQueue,
+} from "./jobs.js";
+
+export type JobSchedule =
+    | {
+        kind: "interval";
+        everyMs: number;
+    }
+    | {
+        kind: "cron";
+        expression: string;
+    };
+
+export interface JobScheduleRecord<
+    TPayload = unknown
+> {
+    id: string;
+    jobName: string;
+    payload: TPayload;
+    schedule: JobSchedule;
+    createdAt: number;
+    updatedAt: number;
+    nextRunAt: number;
+    lastRunAt?: number;
+    maxAttempts?: number;
+    leaseOwner?: string;
+    leaseUntil?: number;
+}
+
+export interface ScheduleJobOptions {
+    id?: string;
+    everyMs?: number;
+    cron?: string;
+    startAt?: number | Date;
+    maxAttempts?: number;
+}
+
+export interface JobScheduleStore {
+    upsert<TPayload = unknown>(
+        schedule: JobScheduleRecord<TPayload>
+    ): Promise<void>;
+
+    get<TPayload = unknown>(
+        id: string
+    ): Promise<JobScheduleRecord<TPayload> | null>;
+
+    list(): Promise<JobScheduleRecord[]>;
+
+    remove(id: string): Promise<boolean>;
+
+    acquireDue(
+        now: number,
+        options: {
+            ownerId: string;
+            leaseMs: number;
+            limit: number;
+        }
+    ): Promise<JobScheduleRecord[]>;
+
+    complete(
+        id: string,
+        options: {
+            ownerId: string;
+            lastRunAt: number;
+            nextRunAt: number;
+            updatedAt: number;
+        }
+    ): Promise<void>;
+
+    release(
+        id: string,
+        ownerId: string
+    ): Promise<void>;
+
+    close?(): Promise<void>;
+}
+
+export interface MemoryJobScheduleStore
+extends JobScheduleStore {
+    clear(): void;
+}
+
+export interface JobSchedulerOptions {
+    queue: BackgroundJobQueue;
+    store?: JobScheduleStore;
+    now?: () => number;
+    idFactory?: () => string;
+    ownerId?: string;
+}
+
+export interface RunDueSchedulesOptions {
+    limit?: number;
+    leaseMs?: number;
+}
+
+export interface StartJobSchedulerOptions
+extends RunDueSchedulesOptions {
+    pollIntervalMs?: number;
+    onError?: (
+        error: unknown
+    ) => void | Promise<void>;
+}
+
+export interface JobSchedulerRunner {
+    readonly running: boolean;
+    stop(): Promise<void>;
+}
+
+export interface JobScheduler {
+    readonly queue: BackgroundJobQueue;
+    readonly store: JobScheduleStore;
+    readonly ownerId: string;
+
+    schedule<TPayload = unknown>(
+        jobName: string,
+        payload: TPayload,
+        options: ScheduleJobOptions
+    ): Promise<JobScheduleRecord<TPayload>>;
+
+    get<TPayload = unknown>(
+        id: string
+    ): Promise<JobScheduleRecord<TPayload> | null>;
+
+    list(): Promise<JobScheduleRecord[]>;
+
+    remove(id: string): Promise<boolean>;
+
+    runDue(
+        options?: RunDueSchedulesOptions
+    ): Promise<number>;
+
+    start(
+        options?: StartJobSchedulerOptions
+    ): JobSchedulerRunner;
+
+    close(): Promise<void>;
+}
+
+export function createMemoryJobScheduleStore():
+MemoryJobScheduleStore {
+    const schedules =
+        new Map<
+            string,
+            JobScheduleRecord
+        >();
+
+    return {
+        async upsert(schedule) {
+            schedules.set(
+                schedule.id,
+                cloneSchedule(
+                    schedule
+                )
+            );
+        },
+
+        async get(id) {
+            const schedule =
+                schedules.get(id);
+
+            return schedule
+                ? cloneSchedule(
+                    schedule
+                ) as JobScheduleRecord<any>
+                : null;
+        },
+
+        async list() {
+            return Array.from(
+                schedules.values()
+            )
+                .map(
+                    cloneSchedule
+                )
+                .sort(
+                    (left, right) =>
+                        left.nextRunAt -
+                            right.nextRunAt ||
+                        left.id.localeCompare(
+                            right.id
+                        )
+                );
+        },
+
+        async remove(id) {
+            return schedules.delete(id);
+        },
+
+        async acquireDue(
+            now,
+            options
+        ) {
+            const due =
+                Array.from(
+                    schedules.values()
+                )
+                    .filter(
+                        schedule =>
+                            schedule.nextRunAt <= now &&
+                            (
+                                schedule.leaseUntil === undefined ||
+                                schedule.leaseUntil <= now
+                            )
+                    )
+                    .sort(
+                        (left, right) =>
+                            left.nextRunAt -
+                                right.nextRunAt ||
+                            left.id.localeCompare(
+                                right.id
+                            )
+                    )
+                    .slice(
+                        0,
+                        options.limit
+                    );
+
+            for (const schedule of due) {
+                schedule.leaseOwner =
+                    options.ownerId;
+                schedule.leaseUntil =
+                    now + options.leaseMs;
+            }
+
+            return due.map(
+                cloneSchedule
+            );
+        },
+
+        async complete(
+            id,
+            options
+        ) {
+            const schedule =
+                schedules.get(id);
+
+            if (
+                !schedule ||
+                schedule.leaseOwner !==
+                    options.ownerId
+            ) {
+                return;
+            }
+
+            schedule.lastRunAt =
+                options.lastRunAt;
+            schedule.nextRunAt =
+                options.nextRunAt;
+            schedule.updatedAt =
+                options.updatedAt;
+            schedule.leaseOwner =
+                undefined;
+            schedule.leaseUntil =
+                undefined;
+        },
+
+        async release(
+            id,
+            ownerId
+        ) {
+            const schedule =
+                schedules.get(id);
+
+            if (
+                !schedule ||
+                schedule.leaseOwner !==
+                    ownerId
+            ) {
+                return;
+            }
+
+            schedule.leaseOwner =
+                undefined;
+            schedule.leaseUntil =
+                undefined;
+        },
+
+        clear() {
+            schedules.clear();
+        },
+    };
+}
+
+export function createJobScheduler(
+    options: JobSchedulerOptions
+): JobScheduler {
+    if (
+        !options ||
+        !options.queue
+    ) {
+        throw new TypeError(
+            "BCP Jobs: createJobScheduler requires a queue."
+        );
+    }
+
+    const queue =
+        options.queue;
+    const store =
+        options.store ??
+        createMemoryJobScheduleStore();
+    const now =
+        options.now ??
+        Date.now;
+    const idFactory =
+        options.idFactory ??
+        randomUUID;
+    const ownerId =
+        normalizeIdentifier(
+            options.ownerId ??
+            `scheduler-${randomUUID()}`,
+            "scheduler owner id"
+        );
+    const runners =
+        new Set<InternalSchedulerRunner>();
+
+    const scheduler:
+        JobScheduler = {
+        queue,
+        store,
+        ownerId,
+
+        async schedule(
+            jobName,
+            payload,
+            scheduleOptions
+        ) {
+            const currentTime =
+                normalizeTimestamp(
+                    now(),
+                    "current time"
+                );
+            const schedule =
+                normalizeSchedule(
+                    scheduleOptions
+                );
+            const id =
+                normalizeIdentifier(
+                    scheduleOptions.id ??
+                    idFactory(),
+                    "schedule id"
+                );
+            const startAt =
+                scheduleOptions.startAt ===
+                undefined
+                    ? undefined
+                    : normalizeTimestamp(
+                        scheduleOptions.startAt instanceof Date
+                            ? scheduleOptions.startAt.getTime()
+                            : scheduleOptions.startAt,
+                        "startAt"
+                    );
+            const maxAttempts =
+                scheduleOptions.maxAttempts ===
+                undefined
+                    ? undefined
+                    : normalizePositiveInteger(
+                        scheduleOptions.maxAttempts,
+                        "maxAttempts"
+                    );
+            const nextRunAt =
+                startAt ??
+                nextScheduleTime(
+                    schedule,
+                    currentTime
+                );
+            const record:
+                JobScheduleRecord<
+                    typeof payload
+                > = {
+                id,
+                jobName:
+                    normalizeIdentifier(
+                        jobName,
+                        "job name"
+                    ),
+                payload,
+                schedule,
+                createdAt:
+                    currentTime,
+                updatedAt:
+                    currentTime,
+                nextRunAt,
+                maxAttempts,
+            };
+
+            await store.upsert(
+                record
+            );
+
+            return cloneSchedule(
+                record
+            );
+        },
+
+        get(id) {
+            return store.get(
+                normalizeIdentifier(
+                    id,
+                    "schedule id"
+                )
+            );
+        },
+
+        list() {
+            return store.list();
+        },
+
+        remove(id) {
+            return store.remove(
+                normalizeIdentifier(
+                    id,
+                    "schedule id"
+                )
+            );
+        },
+
+        async runDue(
+            runOptions = {}
+        ) {
+            const currentTime =
+                normalizeTimestamp(
+                    now(),
+                    "current time"
+                );
+            const limit =
+                normalizePositiveInteger(
+                    runOptions.limit ?? 100,
+                    "limit"
+                );
+            const leaseMs =
+                normalizePositiveInteger(
+                    runOptions.leaseMs ??
+                    30_000,
+                    "leaseMs"
+                );
+            const schedules =
+                await store.acquireDue(
+                    currentTime,
+                    {
+                        ownerId,
+                        leaseMs,
+                        limit,
+                    }
+                );
+            let enqueued = 0;
+
+            for (
+                const scheduleRecord
+                of schedules
+            ) {
+                const scheduledFor =
+                    scheduleRecord.nextRunAt;
+                const runId =
+                    createScheduledRunId(
+                        scheduleRecord.id,
+                        scheduledFor
+                    );
+
+                try {
+                    await queue.enqueue(
+                        scheduleRecord.jobName,
+                        scheduleRecord.payload,
+                        {
+                            id: runId,
+                            maxAttempts:
+                                scheduleRecord.maxAttempts,
+                        }
+                    );
+                    enqueued += 1;
+                } catch (error) {
+                    if (
+                        !isDuplicateJobIdError(
+                            error
+                        )
+                    ) {
+                        await store.release(
+                            scheduleRecord.id,
+                            ownerId
+                        );
+                        throw error;
+                    }
+                }
+
+                const nextRunAt =
+                    nextScheduleTime(
+                        scheduleRecord.schedule,
+                        scheduledFor
+                    );
+
+                await store.complete(
+                    scheduleRecord.id,
+                    {
+                        ownerId,
+                        lastRunAt:
+                            scheduledFor,
+                        nextRunAt,
+                        updatedAt:
+                            currentTime,
+                    }
+                );
+            }
+
+            return enqueued;
+        },
+
+        start(
+            startOptions = {}
+        ) {
+            const runner =
+                createSchedulerRunner(
+                    scheduler,
+                    startOptions,
+                    () =>
+                        runners.delete(
+                            runner
+                        )
+                );
+
+            runners.add(runner);
+            return runner;
+        },
+
+        async close() {
+            await Promise.all(
+                Array.from(
+                    runners,
+                    runner =>
+                        runner.stop()
+                )
+            );
+
+            if (store.close) {
+                await store.close();
+            }
+        },
+    };
+
+    return scheduler;
+}
+
+export function nextScheduleTime(
+    schedule: JobSchedule,
+    after: number
+): number {
+    const timestamp =
+        normalizeTimestamp(
+            after,
+            "schedule reference time"
+        );
+
+    if (schedule.kind === "interval") {
+        return timestamp +
+            normalizePositiveInteger(
+                schedule.everyMs,
+                "everyMs"
+            );
+    }
+
+    return nextCronTime(
+        schedule.expression,
+        timestamp
+    );
+}
+
+export function nextCronTime(
+    expression: string,
+    after: number
+): number {
+    const cron =
+        parseCronExpression(
+            expression
+        );
+    const afterTimestamp =
+        normalizeTimestamp(
+            after,
+            "cron reference time"
+        );
+    const minute =
+        60_000;
+    let candidate =
+        Math.floor(
+            afterTimestamp /
+            minute
+        ) * minute + minute;
+    const maxIterations =
+        366 * 24 * 60 * 8;
+
+    for (
+        let iteration = 0;
+        iteration < maxIterations;
+        iteration += 1
+    ) {
+        const date =
+            new Date(candidate);
+
+        if (
+            cron.month.has(
+                date.getUTCMonth() + 1
+            ) &&
+            cron.hour.has(
+                date.getUTCHours()
+            ) &&
+            cron.minute.has(
+                date.getUTCMinutes()
+            ) &&
+            matchesCronDay(
+                cron,
+                date
+            )
+        ) {
+            return candidate;
+        }
+
+        candidate += minute;
+    }
+
+    throw new RangeError(
+        `BCP Jobs: cron expression "${expression}" did not produce a run time within 8 years.`
+    );
+}
+
+interface InternalSchedulerRunner
+extends JobSchedulerRunner {}
+
+function createSchedulerRunner(
+    scheduler: JobScheduler,
+    options: StartJobSchedulerOptions,
+    onStop: () => void
+): InternalSchedulerRunner {
+    const pollIntervalMs =
+        normalizePositiveInteger(
+            options.pollIntervalMs ??
+            1_000,
+            "pollIntervalMs"
+        );
+    const runOptions:
+        RunDueSchedulesOptions = {
+        limit:
+            options.limit,
+        leaseMs:
+            options.leaseMs,
+    };
+    const controller =
+        new AbortController();
+    let running = true;
+    let stopPromise:
+        Promise<void> | null =
+        null;
+
+    const loop =
+        runSchedulerLoop(
+            scheduler,
+            controller.signal,
+            pollIntervalMs,
+            runOptions,
+            options.onError
+        );
+
+    return {
+        get running() {
+            return running;
+        },
+
+        stop() {
+            if (stopPromise) {
+                return stopPromise;
+            }
+
+            running = false;
+            controller.abort();
+            stopPromise =
+                loop.finally(
+                    onStop
+                );
+
+            return stopPromise;
+        },
+    };
+}
+
+async function runSchedulerLoop(
+    scheduler: JobScheduler,
+    signal: AbortSignal,
+    pollIntervalMs: number,
+    runOptions: RunDueSchedulesOptions,
+    onError:
+        StartJobSchedulerOptions["onError"]
+): Promise<void> {
+    while (!signal.aborted) {
+        try {
+            await scheduler.runDue(
+                runOptions
+            );
+        } catch (error) {
+            if (onError) {
+                await onError(error);
+            }
+        }
+
+        if (!signal.aborted) {
+            await sleep(
+                pollIntervalMs,
+                signal
+            );
+        }
+    }
+}
+
+function normalizeSchedule(
+    options: ScheduleJobOptions
+): JobSchedule {
+    if (!options) {
+        throw new TypeError(
+            "BCP Jobs: schedule options are required."
+        );
+    }
+
+    const hasInterval =
+        options.everyMs !== undefined;
+    const hasCron =
+        options.cron !== undefined;
+
+    if (
+        hasInterval === hasCron
+    ) {
+        throw new TypeError(
+            "BCP Jobs: schedule requires exactly one of everyMs or cron."
+        );
+    }
+
+    if (hasInterval) {
+        return {
+            kind: "interval",
+            everyMs:
+                normalizePositiveInteger(
+                    options.everyMs as number,
+                    "everyMs"
+                ),
+        };
+    }
+
+    const expression =
+        String(options.cron)
+            .trim();
+
+    parseCronExpression(
+        expression
+    );
+
+    return {
+        kind: "cron",
+        expression,
+    };
+}
+
+interface ParsedCronExpression {
+    minute: Set<number>;
+    hour: Set<number>;
+    dayOfMonth: Set<number>;
+    month: Set<number>;
+    dayOfWeek: Set<number>;
+    dayOfMonthWildcard: boolean;
+    dayOfWeekWildcard: boolean;
+}
+
+function parseCronExpression(
+    expression: string
+): ParsedCronExpression {
+    const parts =
+        String(expression)
+            .trim()
+            .split(/\s+/);
+
+    if (parts.length !== 5) {
+        throw new TypeError(
+            "BCP Jobs: cron must contain 5 fields: minute hour day-of-month month day-of-week."
+        );
+    }
+
+    return {
+        minute:
+            parseCronField(
+                parts[0],
+                0,
+                59,
+                "minute"
+            ).values,
+        hour:
+            parseCronField(
+                parts[1],
+                0,
+                23,
+                "hour"
+            ).values,
+        dayOfMonth:
+            parseCronField(
+                parts[2],
+                1,
+                31,
+                "day-of-month"
+            ).values,
+        month:
+            parseCronField(
+                parts[3],
+                1,
+                12,
+                "month"
+            ).values,
+        dayOfWeek:
+            parseCronField(
+                parts[4],
+                0,
+                7,
+                "day-of-week",
+                true
+            ).values,
+        dayOfMonthWildcard:
+            parts[2] === "*",
+        dayOfWeekWildcard:
+            parts[4] === "*",
+    };
+}
+
+function parseCronField(
+    source: string,
+    minimum: number,
+    maximum: number,
+    field: string,
+    normalizeSunday = false
+): {
+    values: Set<number>;
+} {
+    const values =
+        new Set<number>();
+
+    for (
+        const segment
+        of source.split(",")
+    ) {
+        const [base, stepSource] =
+            segment.split("/");
+
+        if (
+            segment.split("/").length > 2
+        ) {
+            throwCronField(
+                field,
+                source
+            );
+        }
+
+        const step =
+            stepSource === undefined
+                ? 1
+                : parseCronInteger(
+                    stepSource,
+                    1,
+                    maximum - minimum + 1,
+                    field,
+                    source
+                );
+        let rangeStart:
+            number;
+        let rangeEnd:
+            number;
+
+        if (base === "*") {
+            rangeStart = minimum;
+            rangeEnd = maximum;
+        } else if (
+            base.includes("-")
+        ) {
+            const bounds =
+                base.split("-");
+
+            if (bounds.length !== 2) {
+                throwCronField(
+                    field,
+                    source
+                );
+            }
+
+            rangeStart =
+                parseCronInteger(
+                    bounds[0],
+                    minimum,
+                    maximum,
+                    field,
+                    source
+                );
+            rangeEnd =
+                parseCronInteger(
+                    bounds[1],
+                    minimum,
+                    maximum,
+                    field,
+                    source
+                );
+
+            if (
+                rangeEnd < rangeStart
+            ) {
+                throwCronField(
+                    field,
+                    source
+                );
+            }
+        } else {
+            rangeStart =
+                parseCronInteger(
+                    base,
+                    minimum,
+                    maximum,
+                    field,
+                    source
+                );
+            rangeEnd =
+                rangeStart;
+        }
+
+        for (
+            let value = rangeStart;
+            value <= rangeEnd;
+            value += step
+        ) {
+            values.add(
+                normalizeSunday &&
+                value === 7
+                    ? 0
+                    : value
+            );
+        }
+    }
+
+    if (values.size === 0) {
+        throwCronField(
+            field,
+            source
+        );
+    }
+
+    return {
+        values,
+    };
+}
+
+function parseCronInteger(
+    source: string,
+    minimum: number,
+    maximum: number,
+    field: string,
+    fullSource: string
+): number {
+    if (!/^\d+$/.test(source)) {
+        throwCronField(
+            field,
+            fullSource
+        );
+    }
+
+    const value =
+        Number(source);
+
+    if (
+        !Number.isInteger(value) ||
+        value < minimum ||
+        value > maximum
+    ) {
+        throwCronField(
+            field,
+            fullSource
+        );
+    }
+
+    return value;
+}
+
+function throwCronField(
+    field: string,
+    source: string
+): never {
+    throw new TypeError(
+        `BCP Jobs: invalid cron ${field} field "${source}".`
+    );
+}
+
+function matchesCronDay(
+    cron: ParsedCronExpression,
+    date: Date
+): boolean {
+    const dayOfMonthMatches =
+        cron.dayOfMonth.has(
+            date.getUTCDate()
+        );
+    const dayOfWeekMatches =
+        cron.dayOfWeek.has(
+            date.getUTCDay()
+        );
+
+    if (
+        cron.dayOfMonthWildcard &&
+        cron.dayOfWeekWildcard
+    ) {
+        return true;
+    }
+
+    if (cron.dayOfMonthWildcard) {
+        return dayOfWeekMatches;
+    }
+
+    if (cron.dayOfWeekWildcard) {
+        return dayOfMonthMatches;
+    }
+
+    return dayOfMonthMatches ||
+        dayOfWeekMatches;
+}
+
+function createScheduledRunId(
+    scheduleId: string,
+    scheduledFor: number
+): string {
+    return `schedule:${scheduleId}:${scheduledFor}`;
+}
+
+function isDuplicateJobIdError(
+    error: unknown
+): boolean {
+    return error instanceof Error &&
+        /job id .* already exists/i.test(
+            error.message
+        );
+}
+
+function normalizeIdentifier(
+    value: string,
+    field: string
+): string {
+    const normalized =
+        String(value)
+            .trim();
+
+    if (!normalized) {
+        throw new TypeError(
+            `BCP Jobs: ${field} must be a non-empty string.`
+        );
+    }
+
+    if (normalized.length > 200) {
+        throw new TypeError(
+            `BCP Jobs: ${field} must not exceed 200 characters.`
+        );
+    }
+
+    return normalized;
+}
+
+function normalizeTimestamp(
+    value: number,
+    field: string
+): number {
+    if (
+        !Number.isFinite(value) ||
+        value < 0
+    ) {
+        throw new TypeError(
+            `BCP Jobs: ${field} must be a non-negative finite timestamp.`
+        );
+    }
+
+    return Math.floor(value);
+}
+
+function normalizePositiveInteger(
+    value: number,
+    field: string
+): number {
+    if (
+        !Number.isInteger(value) ||
+        value <= 0
+    ) {
+        throw new TypeError(
+            `BCP Jobs: ${field} must be a positive integer.`
+        );
+    }
+
+    return value;
+}
+
+function sleep(
+    durationMs: number,
+    signal: AbortSignal
+): Promise<void> {
+    if (signal.aborted) {
+        return Promise.resolve();
+    }
+
+    return new Promise(
+        resolve => {
+            const timeout =
+                setTimeout(
+                    finish,
+                    durationMs
+                );
+            const onAbort =
+                () => finish();
+
+            signal.addEventListener(
+                "abort",
+                onAbort,
+                {
+                    once: true,
+                }
+            );
+
+            function finish() {
+                clearTimeout(timeout);
+                signal.removeEventListener(
+                    "abort",
+                    onAbort
+                );
+                resolve();
+            }
+        }
+    );
+}
+
+function cloneSchedule<
+    TPayload
+>(
+    schedule: JobScheduleRecord<TPayload>
+): JobScheduleRecord<TPayload> {
+    return {
+        ...schedule,
+        schedule: {
+            ...schedule.schedule,
+        },
+    };
+}