Add Diagnostic Dumping Functionality

.gitignore

@@ -266,3 +266,6 @@ examples/PetStore/data/PetData.json
 packers/choco/pode.nuspec
 packers/choco/tools/ChocolateyInstall.ps1
 docs/Getting-Started/Samples.md
+
+# Dump Folder
+Dump

docs/Getting-Started/Debug.md

@@ -246,3 +246,90 @@ Add-PodeSchedule -Name 'TestSchedule' -Cron '@hourly' -ScriptBlock {
 ```
 
 In this example, the schedule outputs the name of the runspace executing the script block every hour. This can be useful for logging and monitoring purposes when dealing with multiple schedules or tasks.
+
+
+## Memory Dump for Diagnostics
+
+Pode provides a powerful memory dump feature to capture detailed information during critical failures or fatal exceptions. This feature, triggered by the `Invoke-PodeDump` function, captures the state of your application, including memory usage, runspace details, variables, and stack traces. You can configure the dump format, enable or disable it, and specify the save location. By default, Pode saves the dump in JSON format, but you can also choose from other supported formats.
+
+### Configuring Dump Defaults
+
+To set up default options for the memory dump feature in Pode, you can configure them in the `server.psd1` configuration file. Under the `Server.Debug.Dump` section, you can specify whether to enable the dump, the default format, and the save path. Below is an example configuration for setting up defaults:
+
+```powershell
+@{
+    Server = @{
+        Debug = @{
+            Breakpoints = @{
+                Enable = $true
+            }
+            Dump = @{
+                Enable = $true
+                Format = 'Yaml'  # Options: 'json', 'clixml', 'txt', 'bin', 'yaml'
+                Path = './Dump'  # Path to save the dump files
+            }
+        }
+    }
+}
+```
+
+- **Enable**: Boolean value to enable or disable the memory dump feature.
+- **Format**: Specifies the default format for the dump file. Supported formats are `json`, `clixml`, `txt`, `bin`, and `yaml`.
+- **Path**: Specifies the directory where the dump file will be saved. If the directory does not exist, it will be created.
+
+### Overriding Default Settings at Runtime
+
+The `Invoke-PodeDump` function allows you to override these defaults at runtime by passing parameters to specify the format and path. This can be useful for debugging in specific cases without altering the default configuration.
+
+```powershell
+try {
+    # Simulate a critical error
+    throw [System.OutOfMemoryException] "Simulated out of memory error"
+}
+catch {
+    # Capture the dump with custom options
+    Invoke-PodeDump -ErrorRecord $_ -Format 'clixml' -Path 'C:\CustomDump' -Halt
+}
+```
+
+In this example:
+- The memory dump is saved in CLIXML format instead of the default.
+- The dump file is saved in the specified directory (`C:\CustomDump`) instead of the default path.
+- The `-Halt` switch will terminate the application after the dump is saved.
+
+### Using the Dump Feature in Pode
+
+To use the dump feature effectively in your Pode server, you may want to include it in specific places within your code to capture state information when critical errors occur.
+
+Example usage in a Pode server:
+
+```powershell
+Start-PodeServer -EnableBreakpoints {
+    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        try {
+            # Simulate an operation that could fail
+            $processes = Get-Process -ErrorAction Stop
+            Write-PodeJsonResponse -Value @{ Process = $processes[0] }
+        }
+        catch {
+            # Invoke a memory dump when a critical error occurs
+            $_ | Invoke-PodeDump -Halt
+        }
+    }
+}
+```
+
+In this setup, if an error occurs in the route, `Invoke-PodeDump` is called, capturing the current state and halting the application if the `-Halt` switch is set.
+
+### Dumping Options and Best Practices
+
+- **Enabling Dump in Production**: Enabling the dump in production can be valuable for diagnosing unexpected failures. However, use it selectively, especially if you are using binary or CLIXML formats, as they can produce large files.
+- **Specifying Formats**: Choose a format based on your needs:
+  - **JSON** and **YAML** are human-readable and suitable for quick inspection.
+  - **CLIXML** is ideal for preserving object structures, especially when analyzing PowerShell-specific data.
+  - **Binary** is compact and suitable for raw state captures but requires deserialization for inspection.
+- **Setting the Path**: Use a dedicated folder for dump files (e.g., `./Dump`) to keep diagnostic files organized. The default path in the configuration can be overridden at runtime if needed.
+
+With these configurations and usage practices, the memory dump feature in Pode can provide a powerful tool for diagnostics and debugging, capturing critical state information at the time of failure.

examples/PetStore/Petstore-OpenApi.ps1

@@ -895,5 +895,17 @@ Some useful links:
             Set-PodeOARequest -Parameters   (  New-PodeOAStringProperty -Name 'username' -Description 'The name that needs to be deleted.' -Required | ConvertTo-PodeOAParameter -In Path ) -PassThru |
             Add-PodeOAResponse -StatusCode 400 -Description 'Invalid username supplied' -PassThru |
             Add-PodeOAResponse -StatusCode 404 -Description 'User not found'
+
+        Add-PodeRoute -PassThru -Method Get -Path '/dump' -ScriptBlock {
+            $format = $WebEvent.Query['format']
+            try {
+                # Simulate a critical error
+                throw [System.DivideByZeroException] 'Simulated divide by zero error'
+            }
+            catch {
+                $_ | Invoke-PodeDump  -Format $format
+            }
+        } | Set-PodeOARouteInfo -Summary 'Dump state' -Description 'Dump the memory state of the server.' -Tags 'dump'  -OperationId 'dump'-PassThru |
+            Set-PodeOARequest -Parameters (New-PodeOAStringProperty -Name 'format' -Description 'Dump export format.' -Enum 'json', 'clixml', 'txt', 'bin', 'yaml' -Default 'json' | ConvertTo-PodeOAParameter -In Query )
     }
 }

examples/PetStore/data/PetData.json

@@ -43,6 +43,14 @@
         "petId": 1,
         "id": 2,
         "quantity": 50
+      },
+      "10": {
+        "id": 10,
+        "petId": 198772,
+        "quantity": 7,
+        "shipDate": "2024-11-04T02:08:54.351Z",
+        "status": "approved",
+        "complete": true
       }
     },
     "Scope": [

examples/PetStore/server.psd1

@@ -10,10 +10,22 @@
     Server                = @{
         Timeout  = 60
         BodySize = 100MB
+        Debug       = @{
+            Breakpoints = @{
+                Enable = $true
+            }
+            Dump        = @{
+                Enabled = $true
+                Format  = 'json'
+                Path    = './Dump'
+                MaxDepth = 6
+            }
+        }
     }
     Web                   = @{
         OpenApi = @{
             DefaultDefinitionTag = 'v3.0.3'
         }
     }
+
 }

examples/server.psd1

@@ -63,6 +63,12 @@
             Breakpoints = @{
                 Enable = $true
             }
+            Dump        = @{
+                Enabled = $true
+                Format  = 'json'
+                Path    = './Dump'
+                MaxDepth = 6
+            }
         }
     }
 }

src/Pode.psd1

@@ -144,6 +144,7 @@
         'Get-PodeCurrentRunspaceName',
         'Set-PodeCurrentRunspaceName',
         'Invoke-PodeGC',
+        'Invoke-PodeDump',
 
         # routes
         'Add-PodeRoute',

src/Pode.psm1

@@ -139,4 +139,8 @@ try {
 catch {
     throw ("Failed to load the Pode module. $_")
 }
+finally {
+    # Cleanup temporary variables
+    Remove-Variable -Name 'tmpPodeLocale', 'localesPath', 'moduleManifest', 'root', 'version', 'libsPath', 'netFolder', 'podeDll', 'sysfuncs', 'sysaliases', 'funcs', 'aliases', 'moduleManifestPath', 'moduleVersion' -ErrorAction SilentlyContinue
+}
 

src/Private/Context.ps1

@@ -190,6 +190,19 @@ function New-PodeContext {
         'Errors' = 'errors'
     }
 
+    $ctx.Server.Debug = @{
+        Breakpoints = @{
+            Debug = $false
+        }
+        Dump        = @{
+            Enabled  = $true
+            Format   = 'Json'
+            Path     = './Dump'
+            MaxDepth = 5
+            Param    = @{}
+        }
+    }
+
     # check if there is any global configuration
     $ctx.Server.Configuration = Open-PodeConfiguration -ServerRoot $ServerRoot -Context $ctx
 
@@ -214,10 +227,6 @@ function New-PodeContext {
 
     # debugging
     if ($EnableBreakpoints) {
-        if ($null -eq $ctx.Server.Debug) {
-            $ctx.Server.Debug = @{ Breakpoints = @{} }
-        }
-
         $ctx.Server.Debug.Breakpoints.Enabled = $EnableBreakpoints.IsPresent
     }
 
@@ -320,13 +329,13 @@ function New-PodeContext {
 
     # routes for pages and api
     $ctx.Server.Routes = [ordered]@{
-# common methods
+        # common methods
         'get'     = [ordered]@{}
         'post'    = [ordered]@{}
         'put'     = [ordered]@{}
         'patch'   = [ordered]@{}
         'delete'  = [ordered]@{}
-# other methods
+        # other methods
         'connect' = [ordered]@{}
         'head'    = [ordered]@{}
         'merge'   = [ordered]@{}
@@ -408,6 +417,7 @@ function New-PodeContext {
     $ctx.Tokens = @{
         Cancellation = [System.Threading.CancellationTokenSource]::new()
         Restart      = [System.Threading.CancellationTokenSource]::new()
+        Dump         = [System.Threading.CancellationTokenSource]::new()
     }
 
     # requests that should be logged
@@ -900,7 +910,14 @@ function Set-PodeServerConfiguration {
     # debug
     $Context.Server.Debug = @{
         Breakpoints = @{
-            Enabled = [bool]$Configuration.Debug.Breakpoints.Enable
+            Enabled = [bool](Protect-PodeValue -Value  $Configuration.Debug.Breakpoints.Enable -Default $Context.Server.Debug.Breakpoints.Enable)
+        }
+        Dump        = @{
+            Enabled = [bool](Protect-PodeValue -Value  $Configuration.Debug.Dump.Enabled -Default $Context.Server.Debug.Dump.Enabled)
+            Format  = [string] (Protect-PodeValue -Value  $Configuration.Debug.Dump.Format -Default $Context.Server.Debug.Dump.Format)
+            Path    = [string] (Protect-PodeValue -Value  $Configuration.Debug.Dump.Path -Default $Context.Server.Debug.Dump.Path)
+            MaxDepth = [int] (Protect-PodeValue -Value  $Configuration.Debug.Dump.MaxDepth -Default $Context.Server.Debug.Dump.MaxDepth)
+            Param   = @{}
         }
     }
 }