Skip to content

Commit ea6e17d

Browse files
BadgeratiBadgerati
authored
Merge pull request #1638 from Badgerati/Issue-1548
Improved SSE/WebSocket connection handling and clean-up; Added additional events for SSE, WebSockets, and Authentication; Added manual upgrade path for WebSocket connection, including custom ClientId support
2 parents e82e945 + a23c1c8 commit ea6e17d

File tree

109 files changed

+42004
-37984
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

109 files changed

+42004
-37984
lines changed

‎docs/Tutorials/Authentication/Overview.md‎

Lines changed: 444 additions & 390 deletions
Large diffs are not rendered by default.

‎docs/Tutorials/Events.md‎

Lines changed: 92 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,92 @@
1-
# Events
2-
3-
Pode lets you register scripts to be run when certain server events are triggered. The following types of events can have scripts registered:
4-
5-
* Start
6-
* Starting
7-
* Terminate
8-
* Restarting
9-
* Restart
10-
* Browser
11-
* Crash
12-
* Stop
13-
* Running
14-
* Suspending
15-
* Suspend
16-
* Resume
17-
* Enable
18-
* Disable
19-
20-
And these events are triggered in the following order:
21-
22-
![event_flow](../../images/event-flow.png)
23-
24-
## Overview
25-
26-
You can use [`Register-PodeEvent`](../../Functions/Events/Register-PodeEvent) to register a script that can be run when an event within Pode is triggered. Each event can have multiple scripts registered, and you can unregister a script at any point using [`Unregister-PodeEvent`](../../Functions/Events/Unregister-PodeEvent):
27-
28-
```powershell
29-
# register:
30-
Register-PodeEvent -Type Start -Name '<name>' -ScriptBlock {
31-
# inform a portal, write a log, etc
32-
}
33-
34-
# unregister:
35-
Unregister-PodeEvent -Type Start -Name '<name>'
36-
```
37-
38-
The scriptblock supplied to `Register-PodeEvent` also supports `$using:` variables. You can retrieve a registered script using [`Get-PodeEvent`](../../Functions/Events/Get-PodeEvent):
39-
40-
```powershell
41-
$evt = Get-PodeEvent -Type Start -Name '<name>'
42-
```
43-
44-
## Types
45-
46-
### Start
47-
48-
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.
49-
50-
If you need the runspaces to be opened, you'll want to look at the `Running` event below.
51-
52-
These scripts will also be re-invoked after a server restart has occurred.
53-
54-
### Starting
55-
56-
Scripts registered to the `Starting` event will all be invoked during the initialization phase of the server, before the `Start` event is triggered.
57-
58-
### Terminate
59-
60-
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.
61-
62-
### Restarting
63-
64-
Scripts registered to the `Restarting` event will all be invoked when the server begins the restart process. This occurs before the `Restart` event.
65-
66-
### Restart
67-
68-
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.
69-
70-
### Browser
71-
72-
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.
73-
74-
### Crash
75-
76-
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 is 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.
77-
78-
### Stop
79-
80-
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 - whichever one causes the server to ultimately stop. Runspaces at this point will still be open.
81-
82-
### Running
83-
84-
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.
85-
86-
### Suspending
87-
88-
Scripts registered to the `Suspending` event will all be invoked when the server begins the suspension process.
89-
90-
### Suspend
91-
92-
Scripts registered to the `Suspend` event will all be invoked when the server completes the suspension process.
93-
94-
### Resume
95-
96-
Scripts registered to the `Resume` event will all be invoked when the server resumes operation after suspension.
97-
98-
### Enable
99-
100-
Scripts registered to the `Enable` event will all be invoked when the server is enabled.
101-
102-
### Disable
103-
104-
Scripts registered to the `Disable` event will all be invoked when the server is disabled.
105-
1+
# Events
2+
3+
Pode lets you register scripts to be run when certain server events are triggered. The following types of events can have scripts registered:
4+
5+
| Event | Description | Runspaces Open? |
6+
| ---------- | -------------------------------------------------------------------------------------------------- | --------------- |
7+
| Starting | Triggered during the initialization phase of the server, just after configuration has been loaded. | No |
8+
| Start | Triggered just after the server's `-ScriptBlock` has been invoked. | No |
9+
| Running | Triggered after all runspaces have been opened and are running. | Yes |
10+
| Restarting | Triggered just after a server restarted is initiated, but just before clean-up has begun. | Yes |
11+
| Restart | Triggered after the server restarts, after the clean-up has occurred. | Yes |
12+
| Terminate | Triggered just before the server terminates. | Yes |
13+
| Crash | Triggered if the server terminates due to an unhandled exception being thrown. | Unstable |
14+
| Stop | Triggered when the server stops - after either a Terminate or Crash. | Yes |
15+
| Suspending | Triggered when the server begins the suspension process. | Yes |
16+
| Suspend | Triggered when the server completes the suspension process. | Yes |
17+
| Resuming | Triggered when the server begins the resuming process after suspension | Yes |
18+
| Resume | Triggered when the server resumes operation after suspension. | Yes |
19+
| Enable | Triggered when the server is enabled. | Yes |
20+
| Disable | Triggered when the server is disabled. | No |
21+
| Browser | Triggered when the server is told to open in a browser. | Yes |
22+
23+
And these events are triggered in the following order:
24+
25+
```mermaid
26+
graph TD
27+
Launch((Launch)) --> Starting(Starting)
28+
Starting --> Start(Start)
29+
Start --> Running(Running)
30+
Running --natural stop --> Terminate(Terminate)
31+
Running --unhandled exception --> Crash(Crash)
32+
Running -- internal restart --> Restarting(Restarting)
33+
Running -- open --> Browser(Browser)
34+
Running --> Suspending(Suspending) --> Suspend(Suspend)
35+
Suspend --> Resuming(Resuming) --> Resume([Resume])
36+
Running --> Disable(Disable) --> Enable([Enable])
37+
Restarting --> Restart(Restart)
38+
Restart --> Starting
39+
Terminate --> Stop(Stop)
40+
Crash --> Stop
41+
Stop --> End((End))
42+
```
43+
44+
!!! note
45+
Resume and Enable both end up back at the "Running" state, but will not trigger the Running event.
46+
47+
## Register
48+
49+
You can use [`Register-PodeEvent`](../../Functions/Events/Register-PodeEvent) to register a scriptblock that can be run when a server level event within Pode is triggered. Each event can have multiple scripts registered.
50+
51+
For example, to register for when the server Starts:
52+
53+
```powershell
54+
Register-PodeEvent -Type Start -Name 'OnStart' -ScriptBlock {
55+
# inform a portal, write a log, etc
56+
}
57+
```
58+
59+
The scriptblock supplied to `Register-PodeEvent` also supports `$using:` variables. You can retrieve a registered script using [`Get-PodeEvent`](../../Functions/Events/Get-PodeEvent):
60+
61+
```powershell
62+
$evt = Get-PodeEvent -Type Start -Name 'OnStart'
63+
```
64+
65+
### Event Data
66+
67+
Various metadata about the server event is supplied to your scriptblock, under the `$TriggeredEvent` variable:
68+
69+
| Property | Description |
70+
| --------- | ------------------------------------------------------------------------------------- |
71+
| Lockable | A global lockable value you can use for `Lock-PodeObject` |
72+
| Metadata | Any additional metadata about the event, you can add your own properties here as well |
73+
| Type | The type of event triggered - Start, Running, Restart, etc. |
74+
| Timestamp | When the event was triggered, in UTC |
75+
76+
## Unregister
77+
78+
To unregister an previous event registration, simply use [`Unregister-PodeEvent`](../../Functions/Events/Unregister-PodeEvent):
79+
80+
81+
```powershell
82+
# to remove the Start event from above:
83+
Unregister-PodeEvent -Type Start -Name 'OnStart'
84+
```
85+
86+
## Other Events
87+
88+
The events listed above are Server related events, you can find various other events for other functionality listed below:
89+
90+
* [Authentication](../Authentication/Overview#events)
91+
* [Signals](../WebSockets/Endpoints#events)
92+
* [SSE](../Routes/Utilities/SSE#events)

0 commit comments

Comments
 (0)