@quark-fw/core 0.1.26 → 0.1.27

package/README.md

@@ -30,10 +30,52 @@ await quark.destroy(); // runs onDestroy hooks in reverse order
 - `quark.registerPlugin(plugin)` — registers a [`QuarkPlugin`](https://www.npmjs.com/package/@quark-fw/plugin); registrations are queued, `dependsOn` is enforced
 - `quark.plugins` — loaded plugins
 - `quark.ee` — an [atom](https://www.npmjs.com/package/@quark-fw/atom) holding the typed event emitter (`quark.ee.value.on/emit`)
-- `quark.ready()` / `quark.destroy()` — lifecycle
+- `quark.ready()` / `quark.destroy()` — lifecycle; `destroy()` runs every plugin's `onDestroy` even if one of them throws and is single-flight (concurrent calls share one run)
+
+## Logging and request context
+
+```ts
+import { log } from "@quark-fw/core/src/log.js";
+
+const logger = log.child({ scope: "billing" });
+logger.info("invoice sent", { invoiceId });
+logger.error("charge failed", { err }); // Error → { name, message, stack }
+```
+
+- `LOG_LEVEL` — `debug | info | warn | error` (default `info`)
+- `LOG_FORMAT` — `json` (default in production) or `pretty` (default otherwise); `warn`/`error` go to stderr
+- Every line written inside an HTTP request carries `requestId` — `@quark-fw/plugin-react` opens the request context (`X-Request-Id` from the proxy or a fresh uuid, echoed on the response). `runWithRequestContext` / `getRequestContext` are exported for custom hosts.
+- `createLogger({ level, format, sink })` builds an independent logger for tests.
+
+## Shutdown
+
+Importing core installs `SIGTERM`/`SIGINT` handlers: the first signal runs `quark.destroy()` and exits with `0`, a second signal exits with `1` immediately. If plugins do not stop within `QUARK_SHUTDOWN_TIMEOUT_MS` (default 8000, below Docker's 10 s `SIGKILL` grace) the process exits with `1`. `installShutdownHandlers` is exported for custom hosts and tests.
 
 Plugins extend `quark` and the global `Events` map through TypeScript declaration merging — see the `Quark` and `Events` interfaces shipped in this package's `global.d.ts`.
 
+## Testing
+
+`resetQuark()` destroys the registered plugins, removes the signal handlers and deletes the global so the next import of core builds a fresh `quark`. Plugin modules are cached by ESM, so re-import them after a reset:
+
+```ts
+import { afterEach, test, vi } from "vitest";
+
+afterEach(async () => {
+	const { resetQuark } = await import("@quark-fw/core");
+	await resetQuark();
+	vi.resetModules();
+});
+
+test("boots with a fake redis", async () => {
+	await import("@quark-fw/core");
+	await quark.registerPlugin({ name: "redis", extend(q) { q.redis = fakeRedis; } });
+	await import("@quark-fw/plugin-cron"); // dependsOn: ["redis"] is satisfied by the fake
+	await quark.ready();
+});
+```
+
+Plugin objects can also be passed to `registerPlugin` directly, without importing the plugin module.
+
 ## Ecosystem
 
 - [`@quark-fw/plugin`](https://www.npmjs.com/package/@quark-fw/plugin) — plugin contract + HTTP middleware registry

package/dist/createLogger.d.ts

@@ -0,0 +1,27 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogFields = Record<string, unknown>;
+export type Logger = {
+    readonly level: LogLevel;
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    /** логгер с постоянными полями, например `{ scope: "cron" }` */
+    child(bindings: LogFields): Logger;
+};
+export type CreateLoggerArgs = {
+    level?: LogLevel;
+    /** json — строка на запись для сборщиков логов; pretty — для терминала */
+    format?: "json" | "pretty";
+    /** куда писать строку; по умолчанию stdout, warn/error — stderr */
+    sink?: (line: string, level: LogLevel) => void;
+    bindings?: LogFields;
+    now?: () => Date;
+};
+export declare const isLogLevel: (value: unknown) => value is LogLevel;
+/**
+ * Логгер без зависимостей: уровни, JSON-строки для прода, request id из
+ * контекста запроса. Плагины писали console.log с ручными префиксами —
+ * без уровней их нельзя было ни выключить, ни распарсить в сборщике логов.
+ */
+export declare function createLogger({ level, format, sink, bindings, now, }?: CreateLoggerArgs): Logger;

package/dist/createLogger.js

@@ -0,0 +1,83 @@
+import { getRequestContext } from "./requestContext.js";
+const ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+export const isLogLevel = (value) => typeof value === "string" && value in ORDER;
+const defaultSink = (line, level) => {
+    (ORDER[level] >= ORDER.warn ? process.stderr : process.stdout).write(line + "\n");
+};
+// Error в JSON.stringify даёт {} — раскладываем руками
+const serializeField = (value) => value instanceof Error
+    ? { name: value.name, message: value.message, stack: value.stack }
+    : value;
+const pad = (n) => String(n).padStart(2, "0");
+const prettyLine = (time, level, msg, fields) => {
+    const { scope, requestId, ...rest } = fields;
+    const parts = [
+        `${pad(time.getHours())}:${pad(time.getMinutes())}:${pad(time.getSeconds())}`,
+        level.toUpperCase().padEnd(5),
+    ];
+    if (scope !== undefined)
+        parts.push(`[${String(scope)}]`);
+    parts.push(msg);
+    if (requestId !== undefined)
+        parts.push(`req=${String(requestId)}`);
+    // стеки ошибок — отдельными строками после полей
+    const errors = [];
+    for (const [key, value] of Object.entries(rest)) {
+        if (value instanceof Error) {
+            errors.push(`\n  ${key}: ${value.stack ?? value.message}`);
+        }
+        else if (typeof value === "string") {
+            parts.push(`${key}=${value}`);
+        }
+        else {
+            parts.push(`${key}=${JSON.stringify(value)}`);
+        }
+    }
+    return parts.join(" ") + errors.join("");
+};
+/**
+ * Логгер без зависимостей: уровни, JSON-строки для прода, request id из
+ * контекста запроса. Плагины писали console.log с ручными префиксами —
+ * без уровней их нельзя было ни выключить, ни распарсить в сборщике логов.
+ */
+export function createLogger({ level = "info", format = "json", sink = defaultSink, bindings = {}, now = () => new Date(), } = {}) {
+    const write = (lvl, msg, fields) => {
+        if (ORDER[lvl] < ORDER[level])
+            return;
+        const time = now();
+        const requestId = getRequestContext()?.requestId;
+        const all = {
+            ...(requestId ? { requestId } : {}),
+            ...bindings,
+            ...fields,
+        };
+        if (format === "pretty") {
+            sink(prettyLine(time, lvl, msg, all), lvl);
+            return;
+        }
+        const record = { time: time.toISOString(), level: lvl, msg };
+        for (const [key, value] of Object.entries(all)) {
+            record[key] = serializeField(value);
+        }
+        sink(JSON.stringify(record), lvl);
+    };
+    return {
+        level,
+        debug: (msg, fields) => write("debug", msg, fields),
+        info: (msg, fields) => write("info", msg, fields),
+        warn: (msg, fields) => write("warn", msg, fields),
+        error: (msg, fields) => write("error", msg, fields),
+        child: (more) => createLogger({
+            level,
+            format,
+            sink,
+            bindings: { ...bindings, ...more },
+            now,
+        }),
+    };
+}

package/dist/ee/createTypedEventEmitter.js

@@ -1,4 +1,6 @@
 import { EventEmitter } from "node:events";
+import { log as rootLog } from "../log.js";
+const log = rootLog.child({ scope: "ee" });
 export function createTypedEventEmitter({ debug, } = {
     debug: false,
 }) {
@@ -12,7 +14,7 @@ export function createTypedEventEmitter({ debug, } = {
             // Логируем emit
             if (prop === "emit") {
                 return (event, ...args) => {
-                    console.log(`[emit] ${event}`, ...args);
+                    log.debug("emit", { event, args });
                     return original.call(target, event, ...args);
                 };
             }
@@ -23,14 +25,14 @@ export function createTypedEventEmitter({ debug, } = {
                 prop === "prependListener" ||
                 prop === "prependOnceListener") {
                 return (event, listener) => {
-                    console.log(`[on] ${event}`, listener.toString());
+                    log.debug("on", { event, listener: listener.toString() });
                     return original.call(target, event, listener);
                 };
             }
             // Логируем удаление подписок
             if (prop === "off" || prop === "removeListener") {
                 return (event, listener) => {
-                    console.log(`[off] ${event}`, listener.toString());
+                    log.debug("off", { event, listener: listener.toString() });
                     return original.call(target, event, listener);
                 };
             }

package/dist/index.d.ts

@@ -1,2 +1,14 @@
 /// <reference path="global.d.ts" />
-export {};
+export { installShutdownHandlers } from "./installShutdownHandlers.js";
+export { log } from "./log.js";
+export type { LogFields, Logger, LogLevel } from "./log.js";
+export { createLogger } from "./createLogger.js";
+export { getRequestContext, runWithRequestContext, type RequestContext, } from "./requestContext.js";
+/**
+ * Для тестов: останавливает плагины, снимает обработчики сигналов и удаляет
+ * глобальный quark, чтобы следующий импорт core собрал его заново. Живёт
+ * здесь, а не в отдельном файле: сбрасывает состояние этого модуля (очередь
+ * регистраций, loaded). Модули плагинов кэшируются ESM — после сброса их
+ * нужно импортировать заново (vi.resetModules() + динамический import).
+ */
+export declare function resetQuark(): Promise<void>;

package/dist/index.js

@@ -1,5 +1,10 @@
 import atom from "@quark-fw/atom";
 import { createTypedEventEmitter } from "./ee/createTypedEventEmitter.js";
+import { installShutdownHandlers } from "./installShutdownHandlers.js";
+export { installShutdownHandlers } from "./installShutdownHandlers.js";
+export { log } from "./log.js";
+export { createLogger } from "./createLogger.js";
+export { getRequestContext, runWithRequestContext, } from "./requestContext.js";
 // создаём emitter
 const eeAtom = atom("ee", createTypedEventEmitter());
 const loaded = new Set();
@@ -42,6 +47,32 @@ const register = async (plugin) => {
     quark.plugins.push(plugin);
     await plugin.onReady?.(quark);
 };
+// Остановка плагинов в обратном порядке регистрации. Ошибка одного плагина
+// не прерывает остальных: иначе упавший onDestroy оставлял живыми воркеры
+// threads и соединение с Redis, и процесс добивал SIGKILL.
+const runDestroy = async () => {
+    const errors = [];
+    for (const plugin of [...quark.plugins].reverse()) {
+        try {
+            await plugin.onDestroy?.(quark);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    quark.plugins.length = 0;
+    loaded.clear();
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length)
+        throw new AggregateError(errors, "quark.destroy");
+};
+// Повторный destroy во время идущего возвращает тот же promise: воркер
+// threads получает quark:shutdown по IPC и SIGTERM от родителя, оператор
+// может нажать Ctrl+C дважды — onDestroy плагинов должен отработать один раз.
+let destroying;
+const created = !global.quark;
+let uninstallShutdown;
 // создаём глобальный quark
 global.quark =
     global.quark ||
@@ -57,15 +88,37 @@ global.quark =
             // дождаться завершения всех уже поставленных в очередь регистраций —
             // нужно модулям приложения, выполняющимся конкурентно с плагинами
             ready: () => registrationQueue,
-            destroy: async () => {
-                // в обратном порядке регистрации
-                for (const plugin of [...quark.plugins].reverse()) {
-                    await plugin.onDestroy?.(quark);
+            destroy: () => {
+                if (!destroying) {
+                    destroying = runDestroy().finally(() => {
+                        destroying = undefined;
+                    });
                 }
-                quark.plugins.length = 0;
-                loaded.clear();
+                return destroying;
             },
             // Quark дополняется плагинами через declaration merging,
             // поэтому базовый объект заведомо неполон
         };
+// Обработчики сигналов ставит тот модуль, который создал quark: при
+// повторной загрузке core (другой specifier) второго набора быть не должно
+if (created) {
+    uninstallShutdown = installShutdownHandlers({
+        quark,
+        timeoutMs: Number(process.env.QUARK_SHUTDOWN_TIMEOUT_MS) || undefined,
+    });
+}
+/**
+ * Для тестов: останавливает плагины, снимает обработчики сигналов и удаляет
+ * глобальный quark, чтобы следующий импорт core собрал его заново. Живёт
+ * здесь, а не в отдельном файле: сбрасывает состояние этого модуля (очередь
+ * регистраций, loaded). Модули плагинов кэшируются ESM — после сброса их
+ * нужно импортировать заново (vi.resetModules() + динамический import).
+ */
+export async function resetQuark() {
+    await quark.destroy().catch(() => { });
+    uninstallShutdown?.();
+    uninstallShutdown = undefined;
+    registrationQueue = Promise.resolve();
+    delete global.quark;
+}
 quark.ee.value.emit("lifecycle:init", "app started");

package/dist/installShutdownHandlers.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from "./log.js";
+export type InstallShutdownHandlersArgs = {
+    quark: Pick<Quark, "destroy">;
+    /**
+     * Сколько ждать onDestroy плагинов, прежде чем выйти принудительно.
+     * Docker/Coolify шлют SIGKILL через 10 с после SIGTERM — укладываемся
+     * с запасом, иначе процесс убивают посреди записи.
+     */
+    timeoutMs?: number;
+    signals?: NodeJS.Signals[];
+    exit?: (code: number) => void;
+    log?: Pick<Logger, "info" | "error">;
+};
+/**
+ * Один обработчик сигналов на процесс: по SIGTERM/SIGINT останавливает
+ * плагины через quark.destroy() и выходит сам. Без него деплой убивал
+ * контейнер посреди cron-задачи или записи файла, а Ctrl+C в dev оставлял
+ * открытые соединения с Redis и базой.
+ *
+ * Возвращает функцию снятия обработчиков (нужна тестам).
+ */
+export declare function installShutdownHandlers({ quark, timeoutMs, signals, exit, log, }: InstallShutdownHandlersArgs): () => void;

package/dist/installShutdownHandlers.js

@@ -0,0 +1,45 @@
+import { log as rootLog } from "./log.js";
+/**
+ * Один обработчик сигналов на процесс: по SIGTERM/SIGINT останавливает
+ * плагины через quark.destroy() и выходит сам. Без него деплой убивал
+ * контейнер посреди cron-задачи или записи файла, а Ctrl+C в dev оставлял
+ * открытые соединения с Redis и базой.
+ *
+ * Возвращает функцию снятия обработчиков (нужна тестам).
+ */
+export function installShutdownHandlers({ quark, timeoutMs = 8_000, signals = ["SIGTERM", "SIGINT"], exit = (code) => process.exit(code), log = rootLog.child({ scope: "quark" }), }) {
+    let shuttingDown = false;
+    const onSignal = (signal) => {
+        // второй сигнал — оператор не хочет ждать плагины
+        if (shuttingDown) {
+            log.error("повторный сигнал — выходим немедленно", { signal });
+            exit(1);
+            return;
+        }
+        shuttingDown = true;
+        log.info("останавливаем плагины", { signal, timeoutMs });
+        // unref: таймер не должен сам держать процесс живым, если плагины
+        // остановились и event loop пуст
+        const timer = setTimeout(() => {
+            log.error("плагины не остановились — выходим принудительно", {
+                timeoutMs,
+            });
+            exit(1);
+        }, timeoutMs);
+        timer.unref();
+        quark.destroy().then(() => {
+            clearTimeout(timer);
+            exit(0);
+        }, (error) => {
+            clearTimeout(timer);
+            log.error("ошибка при остановке плагинов", { err: error });
+            exit(1);
+        });
+    };
+    for (const signal of signals)
+        process.on(signal, onSignal);
+    return () => {
+        for (const signal of signals)
+            process.off(signal, onSignal);
+    };
+}

package/dist/log.d.ts

@@ -0,0 +1,2 @@
+export type { LogFields, Logger, LogLevel } from "./createLogger.js";
+export declare const log: import("./createLogger.js").Logger;

package/dist/log.js

@@ -0,0 +1,13 @@
+import { createLogger, isLogLevel } from "./createLogger.js";
+// Один логгер на процесс, настраивается окружением:
+//   LOG_LEVEL  — debug | info | warn | error (по умолчанию info)
+//   LOG_FORMAT — json | pretty (по умолчанию json в production, иначе pretty)
+// Плагины берут свой scope через log.child({ scope: "cron" }).
+export const log = createLogger({
+    level: isLogLevel(process.env.LOG_LEVEL) ? process.env.LOG_LEVEL : "info",
+    format: process.env.LOG_FORMAT === "json" || process.env.LOG_FORMAT === "pretty"
+        ? process.env.LOG_FORMAT
+        : process.env.NODE_ENV === "production"
+            ? "json"
+            : "pretty",
+});

package/dist/requestContext.d.ts

@@ -0,0 +1,5 @@
+export type RequestContext = {
+    requestId: string;
+};
+export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+export declare function getRequestContext(): RequestContext | undefined;

package/dist/requestContext.js

@@ -0,0 +1,12 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+// Одно хранилище на процесс: обе функции — его стороны, поэтому живут
+// в одном модуле. Контекст открывает HTTP-middleware (plugin-react), а
+// читают его логгер и всё, что исполняется внутри запроса: процедуры tRPC,
+// SSR in-process, кэш.
+const storage = new AsyncLocalStorage();
+export function runWithRequestContext(context, fn) {
+    return storage.run(context, fn);
+}
+export function getRequestContext() {
+    return storage.getStore();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/core",
-	"version": "0.1.26",
+	"version": "0.1.27",
 	"description": "Core runtime of the Quark framework: global quark object, lifecycle and typed event emitter",
 	"type": "module",
 	"main": "dist/index.js",
@@ -19,7 +19,8 @@
 	],
 	"scripts": {
 		"dev": "tsx watch src/index.ts",
-		"build": "tsc -p tsconfig.build.json && node ../../scripts/postbuild.mjs"
+		"build": "node ../../node_modules/tsgo/bin/tsc -p tsconfig.build.json && node ../../scripts/postbuild.mjs",
+		"test": "vitest run"
 	},
 	"keywords": [
 		"quark"
@@ -30,7 +31,10 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/atom": "0.1.26",
-		"@quark-fw/plugin": "0.1.26"
+		"@quark-fw/atom": "0.1.27",
+		"@quark-fw/plugin": "0.1.27"
+	},
+	"devDependencies": {
+		"vitest": "^5.0.0"
 	}
 }