Downloads, cache, and reproducibility

bluertopo_download() is for workflows where the durable deliverable is the original NOAA BlueTopo source file set. The function preserves NOAA basenames, keeps GeoTIFF and RAT sidecar files unmodified, verifies SHA-256 checksums by default, and writes manifests for future auditing.

Plan first

plan <- bluertopo_download(
  aoi,
  path = file.path(tempdir(), "bluertopo-downloads"),
  coverage = "fill",
  dry_run = TRUE
)

Dry runs return planned assets without creating the destination directory.

Download with verification

manifest <- bluertopo_download(
  aoi,
  path = file.path(tempdir(), "bluertopo-downloads"),
  rat = TRUE,
  verify = "sha256",
  on_exists = "verify"
)

Each row records the tile identifier, asset type, source URL, destination path, verification status, SHA-256 value, attempts, and timestamps. A fixed manifest is written at the download root for convenience, and query-addressed manifest copies are written under manifests/ when a query hash is available.

Existing files

on_exists = "verify" reuses an existing file only when verification succeeds. on_exists = "skip" records a skipped file without verification. on_exists = "replace" redownloads the asset.

reused <- bluertopo_download(
  aoi,
  path = file.path(tempdir(), "bluertopo-downloads"),
  on_exists = "verify"
)

Package cache

bluertopo() uses the package cache for catalog files, downloaded source assets, and VRTs. Cache roots are marked with .bluertopo-cache.json before package-owned content is written. The default cache is session-temporary; set options(bluertopo.cache_dir = "/path/to/cache") when a persistent cache is wanted.

bluertopo_cache_dir()

bluertopo_cache_clear() clears only the configured package cache. It refuses unmarked directories, suspicious roots, and symlinked cache paths.

bluertopo_cache_clear(confirm = TRUE)

Concurrency and retries

Downloads are currently deterministic and single-worker. workers = NULL and workers = 1 are accepted; higher values are rejected until bounded parallel downloads are implemented. Individual assets still use retry/backoff behavior for transient transfer failures.

manifest <- bluertopo_download(
  aoi,
  path = file.path(tempdir(), "bluertopo-downloads"),
  workers = 1,
  retries = 3
)