@quark-fw/plugin-threads 0.1.26 → 0.1.27

package/README.md

@@ -0,0 +1,39 @@
+# @quark-fw/plugin-threads
+
+Worker processes for Quark apps: every `src/**/*.quark.ts` file is forked as a child process with a light quark context (core + env + redis), and `quark.ee` is bridged between processes over Redis pub/sub, so an event emitted in the web process is received in the workers and vice versa. Design spec: `docs/superpowers/specs/2026-08-22-quark-threads-design.md`.
+
+## Install
+
+```sh
+npm i @quark-fw/plugin-threads
+```
+
+Peer: `@quark-fw/core`. Requires `@quark-fw/plugin-redis` (`dependsOn: ["redis"]`); `@quark-fw/plugin-env` and `@quark-fw/plugin-redis` are loaded inside each worker.
+
+## Usage
+
+```ts
+// src/index.ts
+import "@quark-fw/plugin-redis";
+import "@quark-fw/plugin-threads"; // provides quark.threads; workers start in onReady
+
+// src/ping.quark.ts — a worker file; runs in its own process
+export const config = { instances: 1 };
+
+quark.ee.value.on("ping:send", (n) => {
+  quark.ee.value.emit("ping:pong", n * 2); // reaches the web process over Redis
+});
+
+// main process
+quark.threads.list.value; // [{ file, instance, pid }]
+await quark.threads.spawn("src/ping.quark.ts");
+await quark.threads.stop("src/ping.quark.ts");
+```
+
+How it works: in `onReady` the plugin globs `src/**/*.quark.ts` (skipping `node_modules` and `frontend`), attaches the event bridge only if at least one file exists (no workers, no Redis requirement), and forks `worker-entry.ts` for each file with `--import tsx`. The worker sets `quark.thread = { file, instance, instances }` before importing the file, reads `export const config = { instances }` and reports it back over IPC (`quark:online`); instance 0 tells the parent how many instances to spawn, so `instances > 1` is a broadcast — every instance receives every event and splits work by `quark.thread.instance`. The bridge publishes each `emit` to the Redis channel `quark:ee` as `{ origin, event, args }` and re-emits incoming messages locally; `lifecycle:init`, `plugin:init`, `atom:update` and non-serializable payloads stay local. The bus also carries `thread:online`, `thread:exit` and `thread:restart`.
+
+Supervision: a crashed instance is restarted with backoff `min(1s * 2^n, 30s)`, the counter resets after 60 s of uptime. Shutdown sends `quark:shutdown` over IPC (the worker runs `quark.destroy()`), then `SIGTERM` after 5 s and `SIGKILL` after another 5 s. Outside production a chokidar watcher on `src` restarts the workers of a changed `.quark.ts`, spawns new files and stops deleted ones.
+
+Env: `NODE_ENV` — the dev watcher runs unless it is `production`. Redis address comes from `@quark-fw/plugin-redis` (`REDIS_URL`).
+
+Part of the [Quark framework](https://www.npmjs.com/package/@quark-fw/core).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/plugin-threads",
-	"version": "0.1.26",
+	"version": "0.1.27",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",
@@ -21,16 +21,16 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/atom": "0.1.26",
-		"@quark-fw/plugin": "0.1.26",
-		"@quark-fw/plugin-env": "0.1.26",
-		"@quark-fw/plugin-redis": "0.1.26",
+		"@quark-fw/atom": "0.1.27",
+		"@quark-fw/plugin": "0.1.27",
+		"@quark-fw/plugin-env": "0.1.27",
+		"@quark-fw/plugin-redis": "0.1.27",
 		"chokidar": "^5.0.0"
 	},
 	"devDependencies": {
 		"ioredis": "^5.9.3"
 	},
 	"peerDependencies": {
-		"@quark-fw/core": "0.1.26"
+		"@quark-fw/core": "0.1.27"
 	}
 }

package/src/bridge.ts

@@ -1,5 +1,8 @@
 import crypto from "node:crypto";
 import { quitClient } from "./helpers.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "threads" });
 
 const CHANNEL = "quark:ee";
 
@@ -44,7 +47,7 @@ export async function attachEventBridge(
 			if (msg.origin === origin) return; // эхо собственного publish
 			originalEmit(msg.event, ...msg.args);
 		} catch (e) {
-			console.error("[threads] bad bridge message", e);
+			log.error("bad bridge message", { err: e });
 		}
 	});
 
@@ -60,7 +63,7 @@ export async function attachEventBridge(
 					args,
 				} satisfies BridgeMessage);
 				void pub.publish(CHANNEL, payload).catch((e) => {
-					console.error("[threads] publish failed", e);
+					log.error("publish failed", { err: e });
 				});
 			} catch {
 				// несериализуемые аргументы — событие остаётся локальным

package/src/index.ts

@@ -7,6 +7,9 @@ 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";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "threads" });
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const workerEntry = path.join(__dirname, "worker-entry.ts");
@@ -80,9 +83,12 @@ await quark.registerPlugin({
 				"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})`,
-					);
+					log.info("worker online", {
+						file: path.relative(process.cwd(), file),
+						instance,
+						instances: Number(msg.config?.instances ?? 1),
+						pid: child.pid,
+					});
 					quark.ee.value.emit("thread:online", file, instance);
 					restarts.delete(`${file}#${instance}`);
 

package/src/worker-entry.ts

@@ -6,6 +6,9 @@ import "@quark-fw/plugin-redis";
 import { pathToFileURL } from "node:url";
 import { attachEventBridge } from "./bridge.js";
 import {} from "@quark-fw/plugin-threads/src/global.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "threads" });
 
 const file = process.argv[2]!;
 const instance = Number(process.argv[3] ?? 0);
@@ -18,7 +21,9 @@ 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 quark
+				.destroy()
+				.catch((e) => log.error("destroy failed", { err: e }));
 			await bridge.close().catch(() => {});
 			process.exit(0);
 		})();