@gyramais/log-transport 0.1.0

package/src/options.ts

@@ -0,0 +1,153 @@
+/*
+  Contrato de configuração do pacote.
+
+  Tudo entra por parâmetro: o pacote NÃO lê `process.env` em nenhum ponto. São três
+  razões, em ordem de peso:
+
+  1. Correção. Os 15 serviços não leem os mesmos envs — `gyra-export` lê `APP_NAME`,
+     e `gyra-file` e `gyra-websocket-server` não leem `ENVIRONMENT` nem `LOG_LEVEL`.
+     Um helper de env compartilhado mudaria o comportamento desses em silêncio.
+  2. Testabilidade. Ler env obriga o teste a mutar estado global do processo, o que
+     torna a suíte sensível à ordem de execução.
+  3. Contrato visível. A assinatura diz o que o pacote precisa, sem o consumidor
+     ter que ler o código-fonte.
+
+  Quem lê env é o serviço, no entrypoint, onde o env já mora hoje.
+*/
+
+/*
+  Estrutura mínima do transport que o pacote manipula, declarada aqui para o
+  `options.ts` não precisar importar o winston-loki.
+
+  Lista os membros que são de fato tocados — `log` pelo winston ao montar o
+  logger, e `flush`/`close`/`once`/`off` pelo caminho de exceção fatal.
+
+  Era `object`, que aceitava `{ qualquer: 'coisa' }` e até um `Date` em tempo de
+  compilação; o erro só aparecia no boot, quando o winston recusava o transport
+  com "Invalid transport, must be an object with a log method".
+*/
+export interface LokiTransportLike {
+  /*
+    Todos os membros são opcionais, e isso é deliberado — não desleixo.
+
+    Não existe membro que dê para exigir: o tipo real do `LokiTransport` declara
+    `log` e `flush` como opcionais, então exigir qualquer um deles rejeitaria o
+    transport de verdade. Tentei, e o `tsc` recusou o caso legítimo.
+
+    Com todos opcionais, a detecção de "weak type" do TypeScript faz o trabalho:
+    um objeto sem NENHUMA propriedade em comum com esta interface é rejeitado. É o
+    suficiente para pegar `{ qualquer: 'coisa' }` e `Date`, que passavam quando o
+    tipo era `object`.
+  */
+  log?: unknown;
+  flush?: () => Promise<void>;
+  close?: () => void;
+  once?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+  off?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+}
+
+export interface LokiOptions {
+  /* Endereço do Loki. Sem ele não há para onde enviar, então é obrigatório. */
+  host: string;
+
+  basicAuth?: string;
+
+  /*
+    Intervalo do batch em segundos. É a janela de linhas que ficam apenas em
+    memória e morrem junto com o processo num crash — daí o default curto.
+  */
+  interval?: number;
+
+  timeout?: number;
+
+  /*
+    Labels extras, somados aos default (`service`, `app`, `instance`). Serve para
+    dimensão específica do serviço; sobrescrever os default é possível, mas quebra
+    as consultas existentes.
+  */
+  labels?: Record<string, string>;
+}
+
+export interface FileOptions {
+  filename: string;
+}
+
+export interface LoggerOptions {
+  /*
+    Nome do serviço, como aparece no label `service` das consultas.
+
+    Obrigatório de propósito: o `gyra-nest-boilerplate` rotula hoje
+    `service: 'gyra-credit-policy'` por cópia de arquivo, e todo serviço criado a
+    partir dele nasce logando sob o rótulo errado até alguém notar. Sendo
+    obrigatório no tipo, esse erro passa a ser falha de compilação.
+  */
+  service: string;
+
+  /*
+    Label `app`. Default `'saas'` porque é o que as consultas e dashboards
+    existentes usam (`{app="saas", service="gyra-x"}`) — mudar aqui quebra painel
+    em produção.
+  */
+  app?: string;
+
+  level?: string;
+
+  /*
+    Identidade da instância, para as réplicas não dividirem uma única stream. Sem
+    isso não há como investigar um pod específico nem comparar o volume dele com o
+    próprio stdout. Default é o hostname do processo, que no Kubernetes é o nome
+    do pod.
+  */
+  instance?: string;
+
+  /*
+    Formato legível para humano, com cor e indentação, em vez de JSON.
+
+    É `boolean` e não um nome de ambiente: substitui o
+    `process.env.ENVIRONMENT === 'DEVELOPMENT'` do código original, para o pacote
+    não precisar conhecer os nomes de ambiente da organização.
+  */
+  pretty?: boolean;
+
+  /*
+    A PRESENÇA deste objeto é o gate de envio — substitui o
+    `LOG_GRAFANA_LOKI === 'true'`. Ausente significa não enviar, e o pacote não
+    precisa parsear string booleana.
+
+    Cada chamada com `loki` constrói um transport NOVO. Serviço que monta mais de
+    um logger no mesmo processo deve usar `lokiTransport` — ver abaixo.
+  */
+  loki?: LokiOptions;
+
+  /*
+    Transport já construído, para COMPARTILHAR um único batcher entre vários
+    loggers do mesmo processo.
+
+    Isto não é conveniência, é correção. O worker do gyra-core monta quatro
+    loggers — um para a app e três para conexões RMQ. Com quatro transports
+    independentes há quatro batchers, e o `registerFatalHandlers` drena apenas o
+    que recebeu: as linhas bufferizadas nos outros três morrem com o processo, que
+    é exatamente o sintoma que a entrega confiável existe para impedir.
+
+    A fonte original resolvia isso com um singleton de módulo. Aqui a decisão fica
+    com o consumidor — ele chama `createLokiTransport` uma vez e passa o mesmo
+    transport para cada logger — sem estado global escondido no pacote.
+
+    Mutuamente exclusivo com `loki`.
+  */
+  lokiTransport?: LokiTransportLike;
+
+  /*
+    Transport de arquivo, usado quando não há Loki. Mantém a precedência do código
+    original: havendo `loki`, o arquivo é ignorado.
+  */
+  file?: FileOptions;
+}
+
+export const DEFAULT_APP_LABEL = 'saas';
+export const DEFAULT_LEVEL = 'debug';
+
+/* Curto de propósito — ver o comentário de `interval` acima. */
+export const DEFAULT_LOKI_INTERVAL_SECONDS = 5;
+
+export const DEFAULT_LOKI_TIMEOUT_MS = 60000;