@foxford/den 3.7.0 → 4.1.0

package/README.mdx

@@ -83,7 +83,7 @@ import { renderApp } from '@foxford/den/island'
 const { status, html, state, head, headHtml, redirect, assets } = await renderApp(app, {
   pathname: '/legal/general',
   search: '?from=footer',
-  context: { cookies, headers }, // реквизиты браузерного запроса
+  context: { cookies, headers, backendHeaders }, // браузерные данные и реквизиты бэкенда
   inputs: { 'host:User': user, 'host:Settings': settings }, // входные данные хоста по ключу token.description
 })
 ```
@@ -182,14 +182,32 @@ describeDocument(): DocumentContribution {
 }
 ```
 
+Для нескольких процессов одного приложения:
+
+```bash
+WORKERS=2 node build/server.mjs
+```
+
+По умолчанию `WORKERS=1`. Все воркеры слушают общий прикладной порт, primary держит
+один служебный порт с их суммарными метриками. `server.configure` выполняется в каждом
+воркере; память и контейнеры процессов отдельные. Значение задаётся каждому приложению
+и должно быть положительным целым. После обновления Den приложение нужно пересобрать,
+чтобы новая точка входа начала читать `WORKERS`. Переменная работает и в `den dev`,
+но локальное хранилище dev-трасс между воркерами не объединяется.
+
+При остановке Den дожидается активных запросов; зависшие воркеры принудительно
+завершаются через 10 секунд. Ошибка запуска или выход любого воркера завершает группу
+с ошибкой, чтобы внешний супервизор мог перезапустить приложение целиком.
+
 Рантайм вокруг дескриптора отдаёт три ручки:
 
 | Ручка                                  | Ответ                                       |
 | -------------------------------------- | ------------------------------------------- |
-| `QUERY /_render` + `{ url, inputs? }`  | `200` + ответ `renderApp` телом             |
+| `QUERY /_render` + `{ url, inputs?, backendHeaders? }`  | `200` + ответ `renderApp` телом             |
 | `GET /_render?url=<path+search>`       | то же без входных данных хоста              |
 | `GET /_routes`                         | `200` + массив regex-строк заявки на адреса |
-| `GET /_health`                         | `200 ok`                                    |
+| `GET /healthz`, `GET /livez` на втором порту | `200 ok`; в кластере `/livez` проверяет heartbeat воркеров |
+| `GET /metrics` на втором порту | Prometheus-метрики Node/process и HTTP |
 
 `QUERY` — безопасный метод с телом (RFC 9110): адрес и входные данные хоста едут JSON-ом,
 потому что заголовкам они не по размеру. `GET` остаётся для хоста, который входных данных
@@ -202,8 +220,42 @@ describeDocument(): DocumentContribution {
 рендер уходит как `reply.send(error)`: Fastify зовёт `onError` у потребителя с исходным
 исключением; тело — стандартный JSON ошибки Fastify.
 
-Браузерные заголовки рантайм читает только из `X-Forwarded-*` и кладёт в `RequestContextToken`;
-`Cookie` — обычным именем.
+Реквизиты запроса (`RequestContextToken`) отвечают на три разных вопроса: `headers` — что прислал
+браузер (только из `X-Forwarded-*`), `cookies` — чему равна отдельная кука, `backendHeaders` — что
+предъявлять бэкенду в каждом запросе. Последнее присылает хост телом (`backendHeaders`), по
+умолчанию это `Cookie` хопа, а навешивает на клиент `@foxford/den-sdk`.
+
+### Служебный порт
+
+Апп слушает основной и служебный порты в одном жизненном цикле: production
+`8080` и `9090`. Переопределение — `PORT`/`SERVICE_PORT`, интерфейсы — `HOST`/`OPS_HOST`.
+Для совместной разработки объявляются локальные `server.port` и `server.opsPort`;
+production server.mjs использует production-умолчания.
+
+`/healthz` — простой GET с `200`, `/livez` — проверка доступности, `/metrics` — экспорт полного
+штатного набора Node/process, дополнительных resourceUsage и HTTP-измерений.
+На основном порту служебные пути отвечают `404`.
+Метрики не зависят от DSN Sentry. Метод `close()` результата `await serveAppProcess(...)`
+закрывает всю группу; у прямого `serveApp` прежний `instance.close()` закрывает оба
+сервера одного процесса.
+
+Для занятости event loop используйте `nodejs_eventloop_utilization_ratio`:
+в кластере это максимум по воркерам, от 0 до 1. Сопоставляйте его с lag и временем
+ответа. Штатный `nodejs_eventloop_utilization_summary` суммирует quantile воркеров
+и для такого алерта не подходит. `/livez` остаётся зелёным, пока жив хотя бы один
+воркер; `/metrics` при неответившем воркере вернёт `503` через 5 секунд. Ошибки и
+длительность scrape тоже должны попадать в мониторинг.
+
+Для своего сервера доступен отдельный подпуть без Fastify:
+
+```ts
+import { getProcessMetrics, startOpsServer } from '@foxford/den/ops'
+
+getProcessMetrics().startRuntime('my-app')
+const ops = await startOpsServer({ port: 9090 })
+```
+
+Детали API и агрегация cluster — в SPEC.md → «Служебный сервер».
 
 ### Расширение снаружи: пример с Sentry
 
@@ -233,7 +285,6 @@ import * as Sentry from '@sentry/node'
 export default (instance) => {
   Sentry.setupFastifyErrorHandler(instance)
 
-  instance.get('/metrics', () => renderMetrics())
 }
 ```
 
@@ -320,6 +371,6 @@ export default defineAppConfig({
 | `@foxford/den/island`  | остров: жизненный цикл, шов `renderApp`, порт `ViewAdapter`, очередь клиентских падений (`reportIslandError`) |
 
 
-| `@foxford/den/serve`   | сетевой транспорт: `serveApp`, `appPlugin`                  |
+| `@foxford/den/serve`   | сетевой транспорт: `serveAppProcess`, `serveApp`, `appPlugin` |
 | `@foxford/den/build`   | конфиг приложения и сборка: `defineAppConfig`, `buildApp`   |
 | `@foxford/den/bin`     | точка входа команды `den`                                   |

package/adapter.d.cts

@@ -1,4 +1,4 @@
-export { R as RequestContext } from './types-BxMQ-VOd.cjs';
+export { R as RequestContext } from './types-Ccd5bmt1.cjs';
 import { Token } from '@foxford/ioc';
 
 /**

package/adapter.d.ts

@@ -1,4 +1,4 @@
-export { R as RequestContext } from './types-BxMQ-VOd.js';
+export { R as RequestContext } from './types-Ccd5bmt1.js';
 import { Token } from '@foxford/ioc';
 
 /**

package/bin/den.cjs

@@ -1,7 +1,7 @@
 "use strict";
 
 
-var _chunkP4J4M2WZcjs = require('../chunk-P4J4M2WZ.cjs');
+var _chunkIATA5QZ7cjs = require('../chunk-IATA5QZ7.cjs');
 require('../chunk-KQAB6C6Q.cjs');
 require('../chunk-A6ZPAM6Z.cjs');
 
@@ -70,11 +70,11 @@ function run(argv) {
     }
     const target = { base: options["base"], root: (_a = options["root"]) != null ? _a : process.cwd() };
     if (command === "build") {
-      yield _chunkP4J4M2WZcjs.buildApp.call(void 0, target);
+      yield _chunkIATA5QZ7cjs.buildApp.call(void 0, target);
       return;
     }
     if (command === "dev") {
-      yield _chunkP4J4M2WZcjs.devApp.call(void 0, target);
+      yield _chunkIATA5QZ7cjs.devApp.call(void 0, target);
       return;
     }
     fail(`\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043A\u043E\u043C\u0430\u043D\u0434\u0430 \xAB${command}\xBB`);

package/bin/den.js

@@ -1,7 +1,7 @@
 import {
   buildApp,
   devApp
-} from "../chunk-2GTQK2PZ.js";
+} from "../chunk-7FOG2MJV.js";
 import "../chunk-RG7ZV5BD.js";
 import "../chunk-TPBI6TOU.js";
 import {

package/builder/index.cjs

@@ -2,7 +2,7 @@
 
 
 
-var _chunkP4J4M2WZcjs = require('../chunk-P4J4M2WZ.cjs');
+var _chunkIATA5QZ7cjs = require('../chunk-IATA5QZ7.cjs');
 require('../chunk-KQAB6C6Q.cjs');
 require('../chunk-A6ZPAM6Z.cjs');
 require('../chunk-T5QVCXVB.cjs');
@@ -10,4 +10,4 @@ require('../chunk-T5QVCXVB.cjs');
 
 
 
-exports.buildApp = _chunkP4J4M2WZcjs.buildApp; exports.defineAppConfig = _chunkP4J4M2WZcjs.defineAppConfig; exports.devApp = _chunkP4J4M2WZcjs.devApp;
+exports.buildApp = _chunkIATA5QZ7cjs.buildApp; exports.defineAppConfig = _chunkIATA5QZ7cjs.defineAppConfig; exports.devApp = _chunkIATA5QZ7cjs.devApp;

package/builder/index.d.cts

@@ -54,13 +54,15 @@ interface AppServerConfig {
      */
     container?: (container: Container) => void;
     /**
-     * Порт процесса приложения.
+     * Прикладной порт процесса в разработке; production — PORT или 8080.
      *
      * `PORT` в окружении важнее: порт назначает тот, кто процесс поднимает, — в проде оркестратор.
-     * Объявление здесь — умолчание самого приложения, чтобы адрес не приходилось повторять в каждой
+     * Объявление здесь — локальное умолчание приложения, чтобы адрес не приходилось повторять в каждой
      * команде запуска и в префиксе артефактов.
      */
     port?: number;
+    /** Служебный порт в разработке; прод — SERVICE_PORT или 9090. */
+    opsPort?: number;
     /**
      * Расширение сетевого инстанса до начала прослушивания: Sentry, метрики, cors.
      *

package/builder/index.d.ts

@@ -54,13 +54,15 @@ interface AppServerConfig {
      */
     container?: (container: Container) => void;
     /**
-     * Порт процесса приложения.
+     * Прикладной порт процесса в разработке; production — PORT или 8080.
      *
      * `PORT` в окружении важнее: порт назначает тот, кто процесс поднимает, — в проде оркестратор.
-     * Объявление здесь — умолчание самого приложения, чтобы адрес не приходилось повторять в каждой
+     * Объявление здесь — локальное умолчание приложения, чтобы адрес не приходилось повторять в каждой
      * команде запуска и в префиксе артефактов.
      */
     port?: number;
+    /** Служебный порт в разработке; прод — SERVICE_PORT или 9090. */
+    opsPort?: number;
     /**
      * Расширение сетевого инстанса до начала прослушивания: Sentry, метрики, cors.
      *

package/builder/index.js

@@ -2,7 +2,7 @@ import {
   buildApp,
   defineAppConfig,
   devApp
-} from "../chunk-2GTQK2PZ.js";
+} from "../chunk-7FOG2MJV.js";
 import "../chunk-RG7ZV5BD.js";
 import "../chunk-TPBI6TOU.js";
 import "../chunk-6FNC3XMI.js";

package/{chunk-2GTQK2PZ.js → chunk-7FOG2MJV.js}

@@ -66,7 +66,7 @@ function collectAssets(outDir, base) {
 }
 
 // src/serve/port.ts
-var DEFAULT_PORT = 3e3;
+var DEFAULT_PORT = 8080;
 function resolvePort(declared) {
   var _a, _b;
   return Number((_b = (_a = process.env["PORT"]) != null ? _a : declared) != null ? _b : DEFAULT_PORT);
@@ -134,7 +134,7 @@ function generateServerProcess(configPath, base, mode) {
 ` : "";
   return `import { fileURLToPath } from 'node:url'
 
-import { loadAppEnv, serveApp } from '@foxford/den/serve'
+import { loadAppEnv, serveAppProcess } from '@foxford/den/serve'
 
 import app from ${JSON.stringify(VIRTUAL_SERVER_APP)}
 import config from ${JSON.stringify(configPath)}
@@ -142,10 +142,12 @@ import config from ${JSON.stringify(configPath)}
 // \u0423\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044F \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u2014 \u0434\u043E \u043F\u0435\u0440\u0432\u043E\u0433\u043E \u0447\u0442\u0435\u043D\u0438\u044F: \u043F\u043E\u0440\u0442 \u0438 \u0430\u0434\u0440\u0435\u0441\u0430 \u0447\u0438\u0442\u0430\u044E\u0442\u0441\u044F \u043D\u0438\u0436\u0435
 loadAppEnv(fileURLToPath(new URL('..', import.meta.url)))
 
-await serveApp(app, {
+await serveAppProcess(app, {
 ${assets}  configure: config.server?.configure,
   host: process.env.HOST,
-  port: Number(process.env.PORT ?? config.server?.port ?? ${String(DEFAULT_PORT)}),
+  ops: { host: process.env.OPS_HOST, port: Number(process.env.SERVICE_PORT ?? ${mode === "development" ? "config.server?.opsPort ?? 9090" : "9090"}) },
+  port: Number(process.env.PORT ?? ${mode === "development" ? "config.server?.port ?? " : ""}${String(DEFAULT_PORT)}),
+  workers: Number(process.env.WORKERS ?? 1),
 })
 `;
 }
@@ -201,7 +203,8 @@ function loadAppConfig(root) {
       configFile: false,
       logLevel: "silent",
       root,
-      server: { middlewareMode: true }
+      // Этот сервер только загружает конфиг; пересборкой в dev управляет watchSources.
+      server: { middlewareMode: true, watch: null }
     });
     try {
       const loaded = yield server.ssrLoadModule(configPath);
@@ -324,7 +327,7 @@ import { pathToFileURL } from "url";
 import os from "os";
 var TOOL = "den";
 var PAD = 11;
-var ENDPOINTS = ["/_render?url=<\u043F\u0443\u0442\u044C>", "/_routes", "/_health"];
+var ENDPOINTS = ["/_render?url=<\u043F\u0443\u0442\u044C>", "/_routes"];
 var OUTPUTS = ["build/client", "build/server", "build/server.mjs"];
 var SHORTCUTS = [
   { key: "r", title: "\u043F\u0435\u0440\u0435\u0441\u043E\u0431\u0440\u0430\u0442\u044C" },

package/chunk-A2CYL5LY.js

@@ -0,0 +1,240 @@
+import {
+  __async
+} from "./chunk-6FNC3XMI.js";
+
+// src/ops/index.ts
+import { createServer } from "http";
+import { ClusterRegistry } from "@prometheus-io/client";
+
+// src/ops/metrics.ts
+import { Counter, Gauge as Gauge2, Histogram, Registry } from "@prometheus-io/client";
+
+// src/ops/runtime.ts
+import cluster from "cluster";
+import { performance as performance2 } from "perf_hooks";
+import { collectDefaultMetrics, Gauge } from "@prometheus-io/client";
+function collectRuntime(registry, appName) {
+  registry.setDefaultLabels({ app: appName, process_role: cluster.isWorker ? "worker" : "main" });
+  collectDefaultMetrics({ register: registry });
+  let previousElu = performance2.eventLoopUtilization();
+  new Gauge({
+    aggregator: "max",
+    collect() {
+      const current = performance2.eventLoopUtilization();
+      this.set(performance2.eventLoopUtilization(current, previousElu).utilization);
+      previousElu = current;
+    },
+    help: "Event loop utilization since the last scrape; maximum across workers",
+    name: "nodejs_eventloop_utilization_ratio",
+    registers: [registry]
+  });
+  let previousCpu = process.cpuUsage();
+  let previousTime = performance2.now();
+  new Gauge({
+    aggregator: "sum",
+    collect() {
+      const currentCpu = process.cpuUsage();
+      const currentTime = performance2.now();
+      const elapsed = currentTime - previousTime;
+      this.set(
+        elapsed > 0 ? (currentCpu.user - previousCpu.user + currentCpu.system - previousCpu.system) / (elapsed * 1e3) : 0
+      );
+      previousCpu = currentCpu;
+      previousTime = currentTime;
+    },
+    help: "CPU time divided by elapsed wall time since the last scrape",
+    name: "process_cpu_utilization_ratio",
+    registers: [registry]
+  });
+  new Gauge({
+    collect() {
+      this.set(process.uptime());
+    },
+    help: "Process uptime in seconds",
+    name: "process_uptime_seconds",
+    registers: [registry]
+  });
+  new Gauge({
+    collect() {
+      this.set(process.memoryUsage().arrayBuffers);
+    },
+    help: "Memory used by ArrayBuffers in bytes",
+    name: "nodejs_arraybuffer_memory_bytes",
+    registers: [registry]
+  });
+  new Gauge({
+    aggregator: "max",
+    collect() {
+      this.set(process.resourceUsage().maxRSS * 1024);
+    },
+    help: "Maximum resident memory in bytes",
+    name: "process_max_resident_memory_bytes",
+    registers: [registry]
+  });
+  for (const [name, field] of [
+    ["minor_page_faults", "minorPageFault"],
+    ["major_page_faults", "majorPageFault"],
+    ["filesystem_reads", "fsRead"],
+    ["filesystem_writes", "fsWrite"],
+    ["voluntary_context_switches", "voluntaryContextSwitches"],
+    ["involuntary_context_switches", "involuntaryContextSwitches"]
+  ]) {
+    new Gauge({
+      collect() {
+        this.set(process.resourceUsage()[field]);
+      },
+      help: `Process ${name} since startup`,
+      name: `process_${name}_total`,
+      registers: [registry]
+    });
+  }
+}
+
+// src/ops/metrics.ts
+var HTTP_LABELS = ["method", "route", "status"];
+var SECOND_BUCKETS = [5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30];
+var ProcessMetrics = class {
+  constructor() {
+    this.registry = new Registry();
+    this.runtimeStarted = false;
+  }
+  counter(name, labelNames = []) {
+    const existing = this.registry.getSingleMetric(name);
+    if (existing) {
+      return existing;
+    }
+    return new Counter({ help: name, labelNames, name, registers: [this.registry] });
+  }
+  histogram(name, labelNames = []) {
+    const existing = this.registry.getSingleMetric(name);
+    if (existing) {
+      return existing;
+    }
+    return new Histogram({ buckets: SECOND_BUCKETS, help: name, labelNames, name, registers: [this.registry] });
+  }
+  /** Полный штатный набор Node/process-метрик клиента и дополнительные данные процесса. */
+  startRuntime(appName) {
+    if (this.runtimeStarted) {
+      return;
+    }
+    this.runtimeStarted = true;
+    collectRuntime(this.registry, appName);
+  }
+  /** HTTP-измерения с ограниченными метками маршрута; вызывается один раз на запрос. */
+  trackHttp(req, res, route) {
+    const active = this.registry.getSingleMetric("http_requests_in_flight");
+    const gauge = active != null ? active : new Gauge2({
+      help: "HTTP requests currently being served",
+      name: "http_requests_in_flight",
+      registers: [this.registry]
+    });
+    const started = performance.now();
+    gauge.inc();
+    let finished = false;
+    const finish = () => {
+      var _a;
+      if (finished) {
+        return;
+      }
+      finished = true;
+      gauge.dec();
+      const labels = { method: (_a = req.method) != null ? _a : "UNKNOWN", route: route(), status: String(res.statusCode) };
+      this.counter("http_requests_total", HTTP_LABELS).inc(labels);
+      this.histogram("http_request_duration_seconds", HTTP_LABELS).observe(labels, (performance.now() - started) / 1e3);
+    };
+    res.once("finish", finish);
+    res.once("close", finish);
+  }
+};
+var PROCESS_METRICS = /* @__PURE__ */ Symbol.for("@foxford/den/process-metrics");
+var storage = globalThis;
+function getProcessMetrics() {
+  var _a;
+  return (_a = storage[PROCESS_METRICS]) != null ? _a : storage[PROCESS_METRICS] = new ProcessMetrics();
+}
+
+// src/ops/index.ts
+var RESERVED_PATHS = /* @__PURE__ */ new Set(["/healthz", "/livez", "/metrics"]);
+function isOpsPath(url = "/") {
+  var _a;
+  return RESERVED_PATHS.has((_a = url.split("?")[0]) != null ? _a : "/");
+}
+function clusterMetrics(metrics = getProcessMetrics()) {
+  const aggregator = new ClusterRegistry();
+  ClusterRegistry.setRegistries(metrics.registry);
+  const lifecycle = aggregator;
+  return {
+    collect: () => aggregator.clusterMetrics(),
+    contentType: metrics.registry.contentType,
+    shutdown: () => lifecycle.shutdown()
+  };
+}
+function startOpsServer() {
+  return __async(this, arguments, function* (options = {}) {
+    var _a;
+    const metrics = (_a = options.metrics) != null ? _a : getProcessMetrics();
+    const server = createServer((req, res) => {
+      var _a2, _b, _c, _d;
+      const path = (_a2 = req.url) == null ? void 0 : _a2.split("?")[0];
+      res.setHeader("cache-control", "no-store");
+      if (req.method !== "GET" || !["/healthz", "/livez", "/metrics"].includes(path != null ? path : "")) {
+        res.writeHead(404).end();
+        return;
+      }
+      if (path !== "/metrics") {
+        res.writeHead(path === "/livez" && ((_b = options.isLive) == null ? void 0 : _b.call(options)) === false ? 503 : 200, {
+          "content-type": "text/plain; charset=utf-8"
+        }).end("ok");
+        return;
+      }
+      void ((_d = (_c = options.collect) == null ? void 0 : _c.call(options)) != null ? _d : metrics.registry.metrics()).then((body) => {
+        var _a3;
+        if (!res.destroyed) {
+          res.writeHead(200, { "content-type": (_a3 = options.contentType) != null ? _a3 : metrics.registry.contentType }).end(body);
+        }
+      }).catch(() => {
+        if (!res.destroyed) {
+          res.writeHead(503).end("metrics unavailable");
+        }
+      });
+    });
+    yield new Promise((resolve, reject) => {
+      var _a2, _b;
+      server.once("error", reject);
+      server.listen((_a2 = options.port) != null ? _a2 : 9090, (_b = options.host) != null ? _b : "0.0.0.0", () => {
+        server.removeListener("error", reject);
+        resolve();
+      });
+    });
+    return server;
+  });
+}
+function closeHttpServer(server, timeoutMs = 5e3) {
+  return __async(this, null, function* () {
+    if (!server.listening) {
+      return;
+    }
+    yield new Promise((resolve, reject) => {
+      const timer = setTimeout(() => server.closeAllConnections(), timeoutMs);
+      timer.unref();
+      server.close((error) => {
+        clearTimeout(timer);
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+      server.closeIdleConnections();
+    });
+  });
+}
+
+export {
+  ProcessMetrics,
+  getProcessMetrics,
+  isOpsPath,
+  clusterMetrics,
+  startOpsServer,
+  closeHttpServer
+};