Merge pull request #571 from Badgerati/develop

v1.8.0

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [Badgerati]

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug Report
-about: Create a report to help us improve
+about: Create a bug report to help us improve
 title: ''
 labels: 'bug :bug:'
 assignees: ''
@@ -25,8 +25,10 @@ If applicable, add screenshots to help explain your problem.
 
 ### Platform
  - OS: [e.g. iOS, Windows]
- - Browser [e.g. Chrome, Safari]
- - Version [e.g. PS6.2.1]
+ - Browser: [e.g. Chrome, Safari]
+ - Versions:
+   - Pode: [e.g. Pode v1.7.3]
+   - PowerShell: [e.g. PS6.2.1]
 
 ### Additional Context
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/packaging-request.md

@@ -0,0 +1,11 @@
+---
+name: Packaging Request
+about: Suggest an improvement for the packaging of Pode, such as a new version of software.
+title: ''
+labels: 'packaging :package:'
+assignees: ''
+
+---
+
+### Describe the Change
+A clear and concise description of what you want to happen.

.github/workflows/ci-coverage.yml

@@ -19,11 +19,15 @@ jobs:
 
     - name: Install Invoke-Build
       shell: pwsh
-      run: Install-Module -Name InvokeBuild -RequiredVersion '5.5.1' -Force
+      run: |
+        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+        Install-Module -Name InvokeBuild -RequiredVersion '5.5.1' -Force
 
     - name: Run Pester Tests
       shell: pwsh
       env:
         PODE_COVERALLS_TOKEN: ${{ secrets.PODE_COVERALLS_TOKEN }}
         PODE_RUN_CODE_COVERAGE: true
-      run: Invoke-Build Test
+      run: |
+        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+        Invoke-Build Test

.github/workflows/ci.yml

@@ -24,8 +24,12 @@ jobs:
 
     - name: Install Invoke-Build
       shell: pwsh
-      run: Install-Module -Name InvokeBuild -RequiredVersion '5.5.1' -Force
+      run: |
+        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+        Install-Module -Name InvokeBuild -RequiredVersion '5.5.1' -Force
 
     - name: Run Pester Tests
       shell: pwsh
-      run: Invoke-Build Test
+      run: |
+        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+        Invoke-Build Test

.gitignore

@@ -5,6 +5,7 @@
 pode_modules/
 ps_modules/
 docs/[Ff]unctions/
+examples/state.json
 
 
 # Code Runner

Dockerfile

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

README.md

@@ -3,8 +3,6 @@
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/Badgerati/Pode/master/LICENSE.txt)
 [![Documentation](https://img.shields.io/github/v/release/badgerati/pode?label=docs)](https://badgerati.github.io/Pode)
 [![GitHub Actions](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fbadgerati%2Fpode%2Fbadge&style=flat&label=GitHub)](https://actions-badge.atrox.dev/badgerati/pode/goto)
-[![AppVeyor](https://img.shields.io/appveyor/ci/Badgerati/Pode/develop.svg?label=AppVeyor)](https://ci.appveyor.com/project/Badgerati/pode/branch/develop)
-[![Travis CI](https://img.shields.io/travis/Badgerati/Pode/develop.svg?label=Travis%20CI)](https://travis-ci.org/Badgerati/Pode)
 [![Code Coverage](https://coveralls.io/repos/github/Badgerati/Pode/badge.svg?branch=develop)](https://coveralls.io/github/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)
 

arm32.dockerfile

@@ -1,4 +1,4 @@
-FROM badgerati/ps-core:7.0.0-arm32
+FROM badgerati/ps-core:7.0.1-arm32
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
 COPY ./src/ /usr/local/share/powershell/Modules/Pode

docs/Hosting/Heroku.md

@@ -0,0 +1,88 @@
+# Heroku
+
+Using Pode's docker image, you can host your Pode server in Heroku.
+
+Hosting your server in Heroku works in a similar fashion to IIS, in that Pode can detect when you're using Heroku and set the Address/Port appropriately. Furthermore, Heroku can deal with HTTPS for you, so your Pode server only needs to bind onto HTTP within the container.
+
+## Requirements
+
+To get started you'll need the following software installed:
+
+* Git
+* Docker
+* Heroku CLI
+
+You'll also need an account with [Heroku](https://heroku.com/).
+
+## Server
+
+Your server will need a Dockerfile, such as the following:
+
+```dockerfile
+FROM badgerati/pode:latest
+COPY . /usr/src/app/
+EXPOSE $PORT
+CMD [ "pwsh", "-c", "cd /usr/src/app; ./server.ps1" ]
+```
+
+While Pode can detect that your server is running in Heroku, and can set your server's endpoints appropriately, the Dockerfile will need to use the `$PORT` variable that Heroku set.
+
+You can set this when testing locally as follows (assuming your server is listening on port 5000 locally):
+
+```powershell
+docker run -p 5000:5000 -e PORT=5000 <image-name>
+```
+
+The server script itself could look as follows:
+
+```powershell
+Start-PodeServer {
+    Add-PodeEndpoint -Address 127.0.0.1 -Port 5000 -Protocol Http
+
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{ Response = 'Hello, world!' }
+    }
+}
+```
+
+Here we have an endpoint on localhost and port 5000; but when in Heroku Pode will automatically change the address/port for you.
+
+## Build and Push
+
+First, login to Heroku and then its Container Registry:
+
+```powershell
+heroku login
+heroku container:login
+```
+
+Next, create an app - note that you'll need to get the app-name that is returned:
+
+```powershell
+heroku create
+$appName = '<app-name-from-above>'
+```
+
+Then, push and release your server to the created app:
+
+```powershell
+heroku container:push web --app $appName
+heroku container:release web --app $appName
+```
+
+Finally, you can open your server as follows:
+
+```powershell
+heroku open --app $appName
+```
+
+After this, you can view the logs of the server using:
+
+```powershell
+heroku logs --tail --app $appName
+```
+
+## Useful Links
+
+* [Building Docker Images with heroku.yml \| Heroku Dev Center](https://devcenter.heroku.com/articles/build-docker-images-heroku-yml)
+* [Container Registry & Runtime (Docker Deploys) \| Heroku Dev Center](https://devcenter.heroku.com/articles/container-registry-and-runtime)

docs/Tutorials/Logging/Overview.md

@@ -5,7 +5,7 @@ There are two aspects to logging in Pode: Methods and Types.
 * Methods define how log items should be recorded, such as to a file or terminal.
 * Types define how items to log are transformed, and what should be supplied to the Method.
 
-For example when you supply an Exception to  [`Write-PodeErrorLog`](../../../Functions/Logging/Write-PodeErrorLog), this Exception is first supplied to Pode's inbuilt Error type. This type transforms any Exception (or Error Record) into a string which can then be supplied to the File logging method.
+For example when you supply an Exception to [`Write-PodeErrorLog`](../../../Functions/Logging/Write-PodeErrorLog), this Exception is first supplied to Pode's inbuilt Error logging type. This type transforms any Exception (or Error Record) into a string which can then be supplied to the File logging method.
 
 In Pode you can use File, Terminal or a Custom method. As well as Request, Error, or a Custom type.
 
@@ -53,7 +53,7 @@ Instead of masking the whole value that matches, there is support for two RegEx
 
 Specifying either of these groups in your pattern will keep the original value in place rather than masking it.
 
-For example, expanding on the above example, to keep the `Password=` text you could use the following:
+For example, expanding on the above, to keep the `Password=` text you could use the following:
 
 ```powershell
 @{
@@ -93,3 +93,19 @@ To specify a custom mask, you can do this in the configuration file:
     }
 }
 ```
+
+## Batches
+
+By default all log items are recorded one-by-one, but this can obviously become very slow if a lot of log items are being processed.
+
+To help speed this up, you can specify a batch size on your logging method:
+
+```powershell
+New-PodeLoggingMethod -Terminal -Batch 10 | Enable-PodeRequestLogging
+```
+
+Instead of writing logs one-by-one, the above will keep transformed log items in an array. Once the array matches the batch size of 10, all items will be sent to the method at once.
+
+This means that the method's scriptblock will receive an array of items, rather than a single item.
+
+You can also sent a `-BatchTimeout` value, in seconds, so that if your batch size it 10 but only 5 log items are added, then after the timeout value the logs items will be sent to your method.

docs/Tutorials/Misc/CronExpressions.md

@@ -19,7 +19,7 @@ For example, if you wanted to run a schedule that triggers every midnight on a T
 Whereas if you wanted a schedule to trigger on the 15th of each month, at 1am:
 
 ```plain
-0 1 15 * * *
+0 1 15 * *
 ```
 
 ## Predefined
@@ -33,7 +33,7 @@ The following table outlines some of the predefined cron expressions supported b
 | @daily | `0 0 * * *` |
 | @weekly | `0 0 * * 0` |
 | @monthly | `0 0 1 * *` |
-| @quarterly | `0 0 1 1,4,8,7,10` |
+| @quarterly | `0 0 1 1,4,8,7,10 *` |
 | @yearly | `0 0 1 1 *` |
 | @annually | `0 0 1 1 *` |
 | @twice-hourly | `0,30 * * * *` |

docs/Tutorials/Schedules.md

@@ -1,6 +1,6 @@
 # Schedules
 
-A Schedule in Pode is a long-running async task, and unlike timers, when they trigger they are run in their own separate runspace - so they don't affect each other if they take a while to process. By default up to a maximum of 10 schedules can run concurrently, this can be changed by using the [`Set-PodeScheduleConcurrency`](../../Functions/Core/Set-PodeScheduleConcurrency) function.
+A Schedule in Pode is a long-running async task, and unlike timers, when they trigger they are run in their own separate runspace - so they don't affect each other if they take a while to process. By default up to a maximum of 10 schedules can run concurrently, but this can be changed by using the [`Set-PodeScheduleConcurrency`](../../Functions/Core/Set-PodeScheduleConcurrency) function.
 
 Schedule triggers are defined using [`cron expressions`](../Misc/CronExpressions), basic syntax is supported as well as some predefined expressions. Schedules can start immediately, have a delayed start time, and also have a defined end time.
 
@@ -44,6 +44,9 @@ Add-PodeSchedule -Name 'date' -Cron '@minutely' -ArgumentList @{ Name = 'Rick';
 }
 ```
 
+!!! important
+    In schedules, your scriptblock parameter names must be exact - including case-sensitivity. This is because the arguments are splatted into a runspace. If you pass in an argument called "Names", the param-block must have `$Names` exactly. Furthermore, the event parameter *must* be called `$Event`.
+
 ## 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.
@@ -85,7 +88,57 @@ For example, to create a schedule from a file that will output `Hello, world` ev
 }
 ```
 
-* Timer
+* Schedule
 ```powershell
 Add-PodeSchedule -Name 'from-file' -Cron '@minutely' -FilePath './Schedules/File.ps1'
 ```
+
+## Getting Schedules
+
+The [`Get-PodeSchedule`](../../Functions/Core/Get-PodeSchedule) helper function will allow you to retrieve a list of schedules configured within Pode. You can use it to retrieve all of the schedules, or supply filters to retrieve specific ones.
+
+To retrieve all of the schedules, you can call the function will no parameters. To filter, here are some examples:
+
+```powershell
+# one schedule by name
+Get-PodeSchedule -Name Name1
+
+# multiple schedules by name
+Get-PodeSchedule -Name Name1, Name2
+```
+
+## Next Trigger Time
+
+When you retrieve a Schedule using [`Get-PodeSchedule`](../../Functions/Core/Get-PodeSchedule), each Schedule object will already have its next trigger time as `NextTriggerTime`. However, if you want to get a trigger time further ino the future than this, then you can use the [`Get-PodeScheduleNextTrigger`](../../Functions/Core/Get-PodeScheduleNextTrigger) function.
+
+This function takes the Name of a Schedule, as well as a custom DateTime and will return the next trigger time after that DateTime. If no DateTime is supplied, then the Schedule's StartTime is used (or the current time if no StartTime).
+
+```powershell
+# just get the next time
+$time = Get-PodeScheduleNextTrigger -Name Schedule1
+
+# get the next time after a date
+$time = Get-PodeScheduleTriggerTime -Name Schedule1 -DateTime [datetime]::new(2020, 3, 20)
+```
+
+## Schedule Object
+
+!!! warning
+    Be careful if you choose to edit these objects, as they will affect the server.
+
+The following is the structure of the Schedule object internally, as well as the object that is returned from [`Get-PodeSchedule`](../../Functions/Core/Get-PodeSchedule):
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| Name | string | The name of the Schedule |
+| StartTime | datetime | The delayed start time of the Schedule |
+| EndTime | datetime | The end time of the Schedule |
+| Crons | hashtable[] | The cron expressions of the Schedule, but parsed into an internal format |
+| CronsRaw | string[] | The raw cron expressions that were supplied |
+| Limit | int | The number of times the Schedule should run - 0 if running infinitely |
+| Count | int | The number of times the Schedule has run |
+| NextTriggerTime | datetime | The datetime the Schedule will next be triggered |
+| Script | scriptblock | The scriptblock of the Schedule |
+| Arguments | hashtable | The arguments supplied from ArgumentList |
+| OnStart | bool | Should the Schedule run once when the server is starting, or once the server has fully loaded |
+| Completed | bool | Has the Schedule completed all of its runs |