#964: add IfExists for Route Groups, and adds docs

Badgerati · Dec 10, 2022 · ca81424 · ca81424
1 parent 06f5686
commit ca81424
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 8 deletions.
diff --git a/docs/Tutorials/Routes/Overview.md b/docs/Tutorials/Routes/Overview.md
@@ -166,6 +166,71 @@ Get-PodeRoute -EndpointName Admin
 
 The [`Get-PodeStaticRoute`](../../../Functions/Routes/Get-PodeStaticRoute) function works in the same way as above - but with no `-Method` parameter.
 
+## If Exists Preference
+
+By default when you try and add a Route with the same Method and Path twice, Pode will throw an error when attempting to add the second Route.
+
+You can alter this behaviour by using the `-IfExists` parameter on several of the Route functions:
+
+* [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute)
+* [`Add-PodeStaticRoute`](../../../Functions/Routes/Add-PodeStaticRoute)
+* [`Add-PodeSignalRoute`](../../../Functions/Routes/Add-PodeSignalRoute)
+* [`Add-PodeRouteGroup`](../../../Functions/Routes/Add-PodeRouteGroup)
+* [`Add-PodeStaticRouteGroup`](../../../Functions/Routes/Add-PodeStaticRouteGroup)
+* [`Add-PodeSignalRouteGroup`](../../../Functions/Routes/Add-PodeSignalRouteGroup)
+* [`Use-PodeRoutes`](../../../Functions/Routes/Use-PodeRoutes)
+
+Or you can alter the global default preference for all Routes using [`Set-PodeRouteIfExistsPreference`](../../../Functions/Routes/Set-PodeRouteIfExistsPreference).
+
+This parameter accepts the following options:
+
+| Option | Description |
+| ------ | ----------- |
+| Default | This will use the `-IfExists` value from higher up the hierarchy (as defined see below) - if none defined, Error is the final default |
+| Error | Throw an error if the Route already exists |
+| Overwrite | Delete the existing Route if one exists, and then recreate the Route with the new definition |
+| Skip | Skip over adding the Route if it already exists |
+
+and the following hierarchy is used when deciding which behaviour to use. At each step if the value defined is `Default` then check the next value in the hierarchy:
+
+1. Use the value defined directly on the Route, such as [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute)
+2. Use the value defined on a Route Group, such as [`Add-PodeRouteGroup`](../../../Functions/Routes/Add-PodeRouteGroup)
+3. Use the value defined on [`Use-PodeRoutes`](../../../Functions/Routes/Use-PodeRoutes)
+4. Use the value defined from [`Set-PodeRouteIfExistsPreference`](../../../Functions/Routes/Set-PodeRouteIfExistsPreference)
+5. Throw an error if the Route already exists
+
+For example, the following will now skip attempting to add the second Route because it already exists; meaning the value returned from `http://localhost:8080` is `1` not `2`:
+
+```powershell
+Start-PodeServer {
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Result = 1 }
+    }
+
+    Add-PodeRoute -Method Get -Path '/' -IfExists Skip -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Result = 2 }
+    }
+}
+```
+
+Or, we could use Overwrite and the value returned will now be `2` not `1`:
+
+```powershell
+Start-PodeServer {
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Result = 1 }
+    }
+
+    Add-PodeRoute -Method Get -Path '/' -IfExists Overwrite -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Result = 2 }
+    }
+}
+```
+
 ## Grouping
 
 If you have a number of Routes that all share the same base path, middleware, authentication, or other parameters, then you can add these Routes within a Route Group (via [`Add-PodeRouteGroup`](../../../Functions/Routes/Add-PodeRouteGroup)) to share the parameter values:

diff --git a/src/Private/Routes.ps1 b/src/Private/Routes.ps1
@@ -609,16 +609,23 @@ function ConvertTo-PodeMiddleware
 
 function Get-PodeRouteIfExistsPreference
 {
-    $interalPref = $RouteIfExists
-    $globalPref = $PodeContext.Server.Preferences.Routes.IfExists
+    # from route groups
+    $groupPref = $RouteGroup.IfExists
+    if (![string]::IsNullOrWhiteSpace($groupPref) -and ($groupPref -ine 'default')) {
+        return $groupPref
+    }
 
-    if ([string]::IsNullOrWhiteSpace($interalPref) -or ($interalPref -ieq 'default')) {
-        if ([string]::IsNullOrWhiteSpace($globalPref) -or ($globalPref -ieq 'default')) {
-            return 'Error'
-        }
+    # from Use-PodeRoute
+    if (![string]::IsNullOrWhiteSpace($RouteIfExists) -and ($RouteIfExists -ine 'default')) {
+        return $RouteIfExists
+    }
 
+    # global preference
+    $globalPref = $PodeContext.Server.Preferences.Routes.IfExists
+    if (![string]::IsNullOrWhiteSpace($globalPref) -and ($globalPref -ine 'default')) {
         return $globalPref
     }
 
-    return $interalPref
+    # final global default
+    return 'Error'
 }
diff --git a/src/Public/Routes.ps1 b/src/Public/Routes.ps1
@@ -795,6 +795,9 @@ The content type of any error pages that may get returned.
 .PARAMETER Authentication
 The name of an Authentication method which should be used as middleware on the Routes.
 
+.PARAMETER IfExists
+Specifies what action to take when a Route already exists. (Default: Default)
+
 .PARAMETER AllowAnon
 If supplied, the Routes will allow anonymous access for non-authenticated users.
 
@@ -839,6 +842,10 @@ function Add-PodeRouteGroup
         [string]
         $Authentication,
 
+        [Parameter()]
+        [ValidateSet('Default', 'Error', 'Overwrite', 'Skip')]
+        $IfExists = 'Default',
+
         [switch]
         $AllowAnon
     )
@@ -891,6 +898,10 @@ function Add-PodeRouteGroup
         if ($RouteGroup.AllowAnon) {
             $AllowAnon = $RouteGroup.AllowAnon
         }
+
+        if ($IfExists -ieq 'default') {
+            $IfExists = Get-PodeRouteIfExistsPreference
+        }
     }
 
     $RouteGroup = @{
@@ -902,6 +913,7 @@ function Add-PodeRouteGroup
         ErrorContentType = $ErrorContentType
         Authentication = $Authentication
         AllowAnon = $AllowAnon
+        IfExists = $IfExists
     }
 
     # add routes
@@ -946,6 +958,9 @@ The content type of any error pages that may get returned.
 .PARAMETER Authentication
 The name of an Authentication method which should be used as middleware on the Static Routes.
 
+.PARAMETER IfExists
+Specifies what action to take when a Static Route already exists. (Default: Default)
+
 .PARAMETER AllowAnon
 If supplied, the Static Routes will allow anonymous access for non-authenticated users.
 
@@ -1001,6 +1016,10 @@ function Add-PodeStaticRouteGroup
         [string]
         $Authentication,
 
+        [Parameter()]
+        [ValidateSet('Default', 'Error', 'Overwrite', 'Skip')]
+        $IfExists = 'Default',
+
         [switch]
         $AllowAnon,
 
@@ -1068,6 +1087,10 @@ function Add-PodeStaticRouteGroup
         if ($RouteGroup.DownloadOnly) {
             $DownloadOnly = $RouteGroup.DownloadOnly
         }
+
+        if ($IfExists -ieq 'default') {
+            $IfExists = Get-PodeRouteIfExistsPreference
+        }
     }
 
     $RouteGroup = @{
@@ -1082,6 +1105,7 @@ function Add-PodeStaticRouteGroup
         Authentication = $Authentication
         AllowAnon = $AllowAnon
         DownloadOnly = $DownloadOnly
+        IfExists = $IfExists
     }
 
     # add routes
@@ -1106,6 +1130,9 @@ A ScriptBlock for adding Signal Routes.
 .PARAMETER EndpointName
 The EndpointName of an Endpoint(s) to use for the Signal Routes.
 
+.PARAMETER IfExists
+Specifies what action to take when a Signal Route already exists. (Default: Default)
+
 .EXAMPLE
 Add-PodeSignalRouteGroup -Path '/signals' -Routes { Add-PodeSignalRoute -Path '/signal1' -Etc }
 #>
@@ -1123,7 +1150,11 @@ function Add-PodeSignalRouteGroup
 
         [Parameter()]
         [string[]]
-        $EndpointName
+        $EndpointName,
+
+        [Parameter()]
+        [ValidateSet('Default', 'Error', 'Overwrite', 'Skip')]
+        $IfExists = 'Default'
     )
 
     if (Test-PodeIsEmpty $Routes) {
@@ -1150,11 +1181,16 @@ function Add-PodeSignalRouteGroup
         if ([string]::IsNullOrWhiteSpace($EndpointName)) {
             $EndpointName = $RouteGroup.EndpointName
         }
+
+        if ($IfExists -ieq 'default') {
+            $IfExists = Get-PodeRouteIfExistsPreference
+        }
     }
 
     $RouteGroup = @{
         Path = $Path
         EndpointName = $EndpointName
+        IfExists = $IfExists
     }
 
     # add routes