Event-Driven Service | NestJS

Event-Driven Integration Service

Arquitectura Técnica

Flujo de procesamiento de eventos

El servicio implementa una arquitectura sólida basada en eventos para procesar webhooks externos con entrega e idempotencia garantizadas.

1. Capa de ingreso: Los endpoints de webhook específicos del proveedor reciben solicitudes HTTP POST
2. Validación de seguridad: Verificación de firma HMAC utilizando secretos específicos del proveedor
3. Verificación de idempotencia: La validación de restricciones de la base de datos atómica evita el procesamiento duplicado
4. Persistencia de eventos: La operación Atomic INSERT almacena el evento con estado PENDIENTE
5. Despacho de cola: ID de evento en cola para BullMQ con configuración de retroceso exponencial
6. Procesamiento asincrónico: El worker procesa eventos con lógica de reintento y actualizaciones de estado.
7. Finalización: El estado del evento cambia a COMPLETADO o DEAD_LETTER en caso de falla

Diagrama de flujo de datos

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ógico

• Tiempo de ejecución: Node.js 18+ con TypeScript 5.0+
• Marco: NestJS 10+ con inyección de dependencia
• Base de datos: PostgreSQL 15+ con Prisma ORM
• Sistema de cola: BullMQ 5+ con Redis 7+
• Observabilidad: OpenTelemetry 1.20+ con Jaeger
• Registro: Winston 3.11+ con salida JSON estructurada
• Contenedorización: Docker con compilaciones de varias etapas

Fiabilidad y resiliencia

Idempotencia atómica

El sistema garantiza un procesamiento exactamente una vez mediante restricciones a nivel de base de datos:

• Restricción única: El índice único compuesto en (proveedor, eventId) evita condiciones de carrera
• Operaciones atómicas: Declaración INSERT única con manejo de violación de restricciones
• Seguimiento de estado: Ciclo de vida del evento desde PENDIENTE -> PROCESANDO -> COMPLETADO/LETRA MUERTA
• Manejo de duplicados: Los eventos existentes devuelven 200 OK sin reprocesamiento

Estrategia de reintento

Mecanismo de reintento configurable con retroceso exponencial:

• Intentos máximos: 3 reintentos por evento
• Algoritmo de retroceso: Retraso exponencial (2^intento * 1000ms)
• Retraso inicial: 1 segundo de retraso base
• Actualizaciones de estado: Se realiza un seguimiento del recuento de reintentos y de la marca de tiempo del siguiente reintento por evento
• Escalada de fallas: Los eventos que exceden el límite de reintentos se mueven a la cola de mensajes no entregados

Cola de mensajes fallidos

Los eventos fallidos se aíslan para su análisis e intervención manual:

• Escalada automática: Los eventos que exceden el límite de reintentos se mueven automáticamente
• Estado de aislamiento: El estado DEAD_LETTER impide futuros intentos de procesamiento
• Pista de auditoría: Historial de procesamiento completo mantenido para depuración
• Recuperación manual: Los eventos fallidos se pueden volver a poner en cola para reintentar

Stack de observabilidad

Seguimiento distribuido

La implementación de OpenTelemetry proporciona visibilidad de solicitudes de un extremo a otro:

• Creación de tramos: Intervalo dedicado para cada ciclo de vida de procesamiento de eventos
• Atributos de extensión: event.id, event.type, event.provider, reintento_count
• Grabación de errores: Excepciones capturadas con seguimientos de stack completo
• Seguimiento de estado: El estado del intervalo refleja el éxito o el fracaso del procesamiento.
• Propagación de trazas: Correlación entre los límites del servicio

Registro estructurado

Registro basado en Winston con información contextual:

• Correlación de eventos: Inyección automática de eventId en todos los mensajes de registro
• Formato estructurado: Salida JSON compatible con ELK/Datadog
• Niveles de registro: DEPURACIÓN, INFORMACIÓN, ADVERTENCIA, ERROR con la categorización adecuada
• Enriquecimiento del contexto: Solicitar metadatos, estado de procesamiento, información de tiempo
• Rotación de registros: Políticas de retención y rotación configurables

Monitoreo de salud

NestJS Terminus proporciona controles de salud integrales:

• Conectividad de base de datos: PostgreSQL monitoreo del estado de la conexión
• Uso de la memoria: Seguimiento de memoria RSS y montón
• Estado de la cola: Conexión de Redis y monitoreo de profundidad de cola
• Estado del servicio: Endpoint HTTP para comprobaciones de estado del balanceador de carga

API Estándares

Respuestas de error estandarizadas

Todos los endpoints API devuelven un formato de error 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 obligatorios:

• statusCode: código de estado HTTP
• timestamp: marca de tiempo con formato ISO 8601
• path: Solicitar ruta
• message: Descripción del error legible por humanos
• correlationId: UUID para seguimiento de solicitudes
• traceId: OpenTelemetry identificador de seguimiento

Endpoints de webhook

Endpoints específicos del proveedor con validación de seguridad:

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

Proveedores compatibles:

• stripe: Webhooks de pago de franjas
• paypal: Webhooks de transacciones de PayPal
• github: GitHub webhooks del repositorio

Endpoint de verificación de estado

GET /health

Devuelve el estado de salud del sistema con métricas de base de datos y memoria.

Operaciones de infraestructura

Apagado elegante

El servicio maneja señales de terminación para un apagado limpio:

• Manejo de señales: Procesamiento de señales SIGTERM y SIGINT
• Limpieza de conexión: Terminación de la conexión Prisma y Redis
• Finalización del trabajo: Los trabajos activos se pueden completar antes del apagado.
• Liberación de recursos: Limpieza adecuada de los recursos del sistema.
• Códigos de salida: Códigos de salida apropiados para sistemas de orquestación

Gestión de configuración

Configuración basada en entorno con validación:

# 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"

Desarrollo y pruebas

Requisitos previos

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

Configuración local

1. Instalar dependencias

   npm install
   

2. Migración de base de datos

   npm run prisma:migrate
   npm run prisma:generate
   

3. Iniciar infraestructura

   docker-compose up -d
   

4. Servidor de desarrollo

   npm run start:dev
   

Estrategia de prueba

• Pruebas unitarias: Jest con prueba de componentes aislados
• Pruebas de integración: Validación del procesamiento de webhooks de un extremo a otro
• Infraestructura simulada: Redis y burla de base de datos para CI/CD
• Pruebas de carga: Validación del rendimiento en condiciones de alto rendimiento

Implementación de Docker

docker-compose up --build

Dockerfile de varias etapas optimiza el tamaño y la seguridad de la imagen de producción.

Características de rendimiento

Capacidad de rendimiento

• Procesamiento de eventos: Más de 1000 eventos/segundo por instancia de worker
• Operaciones de base de datos: Agrupación de conexiones con límites configurables
• Rendimiento de la cola: Cola basada en Redis con escalado horizontal
• Uso de la memoria: Optimizado para procesos de larga duración

Consideraciones de escalabilidad

• Escala horizontal: Se admiten varias instancias de workers
• Escalado de bases de datos: Leer réplicas para escenarios de gran volumen
• Partición de colas: Múltiples instancias de cola para distribución de carga
• Integración de monitoreo: Métricas de Prometheus para decisiones de escala

Implementación de seguridad

Validación de firma HMAC

Verificación de firma específica del proveedor:

• Algoritmo: HMAC-SHA256 con secretos de proveedor
• Análisis de encabezado: Extracción del encabezado de firma específica del proveedor
• Protección contra ataques de sincronización: Implementación de comparación en tiempo constante
• Gestión Secreta: Almacenamiento secreto basado en el entorno

Validación de entrada

Sanitización y validación integral de insumos:

• Esquema JSON: Validación de payload específica del proveedor
• Tipo de verificación: Validación de tipo de tiempo de ejecución para campos críticos
• Límites de tamaño: Restricciones de tamaño de payload para evitar DoS
• Tipo de contenido: Validación estricta del tipo de contenido

Despliegue de producción

Requisitos de infraestructura

• Base de datos: PostgreSQL 15+ con agrupación de conexiones
• Cola de mensajes: Redis 7+ con configuración de persistencia
• Observabilidad: Recolector Jaeger para rastreo distribuido
• Equilibrador de carga: Terminación HTTP/HTTPS con controles de estado

Stack de monitoreo

• Métricas: Prometheus con métricas de aplicaciones personalizadas
• Paneles de control: Grafana para visibilidad operativa
• alertando: AlertManager para respuesta a incidentes
• Agregación de registros: stack ELK o equivalente para análisis de registros

Procedimientos operativos

• Implementación: Implementación azul-verde sin tiempo de inactividad
• Revertir: Reversión automatizada de fallas en las comprobaciones de estado
• Escalado: Escalado automático del pod horizontal según la profundidad de la cola
• Copia de seguridad: Procedimientos de copia de seguridad y recuperación de bases de datos.

Impacto de ingeniería

Ingeniería de Confiabilidad

• Garantías SLA: 99,9 % de tiempo de actividad con la infraestructura adecuada
• Error de presupuesto: Umbrales de tasa de error configurables
• Respuesta a incidentes: Registro y seguimiento estructurados para una depuración rápida
• Planificación de capacidad: Decisiones de escalado basadas en métricas

Ingeniería de Seguridad

• Protección de datos: Comunicación y almacenamiento cifrados
• Control de acceso: Autenticación específica del proveedor
• Pista de auditoría: Historial de procesamiento completo para cumplimiento
• Gestión de vulnerabilidades: Escaneo y actualizaciones periódicas de dependencias

Ingeniería de observabilidad

• Prácticas de ERE: Presupuestos de errores e implementación de SLI/SLO
• Eficiencia de depuración: Registros estructurados y seguimiento distribuido
• Monitoreo del desempeño: Métricas y alertas en tiempo real
• Planificación de capacidad: Datos históricos para el dimensionamiento de infraestructuras.

Autor

Patrick Araujo - Ingeniero Informático
GitHub: https://github.com/PkLavc
Portafolio: https://pklavc.com/projects/

Event-Driven Integration Service - Arquitectura de procesamiento de webhooks confiable con idempotencia, reintentos y observabilidad profunda.