R/download.R

Defines functions .build_tasks .run_downloads caged_download .is_cached .cache_dir .find_7zip .list_text_files .extract_7z .download_file .hf_url

Documented in caged_download

# download.R
# Lógica de construção de URLs, download dos .7z e gestão de cache local
# Fonte: HuggingFace Dataset alexsandroprado/caged (HTTPS)

# -- URLs do HuggingFace -------------------------------------------------------

#' Constrói a URL HTTPS do arquivo no repositório HuggingFace
#'
#' Estrutura de pastas no repositório:
#'   caged_novo/<AAAA>/<CAGEDMOV|FOR|EXC><AAAAMM>.7z
#'   caged_antigo/<AAAA>/<CAGEDEST_MM AAAA>.7z
#'   CAGED_AJUSTES/<AAAA>/CAGEDEST_AJUSTES_MMAAAA.7z
#'
#' @noRd
.hf_url <- function(year, month, type = "MOV") {
  competencia <- .format_period(year, month)
  mm          <- sprintf("%02d", month)

  if (type == "ANTIGO") {
    nome   <- glue::glue("CAGEDEST_{mm}{year}.7z")
    subdir <- glue::glue("{.HF_PASTA_ANTIGO}/{year}")
  } else if (type == "AJUSTES") {
    # Anos 2002-2009: arquivo anual em pasta "2002a2009"
    # Anos 2010-2019: arquivo mensal por ano
    if (year <= 2009L) {
      nome   <- glue::glue("CAGEDEST_AJUSTES_{year}.7z")
      subdir <- glue::glue("{.HF_PASTA_AJUSTES}/2002a2009")
    } else {
      nome   <- glue::glue("CAGEDEST_AJUSTES_{mm}{year}.7z")
      subdir <- glue::glue("{.HF_PASTA_AJUSTES}/{year}")
    }
  } else {
    prefixo <- switch(type,
      MOV = "CAGEDMOV",
      FOR = "CAGEDFOR",
      EXC = "CAGEDEXC",
      cli::cli_abort(gettext("Invalid type: {.val {type}}. Use MOV, FOR, EXC, ANTIGO or AJUSTES."))
    )
    nome   <- glue::glue("{prefixo}{competencia}.7z")
    subdir <- glue::glue("{.HF_PASTA_NOVO}/{year}/{competencia}")
  }

  glue::glue("{.HF_BASE}/{subdir}/{nome}")
}

#' Baixa um único arquivo .7z do HuggingFace com retry
#'
#' Usa httr2 para download HTTPS com timeout, retry e seguimento de redirecionamentos.
#' Trata arquivos inexistentes (HTTP 404/403) silenciosamente retornando NULL.
#'
#' @noRd
.download_file <- function(url, destfile, timeout = 300,
                            sleep_fn = getOption("datacaged.sleep_fn", Sys.sleep)) {
  # Tenta até 3 vezes com backoff exponencial (5 s, 10 s).
  for (tentativa in seq_len(3)) {
    resultado <- tryCatch({
      resp <- httr2::request(url) |>
        httr2::req_timeout(timeout) |>
        httr2::req_retry(max_tries = 1L) |>    # retry interno desativado; gerenciamos aqui
        httr2::req_error(is_error = \(r) FALSE) |>  # do not raise error on 4xx/5xx
        httr2::req_perform()

      status <- httr2::resp_status(resp)

      # Arquivo não encontrado no repositório --- retorna NULL
      if (status %in% c(404L, 403L)) {
        if (file.exists(destfile)) unlink(destfile)
        return(invisible(NULL))
      }

      # Qualquer outro erro HTTP
      if (status >= 400L) {
        return(1L)
      }

      # Sucesso: grava em arquivo temporario e renomeia ao final. Assim uma
      # gravacao interrompida (disco cheio, Ctrl+C) nunca deixa um arquivo
      # parcial com o nome final, que o cache trataria como valido.
      parcial <- paste0(destfile, ".part")
      on.exit(if (file.exists(parcial)) unlink(parcial), add = TRUE)
      writeBin(httr2::resp_body_raw(resp), parcial)
      if (file.exists(destfile)) unlink(destfile)
      if (!file.rename(parcial, destfile)) stop("could not move downloaded file")
      0L
    }, error = function(e) {
      1L
    })

    # Arquivo inexistente no repositório
    if (identical(resultado, 404L)) {
      if (file.exists(destfile)) unlink(destfile)
      return(invisible(NULL))
    }

    # Sucesso
    if (identical(resultado, 0L) && file.exists(destfile) && file.size(destfile) > 0) {
      return(invisible(destfile))
    }

    # Falha --- espera antes de tentar novamente
    if (tentativa < 3) sleep_fn(5 * tentativa)
  }

  # Esgotou tentativas
  if (file.exists(destfile)) unlink(destfile)
  cli::cli_warn(gettext("Failed to download {.url {url}} after 3 attempts. Skipping."))
  invisible(NULL)
}

# -- Extração dos .7z ----------------------------------------------------------

#' Extrai um arquivo .7z para um diretório
#' Extrai arquivo comprimido com múltiplos fallbacks
#' Ordem: archive -> unzip -> 7-Zip (Rtools/PATH/Program Files)
#' @noRd
.extract_7z <- function(path, exdir) {
  if (!file.exists(path)) cli::cli_abort(gettext("File not found: {.path {path}}"))

  # Tentativa 1: archive (libarchive) -- funciona para Novo CAGED (LZMA) e CAGED antigo (PPMd)
  ok <- tryCatch({
    suppressWarnings(archive::archive_extract(path, dir = exdir))
    TRUE
  }, error = function(e) FALSE)

  if (ok) {
    txts <- .list_text_files(exdir)
    if (length(txts) > 0) return(txts)
  }

  # Tentativa 2: utils::unzip -- ZIPs renomeados para .7z
  ok2 <- tryCatch({
    utils::unzip(path, exdir = exdir, junkpaths = TRUE)
    TRUE
  }, error = function(e) FALSE, warning = function(w) FALSE)

  if (ok2) {
    txts <- .list_text_files(exdir)
    if (length(txts) > 0) return(txts)
  }

  # Tentativa 3: 7-Zip -- necessário para PPMd (CAGED antigo)
  exe <- .find_7zip()
  if (!is.null(exe)) {
    path_norm  <- normalizePath(path,  winslash = "\\", mustWork = FALSE)
    exdir_norm <- normalizePath(exdir, winslash = "\\", mustWork = FALSE)

    if (.Platform$OS.type == "windows") {
      cmd <- paste0(
        '"', exe, '" e "', path_norm, '" "-o', exdir_norm, '" -y'
      )
      ret <- tryCatch(
        shell(cmd, intern = TRUE, mustWork = FALSE),
        error = function(e) structure(character(0), status = 1L)
      )
      status <- attr(ret, "status") %||% 0L
      if (!is.integer(status)) status <- as.integer(status)
    } else {
      ret <- tryCatch(
        system2(exe,
                args   = c("e", shQuote(path_norm),
                           paste0("-o", shQuote(exdir_norm)), "-y"),
                stdout = TRUE, stderr = TRUE),
        error = function(e) structure(character(0), status = 1L)
      )
      status <- attr(ret, "status") %||% 0L
      if (!is.integer(status)) status <- as.integer(status)
    }

    if (status == 0L) {
      txts <- .list_text_files(exdir)
      if (length(txts) > 0) return(txts)
    }
  }

  cli::cli_abort(c(
    gettext("Failed to extract {.path {basename(path)}}."),
    "i" = gettext("The file uses PPMd compression (advanced 7-Zip)."),
    "i" = gettext("Install 7-Zip: {.url https://www.7-zip.org/download.html}"),
    "i" = gettext("The standard Windows installer is sufficient (no need to add to PATH).")
  ))
}

#' Lista arquivos .txt/.csv extraídos em um diretório
#' @noRd
.list_text_files <- function(exdir) {
  list.files(exdir, full.names = TRUE,
             pattern = "\\.txt$|\\.csv$|\\.TXT$|\\.CSV$")
}

#' Encontra o executável do 7-Zip
#' Verifica PATH, Rtools e Program Files (Windows)
#' @return caminho do executável ou NULL
#' @noRd
.find_7zip <- function() {
  no_path <- Sys.which(c("7z", "7za", "7zz"))
  no_path <- no_path[nchar(no_path) > 0]
  if (length(no_path) > 0) return(unname(no_path[1]))

  if (.Platform$OS.type == "windows") {
    candidatos <- c(
      "C:/Program Files/7-Zip/7z.exe",
      "C:/Program Files (x86)/7-Zip/7z.exe",
      file.path(Sys.getenv("LOCALAPPDATA"), "Programs/7-Zip/7z.exe"),
      file.path(Sys.getenv("RTOOLS45_HOME", "C:/rtools45"), "usr/bin/7z.exe"),
      file.path(Sys.getenv("RTOOLS44_HOME", "C:/rtools44"), "usr/bin/7z.exe"),
      file.path(Sys.getenv("RTOOLS43_HOME", "C:/rtools43"), "usr/bin/7z.exe")
    )
    for (cand in candidatos) {
      if (file.exists(cand)) return(cand)
    }
  }
  NULL
}

# -- Cache local ---------------------------------------------------------------

#' Retorna o diretório de cache padrão do pacote
#' @noRd
.cache_dir <- function(destdir = NULL) {
  dir <- destdir %||% tools::R_user_dir("datacaged", "cache")
  if (!dir.exists(dir)) dir.create(dir, recursive = TRUE)
  dir
}

#' Verifica se um arquivo já está em cache (existe e não está vazio)
#' @noRd
.is_cached <- function(destfile) {
  file.exists(destfile) && file.size(destfile) > 0
}

# -- Função pública: caged_download -------------------------------------------

#' Baixa microdados do CAGED do repositório HuggingFace
#'
#' Baixa os arquivos `.7z` para um diretório local, criando uma estrutura
#' de pastas por ano. Arquivos já baixados não são re-baixados (cache local).
#'
#' Para o **Novo CAGED** (2020+), são baixados três tipos por competência:
#' movimentações (`MOV`), fora do prazo (`FOR`) e exclusões (`EXC`).
#'
#' Para o **CAGED antigo** (até 2019), o download é nacional (arquivo único por competência).
#'
#' @param years integer vector. Desired years (ex: `2020:2023`).
#' @param months integer vector. Desired months (1--12). Default: `seq_len(12L)` (todos os meses).
#' @param states character vector or NULL. **Ignorado** --- mantido por compatibilidade.
#' @param destdir character or NULL. Local directory to save os arquivos.
#'   If NULL, uses the default directory do sistema via
#'   `tools::R_user_dir("datacaged", "cache")`.
#' @param force logical. If TRUE, re-downloads files already in cache.
#'   Default: FALSE.
#' @param timeout integer. Timeout por arquivo em segundos. Default: 300.
#' @param workers integer. Number of parallel downloads. Default: 3.
#'   Use `1` for sequential mode. Controlled via
#'   `options(datacaged.workers = N)`.
#'
#' @return data.frame invisível com colunas `arquivo`, `competencia`, `type`,
#'   `uf` e `status` (baixado / cache / nao_encontrado / erro).
#'
#' @examples
#' \dontrun{
#' # Baixa Novo CAGED de jan-mar/2023
#' manifest <- caged_download(years = 2023, months = c(1L, 2L, 3L))
#'
#' # Ver status de cada arquivo (baixado / cache / nao_encontrado / erro)
#' dplyr::count(manifest, status)
#'
#' # Baixa CAGED antigo de 2018
#' caged_download(years = 2018)
#'
#' # Forçar re-download mesmo com cache
#' caged_download(years = 2023, months = 1, force = TRUE)
#'
#' # Salvar em diretório personalizado
#' caged_download(years = 2023, months = 1, destdir = file.path(tempdir(), "caged_cache"))
#' }
#'
#' @details
#' **Compatibilidade entre plataformas:**
#'
#' | Recurso | Windows | macOS | Linux |
#' |---|---|---|---|
#' | Download (HTTPS) | OK | OK | OK |
#' | Downloads paralelos | OK | OK | OK |
#' | Novo CAGED (2020+, LZMA) | OK | OK | OK |
#' | CAGED antigo (PPMd) | (!) | (!) | (!) |
#'
#' O CAGED antigo (pré-2020) usa PPMd e requer 7-Zip instalado.
#' O Novo CAGED usa LZMA e funciona em todas as plataformas sem dependências extras.
#'
#' @seealso [caged_load()] para o pipeline completo (download + parse + DuckDB).
#' @seealso [caged_hf_files()] para listar competências disponíveis no HuggingFace.
#' @export
caged_download <- function(years,
                           months  = seq_len(12L),
                           states  = NULL,
                           destdir = NULL,
                           force   = FALSE,
                           timeout = 300,
                           workers = getOption("datacaged.workers", min(3L, future::availableCores()))) {
  years  <- .validate_years(years)
  months <- .validate_months(months)
  states <- .validate_states(states) %||% names(.UF_CODIGOS)
  cache  <- .cache_dir(destdir)

  tasks <- .build_tasks(years, months)
  n     <- nrow(tasks)

  if (n == 0) {
    cli::cli_inform(gettext("No valid competency to download."))
    return(invisible(tibble::tibble()))
  }

  workers <- max(1L, min(as.integer(workers), n))

  cli::cli_h1(gettext("Download CAGED Microdata"))
  cli::cli_inform(c(
    "i" = gettext("{n} file{?s} to process"),
    "i" = paste0("Fonte: ", .HF_BASE),
    "i" = gettext("Cache: {.path {cache}}"),
    "i" = gettext("Workers: {workers}")
  ))

  resultado_final <- .run_downloads(tasks, cache, force, timeout, workers)

  resumo <- dplyr::count(resultado_final, status)
  cli::cli_h2(gettext("Summary"))
  purrr::walk2(resumo$status, resumo$n, function(s, cnt) {
    icon <- switch(s,
      baixado        = cli::col_green("v"),
      cache          = cli::col_blue("o"),
      nao_encontrado = cli::col_yellow("!"),
      erro           = cli::col_red("x"),
      "?"
    )
    cli::cli_inform("{icon} {s}: {cnt}")
  })

  invisible(resultado_final)
}


#' Executa o download de uma tabela de tarefas e retorna o manifest
#' Função interna reutilizável por caged_download e caged_adjustments_load
#' @noRd
.run_downloads <- function(tasks, cache, force, timeout, workers = 1L) {
  n <- nrow(tasks)

  # Pré-cria todos os diretórios antes de qualquer download (evita race condition)
  destfiles <- file.path(cache, tasks$subdir, tasks$nome_arquivo)
  dirs      <- unique(dirname(destfiles))
  for (d in dirs) {
    if (!dir.exists(d)) dir.create(d, recursive = TRUE)
  }

  # Função que processa uma única tarefa
  .processar_tarefa <- function(i) {
    t        <- tasks[i, ]
    destfile <- destfiles[i]

    status <- if (.is_cached(destfile) && !force) {
      "cache"
    } else {
      res <- .download_file(t$url, destfile, timeout)
      if (is.null(res)) "nao_encontrado"
      else if (file.exists(destfile) && file.size(destfile) > 0) "baixado"
      else "erro"
    }

    tibble::tibble(
      arquivo     = destfile,
      competencia = t$competencia,
      type        = t$type,
      ano         = t$ano,
      mes         = t$mes,
      uf          = t$uf,
      status      = status
    )
  }

  if (workers <= 1L) {
    # Sequencial com barra de progresso cli
    resultados <- vector("list", n)
    cli::cli_progress_bar(
      name   = gettext("Downloading"),
      total  = n,
      format = "{cli::pb_bar} {cli::pb_current}/{cli::pb_total} [{cli::pb_elapsed}] ETA: {cli::pb_eta_str}"
    )
    for (i in seq_len(n)) {
      resultados[[i]] <- .processar_tarefa(i)
      cli::cli_progress_update()
    }
    cli::cli_progress_done()
  } else {
    # Paralelo com furrr + progressr
    oplan <- future::plan(future::multisession, workers = workers)
    on.exit(future::plan(oplan), add = TRUE)

    progressr::with_progress({
      p <- progressr::progressor(steps = n)
      resultados <- furrr::future_map(
        seq_len(n),
        function(i) {
          on.exit(p())   # garante p() mesmo em caso de erro
          .processar_tarefa(i)
        },
        .options = furrr::furrr_options(seed = NULL)
      )
    })
  }

  dplyr::bind_rows(resultados)
}

## -- Montagem da tabela de tarefas --------------------------------------------

#' Gera data.frame com todas as combinações de download a realizar
#' @noRd
.build_tasks <- function(years, months) {
  today <- Sys.Date()
  rows  <- list()

  for (year in years) {
    for (month in months) {

      # Ignora competencias futuras
      if (as.Date(sprintf("%04d-%02d-01", year, month)) > today) next

      competencia <- .format_period(year, month)

      if (.is_new_caged(year, month)) {

        # NOVO CAGED (2020+): 3 tipos por competencia
        for (type in c("MOV", "FOR", "EXC")) {
          url <- .hf_url(year, month, type)
          rows[[length(rows) + 1L]] <- tibble::tibble(
            ano          = year,
            mes          = month,
            competencia  = competencia,
            type         = type,
            uf           = NA_character_,
            url          = url,
            nome_arquivo = basename(url),
            subdir       = file.path(.HF_PASTA_NOVO, as.character(year), competencia)
          )
        }

      } else {

        # CAGED ANTIGO (<= 2019): 1 arquivo nacional por competencia
        url <- .hf_url(year, month, type = "ANTIGO")
        rows[[length(rows) + 1L]] <- tibble::tibble(
          ano          = year,
          mes          = month,
          competencia  = competencia,
          type         = "ANTIGO",
          uf           = NA_character_,
          url          = url,
          nome_arquivo = basename(url),
          subdir       = file.path(.HF_PASTA_ANTIGO, as.character(year))
        )

      }
    }
  }

  if (length(rows) == 0L) return(tibble::tibble())

  dplyr::bind_rows(rows)
}

Try the datacaged package in your browser

Any scripts or data that you put into this service are public.

datacaged documentation built on Oct. 13, 2026, 1:06 a.m.