Merge pull request #621 from Badgerati/Issue-618

Stop passing the WebEvent parameter, so it can be used generally

docs/Getting-Started/Migrating/1X-to-2X.md

@@ -8,7 +8,30 @@ In Pode v2.X the Server got the biggest overhaul with the dropping of HttpListen
 
 If you were previously specifying `-Type Pode` on your [`Start-PodeServer`](../../../Functions/Core/Start-PodeServer), then you no longer need to - all servers now default to using Pode new .NET Core socket listener.
 
-### Endpoints
+## Web Event
+
+Originally the Web Event object was the first parameter supplied to the ScriptBlocks of Routes, Middleware, and Endware. These already all had access to the main `$WebEvent` object, including Authentication, without the need to supply it as a parameter.
+
+In 2.0, this first event parameter has been dropped, and you should now use the main `$WebEvent` object.
+
+So from the following:
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    param($e)
+    Write-PodeJsonResponse -Value @{ Result = $e.Data['value']}
+}
+```
+
+To this:
+```powershell
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Write-PodeJsonResponse -Value @{ Result = $WebEvent.Data['value']}
+}
+```
+
+This also applies to Middleware, Endware, and Authentication.
+
+## Endpoints
 
 With the dropping of HttpListener, the `-Certificate` parameter is now the old `-CertificateFile` parameter. The `-RawCertificate` parameter has been renamed, and it now called `-X509Certificate`.
 
@@ -45,7 +68,7 @@ to:
 }
 ```
 
-### Authentication
+## Authentication
 
 Authentication underwent a hefty change in 2.0, with `Get-PodeAuthMiddleware` being removed.
 
@@ -63,7 +86,7 @@ Furthermore, the OpenAPI functions for `Set-PodeOAAuth` and `Set-PodeOAGlobalAut
 
 On `Add-PodeAuth`, `Add-PodeAuthWindowsAd`, and `Add-PodeAuthUserFile` the `-Type` parameter has been renamed to `-Scheme`. If you have always piped `New-PodeAuthScheme` (formally `New-PodeAuthType`) into them, then this won't affect you.
 
-### Endpoint and Protocol
+## Endpoint and Protocol
 
 On the following functions:
 
@@ -82,7 +105,7 @@ Further to this, if no `-Name` is supplied to [`Add-PodeEndpoint`](../../../Func
 
 The 2.0 release sees a big change to some scoping issues in Pode, around modules/snapins/functions and variables. For more information, see the new page on [Scoping](../../../Tutorials/Scoping).
 
-#### Modules/Snapins
+## Modules/Snapins
 
 You can now use `Import-Module`, or `Add-PSSnapin`, and Pode will automatically import all loaded modules/snapins into its runspaces:
 
@@ -121,7 +144,7 @@ To disable the auto-import, you can do so via the `server.psd1` configuration fi
 }
 ```
 
-#### Functions
+### Functions
 
 Local functions are now automatically imported into Pode's runspaces! This makes it a little simpler to use quick functions in Pode:
 
@@ -166,7 +189,7 @@ To disable the auto-import, you can do so via the `server.psd1` configuration fi
 }
 ```
 
-#### Variables
+### Variables
 
 You can now define local variables, and use the `$using:` syntax in almost all `-ScriptBlock` parameters, like:
 
@@ -195,7 +218,7 @@ Start-PodeServer -ScriptBlock {
 }
 ```
 
-### Test Functions
+## Test Functions
 
 If you're using any of the following:
 

docs/Hosting/AzureFunctions.md

@@ -77,14 +77,12 @@ Start-PodeServer -Request $TriggerMetadata -Type 'AzureFunctions' {
 
     # post route to create some data
     Add-PodeRoute -Method Post -Path $endpoint -ScriptBlock {
-        param($e)
-        New-Thing -Name $e.Data['Name']
+        New-Thing -Name $WebEvent.Data['Name']
     }
 
     # put route to update some data
     Add-PodeRoute -Method Put -Path $endpoint -ScriptBlock {
-        param($e)
-        Update-Thing -Name $e.Data['Name']
+        Update-Thing -Name $WebEvent.Data['Name']
     }
 }
 ```

docs/Hosting/IIS.md

@@ -105,13 +105,12 @@ Start-PodeServer {
     Add-PodeAuthIIS -Name 'IISAuth' -Sessionless
 
     Add-PodeRoute -Method Get -Path '/test' -Authentication 'IISAuth' -ScriptBlock {
-        param($e)
-        Write-PodeJsonResponse -Value @{ User = $e.Auth.User }
+        Write-PodeJsonResponse -Value @{ User = $WebEvent.Auth.User }
     }
 }
 ```
 
-If the required header is missing, then Pode responds with a 401. The retrieved user, like other authentication, is set in the web event's `Auth.User` and contains the same information as Pode's inbuilt Windows AD authenticator:
+If the required header is missing, then Pode responds with a 401. The retrieved user, like other authentication, is set on the [web event](../../../WebEvent)'s `$WebEvent.Auth.User` property, and contains the same information as Pode's inbuilt Windows AD authenticator:
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |

docs/Hosting/SmtpServer.md

@@ -1,26 +1,33 @@
 # SMTP Server
 
-Pode has an inbuilt SMTP server which automatically creates a TCP listener on port 25 (unless you specify a different port via the  [`Add-PodeEndpoint`](../../Functions/Core/Add-PodeEndpoint) function).
+Pode has an inbuilt SMTP server which automatically creates a TCP listener on port 25 (unless you specify a different port via the [`Add-PodeEndpoint`](../../Functions/Core/Add-PodeEndpoint) function).
 
 Unlike with web servers that use the Route functions, SMTP servers use the Handler functions, which let you specify logic for handling responses from TCP streams.
 
 To create a Handler for the inbuilt SMTP server you can use the following example:
 
 ```powershell
 Start-PodeServer {
-    Add-PodeEndpoint -Address * -Port 25 -Protocol SMTP
+    Add-PodeEndpoint -Address * -Port 25 -Protocol Smtp
 
     Add-PodeHandler -Type Smtp -Name 'Main' -ScriptBlock {
-        param($email)
-
-        Write-Host $email.From
-        Write-Host $email.To
-        Write-Host $email.Data
+        Write-Host $SmtpEvent.Email.From
+        Write-Host $SmtpEvent.Email.To
+        Write-Host $SmtpEvent.Email.Body
     }
 }
 ```
 
-The SMTP Handler will be passed the current email object, and this will have the following properties:
+The SMTP Handler will be passed the a `$SmtpEvent` object, that contains te Request, Response, and Email:
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| Request | object | The raw Request object |
+| Response | object | The raw Response object |
+| Lockable | hashtable | A synchronized hashtable that can be used with `Lock-PodeObject` |
+| Email | hashtable | An object containing data from the email, as seen below |
+
+The `Email` property contains the following:
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |

docs/Tutorials/Authentication/Inbuilt/UserFile.md

@@ -61,7 +61,7 @@ Start-PodeServer {
 
 ### User Object
 
-The User object returned, and accessible on Routes, and other functions via the web event's `$e.Auth.User`, will contain the following information:
+The User object returned, and accessible on Routes, and other functions via the [web event](../../../WebEvent)'s `$WebEvent.Auth.User` property, will contain the following information:
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
@@ -75,8 +75,7 @@ Such as:
 
 ```powershell
 Add-PodeRoute -Method Get -Path '/info' -Authentication 'Login' -ScriptBlock {
-    param($e)
-    Write-Host $e.Auth.User.Username
+    Write-Host $WebEvent.Auth.User.Username
 }
 ```
 

docs/Tutorials/Authentication/Inbuilt/WindowsAD.md

@@ -16,7 +16,7 @@ Start-PodeServer {
 
 ### User Object
 
-The User object returned, and accessible on Routes, and other functions via `$e.Auth.User`, will contain the following information:
+The User object returned, and accessible on Routes, and other functions via `$WebEvent.Auth.User`, will contain the following information:
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
@@ -34,8 +34,7 @@ Such as:
 
 ```powershell
 Add-PodeRoute -Method Get -Path '/info' -Authentication 'Login' -ScriptBlock {
-    param($e)
-    Write-Host $e.Auth.User.Username
+    Write-Host $WebEvent.Auth.User.Username
 }
 ```
 

docs/Tutorials/Authentication/Methods/ClientCertificate.md

@@ -2,7 +2,7 @@
 
 Client Certificate Authentication is when the server requires the client to supply a certificate on the request, to verify themselves with the server. This only works over HTTPS connections.
 
-If at any point to you need to access the client's certificate outside of this validator, then it can be found on the web event object at `Request.ClientCertificate`.
+If at any point to you need to access the client's certificate outside of this validator, then it can be found on the [web event](../../../WebEvent) object at `Request.ClientCertificate`.
 
 ## Setup
 

docs/Tutorials/Authentication/Methods/Custom.md

@@ -8,23 +8,23 @@ To setup and start using Custom authentication in Pode you use the `New-PodeAuth
 
 Let's say we wanted something similar to [`Form`](../Form) Authentication, but it requires a third piece of information: `ClientName`. To setup Custom Authentication for this method, you'll need to specify the parsing logic within the `-ScriptBlock` of the [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) function.
 
-The `-ScriptBlock` on [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) will be passed the current [web event](../../../WebEvent) (containing the `Request`/`Response` objects, and other pieces of information much like on Routes or Middleware). In this script you can parse the Request payload/headers for any credential information that needs validating. Once sourced the data returned from the script should be an `array`, which will then splatted onto the `-ScriptBlock` from your [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function:
+The `-ScriptBlock` on [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) will have access to the current [web event](../../../WebEvent) variable: `$WebEvent`. In this script you can parse the Request payload/headers for any credential information that needs validating. Once sourced the data returned from the script should be an `array`, which will then splatted onto the `-ScriptBlock` from your [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function:
 
 ```powershell
 Start-PodeServer {
     # define a new custom authentication scheme
     $custom_scheme = New-PodeAuthScheme -Custom -ScriptBlock {
-        param($e, $opts)
+        param($opts)
 
         # get client/user/password field names
         $clientField = (Protect-PodeValue -Value $opts.ClientField -Default 'client')
         $userField = (Protect-PodeValue -Value $opts.UsernameField -Default 'username')
         $passField = (Protect-PodeValue -Value $opts.PasswordField -Default 'password')
 
         # get the client/user/password from the request's post data
-        $client = $e.Data.$clientField
-        $username = $e.Data.$userField
-        $password = $e.Data.$passField
+        $client = $WebEvent.Data.$clientField
+        $username = $WebEvent.Data.$userField
+        $password = $WebEvent.Data.$passField
 
         # return the data in a array, which will be passed to the validator script
         return @($client, $username, $password)
@@ -49,11 +49,10 @@ Start-PodeServer {
 
 The typical setup of authentication is that you create some scheme to parse the request ([`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme)), and then you pipe this into a validator to validate the parsed user's credentials ([`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth)).
 
-There is however also an optional `-PostValidator` ScriptBlock that can be passed to your Custom Authentication scheme on the [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) function. This `-PostValidator` script runs after normal user validation, and is supplied the current [web event](../../../WebEvent), the original splatted array returned from the [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) ScriptBlock, the result HashTable from the user validator from `Add-PodeAuth`, and the `-ArgumentList` HashTable from `New-PodeAuthScheme`. You can use this script to re-generate any hashes for further validation, but if successful you *must* return the User object again (ie: re-return the last parameter which is the original validation result).
+There is however also an optional `-PostValidator` ScriptBlock that can be passed to your Custom Authentication scheme on the [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) function. This `-PostValidator` script runs after normal user validation, and also has access to the current [web event](../../../WebEvent). The original splatted array returned from the [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) ScriptBlock, the result HashTable from the user validator from `Add-PodeAuth`, and the `-ArgumentList` HashTable from `New-PodeAuthScheme` are supplied as parameters. You can use this script to re-generate any hashes for further validation, but if successful you *must* return the User object again (ie: re-return the last parameter which is the original validation result).
 
 For example, if you have a post validator script for the above Client Custom Authentication, then it would be supplied the following parameters:
 
-* Web Event
 * ClientName
 * Username
 * Password
@@ -67,23 +66,23 @@ For example:
 Start-PodeServer {
     # define a new custom authentication scheme
     $custom_scheme = New-PodeAuthScheme -Custom -ScriptBlock {
-        param($e, $opts)
+        param($opts)
 
         # get client/user/password field names
         $clientField = (Protect-PodeValue -Value $opts.ClientField -Default 'client')
         $userField = (Protect-PodeValue -Value $opts.UsernameField -Default 'username')
         $passField = (Protect-PodeValue -Value $opts.PasswordField -Default 'password')
 
         # get the client/user/password from the request's post data
-        $client = $e.Data.$clientField
-        $username = $e.Data.$userField
-        $password = $e.Data.$passField
+        $client = $WebEvent.Data.$clientField
+        $username = $WebEvent.Data.$userField
+        $password = $WebEvent.Data.$passField
 
         # return the data in a array, which will be passed to the validator script
         return @($client, $username, $password)
     } `
     -PostValidator {
-        param($e, $client, $username, $password, $result, $opts)
+        param($client, $username, $password, $result, $opts)
 
         # run any extra post-validation logic
 
@@ -135,17 +134,17 @@ Start-PodeServer {
 
     # define a new custom authentication scheme
     $custom_scheme = New-PodeAuthScheme -Custom -ScriptBlock {
-        param($e, $opts)
+        param($opts)
 
         # get client/user/pass field names to get from payload
         $clientField = (Protect-PodeValue -Value $opts.ClientField -Default 'client')
         $userField = (Protect-PodeValue -Value $opts.UsernameField -Default 'username')
         $passField = (Protect-PodeValue -Value $opts.PasswordField -Default 'password')
 
         # get the client/user/pass from the post data
-        $client = $e.Data.$clientField
-        $username = $e.Data.$userField
-        $password = $e.Data.$passField
+        $client = $WebEvent.Data.$clientField
+        $username = $WebEvent.Data.$userField
+        $password = $WebEvent.Data.$passField
 
         # return the data, to be passed to the validator script
         return @($client, $username, $password)

docs/Tutorials/Authentication/Methods/Form.md

@@ -4,7 +4,7 @@ Form Authentication is for when you're using a `<form>` in HTML, and you submit
 
 ## Setup
 
-To setup and start using Form Authentication in Pode you use the `New-PodeAuthScheme -Form` function, and then pipe this into the  [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function:
+To setup and start using Form Authentication in Pode you use the `New-PodeAuthScheme -Form` function, and then pipe this into the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function:
 
 ```powershell
 Start-PodeServer {

docs/Tutorials/Authentication/Overview.md

@@ -30,17 +30,17 @@ Where as the following example defines a Custom scheme that retrieves the user's
 ```powershell
 Start-PodeServer {
     $custom_type = New-PodeAuthScheme -Custom -ScriptBlock {
-        param($e, $opts)
+        param($opts)
 
         # get client/user/pass field names to get from payload
         $clientField = (Protect-PodeValue -Value $opts.ClientField -Default 'client')
         $userField = (Protect-PodeValue -Value $opts.UsernameField -Default 'username')
         $passField = (Protect-PodeValue -Value $opts.PasswordField -Default 'password')
 
         # get the client/user/pass from the post data
-        $client = $e.Data.$clientField
-        $username = $e.Data.$userField
-        $password = $e.Data.$passField
+        $client = $WebEvent.Data.$clientField
+        $username = $WebEvent.Data.$userField
+        $password = $WebEvent.Data.$passField
 
         # return the data as an array, to be passed to the validator script
         return @($client, $username, $password)
@@ -133,21 +133,6 @@ WWW-Authenticate: Basic realm="Enter creds to access site"
 !!! note
     If no Realm was set then it would just look as follows: `WWW-Authenticate: Basic`
 
-#### WebEvent
-
-By default the web event for the current request is not supplied to the validator's ScriptBlock. If you ever need the web event though, such as for accessing other request details like a client certificate, then you can supply the `-PassEvent` switch on [`Add-PodeAuth`](../../../Functions/Authentication/Add-PodeAuth). With this, Pode will supply the current web event as the first parameter:
-
-```powershell
-Start-PodeServer {
-    New-PodeAuthScheme -Basic | Add-PodeAuth -Name 'Login' -Sessionless -PassEvent -ScriptBlock {
-        param($e, $username, $pass)
-        # logic to check user
-        # logic to check client cert (found at: $e.Request.ClientCertificate)
-        return @{ 'user' = $user }
-    }
-}
-```
-
 ### Routes/Middleware
 
 To use an authentication on a specific route, you can use the `-Authentication` parameter on the [`Add-PodeRoute`](../../../Functions/Routes/Add-PodeRoute) function; this takes the Name supplied to the `-Name` parameter on [`Add-PodeAuth`](../../../Functions/Authentication/Add-PodeAuth). This will set the authentication up to run before other route middleware.
@@ -192,10 +177,8 @@ The following example get the user's name from the `Auth` object:
 
 ```powershell
 Add-PodeRoute -Method Get -Path '/' -Authentication 'Login' -Login -ScriptBlock {
-    param($e)
-
     Write-PodeViewResponse -Path 'index' -Data @{
-        'Username' = $e.Auth.User.Name
+        'Username' = $WebEvent.Auth.User.Name
     }
 }
 ```

docs/Tutorials/Configuration.md

@@ -27,7 +27,7 @@ After this, you can put whatever else you want into the configuration file.
 
 The configuration file is automatically loaded when you start your server. Pode will look in the root directory of your server for a `server.psd1` file, and if found it will be loaded internally.
 
-Within your scripts you can use the  [`Get-PodeConfig`](../../Functions/Utilities/Get-PodeConfig) function, which will return the values of the relevant configuration file.
+Within your scripts you can use the [`Get-PodeConfig`](../../Functions/Utilities/Get-PodeConfig) function, which will return the values of the relevant configuration file.
 
 For example, say you have the following `server.psd1`:
 

docs/Tutorials/Logging/Methods/Custom.md

@@ -7,7 +7,7 @@ These custom method can be used for any log type - Requests, Error, or Custom.
 The ScriptBlock you create will be supplied two arguments:
 
 1. The item to be logged. This could be a string (from Requests/Errors), or any custom type.
-2. The options you supplied on  [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
+2. The options you supplied on [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
 
 ## Examples