Merge ec8b788 into 7c2e22b

.github/CONTRIBUTING.md

@@ -50,9 +50,9 @@ You can raise new issues, for bugs, enhancements, feature ideas; or you can sele
 
 ### Branch Names
 
-Branches should be named after the issue you are working on, such as `Issue-123`.
+Branches should be named after the issue you are working on, such as `Issue-123`. If you're working on an issue that hasn't been raised (such as a typo, tests, docs, etc), branch names should be descriptive.
 
-If you're working on an issue that hasn't been raised (such as a typo, tests, docs, etc), branch names should be descriptive.
+When branching, please create your branches from `develop` - unless another branch is far more appropriate.
 
 ### Pull Requests
 
@@ -84,7 +84,9 @@ Invoke-Build Test
 Where possible, please add new, or update, Pode's documentation. This documentation is in the form of:
 
 * The main `/docs` directory. These are markdown files that are built using mkdocs. The `/docs/Functions` directory is excluded as these are compiled using PlatyPS.
-* All functions within the `/src/Public` directory need to have documentation.
+* All functions within the `/src/Public` directory need to have help comment documentation added/updated.
+  * Synopsis and Parameter descriptions should be descriptive.
+  * Examples should only contain a single line of code to use the function. (This is due a limitation in PlatyPS where it currently doesn't support multi-line examples).
 
 To see the docs you'll need to have the [`Invoke-Build`](https://github.com/nightroman/Invoke-Build) installed, then you can run the following:
 
@@ -101,7 +103,7 @@ In general, observe the coding style used within the file/project and mimic that
 * Bracers (`{}`) on the function header should be on a new line.
 * Bracers  (`{}`) should be on the same line of other calls, such as `foreach`, `if`, etc.
 * **Never** use inline parameters on functions. Such as: `function New-Function($param1, $param2)`
-  * Always use the param block within the function.
+  * Always use the `param` block within the function.
   * Ensure public functions always declare `[CmdletBinding()]` attribute.
   * Ensure parameter names, types, and attributes are declared on new lines - not all on one line.
 * **Never** use the following commandlets ([see below](#powershell-commandlets) for details):
@@ -123,8 +125,10 @@ Comments are always useful for new people reading code. Where possible, try to p
 
 On public functions, new and existing, these should always have Help comments:
 
-* Help comments should be placed above the function header.
-* Help comments should be updated if a new parameter is added to/removed from the function.
+* They should be placed above the function header.
+* They should be updated if a new parameter is added to/removed from the function.
+* Parameter descriptions should be descriptive.
+* Examples should only contain a single line of code to use the function. (This is due a limitation in PlatyPS where it currently doesn't support multi-line examples).
 
 ### PowerShell Commandlets
 

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, ubuntu-16.04, windows-latest, windows-2016, macOS-latest]
+        os: [ubuntu-latest, ubuntu-16.04, windows-latest, windows-2016]
 
     steps:
     - uses: actions/checkout@v1

README.md

@@ -38,7 +38,8 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Docker support, including images for ARM/Raspberry Pi
 * Azure Functions and AWS Lambda support
 * Listen on a single or multiple IP address/hostnames
-* Support for HTTP, HTTPS, TCP and SMTP (Experimental cross-platform support for HTTPS)
+* Cross-platform support for HTTP, HTTPS, TCP and SMTP
+* Cross-platform support for server-to-client WebSockets, including secure WebSockets
 * Host REST APIs, Web Pages, and Static Content (with caching)
 * Support for custom error pages
 * Multi-thread support for incoming requests
@@ -73,6 +74,8 @@ docker pull badgerati/pode
 
 ## Contributing
 
+> The full contributing guide can be [found here](https://github.com/Badgerati/Pode/blob/develop/.github/CONTRIBUTING.md)
+
 Pull Requests, Bug Reports and Feature Requests are welcome! Feel free to help out with Issues and Projects!
 
 To run the unit tests, run the following command from the root of the repository (this will auto-install Pester for you):

docs/Tutorials/Authentication/Overview.md

@@ -61,9 +61,29 @@ Start-PodeServer {
 }
 ```
 
-The `-Name` of the authentication method must be unique. The `-Type` comes from  [`New-PodeAuthType`](../../../Functions/Authentication/New-PodeAuthType), and can also be pied in.
+The `-Name` of the authentication method must be unique. The `-Type` comes from  [`New-PodeAuthType`](../../../Functions/Authentication/New-PodeAuthType), and can also be piped in.
 
-The `-ScriptBlock` is used to validate a user, checking if they exist and the password is correct (or checking if they exist in some data store). If the ScriptBlock succeeds, then a `User` needs to be returned from the script as `@{ User = $user }`. If `$null`, or a null user is returned then the script is assumed to have failed - meaning the user will have failed authentication.
+The `-ScriptBlock` is used to validate a user, checking if they exist and the password is correct (or checking if they exist in some data store). If the ScriptBlock succeeds, then a `User` needs to be returned from the script as `@{ User = $user }`. If `$null`, or a null user, is returned then the script is assumed to have failed - meaning the user will have failed authentication, and a 401 response is returned.
+
+#### Custom Message and Status
+
+When authenticating a user in Pode, any failures will return a 401 response with a generic message. You can inform Pode to return a custom message/status from [`Add-PodeAuth`](../../../Functions/Authentication/Add-PodeAuth) by returning a relevant hashtable.
+
+You can return a custom status code as follows:
+
+```powershell
+New-PodeAuthType -Basic | Add-PodeAuth -Name 'Login' -ScriptBlock {
+    return @{ Code = 403 }
+}
+```
+
+or a custom message as follows, which can be used with a custom status code or on its own:
+
+```powershell
+New-PodeAuthType -Basic | Add-PodeAuth -Name 'Login' -ScriptBlock {
+    return @{ Message = 'Custom authentication failed message' }
+}
+```
 
 ### Get-PodeAuthMiddleware
 

docs/Tutorials/Basics.md

@@ -21,3 +21,4 @@ The above server will start a basic HTTP listener on port 8080. To start the ser
 
 !!! tip
     Once Pode has started, you can exit out at any time using `Ctrl+C`. You can also restart the server by using `Ctrl+R`.
+    On Unix, you can also use `Shuft+C` and `Shift+R`

docs/Tutorials/ExternalEndpoints.md

@@ -0,0 +1,61 @@
+# External Endpoints
+
+At most times you'll possibly be accessing your Pode server locally. However, you can access your server externally if you setup the endpoints appropriately using the [`Add-PodeEndpoint`](../../Functions/Core/Add-PodeEndpoint) function. These will work on a your VMs, or in a Container.
+
+!!! tip
+    In each case, ensure any Firewalls or Network Security Groups are configured to allow access to the port.
+
+## All Addresses
+
+The default and common approach is to set your Pode server to listen on all IP addresses:
+
+```powershell
+Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
+```
+
+With this set, you can access your endpoint using the server's Public, Private IP address or VM name - plus the port number:
+
+```powershell
+Invoke-RestMethod -Uri 'http://<ip-address|vm-name>:8080'
+```
+
+## IP Address
+
+The other way to expose your server externally is to create an endpoint using the server's Private/Public IP address. For example, assuming the the server's IP is `10.10.1.5`:
+
+```powershell
+Add-PodeEndpoint -Address 10.10.1.5 -Port 8080 -Protocol Http
+```
+
+With this set, you can access your endpoint using the server's Private IP address or VM name only - plus the port number:
+
+```powershell
+Invoke-RestMethod -Uri 'http://10.10.1.5:8080'
+```
+
+## Hostnames
+
+The final way to expose your server externally is to allow only specific hostnames bound to the server's Private/Public IP address - something like SNI in IIS.
+
+To do this, let's say you want to allow only `one.pode.com` and `two.pode.com` on a server with IP `10.10.1.5`. The first thing to do is add the hostnames to the server's hosts file (or dns):
+
+```plain
+10.10.1.5   one.pode.com
+10.10.1.5   two.pode.com
+```
+
+Then, create the endpoints within your server:
+
+```powershell
+Add-PodeEndpoint -Address 'one.pode.com' -Port 8080 -Protocol Http
+Add-PodeEndpoint -Address 'two.pode.com' -Port 8080 -Protocol Http
+```
+
+Next, make sure to add the hostnames into your hosts file, or into DNS.
+
+With these set, you can access your endpoint using only the `one.pode.com` and `two.pode.com` hostnames - plus the port number:
+
+```powershell
+Invoke-RestMethod -Uri 'http://one.pode.com:8080'
+Invoke-RestMethod -Uri 'http://two.pode.com:8080'
+```

docs/Tutorials/Middleware/Types/BodyParsing.md

@@ -0,0 +1,50 @@
+# Body Parsing
+
+Pode has inbuilt body/payload parsing on Requests, which by default can parse the following content types:
+
+* `*/json`
+* `*/xml`
+* `*/csv`
+* `*/x-www-form-urlencoded`
+* `multipart/form-data`
+
+This is useful however, there can be times when you might want to use a different JSON parsing library - or parse a completely different content type altogether! This is possible using the [`Add-PodeBodyParser`](../../../../Functions/Middleware/Add-PodeBodyParser) function.
+
+## Adding a Parser
+
+You can use the [`Add-PodeBodyParser`](../../../../Functions/Middleware/Add-PodeBodyParser) function to define a scriptblock that can parse the Request body for a specific content type. Any set parsers have a higher priority than the inbuilt ones, meaning if you define a parser for `application/json` then this will be used instead of the inbuilt one.
+
+The scriptblock you supply will be supplied a single argument, which will be the Body of the Request.
+
+For example, to set your own JSON parser that will simply return the body unmodified you could do the following:
+
+```powershell
+Add-PodeBodyParser -ContentType 'application/json' -ScriptBlock {
+    param($body)
+    return $body
+}
+```
+
+This can then be accessed the normal way within a Route from the `.Data` object on the supplied event:
+
+```powershell
+Add-PodeRoute -Method Post -Path '/' -ScriptBlock {
+    param($e)
+
+    # if using the above parser, .Data here will just be a plain string
+    Write-PodeTextResponse -Value $e.Data
+}
+```
+
+This is great if you want to be able to parse other content types like YAML, HCL, or many others!
+
+## Removing a Parser
+
+To remove a defined parser you can use the [`Remove-PodeBodyParser`](../../../../Functions/Middleware/Remove-PodeBodyParser) function:
+
+```powershell
+Remove-PodeBodyParser -ContentType 'application/json'
+```
+
+!!! note
+    This will only remove defined custom parsers, and will not affect the inbuilt parsers.

docs/Tutorials/Restarting/Overview.md

@@ -3,6 +3,7 @@
 There are 3 ways to restart a running Pode server:
 
 1. **Ctrl+R**: If you press `Ctrl+R` on a running server, it will trigger a restart to take place.
+    1a. On Unix you can use `Shift+R`.
 2. [**File Monitoring**](../Types/FileMonitoring): This will watch for file changes, and if enabled will trigger the server to restart.
 3. [**Auto-Restarting**](../Types/AutoRestarting): Defined within the `server.psd1` configuration file, you can set schedules for the server to automatically restart.
 

docs/Tutorials/Schedules.md

@@ -38,6 +38,18 @@ Start-PodeServer {
 }
 ```
 
+### Arguments
+
+You can supply custom arguments to your schedules by using the `-ArgumentList` parameter. Unlike other features, for schedules the `-ArgumentList` is a hashtable; this is done because parameters to the `-ScriptBlock` are splatted in, and the parameter names are literal.
+
+For example, the first parameter to a schedule is always `$Event` - this contains the `.Lockable` object. Other parameters come from any Key/Values contained with the optional `-ArgumentList`:
+
+```powershell
+Add-PodeSchedule -Name 'date' -Cron '@minutely' -ArgumentList @{ Name = 'Rick'; Environment = 'Multiverse' } -ScriptBlock {
+    param($Event, $Name, $Environment)
+}
+```
+
 ## Delayed Start
 
 The `-StartTime <datetime>` parameter will cause the Schedule to only be triggered after the date/time defined. For example, if you have a schedule set to trigger at 00:05 every Tuesday, and you pass `-StartTime [DateTime]::Now.AddMonths(2)`, then the schedule will only start trigger on Tuesdays in 2 months time.

docs/Tutorials/Views/Pode.md

@@ -94,7 +94,7 @@ This next quick example allows you to include content from another view:
 ```html
 <!-- /views/index.pode -->
 <html>
-    $(Use-PodePartialView -Path 'shared/head')
+    $(Use-PodePartialView -Path 'shared/head' -data @{ 'Title' = 'Include Example'})
 
     <body>
         <span>$([DateTime]::Now.ToString('yyyy-MM-dd HH:mm:ss');)</span>
@@ -103,7 +103,7 @@ This next quick example allows you to include content from another view:
 
 <!-- /views/shared/head.pode -->
 <head>
-    <title>Include Example</title>
+    <title>$($data.Title)</title>
 </head>
 ```