functions/Get-HttpHeaderValue.ps1

# <copyright file="Get-HttpHeaderValue.ps1" company="Endjin Limited">
# Copyright (c) Endjin Limited. All rights reserved.
# </copyright>

function Get-HttpHeaderValue {
    <#
        .SYNOPSIS
            Extracts and validates HTTP header values from a headers collection with type conversion.
 
        .DESCRIPTION
            This function searches for a specific HTTP header in a headers collection and attempts to convert it to the specified type.
            It provides robust error handling, case-insensitive header matching, and verbose logging for debugging.
 
        .PARAMETER Headers
            The collection of HTTP headers to search through. Each header should have a Key and Value property.
 
        .PARAMETER HeaderName
            The name of the header to search for (case-insensitive).
 
        .PARAMETER ExpectedType
            The .NET type to convert the header value to (e.g., [int], [datetime], [string], [double]).
 
        .PARAMETER DefaultValue
            The default value to return if the header is not found or cannot be parsed.
            Must be compatible with ExpectedType.
 
        .OUTPUTS
            System.Object
 
        .EXAMPLE
            ```powershell
            $retryAfter = Get-HttpHeaderValue -Headers $response.Headers -HeaderName "Retry-After" -ExpectedType ([int]) -DefaultValue 0
            ```
 
        .EXAMPLE
            ```powershell
            $headers = $response.Headers
            $resetTime = Get-HttpHeaderValue -Headers $headers -HeaderName "X-RateLimit-Reset" -ExpectedType ([long]) -DefaultValue 0
            if ($resetTime -gt 0) {
                $resetDateTime = [datetime]::FromFileTimeUtc($resetTime)
            }
            ```
 
        .EXAMPLE
            ```powershell
            $customValue = Get-HttpHeaderValue -Headers $response.Headers -HeaderName "X-Custom-Header" -ExpectedType ([string]) -DefaultValue "default"
            ```
    #>

    [CmdletBinding()]
    [OutputType([Object])]
    param (
        [Parameter(Mandatory=$true)]
        [AllowNull()]
        [AllowEmptyCollection()]
        [object[]] $Headers,
        
        [Parameter(Mandatory=$true)]
        [string] $HeaderName,
        
        [Parameter(Mandatory=$true)]
        [type] $ExpectedType,
        
        [Parameter()]
        [object] $DefaultValue = $null
    )
    
    # Handle null or empty headers collection
    if (-not $Headers -or $Headers.Count -eq 0) {
        Write-Verbose "Headers collection is null or empty. Returning default value for header '$HeaderName'."
        return $DefaultValue
    }
    
    # Search for header (case-insensitive)
    $header = $Headers | Where-Object { $_.Key -ieq $HeaderName }
    
    if (-not $header) {
        Write-Verbose "Header '$HeaderName' not found in headers collection. Returning default value."
        return $DefaultValue
    }
    
    # Handle case where header exists but has no value or empty value array
    if (-not $header.Value -or $header.Value.Count -eq 0) {
        Write-Verbose "Header '$HeaderName' found but has no value. Returning default value."
        return $DefaultValue
    }
    
    # Get the first value if multiple values exist
    $headerValue = $header.Value[0]
    
    if ([string]::IsNullOrWhiteSpace($headerValue)) {
        Write-Verbose "Header '$HeaderName' found but value is null or whitespace. Returning default value."
        return $DefaultValue
    }
    
    # Attempt type conversion
    try {
        if ($ExpectedType -eq [string]) {
            # No conversion needed for string
            Write-Verbose "Successfully extracted header '$HeaderName' as string: '$headerValue'"
            return $headerValue
        }
        elseif ($ExpectedType -eq [int]) {
            $converted = [int]$headerValue
            Write-Verbose "Successfully parsed header '$HeaderName' as int: $converted"
            return $converted
        }
        elseif ($ExpectedType -eq [long]) {
            $converted = [long]$headerValue
            Write-Verbose "Successfully parsed header '$HeaderName' as long: $converted"
            return $converted
        }
        elseif ($ExpectedType -eq [double]) {
            $converted = [double]$headerValue
            Write-Verbose "Successfully parsed header '$HeaderName' as double: $converted"
            return $converted
        }
        elseif ($ExpectedType -eq [datetime]) {
            $converted = [datetime]$headerValue
            Write-Verbose "Successfully parsed header '$HeaderName' as datetime: $converted"
            return $converted
        }
        else {
            # Generic type conversion for other types
            $converted = $headerValue -as $ExpectedType
            if ($null -eq $converted) {
                throw "Type conversion failed"
            }
            Write-Verbose "Successfully converted header '$HeaderName' to $($ExpectedType.Name): $converted"
            return $converted
        }
    }
    catch {
        Write-Verbose "Could not parse $HeaderName header: $headerValue. Error: $($_.Exception.Message). Returning default value."
        return $DefaultValue
    }
}