| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Adds an SSE broadcast endpoint to the server. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Registers an in-memory SSE broadcaster service and maps an SSE endpoint that keeps connections open. |
| | | 6 | | Clients connect (e.g. via browser EventSource) and receive events broadcast by Send-KrSseBroadcastEvent. |
| | | 7 | | .PARAMETER Path |
| | | 8 | | The URL path where the SSE broadcast endpoint will be accessible. Defaults to '/sse/broadcast'. |
| | | 9 | | .PARAMETER DocId |
| | | 10 | | The OpenAPI document IDs to which the SSE broadcast endpoint should be added. Default is 'Default'. |
| | | 11 | | .PARAMETER KeepAliveSeconds |
| | | 12 | | If greater than 0, sends periodic SSE comments (keep-alives) to keep intermediaries from closing idle connection |
| | | 13 | | .PARAMETER OperationId |
| | | 14 | | Optional OpenAPI operationId override for the broadcast endpoint. |
| | | 15 | | .PARAMETER Summary |
| | | 16 | | Optional OpenAPI summary override for the broadcast endpoint. |
| | | 17 | | .PARAMETER Description |
| | | 18 | | Optional OpenAPI description override for the broadcast endpoint. |
| | | 19 | | .PARAMETER Tags |
| | | 20 | | Optional OpenAPI tags override for the broadcast endpoint. |
| | | 21 | | .PARAMETER StatusCode |
| | | 22 | | Optional OpenAPI response status code override (default: 200). |
| | | 23 | | .PARAMETER ResponseDescription |
| | | 24 | | Optional OpenAPI response description override. |
| | | 25 | | .PARAMETER ItemSchemaType |
| | | 26 | | Optional OpenAPI schema type for the stream payload (default: String). |
| | | 27 | | This only applies when -OpenApi is not provided. |
| | | 28 | | .PARAMETER SkipOpenApi |
| | | 29 | | If specified, the OpenAPI documentation for this endpoint will be skipped. |
| | | 30 | | .PARAMETER Options |
| | | 31 | | Full OpenAPI customization object (Kestrun.Hosting.Options.SseBroadcastOptions). |
| | | 32 | | When provided, it takes precedence over the individual parameters. |
| | | 33 | | .EXAMPLE |
| | | 34 | | Add-KrSseBroadcastMiddleware -Path '/sse/broadcast' -PassThru |
| | | 35 | | Adds an SSE broadcast endpoint at '/sse/broadcast' and returns the server instance. |
| | | 36 | | .EXAMPLE |
| | | 37 | | New-KrServer -Name 'MyServer' |
| | | 38 | | Add-KrSseBroadcastMiddleware -Path '/events' -KeepAliveSeconds 30 |
| | | 39 | | Adds an SSE broadcast endpoint at '/events' with 30-second keep-alives to the specified server. |
| | | 40 | | .EXAMPLE |
| | | 41 | | Add-KrSseBroadcastMiddleware -SkipOpenApi |
| | | 42 | | Adds an SSE broadcast endpoint without OpenAPI documentation. |
| | | 43 | | .EXAMPLE |
| | | 44 | | $options = [Kestrun.Hosting.Options.SseBroadcastOptions]::new() |
| | | 45 | | $options.Path = '/sse/updates' |
| | | 46 | | $options.KeepAliveSeconds = 15 |
| | | 47 | | Add-KrSseBroadcastMiddleware -Options $options -PassThru |
| | | 48 | | Adds an SSE broadcast endpoint at '/sse/updates' with 15-second keep-alives using the provided options object. |
| | | 49 | | .NOTES |
| | | 50 | | Call this before Enable-KrConfiguration. |
| | | 51 | | The SSE broadcast endpoint allows clients to connect and receive server-sent events broadcast via Send-KrSseBroa |
| | | 52 | | This cmdlet is part of the Kestrun PowerShell module and is used to manage SSE broadcast endpoints on the Kestru |
| | | 53 | | #> |
| | | 54 | | function Add-KrSseBroadcastMiddleware { |
| | | 55 | | [KestrunRuntimeApi('Definition')] |
| | | 56 | | [CmdletBinding(DefaultParameterSetName = 'Items')] |
| | | 57 | | param( |
| | | 58 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 59 | | [Parameter(Mandatory = $false, ParameterSetName = 'ItemsSkipOpenApi')] |
| | | 60 | | [string]$Path, |
| | | 61 | | |
| | | 62 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 63 | | [Parameter(Mandatory = $false, ParameterSetName = 'ItemsSkipOpenApi')] |
| | | 64 | | [string[]]$DocId = [Kestrun.OpenApi.OpenApiDocDescriptor]::DefaultDocumentationIds, |
| | | 65 | | |
| | | 66 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 67 | | [ValidateRange(0, 3600)] |
| | | 68 | | [int]$KeepAliveSeconds, |
| | | 69 | | |
| | | 70 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 71 | | [string]$OperationId, |
| | | 72 | | |
| | | 73 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 74 | | [string]$Summary, |
| | | 75 | | |
| | | 76 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 77 | | [string]$Description, |
| | | 78 | | |
| | | 79 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 80 | | [string[]]$Tags, |
| | | 81 | | |
| | | 82 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 83 | | [ValidatePattern('^(default|\\d{3})$')] |
| | | 84 | | [string]$StatusCode, |
| | | 85 | | |
| | | 86 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 87 | | [string]$ResponseDescription, |
| | | 88 | | |
| | | 89 | | [Parameter(Mandatory = $false, ParameterSetName = 'Items')] |
| | | 90 | | [object]$ItemSchemaType = [string], |
| | | 91 | | |
| | | 92 | | [Parameter(Mandatory = $false, ParameterSetName = 'ItemsSkipOpenApi')] |
| | | 93 | | [switch]$SkipOpenApi, |
| | | 94 | | |
| | | 95 | | [Parameter(Mandatory = $true, ParameterSetName = 'Options')] |
| | | 96 | | [Kestrun.Hosting.Options.SseBroadcastOptions]$Options |
| | | 97 | | ) |
| | | 98 | | # Ensure the server instance is resolved |
| | 0 | 99 | | $Server = Resolve-KestrunServer |
| | | 100 | | |
| | | 101 | | # If the Options parameter set is not used, create an options object from the individual parameters |
| | 0 | 102 | | if ($PSCmdlet.ParameterSetName -eq 'Items') { |
| | 0 | 103 | | $Options = [Kestrun.Hosting.Options.SseBroadcastOptions]::new() |
| | 0 | 104 | | if ( $SkipOpenApi.IsPresent ) { |
| | 0 | 105 | | $Options.SkipOpenApi = $true |
| | | 106 | | }# Set the documentation IDs for the SSE broadcast endpoint |
| | 0 | 107 | | $Options.DocId = $DocId |
| | | 108 | | |
| | | 109 | | # Set the path for the SSE broadcast endpoint |
| | 0 | 110 | | if ($PSBoundParameters.ContainsKey('Path')) { $Options.Path = $Path } |
| | 0 | 111 | | if ($PSBoundParameters.ContainsKey('KeepAliveSeconds')) { $Options.KeepAliveSeconds = $KeepAliveSeconds } |
| | 0 | 112 | | if ($PSBoundParameters.ContainsKey('OperationId')) { $Options.OperationId = $OperationId } |
| | 0 | 113 | | if ($PSBoundParameters.ContainsKey('Summary')) { $Options.Summary = $Summary } |
| | 0 | 114 | | if ($PSBoundParameters.ContainsKey('Description')) { $Options.Description = $Description } |
| | 0 | 115 | | if ($PSBoundParameters.ContainsKey('Tags')) { $Options.Tags = $Tags } |
| | 0 | 116 | | if ($PSBoundParameters.ContainsKey('StatusCode')) { $Options.StatusCode = $StatusCode } |
| | 0 | 117 | | if ($PSBoundParameters.ContainsKey('ResponseDescription')) { $Options.ResponseDescription = $ResponseDescription |
| | 0 | 118 | | if ($PSBoundParameters.ContainsKey('ItemSchemaType')) { |
| | 0 | 119 | | $Options.ItemSchemaType = $ItemSchemaType |
| | | 120 | | } |
| | | 121 | | } |
| | | 122 | | # Add the SSE broadcast middleware to the server |
| | 0 | 123 | | $Server.AddSseBroadcast($Options) | Out-Null |
| | | 124 | | } |
| | | 125 | | |