@quark-fw/plugin-cron 0.0.0-stage → 0.1.19

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @quark-fw/plugin-cron
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+In-process cron scheduler for Quark apps: 5-field expressions (UTC), a Redis lock so only one instance runs a job, and per-job status (last run, success, error, duration) stored in Redis.
+
+## Install
+
+```sh
+npm i @quark-fw/plugin-cron
+```
+
+Peers: `@quark-fw/core`, `@quark-fw/plugin-redis`, `ioredis`.
+
+## Usage
+
+```ts
+import "@quark-fw/plugin-redis";
+import "@quark-fw/plugin-cron"; // provides quark.cron
+
+quark.cron.schedule("parse-listings", "7 * * * *", () => runParser(), {
+  lockTtlMs: 30 * 60 * 1000, // longer than the slowest run
+  maxAgeMs: 3 * 60 * 60 * 1000, // plugin-health reports the job stale after 3h without success
+});
+
+await quark.cron.run("parse-listings"); // manual trigger (false if another instance holds the lock)
+await quark.cron.status(); // [{ name, lastRunAt, lastSuccessAt, lastError, stale, … }]
+```
+
+- Expressions: `*`, `a,b`, `a-b`, `*/n`, `a-b/n`, aliases `@hourly @daily @weekly @monthly`; evaluated in UTC.
+- Heavy work (downloads, LLM calls) belongs in a child process spawned from the handler, not in the web process.
+- Env: `CRON_PREFIX` (default `quark:cron:`), `CRON_DISABLED=1` to register jobs without ticking.
+- If Redis is down, the job still runs on this instance and the error goes to `onError`.
+
+Part of the [Quark framework](https://www.npmjs.com/package/@quark-fw/core).

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@quark-fw/plugin-cron",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@quark-fw/plugin-cron",
+	"version": "0.1.19",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"type": "module",
+	"scripts": {
+		"build": "echo raw-src package, no build",
+		"test": "vitest run"
+	},
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"quark",
+		"cron",
+		"scheduler"
+	],
+	"author": "",
+	"license": "ISC",
+	"description": "In-process cron scheduler for the Quark framework with a Redis lock across instances and per-job status (published as raw TS sources; consumers run tsx)",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@quark-fw/atom": "0.1.19",
+		"@quark-fw/plugin": "0.1.19"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.1.19",
+		"@quark-fw/plugin-redis": "0.1.19",
+		"ioredis": "^5.9.3"
+	},
+	"devDependencies": {
+		"vitest": "^5.0.0"
+	}
+}

package/src/CronScheduler.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test, vi } from "vitest";
+import type { Redis } from "ioredis";
+import { CronScheduler } from "./CronScheduler.js";
+import { cronMatches, parseCron } from "./cronExpression.js";
+
+function fakeRedis() {
+	const kv = new Map<string, string>();
+	const hashes = new Map<string, Record<string, string>>();
+	const client = {
+		set: vi.fn(async (key: string, value: string, ..._args: unknown[]) => {
+			const nx = _args.includes("NX");
+			if (nx && kv.has(key)) return null;
+			kv.set(key, value);
+			return "OK";
+		}),
+		get: vi.fn(async (key: string) => kv.get(key) ?? null),
+		del: vi.fn(async (key: string) => (kv.delete(key) ? 1 : 0)),
+		hset: vi.fn(async (key: string, fields: Record<string, string>) => {
+			hashes.set(key, { ...(hashes.get(key) ?? {}), ...fields });
+			return 1;
+		}),
+		hgetall: vi.fn(async (key: string) => hashes.get(key) ?? {}),
+	};
+	return { client: client as unknown as Redis, kv, hashes };
+}
+
+const at = (iso: string) => new Date(iso);
+
+describe("cronExpression", () => {
+	test("разбирает звёздочки, шаги, диапазоны, списки и алиасы", () => {
+		const f = parseCron("7 */6 1-3,15 * 1-5");
+		expect([...f.minute]).toEqual([7]);
+		expect([...f.hour]).toEqual([0, 6, 12, 18]);
+		expect([...f.dayOfMonth]).toEqual([1, 2, 3, 15]);
+		expect([...f.dayOfWeek]).toEqual([1, 2, 3, 4, 5]);
+		expect([...parseCron("@hourly").minute]).toEqual([0]);
+		// 7 — тоже воскресенье
+		expect([...parseCron("0 0 * * 7").dayOfWeek]).toEqual([0]);
+	});
+
+	test("матчит минуту в UTC", () => {
+		const f = parseCron("7 * * * *");
+		expect(cronMatches(f, at("2026-10-06T12:07:30Z"))).toBe(true);
+		expect(cronMatches(f, at("2026-10-06T12:08:00Z"))).toBe(false);
+	});
+
+	test("отвергает мусор", () => {
+		expect(() => parseCron("* * *")).toThrow();
+		expect(() => parseCron("61 * * * *")).toThrow();
+		expect(() => parseCron("*/0 * * * *")).toThrow();
+	});
+});
+
+describe("CronScheduler", () => {
+	test("tick запускает совпавшую задачу один раз за минуту и пишет статус", async () => {
+		const { client } = fakeRedis();
+		let now = at("2026-10-06T12:07:05Z");
+		const cron = new CronScheduler({
+			client: () => client,
+			now: () => now,
+			prefix: "t:",
+		});
+		const handler = vi.fn(async () => {});
+		cron.schedule("job", "7 * * * *", handler, { maxAgeMs: 3_600_000 });
+
+		await cron.tick();
+		await cron.tick(at("2026-10-06T12:07:40Z"));
+		await cron.tick(at("2026-10-06T12:08:05Z"));
+		await new Promise((r) => setTimeout(r, 0));
+
+		expect(handler).toHaveBeenCalledTimes(1);
+		const [status] = await cron.status();
+		expect(status!.lastSuccessAt).toBe("2026-10-06T12:07:05.000Z");
+		expect(status!.lastError).toBeNull();
+		expect(status!.stale).toBe(false);
+
+		now = at("2026-10-06T14:00:00Z");
+		expect((await cron.status())[0]!.stale).toBe(true);
+	});
+
+	test("лок в Redis: второй инстанс не запускает ту же задачу", async () => {
+		const { client } = fakeRedis();
+		const a = new CronScheduler({ client: () => client, prefix: "t:" });
+		const b = new CronScheduler({ client: () => client, prefix: "t:" });
+		let release!: () => void;
+		const slow = () => new Promise<void>((resolve) => (release = resolve));
+		const fast = vi.fn(async () => {});
+		a.schedule("job", "* * * * *", slow);
+		b.schedule("job", "* * * * *", fast);
+
+		const first = a.run("job");
+		await new Promise((r) => setTimeout(r, 0));
+		const second = await b.run("job");
+
+		expect(second).toBe(false);
+		expect(fast).not.toHaveBeenCalled();
+		release();
+		expect(await first).toBe(true);
+		// лок снят владельцем — теперь b может запустить
+		expect(await b.run("job")).toBe(true);
+	});
+
+	test("ошибка задачи попадает в статус и не роняет планировщик", async () => {
+		const { client } = fakeRedis();
+		const onError = vi.fn();
+		const cron = new CronScheduler({
+			client: () => client,
+			onError,
+			prefix: "t:",
+		});
+		cron.schedule("boom", "* * * * *", async () => {
+			throw new Error("нет связи");
+		});
+		expect(await cron.run("boom")).toBe(true);
+		expect(onError).toHaveBeenCalledWith("boom", expect.any(Error));
+		expect((await cron.status())[0]!.lastError).toBe("нет связи");
+	});
+});

package/src/CronScheduler.ts

@@ -0,0 +1,226 @@
+import os from "node:os";
+import type { Redis } from "ioredis";
+import {
+	cronMatches,
+	minuteKey,
+	parseCron,
+	type CronFields,
+} from "./cronExpression.js";
+import type {
+	CronHandler,
+	CronJob,
+	CronJobOptions,
+	CronJobStatus,
+} from "./types.js";
+
+// команды ioredis, которыми пользуется планировщик (тесты подсовывают фейк)
+type RedisLike = Pick<Redis, "set" | "get" | "del" | "hset" | "hgetall">;
+
+export type CronSchedulerConfig = {
+	client: () => RedisLike;
+	prefix?: string;
+	/** период проверки расписания, мс (минутная сетка — 20 с с запасом) */
+	tickMs?: number;
+	now?: () => Date;
+	onError?: (job: string, error: unknown) => void;
+};
+
+const DEFAULT_LOCK_TTL = 10 * 60 * 1000;
+
+/**
+ * Планировщик cron-задач внутри приложения.
+ *
+ * Каждая минута проверяется на совпадение с выражениями; совпавшая задача
+ * берёт Redis-лок (`SET NX PX`), поэтому при нескольких инстансах приложения
+ * её выполнит один. Статус (последний запуск, успех, ошибка, длительность)
+ * лежит в Redis — его видят все инстансы и проверка здоровья.
+ */
+export class CronScheduler {
+	private readonly client: () => RedisLike;
+	private readonly prefix: string;
+	private readonly tickMs: number;
+	private readonly now: () => Date;
+	private readonly onError: (job: string, error: unknown) => void;
+	private readonly jobs = new Map<
+		string,
+		CronJob & { fields: CronFields; firedMinute?: string }
+	>();
+	private readonly running = new Set<string>();
+	private timer: NodeJS.Timeout | undefined;
+	readonly runnerId = `${os.hostname()}:${process.pid}`;
+
+	constructor({
+		client,
+		prefix = "quark:cron:",
+		tickMs = 20_000,
+		now = () => new Date(),
+		onError = (job, error) => console.error(`[cron] ${job}:`, error),
+	}: CronSchedulerConfig) {
+		this.client = client;
+		this.prefix = prefix;
+		this.tickMs = tickMs;
+		this.now = now;
+		this.onError = onError;
+	}
+
+	/** Регистрирует задачу; выражение проверяется сразу. */
+	schedule(
+		name: string,
+		expression: string,
+		handler: CronHandler,
+		options: CronJobOptions = {},
+	): void {
+		if (this.jobs.has(name))
+			throw new Error(`cron: job "${name}" is already scheduled`);
+		this.jobs.set(name, {
+			name,
+			expression,
+			handler,
+			options: { lockTtlMs: DEFAULT_LOCK_TTL, ...options },
+			fields: parseCron(expression),
+		});
+		if (options.runOnStart) void this.run(name);
+	}
+
+	unschedule(name: string): void {
+		this.jobs.delete(name);
+	}
+
+	names(): string[] {
+		return [...this.jobs.keys()];
+	}
+
+	start(): void {
+		if (this.timer) return;
+		this.timer = setInterval(() => void this.tick(), this.tickMs);
+		// таймер не держит процесс живым — приложение завершается штатно
+		this.timer.unref?.();
+	}
+
+	stop(): void {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = undefined;
+	}
+
+	/** Один проход по расписанию: запускает задачи, чья минута совпала. */
+	async tick(date = this.now()): Promise<void> {
+		const key = minuteKey(date);
+		for (const job of this.jobs.values()) {
+			if (job.firedMinute === key || !cronMatches(job.fields, date))
+				continue;
+			job.firedMinute = key;
+			void this.run(job.name);
+		}
+	}
+
+	/**
+	 * Запускает задачу вне расписания (или по нему). Возвращает false, если
+	 * лок держит другой инстанс или задача уже выполняется здесь.
+	 */
+	async run(name: string): Promise<boolean> {
+		const job = this.jobs.get(name);
+		if (!job) throw new Error(`cron: unknown job "${name}"`);
+		if (this.running.has(name)) return false;
+
+		const lockKey = `${this.prefix}lock:${name}`;
+		// без Redis задача всё равно выполняется: одиночный инстанс важнее
+		// строгой взаимной блокировки
+		const locked = await this.client()
+			.set(lockKey, this.runnerId, "PX", job.options.lockTtlMs, "NX")
+			.then((reply) => reply === "OK")
+			.catch((error) => {
+				this.onError(name, error);
+				return true;
+			});
+		if (!locked) return false;
+
+		this.running.add(name);
+		const startedAt = this.now();
+		await this.writeStatus(name, {
+			lastRunAt: startedAt.toISOString(),
+			lastRunner: this.runnerId,
+			running: "1",
+		});
+		try {
+			await job.handler();
+			await this.writeStatus(name, {
+				lastSuccessAt: this.now().toISOString(),
+				lastDurationMs: String(
+					this.now().getTime() - startedAt.getTime(),
+				),
+				lastError: "",
+				running: "0",
+			});
+		} catch (error) {
+			this.onError(name, error);
+			await this.writeStatus(name, {
+				lastError:
+					error instanceof Error ? error.message : String(error),
+				lastDurationMs: String(
+					this.now().getTime() - startedAt.getTime(),
+				),
+				running: "0",
+			});
+		} finally {
+			this.running.delete(name);
+			// лок снимается только своим владельцем: чужой (после истечения
+			// TTL и перезахвата) трогать нельзя
+			try {
+				const client = this.client();
+				if ((await client.get(lockKey)) === this.runnerId)
+					await client.del(lockKey);
+			} catch (error) {
+				this.onError(name, error);
+			}
+		}
+		return true;
+	}
+
+	/** Статусы всех задач (из Redis) с признаком протухания. */
+	async status(): Promise<CronJobStatus[]> {
+		const result: CronJobStatus[] = [];
+		for (const job of this.jobs.values()) {
+			let raw: Record<string, string> = {};
+			try {
+				raw = await this.client().hgetall(
+					`${this.prefix}job:${job.name}`,
+				);
+			} catch (error) {
+				this.onError(job.name, error);
+			}
+			const lastSuccessAt = raw.lastSuccessAt || null;
+			const stale =
+				job.options.maxAgeMs === undefined
+					? undefined
+					: !lastSuccessAt ||
+						this.now().getTime() -
+							new Date(lastSuccessAt).getTime() >
+							job.options.maxAgeMs;
+			result.push({
+				name: job.name,
+				expression: job.expression,
+				lastRunAt: raw.lastRunAt || null,
+				lastSuccessAt,
+				lastDurationMs: raw.lastDurationMs
+					? Number(raw.lastDurationMs)
+					: null,
+				lastError: raw.lastError || null,
+				lastRunner: raw.lastRunner || null,
+				running: raw.running === "1" || this.running.has(job.name),
+				stale,
+			});
+		}
+		return result;
+	}
+
+	private async writeStatus(
+		name: string,
+		fields: Record<string, string>,
+	): Promise<void> {
+		try {
+			await this.client().hset(`${this.prefix}job:${name}`, fields);
+		} catch (error) {
+			this.onError(name, error);
+		}
+	}
+}

package/src/cronExpression.ts

@@ -0,0 +1,97 @@
+// Разбор 5-полевого cron-выражения (минута час день месяц день-недели) без
+// зависимостей. Поддерживаются `*`, списки `a,b`, диапазоны `a-b`, шаги
+// `*/n` и `a-b/n`; алиасы `@hourly`, `@daily`, `@weekly`, `@monthly`.
+// Время — UTC: расписание не зависит от TZ контейнера.
+
+export type CronFields = {
+	minute: Set<number>;
+	hour: Set<number>;
+	dayOfMonth: Set<number>;
+	month: Set<number>;
+	dayOfWeek: Set<number>;
+};
+
+const ALIASES: Record<string, string> = {
+	"@hourly": "0 * * * *",
+	"@daily": "0 0 * * *",
+	"@midnight": "0 0 * * *",
+	"@weekly": "0 0 * * 0",
+	"@monthly": "0 0 1 * *",
+};
+
+function parseField(
+	field: string,
+	min: number,
+	max: number,
+	name: string,
+): Set<number> {
+	const values = new Set<number>();
+	for (const part of field.split(",")) {
+		const [rangePart, stepPart] = part.split("/");
+		const step = stepPart === undefined ? 1 : Number(stepPart);
+		if (!Number.isInteger(step) || step < 1) {
+			throw new Error(`cron: bad step "${part}" in ${name}`);
+		}
+		let from = min;
+		let to = max;
+		if (rangePart !== "*") {
+			const [a, b] = rangePart!.split("-").map(Number);
+			if (!Number.isInteger(a))
+				throw new Error(`cron: bad value "${part}" in ${name}`);
+			from = a!;
+			// `a/n` без диапазона означает «от a до максимума с шагом n»
+			to = b === undefined ? (stepPart === undefined ? a! : max) : b;
+			if (!Number.isInteger(to))
+				throw new Error(`cron: bad range "${part}" in ${name}`);
+		}
+		if (from < min || to > max || from > to) {
+			throw new Error(
+				`cron: "${part}" out of range ${min}-${max} in ${name}`,
+			);
+		}
+		for (let v = from; v <= to; v += step) values.add(v);
+	}
+	return values;
+}
+
+export function parseCron(expression: string): CronFields {
+	const expr = (ALIASES[expression.trim()] ?? expression).trim().split(/\s+/);
+	if (expr.length !== 5) {
+		throw new Error(`cron: expected 5 fields, got "${expression}"`);
+	}
+	const [minute, hour, dayOfMonth, month, dayOfWeek] = expr as [
+		string,
+		string,
+		string,
+		string,
+		string,
+	];
+	const dow = parseField(
+		dayOfWeek.replace(/\b7\b/g, "0"),
+		0,
+		6,
+		"day-of-week",
+	);
+	return {
+		minute: parseField(minute, 0, 59, "minute"),
+		hour: parseField(hour, 0, 23, "hour"),
+		dayOfMonth: parseField(dayOfMonth, 1, 31, "day-of-month"),
+		month: parseField(month, 1, 12, "month"),
+		dayOfWeek: dow,
+	};
+}
+
+/** Совпадает ли минута `date` (UTC) с выражением. */
+export function cronMatches(fields: CronFields, date: Date): boolean {
+	return (
+		fields.minute.has(date.getUTCMinutes()) &&
+		fields.hour.has(date.getUTCHours()) &&
+		fields.dayOfMonth.has(date.getUTCDate()) &&
+		fields.month.has(date.getUTCMonth() + 1) &&
+		fields.dayOfWeek.has(date.getUTCDay())
+	);
+}
+
+/** Ключ минуты — чтобы задача не сработала дважды за одну минуту. */
+export const minuteKey = (date: Date): string =>
+	date.toISOString().slice(0, 16);

package/src/global.d.ts

@@ -0,0 +1,16 @@
+import "@quark-fw/core/src/global.d.ts";
+import type { CronScheduler } from "./CronScheduler.js";
+
+export {};
+
+declare global {
+	interface Quark {
+		/** cron-задачи внутри приложения с Redis-локом между инстансами */
+		cron: CronScheduler;
+	}
+
+	interface Events {
+		"cron:started": [name: string];
+		"cron:finished": [name: string, ok: boolean];
+	}
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+import { QuarkPlugin } from "@quark-fw/plugin";
+import {} from "@quark-fw/plugin-redis/src/global.js";
+import {} from "@quark-fw/plugin-cron/src/global.js";
+import { CronScheduler } from "./CronScheduler.js";
+
+export { CronScheduler } from "./CronScheduler.js";
+export { parseCron, cronMatches } from "./cronExpression.js";
+export type { CronHandler, CronJobOptions, CronJobStatus } from "./types.js";
+
+// Плагин: quark.cron поверх клиента plugin-redis. Планировщик стартует в
+// onReady — к этому моменту приложение уже зарегистрировало задачи в своих
+// модулях. CRON_DISABLED=1 оставляет регистрацию, но не запускает тики
+// (локальная разработка, воркеры без расписания).
+await quark.registerPlugin({
+	name: "cron",
+	dependsOn: ["redis"],
+	extend(quark) {
+		quark.cron = new CronScheduler({
+			client: () => quark.redis.client.value,
+			prefix: process.env.CRON_PREFIX || "quark:cron:",
+		});
+	},
+	onReady(quark) {
+		if (process.env.CRON_DISABLED === "1") {
+			console.log("[cron] disabled (CRON_DISABLED=1)");
+			return;
+		}
+		quark.cron.start();
+		console.log(
+			`[cron] scheduled: ${quark.cron.names().join(", ") || "(none)"}`,
+		);
+	},
+	onDestroy(quark) {
+		quark.cron.stop();
+	},
+} satisfies QuarkPlugin);

package/src/types.ts

@@ -0,0 +1,37 @@
+export type CronJobOptions = {
+	/**
+	 * TTL Redis-лока в мс. Должен превышать худшее время задачи: пока лок
+	 * жив, ни один инстанс не запустит её повторно. По умолчанию 10 минут.
+	 */
+	lockTtlMs?: number;
+	/**
+	 * Максимальный возраст последнего успешного запуска для проверки
+	 * здоровья (plugin-health): старше — задача считается протухшей.
+	 */
+	maxAgeMs?: number;
+	/** запустить сразу при старте, не дожидаясь расписания */
+	runOnStart?: boolean;
+};
+
+export type CronJobStatus = {
+	name: string;
+	expression: string;
+	lastRunAt: string | null;
+	lastSuccessAt: string | null;
+	lastDurationMs: number | null;
+	lastError: string | null;
+	/** инстанс (hostname:pid), выполнявший задачу в последний раз */
+	lastRunner: string | null;
+	running: boolean;
+	/** протухла по maxAgeMs (undefined — maxAgeMs не задан) */
+	stale?: boolean;
+};
+
+export type CronHandler = () => Promise<void> | void;
+
+export type CronJob = {
+	name: string;
+	expression: string;
+	handler: CronHandler;
+	options: Required<Pick<CronJobOptions, "lockTtlMs">> & CronJobOptions;
+};