Argon.Extensions.Hosting.Abstractions

Configuration classes and abstractions for ASP.NET Core hosting.

📦 Installation

dotnet add package Argon.Extensions.Hosting.Abstractions

✨ Features

• HostingConfiguration: Main configuration class for hosting features
• HealthChecksConfiguration: Configuration for health checks endpoints
• ForwardedHeadersConfiguration: Configuration for forwarded headers middleware with JSON-based setup

🚀 Usage

This package provides configuration classes used by Argon.Extensions.Hosting. It's typically installed automatically as a dependency.

HostingConfiguration

The main configuration class that aggregates all hosting-related configurations.

using Argon.Extensions.Hosting.Abstractions.Configuration;

var hostingConfig = new HostingConfiguration
{
    PathBase = "/api",
    ForwardedHeaders = new ForwardedHeadersConfiguration
    {
        ForwardedHeaders = ForwardedHeaders.All,
        KnownProxies = new List<string> { "10.0.0.1" }
    },
    HealthChecks = new HealthChecksConfiguration
    {
        PathBase = "/health",
        HostRequirements = "*:9090"
    }
};

Configuration via appsettings.json:

{
  "Hosting": {
    "PathBase": "/api",
    "ForwardedHeaders": {
      "ForwardedHeaders": "All",
      "KnownProxies": ["10.0.0.1"],
      "KnownNetworks": ["10.0.0.0/8"]
    },
    "HealthChecks": {
      "PathBase": "/health",
      "HostRequirements": "*:9090"
    }
  }
}

HealthChecksConfiguration

Configuration for health checks endpoints with support for path base and host restrictions.

Properties:

• PathBase (string): Base path for health checks (default: /health)
• HostRequirements (string): Host/port requirements for access (default: *:9090).
  • Uses local port validation (works with Docker port mapping)
  • Supports multiple patterns separated by commas (OR logic)
  • Supports scheme validation (e.g., https://*:9090)
  • Supports wildcard subdomains (e.g., *.example.com:9090)
  • Empty string = no restrictions

Example:

// Basic port restriction (validates local port)
var config = new HealthChecksConfiguration
{
    PathBase = "/health",
    HostRequirements = "*:9090" // Any host on local port 9090
};

// Multiple patterns (OR logic - any match is accepted):
var multiConfig = new HealthChecksConfiguration
{
    HostRequirements = "localhost:9090,*.internal:9090"
};

// With scheme:
var httpsConfig = new HealthChecksConfiguration
{
    HostRequirements = "https://*:9090" // Only HTTPS on port 9090
};

// For Docker with port mapping (9090:9005):
var dockerConfig = new HealthChecksConfiguration
{
    PathBase = "/health",
    HostRequirements = "*:9005" // Use the INTERNAL port
};

// For public access (no restriction):
var publicConfig = new HealthChecksConfiguration
{
    PathBase = "/health",
    HostRequirements = "" // Empty = no restriction
};

Use cases:

• Restrict health checks to internal monitoring ports
• Separate health check traffic from application traffic
• Kubernetes/container orchestration health probes

ForwardedHeadersConfiguration

Configuration for the Forwarded Headers middleware with full JSON configuration support.

Key Properties:

• ForwardedHeaders (ForwardedHeaders?): Which headers to forward (XForwardedFor, XForwardedHost, XForwardedProto, etc.)
• ForwardLimit (int?): Maximum number of headers to process
• KnownProxies (List): IP addresses of known proxies
• KnownNetworks (List): CIDR ranges of known proxy networks
• AllowedHosts (List): Allowed values for X-Forwarded-Host
• RequireHeaderSymmetry (bool?): Require same number of values in all forwarded headers

Header Name Customization:

• ForwardedForHeaderName
• ForwardedHostHeaderName
• ForwardedProtoHeaderName
• OriginalForHeaderName
• OriginalHostHeaderName
• OriginalProtoHeaderName

Example:

var config = new ForwardedHeadersConfiguration
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto,
    ForwardLimit = 2,
    KnownProxies = new List<string> { "10.0.0.1", "10.0.0.2" },
    KnownNetworks = new List<string> { "10.0.0.0/8", "172.16.0.0/12" },
    AllowedHosts = new List<string> { "example.com", "*.example.com" },
    RequireHeaderSymmetry = true
};

// Convert to ForwardedHeadersOptions for middleware
var options = config.GetMiddlewareOptions();

Configuration via appsettings.json:

{
  "Hosting": {
    "ForwardedHeaders": {
      "ForwardedHeaders": "XForwardedFor, XForwardedProto",
      "ForwardLimit": 2,
      "KnownProxies": ["10.0.0.1", "10.0.0.2"],
      "KnownNetworks": ["10.0.0.0/8", "172.16.0.0/12"],
      "AllowedHosts": ["example.com", "*.example.com"],
      "RequireHeaderSymmetry": true
    }
  }
}

Network notation:

• IP addresses: "10.0.0.1"
• CIDR notation: "10.0.0.0/8", "172.16.0.0/12"

📝 API Reference

HostingConfiguration

HealthChecksConfiguration

ForwardedHeadersConfiguration

Methods:

• GetMiddlewareOptions(): Converts configuration to ForwardedHeadersOptions for use with ASP.NET Core middleware

Properties: See detailed list in the "ForwardedHeadersConfiguration" section above.

🔗 Links

• Back to main project
• Hosting package
• NuGet Package