Fun.ps1

<#
.SYNOPSIS
    Fun Server 
.DESCRIPTION
    A Fun Server in PowerShell.
    
    Fun makes web dev fun and interactive.

    We just write function that start with `/`.
    
    Then `Start-Fun`
    
    For example:

    ~~~PowerShell
    function / { 
        "Hello From Fun", "Hi from Fun", "It's Fun" | Get-Random
    }

    Start-Fun
    ~~~

    Fun supports live reloading of functions.
    
    We can redefine functions at any time.

    Functions run in our current context.
    
    This allows for fun interations between the browser and the terminal.    
.NOTES
    .NOTES
    This is a fun experimental server in PowerShell.

    It is build atop a design pattern:

    Any function starting with `/` will serve request.    

    Functions can be a local path or a wildcard of the url.

    Whenever the url is visited, the funtion will be run.    

    Any query parameters will be automatically mapped to function parameters.

    You can write code with this pattern and not have `Fun`.

    `Fun` just makes it fun.

    By default, in `Fun`, functions run as the current user.
    
    They have access to the current state.

    This includes, but is not limited to:

    * Currently loaded modules
    * Current variables
    * The Current PowerShell Host
    * PowerShell Events
    
    This allows for fun and unique server scenarios.
    
    We can allow selective control over our terminal (and operating systems) from our browser.

    This is as fun (and potentially dangerous) as it sounds.

    While we can call any command as a service, we want to be selective.

    For these reasons, we want to run `Fun` locally on a random loopback port,
    or in a container with a constrained list of commands.

    We also want to avoid code injection at all costs,
    and only expose safe commands.    
.EXAMPLE
    # Hello World server
    / { "<h1>hello world</h1>" }

    Start-Fun
.EXAMPLE
    function / {
        "<h1>Hello from Fun</h1>"
        "<h2>It is $([DateTime]::Now).</h2>"
        "<h3>Here's a random number $([Random]::new().next())</h3>"
    }

    (fun).Start()
.EXAMPLE
    # Fun Website
    Get-Module Fun | 
        Split-Path | 
        Push-Location
    . ./Fun.fun.ps1

    Start-Fun

    Pop-Location    
#>
[CmdletBinding(PositionalBinding=$false)]
[Alias('Start-Fun')]
param(
# A list of any arguments.
# If an argument starts with `https?://`, 
# it will be considered a prefix.
# If the argument is 'start', it will start the server.
# All arguments will be persisted and added to the output object.
# This allows them to be used inside of a server, via `$this.Arguments`
[Parameter(ValueFromRemainingArguments)]
[Alias('Arguments','Argument','Args')]
[PSObject[]]
$ArgumentList,

# Any Input Object.

# This is currently passed on directly to a server instance.
# Any function can reference this input with `$this.Input`
[Parameter(ValueFromPipeline)]
[Alias('Input')]
[PSObject]
$InputObject
)

# This function is designed to be pretty performant,
# so we want to handle all of our input once it has been piped in.
$allInput = @($input)
# (we also want to accept non-piped input)
if (-not $allInput -and $InputObject) {
    $allInput = @($InputObject)
}

# We will be outputting a custom object named after ourself
$myTypeName = 
    $MyInvocation.MyCommand.Name -replace 
        '\.ps1$' -replace '^.+?-' # (replacing the extension and any verb)

Update-TypeData -TypeName $myTypeName -Force -DefaultDisplayPropertySet 'CreatedAt','RequestRate','Functions'
# Create our output object
$outputObject = New-Object PSObject -Property ([Ordered]@{
    PSTypeName = $myTypeName
    CreatedAt  = [DateTime]::Now
    # Fun fact: this kind of enumeration is always up to date
    # We will not need to watch for new commands, this variable will always have them.
    Functions  = $ExecutionContext.SessionState.InvokeCommand.GetCommands('/*','Function,Alias', $true)    
    Arguments  = $ArgumentList
    Input      = $allInput
}) |
    # Extend our output with a script methods and properties
    #region `.Build`
    Add-Member ScriptMethod Build {
        <#
        .SYNOPSIS
            Builds the server 
        .DESCRIPTION
            Builds the server into a static site.
        
            Will build any `/` function whose name is like *.*.
        #>
        param([string]$Path = $pwd)
        $this.Functions |
            . { process {
                $cmd = $_
                if ($cmd.Name -notlike '*.*') { return }
                $output = . $cmd
                $path = Join-Path $pwd $cmd.Name
                $newFile = [Ordered]@{
                    Path = Join-Path "." "./$($cmd.Name -replace "^/")"
                    Value=$output -join [Environment]::NewLine
                }
                New-Item @newFile -Force -ItemType File
            } }
    } -Force -PassThru |
    #endregion `.Build`
    #region `.Clear`
    Add-Member ScriptMethod Clear {
        foreach ($func in $this.Functions) {
            if ($func -is [Management.Automation.FunctionInfo]) {
                Remove-Item "function:/$($func.Name)"
            } elseif ($func -is [Management.Automation.AliasInfo]) {
                Remove-Item "alias:/$($func.Name)"
            }
        }
    } -Force -PassThru |
    #endregion `.Clear
    #region `.Define`
    Add-Member ScriptProperty Define {
        <#
        .SYNOPSIS
            Define the Current endpoints.
        .DESCRIPTION
            Returns a script that will define of all current endpoints.
        #>        
        [ScriptBlock]::Create(
            @(
                foreach ($func in $this.Functions) {
                    if ($func -is [Management.Automation.FunctionInfo]) {
                        "function $func {$(
                            $func.ScriptBlock
                        )$(
                            [Environment]::NewLine
                        )}"
                    } elseif ($func -is [Management.Automation.AliasInfo]) {
                        "Set-Alias '$(
                            $func.Name -replace "'","''"
                        )' '$(
                            $func.ResolvedCommand -replace "'","''"
                        )'"
                    }
                }
            ) -join [Environment]::NewLine
        )
    } -Force -PassThru |
    #endregion `.Define`
    #region `.JobScript`
    Add-Member ScriptProperty JobScript { 
        return {
            # All we need to do is pass this object
            param($this)
            
            # It will have a listener
            $httpListener = $this.HttpListener
            # and we can loop while it is listening
            while ($httpListener.IsListening) {
                # Get the next context
                $getContext = $httpListener.GetContextAsync()
                # and wait until it's ready
                while (-not $getContext.Wait(13)) { }
                $context = $getContext.Result
                # If we don't yet have a counter
                if (-not $this.Counter) {
                    # create one.
                    $this | 
                        Add-Member NoteProperty Counter ([long]0) -Force
                }
                # Increment our counter
                $this.Counter++
                # And run our function
                if ($this.Run) {
                    try {
                        $this.Run($context)
                    } catch {
                        $err = $_
                        $context.Response.StatusCode = 400
                        $context.Response.Close([Text.Encoding]::UTF8.GetBytes(
                            "$err"
                        ), $false)
                        $err
                    }                    
                }
            }
        }
    } -Force -PassThru |
    #endregion `.JobScript`
    #region `.Remove`
    Add-Member ScriptMethod Remove {
        param([string]$Wildcard)
        if (-not $Wildcard) { return }
        foreach ($func in $this.Functions) {
            if ($func.Name -notlike $Wildcard) {
                continue
            }
            if ($func -is [Management.Automation.FunctionInfo]) {
                Remove-Item "function:/$($func.Name)"
            } elseif ($func -is [Management.Automation.AliasInfo]) {
                Remove-Item "alias:/$($func.Name)"
            }
        }
    } -Force -PassThru |
    #endregion `.Remove
    #region `.RequestRate`
    # We also want one script property that calculates a request rate
    Add-Member ScriptProperty RequestRate {
        # To do this we just take the counter
        ($this.Counter -as [long]) /
            # and divide by the number of minutes we have been running
            ([DateTime]::Now - $this.CreatedAt).TotalMinutes
    } -Force -PassThru |
    #endregion `.RequestRate`
    #region `.Run`
    Add-Member ScriptMethod Run {
        <#
        .SYNOPSIS
            Run in a context
        .DESCRIPTION
            Run the function in a context
        #>
        param($context)

        # Allow for mock requests by enabling casting to uris
        if ($context -as [uri]) {
            $request = [Ordered]@{HttpMethod='Get';Url = $context -as [uri]}
        } else {
            $request, $response = $context.Request, $context.Response
        }

        # Use the local path if present
        $localPath =
            if ($request.Url.LocalPath) {
                $request.Url.LocalPath
            } else { $null }                    
        
        # We want to match the url to a function.
        $functions = @(foreach ($function in @($this.Functions)) {
            # We don't want to be too picky about ending slashes,
            # so remove them from our function name.
            $functionNameNoSlash = $function.Name -replace '/$'
            if (
                # If the local path is like our function name
                $localPath -and 
                    (
                        # we've found our function
                        $localPath -replace '/$' -like $functionNameNoSlash
                    )
            ) {
                # Break after the first function we find.
                $function
                break
            }
        })

        # If there were no found functions
        if (-not $functions) {
            # We're going to send a 404.
            if ($response.StatusCode) {
                $response.StatusCode = 404
            }
            # We want that 404 to be customizable,
            # so look for a function named the status code `(i.e. /404)
            $statusCodeFunction = @($this.functions -match "^/$($response.StatusCode)/?$")
            if ($statusCodeFunction) {
                # If one existed, set `$functions` and call it normally. 
                $functions = $statusCodeFunction
            } else {
                # Otherwise, close the response
                $response.Close()
                return
            }
        }

        # To add to the fun, we want our functions to take parameters
        $query = [Ordered]@{}
        # If the request had a query
        if ($request.Url.Query) {
            # parse it
            $parsedQueryString = [Web.HttpUtility]::ParseQueryString($request.Url.Query)
            # and copy over our parameters.
            foreach ($queryParameter in $parsedQueryString.Keys) {
                $query[$queryParameter] = $parsedQueryString[$queryParameter]
                if ($query[$queryParameter] -match '^(true|false)$') {
                    $query[$queryParameter] = $query[$queryParameter] -match '^true' 
                }
            }
        }
        
        # Get the last matching function 
        $function = $functions[-1]

        # And use its command metadata to find all possible parameters
        $functionParameterMap = @{}
        foreach ($parameter in ($function -as [Management.Automation.CommandMetadata]).Parameters.Values) {
            $functionParameterMap[$parameter.Name] = $parameter
            foreach ($alias in $parameter.Aliases) {
                $functionParameterMap[$alias] = $parameter
            }
        }
        
        # Now take all of our query parameters
        $functionParameters = [Ordered]@{}
        foreach ($queryParameter in $query.Keys) {
            # and map them to the function where we can
            $functionParameter = $functionParameterMap[$queryParameter]
            if ($functionParameter) {
                $functionParameters[
                    $functionParameter.Name
                ] = $query[$queryParameter]
            }
        }

        # If the function had an output type like `*/*`
        if ($function.OutputType.Name -like '*/*' -and
            $response.OutputStream
        ) {            
            foreach ($outputType in $function.OutputType) {
                if ($outputType.Name -like '*/*') {
                    # this will become the response content type
                    $response.ContentType = $outputType.Name
                    break
                }
            }
        }
        # If we do not have an output type
        if (-not $function.OutputType) {
            # default to `text/html`
            $response.ContentType = 'text/html'
        }

        $functionOutput = {
            begin {
                # To stream output, we need to set the protocol version
                $response.ProtocolVersion = '1.1'
                # and send chunked responses.
                $response.SendChunked = $true
                # Get a pointer to the output stream for repeated use.
                $outputStream = $response.OutputStream                
                $encoding = if ($request.ContentEncoding) {
                    $request.ContentEncoding
                } else {
                    [Text.Encoding]::UTF8
                }
            }

            process {
                # Then we need to take each output object
                $in = $_                

                # If it is XML,
                if ($in.OuterXml -and $outputStream.CanWrite) {
                    # write it out.
                    $buffer = $encoding.GetBytes("$($in.OuterXml)")
                    $outputStream.Write($buffer, 0, $buffer.Length)
                    $outputStream.Flush()
                }
                # If it has an HTML property
                elseif ($in.html -and $outputStream.CanWrite) {
                    # write that out
                    $buffer = $encoding.GetBytes("$($in.html)")
                    $outputStream.Write($buffer, 0, $buffer.Length)
                    $outputStream.Flush()
                }
                # Otherwise
                elseif ($outputStream.CanWrite) {
                    # Stringify the result.
                    $buffer = $encoding.GetBytes("$in")
                    $outputStream.Write($buffer, 0, $buffer.Length)
                    $outputStream.Flush()
                } else {
                    $in
                }
            }

            end {                
                # Close our response when the command is done
                if ($response.Close) {
                    $response.Close()
                }
            }
        }

        # Call our function and stream the results
        try {
            . $function @functionParameters *>&1 | 
                . $functionOutput
        } catch {
            $err = $_
            $response.StatusCode = 400
            $response.Close([Text.Encoding]::UTF8.GetBytes(
                "$err"
            ), $false)
            $err
        }
        
    } -Force -PassThru |
    #endregion `.Run`
    #region `.Start`
    Add-Member ScriptMethod Start {
        param()
        # In order to start the fun, we need an http listener
        if (-not $this.HttpListener) {
            # Attach this listener to this object
            $this | 
                Add-Member NoteProperty HttpListener (
                    [Net.HttpListener]::new()
                ) -Force
            # If we have any prefixes, add them
            if ($this.Prefixes) {
                foreach ($prefix in $this.Prefixes) {
                    $httpPrefix = $prefix -replace '/{0,}$' -replace '$', '/'
                    $this.HttpListener.Prefixes.Add($httpPrefix)
                }                
            } else {
                # Otherwise, pick a random local loopback port
                $this.HttpListener.Prefixes.Add(
                    "http://127.0.0.1:$(Get-Random -Min 8kb -Max 42kb)/"
                )
            }
        }
       
        # Start the listener
        if (-not $this.HttpListener.IsListening) {
            # Write a warning so we know something is listening
            Write-Warning "Listening on $($this.HttpListener.Prefixes)"
            $this.HttpListener.Start()
        }
        
        $listener = $this.HttpListener
        
        # Now start our fun little server loop in a thread job.        
        $newJob = Start-ThreadJob -ScriptBlock $this.JobScript -ArgumentList $this -Name "$(
            $listener.Prefixes -replace '/$'
        )" -ThrottleLimit 16kb |
            Add-Member NoteProperty HttpListener $this.HttpListener -Force -PassThru |
            Add-Member NoteProperty Fun $this -Force -PassThru
    
        if (-not $this.Jobs) {
            $this | Add-Member NoteProperty Jobs @($newJob) -Force
        } else {
            $null = $this.Jobs += $newJob
        }
        $newJob
    } -Force -PassThru
    #endregion `.Start`


$prefixArguments = $ArgumentList -match '^https?://'

if ($prefixArguments) {
    $OutputObject | 
        Add-Member NoteProperty Prefixes (
            $prefixArguments -replace '/?$', '/'
        ) -Force
}
# If the arguments contained `start`
if ($ArgumentList -contains 'Start' -or 
    # or the invocation name started with `Start-`
    $MyInvocation.InvocationName -match '^Start-') {
    # start the fun now.
    $outputObject.Start()
} else {
    # otherwise, output the fun
    $outputObject
}

return