@ecdt/server-common 1.5.1 → 1.6.1

package/README.md

@@ -158,6 +158,44 @@ export default defineEventHandler(async (event) => {
 
 ---
 
+### `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 |
+| `idVisitante` | — | Identificador anônimo, para quando não há token |
+| `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 do usuário sai do token, nunca do corpo: o coletor a resolve a partir do `Authorization`
+repassado. Quando não há token — rota pública, visitante anônimo — vale o `idVisitante`, que vai no
+corpo como `id_visitante`. Ele não é identidade autenticada, é um identificador de correlação: forjá-lo
+não atribui nada à conta de ninguém, e por isso pode vir do corpo da requisição. Basta um dos dois.
+
+Sem `tipo`, ou sem nenhum dos dois identificadores, 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
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Conjunto de ferramentas e configurações comuns nos servidores da Econodata",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -135,3 +135,15 @@ export declare function metricsHandler(registry?: MetricsRegistry): RequestHandl
 export declare function renderMetrics(
   registry?: MetricsRegistry
 ): Promise<{ contentType: string; body: string }>;
+
+export interface PublicarEventoOptions {
+  tipo: string;
+  autorizacao?: string;
+  idVisitante?: string;
+  payload?: Record<string, unknown>;
+  url?: string;
+  timeoutMs?: number;
+  aoFalhar?: (mensagem: string) => void;
+}
+
+export declare function publicarEvento(options?: PublicarEventoOptions): void;

package/src/index.js

@@ -3,6 +3,7 @@ const { devMktTokenSanitaze } = require("./services/tokenService.js");
 const { expressCors } = require("./services/corsService.js");
 const { setupGracefulShutdown } = require("./services/shutdownService.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, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics, publicarEvento }

package/src/services/motorEventosService.js

@@ -0,0 +1,72 @@
+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 textoNaoVazio(valor) {
+    return typeof valor === "string" && valor.trim() !== "" ? valor.trim() : null;
+}
+
+function publicarEvento({
+    tipo,
+    autorizacao,
+    idVisitante,
+    payload,
+    url,
+    timeoutMs = TIMEOUT_PADRAO_MS,
+    aoFalhar = (mensagem) => console.error(mensagem),
+} = {}) {
+    try {
+        const destino = urlConfigurada(url);
+        const visitante = textoNaoVazio(idVisitante);
+
+        if (!destino || !tipo || (!autorizacao && !visitante)) {
+            return;
+        }
+
+        const cabecalhos = { "Content-Type": "application/json" };
+        if (autorizacao) {
+            cabecalhos.Authorization = autorizacao;
+        }
+
+        const corpo = {
+            tipo,
+            dt_evento: new Date().toISOString(),
+            payload: payload ?? {},
+        };
+        if (visitante) {
+            corpo.id_visitante = visitante;
+        }
+
+        fetch(destino, {
+            method: "POST",
+            headers: cabecalhos,
+            body: JSON.stringify(corpo),
+            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/test/motorEventosService.test.js

@@ -0,0 +1,196 @@
+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, nem sem identidade nenhuma', async () => {
+        publicarEvento({ autorizacao: 'Bearer jwt', url: URL, aoFalhar });
+        publicarEvento({ tipo: 'meu_evento', url: URL, aoFalhar });
+        publicarEvento({ tipo: 'meu_evento', url: URL, idVisitante: '   ', aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 0);
+        assert.deepEqual(falhas, []);
+        assert.deepEqual(avisos, []);
+    });
+
+    test('publica so com idVisitante, sem header de autorizacao', async () => {
+        publicarEvento({ tipo: 'meu_evento', idVisitante: 'visitante-1', url: URL, aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 1);
+        assert.equal(chamadas[0].opcoes.headers.Authorization, undefined);
+        assert.equal(JSON.parse(chamadas[0].opcoes.body).id_visitante, 'visitante-1');
+    });
+
+    test('manda os dois quando tem token e visitante', async () => {
+        publicarEvento({
+            tipo: 'meu_evento',
+            autorizacao: 'Bearer jwt',
+            idVisitante: 'visitante-1',
+            url: URL,
+            aoFalhar,
+        });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas[0].opcoes.headers.Authorization, 'Bearer jwt');
+        assert.equal(JSON.parse(chamadas[0].opcoes.body).id_visitante, 'visitante-1');
+    });
+
+    test('omite id_visitante do corpo quando nao ha visitante', async () => {
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: URL, aoFalhar });
+        await esperarMicrotasks();
+
+        assert.ok(!('id_visitante' in JSON.parse(chamadas[0].opcoes.body)));
+    });
+
+    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);
+    });
+});