Merge remote-tracking branch 'upstream/develop' into Log-rest-syslog

.github/workflows/ci-pwsh7_5.yml

@@ -25,7 +25,7 @@ on:
 
 env:
   INVOKE_BUILD_VERSION: '5.12.0'
-  POWERSHELL_VERSION: '7.5.0-rc.1'
+  POWERSHELL_VERSION: '7.5.0'
 
 
 jobs:

Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/powershell:7.4-ubuntu-22.04
+FROM mcr.microsoft.com/powershell:7.5-ubuntu-24.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

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/powershell:7.4-alpine-3.20
+FROM mcr.microsoft.com/powershell:7.5-alpine-3.20
 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 mcr.microsoft.com/powershell:7.4-ubuntu-22.04-arm32
+FROM mcr.microsoft.com/powershell:7.5-ubuntu-22.04-arm32
 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 the latest version of PowerShell v7.4 on either an Ubuntu Jammy image (default), an Alpine image, 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 the latest version of PowerShell v7.5 on either an Ubuntu Noble image (default), an Alpine image, or an ARM32 image (for Raspberry Pis).
 
 * To pull down the latest Pode image you can do:
 

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.4 on either an Ubuntu Jammy (default), Alpine, or ARM32 image.
+The images use PowerShell v7.5 on either an Ubuntu Noble (default), Alpine, or ARM32 image.
 
 ## Images
 
@@ -11,7 +11,7 @@ The images use PowerShell v7.4 on either an Ubuntu Jammy (default), Alpine, or A
 
 ### Default
 
-The default Pode image is an Ubuntu Jammy image with PowerShell v7.4 and Pode installed. An example of using this image in your Dockerfile could be as follows:
+The default Pode image is an Ubuntu Noble image with PowerShell v7.5 and Pode installed. An example of using this image in your Dockerfile could be as follows:
 
 ```dockerfile
 # pull down the pode image

docs/Tutorials/Middleware/Overview.md

@@ -4,7 +4,7 @@ Middleware in Pode allows you to observe and edit the request/response objects f
 
 Middleware is supported in both a global scope, using [`Add-PodeMiddleware`](../../../Functions/Middleware/Add-PodeMiddleware), as well as at the Route level using the `-Middleware` parameter on [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute).
 
-Pode itself has some inbuilt Middleware, which is overridable, so you can use your own custom middleware. For example, Pode has inbuilt Middleware for rate limiting, but you can override this with [`Add-PodeMiddleware`](../../../Functions/Middleware/Add-PodeMiddleware) and the Name `__pode_mw_rate_limit__` (more on the [Access Rules](../Types/AccessRules) and [Rate Limiting](../Types/RateLimiting) page).
+Pode itself has some inbuilt Middleware, which is overridable, so you can use your own custom middleware. For example, Pode has inbuilt Middleware for rate limiting, but you can override this with [`Add-PodeMiddleware`](../../../Functions/Middleware/Add-PodeMiddleware) and the Name `__pode_mw_rate_limit__` (more on the [Access Rules](../Types/Limiters/AccessRules) and [Rate Rules](../Types/Limiters/RateRules) page).
 
 ## Global Middleware
 

docs/Tutorials/Middleware/Types/Limiters/AccessRules.md

@@ -0,0 +1,105 @@
+# Access Rules
+
+Access rules in Pode are inbuilt Middleware that allow you to specify allow/deny rules for requests, built using [Limit Components](../Components). For example, you could deny certain IPs from accessing the server, and vice-versa by allowing them.
+
+## Usage
+
+To create access rules in Pode you use the [`Add-PodeLimitAccessRule`](../../../../../Functions/Limit/Add-PodeLimitAccessRule) function, together with a series of [Limit Components](../Components).
+
+This page will give some quick examples of Access Rules, for more information on the components themselves go to the components page. However, in general you can use the components to build access rules to allow/deny IPs, subnets, access to specific Routes/Endpoints, etc.
+
+!!! info
+    If a requests hits your server from an address 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.
+
+The following example will allow access for requests from localhost:
+
+```powershell
+Add-PodeLimitAccessRule -Name 'example' -Action Allow -Component @(
+    New-PodeLimitIPComponent -IP '127.0.0.1'
+)
+```
+
+Whereas the following example will deny access for requests from a subnet:
+
+```powershell
+Add-PodeLimitAccessRule -Name 'example' -Action Deny -Component @(
+    New-PodeLimitIPComponent -IP '10.10.0.0/24'
+)
+```
+
+You can also only allow localhost access to a `/downloads` route:
+
+```powershell
+Add-PodeLimitAccessRule -Name 'example' -Action Allow -Component @(
+    New-PodeLimitIPComponent -IP '127.0.0.1'
+    New-PodeLimitRouteComponent -Path '/downloads'
+)
+```
+
+Or, deny all requests from a subnet, and send back a custom status code:
+
+```powershell
+Add-PodeLimitAccessRule -Name 'example' -Action Deny -StatusCode 401 -Component @(
+    New-PodeLimitIPComponent -IP '192.0.1.0/16'
+)
+```
+
+As a last resort you can even deny all requests from any IP:
+
+```powershell
+Add-PodeLimitAccessRule -Name 'example' -Action Deny -Component @(
+    New-PodeLimitIPComponent
+)
+```
+
+## Priority
+
+By default, all access rules are created with a minimum priority - meaning the rules will be executed in the order they are created.
+
+If you want to have more control over this, you can customise the priority via the `-Priority` parameter. The higher the value, the higher the priority. If two or more rules have the same priority, then they are run in creation order.
+
+```powershell
+Add-PodeLimitAccessRule -Name 'example' -Action Deny -Priority 100 -Component @(
+    New-PodeLimitIPComponent -IP '192.0.1.0/16'
+)
+```
+
+## Functions
+
+Other helper functions for access rules are:
+
+* [`Update-PodeLimitAccessRule`](../../../../../Functions/Limit/Update-PodeLimitAccessRule)
+* [`Remove-PodeLimitAccessRule`](../../../../../Functions/Limit/Remove-PodeLimitAccessRule)
+* [`Test-PodeLimitAccessRule`](../../../../../Functions/Limit/Test-PodeLimitAccessRule)
+* [`Get-PodeLimitAccessRule`](../../../../../Functions/Limit/Get-PodeLimitAccessRule)
+
+## Overriding
+
+Since access rules are an inbuilt Middleware in Pode, then when you create any rules the point at which the rules are checked on the request lifecycle is fixed (see [here](../../Overview/#order-of-running)).
+
+This means you can override the inbuilt access rule logic with your own custom logic, using the [`Add-PodeMiddleware`](../../../../../Functions/Middleware/Add-PodeMiddleware) function. To override the access rule logic you can pass `__pode_mw_access__` to the `-Name` parameter of the [`Add-PodeMiddleware`](../../../../../Functions/Middleware/Add-PodeMiddleware) function.
+
+The following example uses access rules, and defines Middleware that will override the inbuilt access logic:
+
+```powershell
+Start-PodeServer {
+    # attach to port 8080
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
+
+    # assign access rule to deny localhost
+    Add-PodeLimitAccessRule -Name 'example' -Action Deny -Component @(
+        New-PodeLimitIPComponent -IP @('127.0.0.1', '[::1]')
+    )
+
+    # create middleware to override the inbuilt access rule logic.
+    # this will ignore the 'deny' part, and just allow the request
+    Add-PodeMiddleware -Name '__pode_mw_access__' -ScriptBlock {
+        return $true
+    }
+
+    # basic route
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        # logic
+    }
+}
+```

docs/Tutorials/Middleware/Types/Limiters/Components.md

@@ -0,0 +1,99 @@
+# Components
+
+When building limit rules - such as Access or Rate - you build them using various "components". The following inbuilt components currently exist:
+
+* IP
+* Route
+* Endpoint
+* Method
+* Header
+
+You can use these components on their own, or combine them to make more advanced limit rule configurations. For example, limit requests from a subnet to a specific group of Routes - say limiting requests to 10 per minute, to the Routes under `/api/*`:
+
+```powershell
+Add-PodeLimitRateRule -Name 'example' -Limit 10 -Duration 60000 -Component @(
+    New-PodeLimitIPComponent -Value '10.10.0.0/24' -Group
+    New-PodeLimitRouteComponent -Value '/api/*' -Group
+)
+```
+
+## IP
+
+An IP Component can be created via [`New-PodeLimitIPComponent`](../../../../../Functions/Limit/New-PodeLimitIPComponent). You can specify none, one, or more IP or subnet addresses - if none are supplied, then the component will match every IP.
+
+```powershell
+# match every IP - and treat them individually
+New-PodeLimitIPComponent
+
+# match every IP - but treat them as 1 entity
+New-PodeLimitIPComponent -Group
+
+# match specific IP address(es)
+New-PodeLimitIPComponent -IP '10.0.0.92', '192.0.1.131'
+
+# match all IPs in a subnet - and treat them individually
+New-PodeLimitIPComponent -IP '10.0.1.0/16'
+
+# match all IPs in a subnet - but treat them as 1 entity
+New-PodeLimitIPComponent -IP '10.0.1.0/16' -Group
+```
+
+## Route
+
+A Route Component can be created via [`New-PodeLimitRouteComponent`](../../../../../Functions/Limit/New-PodeLimitRouteComponent). You can specify none, one, or more Route paths - if none are supplied, then the component will match every Route path. You can also use wildcard/regex to match multiple Routes.
+
+```powershell
+# match every Route - and treat them individually
+New-PodeLimitRouteComponent
+
+# match every Route - but treat them as 1 entity
+New-PodeLimitRouteComponent -Group
+
+# match specific Route path(s)
+New-PodeLimitRouteComponent -Path '/download', '/api/users'
+
+# match all Routes via a wildcard - and treat them individually
+New-PodeLimitRouteComponent -Path '/api/*'
+
+# match all Routes via a wildcard - but treat them as 1 entity
+New-PodeLimitRouteComponent -Path '/api/*' -Group
+```
+
+## Endpoint
+
+An Endpoint Component can be created via [`New-PodeLimitEndpointComponent`](../../../../../Functions/Limit/New-PodeLimitEndpointComponent). You can specify none, one, or more Endpoint names - if none are supplied, then the component will match every Endpoint.
+
+```powershell
+# match every Endpoint - and treat them individually
+New-PodeLimitEndpointComponent
+
+# match specific Endpoint(s)
+New-PodeLimitEndpointComponent -Name 'api', 'admin'
+```
+
+## Method
+
+A Method Component can be created via [`New-PodeLimitMethodComponent`](../../../../../Functions/Limit/New-PodeLimitMethodComponent). You can specify none, one, or more HTTP methods - if none are supplied, then the component will match every method.
+
+```powershell
+# match every Method - and treat them individually
+New-PodeLimitMethodComponent
+
+# match specific Method(s)
+New-PodeLimitMethodComponent -Method 'Get', 'Post'
+```
+
+## Header
+
+A Header Component can be created via [`New-PodeLimitHeaderComponent`](../../../../../Functions/Limit/New-PodeLimitHeaderComponent). You can specify one or more Headers, and you can also specify specific values for the Headers to match on as well.
+
+```powershell
+# match a specific Header - and treat different values individually
+New-PodeLimitHeaderComponent -Name 'X-API-KEY'
+
+# match a specific Header - but ignore the value, and treat them as 1 entity
+New-PodeLimitHeaderComponent -Name 'X-API-KEY' -Group
+
+# match a specific Header, with a specific value
+New-PodeLimitHeaderComponent -Name 'X-API-KEY' -Value '1c1aad92-194e-433a-bf0a-385434dcac13'
+```