@ecdt/server-common 1.5.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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.5.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

@@ -104,10 +104,34 @@ export interface RedMetricsOptions {
  */
 export declare function setupRedMetrics(app: Express, options?: RedMetricsOptions): void;
 
-/** Middleware do express que alimenta o histograma `http_request_duration_seconds`. */
+/**
+ * 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'>
+  options?: Pick<RedMetricsOptions, 'buckets' | 'registry'> & {
+    /**
+     * 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.
+     */
+    routeResolver?: (req: unknown) => string | undefined;
+  }
 ): RequestHandler;
 
 /** Handler do endpoint de métricas (exposição no formato Prometheus). */
 export declare function metricsHandler(registry?: MetricsRegistry): RequestHandler;
+
+/** 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/);
+    });
+});