Get-WebSocket.ps1

function Get-WebSocket {
    <#
    .SYNOPSIS
        WebSockets in PowerShell.
    .DESCRIPTION
        Get-WebSocket gets a 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.
        $socketServer = Get-WebSocket -RootUrl "http://localhost:8387/" -HTML "<h1>WebSocket Server</h1>"
        $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 -Maximum 1kb |
            % { 
                $_.commit.record.text
            }
    .EXAMPLE
        # Watch BlueSky, but just the text and spacing
        $blueSkySocketUrl = "wss://jetstream2.us-$(
            'east','west'|Get-Random
        ).bsky.network/subscribe?$(@(
            "wantedCollections=app.bsky.feed.post"
        ) -join '&')"
        websocket $blueSkySocketUrl -Watch | 
            % { 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 -Max 1kb |
            Foreach-Object {
                $in = $_
                if ($in.commit.record.text -match '[\p{IsHighSurrogates}\p{IsLowSurrogates}]+') {
                    Write-Host $matches.0 -NoNewline
                }
            }
    .EXAMPLE
        $emojiPattern = '[\p{IsHighSurrogates}\p{IsLowSurrogates}\p{IsVariationSelectors}\p{IsCombiningHalfMarks}]+)'
        websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -Tail |
            Foreach-Object {
                $in = $_
                $spacing = (' ' * (Get-Random -Minimum 0 -Maximum 7))
                if ($in.commit.record.text -match "(?>(?:$emojiPattern|\#\w+)") {
                    $match = $matches.0                    
                    Write-Host $spacing,$match,$spacing -NoNewline
                }
            }
    .EXAMPLE
        websocket wss://jetstream2.us-east.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -Watch |
            Where-Object {
                $_.commit.record.embed.'$type' -eq 'app.bsky.embed.external'
            } |
            Foreach-Object {
                $_.commit.record.embed.external.uri
            }
    .EXAMPLE
        # BlueSky, but just the hashtags
        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 @{
            {$webSocketoutput.commit.record.text -match "\#\w+"}={
                if ($psStyle.FormatHyperlink) {
                    $psStyle.FormatHyperlink($matches.0, "https://bsky.app/search?q=$([Web.HttpUtility]::UrlEncode($matches.0))")
                } else {
                    $matches.0
                }
            }
        }
    .EXAMPLE
        websocket wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=app.bsky.feed.post -WatchFor @{
            {$args.commit.record.text -match "\#\w+"}={
                $matches.0
            }
            {$args.commit.record.text -match '[\p{IsHighSurrogates}\p{IsLowSurrogates}]+'}={
                $matches.0
            }
        }
    .EXAMPLE
        # We can decorate a type returned from a WebSocket, allowing us to add additional properties.

        # For example, let's add a `Tags` property to the `app.bsky.feed.post` type.
        $typeName = 'app.bsky.feed.post'
        Update-TypeData -TypeName $typeName -MemberName 'Tags' -MemberType ScriptProperty -Value {
            @($this.commit.record.facets.features.tag)
        } -Force
        
        # Now, let's get 10kb posts ( this should not take too long )
        $somePosts =
            websocket "wss://jetstream2.us-west.bsky.network/subscribe?wantedCollections=$typeName" -PSTypeName $typeName -Maximum 10kb -Watch
        $somePosts |
            ? Tags |
            Select -ExpandProperty Tags |
            Group |
            Sort Count -Descending |
            Select -First 10
    #>
    [CmdletBinding(
        PositionalBinding=$false,
        SupportsPaging,
        DefaultParameterSetName='WebSocketClient'
    )]
    [Alias('WebSocket','ws','wss')]
    param(
    # 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,

    # 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]    
    $Variable = @{},

    # 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,

    # The script to run when the WebSocket job starts.
    [ScriptBlock]
    $InitializationScript = {},

    # The buffer size.  Defaults to 16kb.
    [Parameter(ValueFromPipelineByPropertyName)]
    [int]
    $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,    

    # 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 "Key '$key' must be a scriptblock"
            }
        }
        foreach ($value in $values) {
            if ($value -isnot [scriptblock] -and $value -isnot [string]) {
                throw "Value '$value' must be a string or scriptblock"
            }
        }
        return $true
    })]
    [Alias('WhereFor','Wherefore')]
    [Collections.IDictionary]
    $WatchFor,

    # 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.    
    [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 {
        $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 we have no socket url,
            if ((-not $SocketUrl)) {
                # throw up an error.
                throw "No SocketUrl"
            }

            # 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 = 64kb # default to 64kb.
            }

            # Create a cancellation token, as this will save syntax space
            $CT = [Threading.CancellationToken]::None
            
            # If `$WebSocket `is not already a websocket
            if ($webSocket -isnot [Net.WebSockets.ClientWebSocket]) {
                # create a new socket
                $ws = [Net.WebSockets.ClientWebSocket]::new()
                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

            # 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 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)
                $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) { # If we wanted binary
                            $Buf -gt 0 -as [byte[]] # then return non-null bytes
                        } else {
                            # 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()
                        for ($typeNameIndex = $PSTypeName.Length - 1; $typeNameIndex -ge 0; $typeNameIndex--) {
                            # and add each type name in reverse order
                            $webSocketMessage.pstypenames.add($PSTypeName[$typeNameIndex])
                        }                  
                    }

                    # 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 (
                                # 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 # 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$') {
                            "<script src='$javascript'></script>"
                        } else {
                            "<script type='text/javascript'>$js</script>"
                        }
                    }
                }
                    
                # If an import map was provided, we will include it.
                if ($ImportMap) {                
                    $variable['ImportMap'] = @(
                        "<script type='importmap'>"
                        [Ordered]@{
                            imports = $ImportMap
                        } | ConvertTo-Json -Depth 3
                        "</script>"
                    ) -join [Environment]::NewLine
                }

                # If a palette name was provided, we will include the 4bitcss stylesheet.
                if ($PaletteName) {
                    if ($PaletteName -match '/.+?\.css$') {
                        "<link type='text/css' rel='stylesheet' href='$PaletteName' id='4bitcss' />"

                    } else {
                        '<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/gh/2bitdesigns/4bitcss@latest/css/.css" id="4bitcss" />' -replace '\.css', "$PaletteName.css"
                    }            
                }
                
                # If a font name was provided, we will include the font stylesheet.
                if ($GoogleFont) {
                    "<link type='text/css' rel='stylesheet' href='https://fonts.googleapis.com/css?family=$GoogleFont' id='fontname' />"
                    "<style type='text/css'>body { font-family: '$GoogleFont'; }</style>"
                }

                # If a code font was provided, we will include the code font stylesheet.
                if ($CodeFont) {
                    "<link type='text/css' rel='stylesheet' href='https://fonts.googleapis.com/css?family=$CodeFont' id='codefont' />"
                    "<style type='text/css'>pre, code { font-family: '$CodeFont'; }</style>"
                }
                                
                # and if any stylesheets were provided, we will include them.            
                foreach ($css in $variable.StyleSheet) {
                    if ($css -match '.css$') {
                        "<link rel='stylesheet' href='$css' />"
                    } else {
                        "<style type='text/css'>$css</style>"
                    }
                }                            
            )            

            $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 '\<html') {
                            $html
                        } else {
                            # Otherwise, we will wrap it in an html tag.
                            @(
                                "<html>"
                                "<head>"
                                # and apply the site header.
                                $SiteHeader -join [Environment]::NewLine
                                "</head>"
                                "<body>"
                                $html
                                "</body>"
                                "</html>"
                            ) -join [Environment]::NewLine
                    }
                }

                # If we routed to a string, we will close the response with the string.
                if ($routedTo -is [string]) {
                    $response.Close($OutputEncoding.GetBytes($routedTo), $true)
                    continue
                }

                # If we've routed to is a byte array, we will close the response with the byte array.
                if ($routedTo -is [byte[]]) {
                    $response.Close($routedTo, $true)
                    continue
                }                
                    
                # If we routed to a script block or command, we will try to execute it.
                if ($routedTo -is [ScriptBlock] -or 
                    $routedTo -is [Management.Automation.CommandInfo]) {
                    $routeSplat = [Ordered]@{}

                    # If the command had a `-Request` parameter, we will pass the request object.
                    if ($routeParameters -and $routeParameters[$routeKey].Request) {
                        $routeSplat['Request'] = $request
                    }
                    # If the command had a `-Response` parameter, we will pass the response object.
                    if ($routeParameters -and $routeParameters[$routeKey].Response) {
                        $routeSplat['Response'] = $response
                    }

                    # If the request has a query string, we will parse it and pass the values to the command.
                    if ($request.Url.QueryString) {
                        $parsedQuery = [Web.HttpUtility]::ParseQueryString($request.Url.QueryString)
                        foreach ($parsedQueryKey in $parsedQuery.Keys) {
                            if ($routeParameters[$routeKey][$parsedQueryKey]) {
                                $routeSplat[$parsedQueryKey] = $parsedQuery[$parsedQueryKey]
                            }
                        }
                    }
                    # If the request has a content type of json, we will parse the json and pass the values to the command.
                    if ($request.ContentType -match '^(?>application|text)/json') {
                        $streamReader = [IO.StreamReader]::new($request.InputStream)
                        $json = $streamReader.ReadToEnd()
                        $jsonHashtable = ConvertFrom-Json -InputObject $json -AsHashtable
                        foreach ($keyValuePair in $jsonHashtable.GetEnumerator()) {
                            if ($routeParameters[$routeKey][$keyValuePair.Key]) {
                                $routeSplat[$keyValuePair.Key] = $keyValuePair.Value
                            }
                        }
                        $streamReader.Close()
                        $streamReader.Dispose()
                    }

                    # If the request has a content type of form-urlencoded, we will parse the form and pass the values to the command.
                    if ($request.ContentType -eq 'application/x-www-form-urlencoded') {
                        $streamReader = [IO.StreamReader]::new($request.InputStream)
                        $formData = [Web.HttpUtility]::ParseQueryString($streamReader.ReadToEnd())
                        foreach ($formKey in $formData.Keys) {
                            if ($routeParameters[$routeKey][$formKey]) {
                                $routeSplat[$formKey] = $form[$formKey]
                            }
                        }
                        $streamReader.Close()
                        $streamReader.Dispose()
                    }

                    # We will execute the command and get the output.
                    $routeOutput = . $routedTo @routeSplat
                    
                    # If the output is a string, we will close the response with the string.
                    if ($routeOutput -is [string]) 
                    {                        
                        $response.Close($OutputEncoding.GetBytes($routeOutput), $true)
                        continue
                    }
                    # If the output is a byte array, we will close the response with the byte array.
                    elseif ($routeOutput -is [byte[]]) 
                    {
                        $response.Close($routeOutput, $true)
                        continue
                    }
                    # If the response is an array, write the responses out one at a time.
                    # (note: this will likely be changed in the future)
                    elseif ($routeOutput -is [object[]]) {
                        foreach ($routeOut in $routeOutput) {                                
                            if ($routeOut -is [string]) {
                                $routeOut = $OutputEncoding.GetBytes($routeOut)
                            }
                            if ($routeOut -is [byte[]]) {
                                $response.OutputStream.Write($routeOut, 0, $routeOut.Length)
                            }
                        }
                        $response.Close()
                    }
                    else {
                        # If the response was an object, we will convert it to json and close the response with the json.
                        $responseJson = ConvertTo-Json -InputObject $routeOutput -Depth 3
                        $response.ContentType = 'application/json'
                        $response.Close($OutputEncoding.GetBytes($responseJson), $true)
                    }
                }
            }
        }                    
    }

    process {
        # Sometimes we want to customize the behavior of a command based off of the input object
        # So, start off by capturing $_
        $inputObject = $_
        # If the input was a job, we might remap a parameter
        if ($inputObject -is 'Management.Automation.Job') {
            if ($inputObject.WebSocket -is [Net.WebSockets.ClientWebSocket] -and 
                $inputObject.SocketUrl) {
                $SocketUrl = $inputObject.SocketUrl
            }
            if ($inputObject.HttpListener -is [Net.HttpListener] -and 
                $inputObject.RootUrl) {
                $RootUrl = $inputObject.RootUrl
            }
        }
        if ((-not $SocketUrl) -and (-not $RootUrl)) {
            $socketAndListenerJobs =
                foreach ($job in Get-Job) {
                    if (
                        $Job.WebSocket -is [Net.WebSockets.ClientWebSocket] -or 
                        $Job.HttpListener -is [Net.HttpListener]
                    ) {
                        $job
                    }
                }
            $socketAndListenerJobs
        }
        # First, let's pack all of the parameters into a dictionary of variables.
        foreach ($keyValuePair in $PSBoundParameters.GetEnumerator()) {
            $Variable[$keyValuePair.Key] = $keyValuePair.Value
        }
        
        $Variable['MainRunspace'] = [Runspace]::DefaultRunspace
        if (-not $variable['BufferSize']) {
            $variable['BufferSize'] = $BufferSize
        }
        $StartThreadJobSplat = [Ordered]@{
            InitializationScript = $InitializationScript
            ThrottleLimit = $ThrottleLimit
        }

        # If we're going to be listening for HTTP requests, run a thread job for the server.        
        if ($RootUrl) {

            if (-not $Name) {
                $Name = "$($RootUrl -join '|')"
            }

            $existingJob = foreach ($jobWithThisName in (Get-Job -Name $Name -ErrorAction Ignore)) {
                if (
                    $jobWithThisName.State -in 'Running','NotStarted' -and
                    $jobWithThisName.HttpListener -is [Net.HttpListener]
                ) {
                    $jobWithThisName
                    break
                }
            }

            if ((-not $existingJob) -or $Force) {
                $variable['HttpListener'] = $httpListener = [Net.HttpListener]::new()
                foreach ($potentialPrefix in $RootUrl) {
                    if ($potentialPrefix -match '^https?://') {
                        $httpListener.Prefixes.Add($potentialPrefix)
                    } else {
                        $httpListener.Prefixes.Add("http://$potentialPrefix/")
                        $httpListener.Prefixes.Add("https://$potentialPrefix/")
                    }
                }
                $httpListener.Start()
            }            

            if ($DebugPreference -notin 'SilentlyContinue','Ignore') {
                . $SocketServerJob -Variable $Variable
            } else {                
                if ($existingJob -and -not $Force) {
                    $httpListenerJob = $existingJob
                    $httpListener = $existingJob.HttpListener
                } else {
                    $httpListenerJob = Start-ThreadJob -ScriptBlock $SocketServerJob -Name "$RootUrl" -ArgumentList $Variable @StartThreadJobSplat                    
                    $httpListenerJob.pstypenames.insert(0, 'WebSocket.ThreadJob')
                    $httpListenerJob.pstypenames.insert(0, 'WebSocket.Server.ThreadJob')
                }
            }
            
            # If we have a listener job
            if ($httpListenerJob) {
                # and the job has not started
                if ($httpListenerJob.JobStateInfo.State -eq 'NotStarted') {
                    # sleep for no time (this will allow the job to start)
                    Start-Sleep -Milliseconds 0 
                }                
                foreach ($keyValuePair in $Variable.GetEnumerator()) {
                    $httpListenerJob.psobject.properties.add(
                        [psnoteproperty]::new($keyValuePair.Key, $keyValuePair.Value), $true
                    )
                }

                if (-not $Broadcast) {
                    $httpListenerJob
                }
            }            
        }

        # If `-Debug` was passed,
        if ($DebugPreference -notin 'SilentlyContinue','Ignore') {
            # run the job in the current scope (so we can debug it).
            . $SocketClientJob -Variable $Variable
            return
        }

        # If -Debug was not passed, we're running in a background thread job.
        $webSocketJob =
            if ($SocketUrl) {
                # If we had no name, we will use the SocketUrl as the name.
                if (-not $name) {
                    # and we will ensure that it starts with `ws://` or `wss://`
                    $Name = $SocketUrl -replace '^http', 'ws'
                }

                $existingJob = foreach ($jobWithThisName in (Get-Job -Name $Name -ErrorAction Ignore)) {
                    if (
                        $jobWithThisName.State -in 'Running','NotStarted' -and
                        $jobWithThisName.WebSocket -is [Net.WebSockets.ClientWebSocket]
                    ) {
                        $jobWithThisName
                        break
                    }
                }

                if ($existingJob -and -not $Force) {
                    $existingJob
                } else {
                    Start-ThreadJob -ScriptBlock $SocketClientJob -Name $Name -ArgumentList $Variable @StartThreadJobSplat
                }
            }

        $subscriptionSplat = @{
            EventName = 'DataAdded'
            MessageData = $webSocketJob
            SupportEvent = $true
        }
        $eventSubscriptions = @(
            if ($webSocketJob) {
                if ($OnOutput) {
                    Register-ObjectEvent @subscriptionSplat -InputObject $webSocketJob.Output -Action $OnOutput
                }
                if ($OnError) {
                    Register-ObjectEvent @subscriptionSplat -InputObject $webSocketJob.Error -Action $OnError
                }
                if ($OnWarning) {
                    Register-ObjectEvent @subscriptionSplat -InputObject $webSocketJob.Warning -Action $OnWarning
                }
            }            
        )
        if ($eventSubscriptions) {
            $variable['EventSubscriptions'] = $eventSubscriptions
        }

        if ($webSocketJob -and -not $webSocketJob.WebSocket) {            
            $webSocketConnectTimeout = [DateTime]::Now + $ConnectionTimeout
            while (-not $variable['WebSocket'] -and 
                ([DateTime]::Now -lt $webSocketConnectTimeout)) {
                Start-Sleep -Milliseconds 0
            }
            
            foreach ($keyValuePair in $Variable.GetEnumerator()) {                
                $webSocketJob.psobject.properties.add(
                    [psnoteproperty]::new($keyValuePair.Key, $keyValuePair.Value), $true
                )
            }
            $webSocketJob.pstypenames.insert(0, 'WebSocket.ThreadJob')
            $webSocketJob.pstypenames.insert(0, 'WebSocket.Client.ThreadJob')
        }

        # If we're broadcasting a message
        if ($Broadcast) {
            # find out who is listening.
            $socketList = @(
                if ($httpListener.SocketRequests) {
                    @(foreach ($queue in $httpListener.SocketRequests.Values) {
                        foreach ($socket in $queue) {
                            if ($socket.WebSocket.State -eq 'Open') {
                                $socket.WebSocket
                            }                                
                        }
                    })
                }
                if ($webSocketJob.WebSocket) {
                    $webSocketJob.WebSocket
                }
            )

            # If no one is listening, write a warning.
            if (-not $socketList) {
                Write-Warning "No one is listening"
            }

            # If the broadcast is a scriptblock or command, run it.
            if ($Broadcast -is [ScriptBlock] -or 
                $Broadcast -is [Management.Automation.CommandInfo]) {
                $Broadcast = & $Broadcast
            }
            # If the broadcast is a byte array, convert it to an array segment.
            if ($broadcast -is [byte[]]) {
                $broadcast = [ArraySegment[byte]]::new($broadcast)
            }

            # If the broadcast is an array segment, send it as binary.
            if ($broadcast -is [ArraySegment[byte]]) {
                foreach ($socket in $socketList) {
                    $null = $socket.SendAsync($broadcast, 'Binary', 'EndOfMessage', [Threading.CancellationToken]::None)
                }                
            }
            else {
                # Otherwise, convert the broadcast to JSON.
                $broadcastJson = ConvertTo-Json -InputObject $Broadcast
                $broadcastJsonBytes = $OutputEncoding.GetBytes($broadcastJson)
                $broadcastSegment = [ArraySegment[byte]]::new($broadcastJsonBytes)
                foreach ($socket in $socketList) {
                    $null = $socket.SendAsync($broadcastSegment, 'Text', 'EndOfMessage', [Threading.CancellationToken]::None)
                }                
            }
            $Broadcast # emit the broadcast.
        }
        
        if ($Watch -and $webSocketJob) {
            do {
                $webSocketJob | Receive-Job
                Start-Sleep -Milliseconds (
                    7, 11, 13, 17, 19, 23 | Get-Random
                ) 
            } while ($webSocketJob.State -in 'Running','NotStarted')
        } 
        elseif ($WatchFor -and $webSocketJob) {
            . {
                do {                
                    $webSocketJob | Receive-Job
                    Start-Sleep -Milliseconds (
                        7, 11, 13, 17, 19, 23 | Get-Random
                    ) 
                } while ($webSocketJob.State -in 'Running','NotStarted')
            } | . {                
                process {
                    $webSocketOutput = $_
                    foreach ($key in @($WatchFor.Keys)) {
                        $result = 
                            if ($key -is [ScriptBlock]) {
                                . $key $webSocketOutput
                            }

                        if (-not $result) { continue }
                        if ($WatchFor[$key] -is [ScriptBlock]) {
                            $webSocketOutput | . $WatchFor[$key]
                        } else {
                            $WatchFor[$key]
                        }                        
                    }
                }
            }
        }        
        elseif ($webSocketJob -and -not $broadcast) {
            $webSocketJob
        }        
    }
}