Загрузка файлов

Функции загрузки уровня пакета

Download

func Download(ctx context.Context, url string, cfg *DownloadConfig, options ...RequestOption) (*DownloadResult, error)

Загружает файл с использованием клиента по умолчанию. Download — единый канонический вход для загрузки на уровне пакета, интерфейса Client и DomainClient, заменяющий прежнюю матрицу вариантов одной сигнатурой. cfg не может быть nil, и cfg.FilePath должен быть задан (иначе возвращается ErrEmptyFilePath).

cfg := httpc.DefaultDownloadConfig()
cfg.FilePath = "/tmp/file.zip"
cfg.Overwrite = true
cfg.ResumeDownload = true

result, err := httpc.Download(context.Background(), url, cfg)

DownloadConfig

type DownloadConfig struct {
    FilePath          string
    ProgressCallback  DownloadProgressCallback
    Overwrite         bool
    ResumeDownload    bool
    Checksum          string
    ChecksumAlgorithm ChecksumAlgorithm
}

func DefaultDownloadConfig() *DownloadConfig

Поле	Тип	По умолчанию	Описание
FilePath	string	-	Путь сохранения (обязательно)
ProgressCallback	DownloadProgressCallback	nil	Обратный вызов прогресса
Overwrite	bool	false	Перезаписать существующий файл
ResumeDownload	bool	false	Включить докачку
Checksum	string	""	Ожидаемое значение контрольной суммы
ChecksumAlgorithm	ChecksumAlgorithm	"sha256"	Алгоритм контрольной суммы

DownloadProgressCallback

type DownloadProgressCallback func(downloaded, total int64, speed float64)

Параметр	Тип	Описание
downloaded	int64	Количество загруженных байт
total	int64	Общее количество байт (-1 если неизвестно)
speed	float64	Текущая скорость (байт/сек)

cfg.ProgressCallback = func(downloaded, total int64, speed float64) {
    pct := float64(downloaded) / float64(total) * 100
    fmt.Printf("\r%.1f%% (%s)", pct, httpc.FormatSpeed(speed))
}

DownloadResult

type DownloadResult struct {
    FilePath        string
    BytesWritten    int64
    Duration        time.Duration
    AverageSpeed    float64
    StatusCode      int
    ContentLength   int64
    Resumed         bool
    ResponseCookies []*http.Cookie
    ActualChecksum  string
    Proto           string
    ResponseHeaders http.Header
    RequestURL      string
    RequestMethod   string
    RequestHeaders  http.Header
}

Поле	Тип	Описание
FilePath	string	Путь сохранения файла
BytesWritten	int64	Количество записанных байт
Duration	time.Duration	Время загрузки
AverageSpeed	float64	Средняя скорость (байт/сек)
StatusCode	int	HTTP-код состояния
ContentLength	int64	Значение заголовка Content-Length
Resumed	bool	Завершена ли докачка
ResponseCookies	[]*http.Cookie	Cookie ответа
ActualChecksum	string	Фактическая контрольная сумма
Proto	string	Версия HTTP-протокола (например "HTTP/1.1", "HTTP/2.0")
ResponseHeaders	http.Header	Заголовки ответа
RequestURL	string	Фактический URL запроса
RequestMethod	string	HTTP-метод запроса
RequestHeaders	http.Header	Заголовки запроса

fmt.Printf("Загрузка завершена: %s, время %v, средняя скорость %s\n",
    httpc.FormatBytes(result.BytesWritten),
    result.Duration,
    httpc.FormatSpeed(result.AverageSpeed),
)

TIP

Используйте FormatBytes и FormatSpeed, чтобы получить человекочитаемые строки байт и скорости и не выполнять вручную пересчёт по основанию 1024.

Проверка контрольной суммы

ChecksumAlgorithm

type ChecksumAlgorithm string

Алгоритм проверки целостности загруженного файла.

Константа	Значение	Описание
ChecksumSHA256	"sha256"	Алгоритм хеширования SHA-256

Пример использования

cfg := httpc.DefaultDownloadConfig()
cfg.FilePath = "/tmp/package.tar.gz"
cfg.Checksum = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
cfg.ChecksumAlgorithm = httpc.ChecksumSHA256

result, err := httpc.Download(context.Background(), url, cfg)
if err != nil {
    // При несовпадении контрольной суммы автоматически возвращается ошибка и удаляется загруженный файл
    log.Fatal(err)
}
fmt.Println("Контрольная сумма:", result.ActualChecksum)

TIP

При установке Checksum после завершения загрузки автоматически проверяется целостность файла. При несовпадении файл автоматически удаляется и возвращается ошибка, ручное сравнение не требуется.

Защита безопасности

Загрузка файлов включает многоуровневую защиту:

Защита	Описание
Блокировка UNC-путей	Запрет путей формата \\server\share
Фильтрация управляющих символов	Запрет управляющих символов в пути
Защита системных путей	Запрет записи в системные каталоги
Обнаружение обхода пути	Обнаружение обхода пути ../
Обнаружение символических ссылок	Предотвращение атак через символические ссылки
Проверка родительских каталогов	Рекурсивная проверка символических ссылок родительских каталогов

Докачка

cfg := httpc.DefaultDownloadConfig()
cfg.FilePath = "/tmp/large-file.zip"
cfg.ResumeDownload = true

result, err := httpc.Download(context.Background(), url, cfg)
if result.Resumed {
    fmt.Println("Докачка завершена")
}

Механизм докачки:

1. Проверка размера локального файла → используется как смещение запроса Range
2. Сервер возвращает 206 (Partial Content) → дозапись
3. Сервер возвращает 416 (Range Not Satisfiable) → возврат ошибки
4. Сервер возвращает 200 (Range не поддерживается) → возврат ошибки (защита локального частичного файла от перезаписи)

См. также

• Загрузка и выгрузка файлов - руководство по использованию
• Функции пакета - справочник вспомогательных функций
• Доменный клиент - методы загрузки доменного клиента