@quark-fw/plugin-threads 0.1.13

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@quark-fw/plugin-threads",
+	"version": "0.1.13",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"type": "module",
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "echo raw-src package, no build"
+	},
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"quark"
+	],
+	"author": "",
+	"license": "ISC",
+	"description": "Worker-process plugin for the Quark framework: forks each src/**/*.quark.ts, bridges quark.ee over Redis pub/sub (published as raw TS sources; consumers run tsx)",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@quark-fw/atom": "0.1.13",
+		"@quark-fw/plugin": "0.1.13",
+		"@quark-fw/plugin-env": "0.1.13",
+		"@quark-fw/plugin-redis": "0.1.13",
+		"chokidar": "^5.0.0"
+	},
+	"devDependencies": {
+		"ioredis": "^5.9.3"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.1.13"
+	}
+}

package/src/bridge.ts

@@ -0,0 +1,81 @@
+import crypto from "node:crypto";
+import { quitClient } from "./helpers.js";
+
+const CHANNEL = "quark:ee";
+
+// события, которые никогда не покидают процесс
+const LOCAL_EVENTS = new Set(["lifecycle:init", "plugin:init", "atom:update"]);
+
+export type EventBridge = {
+	close(): Promise<void>;
+};
+
+type BridgeMessage = {
+	origin: string;
+	event: string;
+	args: unknown[];
+};
+
+// ВАЖНО: мост подключается ПОСЛЕ любых обёрток над emitter'ом (например
+// debug-Proxy из createTypedEventEmitter) — он захватывает текущий emit
+// и подменяет его собственным.
+export async function attachEventBridge(
+	quark: Quark,
+	opts: { localEvents?: string[] } = {},
+): Promise<EventBridge> {
+	const origin = crypto.randomUUID();
+	const local = new Set([...LOCAL_EVENTS, ...(opts.localEvents ?? [])]);
+
+	const pub = quark.redis.client.value.duplicate();
+	const sub = quark.redis.client.value.duplicate();
+	await sub.subscribe(CHANNEL);
+
+	const ee = quark.ee.value;
+	// захватываем оригинал ДО подмены, иначе входящее сообщение
+	// зациклится через собственный патч
+	const originalEmit = ee.emit.bind(ee) as unknown as (
+		event: string,
+		...args: unknown[]
+	) => boolean;
+
+	sub.on("message", (_channel: string, raw: string) => {
+		try {
+			const msg = JSON.parse(raw) as BridgeMessage;
+			if (msg.origin === origin) return; // эхо собственного publish
+			originalEmit(msg.event, ...msg.args);
+		} catch (e) {
+			console.error("[threads] bad bridge message", e);
+		}
+	});
+
+	// emit подменяется намеренно: события уходят ещё и в Redis. Тип эмиттера
+	// разбирает событие по имени, поэтому здесь он берётся структурно.
+	type EmitHost = { emit: (event: string, ...args: unknown[]) => boolean };
+	(ee as unknown as EmitHost).emit = (event: string, ...args: unknown[]) => {
+		if (!local.has(event)) {
+			try {
+				const payload = JSON.stringify({
+					origin,
+					event,
+					args,
+				} satisfies BridgeMessage);
+				void pub.publish(CHANNEL, payload).catch((e) => {
+					console.error("[threads] publish failed", e);
+				});
+			} catch {
+				// несериализуемые аргументы — событие остаётся локальным
+			}
+		}
+		return originalEmit(event, ...args);
+	};
+
+	return {
+		async close() {
+			(ee as unknown as EmitHost).emit = originalEmit;
+			sub.removeAllListeners("message");
+			await sub.unsubscribe(CHANNEL).catch(() => {});
+			await quitClient(pub);
+			await quitClient(sub);
+		},
+	};
+}

package/src/global.d.ts

@@ -0,0 +1,32 @@
+import "@quark-fw/core/src/global.d.ts";
+import { Atom } from "@quark-fw/atom";
+
+export {};
+
+export type ThreadInfo = {
+	file: string;
+	instance: number;
+	pid?: number;
+};
+
+declare global {
+	interface Events {
+		"thread:online": [file: string, instance: number];
+		"thread:exit": [file: string, instance: number, code: number | null];
+		"thread:restart": [file: string, instance: number];
+	}
+
+	interface Quark {
+		threads: {
+			list: Atom<ThreadInfo[]>;
+			spawn(file: string): Promise<void>;
+			stop(file: string): Promise<void>;
+		};
+		// присутствует только внутри .quark.ts-процесса
+		thread?: {
+			file: string;
+			instance: number;
+			instances: number;
+		};
+	}
+}

package/src/helpers.ts

@@ -0,0 +1,6 @@
+// Хелперы threads-плагина.
+import type { Redis } from "ioredis";
+
+export async function quitClient(client: Redis) {
+	await client.quit().catch(() => client.disconnect());
+}

package/src/index.ts

@@ -0,0 +1,200 @@
+import atom from "@quark-fw/atom";
+import { QuarkPlugin } from "@quark-fw/plugin";
+import { ChildProcess, fork } from "node:child_process";
+import { globSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import chokidar, { FSWatcher } from "chokidar";
+import { attachEventBridge, EventBridge } from "./bridge.js";
+import { ThreadInfo } from "@quark-fw/plugin-threads/src/global.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const workerEntry = path.join(__dirname, "worker-entry.ts");
+const isProd = process.env.NODE_ENV === "production";
+
+const RESTART_RESET_MS = 60_000;
+const RESTART_MAX_DELAY_MS = 30_000;
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+
+type WorkerHandle = {
+	file: string;
+	instance: number;
+	child: ChildProcess;
+	startedAt: number;
+	stopping: boolean;
+};
+
+let bridge: EventBridge | undefined;
+let watcher: FSWatcher | undefined;
+let destroyed = false;
+
+await quark.registerPlugin({
+	name: "threads",
+	dependsOn: ["redis"],
+	extend(quark) {
+		const list = atom<ThreadInfo[]>("threads.list", []);
+
+		// file -> живые инстансы
+		const handles = new Map<string, WorkerHandle[]>();
+		// "file#instance" -> число рестартов подряд
+		const restarts = new Map<string, number>();
+
+		const updateList = () => {
+			list.value = [...handles.values()].flat().map((h) => ({
+				file: h.file,
+				instance: h.instance,
+				pid: h.child.pid,
+			}));
+		};
+
+		const forkInstance = (file: string, instance: number) => {
+			const child = fork(workerEntry, [file, String(instance)], {
+				execArgv: ["--import", "tsx"],
+			});
+			const handle: WorkerHandle = {
+				file,
+				instance,
+				child,
+				startedAt: Date.now(),
+				stopping: false,
+			};
+			const all = handles.get(file) ?? [];
+			all.push(handle);
+			handles.set(file, all);
+			updateList();
+
+			child.on(
+				"message",
+				(msg: { type?: string; config?: { instances?: number } }) => {
+					if (msg?.type !== "quark:online") return;
+					console.log(
+						`[threads] ${path.relative(process.cwd(), file)} #${instance}/${Number(msg.config?.instances ?? 1)} online (pid ${child.pid})`,
+					);
+					quark.ee.value.emit("thread:online", file, instance);
+					restarts.delete(`${file}#${instance}`);
+
+					// инстанс 0 знает config — доспавниваем недостающие инстансы
+					if (instance === 0) {
+						const wanted = Number(msg.config?.instances ?? 1);
+						const running = new Set(
+							(handles.get(file) ?? []).map((h) => h.instance),
+						);
+						for (let i = 1; i < wanted; i++) {
+							if (!running.has(i)) forkInstance(file, i);
+						}
+					}
+				},
+			);
+
+			// рестарт работает и для воркера, упавшего до handshake
+			child.on("exit", (code) => {
+				handles.set(
+					file,
+					(handles.get(file) ?? []).filter((h) => h !== handle),
+				);
+				updateList();
+				quark.ee.value.emit("thread:exit", file, instance, code);
+
+				if (handle.stopping || destroyed) return;
+
+				const key = `${file}#${instance}`;
+				const uptime = Date.now() - handle.startedAt;
+				const n =
+					uptime > RESTART_RESET_MS ? 0 : (restarts.get(key) ?? 0);
+				restarts.set(key, n + 1);
+				const delay = Math.min(1000 * 2 ** n, RESTART_MAX_DELAY_MS);
+
+				setTimeout(() => {
+					if (destroyed) return;
+					quark.ee.value.emit("thread:restart", file, instance);
+					forkInstance(file, instance);
+				}, delay).unref();
+			});
+		};
+
+		const stopHandle = (handle: WorkerHandle) =>
+			new Promise<void>((resolve) => {
+				handle.stopping = true;
+				if (handle.child.exitCode !== null) return resolve();
+
+				const timeout = setTimeout(() => {
+					handle.child.kill();
+				}, SHUTDOWN_TIMEOUT_MS);
+				handle.child.once("exit", () => {
+					clearTimeout(timeout);
+					resolve();
+				});
+				try {
+					handle.child.send({ type: "quark:shutdown" });
+				} catch {
+					handle.child.kill();
+				}
+			});
+
+		quark.threads = {
+			list,
+			async spawn(file) {
+				const abs = path.resolve(file);
+				if ((handles.get(abs) ?? []).length) return;
+				forkInstance(abs, 0);
+			},
+			async stop(file) {
+				const abs = path.resolve(file);
+				const all = handles.get(abs) ?? [];
+				await Promise.all(all.map(stopHandle));
+				handles.delete(abs);
+				updateList();
+			},
+		};
+	},
+	async onReady(quark) {
+		const files = globSync("src/**/*.quark.ts", {
+			cwd: process.cwd(),
+			exclude: (p) =>
+				String(p).includes("node_modules") ||
+				String(p).includes("frontend"),
+		});
+		if (!files.length) return;
+
+		// мост нужен только когда есть воркеры
+		bridge = await attachEventBridge(quark);
+
+		for (const file of files) {
+			await quark.threads.spawn(path.resolve(file));
+		}
+
+		if (!isProd) {
+			watcher = chokidar.watch("src", {
+				ignoreInitial: true,
+				ignored: (p) =>
+					p.includes("node_modules") ||
+					p.includes(`src${path.sep}frontend`),
+			});
+			watcher.on("all", (event, changedPath) => {
+				if (!changedPath.endsWith(".quark.ts")) return;
+				const abs = path.resolve(changedPath);
+				if (event === "change") {
+					void quark.threads
+						.stop(abs)
+						.then(() => quark.threads.spawn(abs));
+				} else if (event === "add") {
+					void quark.threads.spawn(abs);
+				} else if (event === "unlink") {
+					void quark.threads.stop(abs);
+				}
+			});
+		}
+	},
+	async onDestroy(quark) {
+		destroyed = true;
+		await watcher?.close();
+		watcher = undefined;
+		// мост закрываем до остановки воркеров: thread:exit при выключении —
+		// локальное событие, publish в закрывающийся клиент не нужен
+		await bridge?.close();
+		bridge = undefined;
+		for (const info of [...quark.threads.list.value]) {
+			await quark.threads.stop(info.file);
+		}
+	},
+} satisfies QuarkPlugin);

package/src/worker-entry.ts

@@ -0,0 +1,36 @@
+// Точка входа дочернего процесса: собирает лёгкий quark-контекст
+// (core + env + redis + мост событий) и импортирует целевой .quark.ts файл.
+import "@quark-fw/core";
+import "@quark-fw/plugin-env";
+import "@quark-fw/plugin-redis";
+import { pathToFileURL } from "node:url";
+import { attachEventBridge } from "./bridge.js";
+import {} from "@quark-fw/plugin-threads/src/global.js";
+
+const file = process.argv[2]!;
+const instance = Number(process.argv[3] ?? 0);
+
+// до импорта файла, чтобы тело воркера уже видело quark.thread
+quark.thread = { file, instance, instances: 1 };
+
+const bridge = await attachEventBridge(quark);
+
+process.on("message", (msg) => {
+	if ((msg as { type?: string })?.type === "quark:shutdown") {
+		void (async () => {
+			await quark.destroy().catch(console.error);
+			await bridge.close().catch(() => {});
+			process.exit(0);
+		})();
+	}
+});
+
+const mod = (await import(pathToFileURL(file).href)) as {
+	config?: { instances?: number };
+};
+quark.thread.instances = Number(mod.config?.instances ?? 1);
+
+process.send?.({
+	type: "quark:online",
+	config: { instances: quark.thread.instances },
+});