Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new Running event, which triggers after Start when Runspaces are available #1114

Merged
merged 2 commits into from
Jul 8, 2023
Merged

Add new Running event, which triggers after Start when Runspaces are available #1114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2e448b8
#1107, #1082: Add new Running event, which triggers after Start when …
Badgerati Jul 8, 2023
9884114
Clean-up from review
Badgerati Jul 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 17 additions & 8 deletions docs/Tutorials/Events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ Pode lets you register scripts to be run when certain server events are triggere
* Browser
* Crash
* Stop
* Running

And these events are triggered in the following order:

![event_flow](../../images/event-flow.png)

## Overview

Expand All @@ -33,28 +38,32 @@ $evt = Get-PodeEvent -Type Start -Name '<name>'

### Start

Scripts registered to the `Start` event will all be invoked just after the server's main scriptblock has been invoked - ie: the `-ScriptBlock` supplied to [`Start-PodeServer`](../../Functions/Core/Start-PodeServer).
Scripts registered to the `Start` event will all be invoked just after the `-ScriptBlock` supplied to [`Start-PodeServer`](../../Functions/Core/Start-PodeServer) has been invoked, and just before the runspaces for Pode have been opened.

If you need the runspaces to be opened, you'll want to look at the `Running` event below.

These scripts will also be re-invoked after a server restart has occurred.

### Terminate

Scripts registered to the `Terminate` event will all be invoked just before the server terminates. Ie, when the `Terminating...` message usually appears in the terminal, the script will run just after this and just before the `Done` message.

These script *will not* run when a Restart is triggered.
Scripts registered to the `Terminate` event will all be invoked just before the server terminates. Ie, when the `Terminating...` message usually appears in the terminal, the script will run just after this and just before the `Done` message. Runspaces at this point will still be open.

### Restart

Scripts registered to the `Restart` event will all be invoked whenever an internal server restart occurs. This could be due to file monitoring, auto-restarting, `Ctrl+R`, or [`Restart-PodeServer`](../../Functions/Core/Restart-PodeServer). They will be invoked just after the `Restarting...` message appears in the terminal, and just before the `Done` message.
Scripts registered to the `Restart` event will all be invoked whenever an internal server restart occurs. This could be due to file monitoring, auto-restarting, `Ctrl+R`, or [`Restart-PodeServer`](../../Functions/Core/Restart-PodeServer). They will be invoked just after the `Restarting...` message appears in the terminal, and just before the `Done` message. Runspaces at this point will still be open.

### Browser

Scripts registered to the `Browser` event will all be invoked whenever the server is told to open a browser, ie: when `Ctrl+B` is pressed.
Scripts registered to the `Browser` event will all be invoked whenever the server is told to open a browser, ie: when `Ctrl+B` is pressed. Runspaces at this point will still be open.

### Crash

Scripts registered to the `Crash` event will all be invoked if the server ever terminates due to an exception being thrown. If a Crash event it triggered, then Terminate will not be triggered.
Scripts registered to the `Crash` event will all be invoked if the server ever terminates due to an exception being thrown. If a Crash event it triggered, then Terminate will not be triggered. Runspaces at this point will still be open, but there could be a chance not all of them will be available as the crash could have occurred from a runspace error.

### Stop

Scripts registered to the `Stop` event will all be invoked when the server stops and closes. This event will be fired after either the Terminate or Crash events - which ever one causes the server to ultimately stop.
Scripts registered to the `Stop` event will all be invoked when the server stops and closes. This event will be fired after either the Terminate or Crash events - which ever one causes the server to ultimately stop. Runspaces at this point will still be open.

### Running

Scripts registered to the `Running` event will all be run soon after the `Start` event, even after a `Restart`. At this point all of the runspaces will have been opened and available for use.
Binary file added docs/images/event-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions src/Private/Context.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,6 +408,7 @@ function New-PodeContext
Browser = [ordered]@{}
Crash = [ordered]@{}
Stop = [ordered]@{}
Running = [ordered]@{}
}

# modules
Expand Down
2 changes: 1 addition & 1 deletion src/Private/Events.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ function Invoke-PodeEvent
{
param(
[Parameter(Mandatory=$true)]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop')]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop', 'Running')]
[string]
$Type
)
Expand Down
4 changes: 4 additions & 0 deletions src/Private/Server.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,9 @@ function Start-PodeInternalServer
# set the start time of the server (start and after restart)
$PodeContext.Metrics.Server.StartTime = [datetime]::UtcNow

# run running event hooks
Invoke-PodeEvent -Type Running

# state what endpoints are being listened on
if ($endpoints.Length -gt 0) {
Write-PodeHost "Listening on the following $($endpoints.Length) endpoint(s) [$($PodeContext.Threads.General) thread(s)]:" -ForegroundColor Yellow
Expand Down Expand Up @@ -268,6 +271,7 @@ function Restart-PodeInternalServer
# reload the configuration
$PodeContext.Server.Configuration = Open-PodeConfiguration -Context $PodeContext

# done message
Write-PodeHost " Done" -ForegroundColor Green

# restart the server
Expand Down
10 changes: 5 additions & 5 deletions src/Public/Events.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ function Register-PodeEvent
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop')]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop', 'Running')]
[string]
$Type,

Expand Down Expand Up @@ -80,7 +80,7 @@ function Unregister-PodeEvent
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop')]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop', 'Running')]
[string]
$Type,

Expand Down Expand Up @@ -119,7 +119,7 @@ function Test-PodeEvent
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop')]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop', 'Running')]
[string]
$Type,

Expand Down Expand Up @@ -152,7 +152,7 @@ function Get-PodeEvent
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop')]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop', 'Running')]
[string]
$Type,

Expand Down Expand Up @@ -182,7 +182,7 @@ function Clear-PodeEvent
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop')]
[ValidateSet('Start', 'Terminate', 'Restart', 'Browser', 'Crash', 'Stop', 'Running')]
[string]
$Type
)
Expand Down