Merge pull request #700 from Badgerati/develop

v2.1.1

README.md

@@ -5,6 +5,7 @@
 [![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)
 [![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)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/Badgerati?color=%23ff69b4&logo=github&style=flat&label=Sponsers)](https://github.com/sponsors/Badgerati)
 
 [![Chocolatey](https://img.shields.io/chocolatey/dt/pode.svg?label=Chocolatey&colorB=a1301c)](https://chocolatey.org/packages/pode)
 [![PowerShell](https://img.shields.io/powershellgallery/dt/pode.svg?label=PowerShell&colorB=085298)](https://www.powershellgallery.com/packages/Pode)
@@ -22,7 +23,7 @@ See [here](https://badgerati.github.io/Pode/Getting-Started/FirstApp) for buildi
 
 All documentation and tutorials for Pode can be [found here](https://badgerati.github.io/Pode) - this documentation will be for the latest release.
 
-To see the docs for other releases, branches or tags, you can host the documentation locally. To do so you'll need to have the [`Invoke-Build`](https://github.com/nightroman/Invoke-Build) module installed; then:
+To see the docs for other releases, branches or tags, you can host the documentation locally. To do so you'll need to have the [`InvokeBuild`](https://github.com/nightroman/Invoke-Build) module installed; then:
 
 ```powershell
 Invoke-Build Docs

docs/Getting-Started/Frontend.md

@@ -1,6 +1,6 @@
 # Frontend
 
-You can host web-pages using Pode, and to help you can also use package managers like `yarn` to install frontend libraries - like bootstrap.
+You can host web-pages using Pode, as well as also using package managers like `yarn` to install frontend libraries - like bootstrap, jQuery, etc.
 
 ## Using Pode.Web
 
@@ -24,9 +24,40 @@ yarn add bootstrap
 yarn add lodash
 ```
 
+You don't have to use Yarn, you could also use NPM or anything other package manager of your choice.
+
 ## Pode Install
 
-Once you've added some libraries you can use `pode install` to trigger `yarn`. This will tell `yarn` to install the packages to a `pode_modules` directory.
+Once you've added some libraries you can use `pode install` to trigger `yarn`. This will tell `yarn` to install the packages to a `pode_modules` directory. If you're using another package manager, you'll need to update the `install` property in the `package.json` file accordingly.
 
 !!! info
     Other useful packages could include `gulp`, `jquery`, `moment`, etc.
+
+Once these packages have been installed to `pode_modules`, this folder will contain other folders for the install libraries. In most cases, these library folders will contain a `dist` folder with files like `*.min.css` or `*.min.js`. You can then move these files into a `/public` folder at the root of your Pode server.
+
+For example, if you install bootstrap then your `pode_modules` will look something like:
+
+```plain
+/pode_modules
+    /bootstrap
+        /dist
+            bootstrap.min.css
+            bootstrap.min.js
+```
+
+You then take those min files, and move them into `/public`:
+
+```plain
+/public
+    bootstrap.min.css
+    bootstrap.min.js
+```
+
+You can then reference these files in your HTML pages as:
+
+```html
+<link rel="stylesheet" type="text/css" href="/bootstrap.min.css">
+<script src="/bootstrap.min.js"></script>
+```
+
+Instead of doing this manually, you could use tools like [`InvokeBuild`](https://github.com/nightroman/Invoke-Build) or [`psake`](https://github.com/psake/psake) to automate moving the files.

docs/Getting-Started/Installation.md

@@ -2,6 +2,20 @@
 
 Pode is a PowerShell module that can be installed from either Chocolatey, the PowerShell Gallery, or Docker. Once installed, you can use the module in your PowerShell scripts.
 
+## Minimum Requirements
+
+Before installing Pode, the minimum requirements must be met:
+
+* OS:
+    * Windows
+    * Linux
+    * MacOS
+    * Raspberry Pi
+* PowerShell:
+    * Windows PowerShell 5+
+    * PowerShell (Core) 6+
+* .NET Framework 4.7.2+ (For Windows PowerShell)
+
 ## Chocolatey
 
 [![Chocolatey](https://img.shields.io/chocolatey/dt/pode.svg?label=Downloads&colorB=a1301c)](https://chocolatey.org/packages/pode)

docs/Hosting/IIS.md

@@ -130,22 +130,22 @@ If the required header is missing, then Pode responds with a 401. The retrieved
 
 ### Kerberos Constrained Delegation
 
-Pode can impersonate the user that requests the webpage using Kerberos Constrained Delegation (KCD).
+Pode can impersonate the user that requests the web page using Kerberos Constrained Delegation (KCD).
 
-Requirements
-- The use of KCD requires additional configuration in the Active Directory (read up on PrincipalsAllowedToDelegateToAccount)
-- No Session Middleware configured
+Requirements:
+
+* The use of KCD requires additional configuration in Active Directory (read up on PrincipalsAllowedToDelegateToAccount)
+* No Session middleware configured (`-Sessionless` switch on authentication setup)
 
 This can be done using the following example:
 
 ```powershell
-[System.Security.Principal.WindowsIdentity]::RunImpersonated($WebEvent.Auth.User.Identity.AccessToken,{
-    $newIdentity = [Security.Principal.WindowsIdentity]::GetCurrent() | Select-Object -ExpandProperty 'Name'    
+[System.Security.Principal.WindowsIdentity]::RunImpersonated($WebEvent.Auth.User.Identity.AccessToken, {
+    $newIdentity = [Security.Principal.WindowsIdentity]::GetCurrent() | Select-Object -ExpandProperty 'Name'
     Write-PodeTextResponse -Value "You are running this command as the server user $newIdentity"
 })
 ```
 
-
 ### Additional Validation
 
 Similar to the normal [`Add-PodeAuth`](../../Functions/Authentication/Add-PodeAuth), [`Add-PodeAuthIIS`](../../Functions/Authentication/Add-PodeAuthIIS) can be supplied can an optional ScriptBlock parameter. This ScriptBlock is supplied the found User object as a parameter, structured as details above. You can then use this to further check the user, or load additional user information from another storage.

docs/Tutorials/Certificates.md

@@ -11,6 +11,8 @@ There are 6 ways to setup HTTPS on [`Add-PodeEndpoint`](../../Functions/Core/Add
 5. Supplying `-X509Certificate` of type `X509Certificate`.
 6. Supplying the `-SelfSigned` switch, to generate a quick self-signed `X509Certificate`.
 
+Note: for 3. and 4. you can change the certificate store used by supplying `-CertificateStoreName` and/or `-CertificateStoreLocation`.
+
 ## Usage
 
 ### File
@@ -33,6 +35,8 @@ Start-PodeServer {
 }
 ```
 
+Note: You can change the certificate store used by supplying `-CertificateStoreName` and/or `-CertificateStoreLocation`.
+
 ### Name
 
 On Windows only, you can use a certificate that is installed at `Cert:\CurrentUser\My` using its subject name:
@@ -43,6 +47,8 @@ Start-PodeServer {
 }
 ```
 
+Note: You can change the certificate store used by supplying `-CertificateStoreName` and/or `-CertificateStoreLocation`.
+
 ### X509
 
 The following will instead create an X509Certificate, and pass that to the endpoint instead:

docs/Tutorials/Cookies.md

@@ -0,0 +1,49 @@
+# Cookies
+
+In Pode you can add/retrieve cookies for the Request/Response of the current web event. Using the cookie functions has to be done within the context of a web event, such as in Routes/Middleware/Authentication/Logging/Endware.
+
+## Adding Cookies
+
+You can add a cookie to the response by using [`Set-PodeCookie`](../../Functions/Cookies/Set-PodeCookie), passing the Name and Value of cookie:
+
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Set-PodeCookie -Name Cookie1 -Value Value1
+}
+```
+
+You can set a duration for the cookie, in seconds, using `-Duration`, or as an explicit expiry date using `-ExpiryDate`. For example, to set a cookie to expire after 1 minute:
+
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Set-PodeCookie -Name Cookie1 -Value Value1 -Duration 60
+}
+```
+
+## Getting Cookies
+
+To retrieve the value of a cookie on the request, you can use [`Get-PodeCookie`](../../Functions/Cookies/Get-PodeCookie):
+
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Get-PodeCookie -Name 'CookieName'
+}
+```
+
+## Removing Cookies
+
+To flag a cookie for removal on the user's browser you can use [`Remove-PodeCookie`](../../Functions/Cookies/Remove-PodeCookie), which force the cookie to expire:
+
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Remove-PodeCookie -Name 'CookieName'
+}
+```
+
+## Signing Cookies
+
+You can sign a cookie by supplying a `-Secret` to any of the cookie functions; supplying it to [`Get-PodeCookie`](../../Functions/Cookies/Get-PodeCookie) will attempt to unsign the cookie for the raw value.
+
+## Expiry Dates
+
+To update the expiry of a cookie, you can set a duration, in seconds, or as an explicit expiry date using [`Update-PodeCookieExpiry`](../../Functions/Cookies/Update-PodeCookieExpiry).

docs/Tutorials/Endpoints/Basics.md

@@ -53,8 +53,10 @@ If you add an HTTPS or WSS endpoint, then you'll be required to also supply cert
 | ---- | ----------- |
 | Certificate | The path to a `.pfx` or `.cer` certificate |
 | CertificatePassword | The password for the above `.pfx` certificate |
-| CertificateThumbprint | The thumbprint of a certificate in `CurrentUser\My` (Windows only) |
-| CertificateName | The subject name of a certificate in `CurrentUser\My` (Windows only) |
+| CertificateThumbprint | The thumbprint of a certificate to find (Windows only) |
+| CertificateName | The subject name of a certificate to find (Windows only) |
+| CertificateStoreName | The name of the certificate store (Default: My) (Windows only) |
+| CertificateStoreLocation | The location of the certificate store (Default: CurrentUser) (Windows only) |
 | X509Certificate | A raw X509Certificate object |
 | SelfSigned | If supplied, Pode will automatically generate a self-signed certificate as an X509Certificate object |
 
@@ -77,6 +79,20 @@ The below example will create a local self-signed HTTPS endpoint:
 Add-PodeEndpoint -Address * -Port 8443 -Protocol Https -SelfSigned
 ```
 
+## Endpoint Names
+
+You can give endpoints unique names by supplying the `-EndpointName` parameter. This name can then be passed to [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute) or [`Add-PodeStaticRoute`](../../../Functions/Routes/Add-PodeStaticRoute) to bind these routes to that endpoint only.
+
+For example:
+
+```powershell
+Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http -EndpointName Example
+
+Add-PodeRoute -Method Get -Path '/about' -EndpointName Example -ScriptBlock {
+    # ...
+}
+```
+
 ## Getting Endpoints
 
 The [`Get-PodeEndpoint`](../../../Functions/Core/Get-PodeEndpoint) helper function will allow you to retrieve a list of endpoints configured within Pode. You can use it to retrieve all of the endpoints, or supply filters to retrieve specific endpoints.

docs/Tutorials/Headers.md

@@ -0,0 +1,41 @@
+# Headers
+
+In Pode you can add/retrieve headers for the Request/Response of the current web event. Using the header functions has to be done within the context of a web event, such as in Routes/Middleware/Authentication/Logging/Endware.
+
+## Setting Headers
+
+There are 2 ways of setting headers on a response: [`Add-PodeHeader`](../../Functions/Headers/Add-PodeHeader) and [`Set-PodeHeader`](../../Functions/Headers/Set-PodeHeader).
+
+[`Add-PodeHeader`](../../Functions/Headers/Add-PodeHeader) will append multiple values for one header on the response - such as the `Set-Cookie` header of which there can be multiple of on a response. The following will add 2 of the same header on the response:
+
+```powershell
+Add-PodeMiddleware -Name Example -ScriptBlock {
+    Add-PodeHeader -Name Name1 -Value Value1
+    Add-PodeHeader -Name Name1 -Value Value2
+}
+```
+
+[`Set-PodeHeader`](../../Functions/Headers/Set-PodeHeader) will clear all current values for a header on the response, and reset it to one value. The following will add 2 of the same header to the response, but then override that to 1 header:
+
+```powershell
+Add-PodeMiddleware -Name Example -ScriptBlock {
+    Add-PodeHeader -Name Name1 -Value Value1
+    Add-PodeHeader -Name Name1 -Value Value2
+
+    Set-PodeHeader -Name Name1 -Value Value3
+}
+```
+
+## Getting Headers
+
+To retrieve the value of a header on the request, you can use [`Get-PodeHeader`](../../Functions/Headers/Get-PodeHeader):
+
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Get-PodeHeader -Name 'X-Header-Name'
+}
+```
+
+## Signing Headers
+
+You can sign a header by supplying a `-Secret` to any of the header functions; supplying it to [`Get-PodeHeader`](../../Functions/Headers/Get-PodeHeader) will attempt to unsign the header for the raw value.

docs/Tutorials/Logging/Types/Errors.md

@@ -6,7 +6,7 @@ It also has support for error levels (such as Error, Warning, Verbose), with sup
 
 ## Enabling
 
-To enable and use the Error logging you use the [`Enable-PodeErrorLogging`](../../../../Functions/Logging/Enable-PodeErrorLogging) function, supplying a logging method from [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod). You can supply your own errors to be logged by using [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
+To enable and use Error logging you use [`Enable-PodeErrorLogging`](../../../../Functions/Logging/Enable-PodeErrorLogging), supplying a logging method from [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod). You can supply your own errors to be logged by using [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
 
 When Pode logs an error, the information being logged is as follows:
 
@@ -27,6 +27,23 @@ The Error logging logic uses the following Error levels:
 * `Verbose`
 * `Debug`
 
+## Writing Errors
+
+You can log additional errors by using [`Write-PodeErrorLog`](../../../../Functions/Logging/Write-PodeErrorLog), which takes an Exception or an ErrorRecord (both of which can be piped). If you log an Exception you can optionally pass `-CheckInnerException`, which will also log the inner exception.
+
+For example, to log an error:
+
+```powershell
+try {
+    # ...
+}
+catch {
+    $_ | Write-PodeErrorLog
+}
+```
+
+To log an error at a different level, you can also supply a `-Level`.
+
 ## Examples
 
 ### Log to Terminal
@@ -39,10 +56,10 @@ New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
 
 ### Log Verbose
 
-The following example will enable Error logging, however it will log all Error levels up to Verbose, excluding Debug:
+The following example will enable Error logging, and it will log all errors levels except Debug:
 
 ```powershell
-New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging -Levels @('Error', 'Warning', 'Information', 'Verbose')
+New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging -Levels Error, Warning, Information, Verbose
 ```
 
 ### Using Raw Item

docs/Tutorials/Middleware/Types/Sessions.md

@@ -17,9 +17,7 @@ The following is an example of how to setup session middleware using cookies:
 
 ```powershell
 Start-PodeServer {
-    Enable-PodeSessionMiddleware -Secret 'schwifty' -Duration 120 -Extend -Generator {
-        return [System.IO.Path]::GetRandomFileName()
-    }
+    Enable-PodeSessionMiddleware -Secret 'schwifty' -Duration 120 -Extend
 }
 ```
 

docs/Tutorials/Routes/Overview.md

@@ -36,7 +36,11 @@ The scriptblock for the route will have access to the `$WebEvent` variable which
 
 ## Payloads
 
-The following is an example of using data from a request's payload - ie, the data in the body of POST request. To retrieve values from the payload you can use the `.Data` property on the `$WebEvent` variable to a route's logic. This example will get the `userId` and "find" user, returning the users data:
+The following is an example of using data from a request's payload - ie, the data in the body of POST request. To retrieve values from the payload you can use the `.Data` property on the `$WebEvent` variable to a route's logic.
+
+Depending the the Content-Type supplied, Pode has inbuilt body-parsing logic for JSON, XML, CSV, and Form data.
+
+This example will get the `userId` and "find" user, returning the users data:
 
 ```powershell
 Start-PodeServer {
@@ -65,7 +69,7 @@ Invoke-WebRequest -Uri 'http://localhost:8080/users' -Method Post -Body '{ "user
     The `ContentType` is required as it informs Pode on how to parse the requests payload. For example, if the content type were `application/json`, then Pode will attempt to parse the body of the request as JSON - converting it to a hashtable.
 
 !!! important
-    On PowerShell 4 and 5, referencing JSON data on `$WebEvent.Data` must be done as `$WebEvent.Data.userId`. This also works in PowerShell 6+, but you can also use `$WebEvent.Data['userId']` on PowerShell 6+.
+    On PowerShell 5 referencing JSON data on `$WebEvent.Data` must be done as `$WebEvent.Data.userId`. This also works in PowerShell 6+, but you can also use `$WebEvent.Data['userId']` on PowerShell 6+.
 
 ## Query Strings
 

docs/index.md

@@ -4,6 +4,7 @@
 [![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)
 [![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)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/Badgerati?color=%23ff69b4&logo=github&style=flat&label=Sponsers)](https://github.com/sponsors/Badgerati)
 
 Pode is a Cross-Platform framework to create web servers that host REST APIs, Web Sites, and TCP/SMTP Servers. It also allows you to render dynamic files using `.pode` files, which is effectively embedded PowerShell, or other Third-Party template engines. Pode also has support for middleware, sessions, authentication, and logging; as well as access and rate limiting features. There's also Azure Functions and AWS Lambda support!
 

docs/release-notes.md

@@ -1,5 +1,21 @@
 # Release Notes
 
+## v2.1.1
+
+```plain
+### Enhancements
+* #693: Add OperationId OpenAPI support on routes (thanks @glatzert)
+* #698: Add support for Certificate Store Name and Location on `Add-PodeEndoint`
+
+### Bugs
+* #686: Add EndpointName support on `Set-PodeResponseAttachment`
+* #689: Fix bug with rate limiting preventing requests when no endpoint names
+
+### Documentation
+* #661: Multiple additions to docs - error logging, cookies, headers, etc
+* #683: Bump version of mkdocs-material theme
+```
+
 ## v2.1.0
 
 ```plain

examples/assets/file.txt

@@ -0,0 +1 @@
+Hello there.

examples/web-pages.ps1

@@ -24,6 +24,9 @@ Start-PodeServer -Threads 2 {
     Add-PodeAccessRule -Access Deny -Type IP -Values '10.10.0.0/24'
     Add-PodeAccessRule -Access Deny -Type IP -Values all
 
+    # limit
+    Add-PodeLimitRule -Type IP -Values all -Limit 100 -Seconds 5
+
     # log requests to the terminal
     New-PodeLoggingMethod -Terminal -Batch 10 -BatchTimeout 10 | Enable-PodeRequestLogging
     New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging