Add parallel download support to fly_fetch()

New `workers` param enables concurrent downloads via furrr/future.
Default remains sequential (workers = 1) for safety.

Fixes #21

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

Author: NewGraphEnvironment

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: fly
 Title: Airphoto Footprint Estimation and Coverage Selection
-Version: 0.2.0
+Version: 0.2.1
 Authors@R: c(
     person("Allan", "Irvine", , "al@newgraphenvironment.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-3495-2128")),
@@ -26,6 +26,8 @@ Imports:
     stringr
 Suggests:
     bookdown,
+    furrr,
+    future,
     testthat (>= 3.0.0),
     knitr,
     rmarkdown

NEWS.md

@@ -1,5 +1,10 @@
 # fly (development version)
 
+## 0.2.1 (2026-03-11)
+
+- Add `workers` parameter to `fly_fetch()` for parallel downloads via `furrr`/`future` ([#21](https://github.com/NewGraphEnvironment/fly/issues/21))
+- Add `furrr` and `future` to Suggests
+
 ## 0.2.0 (2026-03-11)
 
 - **BREAKING:** Remove `fly_query_habitat()`, `fly_query_lakes()`, `fly_trim_habitat()` — migrate to [fresh](https://github.com/NewGraphEnvironment/fresh) ([#19](https://github.com/NewGraphEnvironment/fly/issues/19))

R/fly_fetch.R

@@ -14,6 +14,9 @@
 #'   not exist.
 #' @param overwrite If `FALSE` (default), skip files that already exist
 #'   in `dest_dir`.
+#' @param workers Number of parallel download workers. `1` (default) runs
+#'   sequentially. Values greater than 1 use [furrr::future_map_dfr()] with
+#'   [future::multisession] — requires `furrr` and `future` packages.
 #' @return A tibble with columns `airp_id`, `url`, `dest`, and `success`.
 #'
 #' @details
@@ -28,6 +31,10 @@
 #' Photos with missing (`NA` or empty) URLs are skipped and reported as
 #' `success = FALSE` in the output.
 #'
+#' When `workers > 1`, a [future::multisession] plan is set for the
+#' duration of the call and restored on exit. Each download is independent
+#' so parallelism is safe.
+#'
 #' @examples
 #' centroids <- sf::st_read(system.file("testdata/photo_centroids.gpkg", package = "fly"))
 #'
@@ -38,7 +45,8 @@
 #'
 #' @export
 fly_fetch <- function(photos_sf, type = "thumbnail",
-                         dest_dir = "photos", overwrite = FALSE) {
+                      dest_dir = "photos", overwrite = FALSE,
+                      workers = 1) {
   type <- match.arg(type, c("thumbnail", "flight_log", "calibration", "georef"))
 
   url_col <- switch(type,
@@ -63,29 +71,51 @@ fly_fetch <- function(photos_sf, type = "thumbnail",
     seq_len(nrow(photos_sf))
   }
 
-  results <- dplyr::tibble(
-    airp_id = ids,
-    url     = urls,
-    dest    = NA_character_,
-    success = FALSE
-  )
+  rows <- lapply(seq_along(urls), function(i) {
+    list(airp_id = ids[i], url = urls[i])
+  })
 
-  for (i in seq_len(nrow(results))) {
-    u <- results$url[i]
-    if (is.na(u) || u == "") next
+  # Self-contained download function that workers can serialize
+  dl_fn <- function(row) {
+    airp_id <- row$airp_id
+    u <- row$url
+
+    if (is.na(u) || u == "") {
+      return(dplyr::tibble(
+        airp_id = airp_id, url = u,
+        dest = NA_character_, success = FALSE
+      ))
+    }
 
     dest_file <- file.path(dest_dir, basename(u))
-    results$dest[i] <- dest_file
 
     if (!overwrite && file.exists(dest_file)) {
-      results$success[i] <- TRUE
-      next
+      return(dplyr::tibble(
+        airp_id = airp_id, url = u,
+        dest = dest_file, success = TRUE
+      ))
     }
 
-    results$success[i] <- tryCatch({
+    ok <- tryCatch({
       utils::download.file(u, dest_file, mode = "wb", quiet = TRUE)
       file.exists(dest_file) && file.size(dest_file) > 0
     }, error = function(e) FALSE)
+
+    dplyr::tibble(
+      airp_id = airp_id, url = u,
+      dest = dest_file, success = ok
+    )
+  }
+
+  if (workers > 1) {
+    rlang::check_installed(c("furrr", "future"),
+                           reason = "for parallel downloads (workers > 1)")
+    old_plan <- future::plan(future::multisession, workers = workers)
+    on.exit(future::plan(old_plan), add = TRUE)
+    results <- furrr::future_map_dfr(rows, dl_fn,
+      .options = furrr::furrr_options(packages = "dplyr"))
+  } else {
+    results <- purrr::map_dfr(rows, dl_fn)
   }
 
   n_ok <- sum(results$success)

man/fly_fetch.Rd

@@ -58,6 +58,21 @@ test_that("fly_fetch rejects invalid type", {
   expect_error(fly_fetch(centroids, type = "bogus"))
 })
 
+test_that("fly_fetch supports parallel downloads with workers > 1", {
+  skip_if_not_installed("furrr")
+  skip_if_not_installed("future")
+  centroids <- sf::st_read(testdata_path("photo_centroids.gpkg"), quiet = TRUE)
+  dest <- file.path(tempdir(), "fly_test_parallel")
+  unlink(dest, recursive = TRUE)
+
+  result <- fly_fetch(centroids[1:2, ], type = "thumbnail",
+                      dest_dir = dest, workers = 2)
+  expect_s3_class(result, "tbl_df")
+  expect_equal(nrow(result), 2)
+  downloaded <- result[result$success, ]
+  expect_true(all(file.exists(downloaded$dest)))
+})
+
 test_that("fly_fetch maps type to correct URL column", {
   centroids <- sf::st_read(testdata_path("photo_centroids.gpkg"), quiet = TRUE)
   dest <- file.path(tempdir(), "fly_test_flight_log")