< Summary - Kestrun — Combined Coverage

Information
Class: Public.Middleware.Add-KrForwardHeader
Assembly: Kestrun.PowerShell.Public
File(s): /home/runner/work/Kestrun/Kestrun/src/PowerShell/Kestrun/Public/Middleware/Add-KrForwardHeader.ps1
Tag: Kestrun/Kestrun@2d87023b37eb91155071c91dd3d6a2eeb3004705
Line coverage
0%
Covered lines: 0
Uncovered lines: 44
Coverable lines: 44
Total lines: 203
Line coverage: 0%
Branch coverage
N/A
Covered branches: 0
Total branches: 0
Branch coverage: N/A
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Coverage history

Coverage history 0 25 50 75 100 10/17/2025 - 15:48:30 Line coverage: 0% (0/44) Total lines: 203 Tag: Kestrun/Kestrun@b8199aff869a847b75e185d0527ba45e04a43d86

Metrics

Method
Add-KrForwardedHeader()

File(s)

/home/runner/work/Kestrun/Kestrun/src/PowerShell/Kestrun/Public/Middleware/Add-KrForwardHeader.ps1

#LineLine coverage
 1<#
 2.SYNOPSIS
 3    Adds Forwarded Headers middleware to a Kestrun server.
 4.DESCRIPTION
 5    This cmdlet adds and configures the ASP.NET Core Forwarded Headers middleware
 6    for a Kestrun server. This middleware processes proxy-related headers such as
 7    X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Prefix to
 8    update the request's Scheme, Host, and Remote IP address accordingly.
 9    This is essential when hosting behind reverse proxies or load balancers that
 10    modify these headers.
 11.PARAMETER Server
 12    The Kestrun server instance to which the Forwarded Headers middleware will be added.
 13    If not specified, the cmdlet will attempt to resolve the current server context.
 14.PARAMETER Options
 15    An instance of Microsoft.AspNetCore.Builder.ForwardedHeadersOptions to configure
 16    the middleware. This allows for full customization of the middleware behavior.
 17.PARAMETER XForwardedFor
 18    Switch to enable processing of the X-Forwarded-For header.
 19.PARAMETER XForwardedProto
 20    Switch to enable processing of the X-Forwarded-Proto header.
 21.PARAMETER XForwardedHost
 22    Switch to enable processing of the X-Forwarded-Host header.
 23.PARAMETER XForwardedPrefix
 24    Switch to enable processing of the X-Forwarded-Prefix header.
 25.PARAMETER All
 26    Switch to enable processing of all supported forwarded headers.
 27.PARAMETER ForwardLimit
 28    Specifies the maximum number of entries to read from the forwarded headers.
 29    Default is 1.
 30.PARAMETER KnownNetworks
 31    An array of IPNetwork objects representing known networks from which forwarded
 32    headers will be accepted.
 33.PARAMETER KnownProxies
 34    An array of IPAddress objects representing known proxy servers from which
 35    forwarded headers will be accepted.
 36.PARAMETER ForwardedForHeaderName
 37    Custom header name for X-Forwarded-For.
 38.PARAMETER ForwardedProtoHeaderName
 39    Custom header name for X-Forwarded-Proto.
 40.PARAMETER ForwardedHostHeaderName
 41    Custom header name for X-Forwarded-Host.
 42.PARAMETER ForwardedPrefixHeaderName
 43    Custom header name for X-Forwarded-Prefix.
 44.PARAMETER OriginalForHeaderName
 45    Custom header name for Original-For.
 46.PARAMETER OriginalProtoHeaderName
 47    Custom header name for Original-Proto.
 48.PARAMETER OriginalHostHeaderName
 49    Custom header name for Original-Host.
 50.PARAMETER OriginalPrefixHeaderName
 51    Custom header name for Original-Prefix.
 52.PARAMETER RequireHeaderSymmetry
 53    Switch to require that all enabled forwarded headers are present in the request.
 54.PARAMETER PassThru
 55    If specified, the cmdlet returns the Kestrun server instance after adding
 56    the middleware.
 57.EXAMPLE
 58    Add-KrForwardedHeader -XForwardedFor -XForwardedProto -KnownProxies $proxyIps
 59    Adds Forwarded Headers middleware to the current Kestrun server, enabling
 60    processing of X-Forwarded-For and X-Forwarded-Proto headers, and
 61    trusting the specified proxy IP addresses.
 62.NOTES
 63    This cmdlet is part of the Kestrun PowerShell module.
 64#>
 65function Add-KrForwardedHeader {
 66    [KestrunRuntimeApi('Definition')]
 67    [CmdletBinding(DefaultParameterSetName = 'Items')]
 68    [OutputType([Kestrun.Hosting.KestrunHost])]
 69    param(
 70        [Parameter(ValueFromPipeline = $true)]
 71        [Kestrun.Hosting.KestrunHost]$Server,
 72
 73        # --- ParameterSet: Options (verbatim pass-through) ---
 74        [Parameter(Mandatory = $true, ParameterSetName = 'Options')]
 75        [Microsoft.AspNetCore.Builder.ForwardedHeadersOptions]$Options,
 76
 77        # --- ParameterSet: Items (switches compose the enum) ---
 78        [Parameter(ParameterSetName = 'Items')]
 79        [switch]$XForwardedFor,
 80        [Parameter(ParameterSetName = 'Items')]
 81        [switch]$XForwardedProto,
 82        [Parameter(ParameterSetName = 'Items')]
 83        [switch]$XForwardedHost,
 84        [Parameter(ParameterSetName = 'Items')]
 85        [switch]$XForwardedPrefix,
 86        [Parameter(ParameterSetName = 'Items')]
 87        [switch]$All,  # convenience
 88
 89        [Parameter(ParameterSetName = 'Items')]
 90        [int]$ForwardLimit = 1,
 91
 92        [Parameter(ParameterSetName = 'Items')]
 93        [string[]]$KnownNetworks,
 94        [Parameter(ParameterSetName = 'Items')]
 95        [string[]]$KnownProxies,
 96
 97        # Optional header name overrides (default to ForwardedHeadersDefaults)
 98        [Parameter(ParameterSetName = 'Items')]
 99        [string]$ForwardedForHeaderName,
 100        [Parameter(ParameterSetName = 'Items')]
 101        [string]$ForwardedProtoHeaderName,
 102        [Parameter(ParameterSetName = 'Items')]
 103        [string]$ForwardedHostHeaderName,
 104        [Parameter(ParameterSetName = 'Items')]
 105        [string]$ForwardedPrefixHeaderName,
 106        [Parameter(ParameterSetName = 'Items')]
 107        [string]$OriginalForHeaderName,
 108        [Parameter(ParameterSetName = 'Items')]
 109        [string]$OriginalProtoHeaderName,
 110        [Parameter(ParameterSetName = 'Items')]
 111        [string]$OriginalHostHeaderName,
 112        [Parameter(ParameterSetName = 'Items')]
 113        [string]$OriginalPrefixHeaderName,
 114
 115        [Parameter(ParameterSetName = 'Items')]
 116        [switch]$RequireHeaderSymmetry,
 117
 118        [switch]$PassThru
 119    )
 120    begin {
 0121        $Server = Resolve-KestrunServer -Server $Server
 122    }
 123    process {
 0124        if ($PSCmdlet.ParameterSetName -eq 'Items') {
 125            # Compose ForwardedHeadersOptions from switches
 0126            $fhEnum = [Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders]
 127
 128            # Create options
 0129            $Options = [Microsoft.AspNetCore.Builder.ForwardedHeadersOptions]::new()
 130            # Compose flags from switches
 0131            if ($All) {
 0132                $Options.ForwardedHeaders = [Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders]::All
 133            } else {
 0134                $flags = $fhEnum::None
 0135                if ($XForwardedFor) { $flags = $flags -bor $fhEnum::XForwardedFor }
 0136                if ($XForwardedProto) { $flags = $flags -bor $fhEnum::XForwardedProto }
 0137                if ($XForwardedHost) { $flags = $flags -bor $fhEnum::XForwardedHost }
 0138                if ($XForwardedPrefix) { $flags = $flags -bor $fhEnum::XForwardedPrefix }
 0139                if ($flags -eq $fhEnum::None) {
 140                    # Sensible default if user didn’t specify: For + Proto
 0141                    $flags = $fhEnum::XForwardedFor -bor $fhEnum::XForwardedProto
 142                }
 0143                $Options.ForwardedHeaders = $flags
 144            }
 145
 146            # Forward limit
 0147            $Options.ForwardLimit = $ForwardLimit
 148
 149            # Known proxies
 0150            if ($PSBoundParameters.ContainsKey('KnownProxies')) {
 0151                $Options.KnownProxies.Clear()
 0152                foreach ($p in $KnownProxies) {
 0153                    $ip = if ($p -is [System.Net.IPAddress]) { $p } else { [System.Net.IPAddress]::Parse($p) }
 0154                    [void]$Options.KnownProxies.Add($ip)
 155                }
 156            }
 157            # Known networks
 0158            if ($PSBoundParameters.ContainsKey('KnownNetworks')) {
 0159                $Options.KnownNetworks.Clear()
 0160                foreach ($n in $KnownNetworks) {
 161                    # Allow "10.0.0.0/24" or IPNetwork objects directly
 0162                    $net = if ($n -is [System.Net.IPNetwork]) { $n } else { [System.Net.IPNetwork]::Parse($n) }
 0163                    [void]$Options.KnownNetworks.Add($net)
 164                }
 165            }
 166            # Custom header names
 0167            if ($PSBoundParameters.ContainsKey('ForwardedForHeaderName')) {
 0168                $Options.ForwardedForHeaderName = $ForwardedForHeaderName
 169            }
 0170            if ($PSBoundParameters.ContainsKey('ForwardedProtoHeaderName')) {
 0171                $Options.ForwardedProtoHeaderName = $ForwardedProtoHeaderName
 172            }
 0173            if ($PSBoundParameters.ContainsKey('ForwardedHostHeaderName')) {
 0174                $Options.ForwardedHostHeaderName = $ForwardedHostHeaderName
 175            }
 0176            if ($PSBoundParameters.ContainsKey('ForwardedPrefixHeaderName')) {
 0177                $Options.ForwardedPrefixHeaderName = $ForwardedPrefixHeaderName
 178            }
 0179            if ($PSBoundParameters.ContainsKey('OriginalForHeaderName')) {
 0180                $Options.OriginalForHeaderName = $OriginalForHeaderName
 181            }
 0182            if ($PSBoundParameters.ContainsKey('OriginalProtoHeaderName')) {
 0183                $Options.OriginalProtoHeaderName = $OriginalProtoHeaderName
 184            }
 0185            if ($PSBoundParameters.ContainsKey('OriginalHostHeaderName')) {
 0186                $Options.OriginalHostHeaderName = $OriginalHostHeaderName
 187            }
 0188            if ($PSBoundParameters.ContainsKey('OriginalPrefixHeaderName')) {
 0189                $Options.OriginalPrefixHeaderName = $OriginalPrefixHeaderName
 190            }
 191
 192            # Symmetry
 0193            $Options.RequireHeaderSymmetry = $RequireHeaderSymmetry.IsPresent
 194        }
 195
 196        # Attach to server so host.Apply() can call app.UseForwardedHeaders($Options)
 0197        $Server.ForwardedHeaderOptions = $Options
 198
 0199        if ($PassThru) { return $Server }
 200    }
 201}
 202
 203
Generated by: ReportGenerator 5.4.17.0
10/18/2025 - 15:14:40
GitHub | reportgenerator.io

Methods/Properties

Add-KrForwardedHeader()