fix: make is_package() read timeout configurable, default 30s

[mikesoares]

Problem

is_package() in src/drive_file_existence.py calls item.open(stream=True) with no timeout. When Apple's CDN (cvws.icloud-content.com) accepts the TCP connection but never delivers the HTTP response, urllib3 blocks indefinitely (read timeout=None). The sync process freezes with no log output and no recovery path.

Observed in production: the sync process was stuck in a kernel read() syscall on an ESTABLISHED TCP connection to Apple's CDN for weeks, with zero log output and no way to self-recover without a container restart.

Root cause

The call chain passes **kwargs all the way through to session.get():

is_package() → item.open(stream=True)
             → DriveNode.open(**kwargs)
             → DriveService.get_file(**kwargs)
             → session.get(cdn_url, **kwargs)   ← no timeout

Because no timeout is passed, urllib3 uses None (infinite wait). A TCP connection that stays ESTABLISHED at the OS level but delivers no HTTP response data will block forever.

Fix

Adds a drive.request_timeout config option (default: 30s). The timeout is threaded through collect_file_for_download and process_file to is_package(), which passes it to item.open() via the existing **kwargs passthrough — no changes needed in icloudpy.

Users who want to adjust or disable the timeout can set request_timeout in their config.yaml:

drive:
  request_timeout: 60  # seconds; omit to use the default of 30

Changes

• src/__init__.py — DEFAULT_REQUEST_TIMEOUT_SEC = 30
• src/config_parser.py — get_drive_request_timeout() getter
• src/drive_file_existence.py — is_package(item, timeout=DEFAULT_REQUEST_TIMEOUT_SEC)
• src/drive_parallel_download.py — collect_file_for_download resolves and passes timeout
• src/drive_sync_directory.py — threads config through _process_file_item
• src/sync_drive.py — process_file resolves and passes timeout
• config.yaml — documents the new option (commented out, showing default)

Tests

• test_get_drive_request_timeout — config with value set
• test_get_drive_request_timeout_default — config missing the key (returns default)
• test_get_drive_request_timeout_none_config — None config (returns default)
• test_is_package_read_timeout — ReadTimeout is caught, returns False, open() called with timeout=30

Note: there are 20 pre-existing test failures in test_sync.py and test_usage.py in the local environment due to a missing /config/ path — these fail identically on the unmodified main branch and are unrelated to this change.

[mikesoares]

Hi @mandarons — just wanted to flag a couple of things:

Tests pass. The build-and-push-docker CI failure is a fork-PR permissions issue (denied: installation not allowed to Write organization package) — the workflow tries to push to ghcr.io/mandarons/icloud-docker from a fork, which GitHub doesn't allow without explicit package write grants. It's not a code problem; the test and cache-requirements-install jobs both pass cleanly.

Production context. This fix came from a real incident — my sync container was stuck in a kernel read() syscall on an ESTABLISHED TCP connection to Apple's CDN (cvws.icloud-content.com) for ~8 weeks with zero log output and no self-recovery. The freeze is reproducible whenever Apple's CDN holds the TCP handshake open but never delivers HTTP response bytes.

Happy to adjust anything if you'd like changes before merging. Thanks for maintaining the project!

[Copilot]

Pull request overview

Adds a configurable timeout for the iCloud Drive “package detection” request path to prevent indefinite hangs when probing items via is_package(), wiring the value from config through the drive sync call chain.

Changes:

• Introduces drive.request_timeout with a default of 30 seconds (DEFAULT_REQUEST_TIMEOUT_SEC).
• Adds config_parser.get_drive_request_timeout() and threads the resolved timeout into is_package(..., timeout=...).
• Adds/updates tests and test config fixtures covering default/value behavior and ReadTimeout handling.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/__init__.py	Adds the default request-timeout constant.
src/config_parser.py	Adds a getter for drive.request_timeout.
src/drive_file_existence.py	Applies the timeout to item.open() in is_package().
src/sync_drive.py	Resolves timeout from config and passes it to is_package() in legacy process_file.
src/drive_sync_directory.py	Threads config through file processing to reach timeout resolution.
src/drive_parallel_download.py	Resolves timeout from config and passes it to is_package() during task collection.
config.yaml	Documents the new drive.request_timeout option.
tests/data/test_config.yaml	Adds request_timeout to the test fixture config.
tests/test_config_parser.py	Adds tests for explicit/default/None-config timeout retrieval.
tests/test_sync_drive.py	Adds test ensuring ReadTimeout is handled and timeout is passed to open().