@ecdt/server-common 1.4.0 → 1.5.1

package/README.md

@@ -127,6 +127,35 @@ topk(10, sum by (route)(rate(http_request_duration_seconds_count{service="dev-mk
 
 Para wiring manual, a lib também exporta `redMetricsMiddleware(options?)` e `metricsHandler(registry?)`.
 
+#### Servidor que não é express (Nitro/h3, fastify, http puro)
+
+`setupRedMetrics` precisa de um `app` do express. Fora dele, monte as três peças à mão:
+
+- `initRedMetrics(options?)` — label `service`, métricas default do Node e o histograma. Devolve `{ registry, histogram }`.
+- `redMetricsMiddleware({ routeResolver })` — o middleware `(req, res, next)`. Sem `req.route` (que é do express) o label `route` cai em `unmatched`, então informe um resolver. **Nunca use a URL crua**: cada id na rota vira uma série temporal nova e a métrica fica impagável.
+- `renderMetrics(registry?)` — `{ contentType, body }` para servir o endpoint.
+
+```js
+// Nitro: server/plugins/red-metrics.ts
+import { initRedMetrics, redMetricsMiddleware } from "@ecdt/server-common";
+
+initRedMetrics({ serviceName: "site-vue3" });
+
+// Nitro: server/middleware/01.red-metrics.ts
+export default fromNodeMiddleware(
+  redMetricsMiddleware({ routeResolver: (req) => templateDaRota(req.url) }),
+);
+
+// Nitro: server/routes/metrics.get.ts
+import { renderMetrics } from "@ecdt/server-common";
+
+export default defineEventHandler(async (event) => {
+  const { contentType, body } = await renderMetrics();
+  setResponseHeader(event, "content-type", contentType);
+  return body;
+});
+```
+
 ---
 
 ## Instalação
@@ -155,3 +184,36 @@ app.listen(3000);
 ```
 
 ---
+
+## TypeScript
+
+O pacote publica os tipos em `src/index.d.ts` (declarado em `types` no `package.json`), tipados com `express` e `http`. **Não é necessário declarar `declare module '@ecdt/server-common'` na aplicação** — se você tem um arquivo desses em `src/@types/`, pode apagar: uma declaração ambiente local sombreia os tipos do pacote e passa a mentir em silêncio se as assinaturas divergirem.
+
+```ts
+import express from "express";
+import http from "http";
+import { expressCommonMiddlewares, expressCors, setupRedMetrics, setupGracefulShutdown } from "@ecdt/server-common";
+
+const app = express();
+
+app.use(...expressCommonMiddlewares());              // RequestHandler[]
+app.use(expressCors({ econodataOrigins: true }));    // RequestHandler
+setupRedMetrics(app, { serviceName: "meu-ms" });
+
+const server = http.createServer(app);
+server.listen(3000);
+setupGracefulShutdown(server, { onShutdown: () => pool.end() });
+```
+
+As interfaces de options são exportadas para reuso: `ExpressCommonMiddlewaresOptions`, `ExpressCorsOptions` (e sua base `ExpressCorsOptionsBase`), `GracefulShutdownOptions`, `RedMetricsOptions` e `MetricsRegistry`.
+
+`ExpressCorsOptions` é uma união que exige `origins` e/ou `econodataOrigins: true` — sem nenhum dos dois o `expressCors` lança no boot, então o erro aparece já em compilação:
+
+```ts
+expressCors({ econodataOrigins: true });  // ok
+expressCors({ methods: ["GET"] });        // erro TS2345 — lançaria no boot
+```
+
+`prom-client` aparece nos tipos como a interface estrutural `MetricsRegistry`, e não como `import` do pacote — assim quem não usa métricas compila sem tê-lo instalado.
+
+---

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Conjunto de ferramentas e configurações comuns nos servidores da Econodata",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   },
   "author": "",
   "license": "ISC",

package/src/index.d.ts

@@ -1,75 +1,137 @@
-declare module '@ecdt/server-common' {
-    export interface ExpressCommonMiddlewaresOptions {
-        /**
-         * Nome(s) do cookie de sessão, em ordem de preferência.
-         * Quando omitido, o nome é resolvido por requisição a partir da origem (origin > referer > host):
-         * origens com subdomínio "hml" usam `hml-ecdt_token_site`, as demais usam `ecdt_token_site`.
-         */
-        cookieName?: string | string[];
-    }
+import type { Express, RequestHandler } from 'express';
+import type { Server } from 'http';
 
-    /**
-     * Aplica bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}) e devMktTokenSanitaze()
-     * no middleware do express.
-     *
-     * Uso: app.use(...expressCommonMiddlewares())
-     */
-    export function expressCommonMiddlewares(
-        options?: ExpressCommonMiddlewaresOptions
-    ): Array<(req: unknown, res: unknown, next: (err?: unknown) => void) => void>;
+export interface ExpressCommonMiddlewaresOptions {
+  /**
+   * Nome(s) do cookie de sessão, em ordem de preferência.
+   * Quando omitido, o nome é resolvido por requisição a partir da origem (origin > referer > host):
+   * origens com subdomínio "hml" usam `hml-ecdt_token_site`, as demais usam `ecdt_token_site`.
+   */
+  cookieName?: string | string[];
+}
 
-    export interface ExpressCorsOptions {
-        /** Origins permitidas (ex: ["https://app.econodata.com.br"]). Obrigatório se econodataOrigins não for true. */
-        origins?: string[];
-        /** Permite todas as origins https do domínio econodata.com.br (qualquer subdomínio). */
-        econodataOrigins?: boolean;
-        /** Headers adicionais além dos padrões (Authorization, Content-Type, X-Requested-With). */
-        extraHeaders?: string[];
-        /** Lista exata de headers permitidos — substitui os padrões. Não combinar com extraHeaders. */
-        headers?: string[];
-        /** Lista exata de métodos permitidos. Default: todos (GET, HEAD, PUT, PATCH, POST, DELETE, OPTIONS). */
-        methods?: string[];
-    }
+/**
+ * Aplica bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}) e
+ * devMktTokenSanitaze() no middleware do express.
+ *
+ * Uso: app.use(...expressCommonMiddlewares())
+ */
+export declare function expressCommonMiddlewares(
+  options?: ExpressCommonMiddlewaresOptions
+): RequestHandler[];
 
-    /**
-     * Cria o middleware de CORS padrão dos servidores Econodata.
-     * Credentials sempre habilitado; origins não listadas não recebem headers CORS.
-     *
-     * Uso: app.use(expressCors({ origins: ["https://app.econodata.com.br"] }))
-     */
-    export function expressCors(options: ExpressCorsOptions): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+export interface ExpressCorsOptionsBase {
+  /** Origins permitidas (ex: ["https://app.econodata.com.br"]). */
+  origins?: string[];
+  /** Permite todas as origins https do domínio econodata.com.br (qualquer subdomínio). */
+  econodataOrigins?: boolean;
+  /** Headers adicionais além dos padrões (Authorization, Content-Type, X-Requested-With). */
+  extraHeaders?: string[];
+  /** Lista exata de headers permitidos — substitui os padrões. Não combinar com extraHeaders. */
+  headers?: string[];
+  /** Lista exata de métodos permitidos. Default: todos (GET, HEAD, PUT, PATCH, POST, DELETE, OPTIONS). */
+  methods?: string[];
+}
+
+/**
+ * Exige `origins` e/ou `econodataOrigins: true`: sem nenhum dos dois o expressCors lança no boot,
+ * então a união recusa em compilação o que o runtime já recusa.
+ */
+export type ExpressCorsOptions =
+  | (ExpressCorsOptionsBase & { origins: string[] })
+  | (ExpressCorsOptionsBase & { econodataOrigins: true });
+
+/**
+ * Cria o middleware de CORS padrão dos servidores Econodata.
+ * Credentials sempre habilitado; origins não listadas não recebem headers CORS.
+ *
+ * Uso: app.use(expressCors({ origins: ["https://app.econodata.com.br"] }))
+ */
+export declare function expressCors(options: ExpressCorsOptions): RequestHandler;
+
+export interface GracefulShutdownOptions {
+  /** Cleanup extra (fechar pools, Redis, etc.) executado após o server fechar. */
+  onShutdown?: () => void | Promise<void>;
+  /** Tempo máximo do graceful antes de forçar a saída. Default: 10000 (grace de 40s − 20s de preStop). */
+  failsafeTimeoutMs?: number;
+}
+
+/**
+ * Registra o graceful shutdown padrão dos microsserviços em Kubernetes: em SIGTERM/SIGINT fecha o
+ * server, drena as conexões em voo, roda o onShutdown e encerra o processo.
+ *
+ * Uso: setupGracefulShutdown(server, { onShutdown: () => pool.end() })
+ */
+export declare function setupGracefulShutdown(
+  server: Server,
+  options?: GracefulShutdownOptions
+): void;
+
+/**
+ * Registry do prom-client, descrito estruturalmente para não acoplar a resolução destes tipos ao
+ * pacote: quem não usa métricas continua compilando sem `prom-client` instalado.
+ */
+export interface MetricsRegistry {
+  contentType: string;
+  metrics(): Promise<string>;
+  setDefaultLabels(labels: Record<string, string>): void;
+  getSingleMetric(name: string): unknown;
+}
+
+export interface RedMetricsOptions {
+  /** Nome do microsserviço. Vira o label `service` em todas as métricas. Fallback: env SERVICE_NAME > npm_package_name. */
+  serviceName?: string;
+  /** Caminho do endpoint de métricas. Default: '/metrics'. */
+  metricsPath?: string;
+  /** Buckets do histograma de latência, em segundos. */
+  buckets?: number[];
+  /** Coletar métricas default do Node (heap, event loop, GC...). Default: true. */
+  collectDefaultMetrics?: boolean;
+  /** Registry alternativo do prom-client. Default: registry global. */
+  registry?: MetricsRegistry;
+}
+
+/**
+ * Configura as métricas RED (Rate, Errors, Duration) no app express: registra o middleware de
+ * medição (antes das rotas) e o endpoint /metrics.
+ *
+ * Alimenta o histograma `http_request_duration_seconds{method,route,status_code}`, que habilita
+ * latência por endpoint, latência total, RPS, erros e top endpoints com erro.
+ *
+ * Requer `prom-client` instalado no microsserviço (peerDependency).
+ *
+ * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
+ */
+export declare function setupRedMetrics(app: Express, options?: RedMetricsOptions): void;
 
-    export interface RedMetricsOptions {
-        /** Nome do microsserviço. Vira o label `service` em todas as métricas. Fallback: env SERVICE_NAME > npm_package_name. */
-        serviceName?: string;
-        /** Caminho do endpoint de métricas. Default: '/metrics'. */
-        metricsPath?: string;
-        /** Buckets do histograma de latência, em segundos. */
-        buckets?: number[];
-        /** Coletar métricas default do Node (heap, event loop, GC...). Default: true. */
-        collectDefaultMetrics?: boolean;
-        /** Registry alternativo do prom-client. Default: registry global. */
-        registry?: unknown;
-    }
+/**
+ * Registra o label `service`, as métricas default do Node e o histograma RED, sem depender de
+ * framework. Use quando o servidor não é express (ex.: Nitro/h3) e você mesmo vai montar o
+ * middleware e a rota de métricas.
+ */
+export declare function initRedMetrics(
+  options?: Omit<RedMetricsOptions, 'metricsPath'>
+): { registry: MetricsRegistry; histogram: unknown };
 
+/**
+ * Middleware `(req, res, next)` que alimenta o histograma `http_request_duration_seconds`.
+ * Compatível com express e com adaptadores de middleware de Node (ex.: `fromNodeMiddleware` do h3).
+ */
+export declare function redMetricsMiddleware(
+  options?: Pick<RedMetricsOptions, 'buckets' | 'registry'> & {
     /**
-     * Configura as métricas RED (Rate, Errors, Duration) no app express: registra o
-     * middleware de medição (antes das rotas) e o endpoint /metrics.
-     *
-     * Alimenta o histograma `http_request_duration_seconds{method,route,status_code}`,
-     * que habilita latência por endpoint, latência total, RPS, erros e top endpoints com erro.
-     *
-     * Requer `prom-client` instalado no microsserviço (peerDependency).
-     *
-     * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
+     * Resolve o label `route`. Default: template do express (`req.route.path`). Framework sem
+     * `req.route` precisa informar o seu, senão todo request cai em `unmatched` — e nunca use a
+     * URL crua, que explode a cardinalidade da métrica.
      */
-    export function setupRedMetrics(app: unknown, options?: RedMetricsOptions): void;
+    routeResolver?: (req: unknown) => string | undefined;
+  }
+): RequestHandler;
 
-    /** Middleware do express que alimenta o histograma `http_request_duration_seconds`. */
-    export function redMetricsMiddleware(
-        options?: Pick<RedMetricsOptions, "buckets" | "registry">
-    ): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+/** Handler do endpoint de métricas (exposição no formato Prometheus). */
+export declare function metricsHandler(registry?: MetricsRegistry): RequestHandler;
 
-    /** Handler do endpoint de métricas (exposição no formato Prometheus). */
-    export function metricsHandler(registry?: unknown): (req: unknown, res: unknown) => void;
-}
+/** Content-type e corpo das métricas, para servir fora do express. */
+export declare function renderMetrics(
+  registry?: MetricsRegistry
+): Promise<{ contentType: string; body: string }>;

package/src/index.js

@@ -2,7 +2,7 @@ const bodyParser = require("body-parser");
 const { devMktTokenSanitaze } = require("./services/tokenService.js");
 const { expressCors } = require("./services/corsService.js");
 const { setupGracefulShutdown } = require("./services/shutdownService.js");
-const { setupRedMetrics, redMetricsMiddleware, metricsHandler } = require("./services/redMetricsService.js");
+const { setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics } = require("./services/redMetricsService.js");
 
 function expressCommonMiddlewares({ cookieName } = {}){
     return [bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}), devMktTokenSanitaze({ cookieName })];
@@ -11,4 +11,4 @@ function expressCommonMiddlewares({ cookieName } = {}){
 
 
 
-module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, redMetricsMiddleware, metricsHandler }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics }

package/src/services/redMetricsService.js

@@ -34,24 +34,28 @@ function routeTemplate(req) {
 }
 
 /**
- * Middleware do express que mede cada requisição e alimenta o histograma RED
+ * Middleware (req, res, next) que mede cada requisição e alimenta o histograma RED
  * (http_request_duration_seconds) com os labels method, route e status_code.
  *
  * @param {object} [options]
  * @param {number[]} [options.buckets] - buckets de latência em segundos
  * @param {import("prom-client").Registry} [options.registry] - registry (default: global do prom-client)
- * @returns middleware do express
+ * @param {(req: object) => string} [options.routeResolver] - resolve o label `route`. Default: template
+ *        do express (`req.route.path`). Framework sem `req.route` (ex.: h3/Nitro) precisa informar o
+ *        seu, senão todo request cai em "unmatched".
+ * @returns middleware compatível com express e com adaptadores de middleware de Node
  */
-function redMetricsMiddleware({ buckets, registry } = {}) {
+function redMetricsMiddleware({ buckets, registry, routeResolver } = {}) {
     const reg = registry || client.register;
     const histogram = getHistogram(reg, buckets || DEFAULT_BUCKETS);
+    const resolveRoute = routeResolver || routeTemplate;
     return function (req, res, next) {
         const stop = histogram.startTimer();
         // 'finish' dispara após a rota resolver -> req.route já está preenchido aqui.
         res.on("finish", () =>
             stop({
                 method: req.method,
-                route: routeTemplate(req),
+                route: resolveRoute(req) || "unmatched",
                 status_code: String(res.statusCode),
             })
         );
@@ -59,6 +63,16 @@ function redMetricsMiddleware({ buckets, registry } = {}) {
     };
 }
 
+/**
+ * Exposição das métricas sem depender de framework: devolve o content-type e o corpo no
+ * formato Prometheus. Use quando o servidor não é express (ex.: rota do Nitro).
+ * @param {import("prom-client").Registry} [registry] - default: global do prom-client
+ * @returns {Promise<{ contentType: string, body: string }>}
+ */
+async function renderMetrics(registry = client.register) {
+    return { contentType: registry.contentType, body: await registry.metrics() };
+}
+
 /**
  * Handler do endpoint de métricas (exposição no formato Prometheus).
  * @param {import("prom-client").Registry} [registry] - default: global do prom-client
@@ -66,28 +80,26 @@ function redMetricsMiddleware({ buckets, registry } = {}) {
  */
 function metricsHandler(registry = client.register) {
     return async function (_req, res) {
-        res.set("Content-Type", registry.contentType);
-        res.end(await registry.metrics());
+        const { contentType, body } = await renderMetrics(registry);
+        res.set("Content-Type", contentType);
+        res.end(body);
     };
 }
 
 /**
- * Configura as métricas RED no app express em uma linha. Registra o middleware
- * (aplique ANTES das rotas) e o endpoint /metrics.
+ * Registra o label `service`, as métricas default do Node e o histograma RED — sem tocar em
+ * framework nenhum. É a parte do setup que serve para express e para qualquer outro servidor.
  *
- * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
- *
- * @param {object} app - instância do express
  * @param {object} [options]
  * @param {string} [options.serviceName] - nome do MS; vira o label `service` em todas as métricas.
  *        Fallback: env SERVICE_NAME > npm_package_name.
- * @param {string} [options.metricsPath] - caminho do endpoint de métricas (default: "/metrics")
  * @param {number[]} [options.buckets] - buckets de latência em segundos
  * @param {boolean} [options.collectDefaultMetrics] - coletar métricas default do Node
  *        (heap, event loop, GC...). Default: true.
  * @param {import("prom-client").Registry} [options.registry] - registry alternativo (default: global)
+ * @returns {{ registry: import("prom-client").Registry, histogram: object }}
  */
-function setupRedMetrics(app, options = {}) {
+function initRedMetrics(options = {}) {
     const registry = options.registry || client.register;
     const serviceName =
         options.serviceName || process.env.SERVICE_NAME || process.env.npm_package_name;
@@ -101,8 +113,24 @@ function setupRedMetrics(app, options = {}) {
         client.collectDefaultMetrics({ register: registry });
     }
 
+    return { registry, histogram: getHistogram(registry, options.buckets || DEFAULT_BUCKETS) };
+}
+
+/**
+ * Configura as métricas RED no app express em uma linha. Registra o middleware
+ * (aplique ANTES das rotas) e o endpoint /metrics.
+ *
+ * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
+ *
+ * @param {object} app - instância do express
+ * @param {object} [options] - ver initRedMetrics, mais:
+ * @param {string} [options.metricsPath] - caminho do endpoint de métricas (default: "/metrics")
+ */
+function setupRedMetrics(app, options = {}) {
+    const { registry } = initRedMetrics(options);
+
     app.use(redMetricsMiddleware({ buckets: options.buckets, registry }));
     app.get(options.metricsPath || "/metrics", metricsHandler(registry));
 }
 
-module.exports = { setupRedMetrics, redMetricsMiddleware, metricsHandler };
+module.exports = { setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics };

package/test/redMetricsService.test.js

@@ -0,0 +1,97 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { EventEmitter } = require('node:events');
+const client = require('prom-client');
+
+const {
+    initRedMetrics,
+    redMetricsMiddleware,
+    renderMetrics,
+} = require('../src/services/redMetricsService.js');
+
+const registryLimpo = () => new client.Registry();
+
+const medir = (registry, req, options = {}) => {
+    const middleware = redMetricsMiddleware({ registry, ...options });
+    const res = Object.assign(new EventEmitter(), { statusCode: 200 });
+    let chamouNext = false;
+
+    middleware(req, res, () => {
+        chamouNext = true;
+    });
+    res.emit('finish');
+
+    return { chamouNext };
+};
+
+describe('redMetricsMiddleware', () => {
+    test('usa o routeResolver quando o framework não tem req.route', async () => {
+        const registry = registryLimpo();
+
+        const { chamouNext } = medir(registry, { method: 'GET', url: '/consulta-empresa/123-x' }, {
+            routeResolver: () => '/consulta-empresa/:slug',
+        });
+
+        assert.equal(chamouNext, true);
+        const texto = await registry.metrics();
+        assert.match(texto, /route="\/consulta-empresa\/:slug"/);
+        assert.match(texto, /method="GET"/);
+        assert.match(texto, /status_code="200"/);
+    });
+
+    test('sem req.route e sem resolver o label cai em unmatched', async () => {
+        const registry = registryLimpo();
+
+        medir(registry, { method: 'POST', url: '/qualquer/coisa' });
+
+        assert.match(await registry.metrics(), /route="unmatched"/);
+    });
+
+    test('resolver que devolve vazio também cai em unmatched', async () => {
+        const registry = registryLimpo();
+
+        medir(registry, { method: 'GET', url: '/x' }, { routeResolver: () => undefined });
+
+        assert.match(await registry.metrics(), /route="unmatched"/);
+    });
+
+    test('template do express continua sendo o default', async () => {
+        const registry = registryLimpo();
+
+        medir(registry, { method: 'GET', baseUrl: '/api', route: { path: '/users/:id' } });
+
+        assert.match(await registry.metrics(), /route="\/api\/users\/:id"/);
+    });
+});
+
+describe('initRedMetrics', () => {
+    test('aplica o label service e devolve registry e histograma', async () => {
+        const registry = registryLimpo();
+
+        const { histogram } = initRedMetrics({ registry, serviceName: 'site-vue3', collectDefaultMetrics: false });
+
+        assert.ok(histogram);
+        histogram.observe({ method: 'GET', route: '/', status_code: '200' }, 0.1);
+        assert.match(await registry.metrics(), /service="site-vue3"/);
+    });
+
+    test('chamar duas vezes não duplica métrica', () => {
+        const registry = registryLimpo();
+
+        initRedMetrics({ registry, collectDefaultMetrics: false });
+
+        assert.doesNotThrow(() => initRedMetrics({ registry, collectDefaultMetrics: false }));
+    });
+});
+
+describe('renderMetrics', () => {
+    test('devolve content-type e corpo no formato Prometheus', async () => {
+        const registry = registryLimpo();
+        initRedMetrics({ registry, serviceName: 'site-vue3', collectDefaultMetrics: false });
+
+        const { contentType, body } = await renderMetrics(registry);
+
+        assert.match(contentType, /text\/plain/);
+        assert.match(body, /http_request_duration_seconds/);
+    });
+});