Private/Tasks.ps1

# Optional bounded background work. The transport reader never runs user code.
# PS scriptblocks execute in isolated worker runspaces; completion callbacks are
# dispatched on the owning application runspace by the ordinary event pump, never
# inside another callback (like notifications) and never after Close-NativeHTMLKit.
#
# Timeout and Stop-NativeHTMLKitTask are cancellation REQUESTS. A worker that ignores
# them keeps its slot (per application and per process) until its thread really
# finishes; only then is it disposed. Disposal never waits on a running worker, so
# neither the pump nor Close-NativeHTMLKit can block on one.
$script:NHKTaskStates = New-Object 'System.Collections.Generic.List[object]'
$script:NHKMaximumTasks = 8
$script:NHKMaximumProcessTasks = 32

function Get-NativeHTMLKitTaskStates {
    param($Application)
    return @($script:NHKTaskStates.ToArray() | Where-Object { [object]::ReferenceEquals($_.Application, $Application) })
}

function Remove-NativeHTMLKitFinishedTasks {
    # Reaps every worker (of any application) whose thread has ended and whose outcome
    # was delivered or abandoned. Dispose of an idle runspace does not block.
    foreach ($task in @($script:NHKTaskStates.ToArray())) {
        if (-not $task.AsyncResult.IsCompleted) { continue }
        if (-not ($task.Completed -and ($task.CallbackDelivered -or $task.Abandoned))) { continue }
        [void]$script:NHKTaskStates.Remove($task)
        try { $task.PowerShell.Dispose() } catch { Write-NativeHTMLKitDiagnostic -Event 'task.dispose_failed' -Level 'WARN' -Context @{ task_id = $task.Id; exception_type = $_.Exception.GetType().Name } }
        try { $task.Runspace.Dispose() } catch { Write-NativeHTMLKitDiagnostic -Event 'task.dispose_failed' -Level 'WARN' -Context @{ task_id = $task.Id; exception_type = $_.Exception.GetType().Name } }
        Write-NativeHTMLKitDiagnostic -Event 'task.reaped' -Level 'DEBUG' -Context @{ task_id = $task.Id; was_stopped = [bool]$task.StopRequested }
    }
}

function Request-NativeHTMLKitTaskStop {
    param($Task)
    if ($Task.StopRequested -or $Task.AsyncResult.IsCompleted) { return }
    $Task.StopRequested = $true
    try { [void]$Task.PowerShell.BeginStop($null, $null) }
    catch { Write-NativeHTMLKitDiagnostic -Event 'task.stop_request_failed' -Level 'ERROR' -Context @{ task_id = $Task.Id; exception_type = $_.Exception.GetType().Name } }
}

function Assert-NativeHTMLKitTaskArgument {
    # SDK objects belong to the owning runspace; refuse them anywhere inside the arguments
    # (arrays, lists, dictionaries, PSCustomObject properties), to a bounded depth.
    param($Value, [int]$Depth)
    if ($null -eq $Value -or $Value -is [string] -or $Value -is [ValueType]) { return }
    if ($Depth -gt 8) { throw 'Background task arguments are nested too deeply (more than 8 levels) to check; pass plain data' }
    foreach ($typeName in @('NativeHTMLKit.Application', 'NativeHTMLKit.Window', 'NativeHTMLKit.Document', 'NativeHTMLKit.Node', 'NativeHTMLKit.LiveBitmap', 'NativeHTMLKit.Request', 'NativeHTMLKit.Task', 'NativeHTMLKit.Subscription')) {
        if (Test-NativeHTMLKitType $Value $typeName) { throw "A $typeName belongs to the owning runspace and cannot be passed to a background task; pass plain data and update the UI in -OnCompleted" }
    }
    # `-is` sees through the PSObject wrapper (`.PSObject.BaseObject` would member-enumerate a collection).
    if ($Value -is [NativeHTMLKit.Transport] -or $Value -is [NativeHTMLKit.MappedBitmap]) { throw 'NativeHTMLKit transport objects cannot be passed to a background task' }
    if ($Value -is [System.Collections.IDictionary]) { foreach ($k in @($Value.Keys)) { Assert-NativeHTMLKitTaskArgument $Value[$k] ($Depth + 1) }; return }
    if ($Value -is [System.Collections.IEnumerable]) { foreach ($item in $Value) { Assert-NativeHTMLKitTaskArgument $item ($Depth + 1) }; return }
    if ($Value -is [System.Management.Automation.PSCustomObject]) { foreach ($p in $Value.PSObject.Properties) { Assert-NativeHTMLKitTaskArgument $p.Value ($Depth + 1) } }
}

function Start-NativeHTMLKitTask {
    <#
    .SYNOPSIS
    Starts bounded background PowerShell work in an isolated runspace; -OnCompleted/-OnFailed run later on this runspace.
    .DESCRIPTION
    The scriptblock runs in a new runspace without the caller's variables or modules and must not
    receive NativeHTMLKit window/document/application objects; pass plain data with -ArgumentList.
    Completion callbacks run on the owning runspace during the event pump (Wait-NativeHTMLKit or any
    waiting RPC), never inside another callback. -TimeoutMilliseconds and Stop-NativeHTMLKitTask only
    request cancellation: a worker that ignores it keeps occupying one of the 8 per-application
    (32 per-process) slots until it really ends.
    #>

    [CmdletBinding()]
    param([Parameter(Mandatory)]$Application,
          [Parameter(Mandatory)][scriptblock]$ScriptBlock,
          [object[]]$ArgumentList = @(),
          [scriptblock]$OnCompleted, [scriptblock]$OnFailed,
          [ValidateRange(0, 3600000)][int]$TimeoutMilliseconds = 0)
    Assert-NativeHTMLKitApplication $Application
    Assert-NativeHTMLKitTaskArgument $ArgumentList 0
    Remove-NativeHTMLKitFinishedTasks
    # Workers whose cancellation was requested STILL occupy a slot until their thread exits.
    if (@(Get-NativeHTMLKitTaskStates $Application).Count -ge $script:NHKMaximumTasks) {
        throw "NativeHTMLKit background task limit ($script:NHKMaximumTasks per application) reached; previous workers, including cancelled ones that are still running, must finish first"
    }
    if ($script:NHKTaskStates.Count -ge $script:NHKMaximumProcessTasks) {
        throw "NativeHTMLKit background task limit ($script:NHKMaximumProcessTasks per process) reached; previous workers, including cancelled ones that are still running, must finish first"
    }
    $runspace = $null; $runner = $null
    try {
        $runspace = [System.Management.Automation.Runspaces.RunspaceFactory]::CreateRunspace()
        $runspace.Open()
        $runner = [System.Management.Automation.PowerShell]::Create()
        $runner.Runspace = $runspace
        [void]$runner.AddScript($ScriptBlock.ToString())
        foreach ($argument in $ArgumentList) { [void]$runner.AddArgument($argument) }
        $state = [pscustomobject]@{
            Id = [guid]::NewGuid().ToString('N'); Application = $Application
            PowerShell = $runner; Runspace = $runspace
            AsyncResult = $null; OnCompleted = $OnCompleted; OnFailed = $OnFailed
            StartedUtc = [DateTime]::UtcNow; TimeoutMilliseconds = $TimeoutMilliseconds
            Completed = $false; Result = $null; Failure = $null; Errors = @()
            StopRequested = $false; CallbackDelivered = $false; Abandoned = $false
        }
        $state.PSObject.TypeNames.Insert(0, 'NativeHTMLKit.Task')
        $state.AsyncResult = $runner.BeginInvoke()
        $script:NHKTaskStates.Add($state)
    } catch {
        if ($null -ne $runner) { $runner.Dispose() }
        if ($null -ne $runspace) { $runspace.Dispose() }
        throw
    }
    Write-NativeHTMLKitDiagnostic -Event 'task.started' -Level 'DEBUG' -Context @{ task_id = $state.Id; timeout_ms = $TimeoutMilliseconds }
    return $state
}

function Update-NativeHTMLKitTaskState {
    # Detects completion or deadline expiry. Runs no user code.
    param($Task)
    if ($Task.Completed) { return }
    if ($Task.AsyncResult.IsCompleted) {
        try { $Task.Result = @($Task.PowerShell.EndInvoke($Task.AsyncResult)) }
        catch {
            # EndInvoke wraps the worker's terminating error; report the worker's own exception.
            $failure = $_.Exception
            if ($failure -is [System.Management.Automation.MethodInvocationException] -and $null -ne $failure.InnerException) { $failure = $failure.InnerException }
            $Task.Failure = $failure
        }
        $Task.Errors = @($Task.PowerShell.Streams.Error.ReadAll())
        $Task.Completed = $true
    } elseif ($Task.TimeoutMilliseconds -gt 0 -and ([DateTime]::UtcNow - $Task.StartedUtc).TotalMilliseconds -gt $Task.TimeoutMilliseconds) {
        $Task.Failure = New-Object -TypeName 'System.TimeoutException' -ArgumentList 'Background task exceeded its deadline; cancellation was requested but the worker may still be running'
        $Task.Completed = $true
        Request-NativeHTMLKitTaskStop $Task
        Write-NativeHTMLKitDiagnostic -Event 'task.timeout' -Level 'WARN' -Context @{ task_id = $Task.Id; timeout_ms = $Task.TimeoutMilliseconds }
    }
}

function Invoke-NativeHTMLKitTaskCompletions {
    # Must execute ONLY on the application owner runspace, outside other callbacks.
    # Returns how many task outcomes were delivered.
    param($Application)
    $delivered = 0
    foreach ($task in @(Get-NativeHTMLKitTaskStates $Application)) {
        Update-NativeHTMLKitTaskState $task
        if (-not $task.Completed -or $task.CallbackDelivered -or $task.Abandoned) { continue }
        if ($Application.Closed) { continue }
        $task.CallbackDelivered = $true
        $delivered++
        $started = [Diagnostics.Stopwatch]::StartNew()
        try {
            if ($null -ne $task.Failure) {
                Write-NativeHTMLKitDiagnostic -Event 'task.failed' -Level 'ERROR' -Context @{ task_id = $task.Id; exception_type = $task.Failure.GetType().Name }
                if ($null -ne $task.OnFailed) { $null = Invoke-NativeHTMLKitCallback $Application $task.OnFailed @($task.Failure) }
                else { Write-Warning ('NativeHTMLKit background task failed: ' + $task.Failure.GetType().Name) }
            } else {
                Write-NativeHTMLKitDiagnostic -Event 'task.completed' -Level 'DEBUG' -DurationMs ([long]([DateTime]::UtcNow - $task.StartedUtc).TotalMilliseconds) -Context @{ task_id = $task.Id; errors = $task.Errors.Count }
                if ($null -ne $task.OnCompleted) { $null = Invoke-NativeHTMLKitCallback $Application $task.OnCompleted @(,$task.Result) }
            }
            Write-NativeHTMLKitDiagnostic -Event 'callback.completed' -Level 'TRACE' -DurationMs $started.ElapsedMilliseconds -Context @{ role = 'task_completion'; task_id = $task.Id }
        } catch {
            # Isolated like document event handlers: logged, counted, never thrown into
            # an unrelated RPC wait that happened to pump this completion.
            Register-NativeHTMLKitCallbackFailure $Application 'task_completion' $_ @{ task_id = $task.Id }
        }
    }
    Remove-NativeHTMLKitFinishedTasks
    return $delivered
}

function Receive-NativeHTMLKitTask {
    <#
    .SYNOPSIS
    Reports a background task's state and result; -Wait keeps pumping host messages until it completes.
    .DESCRIPTION
    CancellationPending is true while a timed-out or stopped worker is still running. -Wait pumps the
    application's host messages (so lifecycle requests are answered) and throws System.TimeoutException
    after -TimeoutMilliseconds (-1 waits indefinitely) without cancelling the task. Errors holds the
    worker's non-terminating error records.
    #>

    [CmdletBinding()]
    param([Parameter(Mandatory)]$Task, [switch]$Wait, [ValidateRange(-1, 2147483647)][int]$TimeoutMilliseconds = -1)
    if (-not (Test-NativeHTMLKitType $Task 'NativeHTMLKit.Task')) { throw 'Expected a NativeHTMLKit.Task from Start-NativeHTMLKitTask' }
    $app = $Task.Application
    $clock = [Diagnostics.Stopwatch]::StartNew()
    Update-NativeHTMLKitTaskState $Task
    while ($Wait -and -not $Task.Completed) {
        if ($TimeoutMilliseconds -ge 0 -and $clock.ElapsedMilliseconds -ge $TimeoutMilliseconds) {
            throw (New-Object -TypeName 'System.TimeoutException' -ArgumentList "NativeHTMLKit background task did not complete within $TimeoutMilliseconds ms; it was not cancelled")
        }
        if (-not $app.Closed -and -not $app.Disconnected) {
            # A lost host does not stop a healthy local worker: keep waiting for it.
            try { [void](Invoke-NativeHTMLKitPump $app 25) } catch [NativeHTMLKit.DisconnectedException] { Start-Sleep -Milliseconds 25 }
        } else { Start-Sleep -Milliseconds 25 }
        Update-NativeHTMLKitTaskState $Task
    }
    if (-not $app.Dispatching -and -not $app.Closed) { $null = Invoke-NativeHTMLKitTaskCompletions -Application $app }
    else { Remove-NativeHTMLKitFinishedTasks }
    return [pscustomobject]@{ Id = $Task.Id; Completed = $Task.Completed; Result = $Task.Result
        Failure = $Task.Failure; Errors = $Task.Errors
        CancellationPending = ($Task.StopRequested -and -not $Task.AsyncResult.IsCompleted) }
}

function Stop-NativeHTMLKitTask {
    <#
    .SYNOPSIS
    Requests cancellation of a background task; -OnFailed later receives an OperationCanceledException.
    .DESCRIPTION
    Not a guarantee: a worker blocked in native or .NET code may keep running and keeps its slot until
    it ends (Receive-NativeHTMLKitTask reports CancellationPending). Its result is discarded.
    #>

    [CmdletBinding()]
    param([Parameter(Mandatory)]$Task)
    if (-not (Test-NativeHTMLKitType $Task 'NativeHTMLKit.Task')) { throw 'Expected a NativeHTMLKit.Task from Start-NativeHTMLKitTask' }
    Update-NativeHTMLKitTaskState $Task
    if ($Task.Completed) { return }
    $Task.Failure = New-Object -TypeName 'System.OperationCanceledException' -ArgumentList 'Background task cancellation was requested; the worker may still be running'
    $Task.Completed = $true
    Request-NativeHTMLKitTaskStop $Task
    Write-NativeHTMLKitDiagnostic -Event 'task.stop_requested' -Level 'DEBUG' -Context @{ task_id = $Task.Id }
}

function Stop-NativeHTMLKitTasks {
    # Close-NativeHTMLKit: request stop of every unfinished worker without waiting; no callback
    # runs after close. Finished workers are disposed now, the rest by a later reap.
    param($Application)
    foreach ($task in @(Get-NativeHTMLKitTaskStates $Application)) {
        Update-NativeHTMLKitTaskState $task
        if (-not $task.Completed) {
            $task.Failure = New-Object -TypeName 'System.OperationCanceledException' -ArgumentList 'The NativeHTMLKit application was closed before the background task finished'
            $task.Completed = $true
        }
        $task.Abandoned = $true
        Request-NativeHTMLKitTaskStop $task
    }
    Remove-NativeHTMLKitFinishedTasks
}