diff --git a/.github/workflows/BuildWebSocket.yml b/.github/workflows/BuildWebSocket.yml
index 2f67fd1..dd87ef2 100644
--- a/.github/workflows/BuildWebSocket.yml
+++ b/.github/workflows/BuildWebSocket.yml
@@ -103,7 +103,7 @@ jobs:
}
} @Parameters
- name: PublishTestResults
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@main
with:
name: PesterResults
path: '**.TestResults.xml'
diff --git a/Build/GitHub/Steps/PublishTestResults.psd1 b/Build/GitHub/Steps/PublishTestResults.psd1
new file mode 100644
index 0000000..e8111e8
--- /dev/null
+++ b/Build/GitHub/Steps/PublishTestResults.psd1
@@ -0,0 +1,10 @@
+@{
+ name = 'PublishTestResults'
+ uses = 'actions/upload-artifact@main'
+ with = @{
+ name = 'PesterResults'
+ path = '**.TestResults.xml'
+ }
+ if = '${{always()}}'
+}
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0eacffa..5403c61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,41 @@
> Like It? [Star It](https://github.com/PowerShellWeb/WebSocket)
> Love It? [Support It](https://github.com/sponsors/StartAutomating)
+## WebSocket 0.1.3
+
+WebSocket server support!
+
+### Server Features
+
+For consistency, capabilities, and aesthetics,
+this is a fairly fully features HTTP server that happens to support websockets
+
+* `Get-WebSocket` `-RootURL/-HostHeader` ( #47 )
+* `-StyleSheet` lets you include stylesheets ( #64 )
+* `-JavaScript` lets you include javascript ( #65 )
+* `-Timeout/-LifeSpan` server support ( #85 )
+
+### Client Improvements
+
+* `Get-WebSocket -QueryParameter` lets you specify query parameters ( #41 )
+* `Get-WebSocket -Debug` lets you debug the websocketjob. ( #45 )
+* `Get-WebSocket -SubProtocol` lets you specify a subprotocol (defaults to JSON) ( #46 )
+* `Get-WebSocket -Authenticate` allows sends pre-connection authentication ( #69 )
+* `Get-WebSocket -Handshake` allows post-connection authentication ( #81 )
+* `Get-WebSocket -Force` allows the creation of multiple clients ( #58 )
+
+
+### General Improvements
+
+* `Get-WebSocket -SupportsPaging` ( #55 )
+* `Get-WebSocket -BufferSize 64kb` ( #52 )
+* `Get-WebSocket -Force` ( #58 )
+* `Get-WebSocket -Filter` ( #42 )
+* `Get-WebSocket -ForwardEvent` ( #56 )
+* `Get-WebSocket` Parameter Sets ( #73, #74 )
+* `-Broadcast` lets you broadcast to clients and servers ( #39 )
+* `Get-WebSocket` quieting previous job check ( #43 )
+
## WebSocket 0.1.2
* WebSocket now decorates (#34)
diff --git a/Commands/Get-WebSocket.ps1 b/Commands/Get-WebSocket.ps1
index a2635c8..8216fd9 100644
--- a/Commands/Get-WebSocket.ps1
+++ b/Commands/Get-WebSocket.ps1
@@ -8,17 +8,26 @@ function Get-WebSocket {
This will create a job that connects to a WebSocket and outputs the results.
If the `-Watch` parameter is provided, will output a continous stream of objects.
+ .LINK
+ https://websocket.powershellweb.com/Get-WebSocket/
+ .LINK
+ https://learn.microsoft.com/en-us/dotnet/api/system.net.websockets.clientwebsocket?wt.mc_id=MVP_321542
+ .LINK
+ https://learn.microsoft.com/en-us/dotnet/api/system.net.httplistener?wt.mc_id=MVP_321542
.EXAMPLE
# Create a WebSocket job that connects to a WebSocket and outputs the results.
- Get-WebSocket -WebSocketUri "wss://localhost:9669/"
+ $socketServer = Get-WebSocket -RootUrl "http://localhost:8387/" -HTML "
WebSocket Server
"
+ $socketClient = Get-WebSocket -SocketUrl "ws://localhost:8387/"
+ foreach ($n in 1..10) { $socketServer.Send(@{n=Get-Random}) }
+ $socketClient | Receive-Job -Keep
.EXAMPLE
# Get is the default verb, so we can just say WebSocket.
# `-Watch` will output a continous stream of objects from the websocket.
- # For example, let's Watch BlueSky, but just the text.
- websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -Watch |
+ # For example, let's Watch BlueSky, but just the text
+ websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -Watch -Maximum 1kb |
% {
$_.commit.record.text
- }
+ }
.EXAMPLE
# Watch BlueSky, but just the text and spacing
$blueSkySocketUrl = "wss://jetstream2.us-$(
@@ -27,12 +36,19 @@ function Get-WebSocket {
"wantedCollections=app.bsky.feed.post"
) -join '&')"
websocket $blueSkySocketUrl -Watch |
- % { Write-Host "$(' ' * (Get-Random -Max 10))$($_.commit.record.text)$($(' ' * (Get-Random -Max 10)))"}
- .EXAMPLE
+ % { Write-Host "$(' ' * (Get-Random -Max 10))$($_.commit.record.text)$($(' ' * (Get-Random -Max 10)))"} -Max 1kb
+ .EXAMPLE
+ # Watch continuously in a background job.
websocket wss://jetstream2.us-east.bsky.network/subscribe?wantedCollections=app.bsky.feed.post
+ .EXAMPLE
+ # Watch the first message in -Debug mode.
+ # This allows you to literally debug the WebSocket messages as they are encountered.
+ websocket wss://jetstream2.us-west.bsky.network/subscribe -QueryParameter @{
+ wantedCollections = 'app.bsky.feed.post'
+ } -Max 1 -Debug
.EXAMPLE
# Watch BlueSky, but just the emoji
- websocket jetstream2.us-east.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -Tail |
+ websocket jetstream2.us-east.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -Tail -Max 1kb |
Foreach-Object {
$in = $_
if ($in.commit.record.text -match '[\p{IsHighSurrogates}\p{IsLowSurrogates}]+') {
@@ -60,11 +76,13 @@ function Get-WebSocket {
}
.EXAMPLE
# BlueSky, but just the hashtags
- websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -WatchFor @{
+ websocket wss://jetstream2.us-west.bsky.network/subscribe -QueryParameter @{
+ wantedCollections = 'app.bsky.feed.post'
+ } -WatchFor @{
{$webSocketoutput.commit.record.text -match "\#\w+"}={
$matches.0
}
- }
+ } -Maximum 1kb
.EXAMPLE
# BlueSky, but just the hashtags (as links)
websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -WatchFor @{
@@ -104,24 +122,112 @@ function Get-WebSocket {
Sort Count -Descending |
Select -First 10
#>
- [CmdletBinding(PositionalBinding=$false)]
- [Alias('WebSocket')]
+ [CmdletBinding(
+ PositionalBinding=$false,
+ SupportsPaging,
+ DefaultParameterSetName='WebSocketClient'
+ )]
+ [Alias('WebSocket','ws','wss')]
param(
- # The Uri of the WebSocket to connect to.
- [Parameter(Position=0,ValueFromPipelineByPropertyName)]
- [Alias('Url','Uri')]
- [uri]$WebSocketUri,
+ # The WebSocket Uri.
+ [Parameter(Position=0,ParameterSetName='WebSocketClient',ValueFromPipelineByPropertyName)]
+ [Alias('Url','Uri','WebSocketUri','WebSocketUrl')]
+ [uri]
+ $SocketUrl,
+
+ # One or more root urls.
+ # If these are provided, a WebSocket server will be created with these listener prefixes.
+ [Parameter(Mandatory,ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('HostHeader','Host','CNAME','ListenerPrefix','ListenerPrefixes','ListenerUrl')]
+ [string[]]
+ $RootUrl,
+
+ # A route table for all requests.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('Routes','RouteTable','WebHook','WebHooks')]
+ [Collections.IDictionary]
+ $Route,
+
+ # The Default HTML.
+ # This will be displayed when visiting the root url.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('DefaultHTML','Home','Index','IndexHTML','DefaultPage')]
+ [string]
+ $HTML,
+
+ # The name of the palette to use. This will include the [4bitcss](https://4bitcss.com) stylesheet.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('Palette','ColorScheme','ColorPalette')]
+ [ArgumentCompleter({
+ param ($commandName,$parameterName,$wordToComplete,$commandAst,$fakeBoundParameters )
+ if (-not $script:4bitcssPaletteList) {
+ $script:4bitcssPaletteList = Invoke-RestMethod -Uri https://cdn.jsdelivr.net/gh/2bitdesigns/4bitcss@latest/docs/Palette-List.json
+ }
+ if ($wordToComplete) {
+ $script:4bitcssPaletteList -match "$([Regex]::Escape($wordToComplete) -replace '\\\*', '.{0,}')"
+ } else {
+ $script:4bitcssPaletteList
+ }
+ })]
+ [string]
+ $PaletteName,
- # A ScriptBlock that will handle the output of the WebSocket.
+ # The [Google Font](https://fonts.google.com/) name.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('FontName')]
+ [string]
+ $GoogleFont,
+
+ # The Google Font name to use for code blocks.
+ # (this should be a [monospace font](https://fonts.google.com/?classification=Monospace))
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('PreFont','CodeFontName','PreFontName')]
+ [string]
+ $CodeFont,
+
+ # A list of javascript files or urls to include in the content.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [string[]]
+ $JavaScript,
+
+ # A javascript import map. This allows you to import javascript modules.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketServer')]
+ [Alias('ImportsJavaScript','JavaScriptImports','JavaScriptImportMap')]
+ [Collections.IDictionary]
+ $ImportMap,
+
+ # A collection of query parameters.
+ # These will be appended onto the `-SocketUrl`.
+ # Multiple values for a single parameter will be passed as multiple parameters.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
+ [Alias('QueryParameters','Query')]
+ [Collections.IDictionary]
+ $QueryParameter,
+
+ # A ScriptBlock that can handle the output of the WebSocket or the Http Request.
+ # This may be run in a separate `-Runspace` or `-RunspacePool`.
+ # The output of the WebSocket or the Context will be passed as an object.
[ScriptBlock]
$Handler,
+ # If set, will forward websocket messages as events.
+ # Only events that match -Filter will be forwarded.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
+ [Alias('Forward')]
+ [switch]
+ $ForwardEvent,
+
# Any variables to declare in the WebSocket job.
# These variables will also be added to the job as properties.
- [Collections.IDictionary]
+ [Collections.IDictionary]
$Variable = @{},
- # The name of the WebSocket job.
+ # Any Http Headers to include in the WebSocket request or server response.
+ [Collections.IDictionary]
+ [Alias('Headers')]
+ $Header,
+
+ # The name of the WebSocket job.
[string]
$Name,
@@ -130,51 +236,109 @@ function Get-WebSocket {
$InitializationScript = {},
# The buffer size. Defaults to 16kb.
+ [Parameter(ValueFromPipelineByPropertyName)]
[int]
- $BufferSize = 16kb,
+ $BufferSize = 64kb,
+
+ # If provided, will send an object.
+ # If this is a scriptblock, it will be run and the output will be sent.
+ [Alias('Send')]
+ [PSObject]
+ $Broadcast,
# The ScriptBlock to run after connection to a websocket.
# This can be useful for making any initial requests.
+ [Parameter(ParameterSetName='WebSocketClient')]
[ScriptBlock]
$OnConnect,
# The ScriptBlock to run when an error occurs.
+ [Parameter(ParameterSetName='WebSocketClient')]
[ScriptBlock]
$OnError,
# The ScriptBlock to run when the WebSocket job outputs an object.
+ [Parameter(ParameterSetName='WebSocketClient')]
[ScriptBlock]
$OnOutput,
# The Scriptblock to run when the WebSocket job produces a warning.
+ [Parameter(ParameterSetName='WebSocketClient')]
[ScriptBlock]
$OnWarning,
+ # If provided, will authenticate the WebSocket.
+ # Many websockets require an initial authentication handshake
+ # after an initial message is received.
+ # This parameter can be either a ScriptBlock or any other object.
+ # If it is a ScriptBlock, it will be run with the output of the WebSocket passed as the first argument.
+ # This will run after the socket is connected but before any messages are received.
+ [Parameter(ParameterSetName='WebSocketClient')]
+ [Alias('Authorize','HelloMessage')]
+ [PSObject]
+ $Authenticate,
+
+ # If provided, will shake hands after the first websocket message is received.
+ # This parameter can be either a ScriptBlock or any other object.
+ # If it is a ScriptBlock, it will be run with the output of the WebSocket passed as the first argument.
+ # This will run after the socket is connected and the first message is received.
+ [Parameter(ParameterSetName='WebSocketClient')]
+ [Alias('Identify')]
+ [PSObject]
+ $Handshake,
+
# If set, will watch the output of the WebSocket job, outputting results continuously instead of outputting a websocket job.
+ [Parameter(ParameterSetName='WebSocketClient')]
[Alias('Tail')]
[switch]
$Watch,
# If set, will output the raw text that comes out of the WebSocket.
+ [Parameter(ParameterSetName='WebSocketClient')]
[Alias('Raw')]
[switch]
$RawText,
# If set, will output the raw bytes that come out of the WebSocket.
+ [Parameter(ParameterSetName='WebSocketClient')]
[Alias('RawByte','RawBytes','Bytes','Byte')]
[switch]
- $Binary,
+ $Binary,
+
+ # If set, will force a new job to be created, rather than reusing an existing job.
+ [switch]
+ $Force,
+
+ # The subprotocol used by the websocket. If not provided, this will default to `json`.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
+ [string]
+ $SubProtocol,
+
+ # If set, will not set a subprotocol. This will only work with certain websocket servers, but will not work with an HTTP Listener WebSocket.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
+ [switch]
+ $NoSubProtocol,
+
+ # One or more filters to apply to the output of the WebSocket.
+ # These can be strings, regexes, scriptblocks, or commands.
+ # If they are strings or regexes, they will be applied to the raw text.
+ # If they are scriptblocks, they will be applied to the deserialized JSON.
+ # These filters will be run within the WebSocket job.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
+ [PSObject[]]
+ $Filter,
# If set, will watch the output of a WebSocket job for one or more conditions.
# The conditions are the keys of the dictionary, and can be a regex, a string, or a scriptblock.
# The values of the dictionary are what will happen when a match is found.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
[ValidateScript({
$keys = $_.Keys
$values = $_.values
foreach ($key in $keys) {
if ($key -isnot [scriptblock]) {
- throw "Keys '$key' must be a scriptblock"
- }
+ throw "Key '$key' must be a scriptblock"
+ }
}
foreach ($value in $values) {
if ($value -isnot [scriptblock] -and $value -isnot [string]) {
@@ -187,145 +351,935 @@ function Get-WebSocket {
[Collections.IDictionary]
$WatchFor,
- # The timeout for the WebSocket connection. If this is provided, after the timeout elapsed, the WebSocket will be closed.
+ # The timeout for the WebSocket connection.
+ # If this is provided, after the timeout elapsed, the WebSocket will be closed.
+ [Parameter(ValueFromPipelineByPropertyName)]
+ [Alias('Lifespan')]
[TimeSpan]
$TimeOut,
# If provided, will decorate the objects outputted from a websocket job.
# This will only decorate objects converted from JSON.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
[Alias('PSTypeNames','Decorate','Decoration')]
[string[]]
$PSTypeName,
# The maximum number of messages to receive before closing the WebSocket.
+ [Parameter(ValueFromPipelineByPropertyName)]
[long]
$Maximum,
+ # The throttle limit used when creating background jobs.
+ [Parameter(ValueFromPipelineByPropertyName)]
+ [int]
+ $ThrottleLimit = 64,
+
# The maximum time to wait for a connection to be established.
- # By default, this is 7 seconds.
+ # By default, this is 7 seconds.
+ [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='WebSocketClient')]
[TimeSpan]
$ConnectionTimeout = '00:00:07',
# The Runspace where the handler should run.
# Runspaces allow you to limit the scope of the handler.
+ [Parameter(ValueFromPipelineByPropertyName)]
[Runspace]
$Runspace,
# The RunspacePool where the handler should run.
# RunspacePools allow you to limit the scope of the handler to a pool of runspaces.
+ [Parameter(ValueFromPipelineByPropertyName)]
[Management.Automation.Runspaces.RunspacePool]
[Alias('Pool')]
$RunspacePool
)
begin {
- $SocketJob = {
- param([Collections.IDictionary]$Variable)
+ $SocketClientJob = {
+ param(
+ # By accepting a single parameter containing variables,
+ # we can avoid the need to pass in a large number of parameters.
+ # we can also modify this dictionary, to provide a way to pass information back.
+ [Collections.IDictionary]$Variable
+ )
+ $Variable.JobRunspace = [Runspace]::DefaultRunspace
+
+ # Take every every `-Variable` passed in and define it within the job
foreach ($keyValue in $variable.GetEnumerator()) {
$ExecutionContext.SessionState.PSVariable.Set($keyValue.Key, $keyValue.Value)
- }
+ }
- if ((-not $WebSocketUri) -or $webSocket) {
- throw "No WebSocketUri"
+ # If we have no socket url,
+ if ((-not $SocketUrl)) {
+ # throw up an error.
+ throw "No SocketUrl"
}
- if (-not $WebSocketUri.Scheme) {
- $WebSocketUri = [uri]"wss://$WebSocketUri"
- }
+ # If the socket url does not have a scheme
+ if (-not $SocketUrl.Scheme) {
+ # assume `wss`
+ $SocketUrl = [uri]"wss://$SocketUrl"
+ } elseif (
+ # otherwise, if the scheme is http or https
+ $SocketUrl.Scheme -match '^https?'
+ ) {
+ # replace it with `ws` or `wss`
+ $SocketUrl = $SocketUrl -replace '^http', 'ws'
+ }
+
+ # If any query parameters were provided
+ if ($QueryParameter) {
+ # add them to the socket url
+ $SocketUrl = [uri]"$($SocketUrl)$($SocketUrl.Query ? '&' : '?')$(@(
+ foreach ($keyValuePair in $QueryParameter.GetEnumerator()) {
+ # cannocially, each key value pair should be url encoded,
+ # and multiple values should be passed multiple times.
+ foreach ($value in $keyValuePair.Value) {
+ $valueString =
+ # If the value is a boolean or a switch,
+ if ($value -is [bool] -or $value -is [switch]) {
+ # convert it to a string and make it lowercase.
+ ($value -as [bool] -as [string]).ToLower()
+ } else {
+ # Otherwise, just stringify.
+ "$value"
+ }
+ "$($keyValuePair.Key)=$([Web.HttpUtility]::UrlEncode($valueString).Replace('+', '%20'))"
+ }
+ }) -join '&')"
+ }
+ # If we had not set a -BufferSize,
if (-not $BufferSize) {
- $BufferSize = 16kb
+ $BufferSize = 64kb # default to 64kb.
}
+ # Create a cancellation token, as this will save syntax space
$CT = [Threading.CancellationToken]::None
- if (-not $webSocket) {
+ # If `$WebSocket `is not already a websocket
+ if ($webSocket -isnot [Net.WebSockets.ClientWebSocket]) {
+ # create a new socket
$ws = [Net.WebSockets.ClientWebSocket]::new()
- $null = $ws.ConnectAsync($WebSocketUri, $CT).Wait()
+ if ($SubProtocol) {
+ # and add the subprotocol
+ $ws.Options.AddSubProtocol($SubProtocol)
+ } elseif (-not $NoSubProtocol) {
+ $ws.Options.AddSubProtocol('json')
+ }
+ # If there are headers
+ if ($Header) {
+ # add them to the initial socket request.
+ foreach ($headerKeyValue in $header.GetEnumerator()) {
+ $ws.Options.SetRequestHeader($headerKeyValue.Key, $headerKeyValue.Value)
+ }
+ }
+ # Now, let's try to connect to the WebSocket.
+ $null = $ws.ConnectAsync($SocketUrl, $CT).Wait()
} else {
$ws = $WebSocket
- }
+ }
+ # Keep track of the time
$webSocketStartTime = $Variable.WebSocketStartTime = [DateTime]::Now
+ # and add the WebSocket to the variable dictionary, so we can access it later.
$Variable.WebSocket = $ws
- $MessageCount = [long]0
-
- while ($true) {
- if ($ws.State -ne 'Open') {break }
+ # Initialize some counters:
+ $MessageCount = [long]0 # * The number of messages received
+ $FilteredCount = [long]0 # * The number of messages filtered out
+ $SkipCount = [long]0 # * The number of messages skipped
+
+ # Initialize variables related to handshaking
+ $saidHello = $null # * Whether we have said hello
+ $shookHands = $null # * Whether we have shaken hands
+
+ # This loop will run as long as the websocket is open.
+ :WebSocketMessageLoop while ($ws.State -eq 'Open') {
+ # If we've given a timeout for the websocket,
+ # and the websocket has been open for longer than the timeout,
if ($TimeOut -and ([DateTime]::Now - $webSocketStartTime) -gt $TimeOut) {
+ # then it's closing time (you don't have to go home but you can't stay here).
$ws.CloseAsync([Net.WebSockets.WebSocketCloseStatus]::NormalClosure, 'Timeout', $CT).Wait()
break
}
- if ($Maximum -and $MessageCount -ge $Maximum) {
+ # If we've gotten the maximum number of messages,
+ if ($Maximum -and (
+ ($MessageCount - $FilteredCount) -ge $Maximum
+ )) {
+ # then I can't even take any more responses.
$ws.CloseAsync([Net.WebSockets.WebSocketCloseStatus]::NormalClosure, 'Maximum messages reached', $CT).Wait()
break
}
+ # If we're authenticating, and haven't yet said hello
+ if ($Authenticate -and -not $SaidHello) {
+ # then we should say hello.
+ # Determine the authentication message
+ $authenticationMessage =
+ # If the authentication message is a scriptblock,
+ if ($Authenticate -is [ScriptBlock]) {
+ & $Authenticate # run it
+ } else {
+ $authenticate # otherwise, use it as-is.
+ }
+
+ # If we have an authentication message
+ if ($authenticationMessage) {
+ # and it's not a string
+ if ($authenticationMessage -isnot [string]) {
+ # then we should send it as JSON and mark that we've said hello.
+ $saidHello = $ws.SendAsync([ArraySegment[byte]]::new(
+ $OutputEncoding.GetBytes((ConvertTo-Json -InputObject $authenticationMessage -Depth 10))
+ ), 'Text', $true, $CT)
+ }
+ }
+ }
+
+ # Ok, let's get the next message.
$Buf = [byte[]]::new($BufferSize)
$Seg = [ArraySegment[byte]]::new($Buf)
- $null = $ws.ReceiveAsync($Seg, $CT).Wait()
+ $receivingWebSocket = $ws.ReceiveAsync($Seg, $CT)
+ # use this tight loop to let us cancel the await if we need to.
+ while (-not ($receivingWebSocket.IsCompleted -or $receivingWebSocket.IsFaulted -or $receivingWebSocket.IsCanceled)) {
+
+ }
+ # If we had a problem, write an error.
+ if ($receivingWebSocket.Exception) {
+ Write-Error -Exception $receivingWebSocket.Exception -Category ProtocolError
+ continue
+ }
$MessageCount++
try {
+ # If we have a handshake and we haven't yet shaken hands
+ if ($Handshake -and -not $shookHands) {
+ # then we should shake hands.
+ # Get the message string
+ $messageString = $OutputEncoding.GetString($Buf, 0, $Buf.Count)
+ # and try to convert it from JSON.
+ $messageObject = ConvertFrom-Json -InputObject $messageString *>&1
+ # Determine the handshake message
+ $handShakeMessage =
+ # If the handshake message is a scriptblock,
+ if ($Handshake -is [ScriptBlock]) {
+ & $Handshake $MessageObject # run it and pass the message
+ } else {
+ $Handshake # otherwise, use it as-is.
+ }
+
+ # If we have a handshake message
+ if ($handShakeMessage) {
+ # and it's not a string
+ if ($handShakeMessage -isnot [string]) {
+ # then we should send it as JSON and mark that we've shaken hands.
+ $saidHello = $ws.SendAsync([ArraySegment[byte]]::new(
+ $OutputEncoding.GetBytes((ConvertTo-Json -InputObject $handShakeMessage -Depth 10))
+ ), 'Text', $true, $CT)
+ }
+ }
+ }
+
+ # Get the message from the websocket
$webSocketMessage =
- if ($Binary) {
- $Buf -gt 0
- } elseif ($RawText) {
- $OutputEncoding.GetString($Buf, 0, $Buf.Count)
+ if ($Binary) { # If we wanted binary
+ $Buf -gt 0 -as [byte[]] # then return non-null bytes
} else {
- $JS = $OutputEncoding.GetString($Buf, 0, $Buf.Count)
- if ([string]::IsNullOrWhitespace($JS)) { continue }
- ConvertFrom-Json $JS
+ # otherwise, get the message as a string
+ $messageString = $OutputEncoding.GetString($Buf, 0, $Buf.Count)
+ # if we have any filters
+ if ($Filter) {
+ # then we see if we can apply them now.
+ foreach ($fil in $filter) {
+ # Wilcard filters can be applied to the raw text
+ if ($fil -is [string] -and $messageString -like "*$fil*") {
+ $FilteredCount++
+ continue WebSocketMessageLoop
+ }
+ # and so can regex filters.
+ if ($fil -is [regex] -and $fil.IsMatch($messageString)) {
+ $FilteredCount++
+ continue WebSocketMessageLoop
+ }
+ }
+ }
+ # If we have asked for -RawText
+ if ($RawText) {
+ $messageString # then return the raw text
+ } else {
+ # Otherwise, try to convert the message from JSON.
+ $MessageObject = ConvertFrom-Json -InputObject $messageString
+
+ # Now we can run any filters that are scriptblocks or commands.
+ if ($filter) {
+ foreach ($fil in $Filter) {
+ if ($fil -is [ScriptBlock] -or
+ $fil -is [Management.Automation.CommandInfo]
+ ) {
+ # Capture the output of the filter
+ $filterOutput = $MessageObject | & $fil $MessageObject
+ # if the output was falsy,
+ if (-not $filterOutput) {
+ $FilteredCount++ # filter out the message.
+ continue WebSocketMessageLoop
+ }
+ }
+ }
+ }
+
+ # If -Skip was provided and we haven't skipped enough messages
+ if ($Skip -and ($SkipCount -le $Skip)) {
+ # then skip this message.
+ $SkipCount++
+ continue WebSocketMessageLoop
+ }
+
+ # Now, emit the message object.
+ # (expressions that are not assigned will be outputted)
+ $MessageObject
+
+ # If we have a -First parameter, and we have not yet reached the maximum
+ # (after accounting for skips and filters)
+ if ($First -and ($MessageCount - $FilteredCount - $SkipCount) -ge $First) {
+ # then set the maximum to first (which will cancel this after the next loop)
+ $Maximum = $first
+ }
+ }
}
+
+ # If we want to decorate the output
if ($PSTypeName) {
+ # clear it's typenames
$webSocketMessage.pstypenames.clear()
- [Array]::Reverse($PSTypeName)
- foreach ($psType in $psTypeName) {
- $webSocketMessage.pstypenames.add($psType)
- }
+ for ($typeNameIndex = $PSTypeName.Length - 1; $typeNameIndex -ge 0; $typeNameIndex--) {
+ # and add each type name in reverse order
+ $webSocketMessage.pstypenames.add($PSTypeName[$typeNameIndex])
+ }
}
- if ($handler) {
- $psCmd =
+
+ # If we are forwarding events
+ if ($ForwardEvent -and $MainRunspace.Events.GenerateEvent) {
+ # generate an event in the main runspace
+ $null = $MainRunspace.Events.GenerateEvent(
+ "$SocketUrl",
+ $ws,
+ @($webSocketMessage),
+ $webSocketMessage
+ )
+ }
+
+ # If we have an output handler, try to run it and get the output
+ $handledResponse = if ($handler) {
+ # We may need to run the handler in a `[PowerShell]` command.
+ $psCmd =
+ # This is true if we want `NoLanguage` mode.
if ($runspace.LanguageMode -eq 'NoLanguage' -or
$runspacePool.InitialSessionState.LanguageMode -eq 'NoLanguage') {
+ # (in which case we'll call .GetPowerShell())
$handler.GetPowerShell()
- } elseif ($Runspace -or $RunspacePool) {
- [PowerShell]::Create().AddScript($handler)
+ } elseif (
+ # or if we have a runspace or runspace pool
+ $Runspace -or $RunspacePool
+ ) {
+ # (in which case we'll `.Create()` and `.AddScript()`)
+ [PowerShell]::Create().AddScript($handler, $true)
}
if ($psCmd) {
+ # If we have a runspace, we'll use that.
if ($Runspace) {
$psCmd.Runspace = $Runspace
} elseif ($RunspacePool) {
+ # or, alternatively, we can use a runspace pool.
$psCmd.RunspacePool = $RunspacePool
}
+ # Now, we can invoke the command.
+ $psCmd.Invoke(@($webSocketMessage))
} else {
+ # Otherwise, we'll just run the handler.
$webSocketMessage | . $handler
}
-
+ }
+
+ # If we have a response from the handler,
+ if ($handledResponse) {
+ $handledResponse # emit that response.
} else {
- $webSocketMessage
+ $webSocketMessage # otherwise, emit the message.
}
} catch {
Write-Error $_
}
}
- }
+
+ # Now that the socket is closed,
+ # check for a status description.
+ # If there is one,
+ if ($ws.CloseStatusDescription) {
+ # write an error.
+ Write-Error $ws.CloseStatusDescription -TargetObject $ws
+ }
+ }
+ $SocketServerJob = {
+ <#
+ .SYNOPSIS
+ A fairly simple WebSocket server
+ .DESCRIPTION
+ A fairly simple WebSocket server
+ #>
+ param(
+ # By accepting a single parameter containing variables,
+ # we can avoid the need to pass in a large number of parameters.
+ # we can also modify this dictionary, to provide a way to pass information back.
+ [Collections.IDictionary]$Variable
+ )
+
+ # Take every every `-Variable` passed in and define it within the job
+ foreach ($keyValue in $variable.GetEnumerator()) {
+ $ExecutionContext.SessionState.PSVariable.Set($keyValue.Key, $keyValue.Value)
+ }
+
+ $Variable['JobRunspace'] = [Runspace]::DefaultRunspace
+
+ # If we have routes, we will cache all of their possible parameters now
+ if ($route.Count) {
+ # We want to keep the parameter sets
+ $routeParameterSets = [Ordered]@{}
+ # and the metadata about parameters.
+ $routeParameters = [Ordered]@{}
+
+ # For each key and value in the route table, we will try to get the command info for the value.
+ foreach ($routePair in $route.GetEnumerator()) {
+ $routeToCmd =
+ # If the value is a scriptblock
+ if ($routePair.Value -is [ScriptBlock]) {
+ # we have to create a temporary function
+ $function:TempFunction = $routePair.Value
+ # and get that function.
+ $ExecutionContext.SessionState.InvokeCommand.GetCommand('TempFunction', 'Function')
+ } elseif ($routePair.Value -is [Management.Automation.CommandInfo]) {
+ $routePair.Value
+ }
+ if ($routeToCmd) {
+ $routeParameterSets[$routePair.Name] = $routeToCmd.ParametersSets
+ $routeParameters[$routePair.Name] = $routeToCmd.Parameters
+ }
+ }
+ }
+
+ # If there's no listener, create one.
+ if (-not $httpListener) {
+ $httpListener = $variable['HttpListener'] = [Net.HttpListener]::new()
+ }
+
+ # If the listener doesn't have a lookup table for SocketRequests, create one.
+ if (-not $httpListener.SocketRequests) {
+ $httpListener.psobject.properties.add(
+ [psnoteproperty]::new('SocketRequests', [Ordered]@{}), $true)
+ }
+
+ # If the listener isn't listening, start it.
+ if (-not $httpListener.IsListening) { $httpListener.Start() }
+
+ $variable['SiteHeader'] = $siteHeader = @(
+
+ if ($Javascript) {
+ # as well as any javascript files provided.
+ foreach ($js in $Javascript) {
+ if ($js -match '.js$') {
+ ""
+ } else {
+ ""
+ }
+ }
+ }
+
+ # If an import map was provided, we will include it.
+ if ($ImportMap) {
+ $variable['ImportMap'] = @(
+ ""
+ ) -join [Environment]::NewLine
+ }
+
+ # If a palette name was provided, we will include the 4bitcss stylesheet.
+ if ($PaletteName) {
+ if ($PaletteName -match '/.+?\.css$') {
+ ""
+
+ } else {
+ '' -replace '\.css', "$PaletteName.css"
+ }
+ }
+
+ # If a font name was provided, we will include the font stylesheet.
+ if ($GoogleFont) {
+ ""
+ ""
+ }
+
+ # If a code font was provided, we will include the code font stylesheet.
+ if ($CodeFont) {
+ ""
+ ""
+ }
+
+ # and if any stylesheets were provided, we will include them.
+ foreach ($css in $variable.StyleSheet) {
+ if ($css -match '.css$') {
+ ""
+ } else {
+ ""
+ }
+ }
+ )
+
+ $httpListener.psobject.properties.add([psnoteproperty]::new('JobVariable',$Variable), $true)
+ $listenerStartTime = [DateTime]::Now
+
+ # While the listener is listening,
+ while ($httpListener.IsListening) {
+ # If we've given a timeout for the listener,
+ # and the listener has been open for longer than the timeout,
+ if ($Timeout -and ([DateTime]::Now - $listenerStartTime) -gt $TimeOut) {
+ # then it's closing time (you don't have to go home but you can't stay here).
+ $httpListener.Stop()
+ break
+ }
+ # get the context asynchronously.
+ $contextAsync = $httpListener.GetContextAsync()
+ # and wait for it to complete.
+ while (-not ($contextAsync.IsCompleted -or $contextAsync.IsFaulted -or $contextAsync.IsCanceled)) {
+ # while this is going on, other events can be processed, and CTRL-C can exit.
+ # also, we can go ahead and check for any socket requests, and get ready for the next one if we find one.
+ foreach ($socketRequest in @($httpListener.SocketRequests.GetEnumerator())) {
+ if ($socketRequest.Value.Receiving.IsCompleted) {
+ $socketRequest.Value.MessageCount++
+ $jsonMessage = ConvertFrom-Json -InputObject ($OutputEncoding.GetString($socketRequest.Value.ClientBuffer -gt 0))
+ $socketRequest.Value.ClientBuffer.Clear()
+ if ($MainRunspace.Events.GenerateEvent) {
+ $MainRunspace.Events.GenerateEvent.Invoke(@(
+ "$($request.Url.Scheme -replace '^http', 'ws')://",
+ $httpListener,
+ @($socketRequest.Value.Context, $socketRequest.Value.WebSocketContet, $socketRequest.Key, $socketRequest.Value),
+ $jsonMessage
+ ))
+ }
+ $socketRequest.Value.Receiving =
+ $socketRequest.Value.WebSocket.ReceiveAsync($socketRequest.Value.ClientBuffer, [Threading.CancellationToken]::None)
+ }
+ }
+ }
+ # If async method fails,
+ if ($contextAsync.IsFaulted) {
+ # write an error and continue.
+ Write-Error -Exception $contextAsync.Exception -Category ProtocolError
+ continue
+ }
+ # Get the context async result.
+ # The context is basically the next request and response in the queue.
+ $context = $(try { $contextAsync.Result } catch { $_ })
+
+ # yield the context immediately, in case anything is watching the output of this job
+ $context
+
+ $Request, $response = $context.Request, $context.Response
+ $RequestedUrl = $Request.Url
+ # Favicons are literally outdated, but they're still requested.
+ if ($RequestedUrl -match '/favicon.ico$') {
+ # by returning a 404 for them, we can make the browser stop asking.
+ $context.Response.StatusCode = 404
+ $context.Response.Close()
+ continue
+ }
+ # Now, for the fun part.
+ # We turn request into a PowerShell events.
+ # The protocol is the scheme of the request url.
+ $Protocol = $RequestedUrl.Scheme
+ # Each event will have the source identifier of the protocol, followed by ://
+ $eventIdentifier = "$($Protocol)://"
+ # and by default it will pass a message containing the context.
+ $messageData = [Ordered]@{Protocol = $protocol; Url = $context.Request.Url;Context = $context}
+
+ if ($Header -and $response) {
+ foreach ($headerKeyValue in $Header.GetEnumerator()) {
+ try {
+ $response.Headers.Add($headerKeyValue.Key, $headerKeyValue.Value)
+ } catch {
+ Write-Warning "Cannot add header '$($headerKeyValue.Key)': $_"
+ }
+ }
+ }
+
+ # HttpListeners are quite nice, especially when it comes to websocket upgrades.
+ # If the request is a websocket request
+ if ($Request.IsWebSocketRequest) {
+ # we will change the event identifier to a websocket scheme.
+ $eventIdentifier = $eventIdentifier -replace '^http', 'ws'
+ # and call the `AcceptWebSocketAsync` method to upgrade the connection.
+ $acceptWebSocket = $context.AcceptWebSocketAsync('json')
+ # Once again, we'll use a tight loop to wait for the upgrade to complete or fail.
+ while (-not ($acceptWebSocket.IsCompleted -or $acceptWebSocket.IsFaulted -or $acceptWebSocket.IsCanceled)) { }
+ # and if it fails,
+ if ($acceptWebSocket.IsFaulted) {
+ # we will write an error and continue.
+ Write-Error -Exception $acceptWebSocket.Exception -Category ProtocolError
+ continue
+ }
+ # If it succeeds, capture the result.
+ $webSocketResult = try { $acceptWebSocket.Result } catch { $_ }
+
+ # If the websocket is open
+ if ($webSocketResult.WebSocket.State -eq 'open') {
+ # we have switched protocols!
+ $Protocol = $requestedUrl.Scheme -replace '^http', 'ws'
+
+ # Now add the result it to the SocketRequests lookup table, using the request trace identifier as the key.
+ $clientBuffer = $webSocketResult.WebSocket::CreateClientBuffer($BufferSize, $BufferSize)
+ $socketObject = [PSCustomObject][Ordered]@{
+ Context = $context
+ WebSocketContext = $webSocketResult
+ WebSocket = $webSocketResult.WebSocket
+ ClientBuffer = $clientBuffer
+ Created = [DateTime]::UtcNow
+ LastMessageTime = $null
+ Receiving = $webSocketResult.WebSocket.ReceiveAsync($clientBuffer, [Threading.CancellationToken]::None)
+ MessageQueue = [Collections.Queue]::new()
+ MessageCount = [long]0
+ }
+
+ if (-not $httpListener.SocketRequests["$($webSocketResult.RequestUri)"]) {
+ $httpListener.SocketRequests["$($webSocketResult.RequestUri)"] = [Collections.Queue]::new()
+ }
+ $httpListener.SocketRequests["$($webSocketResult.RequestUri)"].Enqueue($socketObject)
+ # and add the websocketcontext result to the message data.
+ $messageData["WebSocketContext"] = $webSocketResult
+ # also add the websocket result to the message data,
+ # since many might not exactly know what a "WebSocketContext" is.
+ $messageData["WebSocket"] = $webSocketResult.WebSocket
+ }
+ }
+
+ # Now, we generate the event.
+ $generateEventArguments = @(
+ $eventIdentifier,
+ $httpListener,
+ @($context)
+ $messageData
+ )
+ # Get a pointer to the GenerateEvent method (we'll want this later)
+ if ($MainRunspace.Events.GenerateEvent) {
+ $MainRunspace.Events.GenerateEvent.Invoke($generateEventArguments)
+ }
+
+ # Everything below this point is for HTTP requests.
+ if ($protocol -notmatch '^http') {
+ continue # so if we're already a websocket, we will skip the rest of this code.
+ }
+
+ $routedTo = $null
+ $routeKey = $null
+ # If we have routes, we will try to find a route that matches the request.
+ if ($route.Count) {
+ $routeTable = $route
+ $potentialRouteKeys = @(
+ $request.Url.AbsolutePath,
+ ($request.Url.AbsolutePath -replace '/$'),
+ "$($request.HttpMethod) $($request.Url.AbsolutePath)",
+ "$($request.HttpMethod) $($request.Url.AbsolutePath -replace '/$')"
+ "$($request.HttpMethod) $($request.Url.LocalPath)",
+ "$($request.HttpMethod) $($request.Url.LocalPath -replace '/$')"
+ )
+ $routedTo = foreach ($potentialKey in $potentialRouteKeys) {
+ if ($routeTable[$potentialKey]) {
+ $routeTable[$potentialKey]
+ $routeKey = $potentialKey
+ break
+ }
+ }
+ }
+
+ if (-not $routedTo -and $handler) {
+ # If we have an output handler, try to run it and get the output
+ $routedTo = if ($handler) {
+ # We may need to run the handler in a `[PowerShell]` command.
+ $psCmd =
+ # This is true if we want `NoLanguage` mode.
+ if ($runspace.LanguageMode -eq 'NoLanguage' -or
+ $runspacePool.InitialSessionState.LanguageMode -eq 'NoLanguage') {
+ # (in which case we'll call .GetPowerShell())
+ $handler.GetPowerShell()
+ } elseif (
+ # or if we have a runspace or runspace pool
+ $Runspace -or $RunspacePool
+ ) {
+ # (in which case we'll `.Create()` and `.AddScript()`)
+ [PowerShell]::Create().AddScript($handler, $true)
+ }
+ if ($psCmd) {
+ # If we have a runspace, we'll use that.
+ if ($Runspace) {
+ $psCmd.Runspace = $Runspace
+ } elseif ($RunspacePool) {
+ # or, alternatively, we can use a runspace pool.
+ $psCmd.RunspacePool = $RunspacePool
+ }
+ # Now, we can invoke the command.
+ $psCmd.Invoke(@($context))
+ } else {
+ # Otherwise, we'll just run the handler.
+ $context | . $handler
+ }
+ }
+ }
+
+ if (-not $routedTo -and $html) {
+ $routedTo =
+ # If the content is already html, we will use it as is.
+ if ($html -match '\"
+ ""
+ # and apply the site header.
+ $SiteHeader -join [Environment]::NewLine
+ ""
+ ""
+ $html
+ ""
+ "