diff --git a/docs/Getting-Started/Migrating/1X-to-2X.md b/docs/Getting-Started/Migrating/1X-to-2X.md index 5edd78b05..230991d5c 100644 --- a/docs/Getting-Started/Migrating/1X-to-2X.md +++ b/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: diff --git a/docs/Hosting/AzureFunctions.md b/docs/Hosting/AzureFunctions.md index 24d4b5fec..7cc281c4b 100644 --- a/docs/Hosting/AzureFunctions.md +++ b/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'] } } ``` diff --git a/docs/Hosting/IIS.md b/docs/Hosting/IIS.md index 4eea26fba..21761e4a3 100644 --- a/docs/Hosting/IIS.md +++ b/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 | | ---- | ---- | ----------- | diff --git a/docs/Hosting/SmtpServer.md b/docs/Hosting/SmtpServer.md index 1e453d334..96916bfb2 100644 --- a/docs/Hosting/SmtpServer.md +++ b/docs/Hosting/SmtpServer.md @@ -1,6 +1,6 @@ # 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. @@ -8,19 +8,26 @@ To create a Handler for the inbuilt SMTP server you can use the following exampl ```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 | | ---- | ---- | ----------- | diff --git a/docs/Tutorials/Authentication/Inbuilt/UserFile.md b/docs/Tutorials/Authentication/Inbuilt/UserFile.md index bf64b3db4..334aef0fb 100644 --- a/docs/Tutorials/Authentication/Inbuilt/UserFile.md +++ b/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 } ``` diff --git a/docs/Tutorials/Authentication/Inbuilt/WindowsAD.md b/docs/Tutorials/Authentication/Inbuilt/WindowsAD.md index 2bac38577..52222d16b 100644 --- a/docs/Tutorials/Authentication/Inbuilt/WindowsAD.md +++ b/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 } ``` diff --git a/docs/Tutorials/Authentication/Methods/ClientCertificate.md b/docs/Tutorials/Authentication/Methods/ClientCertificate.md index ad6589931..e9615fc7c 100644 --- a/docs/Tutorials/Authentication/Methods/ClientCertificate.md +++ b/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 diff --git a/docs/Tutorials/Authentication/Methods/Custom.md b/docs/Tutorials/Authentication/Methods/Custom.md index 03399d433..c76e4c36b 100644 --- a/docs/Tutorials/Authentication/Methods/Custom.md +++ b/docs/Tutorials/Authentication/Methods/Custom.md @@ -8,13 +8,13 @@ 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') @@ -22,9 +22,9 @@ Start-PodeServer { $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,7 +66,7 @@ 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') @@ -75,15 +74,15 @@ Start-PodeServer { $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,7 +134,7 @@ 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') @@ -143,9 +142,9 @@ Start-PodeServer { $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) diff --git a/docs/Tutorials/Authentication/Methods/Form.md b/docs/Tutorials/Authentication/Methods/Form.md index 26b579771..58379ce4a 100644 --- a/docs/Tutorials/Authentication/Methods/Form.md +++ b/docs/Tutorials/Authentication/Methods/Form.md @@ -4,7 +4,7 @@ Form Authentication is for when you're using a `