CG.Infrastructure.Responses 3.10.11

CG.Infrastructure.Responses

A .NET 10.0 library that provides comprehensive HTTP response handling services for web API interactions, including authentication, entity management, and response processing.

Overview

This library offers a robust set of response services designed to handle various HTTP operations in .NET applications. It provides both basic HTTP response handling and advanced features like authentication token management, entity CRUD operations, and response serialization.

Features

Core Response Services

• HTTP Response Handling: Process and extract content from HTTP responses
• Entity Management: CRUD operations for various entity types
• Authentication Support: OAuth2 client credentials and password flows
• Response Serialization: Convert responses to strongly-typed entities
• Error Handling: Comprehensive logging and exception management
• Custom Header Support: HTTP requests with configurable custom headers

HTTP Operations

• GET Operations: Retrieve entities and web responses
• POST Operations: Create entities and return responses or GUIDs
• PUT Operations: Update existing entities
• DELETE Operations: Remove entities by ID
• Response Processing: Convert responses to strings, arrays, or typed objects

Authentication & Security

• OAuth2 Integration: Support for client credentials and password flows
• Token Management: Handle authentication tokens and user info requests
• Token Caching: Smart token reuse with automatic refresh when expired
• Discovery Documents: OAuth2 discovery document support
• Secure Password Handling: SecureString support for password operations

Response Processing

• Content Extraction: Extract string content from HTTP responses
• Array Processing: Handle array-based responses
• File Output: Save responses to file paths
• Type Conversion: Automatic deserialization to strongly-typed entities

Dependencies

• CG.Infrastructure.Http (3.10.7) - HTTP client and request handling
• CG.Infrastructure.Services (3.10.6) - Service layer abstractions
• IdentityModel.Client - OAuth2 and OpenID Connect client library

Custom Header Integration

The custom header functionality integrates with CG.Infrastructure.Http:

• HttpClientEnum.Authenticated: Used internally for custom header requests
• CustomHeaderOptions: Configuration binding from appsettings.json
• Automatic Registration: Custom headers are registered via RegisterInfraHttpServices
• Fallback Behavior: Defaults to standard HTTP client if no custom headers configured

Key Components

IResponseService Interface

public interface IResponseService : IService
{
 // HTTP Response Operations
 Task<HttpResponseMessage?> GetWebResponse(string? requestUri);
 Task<HttpResponseMessage?> GetWebResponseWithCustomHeaders(string? requestUri);
 Task<string> GetResponseAsString(HttpResponseMessage response);
 Task<string[]> GetResponseAsStringArray(HttpResponseMessage response);
 
 // Entity CRUD Operations
 Task<TEntity?> GetEntity<TEntity>(string? requestUri, string? baseUrl, TokenResponse? token);
 Task<TEntity?> GetEntityFromPost<TEntity>(string? requestUri, TEntity? entity, string? baseUrl, TokenResponse? token);
 Task<TEntity?> GetEntityFromPut<TEntity>(string? requestUri, TEntity? entity, string? baseUrl, TokenResponse? token);
 Task DeleteEntity(string? requestUri, Guid? id, string? baseUrl, TokenResponse? token);
 
 // Authentication Operations
 Task<TokenResponse?> GetClientCredentialsToken(string clientId, string? clientSecret, string? clientScope);
 Task<TokenResponse?> GetClientPasswordToken(string clientId, string? clientSecret, string? clientScope, string userName, SecureString password);
 Task<UserInfoResponse?> GetUserInfoRequest(TokenResponse token);
 bool IsTokenExpired(TokenResponse? token);
 Task<TokenResponse?> GetValidTokenAsync(string clientId, string? clientSecret, string? clientScope, TokenResponse? currentToken);
}

ResponseService Implementation

• Handles all HTTP operations with proper error handling
• Integrates with logging, HTTP, serialization, and document services
• Provides comprehensive response processing capabilities
• Supports both authenticated and unauthenticated requests

ServiceCollectionExtensions

• Provides dependency injection registration for response services
• Integrates with HTTP service registration
• Enables easy service configuration

Usage Examples

Basic HTTP Response Handling

var responseService = serviceProvider.GetService<IResponseService>();

// Get web response
var response = await responseService.GetWebResponse("https://api.example.com/data");

// Get web response with custom headers (API keys, custom Accept, etc.)
var authenticatedResponse = await responseService.GetWebResponseWithCustomHeaders("https://api.example.com/secure");

// Extract content as string
var content = await responseService.GetResponseAsString(response);

// Extract content as string array
var lines = await responseService.GetResponseAsStringArray(response);

Entity Operations

var responseService = serviceProvider.GetService<IResponseService>();

// Get entity with authentication
var entity = await responseService.GetEntity<MyEntity>(
 "api/entities/123", 
 "https://api.example.com", 
 authToken
);

// Create entity via POST
var newEntity = await responseService.GetEntityFromPost<MyEntity>(
 "api/entities", 
 entityData, 
 "https://api.example.com", 
 authToken
);

// Get GUID from POST response
var id = await responseService.GetGuidFromPost<MyEntity>(
 "api/entities", 
 entityData, 
 "https://api.example.com", 
 authToken
);

Authentication

var responseService = serviceProvider.GetService<IResponseService>();

// Get client credentials token
var token = await responseService.GetClientCredentialsToken(
 "clientId", 
 "clientSecret", 
 "api.scope"
);

// Get user info
var userInfo = await responseService.GetUserInfoRequest(token);

// Check if token has expired
if (responseService.IsTokenExpired(token))
{
 // Token is expired, get a new one
 token = await responseService.GetClientCredentialsToken(
 "clientId", 
 "clientSecret", 
 "api.scope"
 );
}

Token Management with Caching

var responseService = serviceProvider.GetService<IResponseService>();
TokenResponse? cachedToken = null;

// Get valid token (reuses existing if valid, gets new if expired/null)
var token = await responseService.GetValidTokenAsync(
 "clientId", 
 "clientSecret", 
 "api.scope",
 cachedToken
);

// Use token for API calls
var entity = await responseService.GetEntity<MyEntity>(
 "api/entities/123", 
 "https://api.example.com", 
 token
);

// Update cached token for future use
cachedToken = token;

Custom Header Support

The GetWebResponseWithCustomHeaders method provides HTTP requests with configurable custom headers:

var responseService = serviceProvider.GetService<IResponseService>();

// Make authenticated request with custom headers
var response = await responseService.GetWebResponseWithCustomHeaders("https://api.example.com/protected");

// Custom headers are automatically applied based on configuration
// Common use cases include:
// - API key authentication (x-api-key, x-gg-bot-access)
// - Custom Accept headers
// - User-Agent specification
// - Custom authentication tokens

Configuration Required:

• Custom headers must be configured in appsettings.json
• Environment variables are supported for sensitive values
• Headers are automatically applied when using this method
• Falls back to default behavior if no custom headers are configured

Configuration

The library integrates with the .NET dependency injection container and can be configured through standard service registration:

// Register response services
services.RegisterInfraResponseServices(configuration);

// Or register individually
services.AddScoped<IResponseService, ResponseService>();

Custom Header Configuration

To use custom headers, configure them in your appsettings.json:

{
 "CustomHeaders": {
 "Headers": {
 "x-gg-bot-access": "{{ENV:GG_BOT_ACCESS_TOKEN}}",
 "Accept": "application/json",
 "User-Agent": "MyApp/1.0"
 }
 }
}

Environment Variable Support:

# Set environment variables
export GG_BOT_ACCESS_TOKEN="your-token-here"

# Or in Windows PowerShell
$env:GG_BOT_ACCESS_TOKEN="your-token-here"

Requirements

• .NET 10.0 or later
• Access to HTTP endpoints and services
• OAuth2/OpenID Connect provider (for authentication features)
• Proper configuration for HTTP services and serialization

Architecture

The library follows a layered architecture pattern:

• Interface Layer: Defines contracts for response services
• Service Layer: Implements business logic and HTTP operations
• Extension Layer: Provides dependency injection configuration
• Integration Layer: Works with HTTP, serialization, and document services

Best Practices

Custom Header Usage

• Use environment variables for sensitive header values (API keys, tokens)
• Configure fallback headers for consistent behavior
• Test header configuration in development before production
• Monitor header application through logging

Security Considerations

• Never hardcode sensitive values in configuration files
• Use environment variables for production deployments
• Rotate API keys regularly and update environment variables
• Validate header values to prevent injection attacks

Error Handling

• Comprehensive logging for all operations
• Graceful fallbacks for failed requests
• Exception handling with detailed error messages
• Null-safe response processing

License

This project is part of the CG Infrastructure Libraries and follows the same licensing terms as the parent project.

Contributing

Please refer to the main project documentation for contribution guidelines and coding standards.