---
name: http_download_file
kind: function
lang: go
domain: infra
version: "1.0.0"
purity: impure
signature: "func HttpDownloadFile(url, destPath string, headers map[string]string, timeout time.Duration) (int64, error)"
description: "Descarga url en destPath en streaming con io.Copy. Crea directorios con os.MkdirAll. Usa archivo temporal + rename para atomicidad (no deja archivo corrupto si falla). Retorna bytes escritos."
tags: [http, download, file, streaming, atomic, network, stdlib, infra]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["fmt", "io", "net/http", "os", "path/filepath", "time"]
params:
  - name: url
    desc: "URL del archivo a descargar"
  - name: destPath
    desc: "ruta de destino del archivo descargado"
  - name: headers
    desc: "mapa de headers custom a incluir en la solicitud"
  - name: timeout
    desc: "duracion maxima para completar la descarga"
output: "numero de bytes descargados exitosamente"
tested: true
tests:
  - "httptest.Server sirve archivo binario"
  - "Directorio creado automaticamente"
  - "Archivo temporal + rename (no deja basura si falla)"
  - "Size retornado coincide"
test_file_path: "functions/infra/http_download_file_test.go"
file_path: "functions/infra/http_download_file.go"
---

## Ejemplo

```go
n, err := HttpDownloadFile(
    "https://example.com/report.pdf",
    "/tmp/reports/report.pdf",
    nil,
    2*time.Minute,
)
if err != nil {
    return err
}
fmt.Printf("Downloaded %d bytes\n", n)
```

## Notas

Solo usa stdlib. El archivo temporal se crea en el mismo directorio que destPath para que el rename sea atomico (mismo filesystem). Si la descarga falla, el archivo temporal se elimina con os.Remove (el defer lo garantiza). Compatible con archivos de cualquier tamano ya que usa streaming con io.Copy.
