Private/KlipAroundProtocol.ps1

Set-StrictMode -Version Latest

$script:KlipAroundProtocol = 'KlipAround/2'
$script:KlipAroundMarkers = @{
    Begin = '-----BEGIN KLIPAROUND/2-----'
    End   = '-----END KLIPAROUND/2-----'
}

function New-KlipAroundMessage {
    [CmdletBinding()]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Constructs an in-memory protocol message.')]
    param(
        [Parameter(Mandatory)]
        [string]$SessionId,

        [Parameter(Mandatory)]
        [ValidateSet('Sender', 'Receiver')]
        [string]$Role,

        [Parameter(Mandatory)]
        [ValidateSet('HELLO', 'HELLO_ACK', 'FILE_META', 'FILE_META_ACK', 'DATA_BURST', 'ACK_REPORT', 'FILE_EOF', 'FILE_EOF_ACK', 'FIN', 'FIN_ACK', 'ERROR')]
        [string]$MessageType,

        [Parameter()]
        [hashtable]$Payload = @{}
    )

    return [ordered]@{
        Protocol     = $script:KlipAroundProtocol
        SessionId    = $SessionId
        Role         = $Role
        MessageType  = $MessageType
        MessageId    = [guid]::NewGuid().ToString()
        TimestampUtc = (Get-Date).ToUniversalTime().ToString('o')
        Payload      = $Payload
    }
}

function ConvertTo-KlipAroundEnvelope {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [hashtable]$Message
    )

    $json = $Message | ConvertTo-Json -Depth 20 -Compress
    return @(
        $script:KlipAroundMarkers.Begin
        $json
        $script:KlipAroundMarkers.End
    ) -join [Environment]::NewLine
}

function ConvertFrom-KlipAroundEnvelope {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Text
    )

    $normalized = $Text -replace "`r`n", "`n"
    $beginIndex = $normalized.IndexOf($script:KlipAroundMarkers.Begin, [StringComparison]::Ordinal)
    if ($beginIndex -lt 0) {
        throw 'Clipboard payload is not a KlipAround envelope.'
    }

    $bodyStart = $beginIndex + $script:KlipAroundMarkers.Begin.Length
    $endIndex = $normalized.IndexOf("`n$($script:KlipAroundMarkers.End)", $bodyStart, [StringComparison]::Ordinal)
    if ($endIndex -lt 0) {
        throw 'Clipboard payload is not a KlipAround envelope.'
    }
    $body = $normalized.Substring($bodyStart, $endIndex - $bodyStart).Trim()
    if ([string]::IsNullOrWhiteSpace($body)) {
        throw 'KlipAround envelope payload is empty.'
    }

    try {
        $obj = $body | ConvertFrom-Json -ErrorAction Stop
    }
    catch {
        throw "Failed to parse KlipAround envelope: $($_.Exception.Message)"
    }

    if ($obj.Protocol -ne $script:KlipAroundProtocol) {
        throw "Unsupported protocol '$($obj.Protocol)'. Expected '$script:KlipAroundProtocol'."
    }

    return $obj
}

function Write-KlipAroundDebugEnvelope {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateSet('Send', 'Receive')]
        [string]$Direction,

        [Parameter(Mandatory)]
        [string]$Text
    )

    $byteCount = [Text.Encoding]::UTF8.GetByteCount($Text)
    Write-Debug "[$Direction] BEGIN KLIPAROUND MESSAGE ($byteCount UTF-8 bytes)"
    Write-Debug $Text
    Write-Debug "[$Direction] END KLIPAROUND MESSAGE"
}

function Publish-KlipAroundMessage {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [hashtable]$Message,

        [Parameter()]
        [ValidateRange(1, 3600)]
        [int]$TimeoutSeconds = 60
    )

    $envelope = ConvertTo-KlipAroundEnvelope -Message $Message
    Write-KlipAroundDebugEnvelope -Direction Send -Text $envelope
    Set-KlipAroundClipboardText -Text $envelope -TimeoutMilliseconds ($TimeoutSeconds * 1000)
    return $Message
}

function Wait-KlipAroundMessage {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$SessionId,

        [Parameter(Mandatory)]
        [ValidateSet('Sender', 'Receiver')]
        [string]$ExpectedRole,

        [Parameter(Mandatory)]
        [string[]]$ExpectedMessageType,

        [Parameter()]
        [ValidateRange(1, 3600)]
        [int]$TimeoutSeconds = 60,

        [Parameter()]
        [ValidateRange(50, 5000)]
        [int]$PollMilliseconds = 250,

        [Parameter()]
        [ValidateRange(10, 1000)]
        [int]$MinPollMilliseconds = 40,

        [Parameter()]
        [System.Collections.Generic.HashSet[string]]$IgnoreMessageIds,

        [Parameter()]
        [System.Collections.Generic.HashSet[string]]$SeenMessageIds
    )

    $deadline = (Get-Date).AddSeconds($TimeoutSeconds)
    $maxPollMilliseconds = [Math]::Max($PollMilliseconds, $MinPollMilliseconds)
    $currentPollMilliseconds = $MinPollMilliseconds
    $lastClipboardText = $null
    $haveLastClipboardText = $false
    $clipboardListener = $null
    $useClipboardListener = $false
    $listenerTimeoutStreak = 0
    $maxListenerTimeoutStreak = 8
    $readClipboardImmediately = $true

    $sleepWithJitter = {
        param([int]$BaseMilliseconds)
        $jitter = Get-Random -Minimum -10 -Maximum 11
        $sleepFor = $BaseMilliseconds + $jitter
        if ($sleepFor -lt 10) { $sleepFor = 10 }
        if ($sleepFor -gt $maxPollMilliseconds) { $sleepFor = $maxPollMilliseconds }
        Start-Sleep -Milliseconds $sleepFor
    }

    $increasePoll = {
        param([double]$Factor)
        $next = [int][Math]::Ceiling($currentPollMilliseconds * $Factor)
        if ($next -lt $MinPollMilliseconds) { $next = $MinPollMilliseconds }
        if ($next -gt $maxPollMilliseconds) { $next = $maxPollMilliseconds }
        return $next
    }

    try {
        $clipboardListener = New-KlipAroundClipboardListener
        if ($null -ne $clipboardListener) {
            $useClipboardListener = $true
            Write-Verbose "Using clipboard event listener for session '$SessionId'."
        }
    }
    catch {
        $useClipboardListener = $false
    }

    $invokeWaitBackoff = {
        param([double]$Factor)
        if ($useClipboardListener) {
            return
        }

        & $sleepWithJitter $currentPollMilliseconds
        $currentPollMilliseconds = [int](& $increasePoll $Factor)
    }

    try {
        while ((Get-Date) -lt $deadline) {
            if ($useClipboardListener -and -not $readClipboardImmediately) {
                $waitMilliseconds = [Math]::Max(20, [Math]::Min($currentPollMilliseconds, $maxPollMilliseconds))
                $clipboardChanged = $false
                try {
                    $clipboardChanged = $clipboardListener.WaitForChange($waitMilliseconds)
                }
                catch {
                    $useClipboardListener = $false
                    Write-Verbose "Clipboard event listener failed; falling back to polling for session '$SessionId'."
                }

                if (-not $clipboardChanged -and $useClipboardListener) {
                    $listenerTimeoutStreak++
                    if ($listenerTimeoutStreak -ge $maxListenerTimeoutStreak) {
                        $useClipboardListener = $false
                        $currentPollMilliseconds = $MinPollMilliseconds
                        Write-Verbose "Clipboard event listener did not signal changes; falling back to polling for session '$SessionId'."
                    }
                    else {
                        continue
                    }
                }
                elseif ($clipboardChanged) {
                    $listenerTimeoutStreak = 0
                }
            }

            $readClipboardImmediately = $false

            $text = $null
            try {
                # Give a read started near the deadline one polling interval to finish.
                $minimumReadMilliseconds = [Math]::Min($maxPollMilliseconds, $TimeoutSeconds * 1000)
                $remainingMilliseconds = [int][Math]::Max($minimumReadMilliseconds, [Math]::Ceiling(($deadline - (Get-Date)).TotalMilliseconds))
                $text = Get-KlipAroundClipboardText -TimeoutMilliseconds $remainingMilliseconds
            }
            catch [System.InvalidOperationException] {
                throw
            }
            catch {
                & $invokeWaitBackoff 1.35
                continue
            }

            if ($haveLastClipboardText -and $text -ceq $lastClipboardText) {
                & $invokeWaitBackoff 1.35
                continue
            }

            $lastClipboardText = $text
            $haveLastClipboardText = $true
            $currentPollMilliseconds = $MinPollMilliseconds

            try {
                $msg = ConvertFrom-KlipAroundEnvelope -Text $text
                Write-KlipAroundDebugEnvelope -Direction Receive -Text $text
            }
            catch {
                & $invokeWaitBackoff 1.25
                continue
            }

            $messageId = [string]$msg.MessageId

            if ($null -ne $IgnoreMessageIds -and $IgnoreMessageIds.Contains($messageId)) {
                & $invokeWaitBackoff 1.2
                continue
            }
            if ($null -ne $SeenMessageIds -and $SeenMessageIds.Contains($messageId)) {
                & $invokeWaitBackoff 1.2
                continue
            }
            if ($msg.SessionId -ne $SessionId) {
                & $invokeWaitBackoff 1.2
                continue
            }
            if ($msg.Role -ne $ExpectedRole) {
                & $invokeWaitBackoff 1.2
                continue
            }
            if ($ExpectedMessageType -notcontains [string]$msg.MessageType) {
                & $invokeWaitBackoff 1.2
                continue
            }

            if ($null -ne $SeenMessageIds) {
                [void]$SeenMessageIds.Add($messageId)
            }

            return $msg
        }
    }
    finally {
        if ($null -ne $clipboardListener) {
            try {
                $clipboardListener.Dispose()
            }
            catch {
                Write-Warning "Could not dispose the clipboard listener for session '$SessionId': $($_.Exception.Message)"
            }
        }
    }

    throw "Timed out waiting for message types '$($ExpectedMessageType -join ',')' from role '$ExpectedRole' in session '$SessionId'."
}

function New-KlipAroundDataBlock {
    [CmdletBinding()]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Constructs an in-memory data block.')]
    param(
        [Parameter(Mandatory)]
        [int]$Sequence,

        [Parameter(Mandatory)]
        [AllowEmptyCollection()]
        [byte[]]$Bytes,

        [Parameter()]
        [ValidateSet('CRC32C', 'SHA256')]
        [string]$ChecksumAlgorithm = 'CRC32C'
    )

    return @{
        Seq               = $Sequence
        Length            = $Bytes.Length
        ChecksumAlgorithm = $ChecksumAlgorithm
        Checksum          = Get-KlipAroundBlockChecksumHexForByteArray -Bytes $Bytes -Algorithm $ChecksumAlgorithm
        Data              = [Convert]::ToBase64String($Bytes)
    }
}

function Expand-KlipAroundDataBlock {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        $Block,

        [Parameter()]
        [ValidateSet('CRC32C', 'SHA256')]
        [string]$ExpectedChecksumAlgorithm
    )

    $bytes = [Convert]::FromBase64String([string]$Block.Data)
    if ($bytes.Length -ne [int]$Block.Length) {
        throw "Block $($Block.Seq) byte length mismatch."
    }

    $algorithm = 'CRC32C'
    if ($Block.PSObject.Properties.Name -contains 'ChecksumAlgorithm' -and -not [string]::IsNullOrWhiteSpace([string]$Block.ChecksumAlgorithm)) {
        $algorithm = [string]$Block.ChecksumAlgorithm
    }
    elseif ($Block.PSObject.Properties.Name -contains 'Sha256') {
        $algorithm = 'SHA256'
    }

    if ($PSBoundParameters.ContainsKey('ExpectedChecksumAlgorithm') -and $ExpectedChecksumAlgorithm -ne $algorithm) {
        throw "Block $($Block.Seq) checksum algorithm mismatch. Expected $ExpectedChecksumAlgorithm, got $algorithm."
    }

    $expected = if ($algorithm -eq 'SHA256' -and ($Block.PSObject.Properties.Name -contains 'Sha256')) {
        [string]$Block.Sha256
    }
    else {
        [string]$Block.Checksum
    }

    if ([string]::IsNullOrWhiteSpace($expected)) {
        throw "Block $($Block.Seq) missing checksum value."
    }

    $actual = Get-KlipAroundBlockChecksumHexForByteArray -Bytes $bytes -Algorithm $algorithm
    if ($actual -ne $expected) {
        throw "Block $($Block.Seq) checksum mismatch."
    }

    return ,$bytes
}