チャンクを並行取得する再開可能なダウンローダーを Go で構築
完了したチャンクを実行間で保存し、出力先を置き換える前に組み立てたファイルを検証する、単一の実行形式のダウンローダーを構築します。既知のバイナリデータを配信するローカルの HTTP 範囲リクエスト対応オリジンも実行し、外部の URL に依存せずにダウンロード全体を試します。
独自のファイルダウンローダーを構築する理由は?
四つのワーカーが独立したチャンクを取得します。完了したチャンクは実行が中断しても残りますが、未完了のチャンクが完了扱いになることはありません。ファイル全体が期待するダイジェストと一致した場合にのみ、出力先をアトミックに置き換えます。
HTTP 範囲リクエストと部分コンテンツの理解
Range ヘッダーは要求であり、保証ではありません。各チャンクの応答にはステータス 206、要求と完全に一致する Content-Range、同一の強い ETag、期待する正確なバイト数が必要です。If-Range は、異なるオブジェクトバージョンが気づかないうちに混在するのを防ぎます。ここでは、フォールバックによる 200 応答はエラーとして扱います。
HTTP 範囲リクエストとバリデーターのセマンティクス(RFC 9110)
Go による基本的なファイルダウンロードの実装
これらのコマンドは、Bash、PATH 上の Go 1.26.8、GNU Coreutils の
sha256sum を備えた Linux を対象としています。必要に応じて、公式ダウンロードページから Go をインストールしてください。Go 1.26 は引き続きサポート対象のリリースです。この手順は 1.26.8 でテストしており、古いツールチェーンでの動作は保証しません。どちらのプログラムも標準ライブラリのみを使用します。
自身で管理するディレクトリで、このブロックを貼り付けてください。初期化に成功した場合にのみ、新しいプロジェクトのディレクトリに移動します。range-downloader ディレクトリが既にある場合はエラーになります。セットアップをやり直すために既存のプロジェクトを削除するのではなく、別の名前を選ぶか、そのディレクトリの内容を確認してください。
(
mkdir -- range-downloader &&
cd -- range-downloader &&
GOENV=off GOWORK=off GOTOOLCHAIN=local GOFLAGS= go mod init range-downloader
) && cd -- range-downloader
コマンドに限定したこれらの設定は、保存済みの Go 設定と上位の
Go ワークスペースを無視し、継承したビルドフラグをクリアして、インストール済みのツールチェーンを使用します。シェル設定や親プロジェクトの go.mod、go.work は変更しません。ディレクトリの作成後にセットアップが失敗した場合、シェルは元のディレクトリに留まります。再試行する前に、新しいディレクトリを確認してください。
再開可能なダウンロードへの対応
出力パスに「.parts」を付けた場所に、URL、ETag、期待するダイジェスト、長さ、チャンクサイズを保存します。再実行時は、すべてのフィールドが一致する場合にのみ、その状態を受け入れます。期待する長さの完全なチャンクファイルを再利用し、組み立てた内容を信頼できるダイジェストと照合します。一致しない場合は新しい出力パスが必要です。破損した状態を再利用しないでください。
チャンクの並行ダウンロードの実装
固定サイズのワーカープールが、バッファーなしのジョブチャネルから処理を受け取ります。各応答は、32 KiB のコピーバッファーを介して一時チャンクファイルにストリーミングされます。最初のワーカーエラーで他のリクエストをキャンセルし、調整役はすべてのワーカーを待ってから戻ります。
リアルタイム更新によるプログレスバーの追加
このバージョンでは、プログレスバーの依存パッケージを追加せず、最終的な組み立て中にバイト数を出力します。最終ダイジェストが一致するまでは、ダウンロードしたバイトを検証済みとして報告しません。
エラー処理と再試行ロジック
エラーは伝播し、プロセスはゼロ以外の終了ステータスで終了します。一時的な障害の後は、同じコマンドを再実行すると完了したチャンクを再利用できます。認証の失敗や表現の変更に対して再試行を続けかねない、自動再試行ループはありません。Ctrl-C はネットワークリクエストをキャンセルし、完了したチャンクは利用可能な状態で残します。
接続プールによるパフォーマンスの最適化
共有の HTTP クライアントが接続を再利用します。ホストごとのアイドル接続は四つで、リクエストごとのタイムアウトは二分です。ネットワークの同時実行数はワーカー数で制限されます。ディスクには保存済みチャンクに加え、組み立て時に完全なコピーをもう一つ作成します。
完全な例:CLI ダウンローダーの構築
この完全なプログラムを main.go として保存してください。SHA-256 ダイジェストは、ダウンロードとは独立した手段で、信頼できる発行元から入手してください。自身で管理する親ディレクトリを使用し、他のプロセスが出力や保存済みチャンクを変更しないようにしてください。
package main
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"os"
"os/signal"
"path/filepath"
"strings"
"sync"
"time"
)
const chunkSize int64 = 4 << 20
type identity struct {
URL, ETag, SHA256 string
Size, ChunkSize int64
}
func probe(ctx context.Context, client *http.Client, url, digest string) (identity, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodHead, url, nil)
if err != nil {
return identity{}, err
}
req.Header.Set("Accept-Encoding", "identity")
resp, err := client.Do(req)
if err != nil {
return identity{}, err
}
defer resp.Body.Close()
tag := resp.Header.Get("ETag")
if resp.StatusCode != 200 || resp.ContentLength < 0 || resp.ContentLength > 1<<40 ||
len(tag) < 2 || !strings.HasPrefix(tag, "\"") || !strings.HasSuffix(tag, "\"") ||
resp.Header.Get("Content-Encoding") != "" {
return identity{}, errors.New("need a known size (at most 1 TiB), strong ETag and unencoded HEAD 200")
}
return identity{url, tag, digest, resp.ContentLength, chunkSize}, nil
}
func fetchChunk(ctx context.Context, client *http.Client, id identity, dir string, start int64) error {
end := min(start+id.ChunkSize, id.Size) - 1
name := filepath.Join(dir, fmt.Sprintf("%d.part", start))
if info, err := os.Lstat(name); err == nil {
if info.Mode().IsRegular() && info.Size() == end-start+1 {
return nil
}
return errors.New("invalid saved chunk; use a new output path")
} else if !errors.Is(err, os.ErrNotExist) {
return err
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, id.URL, nil)
if err != nil {
return err
}
req.Header.Set("Accept-Encoding", "identity")
req.Header.Set("Range", fmt.Sprintf("bytes=%d-%d", start, end))
req.Header.Set("If-Range", id.ETag)
resp, err := client.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
expected := fmt.Sprintf("bytes %d-%d/%d", start, end, id.Size)
if resp.StatusCode != http.StatusPartialContent || resp.Header.Get("Content-Range") != expected ||
resp.Header.Get("ETag") != id.ETag || resp.Header.Get("Content-Encoding") != "" ||
(resp.ContentLength != -1 && resp.ContentLength != end-start+1) {
return errors.New("server rejected range or changed representation")
}
tmp, err := os.CreateTemp(dir, ".chunk-")
if err != nil {
return err
}
defer os.Remove(tmp.Name())
defer tmp.Close()
n, err := io.CopyBuffer(tmp, io.LimitReader(resp.Body, end-start+2), make([]byte, 32<<10))
if err != nil {
return err
}
if n != end-start+1 {
return errors.New("incorrect chunk length")
}
if err := tmp.Sync(); err != nil {
return err
}
if err := tmp.Close(); err != nil {
return err
}
if err := ctx.Err(); err != nil {
return err
}
return os.Rename(tmp.Name(), name)
}
func download(ctx context.Context, client *http.Client, url, output, digest string, workers int) error {
sum, err := hex.DecodeString(digest)
if err != nil || len(sum) != sha256.Size || workers < 1 || workers > 16 {
return errors.New("provide a SHA-256 hex digest and 1–16 workers")
}
digest = strings.ToLower(digest)
id, err := probe(ctx, client, url, digest)
if err != nil {
return err
}
dir := output + ".parts"
fresh := false
if err := os.Mkdir(dir, 0700); err == nil {
fresh = true
} else if !errors.Is(err, os.ErrExist) {
return err
}
info, err := os.Lstat(dir)
if err != nil {
return err
}
if !info.IsDir() || info.Mode().Perm()&0077 != 0 {
return errors.New("parts directory must be private")
}
lock := filepath.Join(dir, ".lock")
if err := os.Mkdir(lock, 0700); err != nil {
return errors.New("parts directory locked; another download may be active")
}
defer os.Remove(lock)
manifest := filepath.Join(dir, "identity.json")
if fresh {
data, err := json.Marshal(id)
if err != nil {
return err
}
if err := os.WriteFile(manifest, data, 0600); err != nil {
return err
}
} else {
data, err := os.ReadFile(manifest)
if err != nil {
return err
}
var saved identity
if err := json.Unmarshal(data, &saved); err != nil {
return err
}
if saved != id {
return errors.New("saved download identity changed; use a new output path")
}
}
ctx, cancel := context.WithCancel(ctx)
defer cancel()
var wg sync.WaitGroup
var once sync.Once
var firstErr error
jobs := make(chan int64)
for i := 0; i < workers; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for start := range jobs {
if ctx.Err() != nil {
return
}
if err := fetchChunk(ctx, client, id, dir, start); err != nil {
once.Do(func() { firstErr = err; cancel() })
return
}
}
}()
}
send:
for start := int64(0); start < id.Size; start += id.ChunkSize {
select {
case jobs <- start:
case <-ctx.Done():
break send
}
}
close(jobs)
wg.Wait()
if firstErr != nil {
return firstErr
}
if err := ctx.Err(); err != nil {
return err
}
tmp, err := os.CreateTemp(filepath.Dir(output), ".download-")
if err != nil {
return err
}
defer os.Remove(tmp.Name())
defer tmp.Close()
hash := sha256.New()
for start := int64(0); start < id.Size; start += id.ChunkSize {
if err := ctx.Err(); err != nil {
return err
}
part, err := os.Open(filepath.Join(dir, fmt.Sprintf("%d.part", start)))
if err != nil {
return err
}
n, copyErr := io.Copy(io.MultiWriter(tmp, hash), io.LimitReader(part, id.ChunkSize+1))
closeErr := part.Close()
if copyErr != nil {
return copyErr
}
if closeErr != nil {
return closeErr
}
if n != min(id.ChunkSize, id.Size-start) {
return errors.New("saved chunk length changed")
}
fmt.Fprintf(os.Stderr, "Assembled: %d/%d bytes\n", start+n, id.Size)
}
if hex.EncodeToString(hash.Sum(nil)) != digest {
return errors.New("SHA-256 mismatch; use a new output path")
}
if err := tmp.Sync(); err != nil {
return err
}
if err := tmp.Close(); err != nil {
return err
}
if err := ctx.Err(); err != nil {
return err
}
return os.Rename(tmp.Name(), output)
}
func main() {
if len(os.Args) != 4 {
fmt.Fprintln(os.Stderr, "usage: downloader URL OUTPUT SHA256")
os.Exit(2)
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
transport := http.DefaultTransport.(*http.Transport).Clone()
transport.MaxIdleConnsPerHost = 4
defer transport.CloseIdleConnections()
client := &http.Client{Transport: transport, Timeout: 2 * time.Minute}
if err := download(ctx, client, os.Args[1], os.Args[2], os.Args[3], 4); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
独自のダウンロードには、このシェルで DOWNLOAD_URL、OUTPUT_PATH、EXPECTED_SHA256 を設定してください。オリジンは、既知のサイズと強い ETag を持つ、エンコードされていない HEAD 応答を返し、その後のチャンクリクエストにも応じる必要があります。ダウンロードが成功すると、意図的に既存の出力ファイルを置き換えます。検証に失敗した場合、そのファイルは保持されます。これを踏まえて出力先を選んでください。
以下のビルドと実行のブロックを貼り付けるか、先に次のセクションのローカルオリジンを使用してください。main.go を明示的にビルドすることで、二つの独立したプログラムを分離します。古い downloader 実行ファイルがあっても、ビルドが失敗するとブロックは停止します。変数が未設定の場合は、サブシェル内で失敗します。
(
GOENV=off GOWORK=off GOTOOLCHAIN=local GOFLAGS= GOOS= GOARCH= go build -o downloader main.go &&
./downloader "${DOWNLOAD_URL:?Set DOWNLOAD_URL}" "${OUTPUT_PATH:?Set OUTPUT_PATH}" "${EXPECTED_SHA256:?Set EXPECTED_SHA256}"
)
ローカルの範囲リクエスト対応オリジンの試用
この二つ目のプログラムを、origin.go として main.go と同じディレクトリに保存してください。8 MiB の繰り返しバイナリデータに五バイトの tail\n を続けた、合計 8,388,613 バイトを配信します。リクエストごとに専用のリーダーを使用します。http.ServeContent が、ここで指定した強い ETag を使って HEAD、Range、If-Range を処理します。この小さなテスト用フィクスチャは、コンテンツをメモリに保持します。
package main
import (
"bytes"
"crypto/sha256"
"fmt"
"net"
"net/http"
"os"
"time"
)
func main() {
if len(os.Args) != 2 {
fmt.Fprintln(os.Stderr, "usage: local-origin 127.0.0.1:PORT")
os.Exit(2)
}
data := append(bytes.Repeat([]byte{0x00, 0x80, 0xff, 0x0a}, 2<<20), []byte("tail\n")...)
digest := fmt.Sprintf("%x", sha256.Sum256(data))
listener, err := net.Listen("tcp", os.Args[1])
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
defer listener.Close()
mux := http.NewServeMux()
mux.HandleFunc("/file", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("ETag", "\""+digest+"\"")
http.ServeContent(w, r, "fixture.bin", time.Time{}, bytes.NewReader(data))
})
fmt.Printf("DOWNLOAD_URL=http://%s/file\nEXPECTED_SHA256=%s\n", listener.Addr(), digest)
server := &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
if err := server.Serve(listener); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
別の Bash ターミナルで、同じ range-downloader ディレクトリに移動し、このブロックを貼り付けてください。ポート番号ゼロを指定すると、利用可能なループバックポートが選ばれます。ダウンロード中はオリジンを実行したままにし、完了したらこのターミナルで Ctrl+C を押してください。
(
GOENV=off GOWORK=off GOTOOLCHAIN=local GOFLAGS= GOOS= GOARCH= go build -o local-origin origin.go &&
./local-origin 127.0.0.1:0
)
オリジンが出力した二行の代入文を最初のターミナルにコピーし、そこで出力先を設定してください。
export OUTPUT_PATH='example.bin'
上記のダウンローダーのビルドと実行のブロックを実行してください。組み立てのバイト数を 8388613/8388613 bytes まで出力した後、終了ステータスがゼロになるはずです。実際のファイルを独立して検証してください。
(
printf '%s %s\n' "${EXPECTED_SHA256:?Set EXPECTED_SHA256}" "${OUTPUT_PATH:?Set OUTPUT_PATH}" |
sha256sum --check --status
)
この確認の終了ステータスがゼロなら、保存されたファイルはフィクスチャのダイジェストと一致しています。リモートファイルの場合、ダイジェストは信頼できる発行元の経路を通じて入手してください。同じ信頼できないダウンロードから得たチェックサムでは、真正性を確認できません。低速または大きなデータを配信するオリジンで再開動作を試すには、ダウンロード中に Ctrl+C を押し、同じコマンドを再実行してください。完全に保存されたチャンクのみを再利用します。この小さなループバック用フィクスチャは、中断する前に完了することがあります。
ベストプラクティスとよくある落とし穴
この実装は、長さが不明な応答、弱い ETag または ETag の欠落、エンコードされた応答、1 TiB を超えるオブジェクトを拒否します。HEAD が強い ETag と長さゼロを返す場合は、空のファイルにも対応します。SHA-256 は、オリジンが不正な動作をしても、保存済みチャンクの破損やバージョンの混在を検出します。
実行が成功しても、アクセス権を所有者に限定した .parts ディレクトリは明示的に削除するまで残ります。強制終了すると、その中の .lock ディレクトリが残ることがあります。ダウンローダーが動作していないことを確認してから、そのロックを削除してください。出力先の親ディレクトリと保存済みチャンクは、排他的に管理してください。ロックは、同じチャンク保存パスを使うこのプログラムの実行を調整するもので、他のプログラムによるファイルの変更を防ぐものではありません。
組み立て用の一時ファイルは、出力先と同じファイルシステムになるよう、出力先と同じディレクトリに作成します。Linux では、検証後に os.Rename が出力先を置き換えます。これは、電源断に対する永続性を保証するものではありません。ダイジェストが一致しなくても、保存済みチャンクは修復されません。新しい出力パスを選び、オリジンや破損した状態を調査してください。
まとめ
ローカルのフィクスチャで一連の処理全体を確認してから、互換性のある範囲応答を返すオリジンと、独立した手段で信頼性を確認したダイジェストに置き換えてください。四つのワーカーを使うダウンローダーは、完了したチャンクを保持し、検証が完了した場合にのみ、組み立てたファイルを出力先に反映します。
Transloadit の /http/import Robot は、処理ワークフローで HTTP インポートを行います。
