Merge pull request #734 from Badgerati/develop

v2.2.2

.github/CONTRIBUTING.md

@@ -111,18 +111,52 @@ Invoke-Build Docs
 
 In general, observe the coding style used within the file/project and mimic that as best as you can. Some standards that are typical are:
 
-* Bracers (`{}`) on the function header should be on a new line.
+* Bracers (`{}`) on the function header should be on a new line, such as:
+```powershell
+function Add-Something
+{
+    # logic
+}
+```
+
 * 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)`
+```powershell
+foreach ($item in $items) {
+    # logic
+}
+```
+
+* **Never** use inline parameters on functions, such as: `function New-Function($param1, $param2)`
   * 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.
+```powershell
+function Add-Something
+{
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [string]
+        $Item
+    )
+}
+```
+
 * **Never** use the following commandlets ([see below](#powershell-commandlets) for details):
   * `Foreach-Object`
   * `Where-Object`
   * `Select-Object`
   * `Measure-Object`
 
+* Avoid using `-not`, and use `!` instead:
+```powershell
+if (!(Test-Path $Path)) {
+    # logic
+}
+```
+
+* Don't end lines with semi-colons (`;`).
+
 ### Comments
 
 #### General
@@ -147,7 +181,7 @@ For performance reasons, the following PowerShell commandlets should be avoided
 
 #### Foreach-Object
 
-Instead of using the `Foreach-Object` commandlet, please use the `foreach` keyword. This is orders of magnitude more performant than `Foreach-Object`.
+Instead of using the `Foreach-Object` commandlet, please use the `foreach` keyword. This is orders of magnitude faster than `Foreach-Object`.
 
 ```powershell
 # instead of this
@@ -163,7 +197,7 @@ foreach ($i in @(1, 2, 3)) {
 
 #### Where-Object
 
-Instead of using the `Where-Object` commandlet, please use the `foreach` adn `if` keywords. This is orders of magnitude more performant than `Where-Object`.
+Instead of using the `Where-Object` commandlet, please use the `foreach` and `if` keywords. These are orders of magnitude faster than `Where-Object`.
 
 ```powershell
 # instead of this
@@ -179,7 +213,7 @@ $array = @(foreach ($i in @(1, 2, 3, 1, 3, 4)) {
 
 #### Select-Object
 
-Instead of using the `Select-Object` commandlet to expand a property, or to select the first/last elements, please use the following. These is orders of magnitude more performant than `Measure-Object`.
+Instead of using the `Select-Object` commandlet to expand a property, or to select the first/last elements, please use the following. These are orders of magnitude faster than `Measure-Object`.
 
 ```powershell
 # instead of these
@@ -195,7 +229,7 @@ $services | Select-Object -Last 1
 
 #### Measure-Object
 
-Instead of using the `Measure-Object` commandlet, please use either the `.Length` or `.Count` properties. These is orders of magnitude more performant than `Measure-Object`.
+Instead of using the `Measure-Object` commandlet, please use either the `.Length` or `.Count` properties. These are orders of magnitude faster than `Measure-Object`.
 
 ```powershell
 # instead of these

Dockerfile

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

alpine.dockerfile

@@ -0,0 +1,4 @@
+FROM mcr.microsoft.com/powershell:7.1.3-alpine-3.12-20210316
+LABEL maintainer="Matthew Kelly (Badgerati)"
+RUN mkdir -p /usr/local/share/powershell/Modules/Pode
+COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

arm32.dockerfile

@@ -1,4 +1,4 @@
-FROM badgerati/ps-core:7.1.1-arm32
+FROM mcr.microsoft.com/powershell:7.1.3-arm32v7-ubuntu-18.04-20210316
 LABEL maintainer="Matthew Kelly (Badgerati)"
 RUN mkdir -p /usr/local/share/powershell/Modules/Pode
 COPY ./pkg/ /usr/local/share/powershell/Modules/Pode

docs/Getting-Started/Installation.md

@@ -41,7 +41,7 @@ Install-Module -Name Pode
 [![Docker](https://img.shields.io/docker/stars/badgerati/pode.svg?label=Stars)](https://hub.docker.com/r/badgerati/pode/)
 [![Docker](https://img.shields.io/docker/pulls/badgerati/pode.svg?label=Pulls)](https://hub.docker.com/r/badgerati/pode/)
 
-Pode can run on *nix environments, therefore it only makes sense for there to be Docker images for you to use! The images use PowerShell v7.1.1 on either an Ubuntu Bionic image (default), or an ARM32 image (for Raspberry Pis).
+Pode can run on *nix environments, therefore it only makes sense for there to be Docker images for you to use! The images use PowerShell v7.1.3 on either an Ubuntu Bionic image (default), an Alpine image, or an ARM32 image (for Raspberry Pis).
 
 * To pull down the latest Pode image you can do:
 
@@ -50,7 +50,17 @@ Pode can run on *nix environments, therefore it only makes sense for there to be
 docker pull badgerati/pode:latest
 
 # or the following for a specific version:
-docker pull badgerati/pode:2.1.0
+docker pull badgerati/pode:2.2.2
+```
+
+* To pull down the Alpine Pode image you can do:
+
+```powershell
+# for latest
+docker pull badgerati/pode:latest-alpine
+
+# or the following for a specific version:
+docker pull badgerati/pode:2.2.2-alpine
 ```
 
 * To pull down the ARM32 Pode image you can do:
@@ -60,7 +70,7 @@ docker pull badgerati/pode:2.1.0
 docker pull badgerati/pode:latest-arm32
 
 # or the following for a specific version:
-docker pull badgerati/pode:2.1.0-arm32
+docker pull badgerati/pode:2.2.2-arm32
 ```
 
 Once pulled, you can [view here](../Docker) on how to use the image.
@@ -76,7 +86,17 @@ You can also get the Pode docker image from the GitHub Package Registry! The ima
 docker pull docker.pkg.github.com/badgerati/pode/pode:latest
 
 # or the following for a specific version:
-docker pull docker.pkg.github.com/badgerati/pode/pode:2.1.0
+docker pull docker.pkg.github.com/badgerati/pode/pode:2.2.2
+```
+
+* To pull down the Alpine Pode image you can do:
+
+```powershell
+# for latest
+docker pull docker.pkg.github.com/badgerati/pode/pode:latest-apline
+
+# or the following for a specific version:
+docker pull docker.pkg.github.com/badgerati/pode/pode:2.2.2-alpine
 ```
 
 * To pull down the ARM32 Pode image you can do:
@@ -86,7 +106,7 @@ docker pull docker.pkg.github.com/badgerati/pode/pode:2.1.0
 docker pull docker.pkg.github.com/badgerati/pode/pode:latest-arm32
 
 # or the following for a specific version:
-docker pull docker.pkg.github.com/badgerati/pode/pode:2.1.0-arm32
+docker pull docker.pkg.github.com/badgerati/pode/pode:2.2.2-arm32
 ```
 
 Once pulled, you can [view here](../Docker) on how to use the image.

docs/Hosting/Docker.md

@@ -2,7 +2,7 @@
 
 Pode has a Docker image that you can use to host your server, for instructions on pulling these images you can [look here](../../Installation).
 
-The images use PowerShell v7.1.1 on either an Ubuntu Bionic (default) or ARM32 image.
+The images use PowerShell v7.1.3 on either an Ubuntu Bionic (default), Alpine, or ARM32 image.
 
 ## Images
 
@@ -11,7 +11,7 @@ The images use PowerShell v7.1.1 on either an Ubuntu Bionic (default) or ARM32 i
 
 ### Default
 
-The default Pode image is an Ubuntu Bionic image with PowerShell v7.1.1 and Pode installed. An example of using this image in your Dockerfile could be as follows:
+The default Pode image is an Ubuntu Bionic image with PowerShell v7.1.3 and Pode installed. An example of using this image in your Dockerfile could be as follows:
 
 ```dockerfile
 # pull down the pode image
@@ -30,6 +30,27 @@ EXPOSE 8085
 CMD [ "pwsh", "-c", "cd /usr/src/app; ./web-pages-docker.ps1" ]
 ```
 
+### Alpine
+
+Pode also has an image for Alpine, an example of using this image in your Dockerfile could be as follows:
+
+```dockerfile
+# pull down the pode image
+FROM badgerati/pode:latest-alpine
+
+# or use the following for GitHub
+# FROM docker.pkg.github.com/badgerati/pode/pode:latest-alpine
+
+# copy over the local files to the container
+COPY . /usr/src/app/
+
+# expose the port
+EXPOSE 8085
+
+# run the server
+CMD [ "pwsh", "-c", "cd /usr/src/app; ./web-pages-docker.ps1" ]
+```
+
 ### ARM32
 
 Pode also has an image for ARM32, meaning you can run Pode on Raspberry Pis. An example of using this image in your Dockerfile could be as follows:

docs/Tutorials/Authentication/Methods/Basic.md

@@ -18,7 +18,7 @@ Start-PodeServer {
 }
 ```
 
-By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Basic`. The `New-PodeAuthScheme -Basic` function can be supplied parameters to customise this name, as well as the encoding.
+By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Basic` tag. The `New-PodeAuthScheme -Basic` function can be supplied parameters to customise the tag using `-HeaderTag`, as well as the `-Encoding`.
 
 For example, to use `ASCII` encoding rather than the default `ISO-8859-1` you could do:
 

docs/Tutorials/Authentication/Methods/Bearer.md

@@ -18,7 +18,7 @@ Start-PodeServer {
 }
 ```
 
-By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Bearer`.
+By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Bearer` tag. The `New-PodeAuthScheme -Bearer` function can be supplied parameters to customise the tag using `-HeaderTag`.
 
 You can also optionally return a `Scope` property alongside the `User`. If you specify any scopes with [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) then it will be validated in the Bearer's post validator - a 403 will be returned if the scope is invalid.
 

docs/Tutorials/Authentication/Methods/Digest.md

@@ -20,9 +20,9 @@ Start-PodeServer {
 
 Unlike other forms of authentication where you only need return the User on success. Digest requires you to also return the Password of the user as a separate property. This password is what is used as the secret key to generate the client's response hash, and allows the server to re-generate the hash for validation. (Not returning the password will result in an HTTP 401 challenge response).
 
-By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Digest`. Pode will also gather the rest of the parameters in the header such as the Nonce, NonceCount, etc. An HTTP 401 challenge will be sent back if the Authorization header is invalid.
+By default, Pode will check if the Request's header contains an `Authorization` key, and whether the value of that key starts with `Digest` tag. The `New-PodeAuthScheme -Digest` function can be supplied parameters to customise the tag using `-HeaderTag`. Pode will also gather the rest of the parameters in the header such as the Nonce, NonceCount, etc. An HTTP 401 challenge will be sent back if the Authorization header is invalid.
 
-The HashTable of parameters sent to the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) functions's ScriptBlock are the following:
+The HashTable of parameters sent to the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function's ScriptBlock are the following:
 
 | Parameter | Description |
 | --------- | ----------- |

docs/Tutorials/OpenAPI.md

@@ -310,12 +310,13 @@ Properties are used to create all Parameters and Schemas in OpenAPI. You can use
 
 ### Simple Types
 
-There are 4 simple property types: Integers, Numbers, Strings, and Booleans. Each of which can be created using the following functions:
+There are 5 simple property types: Integers, Numbers, Strings, Booleans, and Schemas. Each of which can be created using the following functions:
 
 * [`New-PodeOAIntProperty`]
 * [`New-PodeOANumberProperty`]
 * [`New-PodeOAStringProperty`]
 * [`New-PodeOABoolProperty`]
+* [`New-PodeOASchemaProperty`]
 
 These properties can be created with a Name, and other flags such as Required and/or a Description:
 
@@ -331,6 +332,9 @@ New-PodeOAStringProperty -Name 'type' -Default 'admin' -Enum @('admin', 'user')
 
 # a boolean that's required
 New-PodeOABoolProperty -Name 'enabled' -Required
+
+# a schema property that references another component schema
+New-PodeOASchemaProperty -Name 'Config' -Reference 'ConfigSchema'
 ```
 
 On their own, like above, the simple properties don't really do much. However, you can combine that together to make complex objects/arrays as defined below.

docs/release-notes.md

@@ -1,5 +1,16 @@
 # Release Notes
 
+## v2.2.2
+
+```plain
+### Enhancements
+* #727: Allow referencing an OpenAPI component schema from another component schema (thanks @glatzert!)
+* #732: Allow changing of Bearer and Digest Authorization header tags
+
+### Packaging
+* #726: Bump docker images to v7.1.3, and also add a new Alpine image
+```
+
 ## v2.2.1
 
 ```plain

packers/docker/arm32/Dockerfile

@@ -1,6 +1,6 @@
 FROM arm32v7/ubuntu:bionic
 
-ENV PS_VERSION=7.1.1
+ENV PS_VERSION=7.1.3
 ENV PS_PACKAGE=powershell-${PS_VERSION}-linux-arm32.tar.gz
 ENV PS_PACKAGE_URL=https://github.com/PowerShell/PowerShell/releases/download/v${PS_VERSION}/${PS_PACKAGE}
 

src/Pode.psd1

@@ -220,6 +220,7 @@
         'New-PodeOAStringProperty',
         'New-PodeOABoolProperty',
         'New-PodeOAObjectProperty',
+        'New-PodeOASchemaProperty',
         'ConvertTo-PodeOAParameter',
         'Set-PodeOARouteInfo',
         'Enable-PodeOpenApiViewer',

src/Private/Authentication.ps1

@@ -255,9 +255,9 @@ function Get-PodeAuthBearerType
             }
         }
 
-        if ($atoms[0] -ine 'Bearer') {
+        if ($atoms[0] -ine $options.HeaderTag) {
             return @{
-                Message = 'Authorization header is not Bearer'
+                Message = "Authorization header is not $($options.HeaderTag)"
                 Challenge = (New-PodeAuthBearerChallenge -Scopes $options.Scopes -ErrorType invalid_request)
                 Code = 400
             }
@@ -375,9 +375,9 @@ function Get-PodeAuthDigestType
             }
         }
 
-        if ($atoms[0] -ine 'Digest') {
+        if ($atoms[0] -ine $options.HeaderTag) {
             return @{
-                Message = 'Authorization header is not Digest'
+                Message = "Authorization header is not $($options.HeaderTag)"
                 Challenge = (New-PodeAuthDigestChallenge)
                 Code = 401
             }
@@ -747,7 +747,7 @@ function Get-PodeAuthWindowsADIISMethod
 
                     # Query the ADSISearcher for the above defined SID
                     $ad = $searcher.FindOne()
-                    
+
                     # Save it to our existing array for later usage
                     $user.DistinguishedName = @($ad.Properties.distinguishedname)[0]
                     $user.Name = @($ad.Properties.name)[0]

src/Private/FileMonitor.ps1

@@ -43,7 +43,7 @@ function Start-PodeFileMonitor
         # if enabled, add the file to the list of files that trigggered the restart
         if ($Event.MessageData.Settings.ShowFiles) {
             $name = "[$($Event.SourceEventArgs.ChangeType)] $($Event.SourceEventArgs.Name)"
-            
+
             if ($Event.MessageData.Settings.Files -inotcontains $name) {
                 $Event.MessageData.Settings.Files += $name
             }

src/Private/Gui.ps1

@@ -49,7 +49,7 @@ function Start-PodeGuiRunspace {
             # Check for CefSharp
             $loadCef = [bool]([AppDomain]::CurrentDomain.GetAssemblies() | Where-Object { $_.FullName.StartsWith("CefSharp.Wpf,") })
 
-            # setup the WPF XAML for the server          
+            # setup the WPF XAML for the server
             # Check for CefSharp and used Chromium based WPF if Modules exists
             if ($loadCef) {
                 $gui_browser = "

src/Private/OpenApi.ps1

@@ -130,6 +130,13 @@ function ConvertTo-PodeOASchemaProperty
         format = $Property.format
     }
 
+    # schema refs
+    if ($Property.type -ieq 'schema') {
+        $schema = @{
+            '$ref' = "#/components/schemas/$($Property['schema'])"
+        }
+    }
+
     # are we using an array?
     if ($Property.array) {
         $Property.array = $false

src/Private/Security.ps1

@@ -494,7 +494,7 @@ function Add-PodeEndpointLimit
     if ($Seconds -le 0) {
         throw "Seconds value cannot be 0 or less for $($IP)"
     }
-    
+
     # we need to check endpoints on requests
     $PodeContext.Server.FindRouteEndpoint = $true
 

src/Private/Serverless.ps1

@@ -250,7 +250,7 @@ function Start-PodeAwsLambdaServer
             'statusCode' = $response.StatusCode;
             'headers' = $response.Headers;
             'body' = $response.Body;
-        } | ConvertTo-Json -Depth 10 -Compress) 
+        } | ConvertTo-Json -Depth 10 -Compress)
     }
     catch {
         $_ | Write-PodeErrorLog