Merge 6cce609 into f06537a

docs/Getting-Started/Migrating/1X-to-2X.md

@@ -47,14 +47,27 @@ to:
 
 Authentication underwent a hefty change in 2.0, with `Get-PodeAuthMiddleware` being removed.
 
-First, `New-PodeAuthType` has been renamed to [`New-PodeAuthScheme`] - with its `-Scheme` parameter also being renamed to `-Type`.
+First, `New-PodeAuthType` has been renamed to [`New-PodeAuthScheme`](../../../Functions/Authentication/New-PodeAuthScheme) - with its `-Scheme` parameter also being renamed to `-Type`.
 
-The old `-AutoLogin` (now just `-Login`), and `-Logout` switches, from `Get-PodeAuthMiddleware`, have been moved onto the [`Add-PodeRoute`] function. The [`Add-PodeRoute`] function now also has a new `-Authentication` parameter, which accepts the name of an Auth supplied to [`Add-PodeAuth`]; this will automatically setup authentication middleware for that route.
+The old `-AutoLogin` (now just `-Login`), and `-Logout` switches, from `Get-PodeAuthMiddleware`, have been moved onto the [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute) function. The [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute) function now also has a new `-Authentication` parameter, which accepts the name of an Auth supplied to [`Add-PodeAuth`](../../../Functions/Authentication/Add-PodeAuth); this will automatically setup authentication middleware for that route.
 
-The old `-Sessionless`, `-FailureUrl`, `-FailureMessage` and `-SuccessUrl` parameters, from `Get-PodeAuthMiddleware`, have all been moved onto the [`Add-PodeAuth`] function.
+The old `-Sessionless`, `-FailureUrl`, `-FailureMessage` and `-SuccessUrl` parameters, from `Get-PodeAuthMiddleware`, have all been moved onto the [`Add-PodeAuth`](../../../Functions/Authentication/Add-PodeAuth) function.
 
 The old `-EnabledFlash` switch has been removed (it's just enabled by default if sessions are enabled).
 
-There's also a new [`Add-PodeAuthMiddleware`] function, which will let you setup global authentication middleware.
+There's also a new [`Add-PodeAuthMiddleware`](../../../Functions/Authentication/Add-PodeAuthMiddleware) function, which will let you setup global authentication middleware.
 
-Furthermore, the OpenAPI functions for `Set-PodeOAAuth` and `Set-PodeOAGlobalAuth` have been removed. The new [`Add-PodeAuthMiddleware`] function and `-Authentication` parameter on [`Add-PodeRoute`] set these up for you automatically in OpenAPI.
+Furthermore, the OpenAPI functions for `Set-PodeOAAuth` and `Set-PodeOAGlobalAuth` have been removed. The new [`Add-PodeAuthMiddleware`](../../../Functions/Authentication/Add-PodeAuthMiddleware) function and `-Authentication` parameter on [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute) set these up for you automatically in OpenAPI.
+
+### Endpoint and Protocol
+
+On the following functions:
+
+* `Add-PodeRoute`
+* `Add-PodeStaticRoute`
+* `Get-PodeRoute`
+* `Get-PodeStaticRoute`
+* `Remove-PodeRoute`
+* `Remove-PodeStaticRoute`
+
+The `-Endpoint` and `-Protocol` parameters have been removed in favour of `-EndpointName`.

docs/Tutorials/Routes/Overview.md

@@ -160,9 +160,6 @@ Get-PodeRoute -Method Get
 # all routes for a Path
 Get-PodeRoute -Path '/users'
 
-# all routes for an Endpoint
-Get-PodeRoute -Endpoint 127.0.0.1:8080
-
 # all routes for an Endpoint by name
 Get-PodeRoute -EndpointName Admin
 ```
@@ -180,8 +177,7 @@ The following is the structure of the Route object internally, as well as the ob
 | ---- | ---- | ----------- |
 | Arguments | object[] | Array of arguments that are splatted onto the route's scriptblock (after the web event) |
 | ContentType | string | The content type to use when parsing the payload in the request |
-| Endpoint | string | Endpoint the route is bound to as `<address>:<port>` |
-| EndpointName | string | Name of the endpoint the route is bound to |
+| Endpoint | hashtable | Contains the Address, Protocol, and Name of the Endpoint the route is bound to |
 | ErrorType | string | Content type of the error page to use for the route |
 | IsStatic | bool | Fixed to false for normal routes |
 | Logic | scriptblock | The main scriptblock logic of the route |
@@ -190,7 +186,6 @@ The following is the structure of the Route object internally, as well as the ob
 | Middleware | hashtable[] | Array of middleware that runs prior to the route's scriptblock |
 | OpenApi | hashtable[] | The OpenAPI definition/settings for the route |
 | Path | string | The path of the route - this path will have regex in place of route parameters |
-| Protocol | string | Protocol the route is bound to |
 | TransferEncoding | string | The transfer encoding to use when parsing the payload in the request |
 
 Static routes have a slightly different format:
@@ -200,15 +195,13 @@ Static routes have a slightly different format:
 | ContentType | string | Content type to use when parsing the payload a request to the route |
 | Defaults | string[] | Array of default file names to render if path in request is a folder |
 | Download | bool | Specifies whether files are rendered in the response, or downloaded |
-| Endpoint | string | Endpoint the route is bound to as `<address>:<port>` |
-| EndpointName | string | Name of the endpoint the route is bound to |
+| Endpoint | hashtable | Contains the Address, Protocol, and Name of the Endpoint the route is bound to |
 | ErrorType | string | Content type of the error page to use for the route |
 | IsStatic | bool | Fixed to true for static routes |
 | Method | string | HTTP method of the route |
 | Metrics | hashtable | Metrics for the route, such as Request counts |
 | Middleware | hashtable[] | Array of middleware that runs prior to the route's scriptblock |
 | OpenApi | hashtable[] | The OpenAPI definition/settings for the route |
 | Path | string | The path of the route - this path will have regex in place of dynamic file names |
-| Protocol | string | Protocol the route is bound to |
 | Source | string | The source path within the server that is used for the route |
 | TransferEncoding | string | The transfer encoding to use when parsing the payload in the request |

docs/Tutorials/Routes/Utilities/Redirecting.md

@@ -30,20 +30,20 @@ Start-PodeServer {
     Add-PodeEndpoint -Address * -Port 8086 -Protocol HTTPS
 
     Add-PodeRoute -Method Get -Path '/redirect' -ScriptBlock {
-        Move-PodeResponseUrl -Port 8086 -Protocol https
+        Move-PodeResponseUrl -Port 8086 -Protocol Https
     }
 }
 ```
 
-This final example will redirect every HTTP request, on every action and route, to https:
+This final example will redirect every HTTP request, on every action and route, to HTTPS:
 
 ```powershell
 Start-PodeServer {
-    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
-    Add-PodeEndpoint -Address * -Port 8443 -Protocol HTTPS
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http -Name EndpointHttp
+    Add-PodeEndpoint -Address * -Port 8443 -Protocol Https -Name EndpointHttps
 
-    Add-PodeRoute -Method * -Path * -Protocol Http -ScriptBlock {
-        Move-PodeResponseUrl -Port 8443 -Protocol https
+    Add-PodeRoute -Method * -Path * -EndpointName EndpointHttp -ScriptBlock {
+        Move-PodeResponseUrl -Port 8443 -Protocol Https
     }
 }
 ```

docs/Tutorials/WebEvent.md

@@ -22,7 +22,7 @@ Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
 | ContentType | string | The content type of the data in the Request's payload |
 | Cookies | hashtable | Contains all cookies parsed from the Request's headers |
 | Data | hashtable | Contains the parsed items from the Request's payload |
-| Endpoint | string | The current endpoint being hit - such as "pode.example.com" or "127.0.0.2" |
+| Endpoint | hashtable | Contains the Address and Protocol of the endpoint being hit - such as "pode.example.com" or "127.0.0.2", or HTTP or HTTPS for the Protocol |
 | ErrorType | string | Set by the current Route being hit, this is the content type of the Error Page that will be used if an error occurs |
 | Files | hashtable | Contains any file data from the Request's payload |
 | Lockable | hashtable | A synchronized hashtable that can be used with `Lock-PodeObject` |
@@ -31,7 +31,6 @@ Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
 | Parameters | hashtable | Contains the parsed parameter values from the Route's path |
 | Path | string | The current path of the Request, after the endpoint - such as "/about" |
 | PendingCookies | hashtable | Contains cookies that will be written back on the Response |
-| Protocol | string | The current protocol of the Request - HTTP or HTTPS |
 | Query | hashtable | Contains the parsed items from the Request's query string |
 | Request | object | The raw Request object |
 | Response | object | The raw Response object |

examples/web-pages.ps1

@@ -14,7 +14,7 @@ Start-PodeServer -Threads 2 {
 
     # listen on localhost:8085
     Add-PodeEndpoint -Address * -Port 8090 -Protocol Http -Name '8090Address'
-    Add-PodeEndpoint -Address * -Port $Port -Protocol Http -RedirectTo '8090Address'
+    Add-PodeEndpoint -Address * -Port $Port -Protocol Http -Name '8085Address' -RedirectTo '8090Address'
 
     # allow the local ip and some other ips
     Add-PodeAccessRule -Access Allow -Type IP -Values @('127.0.0.1', '[::1]')

examples/web-route-endpoints.ps1

@@ -8,8 +8,8 @@ Import-Module "$($path)/src/Pode.psm1" -Force -ErrorAction Stop
 Start-PodeServer {
 
     # listen on localhost:8080
-    Add-PodeEndpoint -Address 127.0.0.1 -Port 8080 -Protocol Http
-    Add-PodeEndpoint -Address 127.0.0.2 -Port 8080 -Protocol Http
+    Add-PodeEndpoint -Address 127.0.0.1 -Port 8080 -Protocol Http -Name Endpoint1
+    Add-PodeEndpoint -Address 127.0.0.2 -Port 8080 -Protocol Http -Name Endpoint2
 
     # set view engine to pode
     Set-PodeViewEngine -Type Pode
@@ -26,12 +26,12 @@ Start-PodeServer {
 
     # GET request with parameters
     Add-PodeRoute -Method Get -Path '/:userId/details' -ScriptBlock {
-        param($event)
-        Write-PodeJsonResponse -Value @{ 'userId' = $event.Parameters['userId'] }
+        param($e)
+        Write-PodeJsonResponse -Value @{ 'userId' = $e.Parameters['userId'] }
     }
 
     # ALL requests for 127.0.0.2 to 127.0.0.1
-    Add-PodeRoute -Method * -Path * -Endpoint 127.0.0.2 -ScriptBlock {
+    Add-PodeRoute -Method * -Path * -EndpointName Endpoint2 -ScriptBlock {
         Move-PodeResponseUrl -Domain 127.0.0.1
     }
 

examples/web-route-protocols.ps1

@@ -8,14 +8,14 @@ Import-Module "$($path)/src/Pode.psm1" -Force -ErrorAction Stop
 Start-PodeServer {
 
     # listen on localhost:8080/8443
-    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
-    Add-PodeEndpoint -Address * -Port 8443 -Protocol HTTPS
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http -Name Endpoint1
+    Add-PodeEndpoint -Address * -Port 8443 -Protocol Https -Name Endpoint2
 
     # set view engine to pode
     Set-PodeViewEngine -Type Pode
 
     # GET request for web page
-    Add-PodeRoute -Method Get -Path '/' -Endpoint *:8443 -Protocol Http -ScriptBlock {
+    Add-PodeRoute -Method Get -Path '/' -EndpointName Endpoint2 -ScriptBlock {
         Write-PodeViewResponse -Path 'simple' -Data @{ 'numbers' = @(1, 2, 3); }
     }
 
@@ -26,13 +26,13 @@ Start-PodeServer {
 
     # GET request with parameters
     Add-PodeRoute -Method Get -Path '/:userId/details' -ScriptBlock {
-        param($event)
-        Write-PodeJsonResponse -Value @{ 'userId' = $event.Parameters['userId'] }
+        param($e)
+        Write-PodeJsonResponse -Value @{ 'userId' = $e.Parameters['userId'] }
     }
 
     # ALL requests for http only to redirect to https
-    Add-PodeRoute -Method * -Path * -Protocol Http {
-        Move-PodeResponseUrl -Protocol https -Port 8443
+    Add-PodeRoute -Method * -Path * -EndpointName Endpoint1 {
+        Move-PodeResponseUrl -Protocol Https -Port 8443
     }
 
 }

src/Private/Gui.ps1

@@ -20,14 +20,14 @@ function Start-PodeGuiRunspace
             }
 
             # get the endpoint on which we're currently listening, or use explicitly passed one
-            $endpoint = (Get-PodeEndpointUrl -Endpoint $PodeContext.Server.Gui.Endpoint)
+            $uri = (Get-PodeEndpointUrl -Endpoint $PodeContext.Server.Gui.Endpoint)
 
             # poll the server for a response
             $count = 0
 
             while ($true) {
                 try {
-                    Invoke-WebRequest -Method Get -Uri $endpoint -UseBasicParsing -ErrorAction Stop | Out-Null
+                    Invoke-WebRequest -Method Get -Uri $uri -UseBasicParsing -ErrorAction Stop | Out-Null
                     if (!$?) {
                         throw
                     }
@@ -40,7 +40,7 @@ function Start-PodeGuiRunspace
                         Start-Sleep -Milliseconds 200
                     }
                     else {
-                        throw "Failed to connect to URL: $($endpoint)"
+                        throw "Failed to connect to URL: $($uri)"
                     }
                 }
             }
@@ -86,7 +86,7 @@ function Start-PodeGuiRunspace
             }
 
             # get the browser object from XAML and navigate to base page
-            $form.FindName("WebBrowser").Navigate($endpoint)
+            $form.FindName("WebBrowser").Navigate($uri)
 
             # display the form
             $form.ShowDialog() | Out-Null

src/Private/Helpers.ps1

@@ -185,13 +185,13 @@ function Get-PodeEndpointInfo
     param (
         [Parameter()]
         [string]
-        $Endpoint,
+        $Address,
 
         [switch]
         $AnyPortOnZero
     )
 
-    if ([string]::IsNullOrWhiteSpace($Endpoint)) {
+    if ([string]::IsNullOrWhiteSpace($Address)) {
         return $null
     }
 
@@ -200,8 +200,8 @@ function Get-PodeEndpointInfo
     $cmbdRgx = "$($hostRgx)\:$($portRgx)"
 
     # validate that we have a valid ip/host:port address
-    if (!(($Endpoint -imatch "^$($cmbdRgx)$") -or ($Endpoint -imatch "^$($hostRgx)[\:]{0,1}") -or ($Endpoint -imatch "[\:]{0,1}$($portRgx)$"))) {
-        throw "Failed to parse '$($Endpoint)' as a valid IP/Host:Port address"
+    if (!(($Address -imatch "^$($cmbdRgx)$") -or ($Address -imatch "^$($hostRgx)[\:]{0,1}") -or ($Address -imatch "[\:]{0,1}$($portRgx)$"))) {
+        throw "Failed to parse '$($Address)' as a valid IP/Host:Port address"
     }
 
     # grab the ip address/hostname
@@ -277,10 +277,10 @@ function ConvertTo-PodeIPAddress
     param (
         [Parameter(Mandatory=$true)]
         [ValidateNotNull()]
-        $Endpoint
+        $Address
     )
 
-    return [System.Net.IPAddress]::Parse(([System.Net.IPEndPoint]$Endpoint).Address.ToString())
+    return [System.Net.IPAddress]::Parse(([System.Net.IPEndPoint]$Address).Address.ToString())
 }
 
 function Get-PodeIPAddressesForHostname
@@ -1582,7 +1582,7 @@ function Get-PodeModuleMiscPath
 
 function Get-PodeUrl
 {
-    return "$($WebEvent.Protocol)://$($WebEvent.Endpoint)$($WebEvent.Path)"
+    return "$($WebEvent.Endpoint.Protocol)://$($WebEvent.Endpoint.Address)$($WebEvent.Path)"
 }
 
 function Find-PodeErrorPage

src/Private/Middleware.ps1

@@ -151,17 +151,17 @@ function Get-PodeRouteValidateMiddleware
             param($e)
 
             # check if the path is static route first, then check the main routes
-            $route = Find-PodeStaticRoute -Path $e.Path -Protocol $e.Protocol -Endpoint $e.Endpoint
+            $route = Find-PodeStaticRoute -Path $e.Path -Protocol $e.Endpoint.Protocol -Address $e.Endpoint.Address
             if ($null -eq $route) {
-                $route = Find-PodeRoute -Method $e.Method -Path $e.Path -Protocol $e.Protocol -Endpoint $e.Endpoint -CheckWildMethod
+                $route = Find-PodeRoute -Method $e.Method -Path $e.Path -Protocol $e.Endpoint.Protocol -Address $e.Endpoint.Address -CheckWildMethod
             }
 
             # if there's no route defined, it's a 404 - or a 405 if a route exists for any other method
             if ($null -eq $route) {
                 # check if a route exists for another method
                 $methods = @('DELETE', 'GET', 'HEAD', 'MERGE', 'OPTIONS', 'PATCH', 'POST', 'PUT', 'TRACE')
                 $diff_route = @(foreach ($method in $methods) {
-                    $r = Find-PodeRoute -Method $method -Path $e.Path -Protocol $e.Protocol -Endpoint $e.Endpoint
+                    $r = Find-PodeRoute -Method $method -Path $e.Path -Protocol $e.Endpoint.Protocol -Address $e.Endpoint.Address
                     if ($null -ne $r) {
                         $r
                         break

src/Private/OpenApi.ps1

@@ -202,7 +202,7 @@ function Get-PodeOpenApiDefinitionInternal
         $Protocol,
 
         [Parameter()]
-        $Endpoint,
+        $Address,
 
         [switch]
         $RestrictRoutes
@@ -262,7 +262,7 @@ function Get-PodeOpenApiDefinitionInternal
             # the current route
             $_routes = @($PodeContext.Server.Routes[$method][$path])
             if ($RestrictRoutes) {
-                $_routes = @(Get-PodeRoutesByUrl -Routes $_routes -Protocol $Protocol -Endpoint $Endpoint)
+                $_routes = @(Get-PodeRoutesByUrl -Routes $_routes -Protocol $Protocol -Address $Address)
             }
 
             # continue if no routes
@@ -298,7 +298,7 @@ function Get-PodeOpenApiDefinitionInternal
 
             # add any custom server endpoints for route
             foreach ($_route in $_routes) {
-                if ([string]::IsNullOrWhiteSpace($_route.Endpoint) -or ($_route.Endpoint -ieq '*:*')) {
+                if ([string]::IsNullOrWhiteSpace($_route.Endpoint.Address) -or ($_route.Endpoint.Address -ieq '*:*')) {
                     continue
                 }
 
@@ -307,7 +307,7 @@ function Get-PodeOpenApiDefinitionInternal
                 }
 
                 $def.paths[$_route.OpenApi.Path][$method].servers += @{
-                    url = "$($_route.Protocol)://$($_route.Endpoint)"
+                    url = "$($_route.Endpoint.Protocol)://$($_route.Endpoint.Address)"
                 }
             }
         }

src/Private/PodeServer.ps1

@@ -96,8 +96,10 @@ function Start-PodeWebServer
                             Path = [System.Web.HttpUtility]::UrlDecode($Request.Url.AbsolutePath)
                             Method = $Request.HttpMethod.ToLowerInvariant()
                             Query = $null
-                            Protocol = $Request.Url.Scheme
-                            Endpoint = $Request.Host
+                            Endpoint = @{
+                                Protocol = $Request.Url.Scheme
+                                Address = $Request.Host
+                            }
                             ContentType = $Request.ContentType
                             ErrorType = $null
                             Cookies = @{}