Merge pull request #57 from Badgerati/develop

v0.14.0

.gitignore

@@ -15,7 +15,6 @@
 [Rr]eleases/
 x64/
 x86/
-build/
 bld/
 [Bb]in/
 [Oo]bj/

Dockerfile

@@ -1,4 +1,4 @@
-FROM microsoft/powershell:latest
+FROM microsoft/powershell:6.0.2-ubuntu-xenial
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
-COPY ./src/ /usr/local/share/powershell/Modules/Pode
+COPY ./src/ /usr/local/share/powershell/Modules/Pode

README.md

@@ -1,6 +1,7 @@
 # Pode
 
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/Badgerati/Pode/master/LICENSE.txt)
+[![Build](https://ci.appveyor.com/api/projects/status/nvl1xmh31crp10ea/branch/develop?svg=true)](https://ci.appveyor.com/project/Badgerati/pode/branch/develop)
 [![Gitter](https://badges.gitter.im/Badgerati/Pode.svg)](https://gitter.im/Badgerati/Pode?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
 [![Chocolatey](https://img.shields.io/chocolatey/v/pode.svg?colorB=a1301c)](https://chocolatey.org/packages/pode)
@@ -31,6 +32,8 @@ Pode is a Cross-Platform PowerShell framework that allows you to host [REST APIs
         * [Attach File](#attach-file)
         * [Logging](#logging)
         * [Shared State](#shared-state)
+        * [File Monitor](#file-monitor)
+        * [Access Rules](#access-rules)
 * [Pode Files](#pode-files)
     * [Third-Party Engines](#third-party-view-engines)
 
@@ -46,6 +49,8 @@ Pode is a Cross-Platform PowerShell framework that allows you to host [REST APIs
 * Setup async timers to be used as one off tasks, or for housekeeping services
 * Supports logging to CLI, Files, and custom loggers to other services like LogStash, etc.
 * Cross-state runspace variable access for timers, routes and loggers
+* Optional file monitoring to trigger internal server restart on file changes
+* Ability to allow/deny requests from certain IP addresses and subnets
 
 ## Install
 
@@ -186,6 +191,23 @@ Server -IP 127.0.0.2 -Port 8080 {
 }
 ```
 
+Conversely, you can also use `listen`. If you use `listen` then you do *not* need to supply any of the following parameters to `Server`: `IP`, `Port`, `Smtp`, `Https`, `Tcp`. If you do, then `listen` will just override them.
+
+You can use `listen` within your `Server` block, specifying the IP, Port and Protocol:
+
+```powershell
+Server {
+    # listen on everything for http
+    listen *:8080 http
+
+    # listen on localhost for smtp
+    listen 127.0.0.1:25 smtp
+
+    # listen on ip for https
+    listen 10.10.1.4:8443 https
+}
+```
+
 ### Timers
 
 Timers are supported in all `Server` types, they are async processes that run in a separate runspace along side your main server logic. The following are a few examples of using timers, more can be found in `examples/timers.ps1`:
@@ -467,8 +489,51 @@ Server -Port 8085 {
 
 > You can put any type of variable into the global state, including `scriptblock`s
 
-## Pode Files
+#### File Monitor
+
+> Warning: Monitoring currently only works in Windows and some Unix environments - on Unix you *will* need dotnet-core 2.1 installed. Monitoring does not work in Docker at the moment, as the official PowerShell container only supports dotnet-core 2.0/powershell-core 6.0. Once the container supports powershell-core 6.1 I'll release a hot-fix container for Docker to support monitoring
+
+Pode has inbuilt file monitoring that can be enabled, whereby Pode will trigger an internal server restart if it detects file changes within the same directory as your Pode script. To enable the monitoring supply the `-FileMonitor` switch to your `Server`:
+
+```powershell
+Server -Port 8085 {
+    # logic
+} -FileMonitor
+```
 
+Once enabled, Pode will actively monitor all file changes within the directory of your script - if your script was at `C:/Apps/Pode/server.ps1`, then Pode will monitor the `C:/Apps/Pode` directory and sub-directories. When a change is detected, Pode will wait a couple of seconds before triggering the restart; this is so multiple rapid changes don't trigger multiple restarts.
+
+Changes being monitored are:
+
+* Updates
+* Creation
+* Deletion
+
+Please note that if you change the main server script itself, those changes will not be picked up. It's best to import/dot-source other modules/scripts into your `Server` scriptblock, as the internal restart re-executes this scriptblock. If you do make changes to the main server script, you'll need to terminate and restart the server.
+
+#### Access Rules
+
+Access rules in Pode allow you to specify allow/deny rules for IP addresses and subnet masks. This means you can deny certain IPs from accessing the server, and vice-versa by allowing them. You use `access` within your `Server`, specifying the permission, type and IP/subnet:
+
+```powershell
+Server {
+    # allow access from localhost
+    access allow ip 127.0.0.1
+
+    # allow access from multiple IPs
+    access allow ip @('192.168.1.1', '192.168.1.2')
+
+    # deny access from a subnet
+    access deny ip '10.10.0.0/24'
+
+    # deny access from everything
+    access deny ip all
+}
+```
+
+If an IP hits your server that you've denied access, then a `403` response is returned and the connection immediately closed. For SMTP/TCP servers the connection is just closed with no response.
+
+## Pode Files
 Using Pode to write dynamic HTML files are mostly just an HTML file - in fact, you can write pure HTML and still be able to use it. The difference is that you're able to embed PowerShell logic into the file, which allows you to dynamically generate HTML.
 
 To use Pode files, you will need to place them within the `/views/` folder. Then you'll need to set the View Engine to be Pode; once set, you can just write view responses as per normal:
@@ -658,4 +723,6 @@ Pode comes with a few helper functions - mostly for writing responses and readin
 * `status`
 * `include`
 * `lock`,
-* `state`
+* `state`,
+* `listen`,
+* `access`

appveyor.yml

@@ -0,0 +1,20 @@
+version: 0.14.{build}
+image: Visual Studio 2017
+
+branches:
+  except:
+    - gh-pages
+
+skip_tags: true
+
+configuration: Release
+
+install:
+  - cinst -y pester --version 4.1.0
+  - cinst -y psake --version 4.7.0
+  - ps: Import-Module "$($pwd)\build\appveyor.psm1"
+
+build: off
+
+test_script:
+  - ps: Invoke-AppVeyorTest

build/appveyor.psm1

@@ -0,0 +1,42 @@
+function Invoke-AppVeyorTest
+{
+    # run the tests
+    $file = "$($pwd)\TestsResults.xml"
+    $status = Invoke-Pester "$($pwd)\tests\unit" -OutputFormat NUnitXml -OutputFile $file -PassThru
+
+    # upload the results
+    Update-AppVeyorTestResults -ResultFile $file
+
+    # fail build if any tests failed
+    Test-AppVeyorTestResults -ResultStatus $status -ResultFile $file
+}
+
+function Update-AppVeyorTestResults
+{
+    param (
+        $ResultFile
+    )
+
+    Write-Host "Uploading results for Job ID '$($env:APPVEYOR_JOB_ID)'" -ForegroundColor Cyan
+    (New-Object 'System.Net.WebClient').UploadFile("https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", $ResultFile)
+    Write-Host 'Results uploaded' -ForegroundColor Green
+}
+
+function Test-AppVeyorTestResults
+{
+    param (
+        $ResultStatus,
+        $ResultFile
+    )
+
+    Write-Host 'Checking if any of the tests have failed'
+
+    if ($ResultStatus.FailedCount -gt 0) {
+        Write-Host 'Some of the tests have failed' -ForegroundColor Red
+        Push-AppveyorArtifact $ResultFile
+        throw "$($ResultStatus.FailedCount) tests failed."
+    }
+    else {
+          Write-Host 'No tests failed!' -ForegroundColor Green
+    }
+}

examples/file-monitoring.ps1

@@ -0,0 +1,23 @@
+if ((Get-Module -Name Pode | Measure-Object).Count -ne 0)
+{
+    Remove-Module -Name Pode
+}
+
+$path = Split-Path -Parent -Path (Split-Path -Parent -Path $MyInvocation.MyCommand.Path)
+Import-Module "$($path)/src/Pode.psm1" -ErrorAction Stop
+
+# or just:
+# Import-Module Pode
+
+# create a server listening on port 8085, set to monitor file changes and restart the server
+Server -Port 8085 {
+
+    engine pode
+
+    # GET request for web page on "localhost:8085/"
+    route 'get' '/' {
+        param($session)
+        view 'simple' -Data @{ 'numbers' = @(1, 2, 3); }
+    }
+
+} -FileMonitor

examples/mail-server.ps1

@@ -12,6 +12,9 @@ Import-Module "$($path)/src/Pode.psm1" -ErrorAction Stop
 # create a server, and start listening on port 25
 Server -Smtp {
 
+    # allow the local ip
+    access allow ip 127.0.0.1
+
     # setup an smtp handler
     handler 'smtp' {
         param($session)

examples/shared-state.ps1

@@ -49,4 +49,4 @@ Server -Port 8085 {
         }
     }
 
-}
+} -FileMonitor

examples/tcp-server.ps1

@@ -12,6 +12,9 @@ Import-Module "$($path)/src/Pode.psm1" -ErrorAction Stop
 # create a server, and start listening on port 8999
 Server -Tcp -Port 8999 {
 
+    # allow the local ip
+    access allow ip 127.0.0.1
+
     # setup a tcp handler
     handler 'tcp' {
         param($session)

examples/web-pages-docker.ps1

@@ -6,8 +6,12 @@ if ((Get-Module -Name Pode | Measure-Object).Count -ne 0)
 Import-Module Pode
 
 # create a server, and start listening on port 8085
-Server -Port 8085 {
+Server {
 
+    # listen on *:8085
+    listen *:8085 http
+
+    # set view engine to pode renderer
     engine pode
 
     # GET request for web page on "localhost:8085/"
@@ -22,4 +26,10 @@ Server -Port 8085 {
         status 500
     }
 
-}
+    # PUT update a file to trigger monitor
+    route 'put' '/file' {
+        param($session)
+        'Hello, world!' | Out-File -FilePath "$($PodeSession.ServerRoot)/file.txt" -Append -Force
+    }
+
+} -FileMonitor

examples/web-pages.ps1

@@ -1,9 +1,3 @@
-param (
-    [Parameter()]
-    [string]
-    $IP
-)
-
 if ((Get-Module -Name Pode | Measure-Object).Count -ne 0)
 {
     Remove-Module -Name Pode
@@ -16,8 +10,24 @@ Import-Module "$($path)/src/Pode.psm1" -ErrorAction Stop
 # Import-Module Pode
 
 # create a server, and start listening on port 8085
-Server -IP $IP -Port 8085 {
+Server {
+
+    # listen on localhost:8085
+    listen 127.0.0.1:8085 http
+
+    # allow the local ip and some other ips
+    access allow ip 127.0.0.1
+    access allow ip @('192.169.0.1', '192.168.0.2')
 
+    # deny an ip
+    access deny ip 10.10.10.10
+    access deny ip '10.10.0.0/24'
+    access deny ip all
+
+    # log requests to the terminal
+    logger terminal
+
+    # set view engine to pode renderer
     engine pode
 
     # GET request for web page on "localhost:8085/"
@@ -44,4 +54,5 @@ Server -IP $IP -Port 8085 {
         json @{ 'userId' = $session.Parameters['userId'] }
     }
 
-}
+} -FileMonitor
+

packers/choco/pode.nuspec

@@ -23,6 +23,8 @@ Pode is a Cross-Platform PowerShell framework that allows you to host REST APIs,
 * Setup async timers as one off tasks, or for housekeeping services
 * Supports logging to CLI, Files, and custom loggers to other services like LogStash, etc.
 * Cross-state runspace variable access for timers, routes and loggers
+* Optional file monitoring to trigger internal server restart on file changes
+* Ability to allow/deny requests from certain IP addresses and subnets
 
     </description>
     <projectUrl>https://github.com/Badgerati/Pode</projectUrl>

src/Pode.psd1

@@ -56,7 +56,9 @@
         'Status',
         'Include',
         'Lock',
-        'State'
+        'State',
+        'Listen',
+        'Access'
     )
 
     # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.

src/Tools/ContentTypes.ps1

@@ -6,6 +6,10 @@ function Get-PodeContentType
         $Extension
     )
 
+    if ($Extension -eq $null) {
+        $Extension = '.'
+    }
+
     if (!$Extension.StartsWith('.')) {
         $Extension = ".$($Extension)"
     }