Nuuvify.CommonPack.StandardHttpClient 2.2.0-preview.25102906

Nuuvify.CommonPack.StandardHttpClient

Cliente HTTP otimizado com retry policies, gerenciamento de tokens, resource management e performance aprimorada para bibliotecas .NET.

🚀 Destaques da Versão 2.2.0

🔔 Sistema de Notificações Avançado

• Sistema de notificações robusto com ReadOnlyCollection<NotificationR>
• Thread-safe notifications para coleta segura de erros e avisos
• Integração automática com TokenService para rastreamento de autenticação
• Notificações de serialização para debugging de problemas JSON
• Gerenciamento completo com métodos Add, Clear e Remove

⚡ Performance & Resource Management

• ConfigureAwait(false) implementado em todas as operações assíncronas
• Proper disposal pattern para HttpRequestMessage e HttpResponseMessage
• Memory leak prevention através de gerenciamento adequado de recursos
• Compliance com CA2000 (análise estática de código)

🧪 Testes Unitários Aprimorados

• ✅ 100% de testes unitários passando com correção completa de SocketException
• ✅ Mock setup otimizado com padrão disposeHandler: false
• ✅ Infraestrutura de testes robusta com handlers aprimorados
• ✅ Debugging tools para troubleshooting de HTTP mocking

🔄 Otimizações Implementadas

• ✅ Escalabilidade aprimorada em cenários de alta concorrência
• ✅ Redução significativa no uso de memória
• ✅ Prevenção de deadlocks em código síncrono/assíncrono
• ✅ Thread pool optimization com ConfigureAwait(false)
• ✅ Error tracking com sistema de notificações integrado

Índice

• Funcionalidades
• Dependências
• Instalação
• Configuração
• Uso Básico
  • IStandardHttpClient
  • BaseStandardHttpClient
  • TokenService
  • StandardWebService
• Exemplos Práticos
• Configurações Avançadas
• API Reference
• Troubleshooting
• Changelog

Funcionalidades

• ✅ Comunicação HTTP padronizada com APIs REST
• ✅ Gerenciamento automático de tokens com renovação inteligente
• ✅ Retry policies com Polly para resiliência (retry, circuit breaker, fallback)
• ✅ Renovação automática de tokens expirados em caso de HTTP 401
• ✅ Circuit Breaker pattern para proteção contra cascata de falhas
• ✅ Serialização JSON configurável com conversores customizados
• ✅ Suporte a SOAP para web services legados
• ✅ Logging detalhado para debugging e monitoramento
• ✅ Correlation IDs para rastreamento de requisições
• ✅ Suporte a CancellationToken para cancelamento gracioso
• ✅ Headers customizáveis e autenticação flexível
• ✅ QueryString helper com encoding automático
• ✅ Upload de arquivos (multipart) com progress tracking
• ✅ Performance otimizada com ConfigureAwait(false) para Class Libraries
• ✅ Gerenciamento de recursos com proper disposal de HttpRequestMessage e HttpResponseMessage
• ✅ Memory leak prevention através de padrões IDisposable corretos
• ✅ Sistema de notificações thread-safe para rastreamento de erros e operações
• ✅ Error tracking integrado com coleta automática de problemas de serialização e autenticação

Dependências

Framework

• .NET 8.0
• Microsoft.AspNetCore.App (FrameworkReference)

Pacotes NuGet

• Microsoft.Extensions.Http.Polly (8.0.16) - Para retry policies e circuit breaker patterns
• Nuuvify.CommonPack.Security.Abstraction - Para gerenciamento de credenciais

ℹ️ Sobre a integração com Polly: O TokenService utiliza a biblioteca Polly para implementar padrões de resiliência em comunicações HTTP, incluindo retry policies, circuit breaker e fallback handlers. Isso garante que as requisições de token sejam resilientes a falhas temporárias de rede.

Instalação

<PackageReference Include="Nuuvify.CommonPack.StandardHttpClient" Version="x.x.x" />

Configuração

1. Dependency Injection

// Program.cs ou Startup.cs
using Nuuvify.CommonPack.StandardHttpClient;

// Configuração básica
builder.Services.AddStandardHttpClientSetup(builder.Configuration);

// OU configuração sem registro de credencial
builder.Services.AddStandardHttpClientSetup(builder.Configuration, registerCredential: false);

// OU como Singleton
builder.Services.AddStandardHttpClientSetupSingleton(builder.Configuration);

// OU como Transient
builder.Services.AddStandardHttpClientSetupAddTransient(builder.Configuration);

// Configuração com Polly para resiliência (exemplo avançado)
builder.Services.AddHttpClient<IStandardHttpClient, BaseStandardHttpClient>()
    .AddPolicyWithTokenHandlers<TokenService>(
        retryCount: 3,
        circuitBreakerExceptionsThreshold: 5,
        circuitBreakerDurationInSeconds: 30
    );

2. Configuração do appsettings.json

{
  "AppConfig": {
    "AppURLs": {
      "UrlLoginApi": "https://api.exemplo.com",
      "UrlLoginApiToken": "/auth/token"
    }
  },
  "ApisCredentials": {
    "Username": "seu-usuario",
    "Password": "sua-senha"
  },
  "AzureAdOpenID": {
    "cc": {
      "ClientId": "seu-client-id",
      "ClientSecret": "seu-client-secret"
    }
  }
}

3. Configuração de HttpClient com Proxy (Opcional)

services.AddServiceCredentialRegister(configuration, "CredentialApi")
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler()
    {
        Proxy = new WebProxy("http://proxy:8080"),
        UseProxy = true
    });

Uso Básico

IStandardHttpClient

Interface principal para comunicação HTTP direta:

public class ExemploService
{
    private readonly IStandardHttpClient _httpClient;

    public ExemploService(IStandardHttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<HttpStandardReturn> ChamarApiAsync(CancellationToken cancellationToken = default)
    {
        _httpClient.CreateClient("MeuClient");

        var dados = new { Nome = "João", Idade = 30 };

        var resultado = await _httpClient
            .WithHeader("Accept-Language", "pt-BR")
            .WithAuthorization("Bearer", "meu-token")
            .WithCurrelationHeader(Guid.NewGuid().ToString())
            .WithQueryString("page", 1)
            .Post("api/usuarios", dados, cancellationToken);

        return resultado;
    }
}

BaseStandardHttpClient

Classe base para implementação de clientes HTTP específicos com serialização automática:

public class MeuClienteApi : BaseStandardHttpClient
{
    public MeuClienteApi(IStandardHttpClient standardHttpClient, ITokenService tokenService)
        : base(standardHttpClient, tokenService)
    {
    }

    public async Task<Usuario> ObterUsuarioAsync(int id, CancellationToken cancellationToken = default)
    {
        var token = await ObterTokenAsync(cancellationToken);

        var resultado = await ExecuteWithTokenAsync<Usuario>(
            httpClient => httpClient
                .WithAuthorization("Bearer", token)
                .Get($"api/usuarios/{id}", cancellationToken)
        );

        return resultado.Data;
    }

    public async Task<List<Usuario>> ListarUsuariosAsync(int page = 1, CancellationToken cancellationToken = default)
    {
        var token = await ObterTokenAsync(cancellationToken);

        var resultado = await ExecuteWithTokenAsync<List<Usuario>>(
            httpClient => httpClient
                .WithAuthorization("Bearer", token)
                .WithQueryString("page", page)
                .WithQueryString("limit", 10)
                .Get("api/usuarios", cancellationToken)
        );

        return resultado.Data;
    }
}

TokenService

Gerenciamento automático de tokens de autenticação:

public class MinhaApiService
{
    private readonly ITokenService _tokenService;

    public MinhaApiService(ITokenService tokenService)
    {
        _tokenService = tokenService;
    }

    public async Task<string> ObterTokenAsync(CancellationToken cancellationToken = default)
    {
        var token = await _tokenService.GetToken(
            login: "meu-usuario",
            password: "minha-senha",
            userClaim: "usuario-atual",
            cancellationToken: cancellationToken
        );

        return token?.Token;
    }

    public async Task<bool> RenovarTokenAsync(CancellationToken cancellationToken = default)
    {
        return await _tokenService.GetNewToken(
            "https://api.exemplo.com/auth/token",
            "meu-usuario",
            "minha-senha",
            "usuario-atual",
            cancellationToken
        );
    }
}

Resiliência com Polly

O TokenService integra-se nativamente com a biblioteca Polly para garantir comunicações HTTP resilientes. As políticas implementadas incluem:

🔄 Retry Policies

• Retry básico: Tenta novamente em caso de falha temporária
• Retry com renovação de token: Renova automaticamente tokens expirados (HTTP 401)
• Backoff exponencial: Aumenta progressivamente o tempo entre tentativas

🔌 Circuit Breaker

• Proteção contra cascata de falhas: Interrompe chamadas para serviços indisponíveis
• Recuperação automática: Testa periodicamente se o serviço voltou ao normal
• Logs detalhados: Registra quando o circuito abre/fecha

🛡️ Fallback Handlers

• Respostas alternativas: Retorna dados cached ou padrão em caso de falha
• Degradação graciosa: Mantém funcionalidade básica mesmo com serviços indisponíveis

// Configuração automática com Polly no HttpClient
services.AddServiceCredentialRegister(configuration, "CredentialApi")
    .AddPolicyWithTokenHandlers(services, retryTotal: 3, breakDurationMilliSeconds: 5000);

// OU para APIs externas (sem token)
services.AddHttpClient("ApiExterna", client =>
{
    client.BaseAddress = new Uri("https://api.externa.com");
})
.AddPolicyHandlers(services, retryTotal: 2, breakDurationMilliSeconds: 3000);

Cenários de Retry Automático

Logs de Resiliência

// O TokenService produz logs detalhados sobre retry policies:
// - "GetHttpResponseRetryPolicyWithToken Request with token failed with StatusCode: Unauthorized"
// - "Before ITokenService.GetToken" / "After ITokenService.GetToken"
// - "Service shutdown during: 00:00:05 after: 3 failed retries"

StandardWebService

Para comunicação com web services SOAP:

public class SoapService
{
    private readonly IStandardWebService _webService;

    public SoapService(IStandardWebService webService)
    {
        _webService = webService;
    }

    public async Task<HttpStandardXmlReturn> ChamarWebServiceAsync()
    {
        var soapEnvelope = new XmlDocument();
        soapEnvelope.LoadXml(@"
            <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
                <soap:Body>
                    <MinhaOperacao>
                        <Parametro>Valor</Parametro>
                    </MinhaOperacao>
                </soap:Body>
            </soap:Envelope>
        ");

        _webService.CreateClient("SoapClient");

        var resultado = await _webService
            .WithHeader("SOAPAction", "MinhaOperacao")
            .WithCurrelationHeader(Guid.NewGuid().ToString())
            .RequestSoap("WebService.asmx", soapEnvelope);

        return resultado;
    }
}

Exemplos Práticos

GET com QueryString

var resultado = await _httpClient
    .WithQueryString("nome", "João")
    .WithQueryString("idade", 30)
    .WithQueryString("ativo", true)
    .Get("api/usuarios", cancellationToken);
// URL: api/usuarios?nome=João&idade=30&ativo=true

POST com JSON

var usuario = new Usuario { Nome = "João", Email = "joao@exemplo.com" };

var resultado = await _httpClient
    .WithHeader("Content-Type", "application/json")
    .Post("api/usuarios", usuario, cancellationToken);

PUT com autenticação

var dadosAtualizacao = new { Nome = "João Silva" };

var resultado = await _httpClient
    .WithAuthorization("Bearer", token)
    .Put($"api/usuarios/{id}", dadosAtualizacao, cancellationToken);

PATCH parcial

var patch = new { Status = "Ativo" };

var resultado = await _httpClient
    .WithAuthorization("Bearer", token)
    .Patch($"api/usuarios/{id}", patch, cancellationToken);

DELETE

var resultado = await _httpClient
    .WithAuthorization("Bearer", token)
    .Delete($"api/usuarios/{id}", cancellationToken);

Upload de arquivo

using var fileContent = new StreamContent(fileStream);
using var multipartContent = new MultipartFormDataContent();
multipartContent.Add(fileContent, "arquivo", "documento.pdf");
multipartContent.Add(new StringContent("Descrição do arquivo"), "descricao");

var resultado = await _httpClient
    .WithAuthorization("Bearer", token)
    .Post("api/upload", multipartContent, "multipart/form-data", cancellationToken);

Download de arquivo

var stream = await _httpClient
    .WithAuthorization("Bearer", token)
    .GetStream("api/download/arquivo.pdf", cancellationToken);

await using var fileStream = File.Create("arquivo-local.pdf");
await stream.Data.CopyToAsync(fileStream, cancellationToken);

Autenticação Basic

var username = "usuario";
var password = "senha";
var credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{username}:{password}"));

var resultado = await _httpClient
    .WithAuthorization("Basic", credentials)
    .Get("api/dados", cancellationToken);

Sistema de Notificações

A biblioteca oferece um sistema robusto de notificações para rastreamento de erros e operações:

public class MeuClienteComNotificacoes : BaseStandardHttpClient
{
    public MeuClienteComNotificacoes(IStandardHttpClient standardHttpClient, ITokenService tokenService)
        : base(standardHttpClient, tokenService)
    {
    }

    public async Task<Usuario> ObterUsuarioComRastreamento(int id, CancellationToken cancellationToken = default)
    {
        // Limpar notificações anteriores
        ClearNotifications();

        try
        {
            var resultado = await ExecuteWithTokenAsync<Usuario>(
                httpClient => httpClient.Get($"api/usuarios/{id}", cancellationToken)
            );

            // Verificar se houve problemas durante a operação
            if (Notifications.Any())
            {
                foreach (var notification in Notifications)
                {
                    Console.WriteLine($"Aviso: {notification.Message} (Propriedade: {notification.Property})");
                }
            }

            return resultado.Data;
        }
        catch (Exception ex)
        {
            // Adicionar notificação personalizada
            AddNotification(new NotificationR(
                property: "ObterUsuario",
                message: $"Erro ao obter usuário {id}: {ex.Message}",
                type: "error"
            ));
            throw;
        }
    }

    public ReadOnlyCollection<NotificationR> ObterNotificacoes()
    {
        return Notifications;
    }

    public void LimparNotificacoes()
    {
        ClearNotifications();
    }

    public int RemoverNotificacoesPorPropriedade(string propriedade)
    {
        return RemoveNotifications(propriedade);
    }
}

Tipos de Notificações Automáticas

Thread Safety

// ✅ As notificações são thread-safe via ReadOnlyCollection
public async Task ProcessarMultiplasRequisicoes()
{
    var tasks = Enumerable.Range(1, 10).Select(async i =>
    {
        await ObterUsuario(i);

        // Safe para acessar de múltiplas threads
        var notificacoes = Notifications;
        return notificacoes.Count;
    });

    await Task.WhenAll(tasks);
}

Performance e Best Practices

🚀 Otimizações Implementadas

A biblioteca foi otimizada seguindo as melhores práticas para Class Libraries em .NET:

ConfigureAwait(false)

• ✅ Todos os await utilizam ConfigureAwait(false) para evitar captura desnecessária de contexto
• ✅ Melhor escalabilidade em aplicações server-side (ASP.NET, Web APIs)
• ✅ Prevenção de deadlocks em código síncrono que chama métodos assíncronos
• ✅ Performance superior em cenários de alta concorrência

Resource Management

• ✅ Proper disposal de HttpRequestMessage com using var
• ✅ Automatic cleanup de HttpResponseMessage no padrão IDisposable
• ✅ Memory leak prevention através de liberação adequada de recursos
• ✅ Compliance com CA2000 (análise estática do código)

// ✅ Exemplo de como a biblioteca gerencia recursos internamente:
using var message = new HttpRequestMessage(HttpMethod.Post, url)
{
    Content = new StringContent(jsonData, Encoding.UTF8, "application/json")
};

// HttpResponseMessage é automaticamente disposto via padrão IDisposable
var response = await httpClient.SendAsync(message, cancellationToken).ConfigureAwait(false);

Benefícios para sua aplicação:

Configurações Avançadas

Retry Policy Personalizada

// No Startup.cs
StandardHttpClientSetup.RetryTotal = 5;
StandardHttpClientSetup.BreakDurationMilliSeconds = 3000;

builder.Services.AddStandardHttpClientSetup(builder.Configuration);

JsonSerializerOptions Customizado

public class MeuClienteCustomizado : BaseStandardHttpClient
{
    public MeuClienteCustomizado(IStandardHttpClient standardHttpClient, ITokenService tokenService)
        : base(standardHttpClient, tokenService)
    {
        JsonSettings = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
            WriteIndented = true
        };
    }
}

Logging Detalhado

_httpClient.LogRequest = true; // Ativa logging detalhado

var resultado = await _httpClient
    .WithCurrelationHeader("REQ-001") // Para rastreamento
    .Get("api/dados", cancellationToken);

Console.WriteLine($"Correlation ID: {_httpClient.CorrelationId}");
Console.WriteLine($"URL completa: {_httpClient.FullUrl}");

Timeout Customizado

_httpClient.CreateClient("ClienteCustom");
_httpClient.Configure(
    timeOut: TimeSpan.FromMinutes(5),
    maxResponseContentBufferSize: 1024 * 1024, // 1MB
    httpCompletionOption: HttpCompletionOption.ResponseContentRead
);

API Reference

IStandardHttpClient

BaseStandardHttpClient

ITokenService

HttpStandardReturn

NotificationR

Troubleshooting

Problema: Token não é renovado automaticamente

Solução: Verifique se as configurações AppConfig:AppURLs:UrlLoginApi e AppConfig:AppURLs:UrlLoginApiToken estão corretas no appsettings.json.

Problema: Erro de SSL/TLS

Solução: Configure o HttpClientHandler com as certificações apropriadas:

services.AddServiceCredentialRegister(configuration)
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler()
    {
        ServerCertificateCustomValidationCallback = (sender, cert, chain, errors) => true
    });

Problema: Timeout em requisições longas

Solução: Configure timeout personalizado:

_httpClient.Configure(TimeSpan.FromMinutes(10));

Problema: Problema de encoding em QueryString

Solução: Use WithQueryString que faz encoding automático:

.WithQueryString("busca", "João & Maria") // Automaticamente encoded

Problema: Headers não estão sendo enviados

Solução: Use WithHeader antes da chamada HTTP e certifique-se de não chamar ResetStandardHttpClient() depois:

_httpClient.CreateClient();
// NÃO chame ResetStandardHttpClient() aqui
_httpClient.WithHeader("Custom-Header", "valor");
var result = await _httpClient.Get("api/dados");

Problema: Memory leaks ou alta utilização de memória

Solução: A biblioteca já implementa proper disposal automaticamente. Certifique-se de:

// ✅ Use IDisposable pattern se criar instâncias manuais
using var httpClientService = serviceProvider.GetService<IStandardHttpClient>();

// ✅ Em DI, a biblioteca gerencia recursos automaticamente
// Não é necessário disposal manual quando injetado via DI

Problema: Deadlocks em código síncrono

Solução: A biblioteca usa ConfigureAwait(false) internamente. Em seu código:

// ✅ Use async/await corretamente
var resultado = await _httpClient.Get("api/dados", cancellationToken);

// ❌ Evite .Result ou .Wait() em contextos síncronos
// var resultado = _httpClient.Get("api/dados").Result; // Pode causar deadlock

Problema: Notificações não estão sendo coletadas

Solução: Certifique-se de herdar de BaseStandardHttpClient e usar ExecuteWithTokenAsync:

public class MeuCliente : BaseStandardHttpClient
{
    public async Task<T> MinhaOperacao()
    {
        // ✅ Uso correto - notificações serão coletadas automaticamente
        var resultado = await ExecuteWithTokenAsync<T>(
            httpClient => httpClient.Get("api/dados")
        );

        // Verificar notificações após a operação
        if (Notifications.Any())
        {
            // Processar notificações...
        }
    }
}

Problema: Acesso concorrente às notificações

Solução: Use a propriedade Notifications que é thread-safe:

// ✅ Thread-safe via ReadOnlyCollection
var notificacoes = Notifications;

// ❌ Não acesse diretamente a lista interna
// var notificacoes = _notifications; // Campo privado

Problema: Muitas notificações acumuladas

Solução: Limpe as notificações periodicamente:

public async Task ProcessarLote()
{
    foreach (var item in lote)
    {
        ClearNotifications(); // Limpar antes de cada operação
        await ProcessarItem(item);

        // Processar notificações específicas do item
        ProcessarNotificacoes(item.Id);
    }
}

Changelog

Ver arquivo CHANGELOG.md para histórico detalhado de alterações.

📞 Suporte

Para dúvidas, issues ou contribuições:

• 🐛 Issues: GitHub Issues
• 📧 Email: suporte@zocate.li
• 📖 Documentação: Wiki do Projeto

Nuuvify CommonPack - Construindo soluções robustas para .NET 🚀