-
-
Notifications
You must be signed in to change notification settings - Fork 5
Retry
icloudpd-rs is designed to handle unreliable network conditions and transient iCloud API failures.
Errors are classified as transient or permanent:
| Type | Examples | Retried? |
|---|---|---|
| Transient | HTTP 5xx, 429 (rate limit), timeouts, connection resets, checksum mismatch | Yes |
| Permanent | HTTP 4xx (except 429), disk I/O errors | No |
Checksum mismatches are treated as transient because they typically indicate a truncated transfer or expired CDN URL, not actual data corruption.
Retries use exponential backoff with jitter. The initial delay is configured by --retry-delay (default: 5 seconds), and doubles with each attempt:
| Attempt | Approximate delay |
|---|---|
| 1st retry | ~5s |
| 2nd retry | ~10s |
| 3rd retry | ~20s |
Random jitter is added to prevent multiple concurrent downloads from retrying at the same time. The maximum delay is capped at 60 seconds.
The download pipeline has two phases:
-
Main pass — Downloads all assets with per-file retries (up to
--max-retries, default: 3) - Cleanup pass — Re-fetches CDN URLs from iCloud for all failures, then retries them at concurrency 1
The cleanup pass addresses a common failure mode: CDN download URLs expire during long syncs. By re-fetching URLs from iCloud, the cleanup pass gets fresh URLs that are more likely to succeed. Running at concurrency 1 gives large files full bandwidth.
File downloads use a dedicated HTTP client with no total request timeout, preventing large files from being killed mid-transfer. Stalled connections are detected via a 120s read timeout (no bytes received for 120 seconds). API calls use a separate 30s total timeout for fast failure.
Retries apply not just to downloads but also to API calls:
- Album and photo enumeration
- Zone listing
- Library fetching
These use the same backoff strategy.
After all downloads complete, a summary is printed with:
- Total assets processed
- Successful downloads
- Failed downloads
- Elapsed time