@ecdt/server-common 1.5.0 → 1.6.0

package/README.md

@@ -127,6 +127,68 @@ 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;
+});
+```
+
+---
+
+### `publicarEvento(options)`
+
+Envia um evento para o coletor de eventos configurado, sem bloquear o fluxo que o gerou.
+
+```js
+const { publicarEvento } = require('@ecdt/server-common');
+
+publicarEvento({
+  tipo: 'meu_evento',
+  autorizacao: req.headers.authorization,
+  payload: { campo: 'valor' },
+});
+```
+
+| Opção | Default | Descrição |
+|---|---|---|
+| `tipo` | — | Nome do evento, em `snake_case` |
+| `autorizacao` | — | Header `Authorization` da requisição que originou o evento |
+| `payload` | `{}` | Campos do evento |
+| `url` | `process.env.MOTOR_EVENTOS_URL` | URL completa do coletor; a função não monta caminho nenhum |
+| `timeoutMs` | `2000` | Aborta a requisição |
+| `aoFalhar` | `console.error` | Recebe a mensagem quando a publicação não acontece |
+
+A identidade sai do token, nunca do corpo: o coletor resolve o usuário a partir do `Authorization`
+repassado. Sem `tipo` ou sem `autorizacao` a função não faz nada; sem `url` ela ainda registra um
+`console.warn`, porque url ausente é configuração faltando e não um evento que não se aplica.
+
+**A função nunca lança e nunca devolve promise.** O evento é secundário ao fluxo que o gerou —
+falha de publicação não pode virar erro de quem chamou, e o retorno `undefined` impede que alguém
+consiga dar `await` e acoplar a latência do request ao motor.
+
 ---
 
 ## Instalação

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.5.0",
+  "version": "1.6.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"
+    "test": "node --test"
   },
   "author": "",
   "license": "ISC",

package/src/index.d.ts

@@ -104,10 +104,45 @@ 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 }>;
+
+export interface PublicarEventoOptions {
+  tipo: string;
+  autorizacao: string;
+  payload?: Record<string, unknown>;
+  url?: string;
+  timeoutMs?: number;
+  aoFalhar?: (mensagem: string) => void;
+}
+
+export declare function publicarEvento(options?: PublicarEventoOptions): void;

package/src/index.js

@@ -2,7 +2,8 @@ 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");
+const { publicarEvento } = require("./services/motorEventosService.js");
 
 function expressCommonMiddlewares({ cookieName } = {}){
     return [bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}), devMktTokenSanitaze({ cookieName })];
@@ -11,4 +12,4 @@ function expressCommonMiddlewares({ cookieName } = {}){
 
 
 
-module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, redMetricsMiddleware, metricsHandler }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics, publicarEvento }

package/src/services/motorEventosService.js

@@ -0,0 +1,56 @@
+const TIMEOUT_PADRAO_MS = 2000;
+
+function urlConfigurada(url) {
+    const configurada = url ?? process.env.MOTOR_EVENTOS_URL;
+
+    if (typeof configurada !== "string" || configurada.trim() === "") {
+        console.warn("motorEventos: url do coletor ausente, evento nao publicado");
+        return null;
+    }
+
+    return configurada.trim();
+}
+
+function publicarEvento({
+    tipo,
+    autorizacao,
+    payload,
+    url,
+    timeoutMs = TIMEOUT_PADRAO_MS,
+    aoFalhar = (mensagem) => console.error(mensagem),
+} = {}) {
+    try {
+        const destino = urlConfigurada(url);
+
+        if (!destino || !tipo || !autorizacao) {
+            return;
+        }
+
+        fetch(destino, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: autorizacao },
+            body: JSON.stringify({
+                tipo,
+                dt_evento: new Date().toISOString(),
+                payload: payload ?? {},
+            }),
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+            .then((resposta) => {
+                if (!resposta.ok) {
+                    aoFalhar(`motorEventos: ${tipo} recusado com status ${resposta.status}`);
+                }
+            })
+            .catch((erro) => {
+                aoFalhar(`motorEventos: ${tipo} nao publicado (${erro?.message})`);
+            });
+    } catch (erro) {
+        try {
+            aoFalhar(`motorEventos: ${tipo} nao publicado (${erro?.message})`);
+        } catch (_erroNoCallback) {
+            /* empty */
+        }
+    }
+}
+
+module.exports = { publicarEvento };

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/motorEventosService.test.js

@@ -0,0 +1,165 @@
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { publicarEvento } = require('../src/services/motorEventosService.js');
+
+const URL = 'http://coletor.interno/eventos';
+
+const esperarMicrotasks = () => new Promise((resolve) => setImmediate(resolve));
+
+describe('publicarEvento', () => {
+    let fetchOriginal;
+    let warnOriginal;
+    let urlOriginal;
+    let chamadas;
+    let falhas;
+    let avisos;
+
+    const aoFalhar = (mensagem) => falhas.push(mensagem);
+
+    beforeEach(() => {
+        fetchOriginal = global.fetch;
+        warnOriginal = console.warn;
+        urlOriginal = process.env.MOTOR_EVENTOS_URL;
+        chamadas = [];
+        falhas = [];
+        avisos = [];
+        console.warn = (mensagem) => avisos.push(mensagem);
+        global.fetch = (url, opcoes) => {
+            chamadas.push({ url, opcoes });
+            return Promise.resolve({ ok: true, status: 201 });
+        };
+    });
+
+    afterEach(() => {
+        global.fetch = fetchOriginal;
+        console.warn = warnOriginal;
+        if (urlOriginal === undefined) {
+            delete process.env.MOTOR_EVENTOS_URL;
+        } else {
+            process.env.MOTOR_EVENTOS_URL = urlOriginal;
+        }
+    });
+
+    test('envia POST na url configurada com o token de quem chamou', async () => {
+        publicarEvento({
+            tipo: 'meu_evento',
+            autorizacao: 'Bearer jwt',
+            payload: { campo: 'valor' },
+            url: URL,
+            aoFalhar,
+        });
+
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 1);
+        assert.equal(chamadas[0].url, URL);
+        assert.equal(chamadas[0].opcoes.method, 'POST');
+        assert.equal(chamadas[0].opcoes.headers.Authorization, 'Bearer jwt');
+
+        const corpo = JSON.parse(chamadas[0].opcoes.body);
+        assert.equal(corpo.tipo, 'meu_evento');
+        assert.deepEqual(corpo.payload, { campo: 'valor' });
+        assert.ok(!Number.isNaN(Date.parse(corpo.dt_evento)));
+        assert.deepEqual(falhas, []);
+        assert.deepEqual(avisos, []);
+    });
+
+    test('nao acrescenta caminho nenhum a url configurada', async () => {
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: 'http://coletor.interno/v2/x', aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas[0].url, 'http://coletor.interno/v2/x');
+    });
+
+    test('cai na MOTOR_EVENTOS_URL quando a url nao e passada', async () => {
+        process.env.MOTOR_EVENTOS_URL = URL;
+
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas[0].url, URL);
+    });
+
+    test('avisa e nao publica quando a url esta ausente', async () => {
+        delete process.env.MOTOR_EVENTOS_URL;
+
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 0);
+        assert.equal(avisos.length, 1);
+        assert.match(avisos[0], /url do coletor ausente/);
+    });
+
+    test('avisa quando a url nao e string ou e so espaco', async () => {
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: 123, aoFalhar });
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: '   ', aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 0);
+        assert.equal(avisos.length, 2);
+    });
+
+    test('nao publica sem tipo ou sem autorizacao', async () => {
+        publicarEvento({ autorizacao: 'Bearer jwt', url: URL, aoFalhar });
+        publicarEvento({ tipo: 'meu_evento', url: URL, aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 0);
+        assert.deepEqual(falhas, []);
+        assert.deepEqual(avisos, []);
+    });
+
+    test('nao quebra quando chamado sem argumento nenhum', () => {
+        delete process.env.MOTOR_EVENTOS_URL;
+
+        assert.doesNotThrow(() => publicarEvento());
+        assert.equal(chamadas.length, 0);
+    });
+
+    test('nao propaga rejeicao do fetch e reporta a falha', async () => {
+        global.fetch = () => Promise.reject(new Error('connect ECONNREFUSED'));
+
+        assert.doesNotThrow(() =>
+            publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: URL, aoFalhar })
+        );
+
+        await esperarMicrotasks();
+
+        assert.equal(falhas.length, 1);
+        assert.match(falhas[0], /meu_evento/);
+    });
+
+    test('reporta resposta de erro sem lancar', async () => {
+        global.fetch = () => Promise.resolve({ ok: false, status: 400 });
+
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: URL, aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(falhas.length, 1);
+        assert.match(falhas[0], /400/);
+    });
+
+    test('nao propaga erro sincrono do fetch', () => {
+        global.fetch = () => {
+            throw new TypeError('opcoes invalidas');
+        };
+
+        assert.doesNotThrow(() =>
+            publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: URL, aoFalhar })
+        );
+        assert.equal(falhas.length, 1);
+    });
+
+    test('nao devolve promise, para ninguem conseguir esperar por ela', () => {
+        const retorno = publicarEvento({
+            tipo: 'meu_evento',
+            autorizacao: 'Bearer jwt',
+            url: URL,
+            aoFalhar,
+        });
+
+        assert.equal(retorno, undefined);
+    });
+});

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/);
+    });
+});