This PR addresses critical issues with incomplete and corrupted downloads that result in half-black images and PermissionError(13) failures during file operations.

Problem

Users reported that downloaded images would sometimes appear corrupted (showing as half-black) and downloads would fail with:

PermissionError(13, 'The process cannot access the file because it is being used by another process')

The root cause was that files were being renamed from .tmp to their final names even when downloads were incomplete, and there was no verification that the downloaded file size matched the expected size from HTTP headers.

Solution

1. File Integrity Verification

• Size Verification: Compare actual downloaded file size with expected size from Content-Length or Content-Range headers
• Content-Length Fallback: Use Content-Length header when Content-Range is not available
• HTTP Status Fix: Accept both 206 (Partial Content) and 200 (OK) responses for better server compatibility

2. Enhanced Error Handling

• PermissionError Retry: Automatic retry up to 3 times with exponential backoff (0.1s, 0.2s, 0.3s) when file rename operations fail
• Atomic Operations: Ensure temporary files are only renamed when download is verified complete
• Cleanup on Failure: Properly remove .tmp files when operations fail

3. Optional Checksum Verification

• SHA-256 Checksums: Optional checksum calculation during download with logging for additional integrity verification
• Configurable: Disabled by default to minimize performance impact

Configuration

Two new configuration options are available:

# File integrity verification (enabled by default)
KTOOLBOX_DOWNLOADER__VERIFY_FILE_INTEGRITY=true

# Optional checksum verification (disabled by default)  
KTOOLBOX_DOWNLOADER__CHECKSUM_VERIFICATION=false

Testing

• Added comprehensive test suite for new integrity checking functionality
• Verified backward compatibility with existing download workflows
• Manual testing confirmed fix for both size mismatch detection and PermissionError handling

Impact

• ✅ Eliminates corrupted/half-black images by detecting incomplete downloads
• ✅ Resolves PermissionError(13) issues through automatic retry with backoff
• ✅ Provides optional checksum verification for enhanced data integrity
• ✅ Maintains full backward compatibility - no configuration changes required
• ✅ Includes comprehensive documentation and troubleshooting guide

Fixes #255.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.