@chidchanun/bcp 0.2.6 → 0.2.8

package/packages/server/src/jobs.ts

@@ -0,0 +1,822 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+export type JobState =
+    | "queued"
+    | "running"
+    | "succeeded"
+    | "failed"
+    | "cancelled";
+
+export interface JobRecord<
+    TPayload = unknown
+> {
+    id: string;
+    name: string;
+    payload: TPayload;
+    state: JobState;
+    attempts: number;
+    maxAttempts: number;
+    createdAt: number;
+    availableAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    error?: string;
+}
+
+export interface EnqueueJobOptions {
+    id?: string;
+    delayMs?: number;
+    maxAttempts?: number;
+}
+
+export interface JobQueueAdapter {
+    enqueue<TPayload = unknown>(
+        job: JobRecord<TPayload>
+    ): Promise<void>;
+
+    reserve(
+        now: number
+    ): Promise<JobRecord | null>;
+
+    complete(
+        id: string,
+        completedAt: number
+    ): Promise<void>;
+
+    fail(
+        id: string,
+        options: {
+            error: string;
+            failedAt: number;
+            retryAt?: number;
+        }
+    ): Promise<void>;
+
+    cancel(
+        id: string,
+        cancelledAt: number
+    ): Promise<boolean>;
+
+    get<TPayload = unknown>(
+        id: string
+    ): Promise<JobRecord<TPayload> | null>;
+
+    list(): Promise<JobRecord[]>;
+
+    close?(): Promise<void>;
+}
+
+export interface MemoryJobQueueAdapter
+extends JobQueueAdapter {
+    clear(): void;
+}
+
+export interface JobHandlerContext<
+    TPayload = unknown
+> {
+    job: Readonly<JobRecord<TPayload>>;
+    payload: TPayload;
+    signal: AbortSignal;
+}
+
+export type JobHandler<
+    TPayload = unknown
+> = (
+    context: JobHandlerContext<TPayload>
+) => unknown | Promise<unknown>;
+
+export type JobRetryDelay =
+    | number
+    | ((attempt: number) => number);
+
+export interface JobQueueOptions {
+    adapter?: JobQueueAdapter;
+    defaultMaxAttempts?: number;
+    retryDelayMs?: JobRetryDelay;
+    now?: () => number;
+    idFactory?: () => string;
+}
+
+export interface StartJobWorkerOptions {
+    concurrency?: number;
+    pollIntervalMs?: number;
+}
+
+export interface JobWorker {
+    readonly running: boolean;
+    stop(): Promise<void>;
+}
+
+export interface BackgroundJobQueue {
+    readonly adapter: JobQueueAdapter;
+
+    register<TPayload = unknown>(
+        name: string,
+        handler: JobHandler<TPayload>
+    ): () => void;
+
+    enqueue<TPayload = unknown>(
+        name: string,
+        payload: TPayload,
+        options?: EnqueueJobOptions
+    ): Promise<JobRecord<TPayload>>;
+
+    get<TPayload = unknown>(
+        id: string
+    ): Promise<JobRecord<TPayload> | null>;
+
+    list(): Promise<JobRecord[]>;
+
+    cancel(id: string): Promise<boolean>;
+
+    processNext(
+        signal?: AbortSignal
+    ): Promise<boolean>;
+
+    startWorker(
+        options?: StartJobWorkerOptions
+    ): JobWorker;
+
+    close(): Promise<void>;
+}
+
+export function createMemoryJobQueueAdapter():
+MemoryJobQueueAdapter {
+    const jobs =
+        new Map<string, JobRecord>();
+
+    return {
+        async enqueue(job) {
+            if (jobs.has(job.id)) {
+                throw new Error(
+                    `BCP Jobs: job id "${job.id}" already exists.`
+                );
+            }
+
+            jobs.set(
+                job.id,
+                cloneJob(job)
+            );
+        },
+
+        async reserve(now) {
+            const candidate =
+                Array.from(
+                    jobs.values()
+                )
+                    .filter(
+                        job =>
+                            job.state === "queued" &&
+                            job.availableAt <= now
+                    )
+                    .sort(
+                        (left, right) =>
+                            left.availableAt - right.availableAt ||
+                            left.createdAt - right.createdAt ||
+                            left.id.localeCompare(right.id)
+                    )[0];
+
+            if (!candidate) {
+                return null;
+            }
+
+            candidate.state =
+                "running";
+            candidate.attempts += 1;
+            candidate.startedAt =
+                now;
+            candidate.error =
+                undefined;
+
+            return cloneJob(
+                candidate
+            );
+        },
+
+        async complete(
+            id,
+            completedAt
+        ) {
+            const job =
+                jobs.get(id);
+
+            if (
+                !job ||
+                job.state === "cancelled"
+            ) {
+                return;
+            }
+
+            job.state =
+                "succeeded";
+            job.completedAt =
+                completedAt;
+            job.error =
+                undefined;
+        },
+
+        async fail(
+            id,
+            options
+        ) {
+            const job =
+                jobs.get(id);
+
+            if (
+                !job ||
+                job.state === "cancelled"
+            ) {
+                return;
+            }
+
+            job.error =
+                options.error;
+
+            if (
+                options.retryAt !== undefined &&
+                job.attempts < job.maxAttempts
+            ) {
+                job.state =
+                    "queued";
+                job.availableAt =
+                    options.retryAt;
+                job.startedAt =
+                    undefined;
+                return;
+            }
+
+            job.state =
+                "failed";
+            job.completedAt =
+                options.failedAt;
+        },
+
+        async cancel(
+            id,
+            cancelledAt
+        ) {
+            const job =
+                jobs.get(id);
+
+            if (
+                !job ||
+                job.state === "succeeded" ||
+                job.state === "failed" ||
+                job.state === "cancelled"
+            ) {
+                return false;
+            }
+
+            job.state =
+                "cancelled";
+            job.completedAt =
+                cancelledAt;
+            return true;
+        },
+
+        async get(id) {
+            const job =
+                jobs.get(id);
+
+            return job
+                ? cloneJob(job) as JobRecord<any>
+                : null;
+        },
+
+        async list() {
+            return Array.from(
+                jobs.values()
+            )
+                .map(cloneJob)
+                .sort(
+                    (left, right) =>
+                        left.createdAt - right.createdAt ||
+                        left.id.localeCompare(right.id)
+                );
+        },
+
+        clear() {
+            jobs.clear();
+        },
+    };
+}
+
+export function createJobQueue(
+    options: JobQueueOptions = {}
+): BackgroundJobQueue {
+    const adapter =
+        options.adapter ??
+        createMemoryJobQueueAdapter();
+    const handlers =
+        new Map<string, JobHandler<any>>();
+    const workers =
+        new Set<InternalJobWorker>();
+    const now =
+        options.now ??
+        Date.now;
+    const idFactory =
+        options.idFactory ??
+        randomUUID;
+    const defaultMaxAttempts =
+        normalizePositiveInteger(
+            options.defaultMaxAttempts ?? 3,
+            "defaultMaxAttempts"
+        );
+    const retryDelay =
+        options.retryDelayMs ??
+        ((attempt: number) =>
+            Math.min(
+                30_000,
+                1_000 *
+                2 ** Math.max(
+                    0,
+                    attempt - 1
+                )
+            ));
+
+    const queue:
+        BackgroundJobQueue = {
+        adapter,
+
+        register(name, handler) {
+            const normalizedName =
+                normalizeJobName(name);
+
+            if (
+                typeof handler !==
+                "function"
+            ) {
+                throw new TypeError(
+                    "BCP Jobs: handler must be a function."
+                );
+            }
+
+            if (
+                handlers.has(
+                    normalizedName
+                )
+            ) {
+                throw new Error(
+                    `BCP Jobs: handler "${normalizedName}" is already registered.`
+                );
+            }
+
+            const registeredHandler =
+                handler as JobHandler<any>;
+
+            handlers.set(
+                normalizedName,
+                registeredHandler
+            );
+
+            return () => {
+                if (
+                    handlers.get(
+                        normalizedName
+                    ) === registeredHandler
+                ) {
+                    handlers.delete(
+                        normalizedName
+                    );
+                }
+            };
+        },
+
+        async enqueue(
+            name,
+            payload,
+            enqueueOptions = {}
+        ) {
+            const createdAt =
+                now();
+            const delayMs =
+                normalizeNonNegativeNumber(
+                    enqueueOptions.delayMs ?? 0,
+                    "delayMs"
+                );
+            const maxAttempts =
+                normalizePositiveInteger(
+                    enqueueOptions.maxAttempts ??
+                    defaultMaxAttempts,
+                    "maxAttempts"
+                );
+            const id =
+                normalizeJobId(
+                    enqueueOptions.id ??
+                    idFactory()
+                );
+            const job:
+                JobRecord<typeof payload> = {
+                id,
+                name:
+                    normalizeJobName(
+                        name
+                    ),
+                payload,
+                state: "queued",
+                attempts: 0,
+                maxAttempts,
+                createdAt,
+                availableAt:
+                    createdAt +
+                    delayMs,
+            };
+
+            await adapter.enqueue(
+                job
+            );
+
+            return cloneJob(job);
+        },
+
+        get(id) {
+            return adapter.get(
+                normalizeJobId(id)
+            );
+        },
+
+        list() {
+            return adapter.list();
+        },
+
+        cancel(id) {
+            return adapter.cancel(
+                normalizeJobId(id),
+                now()
+            );
+        },
+
+        async processNext(
+            signal =
+                new AbortController()
+                    .signal
+        ) {
+            if (signal.aborted) {
+                return false;
+            }
+
+            const job =
+                await adapter.reserve(
+                    now()
+                );
+
+            if (!job) {
+                return false;
+            }
+
+            const handler =
+                handlers.get(
+                    job.name
+                );
+
+            if (!handler) {
+                await adapter.fail(
+                    job.id,
+                    {
+                        error:
+                            `No handler registered for job "${job.name}".`,
+                        failedAt:
+                            now(),
+                    }
+                );
+                return true;
+            }
+
+            try {
+                await handler({
+                    job:
+                        cloneJob(job),
+                    payload:
+                        job.payload,
+                    signal,
+                });
+
+                await adapter.complete(
+                    job.id,
+                    now()
+                );
+            } catch (error) {
+                const failedAt =
+                    now();
+                const shouldRetry =
+                    job.attempts <
+                    job.maxAttempts;
+                const retryAt =
+                    shouldRetry
+                        ? failedAt +
+                            resolveRetryDelay(
+                                retryDelay,
+                                job.attempts
+                            )
+                        : undefined;
+
+                await adapter.fail(
+                    job.id,
+                    {
+                        error:
+                            formatJobError(
+                                error
+                            ),
+                        failedAt,
+                        retryAt,
+                    }
+                );
+            }
+
+            return true;
+        },
+
+        startWorker(
+            workerOptions = {}
+        ) {
+            const worker =
+                createWorker(
+                    queue,
+                    workerOptions,
+                    () =>
+                        workers.delete(
+                            worker
+                        )
+                );
+
+            workers.add(worker);
+            return worker;
+        },
+
+        async close() {
+            await Promise.all(
+                Array.from(
+                    workers,
+                    worker =>
+                        worker.stop()
+                )
+            );
+
+            if (adapter.close) {
+                await adapter.close();
+            }
+        },
+    };
+
+    return queue;
+}
+
+interface InternalJobWorker
+extends JobWorker {}
+
+function createWorker(
+    queue: BackgroundJobQueue,
+    options: StartJobWorkerOptions,
+    onStop: () => void
+): InternalJobWorker {
+    const concurrency =
+        normalizePositiveInteger(
+            options.concurrency ?? 1,
+            "concurrency"
+        );
+    const pollIntervalMs =
+        normalizeNonNegativeNumber(
+            options.pollIntervalMs ?? 250,
+            "pollIntervalMs"
+        );
+    const controller =
+        new AbortController();
+    let running =
+        true;
+    let stopPromise:
+        Promise<void> | null =
+        null;
+
+    const loops =
+        Array.from(
+            {
+                length:
+                    concurrency,
+            },
+            () =>
+                runWorkerLoop(
+                    queue,
+                    controller.signal,
+                    pollIntervalMs
+                )
+        );
+
+    return {
+        get running() {
+            return running;
+        },
+
+        stop() {
+            if (stopPromise) {
+                return stopPromise;
+            }
+
+            running =
+                false;
+            controller.abort();
+            stopPromise =
+                Promise.allSettled(
+                    loops
+                )
+                    .then(
+                        () => {
+                            onStop();
+                        }
+                    );
+
+            return stopPromise;
+        },
+    };
+}
+
+async function runWorkerLoop(
+    queue: BackgroundJobQueue,
+    signal: AbortSignal,
+    pollIntervalMs: number
+): Promise<void> {
+    while (!signal.aborted) {
+        const processed =
+            await queue.processNext(
+                signal
+            );
+
+        if (
+            !processed &&
+            !signal.aborted
+        ) {
+            await sleep(
+                pollIntervalMs,
+                signal
+            );
+        }
+    }
+}
+
+function sleep(
+    durationMs: number,
+    signal: AbortSignal
+): Promise<void> {
+    if (
+        durationMs === 0 ||
+        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 resolveRetryDelay(
+    value: JobRetryDelay,
+    attempt: number
+): number {
+    const delay =
+        typeof value === "function"
+            ? value(attempt)
+            : value;
+
+    return normalizeNonNegativeNumber(
+        delay,
+        "retryDelayMs"
+    );
+}
+
+function normalizeJobName(
+    value: string
+): string {
+    const name =
+        String(value)
+            .trim();
+
+    if (!name) {
+        throw new TypeError(
+            "BCP Jobs: job name must be a non-empty string."
+        );
+    }
+
+    if (name.length > 200) {
+        throw new TypeError(
+            "BCP Jobs: job name must not exceed 200 characters."
+        );
+    }
+
+    return name;
+}
+
+function normalizeJobId(
+    value: string
+): string {
+    const id =
+        String(value)
+            .trim();
+
+    if (!id) {
+        throw new TypeError(
+            "BCP Jobs: job id must be a non-empty string."
+        );
+    }
+
+    if (id.length > 200) {
+        throw new TypeError(
+            "BCP Jobs: job id must not exceed 200 characters."
+        );
+    }
+
+    return id;
+}
+
+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 normalizeNonNegativeNumber(
+    value: number,
+    field: string
+): number {
+    if (
+        !Number.isFinite(value) ||
+        value < 0
+    ) {
+        throw new TypeError(
+            `BCP Jobs: ${field} must be a non-negative finite number.`
+        );
+    }
+
+    return Math.floor(value);
+}
+
+function formatJobError(
+    error: unknown
+): string {
+    if (error instanceof Error) {
+        return error.message ||
+            error.name;
+    }
+
+    if (typeof error === "string") {
+        return error;
+    }
+
+    try {
+        const serialized =
+            JSON.stringify(error);
+
+        return serialized ??
+            String(error);
+    } catch {
+        return String(error);
+    }
+}
+
+function cloneJob<
+    TPayload
+>(
+    job: JobRecord<TPayload>
+): JobRecord<TPayload> {
+    return {
+        ...job,
+    };
+}