@application-kit/bootstrap 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @application-kit/bootstrap
 
+## 0.3.0
+
+### Minor Changes
+
+- c9f24d0: Процессы запускаются целиком из пакета, а переменные контракта чарта валидируются на старте:
+
+  - `webBootstrap(rootModule, options)` из `/web` читает `PORT` (по умолчанию 3000) и `TRUST_PROXY_HOPS` (по умолчанию 0), создаёт приложение через `createFastifyApplication`, слушает `0.0.0.0` и возвращает приложение;
+  - новый вход `/consumer`: `consumerBootstrap(rootModule, server)` читает `METRICS_PORT` (по умолчанию 3001), поднимает сервер `/metrics` и передаёт корневой модуль транспорту `server` (например `kafkaConsumerServer` из `@application-kit/kafka`) вместе с логгером `nestjs-pino`.
+
+  Значение, которое не является целым числом в допустимом диапазоне (`abc`, `-1`, `1.5`, порт больше 65535), роняет старт ошибкой `ClassValidationError` с именем переменной ещё до создания приложения. Раньше `Number('abc')` давал `NaN`, и доверенных прокси становилось молча ноль.
+
+  Для этих входов нужен peer `@libs-for-dev/nestjs-config-module` ^3.0.0 рядом с `class-transformer` и `class-validator`. Потребителю `createFastifyApplication` менять ничего не нужно.
+
 ## 0.2.4
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,8 @@
 # @application-kit/bootstrap
 
-Бутстрап процессов NestJS: web на Fastify с периметром и CLI на nestjs-console. Состав модулей, Swagger, метрики, порт и
-число прокси перед приложением знает приложение: пакет собирает процесс из его корневого модуля и опций.
+Бутстрап процессов NestJS: web на Fastify с периметром, consumer с сервером метрик и CLI на nestjs-console. Состав
+модулей, Swagger и хуки метрик знает приложение: пакет собирает процесс из его корневого модуля и опций. Порт, число
+прокси и порт метрик — переменные окружения контракта чарта; невалидное значение роняет старт.
 
 ## Установка
 
@@ -17,13 +18,38 @@ Peer-зависимости — `@nestjs/common`, `@nestjs/core`, `nestjs-pino`;
 
 | Вход | Для чего | Тянет |
 |------|----------|-------|
-| `@application-kit/bootstrap/web` | `createFastifyApplication` — web-процесс на Fastify | `@nestjs/platform-fastify`, `@fastify/cookie`, `class-validator`, `class-transformer`, `@opentelemetry/api` |
+| `@application-kit/bootstrap/web` | `webBootstrap`, `createFastifyApplication` — web-процесс на Fastify | `@nestjs/platform-fastify`, `@fastify/cookie`, `class-validator`, `class-transformer`, `@opentelemetry/api`, `@libs-for-dev/nestjs-config-module` |
+| `@application-kit/bootstrap/consumer` | `consumerBootstrap` — процесс-консьюмер без HTTP-слоя | `class-validator`, `class-transformer`, `@libs-for-dev/nestjs-config-module` |
 | `@application-kit/bootstrap/cli` | `cliBootstrap` — CLI-процесс | `nestjs-console` |
 
 Корневого входа нет: web-процессу `nestjs-console` не нужен, CLI — Fastify.
 
+## Окружение
+
+| Переменная | Процесс | По умолчанию | |
+|------------|---------|--------------|---|
+| `PORT` | web | `3000` | порт `listen` на `0.0.0.0` |
+| `TRUST_PROXY_HOPS` | web | `0` | сколько прокси перед приложением доверенные; `0` — только сокет |
+| `METRICS_PORT` | consumer | `3001` | порт отдельного сервера `/metrics` |
+
+Значение — целое не меньше 0 (порт — не больше 65535). Иное (`abc`, `1.5`, `-1`) — `ClassValidationError` с именем
+переменной до создания приложения: `Number('abc')` дал бы `NaN`, и доверенных прокси молча стало бы ноль.
+
 ## Web
 
+```ts
+import { webBootstrap } from '@application-kit/bootstrap/web'
+
+void webBootstrap(AppModule, {
+  configure: (app) => {
+    setupMetricsHooks(app)
+  },
+})
+```
+
+`webBootstrap` берёт порт и прокси из окружения, собирает приложение через `createFastifyApplication`, слушает и
+возвращает его. `createFastifyApplication` — для своего запуска, когда порт и прокси приходят не из окружения:
+
 ```ts
 import { createFastifyApplication } from '@application-kit/bootstrap/web'
 
@@ -56,6 +82,18 @@ await app.listen(port, '0.0.0.0')
 | `cookie` | `{}` | опции `@fastify/cookie`; `false` — плагин не регистрируется |
 | `configure` | — | `(app) => void`, зовётся после хука request-id, до интерцептора и пайпа |
 
+## Consumer
+
+```ts
+import { consumerBootstrap } from '@application-kit/bootstrap/consumer'
+import { kafkaConsumerServer } from '@application-kit/kafka'
+
+void consumerBootstrap(ConsumerModule, kafkaConsumerServer)
+```
+
+Сервер `/metrics` поднимается на `METRICS_PORT` со своим реестром метрик процесса, затем корневой модуль уходит
+транспорту вместе с логгером `nestjs-pino`. Транспорт передаёт приложение: от брокера пакет не зависит.
+
 ## CLI
 
 ```ts

package/dist/cjs/consumer/consumer-bootstrap.d.ts

@@ -0,0 +1,3 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+export type ConsumerServerType = (rootModule: DynamicModule | Type, loggerModule: Type) => Promise<void>;
+export declare const consumerBootstrap: (rootModule: Type, server: ConsumerServerType) => Promise<void>;

package/dist/cjs/consumer/consumer-bootstrap.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumerBootstrap = void 0;
+const metrics_1 = require("@application-kit/observability/metrics");
+const nestjs_config_module_1 = require("@libs-for-dev/nestjs-config-module");
+const nestjs_pino_1 = require("nestjs-pino");
+const node_process_1 = __importDefault(require("node:process"));
+const consumer_process_environment_js_1 = require("./consumer-process.environment.js");
+const consumerBootstrap = async (rootModule, server) => {
+    const environment = (0, nestjs_config_module_1.exposeObjectWithValidation)(node_process_1.default.env, consumer_process_environment_js_1.ConsumerProcessEnvironment);
+    (0, metrics_1.startMetricsServer)({ port: environment.METRICS_PORT, registry: new metrics_1.MetricsRegistry() });
+    await server(rootModule, nestjs_pino_1.Logger);
+};
+exports.consumerBootstrap = consumerBootstrap;

package/dist/cjs/consumer/consumer-process.environment.d.ts

@@ -0,0 +1,3 @@
+export declare class ConsumerProcessEnvironment {
+    METRICS_PORT: number;
+}

package/dist/cjs/consumer/consumer-process.environment.js

@@ -0,0 +1,27 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsumerProcessEnvironment = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const MAX_PORT = 65_535;
+class ConsumerProcessEnvironment {
+    METRICS_PORT = 3001;
+}
+exports.ConsumerProcessEnvironment = ConsumerProcessEnvironment;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Max)(MAX_PORT),
+    (0, class_validator_1.Min)(0),
+    (0, class_transformer_1.Type)(() => Number),
+    __metadata("design:type", Object)
+], ConsumerProcessEnvironment.prototype, "METRICS_PORT", void 0);

package/dist/cjs/consumer/index.d.ts

@@ -0,0 +1,2 @@
+export * from './consumer-bootstrap.js';
+export * from './consumer-process.environment.js';

package/dist/cjs/consumer/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./consumer-bootstrap.js"), exports);
+__exportStar(require("./consumer-process.environment.js"), exports);

package/dist/cjs/web/index.d.ts

@@ -1,2 +1,4 @@
 export * from './create-fastify-application.js';
 export * from './fastify-application-options.interface.js';
+export * from './web-bootstrap.js';
+export * from './web-process.environment.js';

package/dist/cjs/web/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./create-fastify-application.js"), exports);
 __exportStar(require("./fastify-application-options.interface.js"), exports);
+__exportStar(require("./web-bootstrap.js"), exports);
+__exportStar(require("./web-process.environment.js"), exports);

package/dist/cjs/web/web-bootstrap.d.ts

@@ -0,0 +1,4 @@
+import type { Type } from '@nestjs/common';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+import type { FastifyApplicationOptionsInterface } from './fastify-application-options.interface.js';
+export declare const webBootstrap: (rootModule: Type, options?: Omit<FastifyApplicationOptionsInterface, "trustProxyHops">) => Promise<NestFastifyApplication>;

package/dist/cjs/web/web-bootstrap.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webBootstrap = void 0;
+const nestjs_config_module_1 = require("@libs-for-dev/nestjs-config-module");
+const nestjs_pino_1 = require("nestjs-pino");
+const node_process_1 = __importDefault(require("node:process"));
+const create_fastify_application_js_1 = require("./create-fastify-application.js");
+const web_process_environment_js_1 = require("./web-process.environment.js");
+const LISTEN_HOST = '0.0.0.0';
+const webBootstrap = async (rootModule, options = {}) => {
+    const environment = (0, nestjs_config_module_1.exposeObjectWithValidation)(node_process_1.default.env, web_process_environment_js_1.WebProcessEnvironment);
+    const app = await (0, create_fastify_application_js_1.createFastifyApplication)(rootModule, { ...options, trustProxyHops: environment.TRUST_PROXY_HOPS });
+    await app.listen(environment.PORT, LISTEN_HOST);
+    app.get(nestjs_pino_1.Logger).log(`Application is running on port "${environment.PORT}"`);
+    return app;
+};
+exports.webBootstrap = webBootstrap;

package/dist/cjs/web/web-process.environment.d.ts

@@ -0,0 +1,4 @@
+export declare class WebProcessEnvironment {
+    PORT: number;
+    TRUST_PROXY_HOPS: number;
+}

package/dist/cjs/web/web-process.environment.js

@@ -0,0 +1,35 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebProcessEnvironment = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const MAX_PORT = 65_535;
+class WebProcessEnvironment {
+    PORT = 3000;
+    TRUST_PROXY_HOPS = 0;
+}
+exports.WebProcessEnvironment = WebProcessEnvironment;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Max)(MAX_PORT),
+    (0, class_validator_1.Min)(0),
+    (0, class_transformer_1.Type)(() => Number),
+    __metadata("design:type", Object)
+], WebProcessEnvironment.prototype, "PORT", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_transformer_1.Type)(() => Number),
+    __metadata("design:type", Object)
+], WebProcessEnvironment.prototype, "TRUST_PROXY_HOPS", void 0);

package/dist/esm/consumer/consumer-bootstrap.d.ts

@@ -0,0 +1,3 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+export type ConsumerServerType = (rootModule: DynamicModule | Type, loggerModule: Type) => Promise<void>;
+export declare const consumerBootstrap: (rootModule: Type, server: ConsumerServerType) => Promise<void>;

package/dist/esm/consumer/consumer-bootstrap.js

@@ -0,0 +1,10 @@
+import { MetricsRegistry, startMetricsServer } from '@application-kit/observability/metrics';
+import { exposeObjectWithValidation } from '@libs-for-dev/nestjs-config-module';
+import { Logger } from 'nestjs-pino';
+import process from 'node:process';
+import { ConsumerProcessEnvironment } from './consumer-process.environment.js';
+export const consumerBootstrap = async (rootModule, server) => {
+    const environment = exposeObjectWithValidation(process.env, ConsumerProcessEnvironment);
+    startMetricsServer({ port: environment.METRICS_PORT, registry: new MetricsRegistry() });
+    await server(rootModule, Logger);
+};

package/dist/esm/consumer/consumer-process.environment.d.ts

@@ -0,0 +1,3 @@
+export declare class ConsumerProcessEnvironment {
+    METRICS_PORT: number;
+}

package/dist/esm/consumer/consumer-process.environment.js

@@ -0,0 +1,23 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Expose, Type } from 'class-transformer';
+import { IsInt, Max, Min } from 'class-validator';
+const MAX_PORT = 65_535;
+export class ConsumerProcessEnvironment {
+    METRICS_PORT = 3001;
+}
+__decorate([
+    Expose(),
+    IsInt(),
+    Max(MAX_PORT),
+    Min(0),
+    Type(() => Number),
+    __metadata("design:type", Object)
+], ConsumerProcessEnvironment.prototype, "METRICS_PORT", void 0);

package/dist/esm/consumer/index.d.ts

@@ -0,0 +1,2 @@
+export * from './consumer-bootstrap.js';
+export * from './consumer-process.environment.js';

package/dist/esm/consumer/index.js

@@ -0,0 +1,2 @@
+export * from './consumer-bootstrap.js';
+export * from './consumer-process.environment.js';

package/dist/esm/web/index.d.ts

@@ -1,2 +1,4 @@
 export * from './create-fastify-application.js';
 export * from './fastify-application-options.interface.js';
+export * from './web-bootstrap.js';
+export * from './web-process.environment.js';

package/dist/esm/web/index.js

@@ -1,2 +1,4 @@
 export * from './create-fastify-application.js';
 export * from './fastify-application-options.interface.js';
+export * from './web-bootstrap.js';
+export * from './web-process.environment.js';

package/dist/esm/web/web-bootstrap.d.ts

@@ -0,0 +1,4 @@
+import type { Type } from '@nestjs/common';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+import type { FastifyApplicationOptionsInterface } from './fastify-application-options.interface.js';
+export declare const webBootstrap: (rootModule: Type, options?: Omit<FastifyApplicationOptionsInterface, "trustProxyHops">) => Promise<NestFastifyApplication>;

package/dist/esm/web/web-bootstrap.js

@@ -0,0 +1,13 @@
+import { exposeObjectWithValidation } from '@libs-for-dev/nestjs-config-module';
+import { Logger } from 'nestjs-pino';
+import process from 'node:process';
+import { createFastifyApplication } from './create-fastify-application.js';
+import { WebProcessEnvironment } from './web-process.environment.js';
+const LISTEN_HOST = '0.0.0.0';
+export const webBootstrap = async (rootModule, options = {}) => {
+    const environment = exposeObjectWithValidation(process.env, WebProcessEnvironment);
+    const app = await createFastifyApplication(rootModule, { ...options, trustProxyHops: environment.TRUST_PROXY_HOPS });
+    await app.listen(environment.PORT, LISTEN_HOST);
+    app.get(Logger).log(`Application is running on port "${environment.PORT}"`);
+    return app;
+};

package/dist/esm/web/web-process.environment.d.ts

@@ -0,0 +1,4 @@
+export declare class WebProcessEnvironment {
+    PORT: number;
+    TRUST_PROXY_HOPS: number;
+}

package/dist/esm/web/web-process.environment.js

@@ -0,0 +1,31 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Expose, Type } from 'class-transformer';
+import { IsInt, Max, Min } from 'class-validator';
+const MAX_PORT = 65_535;
+export class WebProcessEnvironment {
+    PORT = 3000;
+    TRUST_PROXY_HOPS = 0;
+}
+__decorate([
+    Expose(),
+    IsInt(),
+    Max(MAX_PORT),
+    Min(0),
+    Type(() => Number),
+    __metadata("design:type", Object)
+], WebProcessEnvironment.prototype, "PORT", void 0);
+__decorate([
+    Expose(),
+    IsInt(),
+    Min(0),
+    Type(() => Number),
+    __metadata("design:type", Object)
+], WebProcessEnvironment.prototype, "TRUST_PROXY_HOPS", void 0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@application-kit/bootstrap",
-  "version": "0.2.4",
-  "description": "Бутстрап процессов NestJS: web на Fastify с периметром (доверенные прокси по хопам, request-id в каждом ответе, cookie, ValidationPipe с плоским списком ошибок, graceful shutdown) и CLI на nestjs-console с логгером pino",
+  "version": "0.3.0",
+  "description": "Бутстрап процессов NestJS: web на Fastify с периметром (доверенные прокси по хопам, request-id в каждом ответе, cookie, ValidationPipe с плоским списком ошибок, graceful shutdown), consumer с сервером метрик, CLI на nestjs-console с логгером pino; порты и прокси — из валидированного окружения",
   "keywords": [
     "bootstrap",
     "fastify",
@@ -32,6 +32,16 @@
         "default": "./dist/cjs/cli/index.js"
       }
     },
+    "./consumer": {
+      "import": {
+        "types": "./dist/esm/consumer/index.d.ts",
+        "default": "./dist/esm/consumer/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/consumer/index.d.ts",
+        "default": "./dist/cjs/consumer/index.js"
+      }
+    },
     "./package.json": "./package.json",
     "./web": {
       "import": {
@@ -51,7 +61,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cli && node ../../scripts/barrels.mjs create ./src/web && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cli && node ../../scripts/barrels.mjs create ./src/consumer && node ../../scripts/barrels.mjs create ./src/web && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
     "lint:tsc": "tsc --noEmit --pretty --project .",
     "test:mutation": "stryker run",
     "test:unit": "vitest run"
@@ -61,6 +71,7 @@
   },
   "devDependencies": {
     "@fastify/cookie": "^11.1.3",
+    "@libs-for-dev/nestjs-config-module": "3.0.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",
     "@nestjs/platform-fastify": "^11.2.7",
@@ -81,6 +92,7 @@
   },
   "peerDependencies": {
     "@fastify/cookie": "^11.0.0",
+    "@libs-for-dev/nestjs-config-module": "^3.0.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-fastify": "^11.0.0",
@@ -94,6 +106,9 @@
     "@fastify/cookie": {
       "optional": true
     },
+    "@libs-for-dev/nestjs-config-module": {
+      "optional": true
+    },
     "@nestjs/platform-fastify": {
       "optional": true
     },