Add Enhanced Diagnostic Dump Feature, Suspend-PodeServer and Resume-PodeServer

[mdaneri]

Description

This pull request introduces two new features for enhanced server control: Suspend/Resume functionality and Diagnostic Dumping.

1. Suspend and Resume: Two functions, Suspend-PodeServer and Resume-PodeServer, allow you to temporarily suspend and resume all server operations without a full restart.
2. Diagnostic Dumping: A new Invoke-PodeDump function is introduced to capture detailed diagnostic information during critical failures or fatal exceptions within Pode.

---

Key Features

1. Suspend and Resume Pode Server Operations

The suspend and resume functions provide a way to temporarily pause and later resume all activities on the Pode server, including all associated runspaces. This can be helpful for:

• Debugging: Pause execution without requiring a full server restart.

• Maintenance: Briefly suspend server activities for quick maintenance tasks.

• Performance Throttling: Temporarily halt server activities during high load, if necessary.

• Suspend-PodeServer: Pauses all runspaces associated with the Pode server. It ensures that runspaces enter a debug-like state, preventing the server from processing requests during suspension.

  • Timeout: An optional -Timeout parameter can be used to specify the maximum wait time for each runspace to suspend.
  • Suspend Event: Triggers a ‘Suspend’ event and updates the server status to suspended.

• Resume-PodeServer: Resumes server activities by restoring all runspaces back to their normal execution state.

  • Resume Event: Triggers a ‘Resume’ event, clears the server status, and provides a refreshed view of the console.

2. Diagnostic Dumping with Invoke-PodeDump

The Invoke-PodeDump function is designed to capture detailed diagnostic information during critical failures, enhancing Pode's error handling and debugging workflows.

• Configurable Output Formats: Supports various formats such as JSON, CLIXML, Plain Text, Binary, and YAML.
• Pipeline Support: The ErrorRecord parameter accepts pipeline input, making it easy to integrate within try-catch blocks.
• Dynamic Path and Format Override: Supports runtime overrides for Path and Format, with default settings configurable in server.psd1.
• Optional Application Halt: An optional -Halt switch terminates the application after saving the dump, useful for managing fatal errors requiring shutdown.

Configuration in server.psd1

The server.psd1 configuration file supports default options for Invoke-PodeDump, making it adaptable for various environments:

@{
    Server = @{
        Debug = @{
            Dump = @{
                Enable      = $true
                Format      = 'Yaml'
                Path        = './Dump'
                MaxDepth    = 5
            }
        }
    }
}

• Enable: Toggle memory dump functionality.
• Format: Set the default format (e.g., 'yaml', 'json').
• Path: Specify the directory for saving dump files.
• MaxDepth: Specify the maximum depth for information collection.

Example Usage

1. Basic Suspend and Resume Usage:

   # Suspend all server activities for 60 seconds
   Suspend-PodeServer -Timeout 60
   
   # Perform debugging or maintenance tasks...
   
   # Resume server operations
   Resume-PodeServer

2. Diagnostic Dump with Application Halt (JSON format):

   try {
       # Simulate an error
       throw [System.OutOfMemoryException] "Simulated out of memory error"
   }
   catch {
       $_ | Invoke-PodeDump -Format 'json' -Halt
   }

3. Custom Diagnostic Dump Configuration Override (YAML format, custom path):

   try {
       throw [System.AccessViolationException] "Access violation"
   }
   catch {
       $_ | Invoke-PodeDump -Format 'yaml' -Path 'C:\CustomDumps'
   }

---

Notes

• Automatic Directory Creation: If the specified path for the dump does not exist, it will be created automatically.
• Enhanced Debugging: The suspend and resume functionality, combined with diagnostic dumping, provides powerful tools for handling, diagnosing, and mitigating issues without a full server restart.

[mdaneri]

removed

[Badgerati]

@mdaneri There's a fair few comments, but the most important ones are for the DebuggerHandler class, so I would recommend reading those first.