TL.MiddlewareLibrary 0.1.0

<p align="center"> <img src="assets/icon.svg" alt="TL Middleware Icon" width="128" height="128" /> </p>

🚀 TL.MiddlewareLibrary

Bem-vindo ao ecossistema TL.MiddlewareLibrary! Esta biblioteca modular em C# / .NET disponibiliza middlewares de alta performance para enriquecer, monitorar e proteger o pipeline HTTP de aplicações corporativas em ASP.NET Core (.NET 6, .NET 8 e .NET 9).

Projetada para eliminar código repetitivo, ela centraliza medição de latência com zero alocação, proteção contra rajadas de requisições por IP, cache em memória seguro e padronização automática de erros em formato JSON amigável com rastreamento via traceId.

🎯 Por que Usar a Biblioteca?

Em muitas APIs, acabamos repetindo o mesmo código defensivo em todos os controllers e endpoints:

• Controladores cheios de blocos try/catch manuais.
• Cada endpoint ou microsserviço retornando erros em formatos diferentes ({ erro }, { message }, { error_description }), complicando a vida do front-end e mobile.
• Falhas 500 vazando stack traces ou mensagens técnicas de infraestrutura para o usuário.
• Falta de controle simples de requisições por cliente e medição precisa de tempo de resposta.

A TL.MiddlewareLibrary resolve isso direto no pipeline do ASP.NET Core, deixando seus controllers e Minimal APIs focados 100% nas regras de negócio.

💡 Antes vs. Depois

Antes (Sem a biblioteca — boilerplate e risco de vazamento)

app.MapGet("/api/produtos/{id:int}", async (int id, IProdutoService service, ILogger<Program> logger) =>
{
    try
    {
        if (id <= 0)
            return Results.BadRequest(new { mensagem = "Id inválido" });

        var produto = await service.ObterPorIdAsync(id);
        if (produto == null)
            return Results.NotFound(new { erro = "Não encontrado" });

        return Results.Ok(produto);
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Erro ao buscar produto");
        return Results.StatusCode(500, new { erro = ex.Message, stack = ex.StackTrace }); // Vaza stack trace!
    }
});

Depois (Com a TL.MiddlewareLibrary — limpo, seguro e idiomático)

app.MapGet("/api/produtos/{id:int}", async (int id, IProdutoService service) =>
{
    if (id <= 0)
        throw new BadRequestException("O id do produto deve ser maior que zero.");

    var produto = await service.ObterPorIdAsync(id) 
        ?? throw new NotFoundException($"Produto {id} não encontrado.");

    return Results.Ok(produto);
});

O middleware intercepta a exceção de negócio automaticamente, retorna o status HTTP correto (400, 404), formata o JSON amigável e adiciona o traceId para consulta imediata nos logs.

🗺️ O Pipeline em Execução

O diagrama abaixo ilustra o ciclo de vida completo da requisição trafegando pelos 6 middlewares e voltando ao cliente:

graph TD
    Client(["🌐 Cliente HTTP"]) --> A["⏱️ RequestTimingMiddleware"]
    A --> B["🛡️ RateLimitingMiddleware"]
    B --> C["🔐 AuthenticationMiddleware"]
    C --> D["⚡ CachingMiddleware"]
    D --> E["🚨 ExceptionHandlingMiddleware"]
    E --> F["📊 StatusCodeMiddleware"]
    F --> Endpoints["⚙️ Endpoints / Controllers / Minimal APIs"]

    Endpoints --> F
    F --> E
    E --> D
    D --> C
    C --> B
    B --> A
    A --> Client

📦 Catálogo de Middlewares

💡 Decisões de Arquitetura: Todas as diretrizes de design e trade-offs dos componentes abaixo estão documentadas de forma unificada na ADR-001: Arquitetura, Convenções e Pipeline HTTP.

⚡ Instalação Rápida via CLI

Adicione o pacote ao seu projeto através do .NET CLI:

dotnet add package TL.MiddlewareLibrary --version 0.1.0

💻 Como Configurar no Program.cs

A configuração é simples, fluente e encadeada na ordem recomendada:

using MiddlewareLibrary.Exceptions;
using MiddlewareLibrary.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 1. Serviços necessários
builder.Services.AddMemoryCache(); // Necessário caso utilize o CachingMiddleware

var app = builder.Build();

// 2. Encadeamento fluente do pipeline (Ordem Canônica)
app.UseRequestTiming();                                              // Mede o tempo total da requisição
app.UseRateLimiting(limit: 100, period: TimeSpan.FromMinutes(1));    // Limite de 100 req/min por IP
app.UseAuthenticationMiddleware();                                   // Validação de cabeçalho Authorization
app.UseCachingMiddleware(cacheDuration: TimeSpan.FromMinutes(2));    // Cache de 2 min para GET/HEAD
app.UseExceptionHandling();                                          // Fallback global para falhas 500
app.UseStatusCodeMiddleware();                                       // Tradução de exceções tipadas de negócio

// 3. Seus endpoints limpos e focados no negócio
app.MapGet("/api/saudacao", () => Results.Ok(new { mensagem = "Olá, mundo!" }));

app.Run();

🎮 Executando o Showcase Interativo

Para ver todos os 6 middlewares operando juntos em tempo real com documentação Swagger / OpenAPI interativa:

dotnet run --project examples/MiddlewareLibrary.Showcase

Abra seu navegador na URL indicada pelo terminal (ex: http://localhost:5000 ou http://localhost:5299) para explorar a interface Swagger e testar ao vivo:

• GET /api/demo/ok: Demonstra o cabeçalho X-Response-Time-Ms com tempo de resposta em tempo real.
• GET /api/demo/cache: Demonstra cache em memória de 30 segundos variando por parâmetro ?categoria=X.
• GET /api/demo/rate-limit: Teste de saturação retornando status 429 após 5 requisições em 30 segundos.
• GET /api/demo/auth-protected: Demonstra a validação do cabeçalho Authorization: Bearer <token>.
• GET /api/demo/exceptions/{tipo}: Disparo de exceções de negócio com tradução automática para ProblemDetails.

⚡ Desempenho & Evidências de Micro-benchmarks

A biblioteca foi projetada com foco em zero-allocation no hot path, pooling de memória e alta vazão concorrente. A solução possui 6 suítes de micro-benchmarks científicos auditados via BenchmarkDotNet:

<p align="center"> <img src="assets/benchmark-terminal.png" alt="Evidência de Execução Real no Terminal com BenchmarkDotNet" width="100%" /> </p>

dotnet run -c Release --project benchmarks/MiddlewareLibrary.Benchmarks

<details> <summary><b>📊 Ver detalhamento técnico e catálogo dos 6 cenários (Clique para expandir)</b></summary>

<br />

</details>

🛡️ Catálogo de Exceções de Domínio

A biblioteca disponibiliza 12 exceções prontas para uso. Quando lançadas no seu serviço, o StatusCodeMiddleware converte automaticamente para a resposta HTTP correspondente:

🏛️ Arquitetura e Decisões de Engenharia

Para entender detalhadamente as decisões de design, trade-offs e a topologia do pipeline:

• Visão Geral da Arquitetura & Diagramas C4
• ADR 001: Arquitetura, Convenções e Pipeline HTTP
• Diretório de Registros Arquiteturais (ADRs)

🤝 Contribuição

Contribuições são muito bem-vindas! Ao submeter melhorias:

1. Abra uma issue para discutir a proposta ou relatar algum comportamento inesperado.
2. Certifique-se de que novos métodos assíncronos retornem Task ou ValueTask (zero async void).
3. Mantenha a conformidade com as versões suportadas (.NET 6.0, .NET 8.0 e .NET 9.0).
4. Acompanhe novas funcionalidades com testes automatizados em MiddlewareLibrary.Tests.

📄 Licença

Este projeto é distribuído sob a licença MIT.