CG.Infrastructure.Http 3.10.7

CG.Infrastructure.Http

A comprehensive HTTP client library for .NET applications that provides robust HTTP operations, authentication support, proxy configuration, and response handling with multiple client types and security features.

Features

• HTTP Operations: Full CRUD operations (GET, POST, PUT, DELETE) with generic entity support
• Authentication Support: OAuth 2.0 client credentials and password grant flows
• Multiple Client Types: Basic, token-based, custom handler, and authenticated HTTP clients
• Custom Headers: Configurable custom HTTP headers with environment variable support
• Proxy Configuration: Configurable proxy settings for enterprise environments
• Response Handling: Multiple response formats (string, string array, generic entities)
• Discovery Document Support: OpenID Connect discovery document retrieval
• User Info Support: OAuth 2.0 user information retrieval
• Testing Utilities: API endpoint testing and link validation
• Network Utilities: Host ping functionality and connection testing
• Dependency Injection Ready: Easy integration with ASP.NET Core applications

Installation

dotnet add package CG.Infrastructure.Http

Quick Start

1. Register Services

using Infrastructure.Http.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register HTTP services
builder.Services.RegisterInfraHttpServices(builder.Configuration);

2. Inject and Use

public class MyController : ControllerBase
{
    private readonly IHttpService _httpService;

    public MyController(IHttpService httpService)
    {
        _httpService = httpService;
    }

    public async Task<IActionResult> GetData()
    {
        var response = await _httpService.Get("api/data");
        var data = await _httpService.GetResponseAsEntity<MyData>(response);
        return Ok(data);
    }
}

3. Add Configuration

{
  "ProxyOptions": {
    "UseProxy": false,
    "ProxyHost": "proxy.company.com",
    "ProxyPort": 8080
  },
  "IssuerOptions": {
    "Authority": "https://identity.example.com",
    "Audience": "my-api"
  },
  "CustomHeaders": {
    "Headers": {
      "x-gg-bot-access": "{{ENV:GG_BOT_ACCESS_TOKEN}}",
      "Accept": "application/json"
    }
  }
}

Core Services

IHttpService

Comprehensive HTTP service interface with authentication and response handling:

public interface IHttpService : IService
{
    // HTTP Operations
    Task<HttpResponseMessage?> Get(string? requestUri, TokenResponse? token = null, string? baseUrl = null, HttpClientEnum client = HttpClientEnum.Basic);
    Task<HttpResponseMessage?> Post<TEntity>(string? requestUri, TEntity? data, TokenResponse? token = null, string? baseUrl = null, HttpClientEnum client = HttpClientEnum.Basic);
    Task<HttpResponseMessage?> Put<TEntity>(string? requestUri, TEntity? data, TokenResponse? token = null, string? baseUrl = null, HttpClientEnum client = HttpClientEnum.Basic);
    Task<HttpResponseMessage?> Delete(string? requestUri, Guid? id, TokenResponse? token = null, string? baseUrl = null, HttpClientEnum client = HttpClientEnum.Basic);

    // Response Handling
    Task<string> GetResponseAsString(HttpResponseMessage response);
    Task<string[]> GetResponseAsStringArray(HttpResponseMessage response);
    Task<TEntity?> GetResponseAsEntity<TEntity>(HttpResponseMessage response);

    // Authentication
    Task<DiscoveryDocumentResponse?> GetDiscoveryDocument(string? requestUri, HttpClientEnum client = HttpClientEnum.Basic);
    Task<TokenResponse?> RequestClientToken(string? requestUri, ClientCredentialsTokenRequest request, HttpClientEnum client = HttpClientEnum.Basic);
    Task<TokenResponse?> RequestPasswordToken(string? requestUri, PasswordTokenRequest request, HttpClientEnum client = HttpClientEnum.Basic);
    Task<UserInfoResponse?> GetUserInfo(string? requestUri, UserInfoRequest request, HttpClientEnum client = HttpClientEnum.Basic);

    // Testing and Utilities
    Task<bool> Test(string? requestUri, string? format = null, HttpClientEnum client = HttpClientEnum.Basic);
    Task TestWithToken(TokenResponse? token, string? requestUri, string? format = null, HttpClientEnum client = HttpClientEnum.Basic);
    Task TestApiClientLinks(List<TestLink>? testLinks);
    bool PingHost(string? nameOrAddress);
}

HTTP Operations

Basic HTTP Requests

// GET request
var response = await _httpService.Get("api/users");

// POST request with entity
var user = new User { Name = "John", Email = "john@example.com" };
var response = await _httpService.Post("api/users", user);

// PUT request with entity
var updatedUser = new User { Id = 1, Name = "John Updated", Email = "john.updated@example.com" };
var response = await _httpService.Put("api/users/1", updatedUser);

// DELETE request
var response = await _httpService.Delete("api/users", Guid.Parse("12345678-1234-1234-1234-123456789012"));

Custom Header Requests

// GET request with custom headers (authenticated client)
var response = await _httpService.Get("api/protected", client: HttpClientEnum.Authenticated);

// POST request with custom headers
var response = await _httpService.Post("api/secure", data, client: HttpClientEnum.Authenticated);

// All HTTP methods support custom headers via HttpClientEnum.Authenticated

Response Handling

// Get response as string
var response = await _httpService.Get("api/data");
var content = await _httpService.GetResponseAsString(response);

// Get response as string array
var response = await _httpService.Get("api/items");
var items = await _httpService.GetResponseAsStringArray(response);

// Get response as typed entity
var response = await _httpService.Get("api/users");
var users = await _httpService.GetResponseAsEntity<List<User>>(response);

Authentication

OAuth 2.0 Client Credentials Flow

// Create client credentials request
var request = _httpService.GetClientCredentialsToken(
    "https://identity.example.com/connect/token",
    "client-id",
    "client-secret",
    "api-scope"
);

// Request token
var token = await _httpService.RequestClientToken(
    "https://identity.example.com/connect/token",
    request
);

// Use token for authenticated requests
var response = await _httpService.Get("api/protected", token);

OAuth 2.0 Password Grant Flow

// Create password token request
var securePassword = new SecureString();
foreach (char c in "password123") securePassword.AppendChar(c);

var request = _httpService.GetClientPasswordToken(
    "https://identity.example.com/connect/token",
    "client-id",
    "client-secret",
    "api-scope",
    "username",
    securePassword
);

// Request token
var token = await _httpService.RequestPasswordToken(
    "https://identity.example.com/connect/token",
    request
);

User Information

// Get user info request
var userInfoRequest = _httpService.GetUserInfoRequest(
    "https://identity.example.com/connect/userinfo",
    token
);

// Retrieve user information
var userInfo = await _httpService.GetUserInfo(
    "https://identity.example.com/connect/userinfo",
    userInfoRequest
);

Discovery Document

// Get OpenID Connect discovery document
var discovery = await _httpService.GetDiscoveryDocument(
    "https://identity.example.com"
);

if (discovery != null)
{
    var tokenEndpoint = discovery.TokenEndpoint;
    var userInfoEndpoint = discovery.UserInfoEndpoint;
}

Client Types

HttpClientEnum

public enum HttpClientEnum
{
    Basic = 1,          // Standard HTTP client
    Token = 2,          // Token-based authentication client
    Handler = 3,        // Custom message handler client
    Authenticated = 4   // Client with custom headers (e.g., API keys, custom Accept)
}

Client Usage Examples

// Basic client (default)
var response = await _httpService.Get("api/data", client: HttpClientEnum.Basic);

// Token-based client
var response = await _httpService.Get("api/protected", token, client: HttpClientEnum.Token);

// Custom handler client
var response = await _httpService.Get("api/data", client: HttpClientEnum.Handler);

// Authenticated client with custom headers
var response = await _httpService.Get("api/secure", client: HttpClientEnum.Authenticated);

Custom Header Behavior

When using HttpClientEnum.Authenticated:

• Custom headers are applied first from the configuration
• Default headers are applied as fallback if no custom headers are configured
• Custom headers override defaults (e.g., custom Accept header takes precedence)
• Environment variables are resolved at runtime for sensitive values
• Fallback to default behavior if custom headers are not configured

Configuration Options

ProxyOptions

public class ProxyOptions
{
    public string? Url { get; set; }                    // Proxy URL
    public bool UseProxy { get; set; } = false;         // Enable/disable proxy
    public string? ProxyHost { get; set; }              // Proxy hostname
    public int ProxyPort { get; set; }                  // Proxy port number
}

CustomHeaderOptions

public class CustomHeaderOptions
{
    public Dictionary<string, string> Headers { get; set; } = new();
}

Configuration Example

{
  "ProxyOptions": {
    "UseProxy": true,
    "ProxyHost": "proxy.company.com",
    "ProxyPort": 8080
  },
  "CustomHeaders": {
    "Headers": {
      "x-api-key": "{{ENV:API_KEY}}",
      "x-gg-bot-access": "{{ENV:GG_BOT_ACCESS_TOKEN}}",
      "Accept": "application/json",
      "User-Agent": "MyApp/1.0"
    }
  }
}

Environment Variable Support

Custom headers support environment variable substitution using the {{ENV:VARIABLE_NAME}} syntax:

# Set environment variables
export API_KEY="your-api-key-here"
export GG_BOT_ACCESS_TOKEN="your-bot-token-here"

# Or in Windows PowerShell
$env:API_KEY="your-api-key-here"
$env:GG_BOT_ACCESS_TOKEN="your-bot-token-here"

Advanced Usage

Custom HTTP Message Handler

public class CustomHttpMessageHandler : HttpMessageHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, 
        CancellationToken cancellationToken)
    {
        // Custom logic before request
        request.Headers.Add("X-Custom-Header", "CustomValue");
        
        // Send request
        var response = await base.SendAsync(request, cancellationToken);
        
        // Custom logic after response
        return response;
    }
}

// Use custom handler
var handler = new CustomHttpMessageHandler();
var httpService = new HttpService(logger, proxyOptions, issuerOptions, 
    serializationService, substringService, secureStringService, handler);

Base URL Configuration

// Use base URL for all requests
var response = await _httpService.Get("users", baseUrl: "https://api.example.com");
// Results in: https://api.example.com/users

// Combine base URL with specific endpoint
var response = await _httpService.Post("users", user, baseUrl: "https://api.example.com");
// Results in: https://api.example.com/users

Testing Utilities

// Test endpoint availability
var isAvailable = await _httpService.Test("https://api.example.com/health");

// Test with specific format
var isAvailable = await _httpService.Test("https://api.example.com/health", "json");

// Test with authentication token
await _httpService.TestWithToken(token, "https://api.example.com/protected");

// Test multiple API client links
var testLinks = new List<TestLink>
{
    new TestLink
    {
        TokenEndpoint = "https://identity.example.com/connect/token",
        ClientId = "client-id",
        ClientSecret = "client-secret",
        ClientScope = "api-scope",
        Links = new Dictionary<string, string?>
        {
            { "Users", "https://api.example.com/users" },
            { "Orders", "https://api.example.com/orders" }
        }
    }
};

await _httpService.TestApiClientLinks(testLinks);

Network Utilities

// Ping host to check connectivity
var isReachable = _httpService.PingHost("api.example.com");
var isReachable = _httpService.PingHost("192.168.1.1");

Service Registration

Automatic Registration

public static class ServiceCollectionExtensions
{
    public static IServiceCollection RegisterInfraHttpServices(
        this IServiceCollection services, 
        IConfiguration configuration)
    {
        services.RegisterProxyOptions(configuration);
        services.RegisterCustomHeaderOptions(configuration);
        
        // Register HttpClient as singleton with default headers
        services.AddHttpClient<HttpService>(client =>
        {
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(
                new MediaTypeWithQualityHeaderValue("application/json"));
        });

        return services;
    }
}

Manual Registration

services.AddSingleton<ProxyOptions>(provider =>
{
    var configuration = provider.GetRequiredService<IConfiguration>();
    var proxyOptions = new ProxyOptions();
    
    configuration.GetSection("ProxyOptions").Bind(proxyOptions);
    
    return proxyOptions;
});

services.AddHttpClient<HttpService>();
services.AddScoped<IHttpService, HttpService>();

Error Handling

Response Validation

var response = await _httpService.Get("api/data");

if (response != null && response.IsSuccessStatusCode)
{
    var data = await _httpService.GetResponseAsEntity<MyData>(response);
    return Ok(data);
}
else
{
    var errorContent = response != null 
        ? await _httpService.GetResponseAsString(response)
        : "No response received";
    
    return BadRequest($"Request failed: {errorContent}");
}

Exception Handling

try
{
    var response = await _httpService.Get("api/data");
    var data = await _httpService.GetResponseAsEntity<MyData>(response);
    return Ok(data);
}
catch (HttpRequestException ex)
{
    logger.LogError(ex, "HTTP request failed");
    return StatusCode(500, "External service unavailable");
}
catch (Exception ex)
{
    logger.LogError(ex, "Unexpected error");
    return StatusCode(500, "Internal server error");
}

Best Practices

1. Client Management: Use appropriate client types for different scenarios
2. Token Handling: Store and reuse tokens when possible to reduce authentication calls
3. Error Handling: Always check response status and handle errors gracefully
4. Configuration: Use strongly-typed configuration options for proxy and issuer settings
5. Logging: Leverage built-in logging for debugging and monitoring
6. Security: Use secure string handling for sensitive data like passwords
7. Testing: Use built-in testing utilities to validate API endpoints
8. Base URLs: Configure base URLs for consistent endpoint management
9. Custom Headers: Use environment variables for sensitive header values
10. Header Security: Never hardcode API keys or tokens in configuration files

Dependencies

• CG.Infrastructure.Configuration (3.10.1) - Configuration management
• CG.Infrastructure.Services (3.10.2) - Shared service implementations
• IdentityModel (7.0.0) - OAuth 2.0 and OpenID Connect support
• Microsoft.Extensions.Http (9.0.8) - HTTP client factory

Performance Considerations

• Connection Pooling: HTTP clients are managed efficiently with connection pooling
• Token Caching: Implement token caching to reduce authentication overhead
• Response Streaming: Use streaming for large response payloads
• Timeout Configuration: Set appropriate timeouts for different operations
• Proxy Optimization: Configure proxy settings for optimal network performance

Security Features

• Secure String Handling: Secure string support for sensitive data
• Token-based Authentication: OAuth 2.0 token management
• Proxy Support: Enterprise proxy configuration
• HTTPS Enforcement: Built-in support for secure connections
• Header Management: Custom header support for security requirements

Troubleshooting

Common Issues

1. Proxy Configuration: Verify proxy settings match your network environment
2. Authentication Failures: Check client credentials and scopes
3. Timeout Issues: Adjust timeout settings for slow networks
4. SSL/TLS Errors: Ensure proper certificate validation
5. Response Parsing: Verify response format matches expected entity types
6. Custom Header Issues: Check environment variable names and values
7. Header Override Problems: Verify custom headers are properly configured

Debug Mode

Enable detailed logging for troubleshooting:

// In appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Infrastructure.Http": "Debug"
    }
  }
}

Version History

• 3.10.4: Current release with comprehensive HTTP operations
• 3.10.3: Enhanced authentication and testing features
• 3.10.2: Improved proxy and client type support
• 3.10.1: Initial HTTP service framework
• 3.10.0: Foundation release

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Create an issue in the repository
• Check the documentation
• Review the test examples

CG.Infrastructure.Http - Robust HTTP operations for modern .NET applications.