| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Registers a health probe that executes an external process. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Creates a Kestrun ProcessProbe that launches the specified command, waits for completion, and |
| | | 6 | | interprets the exit code or JSON payload to determine health. Provide tags to support filtering |
| | | 7 | | and optionally adjust the timeout enforced on the subprocess. |
| | | 8 | | .PARAMETER Server |
| | | 9 | | The Kestrun host instance to configure. If omitted, the current server context is resolved automatically. |
| | | 10 | | .PARAMETER Name |
| | | 11 | | Unique name for the probe. |
| | | 12 | | .PARAMETER FilePath |
| | | 13 | | The executable or script to launch. |
| | | 14 | | .PARAMETER Arguments |
| | | 15 | | Command-line arguments passed to the process. Defaults to an empty string. |
| | | 16 | | .PARAMETER Tags |
| | | 17 | | Optional set of tags used to include or exclude the probe when requests filter by tag. |
| | | 18 | | .PARAMETER Timeout |
| | | 19 | | Optional timeout applied to the process execution. Defaults to 10 seconds. |
| | | 20 | | .PARAMETER PassThru |
| | | 21 | | Emits the configured server instance so the call can be chained. |
| | | 22 | | .EXAMPLE |
| | | 23 | | Add-KrHealthProcessProbe -Name DiskSpace -FilePath 'pwsh' -Arguments '-File ./Scripts/Check-Disk.ps1' -Tags 'infra' |
| | | 24 | | Registers a process probe that runs a PowerShell script to evaluate disk capacity. |
| | | 25 | | #> |
| | | 26 | | function Add-KrHealthProcessProbe { |
| | | 27 | | [KestrunRuntimeApi('Definition')] |
| | | 28 | | [CmdletBinding()] |
| | | 29 | | [OutputType([Kestrun.Hosting.KestrunHost])] |
| | | 30 | | param( |
| | | 31 | | [Parameter(ValueFromPipeline = $true)] |
| | | 32 | | [Kestrun.Hosting.KestrunHost]$Server, |
| | | 33 | | |
| | | 34 | | [Parameter(Mandatory = $true)] |
| | | 35 | | [string]$Name, |
| | | 36 | | |
| | | 37 | | [Parameter(Mandatory = $true)] |
| | | 38 | | [ValidateNotNullOrEmpty()] |
| | | 39 | | [string]$FilePath, |
| | | 40 | | |
| | | 41 | | [string]$Arguments = '', |
| | | 42 | | |
| | | 43 | | [string[]]$Tags, |
| | | 44 | | |
| | | 45 | | [timespan]$Timeout, |
| | | 46 | | |
| | | 47 | | [switch]$PassThru |
| | | 48 | | ) |
| | | 49 | | begin { |
| | 0 | 50 | | $Server = Resolve-KestrunServer -Server $Server |
| | 0 | 51 | | if ($null -eq $Server) { |
| | 0 | 52 | | throw 'Server is not initialized. Call New-KrServer first or pipe an existing host instance.' |
| | | 53 | | } |
| | | 54 | | } |
| | | 55 | | process { |
| | 0 | 56 | | $normalizedTags = @() |
| | 0 | 57 | | if ($PSBoundParameters.ContainsKey('Tags')) { |
| | 0 | 58 | | $normalizedTags = @($Tags | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | ForEach-Object { $_.Tri |
| | | 59 | | } |
| | | 60 | | |
| | 0 | 61 | | if ($normalizedTags.Count -eq 0) { |
| | 0 | 62 | | $normalizedTags = @() |
| | | 63 | | } |
| | | 64 | | |
| | 0 | 65 | | $probe = if ($PSBoundParameters.ContainsKey('Timeout')) { |
| | 0 | 66 | | if ($Timeout -le [timespan]::Zero) { |
| | 0 | 67 | | throw 'Timeout must be greater than zero.' |
| | | 68 | | } |
| | 0 | 69 | | [Kestrun.Health.ProcessProbe]::new($Name, $normalizedTags, $FilePath, $Arguments, $Timeout) |
| | | 70 | | } else { |
| | 0 | 71 | | [Kestrun.Health.ProcessProbe]::new($Name, $normalizedTags, $FilePath, $Arguments) |
| | | 72 | | } |
| | | 73 | | |
| | | 74 | | try { |
| | 0 | 75 | | $hostResult = $Server.AddProbe($probe) |
| | 0 | 76 | | Write-KrLog -Level Information -Message "Process health probe '{0}' registered." -Values $Name |
| | 0 | 77 | | if ($PassThru.IsPresent) { |
| | 0 | 78 | | return $hostResult |
| | | 79 | | } |
| | | 80 | | } catch { |
| | 0 | 81 | | Write-KrLog -Level Error -Message "Failed to register process health probe '{0}'." -Values $Name -ErrorRecor |
| | | 82 | | throw |
| | | 83 | | } |
| | | 84 | | } |
| | | 85 | | } |