Event-Driven Service | NestJS

Event-Driven Integration Service

Arquitetura Técnica

Fluxo de processamento de eventos

O serviço implementa uma arquitetura robusta orientada a eventos para processar webhooks externos com entrega e idempotência garantidas.

1. Camada de entrada: endpoints de webhook específicos do provedor recebem solicitações HTTP POST
2. Validação de segurança: Verificação de assinatura HMAC usando segredos específicos do provedor
3. Verificação de idempotência: A validação de restrição do banco de dados atômico evita processamento duplicado
4. Persistência de Eventos: A operação Atomic INSERT armazena evento com status PENDING
5. Despacho de fila: ID do evento enfileirado no BullMQ com configuração de espera exponencial
6. Processamento Assíncrono: o worker processa eventos com lógica de repetição e atualizações de status
7. Conclusão: O status do evento muda para COMPLETED ou DEAD_LETTER em caso de falha

Diagrama de Fluxo de Dados

External Provider -> HTTP Endpoint -> HMAC Validation -> Database Constraint Check
    |
Event Stored (PENDING) -> BullMQ Queue -> Worker Process -> Status Updates
    |
COMPLETED / DEAD_LETTER -> Observability Stack

Stack tecnológica

• Tempo de execução: Node.js 18+ com TypeScript 5.0+
• Estrutura: NestJS 10+ com injeção de dependência
• Banco de dados: PostgreSQL 15+ com Prisma ORM
• Sistema de filas: BullMQ 5+ com Redis 7+
• Observabilidade: OpenTelemetry 1.20+ com Jaeger
• Registro: Winston 3.11+ com saída JSON estruturada
• Conteinerização: Docker com compilações em vários estágios

Confiabilidade e resiliência

Idempotência Atômica

O sistema garante o processamento exatamente uma vez por meio de restrições no nível do banco de dados:

• Restrição Única: Índice exclusivo composto em (provider, eventId) evita condições de corrida
• Operações Atômicas: Instrução INSERT única com tratamento de violação de restrição
• Rastreamento de status: Ciclo de vida do evento de PENDING -> PROCESSING -> COMPLETED/DEAD_LETTER
• Tratamento duplicado: Eventos existentes retornam 200 OK sem reprocessamento

Estratégia de nova tentativa

Mecanismo de nova tentativa configurável com espera exponencial:

• Máximo de tentativas: 3 novas tentativas por evento
• Algoritmo de retirada: Atraso exponencial (2^tentativa * 1000ms)
• Atraso inicial: atraso base de 1 segundo
• Atualizações de status: Contagem de novas tentativas e carimbo de data/hora da próxima tentativa rastreados por evento
• Escalação de falhas: Eventos que excedem o limite de novas tentativas são movidos para a fila de mensagens não entregues

Dead-letter queue

Os eventos com falha são isolados para análise e intervenção manual:

• Escalação Automática: Eventos que excedem o limite de novas tentativas são movidos automaticamente
• Isolamento de status: O status DEAD_LETTER impede novas tentativas de processamento
• Trilha de auditoria: Histórico completo de processamento mantido para depuração
• Recuperação manual: Eventos com falha podem ser recolocados na fila para nova tentativa

Stack de observabilidade

Rastreamento Distribuído

A implementação OpenTelemetry fornece visibilidade de solicitação ponta a ponta:

• Criação de período: Período dedicado para cada ciclo de vida de processamento de eventos
• Atributos de extensão: event.id, event.type, event.provider, retry_count
• Erro de gravação: Exceções capturadas com full stack traces
• Rastreamento de status: O status do intervalo reflete o sucesso/falha do processamento
• Propagação de rastreamento: Correlação entre limites de serviço

Logs estruturados

Registro baseado em Winston com informações contextuais:

• Correlação de Eventos: Injeção automática de eventId em todas as mensagens de log
• Formato Estruturado: Saída JSON compatível com ELK/Datadog
• Níveis de registro: DEBUG, INFO, WARN, ERROR com categorização apropriada
• Enriquecimento de Contexto: Solicitar metadados, estado de processamento, informações de tempo
• Rotação de registro: Políticas configuráveis de retenção e rotação

Monitoramento de Saúde

NestJS Terminus fornece verificações de integridade abrangentes:

• Conectividade de banco de dados: PostgreSQL monitoramento de integridade da conexão
• Uso de memória: Rastreamento de memória heap e RSS
• Saúde da fila: Conexão Redis e monitoramento de profundidade de fila
• Status do serviço: endpoint HTTP para verificações de integridade do balanceador de carga

Padrões de API

Respostas de erro padronizadas

Todos os endpoints API retornam um formato de erro consistente:

{
  "statusCode": 500,
  "timestamp": "2026-03-06T13:37:07.038Z",
  "path": "/api/webhooks/stripe",
  "message": "Error description",
  "correlationId": "uuid-v4",
  "traceId": "otel-trace-id"
}

Campos obrigatórios:

• statusCode: código de status HTTP
• timestamp: carimbo de data/hora formatado em ISO 8601
• path: Caminho da solicitação
• message: Descrição do erro legível por humanos
• correlationId: UUID para rastreamento de solicitação
• traceId: OpenTelemetry identificador de rastreamento

Endpoints de webhook

Endpoints específicos do provedor com validação de segurança:

POST /webhooks/{provider}
Content-Type: application/json
X-{Provider}-Signature: signature-header-value

Provedores Suportados:

• stripe: Webhooks de pagamento de distribuição
• paypal: webhooks de transação do PayPal
• github: GitHub webhooks do repositório

Endpoint da verificação de integridade

GET /health

Retorna o status de integridade do sistema com métricas de banco de dados e memória.

Operações de infraestrutura

Encerramento gracioso

O serviço lida com sinais de encerramento para desligamento limpo:

• Tratamento de Sinal: Processamento de sinal SIGTERM e SIGINT
• Limpeza de conexão: Encerramento da conexão Prisma e Redis
• Conclusão do Trabalho: trabalhos ativos podem ser concluídos antes do encerramento
• Liberação de recursos: Limpeza adequada dos recursos do sistema
• Códigos de saída: Códigos de saída apropriados para sistemas de orquestração

Gerenciamento de configuração

Configuração baseada em ambiente com validação:

# Database Configuration
DATABASE_URL="postgresql://user:pass@host:port/database"

# Redis Configuration  
REDIS_HOST="localhost"
REDIS_PORT="6379"

# Provider Secrets
STRIPE_WEBHOOK_SECRET="whsec_..."
PAYPAL_WEBHOOK_SECRET="..."
GITHUB_WEBHOOK_SECRET="..."

# Observability
OTEL_SERVICE_NAME="event-driven-integration-service"
JAEGER_ENDPOINT="http://localhost:14268/api/traces"

Desenvolvimento e Teste

Pré-requisitos

• Node.js 18+
• PostgreSQL 15+
• Redis 7+
• Docker 24+ (para infraestrutura)

Configuração local

1. Instalar dependências

   npm install
   

2. Migração de banco de dados

   npm run prisma:migrate
   npm run prisma:generate
   

3. Iniciar infraestrutura

   docker-compose up -d
   

4. Servidor de desenvolvimento

   npm run start:dev
   

Estratégia de teste

• Testes unitários: Brincadeira com teste de componentes isolados
• Testes de Integração: Validação de processamento de webhook ponta a ponta
• Infraestrutura simulada: Redis e simulação de banco de dados para CI/CD
• Teste de carga: Validação de desempenho sob alto rendimento

Implantação do Docker

docker-compose up --build

Dockerfile de vários estágios otimiza o tamanho e a segurança da imagem de produção.

Características de desempenho

Capacidade de throughput

• Processamento de eventos: mais de 1.000 eventos/segundo por instância de trabalho
• Operações de banco de dados: Pool de conexões com limites configuráveis
• Taxa de transferência da fila: Fila baseada em Redis com escala horizontal
• Uso de memória: Otimizado para processos de longa duração

Considerações sobre escalabilidade

• Escala horizontal: Várias instâncias de trabalho suportadas
• Dimensionamento de banco de dados: Leia réplicas para cenários de alto volume
• Particionamento de fila: Várias instâncias de fila para distribuição de carga
• Integração de monitoramento: Métricas do Prometheus para decisões de dimensionamento

Implementação de segurança

Validação de assinatura HMAC

Verificação de assinatura específica do provedor:

• Algoritmo: HMAC-SHA256 com segredos do provedor
• Análise de cabeçalho: Extração de cabeçalho de assinatura específica do provedor
• Proteção contra ataques de tempo: Implementação de comparação em tempo constante
• Gerenciamento Secreto: Armazenamento secreto baseado em ambiente

Validação de entrada

Sanitização e validação abrangente de entradas:

• Esquema JSON: Validação de payload específica do provedor
• Verificação de tipo: Validação de tipo de tempo de execução para campos críticos
• Limites de tamanho: Restrições de tamanho de payload para evitar DoS
• Tipo de conteúdo: Validação estrita do tipo de conteúdo

Implantação de produção

Requisitos de infraestrutura

• Banco de dados: PostgreSQL 15+ com pool de conexões
• Fila de mensagens: Redis 7+ com configuração de persistência
• Observabilidade: Coletor Jaeger para rastreamento distribuído
• Balanceador de carga: Encerramento HTTP/HTTPS com verificações de integridade

Stack de monitoramento

• Métricas: Prometheus com métricas de aplicativos personalizadas
• Painéis: Grafana para visibilidade operacional
• Alerta: AlertManager para resposta a incidentes
• Agregação de registros: Stack ELK ou equivalente para análise de log

Procedimentos Operacionais

• Implantação: Implantação azul esverdeada com tempo de inatividade zero
• Reverter: reversão automatizada em falhas de verificação de integridade
• Dimensionamento: escalonamento automático horizontal do pod com base na profundidade da fila
• Cópia de segurança: Procedimentos de backup e recuperação de banco de dados

Impacto de Engenharia

Engenharia de Confiabilidade

• Garantias de SLA: 99,9% de tempo de atividade com infraestrutura adequada
• Erro no orçamento: Limites de taxa de erro configuráveis
• Resposta a Incidentes: registro e rastreamento estruturados para depuração rápida
• Planejamento de capacidade: Decisões de escalabilidade baseadas em métricas

Engenharia de Segurança

• Proteção de Dados: Comunicação e armazenamento criptografados
• Controle de acesso: Autenticação específica do provedor
• Trilha de auditoria: Histórico completo de processamento para conformidade
• Gerenciamento de vulnerabilidades: Atualizações e verificações regulares de dependências

Engenharia de Observabilidade

• Práticas de SRE: Erro de orçamentos e implementação de SLI/SLO
• Eficiência de depuração: logs estruturados e rastreamento distribuído
• Monitoramento de desempenho: Métricas e alertas em tempo real
• Planejamento de capacidade: Dados históricos para dimensionamento de infraestrutura

Autor

Patrick Araujo - Engenheiro de Computação
GitHub: https://github.com/PkLavc
Portfólio: https://pklavc.com/projects/

Event-Driven Integration Service - Arquitetura de processamento de webhook confiável com idempotência, novas tentativas e observabilidade profunda.