| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Adds a form parsing route to the Kestrun server. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Registers a POST route that parses multipart/form-data payloads using |
| | | 6 | | KrFormParser. Additional request content types (e.g., multipart/mixed |
| | | 7 | | and application/x-www-form-urlencoded) are opt-in via |
| | | 8 | | KrFormOptions.AllowedRequestContentTypes. |
| | | 9 | | Once parsed, it injects the parsed payload into the runspace as |
| | | 10 | | $FormPayload and invokes the provided script block. |
| | | 11 | | .PARAMETER Pattern |
| | | 12 | | The route pattern (e.g., '/upload'). |
| | | 13 | | .PARAMETER ScriptBlock |
| | | 14 | | The script block to execute once the payload is parsed. The parsed |
| | | 15 | | payload is available as $FormPayload (and the request context is |
| | | 16 | | available as $Context). |
| | | 17 | | .PARAMETER Options |
| | | 18 | | The KrFormOptions used to configure form parsing. |
| | | 19 | | .PARAMETER OptionsName |
| | | 20 | | The name of an existing KrFormOptions on the server to use for form parsing. |
| | | 21 | | .PARAMETER AuthorizationScheme |
| | | 22 | | Optional authorization schemes required for the route. |
| | | 23 | | .PARAMETER AuthorizationPolicy |
| | | 24 | | Optional authorization policies required for the route. |
| | | 25 | | .PARAMETER CorsPolicy |
| | | 26 | | Optional CORS policy name to apply to the route. |
| | | 27 | | .PARAMETER AllowAnonymous |
| | | 28 | | Allows anonymous access to the route. |
| | | 29 | | .PARAMETER PassThru |
| | | 30 | | Returns the updated server instance when specified. |
| | | 31 | | .EXAMPLE |
| | | 32 | | Add-KrFormRoute -Pattern '/upload' -ScriptBlock { |
| | | 33 | | param($FormPayload, $Context) |
| | | 34 | | # Handle the parsed form payload |
| | | 35 | | $FormPayload.Files |
| | | 36 | | } -Options $formOptions -PassThru |
| | | 37 | | This example adds a form route at '/upload' that processes multipart/form-data uploads |
| | | 38 | | using the specified form options and returns the updated server instance. |
| | | 39 | | .NOTES |
| | | 40 | | This function is part of the Kestrun.Forms module and is used to define form routes. |
| | | 41 | | #> |
| | | 42 | | function Add-KrFormRoute { |
| | | 43 | | [KestrunRuntimeApi('Definition')] |
| | | 44 | | [CmdletBinding(DefaultParameterSetName = 'Default')] |
| | | 45 | | [OutputType([Kestrun.Hosting.KestrunHost])] |
| | | 46 | | param( |
| | | 47 | | [Parameter(Mandatory = $true)] |
| | | 48 | | [string]$Pattern, |
| | | 49 | | |
| | | 50 | | [Parameter(Mandatory = $true)] |
| | | 51 | | [scriptblock]$ScriptBlock, |
| | | 52 | | |
| | | 53 | | [Parameter(ParameterSetName = 'WithOptions', Mandatory = $true, ValueFromPipeline = $true)] |
| | | 54 | | [Kestrun.Forms.KrFormOptions]$Options, |
| | | 55 | | |
| | | 56 | | [Parameter(Mandatory = $true, ParameterSetName = 'Default')] |
| | | 57 | | [string]$OptionsName, |
| | | 58 | | |
| | | 59 | | [Parameter()] |
| | | 60 | | [string[]]$AuthorizationScheme = $null, |
| | | 61 | | |
| | | 62 | | [Parameter()] |
| | | 63 | | [string[]]$AuthorizationPolicy = $null, |
| | | 64 | | [Parameter()] |
| | | 65 | | [string]$CorsPolicy, |
| | | 66 | | [Parameter()] |
| | | 67 | | [switch]$AllowAnonymous, |
| | | 68 | | [Parameter()] |
| | | 69 | | [switch]$PassThru |
| | | 70 | | ) |
| | | 71 | | begin { |
| | 0 | 72 | | $Server = Resolve-KestrunServer |
| | 0 | 73 | | if (-not $Server) { throw 'Server is not initialized. Call New-KrServer and Enable-KrConfiguration first.' } |
| | | 74 | | } |
| | | 75 | | process { |
| | 0 | 76 | | if ( $PSCmdlet.ParameterSetName -eq 'Default' ) { |
| | 0 | 77 | | $Options = $Server.GetFormOption($OptionsName) |
| | 0 | 78 | | if ($null -eq $Options) { |
| | 0 | 79 | | throw "Form option with name '$OptionsName' not found on the server." |
| | | 80 | | } |
| | | 81 | | } |
| | 0 | 82 | | if ( $null -eq $Options ) { |
| | 0 | 83 | | throw 'KrFormOptions must be provided either via Options parameter or OptionsName parameter.' |
| | | 84 | | } |
| | 0 | 85 | | [Kestrun.Hosting.KestrunHostMapExtensions]::AddFormRoute( |
| | | 86 | | $Server, |
| | | 87 | | $Pattern, |
| | | 88 | | $ScriptBlock, |
| | | 89 | | $Options, |
| | | 90 | | $AuthorizationScheme, |
| | | 91 | | $AuthorizationPolicy, |
| | | 92 | | $CorsPolicy, |
| | | 93 | | $AllowAnonymous.IsPresent |
| | 0 | 94 | | ) | Out-Null |
| | | 95 | | |
| | 0 | 96 | | if ($PassThru.IsPresent) { |
| | 0 | 97 | | return $Server |
| | | 98 | | } |
| | | 99 | | } |
| | | 100 | | } |