| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Registers an HTTP-based health probe that polls a remote endpoint. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Creates a Kestrun HttpProbe that issues a GET request to the specified URL and interprets the |
| | | 6 | | response according to the standard health contract. Provide a shared HttpClient instance for |
| | | 7 | | production use to avoid socket exhaustion, or rely on the default constructed client for simple |
| | | 8 | | scenarios. |
| | | 9 | | .PARAMETER Server |
| | | 10 | | The Kestrun host instance to configure. If omitted, the current server context is resolved automatically. |
| | | 11 | | .PARAMETER Name |
| | | 12 | | Unique name for the probe. |
| | | 13 | | .PARAMETER Url |
| | | 14 | | The absolute URL that the probe polls. |
| | | 15 | | .PARAMETER Tags |
| | | 16 | | Optional set of tags used to include or exclude the probe when requests filter by tag. |
| | | 17 | | .PARAMETER HttpClient |
| | | 18 | | Optional HttpClient reused for the probe requests. When omitted a new HttpClient instance is created. |
| | | 19 | | .PARAMETER Timeout |
| | | 20 | | Optional timeout applied to the HTTP request. Defaults to 5 seconds. |
| | | 21 | | .PARAMETER PassThru |
| | | 22 | | Emits the configured server instance so the call can be chained. |
| | | 23 | | .EXAMPLE |
| | | 24 | | Add-KrHealthHttpProbe -Name Api -Url 'https://api.contoso.local/health' -Tags 'remote','api' |
| | | 25 | | Registers a health probe that checks a downstream API health endpoint. |
| | | 26 | | .EXAMPLE |
| | | 27 | | $client = [System.Net.Http.HttpClient]::new() |
| | | 28 | | Get-KrServer | Add-KrHealthHttpProbe -Name Ping -Url 'https://example.com/health' -HttpClient $client -PassThru |
| | | 29 | | Registers a probe using a shared HttpClient instance and returns the host for additional configuration. |
| | | 30 | | #> |
| | | 31 | | function Add-KrHealthHttpProbe { |
| | | 32 | | [KestrunRuntimeApi('Definition')] |
| | | 33 | | [CmdletBinding()] |
| | | 34 | | [OutputType([Kestrun.Hosting.KestrunHost])] |
| | | 35 | | param( |
| | | 36 | | [Parameter(ValueFromPipeline = $true)] |
| | | 37 | | [Kestrun.Hosting.KestrunHost]$Server, |
| | | 38 | | |
| | | 39 | | [Parameter(Mandatory = $true)] |
| | | 40 | | [string]$Name, |
| | | 41 | | |
| | | 42 | | [Parameter(Mandatory = $true)] |
| | | 43 | | [ValidateNotNullOrEmpty()] |
| | | 44 | | [string]$Url, |
| | | 45 | | |
| | | 46 | | [string[]]$Tags, |
| | | 47 | | |
| | | 48 | | [System.Net.Http.HttpClient]$HttpClient, |
| | | 49 | | |
| | | 50 | | [timespan]$Timeout, |
| | | 51 | | |
| | | 52 | | [switch]$PassThru |
| | | 53 | | ) |
| | | 54 | | begin { |
| | 0 | 55 | | $Server = Resolve-KestrunServer -Server $Server |
| | 0 | 56 | | if ($null -eq $Server) { |
| | 0 | 57 | | throw 'Server is not initialized. Call New-KrServer first or pipe an existing host instance.' |
| | | 58 | | } |
| | | 59 | | } |
| | | 60 | | process { |
| | 0 | 61 | | if (-not [Uri]::IsWellFormedUriString($Url, [UriKind]::Absolute)) { |
| | 0 | 62 | | throw "The URL '$Url' must be an absolute URI." |
| | | 63 | | } |
| | | 64 | | |
| | 0 | 65 | | $normalizedTags = @() |
| | 0 | 66 | | if ($PSBoundParameters.ContainsKey('Tags')) { |
| | 0 | 67 | | $normalizedTags = @($Tags | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | ForEach-Object { $_.Tri |
| | | 68 | | } |
| | | 69 | | |
| | 0 | 70 | | if ($normalizedTags.Count -eq 0) { |
| | 0 | 71 | | $normalizedTags = @() |
| | | 72 | | } |
| | | 73 | | |
| | 0 | 74 | | $client = $HttpClient |
| | 0 | 75 | | if (-not $PSBoundParameters.ContainsKey('HttpClient') -or $null -eq $HttpClient) { |
| | 0 | 76 | | $client = [System.Net.Http.HttpClient]::new() |
| | | 77 | | } |
| | | 78 | | |
| | 0 | 79 | | $probe = if ($PSBoundParameters.ContainsKey('Timeout')) { |
| | 0 | 80 | | if ($Timeout -le [timespan]::Zero) { |
| | 0 | 81 | | throw 'Timeout must be greater than zero.' |
| | | 82 | | } |
| | 0 | 83 | | [Kestrun.Health.HttpProbe]::new($Name, $normalizedTags, $client, $Url, $Timeout) |
| | | 84 | | } else { |
| | 0 | 85 | | [Kestrun.Health.HttpProbe]::new($Name, $normalizedTags, $client, $Url) |
| | | 86 | | } |
| | | 87 | | |
| | | 88 | | try { |
| | 0 | 89 | | $hostResult = $Server.AddProbe($probe) |
| | 0 | 90 | | Write-KrLog -Level Information -Message "HTTP health probe '{0}' registered." -Values $Name |
| | 0 | 91 | | if ($PassThru.IsPresent) { |
| | 0 | 92 | | return $hostResult |
| | | 93 | | } |
| | | 94 | | } catch { |
| | 0 | 95 | | Write-KrLog -Level Error -Message "Failed to register HTTP health probe '{0}'." -Values $Name -ErrorRecord $ |
| | | 96 | | throw |
| | | 97 | | } |
| | | 98 | | } |
| | | 99 | | } |