Add parallel concurrent downloads (#1)

* Add parallel concurrent downloads and --recent early termination

Two-phase download design: sequential filter pass builds task list,
then buffer_unordered downloads with --threads-num concurrency.
Remove --until-found (will be replaced by stateful incremental sync).
Add --recent N early termination to stop API enumeration after N photos.
Add progress logging during photo enumeration and service init.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add 19 unit tests and apply idiomatic Rust fixes

- Add CLI, config, download, and album unit tests (56 total)
- Remove dead dry_run guards in download phase 2
- Modernize ref patterns to idiomatic & style
- Fix stale doc comment in album.rs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Rob Hooper <rhoopr@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: rhoopr

.gitignore

@@ -1,4 +1,5 @@
 .claude/
+.testplans/
 CLAUDE.md
 TODO.md
 .DS_Store

CHANGES.md

@@ -0,0 +1,4 @@
+# Behavioral Changes from Python icloud-photos-downloader
+
+- `--recent N` stops fetching from the API after N photos instead of enumerating the entire library first
+- `--until-found` removed — will be replaced by stateful incremental sync with local database

README.md

@@ -19,7 +19,7 @@ Full feature parity with the Python icloudpd, including:
 - **Complete Apple authentication** — SRP-6a, two-factor authentication, session persistence with trust tokens
 - **Full iCloud Photos API** — albums, smart folders, shared libraries, asset enumeration with pagination
 - **Flexible downloads** — multiple size variants (original, medium, thumb, adjusted, alternative), live photos, RAW files
-- **Content filtering** — by media type, date range, album, recency, and consecutive-found early exit
+- **Content filtering** — by media type, date range, album, recency
 - **File organization** — date-based folder structures, filename sanitization, deduplication policies
 - **EXIF metadata** — read and write DateTimeOriginal, file modification time sync
 - **XMP sidecar export** — GPS, keywords, ratings, title, description, orientation
@@ -71,6 +71,8 @@ icloudpd-rs --username my@email.address --directory /photos
 | `--auth-only` | Only authenticate, don't download |
 | `-l, --list-albums` | List available albums |
 | `--list-libraries` | List available libraries |
+| `--recent N` | Download only the N most recent photos |
+| `--threads-num N` | Number of concurrent downloads (default: 1) |
 | `--dry-run` | Preview without modifying files or iCloud |
 
 ## License

src/cli.rs

@@ -50,9 +50,9 @@ pub struct Cli {
     #[arg(long)]
     pub recent: Option<u32>,
 
-    /// Download until finding X consecutive existing photos
-    #[arg(long)]
-    pub until_found: Option<u32>,
+    /// Number of concurrent download threads (default: 1)
+    #[arg(long = "threads-num", default_value_t = 1, value_parser = clap::value_parser!(u16).range(1..))]
+    pub threads_num: u16,
 
     /// Don't download videos
     #[arg(long)]
@@ -142,3 +142,64 @@ pub struct Cli {
     #[arg(long)]
     pub only_print_filenames: bool,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::Parser;
+
+    fn parse(args: &[&str]) -> Cli {
+        Cli::try_parse_from(args).unwrap()
+    }
+
+    fn base_args() -> Vec<&'static str> {
+        vec!["icloudpd-rs", "--username", "test@example.com"]
+    }
+
+    #[test]
+    fn test_threads_num_defaults_to_1() {
+        let cli = parse(&base_args());
+        assert_eq!(cli.threads_num, 1);
+    }
+
+    #[test]
+    fn test_threads_num_accepts_valid_value() {
+        let mut args = base_args();
+        args.extend(["--threads-num", "8"]);
+        let cli = parse(&args);
+        assert_eq!(cli.threads_num, 8);
+    }
+
+    #[test]
+    fn test_threads_num_rejects_zero() {
+        let mut args = base_args();
+        args.extend(["--threads-num", "0"]);
+        assert!(Cli::try_parse_from(&args).is_err());
+    }
+
+    #[test]
+    fn test_dry_run_default_false() {
+        let cli = parse(&base_args());
+        assert!(!cli.dry_run);
+    }
+
+    #[test]
+    fn test_size_default_original() {
+        let cli = parse(&base_args());
+        assert!(matches!(cli.size, VersionSize::Original));
+    }
+
+    #[test]
+    fn test_recent_none_by_default() {
+        let cli = parse(&base_args());
+        assert!(cli.recent.is_none());
+    }
+
+    #[test]
+    fn test_recent_accepts_value() {
+        let mut args = base_args();
+        args.extend(["--recent", "50"]);
+        let cli = parse(&args);
+        assert_eq!(cli.recent, Some(50));
+    }
+}

src/config.rs

@@ -15,7 +15,7 @@ pub struct Config {
     pub size: VersionSize,
     pub live_photo_size: LivePhotoSize,
     pub recent: Option<u32>,
-    pub until_found: Option<u32>,
+    pub threads_num: u16,
     pub skip_videos: bool,
     pub skip_photos: bool,
     pub skip_live_photos: bool,
@@ -92,7 +92,7 @@ impl Config {
             size: cli.size,
             live_photo_size: cli.live_photo_size,
             recent: cli.recent,
-            until_found: cli.until_found,
+            threads_num: cli.threads_num,
             skip_videos: cli.skip_videos,
             skip_photos: cli.skip_photos,
             skip_live_photos: cli.skip_live_photos,
@@ -198,4 +198,40 @@ mod tests {
         assert!(parse_date_or_interval("not-a-date").is_err());
         assert!(parse_date_or_interval("").is_err());
     }
+
+    fn make_cli(overrides: impl FnOnce(&mut crate::cli::Cli)) -> crate::cli::Cli {
+        use clap::Parser;
+        let mut cli = crate::cli::Cli::try_parse_from([
+            "icloudpd-rs", "--username", "u@example.com",
+        ]).unwrap();
+        overrides(&mut cli);
+        cli
+    }
+
+    #[test]
+    fn test_from_cli_threads_num_passthrough() {
+        let cli = make_cli(|c| c.threads_num = 4);
+        let cfg = Config::from_cli(cli).unwrap();
+        assert_eq!(cfg.threads_num, 4);
+    }
+
+    #[test]
+    fn test_from_cli_skip_flags() {
+        let cli = make_cli(|c| {
+            c.skip_videos = true;
+            c.skip_photos = true;
+            c.skip_live_photos = true;
+        });
+        let cfg = Config::from_cli(cli).unwrap();
+        assert!(cfg.skip_videos);
+        assert!(cfg.skip_photos);
+        assert!(cfg.skip_live_photos);
+    }
+
+    #[test]
+    fn test_from_cli_dry_run() {
+        let cli = make_cli(|c| c.dry_run = true);
+        let cfg = Config::from_cli(cli).unwrap();
+        assert!(cfg.dry_run);
+    }
 }