Merge pull request #1333 from mdaneri/review_examples

Cleans up the Examples in the repository, and adds them to the Documentation

.gitignore

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

examples/Caching.ps1

@@ -0,0 +1,104 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server and integrate with Redis for caching.
+
+.DESCRIPTION
+    This script sets up a Pode server listening on port 8081 with Redis integration for caching.
+    It checks for the existence of the `redis-cli` command and sets up a Pode server with routes
+    that demonstrate caching with Redis.
+
+.EXAMPLE
+    To run the sample: ./Caching.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/Caching.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine the script path and Pode module path
+    $ScriptPath = (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+    $podePath = Split-Path -Parent -Path $ScriptPath
+
+    # 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 }
+
+try {
+    if (Get-Command redis-cli -ErrorAction Stop) {
+        Write-Output 'redis-cli exists.'
+    }
+}
+catch {
+    throw 'Cannot continue redis-cli does not exist.'
+}
+
+# create a server, and start listening on port 8081
+Start-PodeServer -Threads 3 {
+    # listen on localhost:8081
+    Add-PodeEndpoint -Address localhost -Port 8081 -Protocol Http
+
+    # log errors
+    New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+
+    Set-PodeCacheDefaultTtl -Value 60
+
+    $params = @{
+        Set    = {
+            param($key, $value, $ttl)
+            $null = redis-cli -h localhost -p 6379 SET $key "$($value)" EX $ttl
+        }
+        Get    = {
+            param($key, $metadata)
+            $result = redis-cli -h localhost -p 6379 GET $key
+            $result = [System.Management.Automation.Internal.StringDecorated]::new($result).ToString('PlainText')
+            if ([string]::IsNullOrEmpty($result) -or ($result -ieq '(nil)')) {
+                return $null
+            }
+            return $result
+        }
+        Test   = {
+            param($key)
+            $result = redis-cli -h localhost -p 6379 EXISTS $key
+            return [System.Management.Automation.Internal.StringDecorated]::new($result).ToString('PlainText')
+        }
+        Remove = {
+            param($key)
+            $null = redis-cli -h localhost -p 6379 EXPIRE $key -1
+        }
+        Clear  = {}
+    }
+    if ($params) {
+        Add-PodeCacheStorage -Name 'Redis' @params
+
+        # set default value for cache
+        $cache:cpu = (Get-Random -Minimum 1 -Maximum 1000)
+
+        # get cpu, and cache it
+        Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+            if ((Test-PodeCache -Key 'cpu') -and ($null -ne $cache:cpu)) {
+                Write-PodeJsonResponse -Value @{ CPU = $cache:cpu }
+                # Write-PodeHost 'here - cached'
+                return
+            }
+
+            # $cache:cpu = (Get-Counter '\Processor(_Total)\% Processor Time').CounterSamples.CookedValue
+            Start-Sleep -Milliseconds 500
+            $cache:cpu = (Get-Random -Minimum 1 -Maximum 1000)
+            Write-PodeJsonResponse -Value @{ CPU = $cache:cpu }
+            # $cpu = (Get-Random -Minimum 1 -Maximum 1000)
+            # Write-PodeJsonResponse -Value @{ CPU = $cpu }
+            # Write-PodeHost 'here - raw'
+        }
+    }
+
+}

examples/Create-Routes.ps1

@@ -0,0 +1,58 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server with multiple routes using different approaches.
+
+.DESCRIPTION
+    This script sets up a Pode server listening on port 8081 with various routes demonstrating different
+    approaches to route creation. These include using script blocks, file paths, and direct script inclusion.
+
+.EXAMPLE
+    To run the sample: ./Create-Routes.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/Create-Routes.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+#crete routes using different approaches
+try {
+    # Determine the script path and Pode module path
+    $ScriptPath = (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+    $podePath = Split-Path -Parent -Path $ScriptPath
+
+    # 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 1 -ScriptBlock {
+    Add-PodeEndpoint -Address localhost -Port 8081 -Protocol Http
+    New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+
+    Add-PodeRoute -PassThru -Method Get -Path '/routeCreateScriptBlock/:id' -ScriptBlock ([ScriptBlock]::Create( (Get-Content -Path "$ScriptPath\scripts\routeScript.ps1" -Raw))) |
+        Set-PodeOARouteInfo -Summary 'Test' -OperationId 'routeCreateScriptBlock' -PassThru |
+        Set-PodeOARequest -Parameters @((New-PodeOAStringProperty -Name 'id' | ConvertTo-PodeOAParameter -In Path -Required) )
+
+
+    Add-PodeRoute -PassThru -Method Post -Path '/routeFilePath/:id' -FilePath '.\scripts\routeScript.ps1' | Set-PodeOARouteInfo -Summary 'Test' -OperationId 'routeFilePath' -PassThru |
+        Set-PodeOARequest -Parameters @((New-PodeOAStringProperty -Name 'id' | ConvertTo-PodeOAParameter -In Path -Required) )
+
+
+    Add-PodeRoute -PassThru -Method Get -Path '/routeScriptBlock/:id' -ScriptBlock { $Id = $WebEvent.Parameters['id'] ; Write-PodeJsonResponse -StatusCode 200 -Value @{'id' = $Id } } |
+        Set-PodeOARouteInfo -Summary 'Test' -OperationId 'routeScriptBlock' -PassThru |
+        Set-PodeOARequest -Parameters @((New-PodeOAStringProperty -Name 'id' | ConvertTo-PodeOAParameter -In Path -Required) )
+
+
+    Add-PodeRoute -PassThru -Method Get -Path '/routeScriptSameScope/:id' -ScriptBlock { . $ScriptPath\scripts\routeScript.ps1 } |
+        Set-PodeOARouteInfo -Summary 'Test' -OperationId 'routeScriptSameScope' -PassThru |
+        Set-PodeOARequest -Parameters @((New-PodeOAStringProperty -Name 'id' | ConvertTo-PodeOAParameter -In Path -Required) )
+
+}

examples/Dockerfile

@@ -1,4 +1,4 @@
 FROM badgerati/pode:test
 COPY . /usr/src/app/
-EXPOSE 8085
-CMD [ "pwsh", "-c", "cd /usr/src/app; ./web-pages-docker.ps1" ]
+EXPOSE 8081
+CMD [ "pwsh", "-c", "cd /usr/src/app; ./Web-PagesDocker.ps1" ]

examples/Dot-SourceScript.ps1

@@ -0,0 +1,45 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server and run a script from an external file.
+
+.DESCRIPTION
+    This script sets up a Pode server, enables terminal logging for errors, and uses an external
+    script for additional logic. It imports the Pode module from the source path if available,
+    otherwise from the installed modules.
+
+.EXAMPLE
+    To run the sample: ./Dot-SourceScript.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/Dot-SourceScript.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine the script path and Pode module path
+    $ScriptPath = (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+    $podePath = Split-Path -Parent -Path $ScriptPath
+
+    # 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 }
+
+# or just:
+# Import-Module Pode
+
+# runs the logic once, then exits
+Start-PodeServer {
+
+    New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+    Use-PodeScript -Path './modules/Script1.ps1'
+
+}

examples/External-Funcs.ps1

@@ -0,0 +1,52 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server and use an external module function.
+
+.DESCRIPTION
+    This script sets up a Pode server listening on port 8081, imports an external module containing functions,
+    and includes a route that uses a function from the external module to generate a response.
+
+.EXAMPLE
+    To run the sample: ./External-Funcs.ps1
+
+    Invoke-RestMethod -Uri http://localhost:8081 -Method Get
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/External-Funcs.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine the script path and Pode module path
+    $ScriptPath = (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+    $podePath = Split-Path -Parent -Path $ScriptPath
+
+    # 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 }
+
+# or just:
+# Import-Module Pode
+
+# include the external function module
+Import-PodeModule -Path './modules/External-Funcs.psm1'
+
+# create a server, and start listening on port 8081
+Start-PodeServer {
+
+    # listen on localhost:8085
+    Add-PodeEndpoint -Address localhost -Port 8081 -Protocol Http
+
+    # GET request for "localhost:8085/"
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ 'result' = (Get-Greeting) }
+    }
+
+}

examples/File-Monitoring.ps1

@@ -0,0 +1,51 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server with a view engine and file monitoring.
+
+.DESCRIPTION
+    This script sets up a Pode server listening on port 8081, uses Pode's view engine for rendering
+    web pages, and configures the server to monitor file changes and restart automatically.
+
+.EXAMPLE
+    To run the sample: ./File-Monitoring.ps1
+
+    Invoke-RestMethod -Uri http://localhost:8081 -Method Get
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/File-Monitoring.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine the script path and Pode module path
+    $ScriptPath = (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+    $podePath = Split-Path -Parent -Path $ScriptPath
+
+    # 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 }
+
+# or just:
+# Import-Module Pode
+
+# create a server listening on port 8081, set to monitor file changes and restart the server
+Start-PodeServer {
+
+    Add-PodeEndpoint -Address localhost -Port 8081 -Protocol Http
+    Set-PodeViewEngine -Type Pode
+
+    # GET request for web page on "localhost:8081/"
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeViewResponse -Path 'simple' -Data @{ 'numbers' = @(1, 2, 3); }
+    }
+
+}

examples/File-Watchers.ps1

@@ -0,0 +1,47 @@
+<#
+.SYNOPSIS
+    A sample PowerShell script to set up a Pode server with file watcher and logging.
+
+.DESCRIPTION
+    This script sets up a Pode server, enables terminal logging for errors, and adds a file watcher
+    to monitor changes in PowerShell script files (*.ps1) within the script directory. The server
+    logs file change events and outputs them to the terminal.
+
+.EXAMPLE
+    To run the sample: ./File-Watchers.ps1
+
+.LINK
+    https://github.com/Badgerati/Pode/blob/develop/examples/File-Watchers.ps1
+
+.NOTES
+    Author: Pode Team
+    License: MIT License
+#>
+
+try {
+    # Determine the script path and Pode module path
+    $ScriptPath = (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+    $podePath = Split-Path -Parent -Path $ScriptPath
+
+    # 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 }
+
+# or just:
+# Import-Module Pode
+
+Start-PodeServer -Verbose {
+
+    # enable logging
+    New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+
+    Add-PodeFileWatcher -Path $ScriptPath -Include '*.ps1' -ScriptBlock {
+        "[$($FileEvent.Type)][$($FileEvent.Parameters['project'])]: $($FileEvent.FullPath)" | Out-Default
+    }
+}