🚀 Advanced HTTP Request Interceptor

Biblioteca profissional para interceptação, monitoramento e logging avançado de requisições HTTP em aplicações Express.js

🌟 Por que escolher esta biblioteca?

✨ Recursos Únicos

• 🔍 Observabilidade Total: Visibilidade completa de 100% das requisições HTTP
• ⚡ Performance Zero-Impact: Overhead mínimo de 0-1ms por requisição
• 🛡️ Auditoria Enterprise: Logging automático para compliance e segurança
• 📊 Métricas Inteligentes: Estatísticas por rota em tempo real
• 🎯 Detecção Proativa: Identificação automática de requisições lentas
• 🔧 Configuração Flexível: Personalizável para qualquer necessidade
• 📝 TypeScript Nativo: Tipagem completa e autocomplete inteligente
• 🪶 Zero Dependências: Biblioteca leve sem dependências externas

🚀 Casos de Uso Reais

• API Monitoring: Monitoramento profissional de APIs em produção
• Security Auditing: Logs detalhados para auditoria de segurança
• Performance Optimization: Identificação de gargalos de performance
• Debugging Avançado: Contexto completo para resolução de problemas
• Business Analytics: Métricas de uso e padrões de comportamento

📦 Instalação

# NPM
npm install advanced-http-request-interceptor

# Yarn
yarn add advanced-http-request-interceptor

# PNPM
pnpm add advanced-http-request-interceptor

Requisitos

• Node.js: 16.x ou superior
• Express.js: 4.x ou superior
• TypeScript: 4.x ou superior (opcional)

🚀 Início Rápido (30 segundos)

const express = require('express');
const { requestInterceptor } = require('advanced-http-request-interceptor');

const app = express();

// ✨ Uma linha para observabilidade completa
app.use(requestInterceptor({
  enableLogging: true,
  enablePerformanceMonitoring: true,
  enableAuditLogging: true
}));

// Suas rotas normais
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.listen(3000, () => {
  console.log('🚀 Servidor com monitoramento avançado rodando!');
});

Resultado Imediato:

[2025-05-23T10:30:45.123Z] [INFO] HTTP Request: GET /api/users
{
  "method": "GET",
  "url": "/api/users",
  "clientIp": "192.168.1.100",
  "userAgent": "Mozilla/5.0...",
  "duration": 15,
  "bodySize": 0,
  "timestamp": "2025-05-23T10:30:45.108Z"
}

⚙️ Configuração Completa

Todas as Opções Disponíveis

const { requestInterceptor } = require('advanced-http-request-interceptor');

app.use(requestInterceptor({
  // 🔍 Análise do corpo da requisição
  parseBody: true,                    // Analisa o body automaticamente
  maxBodySize: 2 * 1024 * 1024,       // Limite: 2MB (padrão: 1MB)

  // 📝 Sistema de Logging
  enableLogging: true,                 // Ativa logging detalhado
  logLevel: 'info',                   // Níveis: 'debug', 'info', 'warn', 'error'

  // 📊 Monitoramento de Performance
  enablePerformanceMonitoring: true,  // Métricas por rota

  // 🛡️ Auditoria de Segurança
  enableAuditLogging: true,           // Logs para compliance

  // 🔧 Processamento Personalizado
  onRequest: (req, requestInfo) => {
    // Seu código personalizado aqui
    console.log(`📥 ${requestInfo.method} ${requestInfo.url}`);

    // Integração com seu sistema de métricas
    if (requestInfo.duration > 1000) {
      alertSystem.notify('Requisição lenta detectada', requestInfo);
    }
  },

  // 🎛️ Logger Personalizado
  customLogger: (level, message, data) => {
    // Integração com Winston, Bunyan, etc.
    winston[level](message, data);
  }
}));

📊 Métricas e Monitoramento

Endpoint de Métricas Integrado

const { requestInterceptor, MetricsCollector } = require('advanced-http-request-interceptor');

app.use(requestInterceptor({ enablePerformanceMonitoring: true }));

// 📈 Endpoint automático de métricas
app.get('/metrics', (req, res) => {
  const metrics = MetricsCollector.getInstance().getMetrics();
  res.json(metrics);
});

Exemplo de Resposta de Métricas

{
  "/api/users": {
    "count": 1247,
    "totalDuration": 18705,
    "averageDuration": 15.0,
    "minDuration": 8,
    "maxDuration": 89,
    "lastRequest": "2025-05-23T10:45:30.123Z"
  },
  "/api/products": {
    "count": 856,
    "averageDuration": 23.4,
    "minDuration": 12,
    "maxDuration": 156,
    "lastRequest": "2025-05-23T10:44:15.456Z"
  }
}

🛡️ Auditoria e Segurança

Logging de Auditoria Automático

app.use(requestInterceptor({
  enableAuditLogging: true,
  onRequest: (req, requestInfo) => {
    // 🚨 Detecção de atividade suspeita
    if (requestInfo.bodySize > 10 * 1024 * 1024) { // > 10MB
      securityAlert.trigger('Large payload detected', {
        ip: requestInfo.clientIp,
        size: requestInfo.bodySize,
        endpoint: requestInfo.url
      });
    }

    // 📋 Log para compliance (LGPD, GDPR)
    auditLogger.log({
      action: `${requestInfo.method} ${requestInfo.url}`,
      user: req.user?.id,
      ip: requestInfo.clientIp,
      timestamp: requestInfo.timestamp,
      dataAccessed: requestInfo.path.includes('/personal-data')
    });
  }
}));

🔧 TypeScript - Suporte Completo

Tipagem Avançada

import { 
  requestInterceptor, 
  RequestInterceptorOptions,
  MetricsCollector,
  HttpLogger,
  LogLevel 
} from 'advanced-http-request-interceptor';

const options: RequestInterceptorOptions = {
  enableLogging: true,
  logLevel: 'info' as LogLevel,
  enablePerformanceMonitoring: true,
  onRequest: (req, requestInfo) => {
    // Autocomplete completo e validação de tipos
    console.log(`${requestInfo.method} ${requestInfo.url} - ${requestInfo.duration}ms`);
  }
};

app.use(requestInterceptor(options));

// 📊 Acesso tipado às métricas
const metricsCollector: MetricsCollector = MetricsCollector.getInstance();
const routeMetrics = metricsCollector.getRouteMetrics('/api/users');

Interfaces Disponíveis

interface RequestInfo {
  method: string;
  url: string;
  path: string;
  headers: any;
  query: any;
  params: any;
  timestamp: string;
  clientIp: string | undefined;
  userAgent: string | undefined;
  body: any;
  duration?: number;
  contentLength?: number;
  bodySize?: number;
}

interface RouteMetrics {
  count: number;
  totalDuration: number;
  averageDuration: number;
  minDuration: number;
  maxDuration: number;
  lastRequest: string;
}

🎯 Casos de Uso Avançados

1. Integração com Sistemas de APM

const { requestInterceptor } = require('advanced-http-request-interceptor');

app.use(requestInterceptor({
  onRequest: (req, requestInfo) => {
    // New Relic
    newrelic.recordMetric(`Custom/HTTP/${requestInfo.method}${requestInfo.path}`, requestInfo.duration);

    // DataDog
    statsd.timing('http.request.duration', requestInfo.duration, [`route:${requestInfo.path}`]);

    // Prometheus
    httpRequestDuration.labels(requestInfo.method, requestInfo.path).observe(requestInfo.duration / 1000);
  }
}));

2. Rate Limiting Inteligente

const rateLimitMap = new Map();

app.use(requestInterceptor({
  onRequest: (req, requestInfo) => {
    const key = requestInfo.clientIp;
    const now = Date.now();
    const requests = rateLimitMap.get(key) || [];

    // Remove requisições antigas (última hora)
    const recentRequests = requests.filter(time => now - time < 3600000);

    if (recentRequests.length > 100) { // Max 100 req/hour
      throw new Error('Rate limit exceeded');
    }

    recentRequests.push(now);
    rateLimitMap.set(key, recentRequests);
  }
}));

3. A/B Testing e Analytics

app.use(requestInterceptor({
  onRequest: (req, requestInfo) => {
    // Tracking de A/B tests
    if (requestInfo.headers['x-ab-test']) {
      analytics.track('ab_test_request', {
        test: requestInfo.headers['x-ab-test'],
        variant: requestInfo.headers['x-ab-variant'],
        endpoint: requestInfo.path,
        duration: requestInfo.duration
      });
    }

    // Análise de comportamento de usuário
    userBehavior.track({
      userId: req.user?.id,
      action: `${requestInfo.method} ${requestInfo.path}`,
      timestamp: requestInfo.timestamp,
      metadata: {
        userAgent: requestInfo.userAgent,
        duration: requestInfo.duration
      }
    });
  }
}));

🧪 Testes e Qualidade

Executando Testes

# Testes básicos
npm test

# Testes avançados com todas as funcionalidades
npm run test:advanced

# Build e verificação de tipos
npm run build

Cobertura de Testes

• ✅ Interceptação de requisições HTTP
• ✅ Parsing de diferentes tipos de body
• ✅ Métricas de performance
• ✅ Sistema de logging
• ✅ Tratamento de erros
• ✅ Limites de tamanho de payload
• ✅ Compatibilidade TypeScript

📊 Performance Benchmarks

Conclusão: Overhead praticamente imperceptível com benefícios enormes de observabilidade.

🔄 Migração e Compatibilidade

Migrando de outras bibliotecas

// Antes (morgan)
app.use(morgan('combined'));

// Depois (advanced-http-request-interceptor)
app.use(requestInterceptor({
  enableLogging: true,
  logLevel: 'info',
  customLogger: (level, message, data) => {
    console.log(`${data.clientIp} - ${data.method} ${data.url} ${data.duration}ms`);
  }
}));

// Antes (express-winston)
app.use(expressWinston.logger({
  transports: [new winston.transports.Console()],
  format: winston.format.combine(winston.format.colorize(), winston.format.json())
}));

// Depois (advanced-http-request-interceptor)
app.use(requestInterceptor({
  enableLogging: true,
  customLogger: (level, message, data) => {
    winston[level](message, data);
  }
}));

🤝 Contribuindo

Como Contribuir

1. Fork o repositório
2. Clone sua fork: git clone https://github.com/seu-usuario/advanced-http-request-interceptor.git
3. Crie uma branch: git checkout -b feature/nova-feature
4. Faça suas mudanças e adicione testes
5. Execute os testes: npm test
6. Commit: git commit -m "feat: adicionar nova feature"
7. Push: git push origin feature/nova-feature
8. Abra um Pull Request

Desenvolvimento Local

# Clone o repositório
git clone https://github.com/elSilveira/advanced-http-request-interceptor.git

# Instale dependências
npm install

# Execute em modo desenvolvimento
npm run dev

# Execute testes
npm test

# Build
npm run build

📄 Licença

MIT © Eduardo Luiz da Silveira

🔗 Links Úteis

• 📚 Documentação Completa
• 🐛 Reportar Bug
• 💡 Solicitar Feature
• 📦 NPM Package
• 🚀 GitHub Repository

⭐ Se esta biblioteca te ajudou, deixe uma estrela no GitHub!

# Instalação rápida
npm install advanced-http-request-interceptor

Desenvolvido com ❤️ por Eduardo Luiz da Silveira

Changelog

Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.

O formato é baseado em Keep a Changelog, e este projeto adere ao Semantic Versioning.

[1.0.0] - 2025-05-23

🎉 Lançamento Inicial

✨ Adicionado

• Interceptação Completa: Sistema completo de interceptação de requisições HTTP
• Logging Avançado: Sistema de logging com níveis configuráveis (debug, info, warn, error)
• Métricas de Performance: Coleta automática de estatísticas por rota em tempo real
• Auditoria de Segurança: Logging detalhado para compliance e auditoria
• Detecção Proativa: Identificação automática de requisições lentas (>1000ms)
• TypeScript Nativo: Suporte completo com tipagens e autocomplete
• Logger Personalizado: Integração com sistemas externos (Winston, Bunyan, etc.)
• Proteção contra Ataques: Limite configurável de payload para prevenir ataques DoS
• Zero Dependências: Biblioteca leve sem dependências externas

🔧 Funcionalidades Técnicas

• Análise automática de corpo de requisições JSON
• Captura de IP do cliente e User-Agent
• Medição precisa de duração de requisições
• Sistema singleton para coleta centralizada de métricas
• Tratamento robusto de erros
• Suporte a middleware personalizado via callbacks

📊 Sistema de Métricas

• Contador de requisições por rota
• Duração mínima, máxima e média por endpoint
• Timestamp da última requisição
• API para acesso às métricas via MetricsCollector.getInstance()

🛡️ Recursos de Segurança

• Logging de auditoria com IPs, headers e payloads
• Proteção contra payloads excessivamente grandes
• Detecção de streaming malicioso
• Logs estruturados para análise de segurança

🧪 Qualidade e Testes

• Workflow CI/CD completo no GitHub Actions
• Testes em múltiplas versões do Node.js (16, 18, 20)
• Verificação automática de tipos TypeScript
• Testes de importação CommonJS
• Cobertura de casos de uso reais

📚 Documentação

• README profissional com exemplos detalhados
• Comentários JSDoc completos no código
• Exemplos de uso para diferentes cenários
• Guias de migração de outras bibliotecas
• Documentação de todas as interfaces TypeScript

🔧 Configurações Suportadas

• parseBody: Análise do corpo da requisição (padrão: true)
• maxBodySize: Tamanho máximo do payload (padrão: 1MB)
• enableLogging: Ativa logging detalhado (padrão: true)
• logLevel: Nível de logging (padrão: 'info')
• enablePerformanceMonitoring: Métricas de performance (padrão: true)
• enableAuditLogging: Auditoria de segurança (padrão: false)
• customLogger: Logger personalizado (opcional)
• onRequest: Callback personalizado (opcional)

📋 Compatibilidade

• Node.js: 16.x ou superior
• Express.js: 4.x e 5.x
• TypeScript: 4.x ou superior
• Ambientes: Desenvolvimento, teste e produção

Como Contribuir

Para contribuir com este projeto:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Versioning

Usamos SemVer para versionamento. Para as versões disponíveis, veja as tags neste repositório.

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.