Merge branch 'develop' into Issue-Badgerati#1329

.github/CONTRIBUTING.md

@@ -30,6 +30,7 @@ The following is a set of guidelines for contributing to Pode on GitHub. These a
       - [Where-Object](#where-object)
       - [Select-Object](#select-object)
       - [Measure-Object](#measure-object)
+      - [New-Object](#new-object)
 
 ## Code of Conduct
 
@@ -245,3 +246,15 @@ Instead of using the `Measure-Object` commandlet, please use either the `.Length
 (@(1, 2, 3)).Length
 (@{ Name = 'Rick' }).Count
 ```
+
+#### New-Object
+
+Instead of using the `New-Object` commandlet, please use `::new()` as this is far faster than the former.
+
+```powershell
+# instead of
+$stream = New-Object System.IO.MemoryStream
+
+# do this
+$stream = [System.IO.MemoryStream]::new()
+```

.github/workflows/PSScriptAnalyzer.yml

@@ -3,7 +3,7 @@
 # separate terms of service, privacy policy, and support
 # documentation.
 #
-# https://github.com/microsoft/action-psscriptanalyzer
+# https://github.com/microsoft/psscriptanalyzer-action
 # For more information on PSScriptAnalyzer in general, see
 # https://github.com/PowerShell/PSScriptAnalyzer
 
@@ -48,15 +48,11 @@ jobs:
       - name: Run PSScriptAnalyzer
         uses: microsoft/psscriptanalyzer-action@6b2948b1944407914a58661c49941824d149734f
         with:
-          # Check https://github.com/microsoft/action-psscriptanalyzer for more info about the options.
-          # The below set up runs PSScriptAnalyzer to your entire repository and runs some basic security rules.
-          path: .\
+          path: .\src
           recurse: true
-          # Include your own basic security rules. Removing this option will run all the rules
-          includeRule: '"PSAvoidUsingCmdletAliases" ,"PSAvoidUsingPlainTextForPassword","PSAvoidUsingWriteHost","PSAvoidUsingInvokeExpression","PSUseShouldProcessForStateChangingFunctions","PSAvoidUsingUsernameAndPasswordParams","PSUseProcessBlockForPipelineCommand","PSAvoidUsingConvertToSecureStringWithPlainText","PSUseSingularNouns","PSReviewUnusedParameter"'
+          settings: .\PSScriptAnalyzerSettings.psd1
           output: results.sarif
 
-      # Upload the SARIF file generated in the previous step
       - name: Upload SARIF results file
         uses: github/codeql-action/upload-sarif@v3
         with:

.github/workflows/VirusTotal-Releases.yml

@@ -0,0 +1,20 @@
+name: VirusTotal Scan - Releases
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Run VirusTotal Scan
+      uses: crazy-max/ghaction-virustotal@v4
+      with:
+        vt_api_key: ${{ secrets.VIRUSTOTAL_API_KEY }}
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        update_release_body: true
+        request_rate: 4
+        files: |
+          .zip$

.github/workflows/VirusTotal.yml

@@ -0,0 +1,59 @@
+name: VirusTotal Scan
+
+on:
+  push:
+    branches:
+    - 'develop'
+    paths:
+    - 'src/**'
+    - 'pode.build.ps1'
+    - '.github/workflows/VirusTotal.yml'
+  pull_request:
+    branches:
+    - 'master'
+    paths:
+    - 'src/**'
+    - 'pode.build.ps1'
+    - '.github/workflows/VirusTotal.yml'
+  schedule:
+    - cron: '0 12 * * *'
+
+env:
+  INVOKE_BUILD_VERSION: '5.11.1'
+  POWERSHELL_VERSION: 'lts'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 8.0.x
+
+    - name: Setup Powershell
+      shell: pwsh
+      run: |
+        Install-Module -Name InvokeBuild -RequiredVersion $env:INVOKE_BUILD_VERSION -Force
+        Invoke-Build SetupPowerShell -PowerShellVersion $env:POWERSHELL_VERSION
+
+    - name: Install Invoke-Build
+      shell: pwsh
+      run: |
+        Install-Module -Name InvokeBuild -RequiredVersion $env:INVOKE_BUILD_VERSION -Force
+
+    - name: Build Zip Package
+      shell: pwsh
+      run: |
+        Invoke-Build Compress
+
+    - name: Run VirusTotal Scan
+      uses: crazy-max/ghaction-virustotal@v4
+      with:
+        vt_api_key: ${{ secrets.VIRUSTOTAL_API_KEY }}
+        request_rate: 4
+        files: |
+          ./deliverable/*.zip

.github/workflows/ci-pwsh7_2.yml

@@ -25,7 +25,7 @@ on:
 
 env:
   INVOKE_BUILD_VERSION: '5.11.1'
-  POWERSHELL_VERSION: '7.2.19'
+  POWERSHELL_VERSION: '7.2.24'
 
 jobs:
   build:

.gitignore

@@ -265,3 +265,4 @@ examples/PetStore/data/PetData.json
 
 packers/choco/pode.nuspec
 packers/choco/tools/ChocolateyInstall.ps1
+docs/Getting-Started/Samples.md

.vscode/settings.json

@@ -2,6 +2,8 @@
     "editor.formatOnSave": true,
     "editor.formatOnType": false,
     "editor.minimap.enabled": false,
+    "editor.insertSpaces": true,
+    "editor.tabSize": 4,
     "powershell.codeFormatting.addWhitespaceAroundPipe": true,
     "powershell.codeFormatting.alignPropertyValuePairs": true,
     "powershell.codeFormatting.autoCorrectAliases": true,
@@ -21,6 +23,7 @@
     "powershell.codeFormatting.whitespaceBetweenParameters": false,
     "powershell.codeFormatting.whitespaceInsideBrace": true,
     "powershell.scriptAnalysis.settingsPath": "PSScriptAnalyzerSettings.psd1",
+    "powershell.scriptAnalysis.enable": true,
     "files.trimTrailingWhitespace": true,
     "files.associations": {
         "*.pode": "html"
@@ -32,5 +35,8 @@
     "javascript.format.insertSpaceAfterFunctionKeywordForAnonymousFunctions": false,
     "javascript.format.insertSpaceAfterKeywordsInControlFlowStatements": true,
     "javascript.format.insertSpaceBeforeAndAfterBinaryOperators": true,
-    "javascript.format.insertSpaceBeforeFunctionParenthesis": false
+    "javascript.format.insertSpaceBeforeFunctionParenthesis": false,
+    "[yaml]": {
+        "editor.tabSize": 2
+    }
 }

PSScriptAnalyzerSettings.psd1

@@ -1,15 +1,33 @@
-# PSScriptAnalyzerSettings.psd1
 @{
-    Severity     = @('Error', 'Warning', 'Information')
+    Severity            = @('Error', 'Warning', 'Information')
+    IncludeDefaultRules = $true
 
-    Rules = @{
+    CustomRulePath      = @(
+        './analyzers/AvoidNewObjectRule.psm1'
+    )
+
+    Rules               = @{
         PSReviewUnusedParameter = @{
             CommandsToTraverse = @(
-                'Where-Object','Remove-PodeRoute'
+                'Where-Object',
+                'Remove-PodeRoute'
             )
         }
+        AvoidNewObjectRule      = @{
+            Severity = 'Warning'
+        }
     }
-    ExcludeRules = @( 'PSAvoidUsingPlainTextForPassword','PSUseShouldProcessForStateChangingFunctions',
-    'PSAvoidUsingUsernameAndPasswordParams','PSUseProcessBlockForPipelineCommand','PSAvoidUsingConvertToSecureStringWithPlainText','PSReviewUnusedParameter' )
+
+    ExcludeRules        = @(
+        'PSAvoidUsingPlainTextForPassword',
+        'PSUseShouldProcessForStateChangingFunctions',
+        'PSAvoidUsingUsernameAndPasswordParams',
+        'PSUseProcessBlockForPipelineCommand',
+        'PSAvoidUsingConvertToSecureStringWithPlainText',
+        'PSReviewUnusedParameter',
+        'PSAvoidAssignmentToAutomaticVariable',
+        'PSUseBOMForUnicodeEncodedFile',
+        'PSAvoidTrailingWhitespace'
+    )
 
 }

analyzers/AvoidNewObjectRule.psm1

@@ -0,0 +1,38 @@
+function Measure-AvoidNewObjectRule {
+    [CmdletBinding()]
+    [OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.Language.ScriptBlockAst]
+        $ScriptBlockAst
+    )
+
+    # Initialize an empty array to collect diagnostic records
+    $diagnostics = @()
+
+    try {
+        # Traverse the AST to find all instances of New-Object cmdlet
+        $ScriptBlockAst.FindAll({
+                param($Ast)
+                $Ast -is [System.Management.Automation.Language.CommandAst] -and
+                $Ast.CommandElements[0].Extent.Text -eq 'New-Object'
+            }, $true) | ForEach-Object {
+            $diagnostics += [PSCustomObject]@{
+                Message    = "Avoid using 'New-Object' and use '::new()' instead."
+                Extent     = $_.Extent
+                RuleName   = 'AvoidNewObjectRule'
+                Severity   = 'Warning'
+                ScriptName = $FileName
+            }
+        }
+
+        # Return the diagnostic records
+        return $diagnostics
+    }
+    catch {
+        $PSCmdlet.ThrowTerminatingError($PSItem)
+    }
+}
+
+Export-ModuleMember -Function Measure-AvoidNewObjectRule

docs/Getting-Started/Debug.md

@@ -174,3 +174,75 @@ The steps to attach to the Pode process are as follows:
 5. You'll also be able to query variables as well, such as `$WebEvent` and other variables you might have created.
 
 6. When you are done debugging the current request, hit the `d` key.
+
+
+
+## Managing Runspace Names
+
+### Internal Runspace Naming
+
+In Pode, internal runspaces are automatically assigned distinct names. This built-in naming convention is crucial for identifying and managing runspaces efficiently, particularly during debugging or when monitoring multiple concurrent processes.
+
+Pode uses specific naming patterns for its internal runspaces, which include:
+
+- **Pode_Web_Listener_1**
+- **Pode_Signals_Broadcaster_1**
+- **Pode_Signals_Listener_1**
+- **Pode_Web_KeepAlive_1**
+- **Pode_Files_Watcher_1**
+- **Pode_Main_Logging_1**
+- **Pode_Timers_Scheduler_1**
+- **Pode_Schedules_[Schedule Name]_1** – where `[Schedule Name]` is the name of the schedule.
+- **Pode_Tasks_[Task Name]_1** – where `[Task Name]` is the name of the task.
+
+These default names are automatically assigned by Pode, making it easier to identify the purpose of each runspace during execution.
+
+### Customizing Runspace Names
+
+By default, Pode’s Tasks, Schedules, and Timers label their associated runspaces with their own names (as shown above). This simplifies the identification of runspaces when debugging or reviewing logs.
+
+However, if a different runspace name is needed, Pode allows you to customize it. Inside the script block of `Add-PodeTask`, `Add-PodeSchedule`, or `Add-PodeTimer`, you can use the `Set-PodeCurrentRunspaceName` cmdlet to assign any custom name you prefer.
+
+```powershell
+Set-PodeCurrentRunspaceName -Name 'Custom Runspace Name'
+```
+
+This cmdlet sets a custom name for the runspace, making it easier to track during execution.
+
+#### Example
+
+Here’s an example that demonstrates how to set a custom runspace name in a Pode task:
+
+```powershell
+Add-PodeTask -Name 'Test2' -ScriptBlock {
+    param($value)
+    # Set a custom name for the current runspace
+    Set-PodeCurrentRunspaceName -Name 'My Fancy Runspace'
+    Start-Sleep -Seconds 10
+    "A $($value) is never late, it arrives exactly when it means to" | Out-Default
+}
+```
+
+In this example, the `Set-PodeCurrentRunspaceName` cmdlet assigns the custom name `'My Fancy Runspace'` to the task's runspace. This is especially useful for debugging or when examining logs, as the custom name makes the runspace more recognizable.
+
+### Retrieving Runspace Names
+
+Pode also provides the `Get-PodeCurrentRunspaceName` cmdlet to retrieve the name of the current runspace. This is particularly helpful when you need to log or display the runspace name dynamically during execution.
+
+```powershell
+Get-PodeCurrentRunspaceName
+```
+
+This cmdlet returns the name of the current runspace, allowing for easier tracking and management in complex scenarios with multiple concurrent runspaces.
+
+#### Example
+
+Here’s an example that uses `Get-PodeCurrentRunspaceName` to output the runspace name during the execution of a schedule:
+
+```powershell
+Add-PodeSchedule -Name 'TestSchedule' -Cron '@hourly' -ScriptBlock {
+    Write-PodeHost "Runspace name: $(Get-PodeCurrentRunspaceName)"
+}
+```
+
+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.

docs/Getting-Started/Installation.md

@@ -93,7 +93,7 @@ docker pull docker.pkg.github.com/badgerati/pode/pode:2.2.2
 
 ```powershell
 # for latest
-docker pull docker.pkg.github.com/badgerati/pode/pode:latest-apline
+docker pull docker.pkg.github.com/badgerati/pode/pode:latest-alpine
 
 # or the following for a specific version:
 docker pull docker.pkg.github.com/badgerati/pode/pode:2.2.2-alpine

docs/Hosting/IIS.md

@@ -202,7 +202,7 @@ The server will get a URL path of `/api/etc`, but you can keep your route paths
 
 Although Pode does have support for HTTPS/WSS, when running via IIS it takes control of HTTPS/WSS for us - this is why the endpoints are forced to HTTP/WS.
 
-You can setup a binding in IIS for HTTPS (still HTPPS for WSS) with a Certificate, and IIS will deal with SSL for you:
+You can setup a binding in IIS for HTTPS (still HTTPS for WSS) with a Certificate, and IIS will deal with SSL for you:
 
 1. Open IIS, and expand the Sites folder
 2. Right click your Site, and select "Edit Bindings..."

docs/Servers/TCP.md

@@ -172,14 +172,14 @@ Start-PodeServer {
 
 Verbs will be passed the `$TcpEvent` object, that contains the Request, Response, and other properties:
 
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-| Request | object | The raw Request object |
-| Response | object | The raw Response object |
-| Lockable | hashtable | A synchronized hashtable that can be used with `Lock-PodeObject` |
-| 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 |
-| Parameters | hashtable | Contains the parsed parameter values from the Verb's path |
-| Timestamp | datetime | The current date and time of the Request |
+| Name       | Type      | Description                                                                                                                                |
+| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Request    | object    | The raw Request object                                                                                                                     |
+| Response   | object    | The raw Response object                                                                                                                    |
+| Lockable   | hashtable | A synchronized hashtable that can be used with `Lock-PodeObject`                                                                           |
+| 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 |
+| Parameters | hashtable | Contains the parsed parameter values from the Verb's path                                                                                  |
+| Timestamp  | datetime  | The current date and time of the Request                                                                                                   |
 
 ## Test Send
 
@@ -189,11 +189,11 @@ The following function can be used to test sending messages to a TCP server. Thi
 function Send-TCPMessage($Endpoint, $Port, $Message) {
     # Setup connection
     $Address = [System.Net.IPAddress]::Parse([System.Net.Dns]::GetHostAddresses($EndPoint))
-    $Socket = New-Object System.Net.Sockets.TCPClient($Address,$Port)
+    $Socket = [System.Net.Sockets.TcpClient]::new($Address, $Port)
 
-    # Setup stream wrtier
+    # Setup stream writer
     $Stream = $Socket.GetStream()
-    $Writer = New-Object System.IO.StreamWriter($Stream)
+    $Writer = [System.IO.StreamWriter]::new($Stream)
 
     # Write message to stream
     $Writer.WriteLine($Message)