Public/Send-KlipAround.ps1
|
Set-StrictMode -Version Latest <# .SYNOPSIS Sends files using the KlipAround reliable windowed clipboard protocol. .DESCRIPTION Send-KlipAround is the sender side of a two-party transfer. It exchanges control/data messages over the clipboard with a concurrently running Receive-KlipAround process on the other machine/session. .PARAMETER Path One or more file paths to transfer. Existing literal paths take precedence over wildcard expansion. .PARAMETER BlockSize Bytes per data block in a DATA_BURST payload. Default is 131072 (128 KiB). .PARAMETER WindowSize Number of data blocks sent in each burst before awaiting ACK_REPORT. Default is 16. .PARAMETER TimeoutSeconds Per-message timeout while waiting for receiver responses. .PARAMETER MaxRetries Maximum retries for a timed-out or unadvanced ACK before failing transfer. .PARAMETER BlockChecksumAlgorithm Checksum algorithm for per-block integrity. Defaults to SHA256. .PARAMETER PrecomputeHash Computes each file SHA-256 before data transfer (legacy behavior). By default, SHA-256 is computed incrementally while blocks are sent to avoid an extra full file read. .PARAMETER SessionId Optional session identifier. Defaults to a new GUID. .PARAMETER PassThru Returns transfer summary details. #> function Send-KlipAround { [CmdletBinding()] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)] [Alias('FullName')] [ValidateNotNullOrEmpty()] [string[]]$Path, [Parameter()] [ValidateRange(4096, 1048576)] [int]$BlockSize = 131072, [Parameter()] [ValidateRange(1, 64)] [int]$WindowSize = 16, [Parameter()] [ValidateRange(1, 3600)] [int]$TimeoutSeconds = 90, [Parameter()] [ValidateRange(1, 20)] [int]$MaxRetries = 5, [Parameter()] [ValidateSet('CRC32C', 'SHA256')] [string]$BlockChecksumAlgorithm = 'SHA256', [Parameter()] [switch]$PrecomputeHash, [Parameter()] [ValidateNotNullOrEmpty()] [string]$SessionId = ([guid]::NewGuid().ToString()), [Parameter()] [switch]$PassThru ) begin { $files = New-Object System.Collections.Generic.List[string] } process { foreach ($candidate in $Path) { $resolved = @(if (Test-Path -LiteralPath $candidate -PathType Leaf) { Resolve-Path -LiteralPath $candidate -ErrorAction Stop } else { Resolve-Path -Path $candidate -ErrorAction Stop }) if ($resolved.Count -eq 0) { throw "Path '$candidate' did not resolve to a file." } foreach ($entry in $resolved) { if (-not (Test-Path -LiteralPath $entry.Path -PathType Leaf)) { throw "Path '$($entry.Path)' is not a file." } if (-not $files.Contains($entry.Path)) { [void]$files.Add($entry.Path) } } } } end { if ($files.Count -eq 0) { throw 'No files resolved for transfer.' } $sentMessageIds = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase) $seenMessageIds = New-Object 'System.Collections.Generic.HashSet[string]' $overallProgressId = 4100 $fileProgressId = 4101 $results = New-Object System.Collections.Generic.List[object] $readBlockBySequence = { param( [Parameter(Mandatory)] [System.IO.FileStream]$Stream, [Parameter(Mandatory)] [int]$Sequence, [Parameter(Mandatory)] [int]$BlockSize, [Parameter(Mandatory)] [int64]$FileLength ) $offset = [int64]$Sequence * $BlockSize if ($offset -gt $FileLength) { throw "Sequence $Sequence resolves past EOF." } $bytesToRead = [int][Math]::Min([int64]$BlockSize, [Math]::Max([int64]0, $FileLength - $offset)) if ($bytesToRead -eq 0) { return ,([byte[]]@()) } $buffer = New-Object byte[] $bytesToRead $Stream.Position = $offset $totalRead = 0 while ($totalRead -lt $bytesToRead) { $readCount = $Stream.Read($buffer, $totalRead, $bytesToRead - $totalRead) if ($readCount -le 0) { break } $totalRead += $readCount } if ($totalRead -ne $bytesToRead) { throw "Could not read block sequence $Sequence from source file." } return ,$buffer } try { $helloPayload = @{ FileCount = $files.Count WindowSize = $WindowSize BlockSize = $BlockSize SenderHost = $env:COMPUTERNAME SenderUser = [Environment]::UserName StartedUtc = (Get-Date).ToUniversalTime().ToString('o') } $helloAck = $null $helloWait = [System.Diagnostics.Stopwatch]::StartNew() while ($helloWait.Elapsed.TotalSeconds -lt $TimeoutSeconds) { $hello = New-KlipAroundMessage -SessionId $SessionId -Role Sender -MessageType HELLO -Payload $helloPayload $published = Publish-KlipAroundMessage -Message $hello -TimeoutSeconds $TimeoutSeconds [void]$sentMessageIds.Add($published.MessageId) $remainingSeconds = [int][Math]::Ceiling($TimeoutSeconds - $helloWait.Elapsed.TotalSeconds) if ($remainingSeconds -lt 1) { break } $attemptTimeoutSeconds = [Math]::Min(10, $remainingSeconds) try { $helloAck = Wait-KlipAroundMessage -SessionId $SessionId -ExpectedRole Receiver -ExpectedMessageType HELLO_ACK -TimeoutSeconds $attemptTimeoutSeconds -IgnoreMessageIds $sentMessageIds -SeenMessageIds $seenMessageIds break } catch { $isWaitTimeout = $_.Exception.Message -like "Timed out waiting for message types*" if (-not $isWaitTimeout) { throw } Write-Verbose "No HELLO_ACK yet. Re-sending HELLO." } } $helloWait.Stop() if ($null -eq $helloAck) { throw "Timed out waiting for HELLO_ACK in session '$SessionId'." } if ($helloAck.Payload.Accepted -ne $true) { throw "Receiver rejected HELLO for session '$SessionId'." } for ($fileIndex = 0; $fileIndex -lt $files.Count; $fileIndex++) { $filePath = $files[$fileIndex] $fileInfo = Get-Item -LiteralPath $filePath -ErrorAction Stop $fileHash = $null if ($PrecomputeHash) { $fileHash = Get-KlipAroundSha256HexForFile -Path $filePath } $totalBlocks = [int][Math]::Ceiling($fileInfo.Length / [double]$BlockSize) if ($totalBlocks -eq 0) { $totalBlocks = 1 } Write-Progress -Id $overallProgressId -Activity 'KlipAround send' -Status "Preparing file $($fileIndex + 1) of $($files.Count): $($fileInfo.Name)" -PercentComplete ([int](($fileIndex / [double]$files.Count) * 100)) $metaPayload = @{ FileIndex = $fileIndex Name = $fileInfo.Name Length = [int64]$fileInfo.Length Sha256 = $fileHash BlockSize = $BlockSize TotalBlocks = $totalBlocks BlockChecksumAlgorithm = $BlockChecksumAlgorithm } $metaAck = $null $metaWait = [System.Diagnostics.Stopwatch]::StartNew() while ($metaWait.Elapsed.TotalSeconds -lt $TimeoutSeconds) { $meta = New-KlipAroundMessage -SessionId $SessionId -Role Sender -MessageType FILE_META -Payload $metaPayload $published = Publish-KlipAroundMessage -Message $meta -TimeoutSeconds $TimeoutSeconds [void]$sentMessageIds.Add($published.MessageId) $remainingSeconds = [int][Math]::Ceiling($TimeoutSeconds - $metaWait.Elapsed.TotalSeconds) if ($remainingSeconds -lt 1) { break } $attemptTimeoutSeconds = [Math]::Min(10, $remainingSeconds) try { $metaAck = Wait-KlipAroundMessage -SessionId $SessionId -ExpectedRole Receiver -ExpectedMessageType FILE_META_ACK -TimeoutSeconds $attemptTimeoutSeconds -IgnoreMessageIds $sentMessageIds -SeenMessageIds $seenMessageIds break } catch { $isWaitTimeout = $_.Exception.Message -like "Timed out waiting for message types*" if (-not $isWaitTimeout) { throw } Write-Verbose "No FILE_META_ACK yet for file index $fileIndex. Re-sending FILE_META." } } $metaWait.Stop() if ($null -eq $metaAck) { throw "Timed out waiting for FILE_META_ACK for file index $fileIndex in session '$SessionId'." } if ([int]$metaAck.Payload.FileIndex -ne $fileIndex) { throw "Unexpected FILE_META_ACK for file index $($metaAck.Payload.FileIndex), expected $fileIndex." } $stream = [System.IO.File]::OpenRead($filePath) $streamHasher = if (-not $PrecomputeHash) { [System.Security.Cryptography.SHA256]::Create() } else { $null } $streamedFileHash = $null try { $nextSeq = 0 $pendingSrejSeqs = New-Object 'System.Collections.Generic.HashSet[int]' $blockCache = New-Object 'System.Collections.Generic.Dictionary[int,hashtable]' $hashedUntilSeq = 0 $lastAckSignature = $null $retries = 0 while ($nextSeq -lt $totalBlocks) { $sequencesToSend = New-Object System.Collections.Generic.List[int] if ($pendingSrejSeqs.Count -gt 0) { $sortedPending = @($pendingSrejSeqs | Sort-Object) foreach ($pendingSeq in $sortedPending) { if ($sequencesToSend.Count -ge $WindowSize) { break } [void]$sequencesToSend.Add([int]$pendingSeq) } } else { for ($i = 0; $i -lt $WindowSize -and $nextSeq + $i -lt $totalBlocks; $i++) { [void]$sequencesToSend.Add([int]($nextSeq + $i)) } } $blocks = New-Object System.Collections.Generic.List[hashtable] foreach ($sequence in $sequencesToSend) { if ($blockCache.ContainsKey($sequence)) { [void]$blocks.Add($blockCache[$sequence]) continue } $payload = & $readBlockBySequence -Stream $stream -Sequence $sequence -BlockSize $BlockSize -FileLength $fileInfo.Length if (-not $PrecomputeHash) { if ($sequence -ne $hashedUntilSeq) { throw "Unexpected hash sequence state at block $sequence." } if (($sequence + 1) -eq $totalBlocks) { [void]$streamHasher.TransformFinalBlock($payload, 0, $payload.Length) } else { [void]$streamHasher.TransformBlock($payload, 0, $payload.Length, $null, 0) } $hashedUntilSeq++ } $block = New-KlipAroundDataBlock -Sequence $sequence -Bytes $payload -ChecksumAlgorithm $BlockChecksumAlgorithm $blockCache[$sequence] = $block [void]$blocks.Add($block) } if ($blocks.Count -eq 0) { throw "Unexpected empty block burst at sequence $nextSeq." } $burstPayload = @{ FileIndex = $fileIndex StartSeq = [int]($sequencesToSend | Measure-Object -Minimum).Minimum Blocks = $blocks } $ack = $null $ackWaitSeconds = [Math]::Max(1, [int][Math]::Floor($TimeoutSeconds / 2.0)) for ($attempt = 0; $attempt -le $MaxRetries; $attempt++) { $burst = New-KlipAroundMessage -SessionId $SessionId -Role Sender -MessageType DATA_BURST -Payload $burstPayload $published = Publish-KlipAroundMessage -Message $burst -TimeoutSeconds $TimeoutSeconds [void]$sentMessageIds.Add($published.MessageId) try { $ack = Wait-KlipAroundMessage -SessionId $SessionId -ExpectedRole Receiver -ExpectedMessageType ACK_REPORT -TimeoutSeconds $ackWaitSeconds -IgnoreMessageIds $sentMessageIds -SeenMessageIds $seenMessageIds break } catch { if ($_.Exception.Message -notlike 'Timed out waiting for message types*' -or $attempt -eq $MaxRetries) { throw } Write-Verbose "No ACK_REPORT for file index $fileIndex. Re-sending DATA_BURST." } } if ([int]$ack.Payload.FileIndex -ne $fileIndex) { throw "Unexpected ACK_REPORT for file index $($ack.Payload.FileIndex), expected $fileIndex." } $ackNextSeq = [int]$ack.Payload.AckNextSeq $srejMissingSeqs = @() if ($ack.Payload.PSObject.Properties.Name -contains 'MissingSeqs' -and $null -ne $ack.Payload.MissingSeqs) { $srejMissingSeqs = @($ack.Payload.MissingSeqs | ForEach-Object { [int]$_ } | Where-Object { $_ -ge $ackNextSeq -and $_ -lt $totalBlocks } | Sort-Object -Unique) } if ($ackNextSeq -gt $nextSeq) { $nextSeq = $ackNextSeq } foreach ($pendingSeq in @($pendingSrejSeqs)) { if ($pendingSeq -lt $nextSeq) { [void]$pendingSrejSeqs.Remove($pendingSeq) } } foreach ($cachedSeq in @($blockCache.Keys)) { if ($cachedSeq -lt $nextSeq) { [void]$blockCache.Remove($cachedSeq) } } foreach ($missingSeq in $srejMissingSeqs) { if ($missingSeq -ge $nextSeq) { [void]$pendingSrejSeqs.Add($missingSeq) } } $signature = "$nextSeq|$($srejMissingSeqs -join ',')" if ($signature -eq $lastAckSignature) { $retries++ if ($retries -gt $MaxRetries) { throw "ACK did not advance beyond sequence $nextSeq after $MaxRetries retries." } } else { $retries = 0 $lastAckSignature = $signature } $percent = [int](($nextSeq / [double]$totalBlocks) * 100) Write-Progress -Id $fileProgressId -ParentId $overallProgressId -Activity "Sending $($fileInfo.Name)" -Status "Block $nextSeq of $totalBlocks acknowledged ($BlockChecksumAlgorithm)" -PercentComplete $percent } if (-not $PrecomputeHash) { if ($null -eq $streamHasher.Hash) { throw "Streaming SHA-256 hash was not finalized for '$($fileInfo.Name)'." } $streamedFileHash = -join ($streamHasher.Hash | ForEach-Object { $_.ToString('X2') }) } } finally { Write-Progress -Id $fileProgressId -ParentId $overallProgressId -Activity "Sending $($fileInfo.Name)" -Completed if ($streamHasher) { $streamHasher.Dispose() } $stream.Dispose() } if (-not $PrecomputeHash) { $fileHash = $streamedFileHash } $eofPayload = @{ FileIndex = $fileIndex Length = [int64]$fileInfo.Length Sha256 = $fileHash } $eofAck = $null $eofWait = [System.Diagnostics.Stopwatch]::StartNew() while ($eofWait.Elapsed.TotalSeconds -lt $TimeoutSeconds) { $eof = New-KlipAroundMessage -SessionId $SessionId -Role Sender -MessageType FILE_EOF -Payload $eofPayload $published = Publish-KlipAroundMessage -Message $eof -TimeoutSeconds $TimeoutSeconds [void]$sentMessageIds.Add($published.MessageId) $remainingSeconds = [int][Math]::Ceiling($TimeoutSeconds - $eofWait.Elapsed.TotalSeconds) if ($remainingSeconds -lt 1) { break } $attemptTimeoutSeconds = [Math]::Min(10, $remainingSeconds) try { $eofAck = Wait-KlipAroundMessage -SessionId $SessionId -ExpectedRole Receiver -ExpectedMessageType FILE_EOF_ACK -TimeoutSeconds $attemptTimeoutSeconds -IgnoreMessageIds $sentMessageIds -SeenMessageIds $seenMessageIds break } catch { $isWaitTimeout = $_.Exception.Message -like "Timed out waiting for message types*" if (-not $isWaitTimeout) { throw } Write-Verbose "No FILE_EOF_ACK yet for file index $fileIndex. Re-sending FILE_EOF." } } $eofWait.Stop() if ($null -eq $eofAck) { throw "Timed out waiting for FILE_EOF_ACK for file index $fileIndex in session '$SessionId'." } if ([int]$eofAck.Payload.FileIndex -ne $fileIndex) { throw "Unexpected FILE_EOF_ACK for file index $($eofAck.Payload.FileIndex), expected $fileIndex." } [void]$results.Add([pscustomobject]@{ FileIndex = $fileIndex Path = $filePath Name = $fileInfo.Name Length = [int64]$fileInfo.Length Sha256 = $fileHash Blocks = $totalBlocks }) } $finRetrySeconds = [Math]::Min(2, $TimeoutSeconds) $finPayload = @{ FileCount = $files.Count AckGraceSeconds = [Math]::Min($TimeoutSeconds, ($MaxRetries + 1) * $finRetrySeconds) + 2 } $finAck = $null $finWait = [System.Diagnostics.Stopwatch]::StartNew() $finRetries = 0 while ($finWait.Elapsed.TotalSeconds -lt $TimeoutSeconds -and $finRetries -le $MaxRetries) { $fin = New-KlipAroundMessage -SessionId $SessionId -Role Sender -MessageType FIN -Payload $finPayload $published = Publish-KlipAroundMessage -Message $fin -TimeoutSeconds $TimeoutSeconds [void]$sentMessageIds.Add($published.MessageId) $remainingSeconds = [int][Math]::Ceiling($TimeoutSeconds - $finWait.Elapsed.TotalSeconds) if ($remainingSeconds -lt 1) { break } $attemptTimeoutSeconds = [Math]::Min($finRetrySeconds, $remainingSeconds) try { $finAck = Wait-KlipAroundMessage -SessionId $SessionId -ExpectedRole Receiver -ExpectedMessageType FIN_ACK -TimeoutSeconds $attemptTimeoutSeconds -IgnoreMessageIds $sentMessageIds -SeenMessageIds $seenMessageIds break } catch { $isWaitTimeout = $_.Exception.Message -like "Timed out waiting for message types*" if (-not $isWaitTimeout) { throw } $finRetries++ Write-Verbose "No FIN_ACK yet. Re-sending FIN." } } $finWait.Stop() if ($null -eq $finAck) { throw "Timed out waiting for FIN_ACK in session '$SessionId'." } if ($PassThru) { return [pscustomobject]@{ SessionId = $SessionId FileCount = $results.Count BlockSize = $BlockSize WindowSize = $WindowSize BlockChecksumAlgorithm = $BlockChecksumAlgorithm Files = $results.ToArray() } } } finally { Write-Progress -Id $fileProgressId -ParentId $overallProgressId -Activity 'Sending file' -Completed Write-Progress -Id $overallProgressId -Activity 'KlipAround send' -Completed } } } |