@ecdt/server-common 1.2.1 → 1.5.0

package/README.md

@@ -79,6 +79,54 @@ app.use(expressCors({ origins: [...], extraHeaders: ["X-Custom-Header"] }));
 app.use(expressCors({ origins: [...], headers: ["Content-Type"], methods: ["GET", "POST"] }));
 ```
 
+### `setupRedMetrics(app, options?)`
+
+Instrumenta o servidor com métricas **RED** (Rate, Errors, Duration) e expõe o endpoint `/metrics` no formato Prometheus, em uma linha. Todas as requisições passam a alimentar o histograma `http_request_duration_seconds{method, route, status_code}`.
+
+> Requer `prom-client` instalado no microsserviço (é uma `peerDependency`).
+
+| Opção | Tipo | Descrição |
+|---|---|---|
+| `serviceName` | `string` | Nome do MS; vira o label `service` em todas as métricas. Fallback: env `SERVICE_NAME` > `npm_package_name` |
+| `metricsPath` | `string` | Caminho do endpoint de métricas. Default: `/metrics` |
+| `buckets` | `number[]` | Buckets de latência (segundos). Default: `[0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]` |
+| `collectDefaultMetrics` | `boolean` | Coletar métricas default do Node (heap, event loop, GC...). Default: `true` |
+| `registry` | `Registry` | Registry alternativo do prom-client. Default: registry global |
+
+```js
+const express = require("express");
+const { setupRedMetrics } = require("@ecdt/server-common");
+
+const app = express();
+
+// ANTES de montar as rotas:
+setupRedMetrics(app, { serviceName: "dev-mkt-busca" });
+
+app.get("/users/:id", (req, res) => res.json({ id: req.params.id }));
+
+app.listen(3000);
+```
+
+O label `route` usa o **template** da rota (`/users/:id`), nunca a URL crua — isso mantém a cardinalidade (e o custo de ingestão) sob controle.
+
+#### Consultas (PromQL) habilitadas
+
+```promql
+# Latência p95 por endpoint
+histogram_quantile(0.95, sum by (le, route)(rate(http_request_duration_seconds_bucket{service="dev-mkt-busca"}[5m])))
+
+# Taxa de requisições por segundo (RPS)
+sum(rate(http_request_duration_seconds_count{service="dev-mkt-busca"}[1m]))
+
+# Erros 5xx por segundo
+sum(rate(http_request_duration_seconds_count{service="dev-mkt-busca",status_code=~"5.."}[5m]))
+
+# Endpoints que mais geram erro
+topk(10, sum by (route)(rate(http_request_duration_seconds_count{service="dev-mkt-busca",status_code=~"5.."}[5m])))
+```
+
+Para wiring manual, a lib também exporta `redMetricsMiddleware(options?)` e `metricsHandler(registry?)`.
+
 ---
 
 ## Instalação
@@ -107,3 +155,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,8 +1,9 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.2.1",
+  "version": "1.5.0",
   "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"
   },
@@ -11,5 +12,8 @@
   "dependencies": {
     "body-parser": "^2.2.2",
     "cors": "^2.8.6"
+  },
+  "peerDependencies": {
+    "prom-client": "^15.0.0"
   }
 }

package/src/index.d.ts

@@ -1,41 +1,113 @@
-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[];
-    }
-
-    /**
-     * 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 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[];
-    }
-
-    /**
-     * 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;
-}
+import type { Express, RequestHandler } from 'express';
+import type { Server } from 'http';
+
+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[];
+}
+
+/**
+ * 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[];
+
+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;
+
+/** Middleware do express que alimenta o histograma `http_request_duration_seconds`. */
+export declare function redMetricsMiddleware(
+  options?: Pick<RedMetricsOptions, 'buckets' | 'registry'>
+): RequestHandler;
+
+/** Handler do endpoint de métricas (exposição no formato Prometheus). */
+export declare function metricsHandler(registry?: MetricsRegistry): RequestHandler;

package/src/index.js

@@ -2,6 +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");
 
 function expressCommonMiddlewares({ cookieName } = {}){
     return [bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}), devMktTokenSanitaze({ cookieName })];
@@ -10,4 +11,4 @@ function expressCommonMiddlewares({ cookieName } = {}){
 
 
 
-module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, redMetricsMiddleware, metricsHandler }

package/src/services/redMetricsService.js

@@ -0,0 +1,108 @@
+const client = require("prom-client");
+
+const METRIC_NAME = "http_request_duration_seconds";
+const DEFAULT_BUCKETS = [0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+/**
+ * get-or-create do histograma. Reaproveita a métrica se já registrada, evitando
+ * o erro "A metric with the name ... has already been registered" em import duplo
+ * ou múltiplas chamadas de setup.
+ * @param {import("prom-client").Registry} registry
+ * @param {number[]} buckets
+ */
+function getHistogram(registry, buckets) {
+    const existing = registry.getSingleMetric(METRIC_NAME);
+    if (existing) return existing;
+    return new client.Histogram({
+        name: METRIC_NAME,
+        help: "Duração das requisições HTTP, em segundos",
+        labelNames: ["method", "route", "status_code"],
+        buckets,
+        registers: [registry],
+    });
+}
+
+/**
+ * Extrai o TEMPLATE da rota (ex.: "/users/:id"), com o prefixo de routers aninhados.
+ * Nunca usa a URL crua — evita explosão de cardinalidade (e custo de ingestão no GMP).
+ */
+function routeTemplate(req) {
+    const path = req.route && req.route.path;
+    if (!path) return "unmatched";
+    const p = Array.isArray(path) ? path[0] : path;
+    return `${req.baseUrl || ""}${p}` || "unmatched";
+}
+
+/**
+ * Middleware do express 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
+ */
+function redMetricsMiddleware({ buckets, registry } = {}) {
+    const reg = registry || client.register;
+    const histogram = getHistogram(reg, buckets || DEFAULT_BUCKETS);
+    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),
+                status_code: String(res.statusCode),
+            })
+        );
+        next();
+    };
+}
+
+/**
+ * Handler do endpoint de métricas (exposição no formato Prometheus).
+ * @param {import("prom-client").Registry} [registry] - default: global do prom-client
+ * @returns handler do express
+ */
+function metricsHandler(registry = client.register) {
+    return async function (_req, res) {
+        res.set("Content-Type", registry.contentType);
+        res.end(await registry.metrics());
+    };
+}
+
+/**
+ * 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]
+ * @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)
+ */
+function setupRedMetrics(app, options = {}) {
+    const registry = options.registry || client.register;
+    const serviceName =
+        options.serviceName || process.env.SERVICE_NAME || process.env.npm_package_name;
+    if (serviceName) registry.setDefaultLabels({ service: serviceName });
+
+    // guard: collectDefaultMetrics chamado 2x joga "already registered".
+    if (
+        options.collectDefaultMetrics !== false &&
+        !registry.getSingleMetric("process_cpu_user_seconds_total")
+    ) {
+        client.collectDefaultMetrics({ register: registry });
+    }
+
+    app.use(redMetricsMiddleware({ buckets: options.buckets, registry }));
+    app.get(options.metricsPath || "/metrics", metricsHandler(registry));
+}
+
+module.exports = { setupRedMetrics, redMetricsMiddleware, metricsHandler };

package/src/services/shutdownService.js

@@ -1,9 +1,5 @@
 /**
  * Graceful shutdown padrão dos microsserviços da Econodata em Kubernetes.
- * Extraído do dev-mkt-busca: o preStop (20s) já tirou o pod do EndpointSlice
- * antes do SIGTERM, então aqui só drenamos as conexões em voo e encerramos o
- * processo antes do SIGKILL.
- *
  * @param {import('http').Server} server - servidor retornado por http.createServer(app).listen(...) ou app.listen(...)
  * @param {object} [options]
  * @param {() => (Promise<void>|void)} [options.onShutdown] - cleanup extra (fechar pools, Redis, etc.) executado após o server fechar
@@ -44,7 +40,7 @@ function setupGracefulShutdown(server, { onShutdown, failsafeTimeoutMs = 10 * 10
         // fecha conexões keep-alive ociosas, senão um keepAliveTimeout alto segura o close()
         server.closeIdleConnections();
 
-        // failsafe antes do SIGKILL (grace 40s − 20s de preStop)
+        // failsafe antes do SIGKILL
         setTimeout(() => {
             console.error('[shutdown] Timeout no graceful shutdown, forçando saída');
             process.exit(1);