Pode Watchdog Feature (work in progress)

docs/Tutorials/Watchdog/Overview.md

@@ -0,0 +1,76 @@
+# Watchdog
+
+The Pode Watchdog feature allows you to monitor and manage processes or scripts running within your Pode server. It provides the ability to track the status of a process, log important events, and interact with the process, including via REST API endpoints.
+
+## Features
+- **Process Monitoring**: Continuously track the status, uptime, and performance of processes running under the Pode Watchdog.
+- **File Monitoring with Automatic Restart**: Automatically restart a monitored process when changes are detected in files it depends on, such as configuration or critical files.
+- **Process Control**: Control the monitored processes through REST API commands such as restart, stop, or reset.
+- **Logging**: Watchdog supports logging of important events and errors, which can be useful for auditing and debugging.
+- **Automatic Restarts**: If a monitored process crashes unexpectedly, Pode Watchdog will automatically restart it to ensure it remains active.
+
+### How It Works
+Pode Watchdog monitors processes or files as configured in your Pode server. Once a process is being monitored, you can interact with it using commands or REST API endpoints. Watchdog continuously tracks the process and ensures it remains active by automatically restarting it when necessary—especially when critical files change.
+
+### Typical Use Cases
+1. **Process Monitoring**: Monitor long-running scripts or background services and ensure they are continuously running.
+2. **File Monitoring with Automatic Restart**: Watch for changes in key files, such as configuration files, and restart the process automatically when changes are detected.
+3. **Automatic Restarts**: Ensure critical processes automatically restart if they crash or when monitored files are modified.
+4. **Remote Control**: Use API endpoints to control processes remotely—start, stop, reset, or restart them.
+
+---
+
+### Enabling Pode Watchdog
+To begin using the Pode Watchdog feature, specify the process or file you wish to monitor. Here’s an example to monitor a script file and automatically restart the process when the file changes:
+
+```powershell
+Enable-PodeWatchdog -FilePath './scripts/myProcess.ps1' -FileMonitoring -FileExclude '*.log' -Name 'myProcessWatchdog'
+```
+
+- `-FilePath`: Specifies the path to the script or process you want to monitor.
+- `-FileMonitoring`: Enables file monitoring to track changes to the specified file.
+- `-FileExclude`: Excludes certain files (e.g., `.log` files) from triggering a restart.
+- `-Name`: Assigns a unique identifier for this Watchdog instance.
+
+### **Monitoring**
+You can monitor process metrics, such as status, uptime, or other performance data, using the `Get-PodeWatchdogProcessMetric` cmdlet.
+
+### **Controlling the Watchdog**
+Pode Watchdog provides full control over monitored processes using the `Set-PodeWatchdogProcessState` cmdlet, allowing you to restart, stop, start, or reset the process.
+
+---
+
+### **Example Usage with RESTful Integration**
+
+Here’s an example of how to set up a Pode server with Watchdog and expose REST API routes to monitor and control the process:
+
+```powershell
+Start-PodeServer {
+    # Define an HTTP endpoint
+    Add-PodeEndpoint -Address localhost -Port 8082 -Protocol Http
+
+    # Path to the monitored script
+    $filePath = "./scripts/myProcess.ps1"
+
+    # Set up Watchdog logging
+    New-PodeLoggingMethod -File -Name 'watchdog' -MaxDays 4 | Enable-PodeErrorLogging
+
+    # Enable Watchdog monitoring for the process
+    Enable-PodeWatchdog -FilePath $filePath -FileMonitoring -FileExclude '*.log' -Name 'myProcessWatchdog'
+
+    # Route to check process status
+    Add-PodeRoute -Method Get -Path '/monitor/status' -ScriptBlock {
+        Write-PodeJsonResponse -Value (Get-PodeWatchdogProcessMetric -Name 'myProcessWatchdog' -Type Status)
+    }
+
+    # Route to restart the process
+    Add-PodeRoute -Method Post -Path '/cmd/restart' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{success = (Set-PodeWatchdogProcessState -Name 'myProcessWatchdog' -State Restart)}
+    }
+}
+```
+
+In this example:
+- Pode Watchdog is configured to monitor a script (`myProcess.ps1`).
+- The Pode server exposes REST API routes to check the process status (`/monitor/status`) and restart the process (`/cmd/restart`).
+

examples/Logging.ps1

@@ -82,4 +82,4 @@ Start-PodeServer {
         Set-PodeResponseAttachment -Path 'Anger.jpg'
     }
 
-}
+}

examples/Watchdog/Watchdog-MultipleInstances.ps1

@@ -0,0 +1,51 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server with multiple Pode Watchdog instances for process monitoring.
+
+.DESCRIPTION
+    This script sets up a Pode server that listens on port 8082 and configures two Pode Watchdog instances to monitor the same script.
+    It configures logging for the Watchdog service and monitors the provided script file, excluding `.log` files for both instances.
+    The script dynamically loads the Pode module and enables multiple instances of the Pode Watchdog service for monitoring.
+
+.EXAMPLE
+    To run the sample: ./Watchdog-MultipleInstances.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/Waatchdog/Watchdog-MultipleInstances.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine paths for the Pode module
+    $watchdogPath = Split-Path -Parent -Path $MyInvocation.MyCommand.Path
+    $podePath = Split-Path -Parent -Path (Split-Path -Parent -Path $watchdogPath)
+
+    # Import the Pode module from the source path if it exists, otherwise from installed modules
+    if (Test-Path -Path "$($podePath)/src/Pode.psm1" -PathType Leaf) {
+        Import-Module "$($podePath)/src/Pode.psm1" -Force -ErrorAction Stop
+    }
+    else {
+        Import-Module -Name 'Pode' -MaximumVersion 2.99 -ErrorAction Stop
+    }
+}
+catch { throw }
+
+Start-PodeServer {
+    # Define a simple HTTP endpoint on localhost:8082
+    Add-PodeEndpoint -Address localhost -Port 8082 -Protocol Http
+
+    # Path to the monitored script
+    $filePath = "$($watchdogPath)/monitored.ps1"
+
+    # Set up logging for the Watchdog service with a 4-day retention period
+    New-PodeLoggingMethod -File -Name 'watchdog' -MaxDays 4 | Enable-PodeErrorLogging
+
+    # Enable the first Pode Watchdog instance to monitor the script file, excluding .log files
+    Enable-PodeWatchdog -FilePath $filePath -FileMonitoring -Parameters @{Port = 8080 }  -FileExclude '*.log' -Name 'watch01'
+
+    # Enable the second Pode Watchdog instance to monitor the script file, excluding .log files
+    Enable-PodeWatchdog -FilePath $filePath -FileMonitoring -Parameters @{Port = 8081 } -FileExclude '*.log' -Name 'watch02'
+}

examples/Watchdog/Watchdog-OpenApiIntegration.ps1

@@ -0,0 +1,150 @@
+<#
+.SYNOPSIS
+    A Pode server setup with OpenAPI integration that monitors a script using the Pode Watchdog service.
+
+.DESCRIPTION
+    This script initializes a Pode server with OpenAPI documentation and multiple routes to monitor the status, listeners, requests,
+    and signals of a monitored process via the Pode Watchdog service.
+    It also provides commands to control the state of the monitored process, such as restart, stop, reset, and halt.
+    The script dynamically loads the Pode module and configures OpenAPI viewers and an editor for documentation.
+    This sample demonstrates the integration of Pode Watchdog with OpenAPI routes for monitoring and controlling processes.
+
+.EXAMPLE
+    Run the script to start a Pode server on localhost at port 8082 with OpenAPI documentation:
+
+        ./Watchdog-OpenApiIntegration.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/Watchdog/Watchdog-OpenApiIntegration.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine paths for the Pode module
+    $watchdogPath = Split-Path -Parent -Path $MyInvocation.MyCommand.Path
+    $podePath = Split-Path -Parent -Path (Split-Path -Parent -Path $watchdogPath)
+
+    # Import the Pode module from the source path if it exists, otherwise from installed modules
+    if (Test-Path -Path "$($podePath)/src/Pode.psm1" -PathType Leaf) {
+        Import-Module "$($podePath)/src/Pode.psm1" -Force -ErrorAction Stop
+    }
+    else {
+        Import-Module -Name 'Pode' -MaximumVersion 2.99 -ErrorAction Stop
+    }
+}
+catch { throw }
+
+Start-PodeServer -Threads 2 {
+    # Define a simple HTTP endpoint on localhost:8082
+    Add-PodeEndpoint -Address localhost -Port 8082 -Protocol Http
+
+    # Enable OpenAPI with OpenAPI version 3.0.3 and disable minimal definitions
+    Enable-PodeOpenApi -Path '/docs/openapi' -OpenApiVersion '3.0.3' -DisableMinimalDefinitions
+    Add-PodeOAInfo -Title 'Pode Watchdog sample' -Version 1.0.0
+
+    # Enable various OpenAPI viewers for documentation
+    Enable-PodeOAViewer -Type Swagger -Path '/docs/swagger'
+    Enable-PodeOAViewer -Type ReDoc -Path '/docs/redoc'
+    Enable-PodeOAViewer -Type RapiDoc -Path '/docs/rapidoc'
+    Enable-PodeOAViewer -Type StopLight -Path '/docs/stoplight'
+    Enable-PodeOAViewer -Type Explorer -Path '/docs/explorer'
+    Enable-PodeOAViewer -Type RapiPdf -Path '/docs/rapipdf'
+
+    # Enable OpenAPI editor and bookmarks for easier documentation navigation
+    Enable-PodeOAViewer -Editor -Path '/docs/swagger-editor'
+    Enable-PodeOAViewer -Bookmarks -Path '/docs'
+
+    # Path to the monitored script
+    $filePath = "$($watchdogPath)/monitored.ps1"
+
+    # Set up logging for the Watchdog service
+    New-PodeLoggingMethod -File -Name 'watchdog' -MaxDays 4 | Enable-PodeErrorLogging
+
+    # Enable the Pode Watchdog to monitor the script file, excluding .log files
+    Enable-PodeWatchdog -FilePath $filePath -Parameters @{Port = 8081 } -FileMonitoring -FileExclude '*.log' -Name 'watch01' -RestartServiceAfter 10 -MaxNumberOfRestarts 2 -ResetFailCountAfter 3
+
+     # Define OpenAPI schemas for request, listener, signal, and status metrics
+    $WatchdogSchemaPrefix = 'Watchdog'
+    Add-PodeWatchdogOASchema -WatchdogSchemaPrefix $WatchdogSchemaPrefix
+
+    # REST API to retrieve the list of listeners
+    Add-PodeRoute -PassThru -Method Get -Path '/monitor/listeners' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value (Get-PodeWatchdogProcessMetric -Name 'watch01' -type Listeners)
+    } | Set-PodeOARouteInfo -Summary 'Retrieves a list of active listeners for the monitored Pode server' -Tags 'Monitor' -OperationId 'getListeners' -PassThru |
+        Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content @{'application/json' = "$($WatchdogSchemaPrefix)Listeners" }
+
+    # REST API to retrieve the request count
+    Add-PodeRoute -PassThru -Method Get -Path '/monitor/requests' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value (Get-PodeWatchdogProcessMetric -Name 'watch01' -type Requests)
+    } | Set-PodeOARouteInfo -Summary 'Retrieves the total number of requests handled by the monitored Pode server' -Tags 'Monitor' -OperationId 'getRequests' -PassThru |
+        Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content @{'application/json' = "$($WatchdogSchemaPrefix)Requests" }
+
+    # REST API to retrieve the process status
+    Add-PodeRoute -PassThru -Method Get -Path '/monitor/status' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value (Get-PodeWatchdogProcessMetric -Name 'watch01' -type Status)
+    } | Set-PodeOARouteInfo -Summary 'Retrieves the current status and uptime of the monitored Pode server' -Tags 'Monitor' -OperationId 'getStatus' -PassThru |
+        Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content @{'application/json' = "$($WatchdogSchemaPrefix)Status" }
+
+    # REST API to retrieve signal metrics
+    Add-PodeRoute -PassThru -Method Get -Path '/monitor/signals' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value (Get-PodeWatchdogProcessMetric -Name 'watch01' -type Signals)
+    } | Set-PodeOARouteInfo -Summary 'Retrieves signal metrics for the monitored Pode server' -Tags 'Monitor' -OperationId 'getSignals' -PassThru |
+        Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content @{'application/json' = "$($WatchdogSchemaPrefix)Signals" }
+
+    # REST API to retrieve all metrics of the monitored process
+    Add-PodeRoute -PassThru -Method Get -Path '/monitor' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value (Get-PodeWatchdogProcessMetric -Name 'watch01')
+    } | Set-PodeOARouteInfo -Summary 'Retrieves all monitoring stats for the monitored Pode server' -Tags 'Monitor' -OperationId 'getMonitor' -PassThru |
+        Add-PodeOAResponse -StatusCode 200 -Description 'Successful operation' -Content @{'application/json' = "$($WatchdogSchemaPrefix)Monitor" }
+
+    # REST API to restart the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/restart' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Restart) }
+    } | Set-PodeOARouteInfo -Summary 'Restarts the monitored Pode server' -Tags 'Command' -OperationId 'restart'
+
+    # REST API to reset the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/reset' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Reset) }
+    } | Set-PodeOARouteInfo -Summary 'Stops and restarts the monitored Pode server process' -Tags 'Command' -OperationId 'reset'
+
+    # REST API to stop the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/stop' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Stop) }
+    } | Set-PodeOARouteInfo -Summary 'Stops the monitored Pode server process' -Tags 'Command' -OperationId 'stop'
+
+    # REST API to start the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/start' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Start) }
+    } | Set-PodeOARouteInfo -Summary 'Starts the monitored Pode server process' -Tags 'Command' -OperationId 'start'
+
+    # REST API to terminate (force stop) the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/terminate' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Terminate) }
+    } | Set-PodeOARouteInfo -Summary 'Terminates (force stops) the monitored Pode server process' -Tags 'Command' -OperationId 'terminate'
+
+    # REST API to disable the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/disable' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Disable) }
+    } | Set-PodeOARouteInfo -Summary 'Disables the monitored Pode server process' -Tags 'Command' -OperationId 'disable'
+
+    # REST API to enable the monitored process
+    Add-PodeRoute -PassThru -Method Post -Path '/cmd/enable' -ScriptBlock {
+        Write-PodeJsonResponse -StatusCode 200 -Value @{ success = (Set-PodeWatchdogProcessState -Name 'watch01' -State Enable) }
+    } | Set-PodeOARouteInfo -Summary 'Enables the monitored Pode server process' -Tags 'Command' -OperationId 'enable'
+
+    # REST API to disable Auto Restart
+    Add-PodeRoute -PassThru -Method Post -Path '/settings/noAutoRestart' -ScriptBlock {
+        Disable-PodeWatchdogAutoRestart -Name 'watch01'
+        Set-PodeResponseStatus -Code 200
+    } | Set-PodeOARouteInfo -Summary 'Disables the auto-restart feature for the monitored Pode server process' -Tags 'Settings' -OperationId 'noAutoRestart'
+
+    # REST API to enable Auto Restart
+    Add-PodeRoute -PassThru -Method Post -Path '/settings/autoRestart' -ScriptBlock {
+        Enable-PodeWatchdogAutoRestart -Name 'watch01'
+        Set-PodeResponseStatus -Code 200
+    } | Set-PodeOARouteInfo -Summary 'Enables the auto-restart feature for the monitored Pode server process' -Tags 'Settings' -OperationId 'autoRestart'
+
+}

examples/Watchdog/Watchdog-SingleInstance.ps1

@@ -0,0 +1,47 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server with a Pode Watchdog for process monitoring.
+
+.DESCRIPTION
+    This script sets up a Pode server that listens on port 8082 and monitors a script using the Pode Watchdog service.
+    It configures logging for the Watchdog service and monitors the provided script file, excluding `.log` files.
+    The script dynamically loads the Pode module and sets up basic process monitoring using the Pode Watchdog.
+
+.EXAMPLE
+    To run the sample: ./Watchdog-Sample.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/Waatchdog/Watchdog-SingleInstance.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+
+try {
+    # Determine paths for the Pode module
+    $watchdogPath = Split-Path -Parent -Path $MyInvocation.MyCommand.Path
+    $podePath = Split-Path -Parent -Path (Split-Path -Parent -Path $watchdogPath)
+
+    # Import the Pode module from the source path if it exists, otherwise from installed modules
+    if (Test-Path -Path "$($podePath)/src/Pode.psm1" -PathType Leaf) {
+        Import-Module "$($podePath)/src/Pode.psm1" -Force -ErrorAction Stop
+    }
+    else {
+        Import-Module -Name 'Pode' -MaximumVersion 2.99 -ErrorAction Stop
+    }
+}
+catch { throw }
+
+Start-PodeServer {
+    # Define a simple HTTP endpoint on localhost:8082
+    Add-PodeEndpoint -Address localhost -Port 8082 -Protocol Http
+
+    # Path to the monitored script
+    $filePath = "$($watchdogPath)/monitored.ps1"
+
+    # Enable the Pode Watchdog to monitor the script file, excluding .log files
+    Enable-PodeWatchdog -FilePath $filePath -Parameters @{Port = 8081 } -FileMonitoring -FileExclude '*.log' -Name 'watch01'
+
+}