fix(ci): restore Windows release asset uploads

.gitattributes

@@ -0,0 +1,2 @@
+# Keep upstream plugin sources recognizable and collapsed in GitHub reviews.
+ui/flutter/third_party/** linguist-vendored whitespace=-blank-at-eol,-blank-at-eof

.github/workflows/build.yml

@@ -106,17 +106,32 @@ jobs:
           if ("${{ matrix.arch }}" -eq "amd64") {
               # for amd64
               $release = "build\windows\x64\runner\Release\"
-              $mingw = "C:\Program Files\Git\mingw64\bin"
-              cp $mingw\libstdc++-6.dll $release
-              cp $mingw\libgcc_s_seh-1.dll $release
+              # Use the same toolchain as cgo instead of Git's bundled DLLs.
+              $cc = (Get-Command -Name (go env CC) -CommandType Application -ErrorAction Stop | Select-Object -First 1).Source
+              foreach ($dll in @("libstdc++-6.dll", "libgcc_s_seh-1.dll", "libwinpthread-1.dll")) {
+                  $runtimePath = [string](& $cc "-print-file-name=$dll")
+                  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($runtimePath)) {
+                      throw "Failed to locate $dll using $cc"
+                  }
+                  $runtimePath = $runtimePath.Trim()
+                  # Some MinGW distributions keep runtime DLLs beside gcc.exe.
+                  if ($runtimePath -eq $dll) {
+                      $runtimePath = Join-Path (Split-Path -Parent $cc) $dll
+                  }
+                  if (!(Test-Path -LiteralPath $runtimePath -PathType Leaf)) {
+                      throw "MinGW runtime $dll was not found by $cc (reported path: $runtimePath)"
+                  }
+                  Write-Host "Copying MinGW runtime: $runtimePath"
+                  Copy-Item -LiteralPath $runtimePath -Destination $release
+              }
           } else {
               # for ARM64
               $release = "build\windows\arm64\runner\Release\"
               $mingw = "$env:CLANGARM64_ROOT\aarch64-w64-mingw32\bin"
               cp $mingw\libc++.dll $release
               cp $mingw\libunwind.dll $release
+              cp $mingw\libwinpthread-1.dll $release
           }
-          cp $mingw\libwinpthread-1.dll $release
           cp $system\msvcp140.dll $release
           cp $system\vcruntime140.dll $release
           cp $system\vcruntime140_1.dll $release

.github/workflows/test.yml

@@ -69,6 +69,23 @@ jobs:
         with:
           files: ./coverage.txt
           token: ${{ secrets.CODECOV_UPLOAD_TOKEN }}
+  test-flutter-category:
+    # The settings editor and the backend have to read an extension list the
+    # same way, so both sides run the shared rule table. The Go side is covered
+    # by the test job above, this runs the ui side of it.
+    name: Test shared category rules
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: ${{ env.FLUTTER_VERSION }}
+      - name: Run the shared category rule table on the ui side
+        working-directory: ui/flutter
+        run: |
+          flutter pub get
+          flutter gen-l10n
+          flutter test test/api/downloader_config_test.dart
   test-webview-integration:
     name: Test webview integration (${{ matrix.name }})
     strategy:
@@ -77,6 +94,8 @@ jobs:
         include:
           - name: Windows
             os: windows-latest
+          - name: Linux
+            os: ubuntu-latest
           - name: macOS
             os: macos-latest
     runs-on: ${{ matrix.os }}
@@ -89,9 +108,25 @@ jobs:
         if: runner.os == 'macOS'
         with:
           flutter-version: ${{ env.FLUTTER_VERSION }}
+      - name: Install Linux WebView dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev xvfb
+      - name: Test webview
+        if: runner.os == 'Linux'
+        # Match the full suite's coverage instrumentation and repeat on the same
+        # GTK event loop to catch queued callbacks after engine destruction.
+        run: |
+          PACKAGES=$(go list ./... | awk '!/\/bind\// && (!/\/cmd\// || /\/cmd\/web$/)')
+          go test -c -tags webview -coverpkg=$(echo "$PACKAGES" | paste -sd "," -) -covermode=count -o "$RUNNER_TEMP/goprovider.test" ./internal/webview/goprovider
+          xvfb-run -a "$RUNNER_TEMP/goprovider.test" -test.v -test.count=5 -test.timeout=300s -test.coverprofile="$RUNNER_TEMP/webview-coverage.out"
+        env:
+          CGO_ENABLED: 1
       - name: Test webview
         if: runner.os == 'Windows'
-        run: go test -tags webview -v -count=1 -timeout 300s ./internal/webview/goprovider/
+        # Repeat close/reopen coverage to catch browser shutdown races.
+        run: go test -tags webview -v -count=3 -timeout 300s ./internal/webview/goprovider/
         env:
           CGO_ENABLED: 1
       - name: Test webview

README.md

@@ -63,7 +63,7 @@ Connect Gopeed to an AI agent and manage downloads with natural language. For ex
 
 Gopeed 2.0.0 is currently in public beta, introducing a redesigned interface, a native communication architecture that connects desktop and mobile clients directly to the Go core through FFI, a more consistent cross-platform experience, improved task management, more flexible API support, and MCP-based AI agent integration. Some features may still be incomplete or unstable, so please try it and report any issues you encounter.
 
-- [Download Gopeed 2.0.0 Beta 1](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.1)
+- [Download Gopeed 2.0.0 Beta 3](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.3)
 
 Once the features and stability meet our release standards, we will publish the official Gopeed 2.0.0 release. Beta users will be able to upgrade directly to the final release, while existing stable users will not be automatically moved onto the beta channel.
 

README_ja-JP.md

@@ -63,7 +63,7 @@ Gopeed を AI Agent と連携すると、自然言語でダウンロードを管
 
 Gopeed 2.0.0 は現在パブリックベータ版です。刷新されたインターフェース、デスクトップおよびモバイルから FFI で Go コアへ直接接続するネイティブ通信アーキテクチャ、より統一されたクロスプラットフォーム体験、強化されたタスク管理、より柔軟な API、MCP による AI Agent 連携機能を導入しています。一部の機能はまだ不完全または不安定な場合がありますので、ぜひお試しいただき、問題があればフィードバックをお寄せください。
 
-- [Gopeed 2.0.0 Beta 1 をダウンロード](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.1)
+- [Gopeed 2.0.0 Beta 3 をダウンロード](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.3)
 
 機能と安定性が正式リリースの基準に達した時点で、Gopeed 2.0.0 正式版を公開します。ベータ版のユーザーは正式版へ直接アップデートできます。既存の安定版ユーザーが自動的にベータチャンネルへ移行することはありません。
 

README_vi-VN.md

@@ -63,7 +63,7 @@ Sau khi kết nối Gopeed với AI Agent, bạn có thể quản lý tải xu
 
 Gopeed 2.0.0 hiện đang trong giai đoạn beta công khai, với giao diện được thiết kế lại, kiến trúc giao tiếp native kết nối trực tiếp ứng dụng desktop và di động với lõi Go qua FFI, trải nghiệm đa nền tảng nhất quán hơn, khả năng quản lý tác vụ được cải thiện, API linh hoạt hơn và khả năng tích hợp AI Agent qua MCP. Một số tính năng có thể vẫn chưa hoàn thiện hoặc chưa ổn định, vì vậy hãy dùng thử và gửi phản hồi nếu bạn gặp vấn đề.
 
-- [Tải Gopeed 2.0.0 Beta 1](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.1)
+- [Tải Gopeed 2.0.0 Beta 3](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.3)
 
 Khi các tính năng và độ ổn định đáp ứng tiêu chuẩn phát hành, chúng tôi sẽ phát hành Gopeed 2.0.0 chính thức. Người dùng bản beta có thể nâng cấp trực tiếp lên bản chính thức, trong khi người dùng bản ổn định hiện tại sẽ không tự động được chuyển sang kênh beta.
 

README_zh-CN.md

@@ -63,7 +63,7 @@ Gopeed（全称 **Go Speed**，也叫“够快下载器”）是一款使用 Go
 
 Gopeed 2.0.0 目前处于公开 Beta 测试阶段，引入了全新界面、通过 FFI 直连 Go 核心的原生通信架构、更一致的跨平台体验、更完善的任务管理、更灵活的 API，以及用于 AI Agent 接入的 MCP 能力。部分功能仍可能不够完善或稳定，欢迎提前体验并向我们反馈问题。
 
-- [下载 Gopeed 2.0.0 Beta 1](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.1)
+- [下载 Gopeed 2.0.0 Beta 3](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.3)
 
 当功能完整度和稳定性达到正式发布标准后，我们会发布 Gopeed 2.0.0 正式版。已安装 Beta 版本的用户可以直接升级到最终正式版，现有稳定版用户则不会被自动切换到 Beta 渠道。
 

README_zh-TW.md

@@ -63,7 +63,7 @@ Gopeed（**Go Speed** 的縮寫）是一款以 Go 與 Flutter 開發的高速、
 
 Gopeed 2.0.0 目前處於公開 Beta 測試階段，引入了全新介面、透過 FFI 直連 Go 核心的原生通訊架構、更一致的跨平台體驗、更完善的任務管理、更靈活的 API，以及透過 MCP 串接 AI Agent 的能力。部分功能仍可能不夠完善或穩定，歡迎搶先體驗並向我們回報問題。
 
-- [下載 Gopeed 2.0.0 Beta 1](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.1)
+- [下載 Gopeed 2.0.0 Beta 3](https://github.com/GopeedLab/gopeed/releases/tag/v2.0.0-beta.3)
 
 當功能完整度與穩定性達到正式發布標準後，我們會發布 Gopeed 2.0.0 正式版。已安裝 Beta 版本的使用者可以直接升級至最終正式版，現有穩定版使用者則不會被自動切換至 Beta 頻道。
 

bind/mobile/main.go

@@ -7,6 +7,7 @@ import (
 
 	nativebridge "github.com/GopeedLab/gopeed/bind/native"
 	"github.com/GopeedLab/gopeed/internal/webview/rpcprovider"
+	goapi "github.com/GopeedLab/gopeed/pkg/api"
 	"github.com/GopeedLab/gopeed/pkg/rest"
 	"github.com/GopeedLab/gopeed/pkg/rest/model"
 )
@@ -90,3 +91,14 @@ func applyWebViewProvider(config *model.StartConfig) {
 	}
 	config.WebViewProvider = rpcprovider.New(*config.WebViewRPCConfig)
 }
+
+func LiveActivityTaskEventMask() int64 {
+	return int64(
+		goapi.TaskEventDone |
+			goapi.TaskEventError |
+			goapi.TaskEventStart |
+			goapi.TaskEventProgress |
+			goapi.TaskEventPause |
+			goapi.TaskEventDelete,
+	)
+}

cmd/extmock/main.go

@@ -166,7 +166,7 @@ func runResolve(args []string) error {
 	result, err := d.Resolve(&base.Request{
 		URL:    url,
 		Labels: map[string]string(labels),
-	}, nil)
+	})
 	if err != nil {
 		return err
 	}
@@ -250,7 +250,7 @@ func runDownload(args []string) error {
 	result, err := d.Resolve(&base.Request{
 		URL:    url,
 		Labels: map[string]string(labels),
-	}, nil)
+	})
 	if err != nil {
 		return err
 	}

cmd/gopeed/flags.go

@@ -7,9 +7,11 @@ import (
 )
 
 type args struct {
-	url         string
-	connections *int
-	dir         *string
+	url          string
+	connections  *int
+	dir          *string
+	checksum     *string
+	checksumAlgo *string
 }
 
 func parse() *args {
@@ -20,6 +22,8 @@ func parse() *args {
 	var args args
 	args.connections = flag.Int("C", 16, "Concurrent connections.")
 	args.dir = flag.String("D", dir, "Store directory.")
+	args.checksum = flag.String("checksum", "", "Expected checksum hash (hex encoded).")
+	args.checksumAlgo = flag.String("checksum-algo", "md5", "Checksum algorithm: md5, sha1, or sha256.")
 	flag.Parse()
 	t := flag.Args()
 	if len(t) > 0 {

cmd/gopeed/main.go

@@ -19,6 +19,18 @@ func main() {
 
 	var wg sync.WaitGroup
 	wg.Add(1)
+	var checksumOpt *http.ChecksumOption
+	if args.checksum != nil && *args.checksum != "" {
+		algo := "md5"
+		if args.checksumAlgo != nil && *args.checksumAlgo != "" {
+			algo = *args.checksumAlgo
+		}
+		checksumOpt = &http.ChecksumOption{
+			Algorithm: algo,
+			Expected:  *args.checksum,
+		}
+	}
+
 	_, err := download.Boot().
 		URL(args.url).
 		Listener(func(event *download.Event) {
@@ -43,8 +55,11 @@ func main() {
 			}
 		}).
 		Create(&base.Options{
-			Path:  *args.dir,
-			Extra: http.OptsExtra{Connections: *args.connections},
+			Path: *args.dir,
+			Extra: http.OptsExtra{
+				Connections: *args.connections,
+				Checksum:    checksumOpt,
+			},
 		})
 	if err != nil {
 		panic(err)

cmd/server.go

@@ -26,7 +26,7 @@ func Start(cfg *model.StartConfig) {
 	if err != nil {
 		panic(err)
 	}
-	if downloadCfg.FirstLoad {
+	if rest.Downloader.IsFirstLoad() {
 		// Set default download config
 		if cfg.DownloadConfig != nil {
 			cfg.DownloadConfig.Merge(downloadCfg)
@@ -51,6 +51,12 @@ func Start(cfg *model.StartConfig) {
 				rest.Downloader.PutConfig(downloadCfg)
 			}
 		}
+
+		// The default download dir is resolved only after the core starts, so
+		// seed the built-in categories now that the dir is known. Init is
+		// idempotent and leaves an existing category list untouched.
+		downloadCfg.Init()
+		rest.Downloader.PutConfig(downloadCfg)
 	}
 	watchExit()
 

cmd/updater/updater_windows.go

@@ -37,15 +37,17 @@ func installByInstaller(killSignalChan chan<- any, packagePath, destDir string)
 	}
 	defer reader.Close()
 
-	// Find the installer file
 	var installerPath string
 	for _, file := range reader.File {
+		cleanName := filepath.Clean(file.Name)
+		if strings.HasPrefix(cleanName, "..") || filepath.IsAbs(cleanName) {
+			continue
+		}
 		if file.FileInfo().IsDir() {
 			continue
 		}
 
-		// Extract file
-		path := filepath.Join(tempDir, file.Name)
+		path := filepath.Join(tempDir, cleanName)
 
 		if err := os.MkdirAll(filepath.Dir(path), os.ModePerm); err != nil {
 			return err
@@ -101,7 +103,11 @@ func installByPortable(killSignalChan chan<- any, packagePath, destDir string) e
 	defer reader.Close()
 
 	for _, file := range reader.File {
-		path := filepath.Join(destDir, file.Name)
+		cleanName := filepath.Clean(file.Name)
+		if strings.HasPrefix(cleanName, "..") || filepath.IsAbs(cleanName) {
+			continue
+		}
+		path := filepath.Join(destDir, cleanName)
 
 		if file.FileInfo().IsDir() {
 			os.MkdirAll(path, file.Mode())

cmd/web/flags.go

@@ -13,6 +13,7 @@ import (
 )
 
 type args struct {
+	TempDir           *string  `json:"tempDir"`
 	Address           *string  `json:"address"`
 	Port              *int     `json:"port"`
 	Username          *string  `json:"username"`
@@ -54,6 +55,7 @@ func loadCliArgs() *args {
 	cfg.ApiToken = flag.String("T", "", "API token, it must be configured when using HTTP API in the case of enabling web authentication")
 	flag.StringVar(cfg.ApiToken, "api-token", "", "API token, it must be configured when using HTTP API in the case of enabling web authentication")
 	flag.BoolVar(&cfg.MCPEnable, "mcp-enable", false, "Enable MCP endpoint")
+	cfg.TempDir = flag.String("temp-dir", "", "Temporary directory (defaults to the OS temporary directory)")
 	cfg.StorageDir = flag.String("d", "", "Storage directory")
 	flag.StringVar(cfg.StorageDir, "storage-dir", "", "Storage directory")
 	whiteDownloadDirs := flag.String("white-download-dirs", "", "White download directories, comma-separated")
@@ -89,6 +91,8 @@ func overrideWithCliArgs(cfg *args, cliConfig *args) {
 			cfg.ApiToken = cliConfig.ApiToken
 		case "mcp-enable":
 			cfg.MCPEnable = cliConfig.MCPEnable
+		case "temp-dir":
+			cfg.TempDir = cliConfig.TempDir
 		case "d", "storage-dir":
 			cfg.StorageDir = cliConfig.StorageDir
 		case "white-download-dirs":
@@ -101,6 +105,9 @@ func overrideWithCliArgs(cfg *args, cliConfig *args) {
 
 // setDefaults sets default values for any unset configuration fields
 func setDefaults(cfg *args, cliConfig *args) {
+	if cfg.TempDir == nil {
+		cfg.TempDir = cliConfig.TempDir
+	}
 	if cfg.Address == nil {
 		cfg.Address = cliConfig.Address
 	}

cmd/web/main.go

@@ -43,11 +43,16 @@ func main() {
 		storageDir = filepath.Join(filepath.Dir(exe), "storage")
 	}
 
+	tempDir := ""
+	if args.TempDir != nil {
+		tempDir = *args.TempDir
+	}
 	cfg := &model.StartConfig{
 		Network:           "tcp",
 		Address:           fmt.Sprintf("%s:%d", *args.Address, *args.Port),
 		Storage:           model.StorageBolt,
 		StorageDir:        storageDir,
+		TempDir:           tempDir,
 		WhiteDownloadDirs: args.WhiteDownloadDirs,
 		ApiToken:          *args.ApiToken,
 		MCPEnable:         args.MCPEnable,

go.mod

@@ -3,13 +3,15 @@ module github.com/GopeedLab/gopeed
 go 1.25.4
 
 require (
-	github.com/GopeedLab/webview_go v0.0.0-20260423085439-7a2f88b6e9b5
+	codeberg.org/gruf/go-ffmpreg v0.6.23-0.20260827095416-df1836cb5be0
+	github.com/GopeedLab/webview_go v0.0.0-20260918010912-0d4c27bb7914
 	github.com/anacrolix/torrent v1.60.1-0.20251217073903-486bcbe758e0
 	github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5
 	github.com/bodgit/sevenzip v1.6.1
 	github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3
 	github.com/dop251/goja_nodejs v0.0.0-20240728170619-29b559befffc
 	github.com/go-git/go-git/v5 v5.8.1
+	github.com/google/jsonschema-go v0.4.3
 	github.com/gorilla/handlers v1.5.1
 	github.com/gorilla/mux v1.8.0
 	github.com/imroc/req/v3 v3.52.2
@@ -21,6 +23,7 @@ require (
 	github.com/pkg/errors v0.9.1
 	github.com/rs/dnscache v0.0.0-20230804202142-fc85eb664529
 	github.com/rs/zerolog v1.31.0
+	github.com/tetratelabs/wazero v1.12.0
 	github.com/xiaoqidun/setft v0.0.0-20220310121541-be86327699ad
 	go.etcd.io/bbolt v1.4.3
 	golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93
@@ -38,7 +41,6 @@ require (
 	github.com/felixge/fgprof v0.9.5 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
@@ -64,6 +66,7 @@ require (
 	go.uber.org/automaxprocs v1.6.0 // indirect
 	go.uber.org/mock v0.5.1 // indirect
 	go4.org v0.0.0-20230225012048-214862532bf5 // indirect
+	golang.org/x/mod v0.33.0
 	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
 )
@@ -154,9 +157,8 @@ require (
 	go.opentelemetry.io/otel/metric v1.39.0 // indirect
 	go.opentelemetry.io/otel/trace v1.39.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
-	golang.org/x/mod v0.33.0 // indirect
 	golang.org/x/net v0.50.0
-	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
 	golang.org/x/text v0.34.0
 	golang.org/x/time v0.15.0 // indirect
 	golang.org/x/tools v0.42.0 // indirect

go.sum

@@ -14,6 +14,8 @@ cloud.google.com/go/pubsub v1.0.1/go.mod h1:R0Gpsv3s54REJCy4fxDixWD93lHJMoZTyQ2k
 cloud.google.com/go/pubsub v1.1.0/go.mod h1:EwwdRX2sKPjnvnqCa270oGRyludottCI76h+R3AArQw=
 cloud.google.com/go/storage v1.0.0/go.mod h1:IhtSnM/ZTZV8YYJWCY8RULGVqBDmpoyjwiyrjsg+URw=
 cloud.google.com/go/storage v1.5.0/go.mod h1:tpKbwo567HUNpVclU5sGELwQWBDZ8gh0ZeosJ0Rtdos=
+codeberg.org/gruf/go-ffmpreg v0.6.23-0.20260827095416-df1836cb5be0 h1:AqNFl60o4xhTTOxmzAvSf7pazXHKBGuV5ATw7sETIRA=
+codeberg.org/gruf/go-ffmpreg v0.6.23-0.20260827095416-df1836cb5be0/go.mod h1:XM6eW8CSgAuZRKRynm5nDiSNedm0rav30IychqygOHE=
 crawshaw.io/iox v0.0.0-20181124134642-c51c3df30797/go.mod h1:sXBiorCo8c46JlQV3oXPKINnZ8mcqnye1EkVkqsectk=
 crawshaw.io/sqlite v0.3.2/go.mod h1:igAO5JulrQ1DbdZdtVq48mnZUBAPOeFzer7VhDWNtW4=
 dario.cat/mergo v1.0.0 h1:AGCNq9Evsj31mOgNPcLyXc+4PNABt905YmuqPYYpBWk=
@@ -23,8 +25,20 @@ filippo.io/edwards25519 v1.0.0-rc.1 h1:m0VOOB23frXZvAOK44usCgLWvtsxIoMCTBGJZlpmG
 filippo.io/edwards25519 v1.0.0-rc.1/go.mod h1:N1IkdkCkiLB6tki+MYJoSx2JTY9NUlxZE7eHn5EwJns=
 github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym/WlBOVXweHU+Q+/VP0lqqI8lqeDx9IjBqo=
-github.com/GopeedLab/webview_go v0.0.0-20260423085439-7a2f88b6e9b5 h1:86LVTaNDM/j/uTAD2HedkXNO9LIQlt642VAdbU/0D/M=
-github.com/GopeedLab/webview_go v0.0.0-20260423085439-7a2f88b6e9b5/go.mod h1:FvV19lu9rQ9NcbczN5y8pbWecURRRbWa8tbfFARBDa0=
+github.com/GopeedLab/webview_go v0.0.0-20260915010614-2567e492369a h1:Vzz+8aMVX9ZPPpkxgxa7mCorrAgdXCZL5EunOpOBvao=
+github.com/GopeedLab/webview_go v0.0.0-20260915010614-2567e492369a/go.mod h1:FvV19lu9rQ9NcbczN5y8pbWecURRRbWa8tbfFARBDa0=
+github.com/GopeedLab/webview_go v0.0.0-20260917153919-dcf00737f32a h1:nz1bC6TGwQ1kv/OVLahNZ0EEtb7v5LHfceAkW4MvS6I=
+github.com/GopeedLab/webview_go v0.0.0-20260917153919-dcf00737f32a/go.mod h1:FvV19lu9rQ9NcbczN5y8pbWecURRRbWa8tbfFARBDa0=
+github.com/GopeedLab/webview_go v0.0.0-20260917155039-1ee7ffb4169a h1:yudcfXpipKLnMaaw1losn6YeOBjvj2rAFicfjqYJexY=
+github.com/GopeedLab/webview_go v0.0.0-20260917155039-1ee7ffb4169a/go.mod h1:FvV19lu9rQ9NcbczN5y8pbWecURRRbWa8tbfFARBDa0=
+github.com/GopeedLab/webview_go v0.0.0-20260917155218-bd16da0d6f53 h1:nMSHKhbrEaWPE/x3mYl/270GPjswbUmS+E7yYjly4xk=
+github.com/GopeedLab/webview_go v0.0.0-20260917155218-bd16da0d6f53/go.mod h1:oNO07SCX8xgoHLds2OBwML8TU4xils88vMQ4gadKUHQ=
+github.com/GopeedLab/webview_go v0.0.0-20260917161756-2a4f989dcb1d h1:4fjlhJpBWa6IcdKVPkEMMIDd6Xo9JM09dJHdKU+1V7k=
+github.com/GopeedLab/webview_go v0.0.0-20260917161756-2a4f989dcb1d/go.mod h1:oNO07SCX8xgoHLds2OBwML8TU4xils88vMQ4gadKUHQ=
+github.com/GopeedLab/webview_go v0.0.0-20260917163929-ca26c3e6bcfa h1:VkdBMcNHYTqCMwOOCimA7b3xZKV/qFIGrhh3+vm9n3s=
+github.com/GopeedLab/webview_go v0.0.0-20260917163929-ca26c3e6bcfa/go.mod h1:oNO07SCX8xgoHLds2OBwML8TU4xils88vMQ4gadKUHQ=
+github.com/GopeedLab/webview_go v0.0.0-20260918010912-0d4c27bb7914 h1:9VJQZIZ1R6T4m+4vlNQYNXSPNUv2gf2PiTfIXiQ3MTw=
+github.com/GopeedLab/webview_go v0.0.0-20260918010912-0d4c27bb7914/go.mod h1:oNO07SCX8xgoHLds2OBwML8TU4xils88vMQ4gadKUHQ=
 github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0rYXWg0=
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
 github.com/Microsoft/go-winio v0.5.2/go.mod h1:WpS1mjBmmwHBEWmogvA2mj8546UReBk4v8QkMxJ6pZY=
@@ -552,6 +566,8 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tetratelabs/wazero v1.12.0 h1:DuWcpNu/FzgEXgGBDp8J1Spc+CWOvvtvVyjKlaZopYU=
+github.com/tetratelabs/wazero v1.12.0/go.mod h1:LvKtzl2RqO4gyF27BiXU+nKAjcV8f38U+kP/q2vgxh0=
 github.com/tidwall/btree v1.8.1 h1:27ehoXvm5AG/g+1VxLS1SD3vRhp/H7LuEfwNvddEdmA=
 github.com/tidwall/btree v1.8.1/go.mod h1:jBbTdUWhSZClZWoDg54VnvV7/54modSOzDN7VXftj1A=
 github.com/tinylib/msgp v1.0.2/go.mod h1:+d+yLhGm8mzTaHzB+wgMYrodPfmZrzkirds8fDWklFE=
@@ -732,6 +748,8 @@ golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.2.0/go.mod h1:TVmDHMZPmdnySmBfhjOoOdhjzdE1h4u1VwSiw2l1Nuc=

internal/blob/registry.go

@@ -7,6 +7,7 @@ import (
 	"encoding/hex"
 	"errors"
 	"fmt"
+	"github.com/GopeedLab/gopeed/internal/production"
 	"io"
 	"net"
 	"net/http"
@@ -61,6 +62,7 @@ type Metadata struct {
 }
 
 type Source struct {
+	producer    production.Reader
 	ID          string
 	URL         string
 	ContentType string
@@ -359,11 +361,35 @@ func (r *Registry) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 		return
 	}
 	defer reader.Close()
+	if producer, ok := reader.(production.Reader); ok {
+		src.mu.Lock()
+		src.producer = producer
+		src.mu.Unlock()
+		if err := producer.WaitProduction(req.Context()); err != nil {
+			return
+		}
+		if producer.Production() != nil {
+			meta.Size = 0
+			meta.Range = false
+			start = 0
+			end = -1
+			ranged = false
+			src.mu.Lock()
+			src.size = 0
+			src.rangeEnabled = false
+			src.mu.Unlock()
+		}
+	}
 
 	writeHeaders(w, meta, start, end, ranged)
 	if ranged {
 		w.WriteHeader(http.StatusPartialContent)
 	}
+	if producer, ok := reader.(production.Reader); ok && producer.Production() != nil {
+		if flusher, ok := w.(http.Flusher); ok {
+			flusher.Flush()
+		}
+	}
 	limit := int64(-1)
 	if end >= start {
 		limit = end - start + 1
@@ -675,3 +701,21 @@ func randomID(size int) (string, error) {
 	}
 	return hex.EncodeToString(buf), nil
 }
+
+// Production returns the active opener's input counter, if it generates output.
+func (r *Registry) Production(raw string) production.Source {
+	if r == nil {
+		return nil
+	}
+	src, err := r.get(raw)
+	if err != nil {
+		return nil
+	}
+	src.mu.Lock()
+	reader := src.producer
+	src.mu.Unlock()
+	if reader == nil {
+		return nil
+	}
+	return reader.Production()
+}

internal/controller/controller.go

@@ -1,6 +1,7 @@
 package controller
 
 import (
+	"github.com/GopeedLab/gopeed/internal/tempfiles"
 	"github.com/GopeedLab/gopeed/pkg/base"
 	"net/http"
 	"net/url"
@@ -9,8 +10,11 @@ import (
 )
 
 type Controller struct {
-	GetConfig func(v any)
-	GetProxy  func(requestProxy *base.RequestProxy) func(*http.Request) (*url.URL, error)
+	TempFiles         *tempfiles.Scope
+	ManagedProduction func(string) bool
+	TempDir           string
+	GetConfig         func(v any)
+	GetProxy          func(requestProxy *base.RequestProxy) func(*http.Request) (*url.URL, error)
 	FileController
 	//ContextDialer() (proxy.Dialer, error)
 }

internal/fetcher/fetcher.go

@@ -12,7 +12,7 @@ import (
 // Each download task will have a corresponding Fetcher instance for the management of the download task
 type Fetcher interface {
 	Setup(ctl *controller.Controller)
-	Resolve(req *base.Request, opts *base.Options) error
+	Resolve(req *base.Request) error
 	Start() error
 	// Patch modifies task-specific data based on the protocol.
 	// For HTTP: can modify Request info (URL, headers, etc.)
@@ -106,7 +106,13 @@ func (s *SchemeFilter) Match(uri string) bool {
 	case FilterTypeUrl:
 		return strings.HasPrefix(uriUpper, patternUpper+":")
 	case FilterTypeFile:
-		return strings.HasSuffix(uriUpper, "."+patternUpper)
+		// Strip query and fragment before matching so URLs like
+		// https://example.com/video.m3u8?sign=abc still route by extension.
+		clean := uri
+		if idx := strings.IndexAny(clean, "?#"); idx >= 0 {
+			clean = clean[:idx]
+		}
+		return strings.HasSuffix(strings.ToUpper(clean), "."+patternUpper)
 	case FilterTypeBase64:
 		return strings.HasPrefix(uriUpper, "DATA:"+patternUpper+";BASE64,")
 	}

internal/fetcher/jobs.go

@@ -0,0 +1,72 @@
+package fetcher
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+)
+
+type TriggerSource string
+
+const (
+	TriggerScheduled TriggerSource = "scheduled"
+	TriggerManual    TriggerSource = "manual"
+)
+
+var ErrJobSkipped = errors.New("protocol job skipped")
+var ErrConfigChanged = errors.New("protocol configuration changed during execution")
+
+// ConfigState embeds the common backend-owned state section in a protocol config.
+// Public config PUTs always retain this section from the latest stored config.
+type ConfigState[T any] struct {
+	State T `json:"state"`
+}
+
+// ProtocolHost is scoped to one manager. UpdateState runs against the latest
+// config under Downloader's lock; callbacks must not perform network I/O.
+type ProtocolHost struct {
+	Read        func(any) error
+	UpdateState func(func(config, state json.RawMessage) (any, error)) error
+	Fetch       func(context.Context, string, int64, func([]byte) error) ([]byte, error)
+}
+
+func ReadConfig[T any](host ProtocolHost) (*T, error) {
+	var cfg T
+	if err := host.Read(&cfg); err != nil {
+		return nil, err
+	}
+	return &cfg, nil
+}
+
+// UpdateState gives the callback a detached config snapshot and mutable state.
+// Only the state is committed; edits to the config snapshot are discarded.
+func UpdateState[C, S any](host ProtocolHost, update func(*C, *S) error) error {
+	return host.UpdateState(func(rawConfig, rawState json.RawMessage) (any, error) {
+		var cfg C
+		var state S
+		if err := json.Unmarshal(rawConfig, &cfg); err != nil {
+			return nil, err
+		}
+		if err := json.Unmarshal(rawState, &state); err != nil {
+			return nil, err
+		}
+		if err := update(&cfg, &state); err != nil {
+			return nil, err
+		}
+		return &state, nil
+	})
+}
+
+type CronJob struct {
+	Name    string
+	Every   time.Duration
+	Timeout time.Duration
+	Run     func(context.Context, TriggerSource) error
+}
+type CronProvider interface{ CronJobs(ProtocolHost) []CronJob }
+
+// ConfigNormalizer is optional. It owns protocol validation and derived fields.
+type ConfigNormalizer interface {
+	NormalizeConfig(json.RawMessage) (any, error)
+}

internal/githubmirror/README.md

@@ -0,0 +1,73 @@
+# GitHub mirror execution
+
+This package owns GitHub URL rewriting and execution strategies. It depends only
+on the standard library and does not depend on Downloader, HTTP clients, Git, or
+storage. Downloader persists `Config` at its top-level `githubMirror` field;
+`pkg/base` preserves the existing configuration names through aliases.
+
+## Race: resource reads
+
+```go
+body, err := githubmirror.Race(ctx, cfg.GithubMirror, rawURL,
+    githubmirror.Options[[]byte]{
+        Kind:    githubmirror.Resource,
+        Timeout: 30 * time.Second,
+    },
+    func(ctx context.Context, candidate string) ([]byte, error) {
+        return fetchAndValidate(ctx, client, candidate)
+    },
+)
+```
+
+The callback owns HTTP requests, size limits, and content validation. The first
+completed valid result wins. Other operations are canceled and drained. There is
+no HEAD-probe assumption or client-specific HTTP behavior inside the executor.
+
+## Fallback: repository operations
+
+```go
+repo, err := githubmirror.Fallback(ctx, cfg.GithubMirror, officialURL,
+    githubmirror.Options[*git.Repository]{
+        Kind: githubmirror.Repository,
+    },
+    func(ctx context.Context, candidate string) (*git.Repository, error) {
+        // Use a clean temporary checkout for each attempt.
+        return clone(ctx, candidate)
+    },
+)
+```
+
+The official URL is attempted first; mirrors follow their configured order.
+jsDelivr is excluded for repositories. Stop on the first success. Perform
+persistent installation or other business state changes after success, rather
+than inside a potentially repeated attempt.
+
+## Results with resources
+
+For temporary files, set `Options[*Download].Discard` to remove the file. Return
+the partial `*Download` alongside errors, so cleanup also covers failed reads or
+validation. The executor discards every failure and every race loser exactly
+once. The caller owns and must track/release the winning result.
+
+- `Timeout == 0` uses 30 seconds per resource attempt and no overall deadline
+  for repository attempts; a negative timeout is invalid. Extension Git HTTP
+  transport limits connections/TLS handshakes to 10 seconds and resets a 60-second
+  read deadline as data arrives. Slow continuous transfers can finish, while
+  stalled sources fail and allow ordered fallback. Parent cancellation still applies.
+- Attempts must honor the supplied context; draining waits for them to return.
+- Attempt contexts are canceled after return, so callbacks must finish reading
+  HTTP bodies before returning. Returning a still-streaming response is unsupported.
+- Discard callbacks must accept zero values, must not panic, and run serially.
+- Parent cancellation wins over a result selected while the parent is canceled;
+  the selected result is then discarded as well.
+- Errors preserve their causes through wrapping/joining for `errors.Is`.
+- `github.com` and `raw.githubusercontent.com` expand into eligible mirrors.
+  jsDelivr is only eligible for raw source resources. `api.github.com` is never
+  mirrored and is rejected by the public mirror candidates API.
+- Client application update checks request the official GitHub API directly,
+  falling back to the independent Gopeed website API on request or validation
+  failure. Only package downloads obtain URLs from
+  `POST /api/v1/mirrors/github/candidates`. Candidate generation never performs
+  HTTP requests.
+- Disabled mirrors and other URLs execute only the original URL.
+- Config is a caller-owned immutable snapshot for the duration of a call.

internal/githubmirror/config.go

@@ -0,0 +1,90 @@
+// Package githubmirror rewrites GitHub URLs and executes mirrored operations.
+package githubmirror
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+)
+
+type Mirror struct {
+	Type      string `json:"type"`
+	URL       string `json:"url"`
+	IsBuiltIn bool   `json:"isBuiltIn"`
+	IsDeleted bool   `json:"isDeleted"`
+}
+type Config struct {
+	Enabled bool     `json:"enabled"`
+	Mirrors []Mirror `json:"mirrors"`
+}
+
+func DefaultConfig() *Config {
+	return &Config{Enabled: true, Mirrors: []Mirror{
+		{Type: "jsdelivr", URL: "https://fastly.jsdelivr.net/gh", IsBuiltIn: true},
+		{Type: "ghProxy", URL: "https://fastgit.cc", IsBuiltIn: true},
+		{Type: "ghProxy", URL: "https://gh-proxy.com", IsBuiltIn: true},
+		{Type: "ghProxy", URL: "https://ghfast.top", IsBuiltIn: true},
+	}}
+}
+func (c *Config) Validate() error {
+	if len(c.Mirrors) > 32 {
+		return fmt.Errorf("too many GitHub mirrors")
+	}
+	for _, mirror := range c.Mirrors {
+		u, err := url.Parse(mirror.URL)
+		if err != nil || u == nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" {
+			return fmt.Errorf("invalid GitHub mirror URL")
+		}
+		if mirror.Type != "jsdelivr" && mirror.Type != "ghProxy" {
+			return fmt.Errorf("invalid GitHub mirror type: %s", mirror.Type)
+		}
+	}
+	return nil
+}
+
+// Kind describes what a candidate endpoint must support.
+type Kind uint8
+
+const (
+	Resource Kind = iota
+	Repository
+)
+
+// Candidates preserves the official URL first. jsDelivr is only eligible for
+// raw source resources; Git operations use mirrors supporting Git Smart HTTP.
+// GitHub API URLs are never mirrored.
+func Candidates(c *Config, raw string, kind Kind) []string {
+	result := []string{raw}
+	u, err := url.Parse(raw)
+	if err != nil || c == nil || !c.Enabled || u.User != nil || (u.Scheme != "https" && u.Scheme != "http") {
+		return result
+	}
+	if u.Host != "github.com" && u.Host != "raw.githubusercontent.com" {
+		return result
+	}
+	seen := map[string]bool{raw: true}
+	for _, mirror := range c.Mirrors {
+		if mirror.IsDeleted {
+			continue
+		}
+		var candidate string
+		switch mirror.Type {
+		case "ghProxy":
+			candidate = strings.TrimRight(mirror.URL, "/") + "/" + raw
+		case "jsdelivr":
+			if kind == Repository || u.Host != "raw.githubusercontent.com" {
+				continue
+			}
+			parts := strings.SplitN(strings.TrimPrefix(u.EscapedPath(), "/"), "/", 4)
+			if len(parts) != 4 {
+				continue
+			}
+			candidate = strings.TrimRight(mirror.URL, "/") + "/" + parts[0] + "/" + parts[1] + "@" + parts[2] + "/" + parts[3]
+		}
+		if candidate != "" && !seen[candidate] {
+			result = append(result, candidate)
+			seen[candidate] = true
+		}
+	}
+	return result
+}

internal/githubmirror/config_test.go

@@ -0,0 +1,38 @@
+package githubmirror
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestMirrorCandidates(t *testing.T) {
+	cfg := &Config{Enabled: true, Mirrors: []Mirror{
+		{Type: "jsdelivr", URL: "https://cdn.example/gh/"},
+		{Type: "ghProxy", URL: "https://mirror.example/"},
+		{Type: "ghProxy", URL: "https://deleted.example", IsDeleted: true},
+	}}
+	source := "https://raw.githubusercontent.com/owner/repo/main/a.txt"
+	want := []string{source, "https://cdn.example/gh/owner/repo@main/a.txt", "https://mirror.example/" + source}
+	if got := Candidates(cfg, source, Resource); !reflect.DeepEqual(got, want) {
+		t.Fatalf("got %v", got)
+	}
+	repo := "https://github.com/owner/repo.git"
+	if got := Candidates(cfg, repo, Repository); !reflect.DeepEqual(got, []string{repo, "https://mirror.example/" + repo}) {
+		t.Fatalf("git candidates %v", got)
+	}
+	for _, raw := range []string{"https://github.com.evil.example/a", "https://example.com/a", "https://user:[email protected]/a"} {
+		if got := Candidates(cfg, raw, Resource); !reflect.DeepEqual(got, []string{raw}) {
+			t.Fatalf("unexpected mirror: %v", got)
+		}
+	}
+	apiURL := "https://api.github.com/repos/GopeedLab/gopeed/releases?per_page=10"
+	for _, kind := range []Kind{Resource, Repository} {
+		if got := Candidates(cfg, apiURL, kind); !reflect.DeepEqual(got, []string{apiURL}) {
+			t.Fatalf("GitHub API must never use mirrors: %v", got)
+		}
+	}
+	cfg.Enabled = false
+	if got := Candidates(cfg, source, Resource); !reflect.DeepEqual(got, []string{source}) {
+		t.Fatalf("disabled mirror: %v", got)
+	}
+}

internal/githubmirror/execute.go

@@ -0,0 +1,160 @@
+package githubmirror
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+)
+
+// Options configures execution, not URL persistence. Discard releases results
+// from failed attempts and successful race losers, including partial results
+// returned together with an error. The caller owns the winning result.
+type Options[T any] struct {
+	Kind Kind
+	// Timeout limits each attempt. Zero uses 30 seconds for resources and no
+	// overall deadline for repositories, whose transport owns idle timeouts.
+	Timeout time.Duration
+	Discard func(T)
+}
+
+// Attempt must honor ctx and return a completed, validated result. Its context
+// is canceled after it returns, so live response streams must not be returned.
+// Return any partially acquired resources along with errors so Discard can
+// release them. Failed attempts must not mutate persistent business state.
+type Attempt[T any] func(context.Context, string) (T, error)
+
+const defaultTimeout = 30 * time.Second
+
+func prepare[T any](ctx context.Context, config *Config, raw string, options Options[T], attempt Attempt[T]) ([]string, time.Duration, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, 0, err
+	}
+	if raw == "" {
+		return nil, 0, errors.New("empty GitHub source URL")
+	}
+	if options.Kind != Resource && options.Kind != Repository {
+		return nil, 0, errors.New("invalid GitHub resource kind")
+	}
+	if options.Timeout < 0 {
+		return nil, 0, errors.New("invalid GitHub attempt timeout")
+	}
+	if attempt == nil {
+		return nil, 0, errors.New("GitHub mirror attempt is required")
+	}
+	if config != nil {
+		if err := config.Validate(); err != nil {
+			return nil, 0, err
+		}
+	}
+	timeout := options.Timeout
+	if timeout == 0 && options.Kind == Resource {
+		timeout = defaultTimeout
+	}
+	return Candidates(config, raw, options.Kind), timeout, nil
+}
+func invoke[T any](ctx context.Context, timeout time.Duration, candidate string, attempt Attempt[T]) (value T, err error) {
+	var cancel context.CancelFunc
+	if timeout > 0 {
+		ctx, cancel = context.WithTimeout(ctx, timeout)
+	} else {
+		ctx, cancel = context.WithCancel(ctx)
+	}
+	defer cancel()
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			err = fmt.Errorf("GitHub mirror attempt panicked: %v", recovered)
+		}
+	}()
+	value, err = attempt(ctx, candidate)
+	if err == nil {
+		err = ctx.Err()
+	}
+	return
+}
+func discard[T any](options Options[T], value T) {
+	if options.Discard != nil {
+		options.Discard(value)
+	}
+}
+
+// Race executes the official URL and eligible mirrors concurrently. The first
+// completed successful result wins; losing attempts are canceled and drained
+// before return so no temporary files or other resources outlive the call.
+// HTTP status/content validation is the attempt's responsibility.
+func Race[T any](ctx context.Context, config *Config, raw string, options Options[T], attempt Attempt[T]) (T, error) {
+	var zero T
+	candidates, timeout, err := prepare(ctx, config, raw, options, attempt)
+	if err != nil {
+		return zero, err
+	}
+	raceCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	type outcome struct {
+		index int
+		value T
+		err   error
+	}
+	outcomes := make(chan outcome, len(candidates))
+	for index, candidate := range candidates {
+		go func(index int, candidate string) {
+			value, err := invoke(raceCtx, timeout, candidate, attempt)
+			outcomes <- outcome{index, value, err}
+		}(index, candidate)
+	}
+	var winner T
+	won := false
+	failures := make([]error, len(candidates))
+	for range candidates {
+		outcome := <-outcomes
+		if !won && outcome.err == nil && ctx.Err() == nil {
+			winner = outcome.value
+			won = true
+			cancel()
+		} else {
+			discard(options, outcome.value)
+			if outcome.err != nil {
+				failures[outcome.index] = fmt.Errorf("GitHub source %d: %w", outcome.index+1, outcome.err)
+			}
+			if ctx.Err() != nil {
+				cancel()
+			}
+		}
+	}
+	if err := ctx.Err(); err != nil {
+		if won {
+			discard(options, winner)
+		}
+		return zero, err
+	}
+	if won {
+		return winner, nil
+	}
+	return zero, fmt.Errorf("all GitHub sources failed: %w", errors.Join(failures...))
+}
+
+// Fallback executes the official URL first, then eligible mirrors in their
+// configured order. It stops immediately on success and cleans every failure.
+func Fallback[T any](ctx context.Context, config *Config, raw string, options Options[T], attempt Attempt[T]) (T, error) {
+	var zero T
+	candidates, timeout, err := prepare(ctx, config, raw, options, attempt)
+	if err != nil {
+		return zero, err
+	}
+	failures := make([]error, 0, len(candidates))
+	for index, candidate := range candidates {
+		if err := ctx.Err(); err != nil {
+			return zero, err
+		}
+		value, err := invoke(ctx, timeout, candidate, attempt)
+		if err == nil && ctx.Err() == nil {
+			return value, nil
+		}
+		discard(options, value)
+		if parentErr := ctx.Err(); parentErr != nil {
+			return zero, parentErr
+		}
+		failures = append(failures, fmt.Errorf("GitHub source %d: %w", index+1, err))
+	}
+	return zero, fmt.Errorf("all GitHub sources failed: %w", errors.Join(failures...))
+}

internal/githubmirror/execute_test.go

@@ -0,0 +1,214 @@
+package githubmirror
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+const testSource = "https://github.com/owner/repo.git"
+
+func testConfig() *Config {
+	return &Config{Enabled: true, Mirrors: []Mirror{
+		{Type: "ghProxy", URL: "https://first.example"},
+		{Type: "ghProxy", URL: "https://second.example"},
+	}}
+}
+func TestRaceWinsAndDrainsOwnedResults(t *testing.T) {
+	config := testConfig()
+	candidates := Candidates(config, testSource, Resource)
+	var started sync.WaitGroup
+	started.Add(len(candidates))
+	discarded := []string{}
+	winner, err := Race(context.Background(), config, testSource, Options[string]{
+		Discard: func(value string) { discarded = append(discarded, value) },
+	}, func(ctx context.Context, address string) (string, error) {
+		started.Done()
+		started.Wait()
+		switch address {
+		case candidates[0]:
+			return address, errors.New("official offline")
+		case candidates[1]:
+			return address, nil
+		default:
+			<-ctx.Done()
+			return address, ctx.Err()
+		}
+	})
+	if err != nil || winner != candidates[1] {
+		t.Fatalf("winner=%s err=%v", winner, err)
+	}
+	if len(discarded) != 2 || !contains(discarded, candidates[0]) || !contains(discarded, candidates[2]) {
+		t.Fatalf("discarded %v", discarded)
+	}
+}
+func contains(values []string, value string) bool {
+	for _, item := range values {
+		if item == value {
+			return true
+		}
+	}
+	return false
+}
+func TestRaceCleansSimultaneousSuccessfulLosers(t *testing.T) {
+	config := testConfig()
+	var started sync.WaitGroup
+	started.Add(3)
+	cleaned := []string{}
+	winner, err := Race(context.Background(), config, testSource, Options[string]{Discard: func(value string) { cleaned = append(cleaned, value) }}, func(_ context.Context, address string) (string, error) {
+		started.Done()
+		started.Wait()
+		return address, nil
+	})
+	if err != nil || winner == "" || len(cleaned) != 2 || contains(cleaned, winner) {
+		t.Fatalf("winner=%s discarded=%v err=%v", winner, cleaned, err)
+	}
+}
+func TestRaceParentCancellationCleansWinnerToo(t *testing.T) {
+	config := testConfig()
+	config.Mirrors = config.Mirrors[:1]
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	cleaned := []string{}
+	winner, err := Race(ctx, config, testSource, Options[string]{Discard: func(value string) { cleaned = append(cleaned, value) }}, func(ctx context.Context, address string) (string, error) {
+		if address == testSource {
+			return address, nil
+		}
+		<-ctx.Done()
+		cancel()
+		return address, ctx.Err()
+	})
+	if !errors.Is(err, context.Canceled) || winner != "" || len(cleaned) != 2 || !contains(cleaned, testSource) {
+		t.Fatalf("winner=%s cleanup=%v err=%v", winner, cleaned, err)
+	}
+}
+func TestRaceTimeoutAndErrorAggregation(t *testing.T) {
+	expected := errors.New("offline")
+	config := testConfig()
+	config.Mirrors = config.Mirrors[:1]
+	discarded := 0
+	_, err := Race(context.Background(), config, testSource, Options[string]{Timeout: 10 * time.Millisecond, Discard: func(string) { discarded++ }}, func(ctx context.Context, address string) (string, error) {
+		if address == testSource {
+			return address, expected
+		}
+		<-ctx.Done()
+		return address, ctx.Err()
+	})
+	if !errors.Is(err, expected) || !errors.Is(err, context.DeadlineExceeded) || discarded != 2 {
+		t.Fatalf("discarded=%d err=%v", discarded, err)
+	}
+}
+func TestFallbackPreservesOrderAndStopsOnSuccess(t *testing.T) {
+	config := testConfig()
+	candidates := Candidates(config, testSource, Repository)
+	tried := []string{}
+	cleaned := []string{}
+	winner, err := Fallback(context.Background(), config, testSource, Options[string]{Kind: Repository, Discard: func(value string) { cleaned = append(cleaned, value) }}, func(_ context.Context, address string) (string, error) {
+		tried = append(tried, address)
+		if address == candidates[1] {
+			return address, nil
+		}
+		return address, errors.New("offline")
+	})
+	if err != nil || winner != candidates[1] || !reflect.DeepEqual(tried, candidates[:2]) || !reflect.DeepEqual(cleaned, candidates[:1]) {
+		t.Fatalf("winner=%s tried=%v discarded=%v err=%v", winner, tried, cleaned, err)
+	}
+	tried = nil
+	_, err = Fallback(context.Background(), config, testSource, Options[string]{Kind: Repository}, func(_ context.Context, address string) (string, error) {
+		tried = append(tried, address)
+		return address, nil
+	})
+	if err != nil || !reflect.DeepEqual(tried, candidates[:1]) {
+		t.Fatalf("tried=%v err=%v", tried, err)
+	}
+}
+func TestFallbackTimeoutContinuesWithFreshContext(t *testing.T) {
+	discarded := []string{}
+	winner, err := Fallback(context.Background(), testConfig(), testSource, Options[string]{Kind: Repository, Timeout: 10 * time.Millisecond, Discard: func(value string) { discarded = append(discarded, value) }}, func(ctx context.Context, address string) (string, error) {
+		if address == testSource {
+			<-ctx.Done()
+			return address, ctx.Err()
+		}
+		if err := ctx.Err(); err != nil {
+			return address, err
+		}
+		return address, nil
+	})
+	if err != nil || !strings.HasPrefix(winner, "https://first.example/") || !reflect.DeepEqual(discarded, []string{testSource}) {
+		t.Fatalf("winner=%s cleanup=%v err=%v", winner, discarded, err)
+	}
+}
+func TestFallbackCancellationStopsBeforeNextMirror(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	calls := 0
+	cleaned := 0
+	_, err := Fallback(ctx, testConfig(), testSource, Options[string]{Kind: Repository, Discard: func(string) { cleaned++ }}, func(ctx context.Context, address string) (string, error) {
+		calls++
+		cancel()
+		return address, ctx.Err()
+	})
+	if !errors.Is(err, context.Canceled) || calls != 1 || cleaned != 1 {
+		t.Fatalf("calls=%d discarded=%d err=%v", calls, cleaned, err)
+	}
+}
+func TestExecutorsDoNotStartInvalidOrCanceledRequests(t *testing.T) {
+	canceled, cancel := context.WithCancel(context.Background())
+	cancel()
+	for _, test := range []struct {
+		ctx     context.Context
+		config  *Config
+		options Options[string]
+		attempt Attempt[string]
+	}{
+		{ctx: canceled, options: Options[string]{}, attempt: func(context.Context, string) (string, error) { t.Fatal("called after cancellation"); return "", nil }},
+		{ctx: context.Background(), options: Options[string]{Kind: 99}, attempt: func(context.Context, string) (string, error) { t.Fatal("invalid kind"); return "", nil }},
+		{ctx: context.Background(), options: Options[string]{Timeout: -time.Second}, attempt: func(context.Context, string) (string, error) { t.Fatal("invalid timeout"); return "", nil }},
+		{ctx: context.Background(), options: Options[string]{}, attempt: nil},
+		{ctx: context.Background(), config: &Config{Mirrors: []Mirror{{Type: "invalid", URL: "https://mirror.example"}}}, attempt: func(context.Context, string) (string, error) { t.Fatal("invalid config"); return "", nil }},
+	} {
+		if _, err := Race(test.ctx, test.config, testSource, test.options, test.attempt); err == nil {
+			t.Fatal("invalid race accepted")
+		}
+		if _, err := Fallback(test.ctx, test.config, testSource, test.options, test.attempt); err == nil {
+			t.Fatal("invalid fallback accepted")
+		}
+	}
+}
+func TestAttemptPanicBecomesError(t *testing.T) {
+	attempt := func(context.Context, string) (string, error) { panic("broken operation") }
+	if _, err := Race(context.Background(), nil, testSource, Options[string]{}, attempt); err == nil || !strings.Contains(err.Error(), "broken operation") {
+		t.Fatal(err)
+	}
+	if _, err := Fallback(context.Background(), nil, testSource, Options[string]{}, attempt); err == nil || !strings.Contains(err.Error(), "broken operation") {
+		t.Fatal(err)
+	}
+}
+func TestNonGithubResourcesAndDisabledMirrorsUseOnlyOriginal(t *testing.T) {
+	for _, test := range []struct {
+		config *Config
+		raw    string
+	}{{testConfig(), "https://example.com/resource"}, {&Config{Enabled: false, Mirrors: testConfig().Mirrors}, testSource}} {
+		calls := 0
+		got, err := Race(context.Background(), test.config, test.raw, Options[string]{}, func(_ context.Context, address string) (string, error) { calls++; return address, nil })
+		if err != nil || got != test.raw || calls != 1 {
+			t.Fatalf("got=%s calls=%d err=%v", got, calls, err)
+		}
+	}
+}
+
+func TestRepositoryAttemptsHaveNoDefaultDeadline(t *testing.T) {
+	value, err := Fallback(context.Background(), nil, testSource, Options[string]{Kind: Repository}, func(ctx context.Context, raw string) (string, error) {
+		if _, ok := ctx.Deadline(); ok {
+			t.Fatal("repository attempt has a total deadline")
+		}
+		return raw, nil
+	})
+	if err != nil || value != testSource {
+		t.Fatalf("value=%s error=%v", value, err)
+	}
+}

internal/production/progress.go

@@ -0,0 +1,35 @@
+// Package production associates generated resources with their input progress.
+package production
+
+import (
+	"context"
+	"sync"
+)
+
+// Source counts unique input bytes and total received bytes (including refetches).
+// Implementations must support concurrent snapshots.
+type Source interface {
+	Progress() (downloaded, received int64)
+}
+
+// Reader resolves its optional producer before response headers are sent.
+// A nil producer preserves ordinary Blob behavior.
+type Reader interface {
+	Production() Source
+	WaitProduction(context.Context) error
+}
+type Registry struct {
+	mu      sync.Mutex
+	sources map[string]Source
+}
+
+func (r *Registry) Set(id string, source Source) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.sources == nil {
+		r.sources = make(map[string]Source)
+	}
+	r.sources[id] = source
+}
+func (r *Registry) Get(id string) Source { r.mu.Lock(); defer r.mu.Unlock(); return r.sources[id] }
+func (r *Registry) Remove(id string)     { r.mu.Lock(); defer r.mu.Unlock(); delete(r.sources, id) }

internal/protocol/bt/config.go

@@ -1,12 +1,37 @@
 package bt
 
+import (
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+)
+
+type trackerSubscriptionStatus struct {
+	Success       bool      `json:"success"`
+	TrackerCount  int       `json:"trackerCount"`
+	LastFetchTime time.Time `json:"lastFetchTime"`
+}
+
+type state struct {
+	TrackerSubscriptionStatuses map[string]trackerSubscriptionStatus `json:"trackerSubscriptionStatuses"`
+	TrackerSources              map[string][]string                  `json:"trackerSources"`
+	LastTrackerUpdateTime       time.Time                            `json:"lastTrackerUpdateTime"`
+}
+
 type config struct {
-	ListenPort int      `json:"listenPort"`
-	Trackers   []string `json:"trackers"`
+	fetcher.ConfigState[state]
+	TrackerSubscribeURLs []string `json:"trackerSubscribeUrls"`
+	AutoUpdateTrackers   bool     `json:"autoUpdateTrackers"`
+	CustomTrackers       []string `json:"customTrackers"`
+	ListenPort           int      `json:"listenPort"`
 	// SeedKeep is always keep seeding after downloading is complete, unless manually stopped.
 	SeedKeep bool `json:"seedKeep"`
 	// SeedRatio is the ratio of uploaded data to downloaded data to seed.
 	SeedRatio float64 `json:"seedRatio"`
 	// SeedTime is the time in seconds to seed after downloading is complete.
 	SeedTime int64 `json:"seedTime"`
+	// DisableDHT and DisablePEX turn off DHT and PEX peer discovery. Like ListenPort,
+	// they are read when the shared client is built.
+	DisableDHT bool `json:"disableDht"`
+	DisablePEX bool `json:"disablePex"`
 }

internal/protocol/bt/download_test.go

@@ -0,0 +1,464 @@
+package bt
+
+import (
+	"encoding/json"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/controller"
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+	"github.com/GopeedLab/gopeed/pkg/base"
+	btprotocol "github.com/GopeedLab/gopeed/pkg/protocol/bt"
+	"github.com/anacrolix/torrent"
+	pp "github.com/anacrolix/torrent/peer_protocol"
+	"golang.org/x/time/rate"
+)
+
+type btDownloadHarness struct {
+	*Fetcher
+	pendingRequests atomic.Int64
+}
+
+// These tests exercise the BT fetcher, native storage and real peer protocol.
+// All content is generated locally and served by a loopback seeder.
+func btDownloadFetcher(t *testing.T, f fetcher.Fetcher) *btDownloadHarness {
+	t.Helper()
+	if f == nil {
+		f = new(FetcherManager).Build()
+	}
+	ctl := controller.NewController()
+	ctl.GetConfig = func(v any) {
+		encoded, err := json.Marshal(new(FetcherManager).DefaultConfig())
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := json.Unmarshal(encoded, v); err != nil {
+			t.Fatal(err)
+		}
+	}
+	f.Setup(ctl)
+	t.Cleanup(func() {
+		if err := f.Close(); err != nil {
+			t.Error(err)
+		}
+		if err := closeClient(); err != nil {
+			t.Error(err)
+		}
+	})
+	h := &btDownloadHarness{Fetcher: f.(*Fetcher)}
+	// Keep the test client on loopback and observe real cancellation replies.
+	// Waiting for them avoids the pinned library's immediate cancel/resume
+	// request scheduling bug, without relying on arbitrary sleep durations.
+	cfg = torrent.TestingConfig(t)
+	cfg.DisableTrackers = false
+	cfg.Seed = true
+	cfg.DisableUTP = true
+	cfg.DisableIPv6 = true
+	cfg.DisableWebtorrent = true
+	cfg.KeepAliveTimeout = time.Minute
+	cfg.MaxAllocPeerRequestDataPerConn = 1 << 20
+	cfg.Callbacks.SentRequest = []func(torrent.PeerRequestEvent){func(torrent.PeerRequestEvent) {
+		h.pendingRequests.Add(1)
+	}}
+	cfg.Callbacks.ReadMessage = func(_ *torrent.PeerConn, msg *pp.Message) {
+		if !msg.Keepalive && (msg.Type == pp.Piece || msg.Type == pp.Reject) {
+			h.pendingRequests.Add(-1)
+		}
+	}
+	var err error
+	client, err = torrent.NewClient(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return h
+}
+
+func btResolve(t *testing.T, f *btDownloadHarness, source string) {
+	t.Helper()
+	if err := f.Resolve(&base.Request{URL: source}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func btStart(t *testing.T, f *btDownloadHarness) {
+	t.Helper()
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func btAwaitDone(t *testing.T, f *btDownloadHarness) {
+	t.Helper()
+	done := make(chan error, 1)
+	go func() { done <- f.Wait() }()
+	timeout := time.NewTimer(20 * time.Second)
+	defer timeout.Stop()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("BT download failed: %v", err)
+		}
+		if !f.isDone() {
+			t.Fatal("Wait returned before selected files were verified")
+		}
+	case <-timeout.C:
+		var status strings.Builder
+		client.WriteStatus(&status)
+		t.Log(status.String())
+		t.Fatalf("BT download did not finish: progress=%v stats=%+v pieces=%+v peers=%+v", f.Progress(), f.torrent.Stats(), f.torrent.PieceStateRuns(), f.Stats().Runtime)
+	}
+}
+
+func btAwaitPartial(t *testing.T, f *btDownloadHarness) {
+	t.Helper()
+	timeout := time.NewTimer(15 * time.Second)
+	defer timeout.Stop()
+	ticker := time.NewTicker(20 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			progress := f.Progress().TotalDownloaded()
+			if progress >= 32*1024 && progress < f.Meta().Res.Size {
+				return
+			}
+		case <-timeout.C:
+			t.Fatal("BT transfer did not reach partial progress")
+		}
+	}
+}
+
+func btPause(t *testing.T, f *btDownloadHarness) {
+	t.Helper()
+	if err := f.Pause(); err != nil {
+		t.Fatal(err)
+	}
+	timeout := time.NewTimer(5 * time.Second)
+	defer timeout.Stop()
+	ticker := time.NewTicker(10 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		if f.pendingRequests.Load() == 0 {
+			// The message callback runs under the client lock. Acquiring that
+			// lock ensures the final cancellation reply has finished processing.
+			client.Stats()
+			return
+		}
+		select {
+		case <-ticker.C:
+		case <-timeout.C:
+			t.Fatal("peer did not acknowledge cancelled requests")
+		}
+	}
+}
+
+func TestBTDownloadSources(t *testing.T) {
+	for _, kind := range []string{"magnet", "torrent", "file URI", "data URI"} {
+		t.Run(kind, func(t *testing.T) {
+			fixture := newBTFixture(t, map[string][]byte{"": btPayload(96*1024, kind)}, 0)
+			source := fixture.Magnet
+			switch kind {
+			case "torrent":
+				source = fixture.TorrentFile
+			case "file URI":
+				source = fixture.FileURI()
+			case "data URI":
+				source = fixture.DataURI
+			}
+			f := btDownloadFetcher(t, nil)
+			btResolve(t, f, source)
+			if f.Meta().Opts != nil {
+				t.Fatal("Resolve assigned download options")
+			}
+			f.storage.mu.RLock()
+			bound := f.storage.owner != nil
+			f.storage.mu.RUnlock()
+			if bound {
+				t.Fatal("Resolve bound download storage")
+			}
+			resolvedTorrent := f.torrent
+			dir := filepath.Join(t.TempDir(), "chosen-after-resolve")
+			f.Meta().Opts = &base.Options{Path: dir}
+			if _, err := os.Stat(dir); !os.IsNotExist(err) {
+				t.Fatalf("output directory exists before Start: %v", err)
+			}
+			btStart(t, f)
+			if f.torrent != resolvedTorrent {
+				t.Fatal("Start replaced the resolved torrent")
+			}
+			btAwaitDone(t, f)
+			fixture.AssertFiles(t, dir)
+		})
+	}
+}
+
+func TestBTDirectDownloadWithExtraTrackers(t *testing.T) {
+	for _, source := range []string{"request", "config", "subscription"} {
+		t.Run(source, func(t *testing.T) {
+			fixture := makeBTFixture(t, map[string][]byte{
+				"a.bin":        btPayload(20*1024, "direct-a"),
+				"nested/b.bin": btPayload(48*1024, "direct-b"),
+			}, 0, false, false)
+			magnet, err := url.Parse(fixture.Magnet)
+			if err != nil {
+				t.Fatal(err)
+			}
+			query := magnet.Query()
+			query.Del("tr")
+			query.Del("x.pe")
+			magnet.RawQuery = query.Encode()
+			req := &base.Request{URL: magnet.String()}
+			f := btDownloadFetcher(t, nil)
+			if source == "request" {
+				req.Extra = &btprotocol.ReqExtra{Trackers: []string{fixture.TrackerURL}}
+			} else {
+				backendConfig := new(FetcherManager).DefaultConfig().(*config)
+				if source == "config" {
+					backendConfig.CustomTrackers = []string{fixture.TrackerURL}
+				} else {
+					backendConfig.TrackerSubscribeURLs = []string{"https://subscription.example/list"}
+					backendConfig.State.TrackerSources[backendConfig.TrackerSubscribeURLs[0]] = []string{fixture.TrackerURL}
+				}
+				f.ctl.GetConfig = func(dst any) {
+					raw, err := json.Marshal(backendConfig)
+					if err != nil {
+						t.Error(err)
+						return
+					}
+					if err := json.Unmarshal(raw, dst); err != nil {
+						t.Error(err)
+					}
+				}
+			}
+			// CreateDirect supplies options before Downloader resolves the task.
+			dir := filepath.Join(t.TempDir(), "direct-download")
+			opts := &base.Options{Path: dir, SelectFiles: []int{}}
+			f.Meta().Opts = opts
+			resolved := make(chan error, 1)
+			go func() { resolved <- f.Resolve(req) }()
+			select {
+			case err := <-resolved:
+				if err != nil {
+					t.Fatal(err)
+				}
+			case <-time.After(5 * time.Second):
+				f.torrentDropFunc()
+				<-resolved
+				t.Fatal("direct magnet download did not obtain metadata from its extra tracker")
+			}
+			if f.Meta().Opts != opts || len(opts.SelectFiles) != len(fixture.Files) {
+				t.Fatal("resolution lost direct download options or did not select all files")
+			}
+			btStart(t, f)
+			btAwaitDone(t, f)
+			fixture.AssertFiles(t, dir)
+		})
+	}
+}
+
+func TestBTDownloadSelectedFiles(t *testing.T) {
+	fixture := newBTFixture(t, map[string][]byte{
+		"a.bin": btPayload(20*1024, "a"), "nested/b.bin": btPayload(48*1024, "b"),
+	}, 0)
+	f := btDownloadFetcher(t, nil)
+	dir := t.TempDir()
+	btResolve(t, f, fixture.Magnet)
+	selected := -1
+	for i, file := range f.Meta().Res.Files {
+		if file.Name == "b.bin" {
+			selected = i
+		}
+	}
+	if selected < 0 {
+		t.Fatal("selected file absent from metadata")
+	}
+	f.Meta().Opts = &base.Options{Path: dir}
+	if err := f.Patch(nil, &base.Options{SelectFiles: []int{selected}}); err != nil {
+		t.Fatal(err)
+	}
+	btStart(t, f)
+	btAwaitDone(t, f)
+	fixture.AssertFiles(t, dir, filepath.Join("bundle", "nested", "b.bin"))
+	if _, err := os.Stat(filepath.Join(dir, "bundle", "a.bin")); !os.IsNotExist(err) {
+		t.Fatalf("unselected output remains: %v", err)
+	}
+	if f.Meta().Res.Size != 48*1024 {
+		t.Fatal("selected resource size is incorrect")
+	}
+}
+
+func TestBTPauseAndResume(t *testing.T) {
+	fixture := newBTFixture(t, map[string][]byte{"": btPayload(512*1024, "pause")}, 64*1024)
+	f := btDownloadFetcher(t, nil)
+	dir := t.TempDir()
+	btResolve(t, f, fixture.Magnet)
+	f.Meta().Opts = &base.Options{Path: dir}
+	btStart(t, f)
+	btAwaitPartial(t, f)
+	btPause(t, f)
+	resolvedTorrent := f.torrent
+	fixture.Limiter.SetLimit(rate.Inf)
+	// Once cancelled requests have settled, no more data should arrive.
+	stats := f.torrent.Stats()
+	readWhilePaused := stats.BytesReadData.Int64()
+	time.Sleep(200 * time.Millisecond)
+	stats = f.torrent.Stats()
+	if stats.BytesReadData.Int64() != readWhilePaused || f.isDone() {
+		t.Fatal("data download continued while paused")
+	}
+	btStart(t, f)
+	if f.torrent != resolvedTorrent {
+		t.Fatal("resume replaced the resolved torrent")
+	}
+	btAwaitDone(t, f)
+	fixture.AssertFiles(t, dir)
+}
+
+type btFetcherCheckpoint struct {
+	Meta *fetcher.FetcherMeta `json:"meta"`
+	Data json.RawMessage      `json:"data"`
+}
+
+func btStore(t *testing.T, f *btDownloadHarness) []byte {
+	t.Helper()
+	data, err := new(FetcherManager).Store(f.Fetcher)
+	if err != nil {
+		t.Fatal(err)
+	}
+	encodedData, err := json.Marshal(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	encoded, err := json.Marshal(btFetcherCheckpoint{Meta: f.Meta(), Data: encodedData})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return encoded
+}
+
+func btRestore(t *testing.T, encoded []byte) *btDownloadHarness {
+	t.Helper()
+	var checkpoint btFetcherCheckpoint
+	if err := json.Unmarshal(encoded, &checkpoint); err != nil {
+		t.Fatal(err)
+	}
+	data, restore := new(FetcherManager).Restore()
+	if err := json.Unmarshal(checkpoint.Data, data); err != nil {
+		t.Fatal(err)
+	}
+	return btDownloadFetcher(t, restore(checkpoint.Meta, data))
+}
+
+func btCloseForRestart(t *testing.T, f *btDownloadHarness) {
+	t.Helper()
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := new(FetcherManager).Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestBTColdStartResume(t *testing.T) {
+	for _, kind := range []string{"v1", "hybrid"} {
+		t.Run(kind, func(t *testing.T) {
+			var fixture *btFixture
+			if kind == "hybrid" {
+				fixture = newBTHybridFixture(t, btPayload(512*1024, "restart-hybrid"))
+				fixture.Limiter.SetLimit(64 * 1024)
+			} else {
+				fixture = newBTFixture(t, map[string][]byte{"": btPayload(512*1024, "restart")}, 64*1024)
+			}
+			f := btDownloadFetcher(t, nil)
+			dir := t.TempDir()
+			btResolve(t, f, fixture.Magnet)
+			f.Meta().Opts = &base.Options{Path: dir}
+			btStart(t, f)
+			btAwaitPartial(t, f)
+			btPause(t, f)
+			checkpoint := btStore(t, f)
+			hash := f.Meta().Res.Hash
+			btCloseForRestart(t, f)
+			seedStats := fixture.Torrent.Stats()
+			sentBeforeRestart := seedStats.BytesWrittenData.Int64()
+			restored := btRestore(t, checkpoint)
+			if restored.Meta().Opts.Path != dir || restored.Meta().Res.Hash != hash {
+				t.Fatal("download directory or hash was lost")
+			}
+			fixture.Limiter.SetLimit(rate.Inf)
+			btStart(t, restored)
+			btAwaitDone(t, restored)
+			fixture.AssertFiles(t, dir)
+			seedStats = fixture.Torrent.Stats()
+			if sent := seedStats.BytesWrittenData.Int64() - sentBeforeRestart; sent >= 512*1024 {
+				t.Fatalf("restart redownloaded the entire file: %d bytes", sent)
+			}
+		})
+	}
+}
+
+func TestBTDownloadHybrid(t *testing.T) {
+	fixture := newBTHybridFixture(t, btPayload(80*1024, "hybrid-v2"))
+	f := btDownloadFetcher(t, nil)
+	dir := t.TempDir()
+	btResolve(t, f, fixture.Magnet)
+	f.Meta().Opts = &base.Options{Path: dir}
+	btStart(t, f)
+	btAwaitDone(t, f)
+	fixture.AssertFiles(t, dir)
+}
+
+func TestBTRepairCorruptedExistingFile(t *testing.T) {
+	fixture := newBTFixture(t, map[string][]byte{"": btPayload(128*1024, "repair")}, 0)
+	dir := t.TempDir()
+	damaged := append([]byte(nil), fixture.Files["payload.bin"]...)
+	damaged[20000] ^= 0xff
+	if err := os.WriteFile(filepath.Join(dir, "payload.bin"), damaged, 0600); err != nil {
+		t.Fatal(err)
+	}
+	f := btDownloadFetcher(t, nil)
+	btResolve(t, f, fixture.Magnet)
+	f.Meta().Opts = &base.Options{Path: dir}
+	btStart(t, f)
+	btAwaitDone(t, f)
+	fixture.AssertFiles(t, dir)
+}
+
+func TestBTPatchSelectionWhilePaused(t *testing.T) {
+	fixture := newBTFixture(t, map[string][]byte{"a.bin": btPayload(256*1024, "patch-a"), "b.bin": btPayload(256*1024, "patch-b")}, 64*1024)
+	f := btDownloadFetcher(t, nil)
+	dir := t.TempDir()
+	btResolve(t, f, fixture.Magnet)
+	f.Meta().Opts = &base.Options{Path: dir, SelectFiles: []int{0}}
+	btStart(t, f)
+	btAwaitPartial(t, f)
+	btPause(t, f)
+	if err := f.Patch(nil, &base.Options{SelectFiles: []int{1}}); err != nil {
+		t.Fatal(err)
+	}
+	fixture.Limiter.SetLimit(rate.Inf)
+	btStart(t, f)
+	btAwaitDone(t, f)
+	fixture.AssertFiles(t, dir, filepath.Join("bundle", "b.bin"))
+	for _, suffix := range []string{"", ".part"} {
+		if _, err := os.Stat(filepath.Join(dir, "bundle", "a.bin") + suffix); !os.IsNotExist(err) {
+			t.Fatalf("unselected output remains: %v", err)
+		}
+	}
+}
+
+func TestBTDownloadMultiFileWithEmptyFile(t *testing.T) {
+	fixture := newBTFixture(t, map[string][]byte{"empty.txt": {}, "nested/data.bin": btPayload(48*1024, "empty-file")}, 0)
+	f := btDownloadFetcher(t, nil)
+	dir := t.TempDir()
+	btResolve(t, f, fixture.Magnet)
+	f.Meta().Opts = &base.Options{Path: dir}
+	btStart(t, f)
+	btAwaitDone(t, f)
+	fixture.AssertFiles(t, dir)
+}

internal/protocol/bt/fetcher.go

@@ -3,11 +3,13 @@ package bt
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"net/url"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -33,6 +35,10 @@ var (
 )
 
 type Fetcher struct {
+	mu        sync.Mutex
+	closeOnce sync.Once
+	storage   *deferredFileStorage
+
 	ctl    *controller.Controller
 	config *config
 
@@ -77,6 +83,8 @@ func (f *Fetcher) initClient() (err error) {
 	cfg.Bep20 = fmt.Sprintf("-GP%s-", parseBep20())
 	cfg.ExtendedHandshakeClientVersion = fmt.Sprintf("Gopeed %s", base.Version)
 	cfg.ListenPort = f.config.ListenPort
+	cfg.NoDHT = f.config.DisableDHT
+	cfg.DisablePEX = f.config.DisablePEX
 	cfg.HTTPProxy = f.ctl.GetProxy(f.meta.Req.Proxy)
 	dnsResolver := &DnsCacheResolver{RefreshTimeout: 5 * time.Minute}
 	cfg.TrackerDialContext = dnsResolver.DialContext
@@ -92,13 +100,17 @@ func (f *Fetcher) initClient() (err error) {
 	return
 }
 
-func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
-	f.meta.Req = req
-	f.meta.Opts = opts
-	if f.meta.Opts == nil {
-		f.meta.Opts = &base.Options{}
+func (f *Fetcher) Resolve(req *base.Request) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.torrent != nil {
+		f.safeDrop()
+		f.torrent = nil
+		f.storage = nil
+		f.torrentReady.Store(false)
 	}
-	if err := f.addTorrent(req, false); err != nil {
+	f.meta.Req = req
+	if err := f.addTorrent(req); err != nil {
 		return err
 	}
 	f.updateRes()
@@ -106,12 +118,72 @@ func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
 }
 
 func (f *Fetcher) Start() (err error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.meta.Opts == nil || f.meta.Opts.Path == "" {
+		return errors.New("download directory is required when starting a torrent")
+	}
+	if err := f.torrentDropCtx.Err(); err != nil {
+		return err
+	}
 	if !f.torrentReady.Load() {
-		if err = f.addTorrent(f.meta.Req, false); err != nil {
+		if err = f.addTorrent(f.meta.Req); err != nil {
 			return
 		}
 	}
 
+	path := f.meta.Opts.Path
+	if err := os.MkdirAll(path, 0755); err != nil {
+		return err
+	}
+	hashes, err := f.storage.bind(storage.NewFileClientOpts{
+		ClientBaseDir: path,
+		FilePathMaker: func(opts storage.FilePathMakerOpts) string {
+			_, name := torrentFileLayout(opts.Info, *opts.File)
+			return name
+		},
+	})
+	if err != nil {
+		return err
+	}
+	if hashes != nil {
+		// File storage infers completion from final file names and sizes. Verify
+		// before publishing that state, or peers can see an unverified file as
+		// complete and disconnect before a damaged piece is discovered.
+		// Late v2 hashes schedule their own initial checks through the library.
+		changes := f.torrent.SubscribePieceStateChanges()
+		defer changes.Close()
+		for i, known := range hashes {
+			if !known {
+				continue
+			}
+			if err := f.torrentDropCtx.Err(); err != nil {
+				return err
+			}
+			if err := f.torrent.Piece(i).VerifyDataContext(f.torrentDropCtx); err != nil {
+				return err
+			}
+			// VerifyDataContext can return while the result is still being
+			// written to storage. Wait for it before refreshing completion.
+			for {
+				state := f.torrent.Piece(i).State()
+				if !state.Hashing && !state.QueuedForHash && !state.Marking {
+					break
+				}
+				select {
+				case <-changes.Values:
+				case <-f.torrentDropCtx.Done():
+					return f.torrentDropCtx.Err()
+				case <-f.torrent.Closed():
+					return errors.New("torrent closed during verification")
+				}
+			}
+		}
+		for i := range hashes {
+			f.torrent.Piece(i).UpdateCompletion()
+		}
+	}
+
 	files := f.torrent.Files()
 	// If the user does not specify the file to download, all files will be downloaded by default
 	if f.data.Progress == nil {
@@ -132,21 +204,29 @@ func (f *Fetcher) Start() (err error) {
 		}
 	}
 	f.torrent.AllowDataDownload()
+	go f.doUpload(false)
 	return
 }
 
 func (f *Fetcher) Pause() (err error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.torrent == nil {
+		return nil
+	}
 	f.torrent.DisallowDataDownload()
 	return
 }
 
 func (f *Fetcher) Close() (err error) {
-	f.safeDrop()
-	f.torrentDropFunc()
-	f.uploadDoneCh <- nil
-	if len(client.Torrents()) == 0 {
-		err = closeClient()
-	}
+	f.closeOnce.Do(func() {
+		f.torrentDropFunc()
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		f.safeDrop()
+		f.torrentReady.Store(false)
+		close(f.uploadDoneCh)
+	})
 	return nil
 }
 
@@ -164,6 +244,8 @@ func (f *Fetcher) Meta() *fetcher.FetcherMeta {
 }
 
 func (f *Fetcher) Stats() *fetcher.Stats {
+	f.mu.Lock()
+	defer f.mu.Unlock()
 	var stats torrent.TorrentStats
 	var pieceMap *base.PieceMap
 	pieceMapReady := false
@@ -370,53 +452,138 @@ func normalizeBTTransport(network string) string {
 }
 
 func (f *Fetcher) Progress() fetcher.Progress {
+	f.mu.Lock()
+	defer f.mu.Unlock()
 	if !f.torrentReady.Load() {
-		return f.data.Progress
+		return append(fetcher.Progress(nil), f.data.Progress...)
 	}
 	for i := range f.data.Progress {
 		selectIndex := f.meta.Opts.SelectFiles[i]
 		file := f.torrent.Files()[selectIndex]
 		f.data.Progress[i] = file.BytesCompleted()
 	}
-	return f.data.Progress
+	return append(fetcher.Progress(nil), f.data.Progress...)
 }
 
-func (f *Fetcher) Wait() (err error) {
+func (f *Fetcher) Wait() error {
+	f.mu.Lock()
+	var closed <-chan struct{}
+	if f.torrent != nil {
+		closed = f.torrent.Closed()
+	}
+	f.mu.Unlock()
+	ticker := time.NewTicker(time.Second)
+	defer ticker.Stop()
 	for {
 		select {
 		case <-f.torrentDropCtx.Done():
-			return
-		case <-time.After(time.Second):
-			if f.torrentReady.Load() && len(f.meta.Opts.SelectFiles) > 0 {
-				if f.isDone() {
-					// remove unselected files
-					for i, file := range f.torrent.Files() {
-						selected := false
-						for _, selectIndex := range f.meta.Opts.SelectFiles {
-							if i == selectIndex {
-								selected = true
-								break
-							}
-						}
-						if !selected {
-							util.SafeRemove(filepath.Join(f.meta.Opts.Path, f.meta.Res.Name, file.Path()))
-						}
-					}
-					return
-				}
+			return nil
+		case <-closed:
+			return nil
+		case <-ticker.C:
+			done, err := f.finishDownload()
+			if done || err != nil {
+				return err
 			}
 		}
 	}
 }
 
+func (f *Fetcher) finishDownload() (bool, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if !f.torrentReady.Load() || f.meta.Opts == nil || len(f.meta.Opts.SelectFiles) == 0 || !f.isDoneLocked() {
+		return false, nil
+	}
+	selected := make(map[int]bool, len(f.meta.Opts.SelectFiles))
+	for _, i := range f.meta.Opts.SelectFiles {
+		selected[i] = true
+	}
+	for i, file := range f.torrent.Files() {
+		if selected[i] {
+			continue
+		}
+		root, name := torrentFileLayout(f.torrent.Info(), file.FileInfo())
+		if err := removeUnselectedFile(f.meta.Opts.Path, root, name); err != nil {
+			return false, err
+		}
+	}
+	return true, nil
+}
+
+// Match the file storage layout, including its NoName convention for rootless
+// torrents. File.Path() always prepends BestName, even when storage omits it.
+func torrentFileLayout(info *metainfo.Info, file metainfo.FileInfo) (root, name string) {
+	parts := file.BestPath()
+	if info.BestName() != metainfo.NoName {
+		if len(parts) > 0 {
+			root = info.BestName()
+		}
+		parts = append([]string{info.BestName()}, parts...)
+	}
+	// A v2 file tree can itself have a named root without an extra name wrapper.
+	if root == "" && info.HasV2() && len(info.FileTree.Dir) == 1 {
+		for dir, tree := range info.FileTree.Dir {
+			if tree.IsDir() {
+				root = dir
+			}
+		}
+	}
+	return root, filepath.Join(parts...)
+}
+
+// Preserve the actual torrent root, or the download directory for rootless
+// torrents. Only prune empty directories strictly below that boundary.
+func removeUnselectedFile(downloadDir, torrentRoot, torrentPath string) error {
+	if !filepath.IsLocal(torrentPath) || (torrentRoot != "" && !filepath.IsLocal(torrentRoot)) {
+		return fmt.Errorf("invalid torrent file path %q", torrentPath)
+	}
+	root := filepath.Join(downloadDir, torrentRoot)
+	name := filepath.Join(downloadDir, torrentPath)
+	rel, err := filepath.Rel(root, name)
+	if err != nil || rel == "." || !filepath.IsLocal(rel) {
+		return fmt.Errorf("torrent file %q is outside cleanup root %q", name, root)
+	}
+	for _, candidate := range []string{name, name + ".part"} {
+		if err := util.SafeRemove(candidate); err != nil {
+			return fmt.Errorf("remove unselected torrent file %q: %w", candidate, err)
+		}
+	}
+	for dir := filepath.Dir(name); dir != root && dir != filepath.Dir(dir); dir = filepath.Dir(dir) {
+		entries, err := os.ReadDir(dir)
+		if os.IsNotExist(err) {
+			continue
+		}
+		if err != nil {
+			return fmt.Errorf("read torrent directory %q: %w", dir, err)
+		}
+		if len(entries) != 0 {
+			break
+		}
+		if err := util.SafeRemove(dir); err != nil {
+			return fmt.Errorf("remove empty torrent directory %q: %w", dir, err)
+		}
+	}
+	return nil
+}
+
 func (f *Fetcher) isDone() bool {
-	if f.meta.Opts == nil {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.isDoneLocked()
+}
+
+func (f *Fetcher) isDoneLocked() bool {
+	if f.meta.Opts == nil || f.torrent == nil {
 		return false
 	}
-	for _, selectIndex := range f.meta.Opts.SelectFiles {
-		file := f.torrent.Files()[selectIndex]
-		if file.BytesCompleted() < file.Length() {
-			return false
+	for _, index := range f.meta.Opts.SelectFiles {
+		file := f.torrent.Files()[index]
+		for i := file.BeginPieceIndex(); i < file.EndPieceIndex(); i++ {
+			state := f.torrent.Piece(i).State()
+			if !state.Ok || !state.Complete || state.Hashing || state.QueuedForHash {
+				return false
+			}
 		}
 	}
 	return true
@@ -425,6 +592,11 @@ func (f *Fetcher) isDone() bool {
 // Patch modifies the BT task settings.
 // Invalid file indices are silently ignored.
 func (f *Fetcher) Patch(req *base.Request, opts *base.Options) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.meta.Opts == nil {
+		f.meta.Opts = &base.Options{}
+	}
 	if opts == nil {
 		return nil
 	}
@@ -481,9 +653,9 @@ func (f *Fetcher) updateRes() {
 		Files: make([]*base.FileInfo, len(f.torrent.Files())),
 		Hash:  f.torrent.InfoHash().String(),
 	}
-	// Directory torrent
-	if f.torrent.Info().Length == 0 {
-		res.Name = f.torrent.Name()
+	// Use the same root classification as storage (v2 single files have Length == 0).
+	if files := f.torrent.Files(); len(files) > 0 {
+		res.Name, _ = torrentFileLayout(f.torrent.Info(), files[0].FileInfo())
 	}
 	for i, file := range f.torrent.Files() {
 		res.Files[i] = &base.FileInfo{
@@ -500,61 +672,50 @@ func (f *Fetcher) updateRes() {
 }
 
 func (f *Fetcher) Upload() (err error) {
-	return f.addTorrent(f.meta.Req, true)
+	if err = f.Start(); err != nil {
+		return err
+	}
+	return nil
 }
 
 func (f *Fetcher) doUpload(fromUpload bool) {
 	if !f.torrentUpload.CompareAndSwap(false, true) {
 		return
 	}
-
-	// Check and update seed data
-	lastData := &fetcherData{
-		SeedBytes: f.data.SeedBytes,
-		SeedTime:  f.data.SeedTime,
-	}
-	var doneTime int64 = 0
+	f.mu.Lock()
+	initialBytes, initialTime := f.data.SeedBytes, f.data.SeedTime
+	torrentClosed := f.torrent.Closed()
+	f.mu.Unlock()
+	var doneTime int64
+	ticker := time.NewTicker(time.Second)
+	defer ticker.Stop()
 	for {
 		select {
 		case <-f.torrentDropCtx.Done():
 			return
-		case <-time.After(time.Second):
+		case <-torrentClosed:
+			return
+		case <-ticker.C:
+			f.mu.Lock()
 			if !f.torrentReady.Load() {
+				f.mu.Unlock()
 				continue
 			}
-
 			stats := f.torrentStats()
-			f.data.SeedBytes = lastData.SeedBytes + stats.BytesWrittenData.Int64()
-
-			// Check is download complete, if not don't check and stop seeding
-			if !fromUpload && !f.isDone() {
+			f.data.SeedBytes = initialBytes + stats.BytesWrittenData.Int64()
+			if !fromUpload && !f.isDoneLocked() {
+				f.mu.Unlock()
 				continue
 			}
 			if doneTime == 0 {
 				doneTime = time.Now().Unix()
 			}
-			f.data.SeedTime = lastData.SeedTime + time.Now().Unix() - doneTime
-
-			// If the seed forever is true, keep seeding
-			if f.config.SeedKeep {
-				continue
-			}
-
-			// If the seed ratio is reached, stop seeding
-			if f.config.SeedRatio > 0 {
-				seedRadio := f.seedRadio()
-				if seedRadio >= f.config.SeedRatio {
-					f.Close()
-					break
-				}
-			}
-
-			// If the seed time is reached, stop seeding
-			if f.config.SeedTime > 0 {
-				if f.data.SeedTime >= f.config.SeedTime {
-					f.Close()
-					break
-				}
+			f.data.SeedTime = initialTime + time.Now().Unix() - doneTime
+			stop := !f.config.SeedKeep && ((f.config.SeedRatio > 0 && f.seedRadio() >= f.config.SeedRatio) || (f.config.SeedTime > 0 && f.data.SeedTime >= f.config.SeedTime))
+			f.mu.Unlock()
+			if stop {
+				f.Close()
+				return
 			}
 		}
 	}
@@ -572,6 +733,8 @@ func (f *Fetcher) torrentStats() torrent.TorrentStats {
 }
 
 func (f *Fetcher) UploadedBytes() int64 {
+	f.mu.Lock()
+	defer f.mu.Unlock()
 	return f.data.SeedBytes
 }
 
@@ -580,7 +743,8 @@ func (f *Fetcher) WaitUpload() (err error) {
 	return nil
 }
 
-func (f *Fetcher) addTorrent(req *base.Request, fromUpload bool) (err error) {
+func (f *Fetcher) addTorrent(req *base.Request) (err error) {
+	f.ctl.GetConfig(&f.config)
 	if err = base.ParseReqExtra[bt.ReqExtra](req); err != nil {
 		return
 	}
@@ -599,11 +763,16 @@ func (f *Fetcher) addTorrent(req *base.Request, fromUpload bool) (err error) {
 		var reader io.Reader
 		if schema == "FILE" {
 			fileUrl, _ := url.Parse(req.URL)
-			filePath := fileUrl.Path[1:]
+			filePath := fileUrl.Path
+			if runtime.GOOS == "windows" && len(filePath) > 2 && filePath[0] == '/' && filePath[2] == ':' {
+				filePath = filePath[1:]
+			}
+			filePath = filepath.FromSlash(filePath)
 			reader, err = os.Open(filePath)
 			if err != nil {
 				return
 			}
+			defer reader.(io.Closer).Close()
 		} else if schema == "DATA" {
 			_, data := util.ParseDataUri(req.URL)
 			reader = bytes.NewBuffer(data)
@@ -636,17 +805,6 @@ func (f *Fetcher) addTorrent(req *base.Request, fromUpload bool) (err error) {
 			return
 		}
 	}
-	spec.Storage = storage.NewFileOpts(storage.NewFileClientOpts{
-		ClientBaseDir: cfg.DataDir,
-		TorrentDirMaker: func(baseDir string, info *metainfo.Info, infoHash metainfo.Hash) string {
-			return f.meta.Opts.Path
-		},
-	})
-	f.torrent, _, err = client.AddTorrentSpec(spec)
-	if err != nil {
-		return
-	}
-
 	// Do not add external tracker to a private torrent.
 	if !privateTorrent {
 		// use map to deduplicate
@@ -659,23 +817,40 @@ func (f *Fetcher) addTorrent(req *base.Request, fromUpload bool) (err error) {
 				}
 			}
 		}
-		if len(f.config.Trackers) > 0 {
-			for _, tracker := range f.config.Trackers {
-				trackers[tracker] = true
-			}
+		for _, tracker := range f.config.effectiveTrackers() {
+			trackers[tracker] = true
 		}
 		if len(trackers) > 0 {
-			announceList := make([][]string, 0)
 			for tracker := range trackers {
-				announceList = append(announceList, []string{tracker})
+				spec.Trackers = append(spec.Trackers, []string{tracker})
 			}
-			f.torrent.AddTrackers(announceList)
 		}
 	}
-	<-f.torrent.GotInfo()
+	s := &deferredFileStorage{}
+	spec.Storage = s
+	var added bool
+	f.torrent, added, err = client.AddTorrentSpec(spec)
+	if err != nil {
+		return err
+	}
+	if !added {
+		f.torrent = nil
+		return errors.New("torrent is already active")
+	}
+	f.storage = s
+	f.torrent.DisallowDataDownload()
+	// Extra trackers must be available while magnet metadata is still missing;
+	// they may be the only way to discover a peer that can provide it.
+	select {
+	case <-f.torrent.GotInfo():
+	case <-f.torrentDropCtx.Done():
+		f.safeDrop()
+		return f.torrentDropCtx.Err()
+	case <-f.torrent.Closed():
+		return errors.New("torrent closed during resolution")
+	}
 	f.torrentReady.Store(true)
 
-	go f.doUpload(fromUpload)
 	return
 }
 
@@ -771,17 +946,29 @@ func (fm *FetcherManager) AutoRename() bool {
 
 func (fm *FetcherManager) DefaultConfig() any {
 	return &config{
+		TrackerSubscribeURLs: append([]string{}, defaultTrackerSubscribeURLs...),
+		AutoUpdateTrackers:   true,
+		CustomTrackers:       []string{},
+		ConfigState: fetcher.ConfigState[state]{State: state{
+			TrackerSources:              map[string][]string{},
+			TrackerSubscriptionStatuses: map[string]trackerSubscriptionStatus{},
+		}},
 		ListenPort: 0,
-		Trackers:   []string{},
 		SeedKeep:   false,
 		SeedRatio:  1.0,
 		SeedTime:   120 * 60,
+		DisableDHT: false,
+		DisablePEX: false,
 	}
 }
 
 func (fm *FetcherManager) Store(f fetcher.Fetcher) (data any, err error) {
 	_f := f.(*Fetcher)
-	return _f.data, nil
+	_f.mu.Lock()
+	defer _f.mu.Unlock()
+	snapshot := *_f.data
+	snapshot.Progress = append(fetcher.Progress(nil), snapshot.Progress...)
+	return &snapshot, nil
 }
 
 func (fm *FetcherManager) Restore() (v any, f func(meta *fetcher.FetcherMeta, v any) fetcher.Fetcher) {

internal/protocol/bt/fetcher_test.go

@@ -18,11 +18,11 @@ import (
 )
 
 func TestFetcher_Resolve_Torrent(t *testing.T) {
-	doResolve(t, buildFetcher())
+	doResolve(t, buildFetcher(t))
 }
 
 func TestFetcher_Resolve_DataUri_Torrent(t *testing.T) {
-	fetcher := buildFetcher()
+	fetcher := buildFetcher(t)
 	buf, err := os.ReadFile("./testdata/ubuntu-22.04-live-server-amd64.iso.torrent")
 	if err != nil {
 		t.Fatal(err)
@@ -31,7 +31,7 @@ func TestFetcher_Resolve_DataUri_Torrent(t *testing.T) {
 	dataUri := "data:application/x-bittorrent;base64," + base64.StdEncoding.EncodeToString(buf)
 	err = fetcher.Resolve(&base.Request{
 		URL: dataUri,
-	}, nil)
+	})
 	if err != nil {
 		panic(err)
 	}
@@ -53,7 +53,7 @@ func TestFetcher_Resolve_DataUri_Torrent(t *testing.T) {
 }
 
 func TestFetcher_Config(t *testing.T) {
-	doResolve(t, buildConfigFetcher(nil))
+	doResolve(t, buildConfigFetcher(t, nil))
 }
 
 func TestFetcher_ResolveWithProxy(t *testing.T) {
@@ -61,7 +61,7 @@ func TestFetcher_ResolveWithProxy(t *testing.T) {
 	proxyListener := test.StartSocks5Server(usr, pwd)
 	defer proxyListener.Close()
 
-	doResolve(t, buildConfigFetcher(&base.DownloaderProxyConfig{
+	doResolve(t, buildConfigFetcher(t, &base.DownloaderProxyConfig{
 		Enable: true,
 		System: false,
 		Scheme: "socks5",
@@ -81,7 +81,7 @@ func doResolve(t *testing.T, fetcher fetcher.Fetcher) {
 					"udp://tracker.bitsearch.to:1337/announce",
 				},
 			},
-		}, nil)
+		})
 		if err != nil {
 			panic(err)
 		}
@@ -111,7 +111,7 @@ func doResolve(t *testing.T, fetcher fetcher.Fetcher) {
 					"udp://tracker.bitsearch.to:1337/announce",
 				},
 			},
-		}, nil)
+		})
 		if err != nil {
 			panic(err)
 		}
@@ -145,7 +145,7 @@ func doResolve(t *testing.T, fetcher fetcher.Fetcher) {
 	t.Run("Resolve Unclean Torrent", func(t *testing.T) {
 		err := fetcher.Resolve(&base.Request{
 			URL: "./testdata/test.unclean.torrent",
-		}, nil)
+		})
 		if err != nil {
 			t.Errorf("Resolve Unclean Torrent Resolve() got = %v, want nil", err)
 		}
@@ -156,7 +156,7 @@ func doResolve(t *testing.T, fetcher fetcher.Fetcher) {
 		uri := "file:///" + file
 		err := fetcher.Resolve(&base.Request{
 			URL: uri,
-		}, nil)
+		})
 		if err != nil {
 			t.Errorf("Resolve file scheme Torrent Resolve() got = %v, want nil", err)
 		}
@@ -211,7 +211,7 @@ func TestFetcherManager_ParseName(t *testing.T) {
 	}
 }
 
-func buildFetcher() fetcher.Fetcher {
+func buildFetcher(t testing.TB) fetcher.Fetcher {
 	fb := new(FetcherManager)
 	fetcher := fb.Build()
 	newController := controller.NewController()
@@ -219,14 +219,15 @@ func buildFetcher() fetcher.Fetcher {
 		json.Unmarshal([]byte(test.ToJson(fb.DefaultConfig())), v)
 	}
 	fetcher.Setup(newController)
+	t.Cleanup(func() { fetcher.Close(); closeClient() })
 	return fetcher
 }
 
-func buildConfigFetcher(proxyConfig *base.DownloaderProxyConfig) fetcher.Fetcher {
+func buildConfigFetcher(t testing.TB, proxyConfig *base.DownloaderProxyConfig) fetcher.Fetcher {
 	fetcher := new(FetcherManager).Build()
 	newController := controller.NewController()
 	mockCfg := config{
-		Trackers: []string{
+		CustomTrackers: []string{
 			"udp://tracker.birkenwald.de:6969/announce",
 			"udp://tracker.bitsearch.to:1337/announce",
 		}}
@@ -237,29 +238,30 @@ func buildConfigFetcher(proxyConfig *base.DownloaderProxyConfig) fetcher.Fetcher
 		return proxyConfig.ToHandler()
 	}
 	fetcher.Setup(newController)
+	t.Cleanup(func() { fetcher.Close(); closeClient() })
 	return fetcher
 }
 
 // TestFetcher_Patch tests the Patch functionality for BT fetcher.
 // It tests modifying selected files after Resolve (without downloading).
 func TestFetcher_Patch(t *testing.T) {
-	f := buildFetcher()
+	f := buildFetcher(t)
 
 	// Resolve a multi-file torrent
 	err := f.Resolve(&base.Request{
 		URL: "./testdata/test.torrent",
-	}, nil)
+	})
 	if err != nil {
 		t.Fatalf("Resolve failed: %v", err)
 	}
 
-	// Verify initial state: 3 files, all selected by default
+	// Resolution describes files without choosing download options.
 	meta := f.Meta()
 	if len(meta.Res.Files) != 3 {
 		t.Fatalf("Expected 3 files, got %d", len(meta.Res.Files))
 	}
-	if len(meta.Opts.SelectFiles) != 3 {
-		t.Fatalf("Expected 3 selected files, got %d", len(meta.Opts.SelectFiles))
+	if meta.Opts != nil {
+		t.Fatal("Resolve should not assign download options")
 	}
 
 	// Total size of all files: 107484864
@@ -366,3 +368,52 @@ func TestFetcher_Patch(t *testing.T) {
 		}
 	})
 }
+
+func TestFetcher_PeerDiscoveryConfig(t *testing.T) {
+	tests := []struct {
+		name           string
+		stored         any
+		wantDisableDHT bool
+		wantDisablePEX bool
+	}{
+		{"default config", new(FetcherManager).DefaultConfig(), false, false},
+		{"stored config without the fields", map[string]any{"listenPort": 0, "seedRatio": 1.0}, false, false},
+		{"both disabled", map[string]any{"disableDht": true, "disablePex": true}, true, true},
+		{"only DHT disabled", map[string]any{"disableDht": true}, true, false},
+		{"only PEX disabled", map[string]any{"disablePex": true}, false, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f := buildFetcherWithConfig(tt.stored).(*Fetcher)
+			if f.config.DisableDHT != tt.wantDisableDHT || f.config.DisablePEX != tt.wantDisablePEX {
+				t.Errorf("config got DisableDHT = %v, DisablePEX = %v, want %v, %v", f.config.DisableDHT, f.config.DisablePEX, tt.wantDisableDHT, tt.wantDisablePEX)
+			}
+		})
+	}
+}
+
+func TestFetcher_PeerDiscoveryDisabledOnClient(t *testing.T) {
+	if err := closeClient(); err != nil {
+		t.Fatal(err)
+	}
+	f := buildFetcherWithConfig(map[string]any{"disableDht": true, "disablePex": true})
+	if err := f.Resolve(&base.Request{URL: "./testdata/test.torrent"}); err != nil {
+		t.Fatal(err)
+	}
+	if !cfg.NoDHT || !cfg.DisablePEX {
+		t.Errorf("client config got NoDHT = %v, DisablePEX = %v, want true", cfg.NoDHT, cfg.DisablePEX)
+	}
+	if n := len(client.DhtServers()); n != 0 {
+		t.Errorf("client got %d DHT servers, want 0", n)
+	}
+}
+
+func buildFetcherWithConfig(stored any) fetcher.Fetcher {
+	fetcher := new(FetcherManager).Build()
+	newController := controller.NewController()
+	newController.GetConfig = func(v any) {
+		json.Unmarshal([]byte(test.ToJson(stored)), v)
+	}
+	fetcher.Setup(newController)
+	return fetcher
+}

internal/protocol/bt/fixture_test.go

@@ -0,0 +1,212 @@
+package bt
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/binary"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/anacrolix/torrent"
+	"github.com/anacrolix/torrent/bencode"
+	"github.com/anacrolix/torrent/merkle"
+	"github.com/anacrolix/torrent/metainfo"
+	"golang.org/x/time/rate"
+)
+
+// btFixture serves generated, trackerless content over a real loopback TCP peer.
+// Its HTTP tracker exercises .torrent downloads; magnet links also carry the
+// explicit x.pe address.
+type btFixture struct {
+	MetaInfo    *metainfo.MetaInfo
+	Magnet      string
+	TorrentFile string
+	DataURI     string
+	TrackerURL  string
+	Files       map[string][]byte // Paths relative to the selected download directory.
+	Seeder      *torrent.Client
+	Torrent     *torrent.Torrent
+	Limiter     *rate.Limiter
+}
+
+func newBTFixture(t testing.TB, files map[string][]byte, bytesPerSecond int) *btFixture {
+	return makeBTFixture(t, files, bytesPerSecond, false, true)
+}
+
+func newBTHybridFixture(t testing.TB, payload []byte) *btFixture {
+	return makeBTFixture(t, map[string][]byte{"": payload}, 0, true, true)
+}
+
+func makeBTFixture(t testing.TB, files map[string][]byte, bytesPerSecond int, v2, private bool) *btFixture {
+	t.Helper()
+	source := t.TempDir()
+	name := "payload.bin"
+	if _, single := files[""]; !single {
+		name = "bundle"
+	}
+	root := filepath.Join(source, name)
+	expected := make(map[string][]byte, len(files))
+	for path, data := range files {
+		target := filepath.Join(root, filepath.FromSlash(path))
+		if err := os.MkdirAll(filepath.Dir(target), 0700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(target, data, 0600); err != nil {
+			t.Fatal(err)
+		}
+		expected[filepath.Join(name, filepath.FromSlash(path))] = append([]byte(nil), data...)
+	}
+	info := metainfo.Info{PieceLength: 16 * 1024}
+	if err := info.BuildFromFilePath(root); err != nil {
+		t.Fatal(err)
+	}
+	var layers map[string]string
+	if v2 {
+		data := files[""]
+		h := merkle.NewHash()
+		h.Write(data)
+		root := h.Sum(nil)
+		var pieceHashes []byte
+		for off := 0; off < len(data); off += int(info.PieceLength) {
+			end := min(off+int(info.PieceLength), len(data))
+			ph := merkle.NewHash()
+			ph.Write(data[off:end])
+			pieceHashes = append(pieceHashes, ph.SumMinLength(nil, int(info.PieceLength))...)
+		}
+		info = metainfo.Info{Name: name, PieceLength: info.PieceLength, Length: int64(len(data)), Pieces: info.Pieces, MetaVersion: 2, FileTree: metainfo.FileTree{File: metainfo.FileTreeFile{Length: int64(len(data)), PiecesRoot: string(root)}}}
+		layers = map[string]string{string(root): string(pieceHashes)}
+	}
+	// Private torrents avoid public DHT discovery once metadata is available.
+	info.Private = &private
+	raw, err := bencode.Marshal(&info)
+	if err != nil {
+		t.Fatal(err)
+	}
+	mi := &metainfo.MetaInfo{InfoBytes: raw, PieceLayers: layers}
+	cfg := torrent.TestingConfig(t)
+	cfg.DataDir = source
+	cfg.Seed = true
+	cfg.DisableUTP = true
+	cfg.DisableIPv6 = true
+	cfg.DisableWebtorrent = true
+	cfg.KeepAliveTimeout = time.Minute
+	cfg.MaxAllocPeerRequestDataPerConn = 1 << 20
+	limiter := rate.NewLimiter(rate.Inf, 16*1024)
+	if bytesPerSecond > 0 {
+		limiter.SetLimit(rate.Limit(bytesPerSecond))
+	}
+	cfg.UploadRateLimiter = limiter
+	seed, err := torrent.NewClient(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { seed.Close() })
+	seeded, _, err := seed.AddTorrentSpec(torrent.TorrentSpecFromMetaInfo(mi))
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if err := seeded.VerifyDataContext(ctx); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case <-seeded.Complete().On():
+	case <-ctx.Done():
+		t.Fatal("local seeder did not finish verification")
+	}
+	addr := seed.ListenAddrs()[0].String()
+	host, portString, err := net.SplitHostPort(addr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolved, err := net.ResolveTCPAddr("tcp4", net.JoinHostPort(host, portString))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compact := make([]byte, 6)
+	copy(compact, resolved.IP.To4())
+	binary.BigEndian.PutUint16(compact[4:], uint16(resolved.Port))
+	tracker := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		response, err := bencode.Marshal(map[string]any{"interval": 3600, "peers": string(compact)})
+		if err != nil {
+			http.Error(w, err.Error(), 500)
+			return
+		}
+		w.Write(response)
+	}))
+	t.Cleanup(tracker.Close)
+	// The pinned library has a hybrid tracker-dispatch assertion bug.
+	// Hybrid fixtures use their explicit loopback peer rather than a tracker.
+	if !v2 {
+		mi.Announce = tracker.URL
+	}
+	var encoded bytes.Buffer
+	if err := mi.Write(&encoded); err != nil {
+		t.Fatal(err)
+	}
+	torrentFile := filepath.Join(t.TempDir(), "fixture.torrent")
+	if err := os.WriteFile(torrentFile, encoded.Bytes(), 0600); err != nil {
+		t.Fatal(err)
+	}
+	m, err := mi.MagnetV2()
+	if err != nil {
+		t.Fatal(err)
+	}
+	magnet := m.String()
+	u, err := url.Parse(magnet)
+	if err != nil {
+		t.Fatal(err)
+	}
+	q := u.Query()
+	q.Add("x.pe", addr)
+	u.RawQuery = q.Encode()
+	return &btFixture{MetaInfo: mi, Magnet: u.String(), TorrentFile: torrentFile, DataURI: "data:application/x-bittorrent;base64," + base64.StdEncoding.EncodeToString(encoded.Bytes()), TrackerURL: tracker.URL, Files: expected, Seeder: seed, Torrent: seeded, Limiter: limiter}
+}
+
+func btPayload(size int, label string) []byte {
+	data := make([]byte, size)
+	for i := range data {
+		data[i] = byte((i*31 + i/251) % 251)
+	}
+	copy(data, label)
+	return data
+}
+
+func (f *btFixture) AssertFiles(t testing.TB, dir string, paths ...string) {
+	t.Helper()
+	if len(paths) == 0 {
+		for path := range f.Files {
+			paths = append(paths, path)
+		}
+	}
+	for _, path := range paths {
+		got, err := os.ReadFile(filepath.Join(dir, path))
+		if err != nil {
+			t.Fatal(err)
+		}
+		want, ok := f.Files[path]
+		if !ok {
+			t.Fatalf("unknown fixture file %q", path)
+		}
+		if !bytes.Equal(got, want) {
+			t.Fatalf("BT file %s differs: received %d bytes, want %d", path, len(got), len(want))
+		}
+	}
+}
+
+func (f *btFixture) FileURI() string {
+	path := filepath.ToSlash(f.TorrentFile)
+	if !strings.HasPrefix(path, "/") {
+		path = "/" + path
+	}
+	return (&url.URL{Scheme: "file", Path: path}).String()
+}

internal/protocol/bt/selection_test.go

@@ -0,0 +1,367 @@
+package bt
+
+import (
+	"context"
+	"crypto/sha1"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+	"github.com/GopeedLab/gopeed/pkg/base"
+	"github.com/anacrolix/torrent"
+	"github.com/anacrolix/torrent/bencode"
+	"github.com/anacrolix/torrent/metainfo"
+	"github.com/anacrolix/torrent/storage"
+)
+
+func TestStartDoesNotPublishUnverifiedCompletion(t *testing.T) {
+	cfg := torrent.TestingConfig(t)
+	cfg.DisableTCP = true
+	cfg.DisableUTP = true
+	c, err := torrent.NewClient(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close()
+	payload := btPayload(32*1024, "unverified")
+	info := metainfo.Info{Name: "payload.bin", Length: int64(len(payload)), PieceLength: 16 * 1024}
+	for offset := 0; offset < len(payload); offset += int(info.PieceLength) {
+		hash := sha1.Sum(payload[offset : offset+int(info.PieceLength)])
+		info.Pieces = append(info.Pieces, hash[:]...)
+	}
+	raw, err := bencode.Marshal(info)
+	if err != nil {
+		t.Fatal(err)
+	}
+	store := &deferredFileStorage{}
+	spec := torrent.TorrentSpecFromMetaInfo(&metainfo.MetaInfo{InfoBytes: raw})
+	spec.Storage = store
+	tor, _, err := c.AddTorrentSpec(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tor.DisallowDataDownload()
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	f := &Fetcher{torrent: tor, storage: store, meta: &fetcher.FetcherMeta{}, data: &fetcherData{}, torrentDropCtx: ctx, torrentDropFunc: cancel, config: &config{SeedKeep: true}}
+	f.torrentReady.Store(true)
+	f.updateRes()
+	dir := t.TempDir()
+	payload[20000] ^= 0xff
+	if err := os.WriteFile(filepath.Join(dir, info.Name), payload, 0600); err != nil {
+		t.Fatal(err)
+	}
+	f.meta.Opts = &base.Options{Path: dir}
+	// Retain the original event channel to detect even a transient completion.
+	// With no network transports, the damaged piece cannot have been repaired.
+	completed := tor.Complete().On()
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case <-completed:
+		t.Fatal("Start published completion before verifying the existing file")
+	default:
+	}
+}
+
+func TestStartUsesSelectionSubmittedAfterResolve(t *testing.T) {
+	cfg := torrent.TestingConfig(t)
+	cfg.DataDir = t.TempDir()
+	cfg.DisableTCP = true
+	cfg.DisableUTP = true
+	c, err := torrent.NewClient(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close()
+	store := &deferredFileStorage{}
+	mi, err := metainfo.LoadFromFile("testdata/test.torrent")
+	if err != nil {
+		t.Fatal(err)
+	}
+	spec := torrent.TorrentSpecFromMetaInfo(mi)
+	spec.Storage = store
+	tor, _, err := c.AddTorrentSpec(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tor.DisallowDataDownload()
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	f := &Fetcher{torrent: tor, storage: store, meta: &fetcher.FetcherMeta{}, data: &fetcherData{}, torrentDropCtx: ctx, torrentDropFunc: cancel, config: &config{SeedKeep: true}}
+	f.torrentReady.Store(true)
+	f.updateRes()
+	f.meta.Opts = &base.Options{Path: t.TempDir(), SelectFiles: []int{2}}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	for i, file := range tor.Files() {
+		want := torrent.PiecePriorityNone
+		if i == 2 {
+			want = torrent.PiecePriorityNormal
+		}
+		if file.Priority() != want {
+			t.Errorf("file %d priority = %v, want %v", i, file.Priority(), want)
+		}
+	}
+	if len(f.data.Progress) != 1 {
+		t.Fatalf("progress tracks %d files, want 1", len(f.data.Progress))
+	}
+	if err := f.Pause(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if tor.Files()[0].Priority() != torrent.PiecePriorityNone {
+		t.Fatal("resume selected an unselected file")
+	}
+}
+
+func TestWaitCleansUnselectedFilesFromSharedPiece(t *testing.T) {
+	for _, mode := range []string{"partial", "part only", "both paths", "all", "already removed", "remove error"} {
+		t.Run(mode, func(t *testing.T) {
+			dir := t.TempDir()
+			keepPath := filepath.Join(dir, "bundle", "keep.txt")
+			skipPath := filepath.Join(dir, "bundle", "nested", "skip.txt")
+			if err := os.MkdirAll(filepath.Dir(skipPath), 0755); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(keepPath, []byte("keep"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(skipPath, []byte("skip"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			// Both files occupy the same piece, so downloading keep.txt also writes skip.txt.
+			hash := sha1.Sum([]byte("keepskip"))
+			info := metainfo.Info{Name: "bundle", PieceLength: 16, Pieces: hash[:], Files: []metainfo.FileInfo{
+				{Length: 4, Path: []string{"keep.txt"}},
+				{Length: 4, Path: []string{"nested", "skip.txt"}},
+			}}
+			storageOpts := storage.NewFileClientOpts{
+				ClientBaseDir:   dir,
+				TorrentDirMaker: func(baseDir string, _ *metainfo.Info, _ metainfo.Hash) string { return baseDir },
+			}
+			// VerifyDataContext can return before storage finishes marking the piece
+			// complete. Disable automatic part-file promotion so it cannot rename
+			// the .part fixtures that this test creates to exercise cleanup.
+			storageOpts.UsePartFiles.Set(false)
+			store := storage.NewFileOpts(storageOpts)
+			defer store.Close()
+			config := torrent.TestingConfig(t)
+			config.DisableTCP = true
+			config.DisableUTP = true
+			c, err := torrent.NewClient(config)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer c.Close()
+			spec, err := torrent.TorrentSpecFromMetaInfoErr(&metainfo.MetaInfo{InfoBytes: bencode.MustMarshal(&info)})
+			if err != nil {
+				t.Fatal(err)
+			}
+			spec.Storage = store
+			tor, _, err := c.AddTorrentSpec(spec)
+			if err != nil {
+				t.Fatal(err)
+			}
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			if err := tor.VerifyDataContext(ctx); err != nil {
+				t.Fatal(err)
+			}
+			f := &Fetcher{torrent: tor, meta: &fetcher.FetcherMeta{Opts: &base.Options{Path: dir, SelectFiles: []int{0}}}, data: &fetcherData{}, torrentDropCtx: ctx}
+			f.torrentReady.Store(true)
+			f.updateRes()
+			if mode == "all" {
+				f.meta.Opts.SelectFiles = []int{0, 1}
+			}
+			if !f.isDone() {
+				t.Fatal("selected file is not complete")
+			}
+			if mode == "part only" || mode == "both paths" || mode == "all" {
+				if err := os.WriteFile(skipPath+".part", []byte("skip"), 0644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if mode == "part only" || mode == "already removed" || mode == "remove error" {
+				if err := os.Remove(skipPath); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if mode == "remove error" {
+				if err := os.Mkdir(skipPath, 0755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(filepath.Join(skipPath, "child"), []byte("preserve"), 0644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			err = f.Wait()
+			if ctx.Err() != nil {
+				t.Fatal(ctx.Err())
+			}
+			if mode == "remove error" {
+				if err == nil {
+					t.Fatal("cleanup failure was silently ignored")
+				}
+			} else if err != nil {
+				t.Fatal(err)
+			}
+			data, err := os.ReadFile(keepPath)
+			if err != nil || string(data) != "keep" {
+				t.Fatalf("selected file changed: %q, %v", data, err)
+			}
+			if mode == "all" {
+				if _, err := os.Stat(skipPath + ".part"); err != nil {
+					t.Fatalf("selected part file was removed: %v", err)
+				}
+				data, err := os.ReadFile(skipPath)
+				if err != nil || string(data) != "skip" {
+					t.Fatalf("selected file changed: %q, %v", data, err)
+				}
+			} else if mode != "remove error" {
+				for _, removed := range []string{skipPath, skipPath + ".part", filepath.Dir(skipPath)} {
+					if _, err := os.Stat(removed); !os.IsNotExist(err) {
+						t.Fatalf("unselected file or empty directory remains: %s: %v", removed, err)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestRemoveUnselectedFilePrunesOnlyEmptyParents(t *testing.T) {
+	for _, preserveSibling := range []bool{false, true} {
+		t.Run(fmt.Sprint(preserveSibling), func(t *testing.T) {
+			root := t.TempDir()
+			relative := filepath.Join("bundle", "nested", "deep", "skip.txt")
+			name := filepath.Join(root, relative)
+			if err := os.MkdirAll(filepath.Dir(name), 0755); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(name+".part", []byte("partial"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			sibling := filepath.Join(root, "bundle", "keep.txt")
+			if preserveSibling {
+				if err := os.WriteFile(sibling, []byte("keep"), 0644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if err := removeUnselectedFile(root, "bundle", relative); err != nil {
+				t.Fatal(err)
+			}
+			if _, err := os.Stat(filepath.Join(root, "bundle", "nested")); !os.IsNotExist(err) {
+				t.Fatalf("empty ancestors remain: %v", err)
+			}
+			if preserveSibling {
+				data, err := os.ReadFile(sibling)
+				if err != nil || string(data) != "keep" {
+					t.Fatalf("sibling changed: %q, %v", data, err)
+				}
+			}
+			if info, err := os.Stat(filepath.Join(root, "bundle")); err != nil || !info.IsDir() {
+				t.Fatalf("torrent root directory was removed: %v", err)
+			}
+			if _, err := os.Stat(root); err != nil {
+				t.Fatalf("download directory was removed: %v", err)
+			}
+			// A file directly inside the torrent root must not cause that root to be pruned.
+			rootFile := filepath.Join("bundle", "root.txt")
+			if err := os.WriteFile(filepath.Join(root, rootFile)+".part", []byte("partial"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			if err := removeUnselectedFile(root, "bundle", rootFile); err != nil {
+				t.Fatal(err)
+			}
+			if _, err := os.Stat(filepath.Join(root, "bundle")); err != nil {
+				t.Fatalf("torrent root directory was removed after root-level cleanup: %v", err)
+			}
+			// Repeating cleanup after the file and its subdirectories are gone is harmless.
+			if err := removeUnselectedFile(root, "bundle", relative); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+}
+
+func TestCleanupMatchesNamedAndRootlessStorage(t *testing.T) {
+	for _, version := range []int64{1, 2} {
+		for _, layout := range []string{"rootless", "wrapped", "file-tree-root"} {
+			if version == 1 && layout == "file-tree-root" {
+				continue
+			}
+			t.Run(fmt.Sprintf("v%d/%s", version, layout), func(t *testing.T) {
+				dir := t.TempDir()
+				info := metainfo.Info{Name: metainfo.NoName, PieceLength: 16384}
+				root := dir
+				if layout == "wrapped" {
+					info.Name = "bundle"
+					root = filepath.Join(dir, "bundle")
+				}
+				if version == 1 {
+					info.Files = []metainfo.FileInfo{{Path: []string{"keep.txt"}}, {Path: []string{"nested", "deep", "skip.txt"}}}
+				} else {
+					info.MetaVersion = 2
+					info.FileTree = metainfo.FileTree{Dir: map[string]metainfo.FileTree{
+						"keep.txt": {},
+						"nested":   {Dir: map[string]metainfo.FileTree{"deep": {Dir: map[string]metainfo.FileTree{"skip.txt": {}}}}},
+					}}
+				}
+				if layout == "file-tree-root" {
+					info.FileTree = metainfo.FileTree{Dir: map[string]metainfo.FileTree{"tree-root": info.FileTree}}
+					root = filepath.Join(dir, "tree-root")
+				}
+				// Keep the library's default FilePathMaker here to independently verify
+				// that cleanup agrees with its real disk layout, including NoName.
+				store := storage.NewFileOpts(storage.NewFileClientOpts{
+					ClientBaseDir:   dir,
+					TorrentDirMaker: func(baseDir string, _ *metainfo.Info, _ metainfo.Hash) string { return baseDir },
+				})
+				defer store.Close()
+				torrentStorage, err := store.OpenTorrent(context.Background(), &info, metainfo.Hash{1})
+				if err != nil {
+					t.Fatal(err)
+				}
+				defer torrentStorage.Close()
+				skip := filepath.Join(root, "nested", "deep", "skip.txt")
+				if _, err := os.Stat(skip); err != nil {
+					t.Fatalf("unexpected storage layout: %v", err)
+				}
+				if err := os.WriteFile(skip+".part", []byte("partial"), 0644); err != nil {
+					t.Fatal(err)
+				}
+				files := info.UpvertedFiles()
+				boundary, name := torrentFileLayout(&info, files[1])
+				if err := removeUnselectedFile(dir, boundary, name); err != nil {
+					t.Fatal(err)
+				}
+				if _, err := os.Stat(filepath.Join(root, "nested")); !os.IsNotExist(err) {
+					t.Fatalf("empty subtree remains: %v", err)
+				}
+				if _, err := os.Stat(filepath.Join(root, "keep.txt")); err != nil {
+					t.Fatalf("selected file removed: %v", err)
+				}
+				// Also verify the boundary when the protected directory becomes empty.
+				if err := os.Remove(filepath.Join(root, "keep.txt")); err != nil {
+					t.Fatal(err)
+				}
+				for _, file := range files {
+					boundary, name := torrentFileLayout(&info, file)
+					if err := removeUnselectedFile(dir, boundary, name); err != nil {
+						t.Fatal(err)
+					}
+				}
+				if stat, err := os.Stat(root); err != nil || !stat.IsDir() {
+					t.Fatalf("cleanup boundary was removed: %v", err)
+				}
+			})
+		}
+	}
+}

internal/protocol/bt/storage.go

@@ -0,0 +1,116 @@
+package bt
+
+import (
+	"context"
+	"errors"
+	"os"
+	"sync"
+
+	g "github.com/anacrolix/generics"
+	"github.com/anacrolix/torrent/metainfo"
+	"github.com/anacrolix/torrent/storage"
+)
+
+// deferredFileStorage lets metadata resolve without opening the user's files.
+// It binds once. After binding, pieces are supplied directly by file storage.
+type deferredFileStorage struct {
+	mu          sync.RWMutex
+	ctx         context.Context
+	info        *metainfo.Info
+	hash        metainfo.Hash
+	knownHashes []bool
+	owner       storage.ClientImplCloser
+	torrent     storage.TorrentImpl
+	closed      bool
+}
+
+func (s *deferredFileStorage) OpenTorrent(ctx context.Context, info *metainfo.Info, hash metainfo.Hash) (storage.TorrentImpl, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed || s.info != nil {
+		return storage.TorrentImpl{}, errors.New("torrent storage already opened or closed")
+	}
+	s.ctx, s.info, s.hash = ctx, info, hash
+	s.knownHashes = make([]bool, info.NumPieces())
+	return storage.TorrentImpl{
+		PieceWithHash: func(p metainfo.Piece, hash g.Option[[]byte]) storage.PieceImpl {
+			s.mu.Lock()
+			defer s.mu.Unlock()
+			if s.closed {
+				return metadataPiece{err: os.ErrClosed}
+			}
+			if s.owner == nil {
+				s.knownHashes[p.Index()] = hash.Ok
+				// A missing v2 hash must remain unknown until its arrival changes
+				// completion and updates the library's piece request priorities.
+				return metadataPiece{known: hash.Ok}
+			}
+			if s.torrent.PieceWithHash != nil {
+				return s.torrent.PieceWithHash(p, hash)
+			}
+			return s.torrent.Piece(p)
+		},
+		Close: s.Close,
+	}, nil
+}
+
+func (s *deferredFileStorage) bind(opts storage.NewFileClientOpts) ([]bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return nil, os.ErrClosed
+	}
+	if s.info == nil {
+		return nil, errors.New("torrent metadata is not ready")
+	}
+	if s.owner != nil {
+		return nil, nil
+	}
+	if opts.FilePathMaker == nil {
+		opts.FilePathMaker = func(o storage.FilePathMakerOpts) string { _, name := torrentFileLayout(o.Info, *o.File); return name }
+	}
+	owner := storage.NewFileOpts(opts)
+	t, err := owner.OpenTorrent(s.ctx, s.info, s.hash)
+	if err != nil {
+		owner.Close()
+		return nil, err
+	}
+	s.owner, s.torrent = owner, t
+	return append([]bool(nil), s.knownHashes...), nil
+}
+
+func (s *deferredFileStorage) Close() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return nil
+	}
+	s.closed = true
+	if s.owner == nil {
+		return nil
+	}
+	var err error
+	if s.torrent.Close != nil {
+		err = s.torrent.Close()
+	}
+	return errors.Join(err, s.owner.Close())
+}
+
+type metadataPiece struct {
+	known bool
+	err   error
+}
+
+func (p metadataPiece) Completion() storage.Completion {
+	return storage.Completion{Ok: p.known, Err: p.err}
+}
+func (p metadataPiece) ReadAt([]byte, int64) (int, error) {
+	return 0, errors.New("download storage is not initialized")
+}
+func (p metadataPiece) WriteAt([]byte, int64) (int, error) {
+	return 0, errors.New("download storage is not initialized")
+}
+func (p metadataPiece) MarkComplete() error { return errors.New("download storage is not initialized") }
+func (p metadataPiece) MarkNotComplete() error {
+	return errors.New("download storage is not initialized")
+}

internal/protocol/bt/trackers.go

@@ -0,0 +1,234 @@
+package bt
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/url"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+)
+
+var defaultTrackerSubscribeURLs = []string{
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all_http.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all_https.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all_ip.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all_udp.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_all_ws.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt",
+	"https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best_ip.txt",
+	"https://raw.githubusercontent.com/XIU2/TrackersListCollection/master/all.txt",
+	"https://raw.githubusercontent.com/XIU2/TrackersListCollection/master/best.txt",
+	"https://raw.githubusercontent.com/XIU2/TrackersListCollection/master/http.txt",
+}
+
+func validTracker(raw string) bool {
+	u, err := url.Parse(raw)
+	if err != nil || u.Hostname() == "" || u.User != nil {
+		return false
+	}
+	switch u.Scheme {
+	case "udp", "http", "https", "ws", "wss":
+		return true
+	}
+	return false
+}
+func uniqueTrackers(groups ...[]string) []string {
+	result := []string{}
+	seen := map[string]bool{}
+	for _, group := range groups {
+		for _, raw := range group {
+			value := strings.TrimSpace(raw)
+			if value != "" && !seen[value] {
+				seen[value] = true
+				result = append(result, value)
+			}
+		}
+	}
+	return result
+}
+
+// effectiveTrackers derives the client list without persisting duplicate lists.
+func (c *config) effectiveTrackers() []string {
+	groups := [][]string{c.CustomTrackers}
+	for _, source := range c.TrackerSubscribeURLs {
+		groups = append(groups, c.State.TrackerSources[source])
+	}
+	return uniqueTrackers(groups...)
+}
+func (fm *FetcherManager) NormalizeConfig(raw json.RawMessage) (any, error) {
+	c := fm.DefaultConfig().(*config)
+	if err := json.Unmarshal(raw, c); err != nil {
+		return nil, err
+	}
+	if c.ListenPort < 0 || c.ListenPort > 65535 || c.SeedRatio < 0 || c.SeedTime < 0 {
+		return nil, errors.New("invalid BT configuration")
+	}
+	if len(c.TrackerSubscribeURLs) > 64 {
+		return nil, errors.New("too many tracker subscriptions")
+	}
+	c.TrackerSubscribeURLs = uniqueTrackers(c.TrackerSubscribeURLs)
+	for _, source := range c.TrackerSubscribeURLs {
+		u, err := url.Parse(source)
+		if err != nil || u == nil || (u.Scheme != "https" && u.Scheme != "http") || u.Hostname() == "" || u.User != nil {
+			return nil, errors.New("invalid tracker subscription URL")
+		}
+	}
+	c.CustomTrackers = uniqueTrackers(c.CustomTrackers)
+	for _, tracker := range c.CustomTrackers {
+		if !validTracker(tracker) {
+			return nil, fmt.Errorf("invalid tracker URL: %s", tracker)
+		}
+	}
+	if c.State.TrackerSources == nil {
+		c.State.TrackerSources = map[string][]string{}
+	}
+	for source := range c.State.TrackerSources {
+		if !slices.Contains(c.TrackerSubscribeURLs, source) {
+			delete(c.State.TrackerSources, source)
+		}
+	}
+	if c.State.TrackerSubscriptionStatuses == nil {
+		c.State.TrackerSubscriptionStatuses = map[string]trackerSubscriptionStatus{}
+	}
+	for source := range c.State.TrackerSubscriptionStatuses {
+		if !slices.Contains(c.TrackerSubscribeURLs, source) {
+			delete(c.State.TrackerSubscriptionStatuses, source)
+		}
+	}
+	return c, nil
+}
+func (fm *FetcherManager) CronJobs(host fetcher.ProtocolHost) []fetcher.CronJob {
+	return []fetcher.CronJob{{
+		Name:    "update-trackers",
+		Every:   24 * time.Hour,
+		Timeout: 90 * time.Second,
+		Run: func(ctx context.Context, source fetcher.TriggerSource) error {
+			return fm.updateTrackers(ctx, host, source)
+		},
+	}}
+}
+func parseTrackers(data []byte) ([]string, error) {
+	scanner := bufio.NewScanner(bytes.NewReader(data))
+	scanner.Buffer(make([]byte, 4096), 64*1024)
+	result := []string{}
+	for scanner.Scan() {
+		line := strings.TrimSpace(strings.TrimPrefix(scanner.Text(), "\ufeff"))
+		if validTracker(line) {
+			result = append(result, line)
+		}
+		if len(result) > 20000 {
+			return nil, errors.New("too many trackers")
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+	if len(result) == 0 {
+		return nil, errors.New("subscription contains no valid trackers")
+	}
+	return uniqueTrackers(result), nil
+}
+func (fm *FetcherManager) updateTrackers(ctx context.Context, host fetcher.ProtocolHost, source fetcher.TriggerSource) error {
+	snapshot, err := fetcher.ReadConfig[config](host)
+	if err != nil {
+		return err
+	}
+	if (source == fetcher.TriggerScheduled && !snapshot.AutoUpdateTrackers) || len(snapshot.TrackerSubscribeURLs) == 0 {
+		return fetcher.ErrJobSkipped
+	}
+	fetched := map[string][]string{}
+	statuses := map[string]trackerSubscriptionStatus{}
+	var failures []error
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+	slots := make(chan struct{}, 4)
+	for _, address := range snapshot.TrackerSubscribeURLs {
+		wg.Add(1)
+		go func(address string) {
+			defer wg.Done()
+			select {
+			case slots <- struct{}{}:
+				defer func() { <-slots }()
+			case <-ctx.Done():
+				return
+			}
+			data, err := host.Fetch(ctx, address, 2<<20, func(body []byte) error { _, err := parseTrackers(body); return err })
+			var trackers []string
+			if err == nil {
+				trackers, err = parseTrackers(data)
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			statuses[address] = trackerSubscriptionStatus{Success: err == nil, TrackerCount: len(trackers), LastFetchTime: time.Now().UTC()}
+			if err != nil {
+				failures = append(failures, fmt.Errorf("subscription %s: %w", address, err))
+			} else {
+				fetched[address] = trackers
+			}
+		}(address)
+	}
+	wg.Wait()
+	if err := ctx.Err(); err != nil {
+		failures = append(failures, err)
+	}
+	if len(statuses) == 0 {
+		return errors.Join(failures...)
+	}
+	err = fetcher.UpdateState[config, state](host, func(current *config, state *state) error {
+		if !slices.Equal(current.TrackerSubscribeURLs, snapshot.TrackerSubscribeURLs) {
+			return fetcher.ErrConfigChanged
+		}
+		if state.TrackerSources == nil {
+			state.TrackerSources = map[string][]string{}
+		}
+		if state.TrackerSubscriptionStatuses == nil {
+			state.TrackerSubscriptionStatuses = map[string]trackerSubscriptionStatus{}
+		}
+		for address, status := range statuses {
+			state.TrackerSubscriptionStatuses[address] = status
+		}
+		for address, trackers := range fetched {
+			state.TrackerSources[address] = trackers
+		}
+		if len(failures) == 0 {
+			state.LastTrackerUpdateTime = time.Now().UTC()
+		}
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+	current, err := fetcher.ReadConfig[config](host)
+	if err != nil {
+		return err
+	}
+	fm.applyTrackers(current.effectiveTrackers())
+	return errors.Join(failures...)
+}
+func (fm *FetcherManager) applyTrackers(trackers []string) {
+	lock.Lock()
+	defer lock.Unlock()
+	if client == nil {
+		return
+	}
+	announce := make([][]string, 0, len(trackers))
+	for _, tracker := range trackers {
+		announce = append(announce, []string{tracker})
+	}
+	for _, t := range client.Torrents() {
+		info := t.Info()
+		if info == nil || (info.Private != nil && *info.Private) {
+			continue
+		}
+		t.AddTrackers(announce)
+	}
+}

internal/protocol/bt/trackers_test.go

@@ -0,0 +1,217 @@
+package bt
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+)
+
+func trackerTestHost(t *testing.T, c *config, fetch func(context.Context, string, int64, func([]byte) error) ([]byte, error)) (fetcher.ProtocolHost, *sync.Mutex) {
+	t.Helper()
+	mu := &sync.Mutex{}
+	return fetcher.ProtocolHost{
+		Read: func(dst any) error {
+			mu.Lock()
+			defer mu.Unlock()
+			raw, err := json.Marshal(c)
+			if err != nil {
+				return err
+			}
+			return json.Unmarshal(raw, dst)
+		},
+		UpdateState: func(change func(config, state json.RawMessage) (any, error)) error {
+			mu.Lock()
+			defer mu.Unlock()
+			raw, _ := json.Marshal(c)
+			currentState, _ := json.Marshal(c.State)
+			next, err := change(raw, currentState)
+			if err != nil {
+				return err
+			}
+			raw, err = json.Marshal(next)
+			if err != nil {
+				return err
+			}
+			return json.Unmarshal(raw, &c.State)
+		},
+		Fetch: fetch,
+	}, mu
+}
+func TestTrackerRefreshPartialSuccessUsesLatestConfig(t *testing.T) {
+	fm := &FetcherManager{}
+	cfg := fm.DefaultConfig().(*config)
+	cfg.TrackerSubscribeURLs = []string{"https://a.example/list", "https://b.example/list"}
+	cfg.CustomTrackers = []string{"udp://custom.example:80/announce"}
+	cfg.State.TrackerSources = map[string][]string{cfg.TrackerSubscribeURLs[0]: {"udp://old.example:80/announce"}, cfg.TrackerSubscribeURLs[1]: {"udp://cached.example:80/announce"}}
+	host, mu := trackerTestHost(t, cfg, nil)
+	host.Fetch = func(ctx context.Context, address string, _ int64, validate func([]byte) error) ([]byte, error) {
+		if address == "https://b.example/list" {
+			return nil, errors.New("offline")
+		}
+		// Simulate a frontend update while the network request is in flight.
+		mu.Lock()
+		cfg.CustomTrackers = []string{"udp://new-custom.example:80/announce"}
+		mu.Unlock()
+		data := []byte("udp://fresh.example:80/announce\n# ignored\nudp://fresh.example:80/announce\n")
+		return data, validate(data)
+	}
+	err := fm.updateTrackers(context.Background(), host, fetcher.TriggerManual)
+	if err == nil {
+		t.Fatal("partial failure must be reported")
+	}
+	want := []string{"udp://new-custom.example:80/announce", "udp://fresh.example:80/announce", "udp://cached.example:80/announce"}
+	if !reflect.DeepEqual(cfg.effectiveTrackers(), want) {
+		t.Fatalf("got %v", cfg.effectiveTrackers())
+	}
+	success := cfg.State.TrackerSubscriptionStatuses["https://a.example/list"]
+	failure := cfg.State.TrackerSubscriptionStatuses["https://b.example/list"]
+	if !success.Success || success.TrackerCount != 1 || success.LastFetchTime.IsZero() || failure.Success || failure.TrackerCount != 0 || failure.LastFetchTime.IsZero() {
+		t.Fatalf("unexpected subscription statuses: %+v", cfg.State.TrackerSubscriptionStatuses)
+	}
+	if !cfg.State.LastTrackerUpdateTime.IsZero() {
+		t.Fatal("partial refresh marked fully successful")
+	}
+}
+func TestTrackerRefreshDiscardsChangedSubscriptions(t *testing.T) {
+	fm := &FetcherManager{}
+	cfg := fm.DefaultConfig().(*config)
+	cfg.TrackerSubscribeURLs = []string{"https://a.example/list"}
+	host, mu := trackerTestHost(t, cfg, nil)
+	host.Fetch = func(context.Context, string, int64, func([]byte) error) ([]byte, error) {
+		mu.Lock()
+		cfg.TrackerSubscribeURLs = []string{}
+		mu.Unlock()
+		return []byte("udp://fresh.example:80/announce"), nil
+	}
+	if err := fm.updateTrackers(context.Background(), host, fetcher.TriggerManual); !errors.Is(err, fetcher.ErrConfigChanged) {
+		t.Fatal(err)
+	}
+	if len(cfg.State.TrackerSources) != 0 {
+		t.Fatal("outdated source was committed")
+	}
+}
+func TestTrackerRefreshManualWorksWhenAutomaticDisabled(t *testing.T) {
+	fm := &FetcherManager{}
+	cfg := fm.DefaultConfig().(*config)
+	cfg.AutoUpdateTrackers = false
+	cfg.TrackerSubscribeURLs = []string{"https://a.example/list"}
+	calls := 0
+	host, _ := trackerTestHost(t, cfg, func(context.Context, string, int64, func([]byte) error) ([]byte, error) {
+		calls++
+		return []byte("udp://fresh.example:80/announce"), nil
+	})
+	if err := fm.updateTrackers(context.Background(), host, fetcher.TriggerScheduled); !errors.Is(err, fetcher.ErrJobSkipped) {
+		t.Fatal(err)
+	}
+	if calls != 0 {
+		t.Fatal("scheduled job fetched while disabled")
+	}
+	if err := fm.updateTrackers(context.Background(), host, fetcher.TriggerManual); err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 || cfg.State.LastTrackerUpdateTime.IsZero() {
+		t.Fatal("manual refresh did not succeed")
+	}
+}
+func TestTrackerConfigPreservesExplicitSettings(t *testing.T) {
+	value, err := (&FetcherManager{}).NormalizeConfig(json.RawMessage(`{
+		"listenPort":6881, "trackerSubscribeUrls":[], "autoUpdateTrackers":false,
+		"customTrackers":["udp://custom.example:80/announce"]
+	}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg := value.(*config)
+	if cfg.AutoUpdateTrackers || len(cfg.TrackerSubscribeURLs) != 0 || cfg.ListenPort != 6881 {
+		t.Fatalf("%+v", cfg)
+	}
+	if !reflect.DeepEqual(cfg.effectiveTrackers(), cfg.CustomTrackers) {
+		t.Fatalf("derived trackers: %v", cfg.effectiveTrackers())
+	}
+}
+
+func TestParseTrackerList(t *testing.T) {
+	got, err := parseTrackers([]byte("\ufeffudp://tracker.example:80/announce\r\n\n<html>error</html>\nhttps://tracker.example/announce\n"))
+	if err != nil || len(got) != 2 {
+		t.Fatalf("%v %v", got, err)
+	}
+	if _, err := parseTrackers([]byte("<html>mirror error</html>")); err == nil {
+		t.Fatal("invalid mirror body accepted")
+	}
+}
+func TestTrackerDefaultsRegisterDailyJob(t *testing.T) {
+	jobs := (&FetcherManager{}).CronJobs(fetcher.ProtocolHost{})
+	if len(jobs) != 1 || jobs[0].Name != "update-trackers" || jobs[0].Every != 24*time.Hour {
+		t.Fatal(jobs)
+	}
+}
+
+func TestTrackerRefreshAllFailuresPersistStatusesAndKeepCache(t *testing.T) {
+	fm := &FetcherManager{}
+	cfg := fm.DefaultConfig().(*config)
+	address := "https://custom.example/trackers.txt"
+	cfg.TrackerSubscribeURLs = []string{address}
+	cfg.State.TrackerSources[address] = []string{"udp://cached.example:80/announce"}
+	cfg.State.TrackerSubscriptionStatuses[address] = trackerSubscriptionStatus{Success: true, TrackerCount: 1, LastFetchTime: time.Now().Add(-time.Hour)}
+	host, _ := trackerTestHost(t, cfg, func(context.Context, string, int64, func([]byte) error) ([]byte, error) {
+		return nil, errors.New("offline")
+	})
+	before := time.Now()
+	if err := fm.updateTrackers(context.Background(), host, fetcher.TriggerManual); err == nil {
+		t.Fatal("failure was not reported")
+	}
+	status, ok := cfg.State.TrackerSubscriptionStatuses[address]
+	if !ok || status.Success || status.TrackerCount != 0 || status.LastFetchTime.Before(before) {
+		t.Fatalf("failed fetch status not stored: %+v", status)
+	}
+	if !reflect.DeepEqual(cfg.State.TrackerSources[address], []string{"udp://cached.example:80/announce"}) {
+		t.Fatal("last good cache lost")
+	}
+	if !reflect.DeepEqual(cfg.effectiveTrackers(), cfg.State.TrackerSources[address]) {
+		t.Fatal("cached trackers not retained")
+	}
+}
+
+func TestTrackerConfigPrunesRemovedSubscriptions(t *testing.T) {
+	fm := &FetcherManager{}
+	cfg := fm.DefaultConfig().(*config)
+	address := "https://custom.example/trackers.txt"
+	cfg.TrackerSubscribeURLs = []string{}
+	cfg.State.TrackerSources[address] = []string{"udp://cached.example:80/announce"}
+	cfg.State.TrackerSubscriptionStatuses[address] = trackerSubscriptionStatus{Success: true, TrackerCount: 1, LastFetchTime: time.Now()}
+	raw, _ := json.Marshal(cfg)
+	value, err := fm.NormalizeConfig(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	next := value.(*config)
+	if len(next.State.TrackerSources) != 0 || len(next.State.TrackerSubscriptionStatuses) != 0 || len(next.effectiveTrackers()) != 0 {
+		t.Fatal("removed subscription still owns cached results")
+	}
+}
+
+func TestTrackerRefreshTimeoutPersistsCompletedAttemptStatus(t *testing.T) {
+	fm := &FetcherManager{}
+	cfg := fm.DefaultConfig().(*config)
+	address := "https://custom.example/trackers.txt"
+	cfg.TrackerSubscribeURLs = []string{address}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	host, _ := trackerTestHost(t, cfg, func(context.Context, string, int64, func([]byte) error) ([]byte, error) {
+		cancel()
+		return nil, context.DeadlineExceeded
+	})
+	if err := fm.updateTrackers(ctx, host, fetcher.TriggerManual); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatal(err)
+	}
+	status, ok := cfg.State.TrackerSubscriptionStatuses[address]
+	if !ok || status.Success || status.TrackerCount != 0 || status.LastFetchTime.IsZero() {
+		t.Fatalf("timeout status lost: %+v", status)
+	}
+}

internal/protocol/ed2k/fetcher.go

@@ -67,17 +67,14 @@ func (f *Fetcher) Setup(ctl *controller.Controller) {
 	f.ctl.GetConfig(&f.config)
 }
 
-func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
+func (f *Fetcher) Resolve(req *base.Request) error {
 	link, err := parseLink(req.URL)
 	if err != nil {
 		return err
 	}
 
 	f.meta.Req = req
-	f.meta.Opts = opts
-	if f.meta.Opts == nil {
-		f.meta.Opts = &base.Options{}
-	}
+
 	f.meta.Res = buildResource(link)
 	return nil
 }

internal/protocol/ed2k/fetcher_test.go

@@ -13,7 +13,8 @@ func TestFetcher_Resolve(t *testing.T) {
 	f := (&FetcherManager{}).Build()
 	f.Setup(controller.NewController())
 
-	err := f.Resolve(&base.Request{URL: testLink}, &base.Options{Path: t.TempDir()})
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	err := f.Resolve(&base.Request{URL: testLink})
 	if err != nil {
 		t.Fatalf("Resolve() error = %v", err)
 	}

internal/protocol/hls/config.go

@@ -0,0 +1,30 @@
+package hls
+
+const (
+	defaultSegmentConnections = 8
+	defaultMaxRetries         = 5
+	defaultTimeoutSeconds     = 30
+
+	// maxPrefetchSizeSegments caps the HEAD probing done at resolve time.
+	// Playlists larger than this skip size prefetch entirely.
+	maxPrefetchSizeSegments = 500
+)
+
+type config struct {
+	SegmentConnections    int  `json:"segmentConnections"`
+	MaxRetries            int  `json:"maxRetries"`
+	TimeoutSeconds        int  `json:"timeoutSeconds"`
+	PrefetchContentLength bool `json:"prefetchContentLength"`
+}
+
+func (c *config) normalize() {
+	if c.SegmentConnections <= 0 {
+		c.SegmentConnections = defaultSegmentConnections
+	}
+	if c.MaxRetries < 0 {
+		c.MaxRetries = defaultMaxRetries
+	}
+	if c.TimeoutSeconds <= 0 {
+		c.TimeoutSeconds = defaultTimeoutSeconds
+	}
+}

internal/protocol/hls/crypto.go

@@ -0,0 +1,59 @@
+package hls
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"fmt"
+)
+
+// decryptAES128 decrypts an AES-128-CBC encrypted segment and strips PKCS7
+// padding. data length must be a multiple of the AES block size.
+func decryptAES128(data, key, iv []byte) ([]byte, error) {
+	if len(key) != 16 {
+		return nil, fmt.Errorf("invalid AES-128 key size %d", len(key))
+	}
+	if len(iv) != 16 {
+		return nil, fmt.Errorf("invalid AES-128 IV size %d", len(iv))
+	}
+	if len(data) == 0 || len(data)%aes.BlockSize != 0 {
+		return nil, fmt.Errorf("invalid AES-128 data size %d", len(data))
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	plain := make([]byte, len(data))
+	cipher.NewCBCDecrypter(block, iv).CryptBlocks(plain, data)
+	return pkcs7Unpad(plain, aes.BlockSize)
+}
+
+func pkcs7Unpad(data []byte, blockSize int) ([]byte, error) {
+	if len(data) == 0 {
+		return nil, fmt.Errorf("empty plaintext")
+	}
+	pad := int(data[len(data)-1])
+	if pad == 0 || pad > blockSize || pad > len(data) {
+		return nil, fmt.Errorf("invalid PKCS7 padding")
+	}
+	for _, b := range data[len(data)-pad:] {
+		if int(b) != pad {
+			return nil, fmt.Errorf("invalid PKCS7 padding")
+		}
+	}
+	return data[:len(data)-pad], nil
+}
+
+// sequenceIV derives the default per-segment IV mandated by RFC 8216: the
+// segment media sequence number as a 16-byte big-endian integer.
+func sequenceIV(sequence int64) []byte {
+	iv := make([]byte, 16)
+	iv[8] = byte(sequence >> 56)
+	iv[9] = byte(sequence >> 48)
+	iv[10] = byte(sequence >> 40)
+	iv[11] = byte(sequence >> 32)
+	iv[12] = byte(sequence >> 24)
+	iv[13] = byte(sequence >> 16)
+	iv[14] = byte(sequence >> 8)
+	iv[15] = byte(sequence)
+	return iv
+}

internal/protocol/hls/crypto_test.go

@@ -0,0 +1,66 @@
+package hls
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"testing"
+)
+
+func pkcs7Pad(data []byte, blockSize int) []byte {
+	pad := blockSize - len(data)%blockSize
+	return append(data, bytes.Repeat([]byte{byte(pad)}, pad)...)
+}
+
+func TestDecryptAES128Roundtrip(t *testing.T) {
+	key := make([]byte, 16)
+	iv := make([]byte, 16)
+	if _, err := rand.Read(key); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := rand.Read(iv); err != nil {
+		t.Fatal(err)
+	}
+	plain := []byte("hello hls segment payload, padded to block size!")
+	padded := pkcs7Pad(plain, aes.BlockSize)
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		t.Fatal(err)
+	}
+	encrypted := make([]byte, len(padded))
+	cipher.NewCBCEncrypter(block, iv).CryptBlocks(encrypted, padded)
+
+	got, err := decryptAES128(encrypted, key, iv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(got, plain) {
+		t.Errorf("roundtrip mismatch: %q", got)
+	}
+}
+
+func TestDecryptAES128InvalidInput(t *testing.T) {
+	if _, err := decryptAES128([]byte{1, 2, 3}, make([]byte, 16), make([]byte, 16)); err == nil {
+		t.Error("non-block-aligned data should fail")
+	}
+	if _, err := decryptAES128(make([]byte, 16), make([]byte, 15), make([]byte, 16)); err == nil {
+		t.Error("short key should fail")
+	}
+	if _, err := decryptAES128(make([]byte, 16), make([]byte, 16), make([]byte, 16)); err == nil {
+		t.Error("all-zero block has invalid padding and should fail")
+	}
+}
+
+func TestSequenceIV(t *testing.T) {
+	iv := sequenceIV(1)
+	if len(iv) != 16 || iv[15] != 1 {
+		t.Errorf("sequence 1 IV wrong: %v", iv)
+	}
+	iv = sequenceIV(0x0102030405060708)
+	for i, want := range []byte{1, 2, 3, 4, 5, 6, 7, 8} {
+		if iv[8+i] != want {
+			t.Errorf("sequence IV byte %d: want %d got %d", i, want, iv[8+i])
+		}
+	}
+}

internal/protocol/hls/doc.go

@@ -0,0 +1,24 @@
+// Package hls implements native HTTP Live Streaming downloads for m3u8
+// playlists. A task produces exactly one merged, playable output file:
+// MPEG-2 TS segments are concatenated as-is, fMP4 streams are merged as
+// init section followed by the media fragments, and AES-128 encrypted
+// segments are decrypted before they are stored.
+//
+// Supported subset:
+//   - VOD media playlists (EXT-X-ENDLIST present) and master playlists whose
+//     selected variant carries its own audio
+//   - AES-128 with the identity KEYFORMAT, explicit IV or media-sequence
+//     derived IV, including key rotation mid-playlist
+//   - EXT-X-BYTERANGE (including offset inheritance) and fMP4 init sections
+//     via a single, constant EXT-X-MAP
+//
+// Everything the merge pipeline cannot reproduce faithfully is rejected with
+// an explicit error instead of silently producing a broken output file:
+//   - live streams (no EXT-X-ENDLIST) and SAMPLE-AES / DRM encryption
+//   - EXT-X-GAP (would leave a hole) and EXT-X-DISCONTINUITY (broken timeline)
+//   - changing init sections (a repeated EXT-X-MAP is compared by all its
+//     attributes, not just the URI) and encrypted EXT-X-MAP without an
+//     explicit IV
+//   - separate audio renditions referenced by the selected variant (the
+//     merged output would have no audio) and non-identity KEYFORMATs
+package hls

internal/protocol/hls/fetcher.go

@@ -0,0 +1,997 @@
+package hls
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/controller"
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+	"github.com/GopeedLab/gopeed/internal/httpclient"
+	"github.com/GopeedLab/gopeed/pkg/base"
+)
+
+// ReqExtra mirrors the HTTP protocol extra: the create dialog attaches HTTP
+// style options to m3u8 URLs (same JSON keys), so the same shape is decoded.
+type ReqExtra struct {
+	Method string            `json:"method,omitempty"`
+	Header map[string]string `json:"header,omitempty"`
+	Body   string            `json:"body,omitempty"`
+}
+
+func copyReqExtra(extra *ReqExtra) *ReqExtra {
+	copied := &ReqExtra{}
+	if extra == nil {
+		return copied
+	}
+	copied.Method = extra.Method
+	copied.Body = extra.Body
+	if extra.Header != nil {
+		copied.Header = make(map[string]string, len(extra.Header))
+		for key, value := range extra.Header {
+			copied.Header[key] = value
+		}
+	}
+	return copied
+}
+
+// fetcherState is the resolved download plan persisted for resume. StagingID
+// gives the task its own staging folder (two tasks downloading the same URL
+// into the same directory never share segment files) and survives restarts
+// through the persisted state. StagingDir pins the absolute folder so user
+// renames or moves of the task output do not orphan the staged segments.
+type fetcherState struct {
+	MediaURL   string     `json:"mediaURL"`
+	OutputName string     `json:"outputName"`
+	Segments   []*Segment `json:"segments"`
+	StagingID  string     `json:"stagingID,omitempty"`
+	StagingDir string     `json:"stagingDir,omitempty"`
+}
+
+// Stats is the protocol task statistics snapshot.
+type Stats struct {
+	SegmentsTotal  int `json:"segmentsTotal"`
+	SegmentsDone   int `json:"segmentsDone"`
+	SegmentsFailed int `json:"segmentsFailed"`
+}
+
+// tempDirPrefix separates HLS staging folders from regular task files.
+const tempDirPrefix = ".gopeed-hls-"
+
+// hlsRun holds every piece of state that belongs to one Start..Pause/complete
+// cycle. Runs never share mutable state: a Pause that is immediately followed
+// by a Start replaces the whole run, so workers of the previous run cannot
+// race with the next one. The run also snapshots the plan, request headers,
+// client and merge target so concurrent Patch calls cannot change them under
+// a running download.
+type hlsRun struct {
+	ctx    context.Context
+	cancel context.CancelFunc
+	// wg covers the queue producer AND the segment workers: Pause must not
+	// return while the producer can still hand out segment indexes.
+	wg   sync.WaitGroup
+	done chan struct{} // closed when the supervisor has fully exited
+
+	segs       []*Segment // plan snapshot, read-only for the duration of the run
+	extra      *ReqExtra  // header snapshot (deep copy)
+	client     *http.Client
+	outputPath string // merge target snapshot
+	tempDir    string
+
+	keyCache   map[string][]byte
+	keyCacheMu sync.Mutex
+
+	stagingID   string // identity of the staging folder, bound into the journal
+	planHash    string // fingerprint of the download plan, validated on resume
+	journal     map[int64]int64
+	journalPath string
+	journalMu   sync.Mutex
+
+	// downloaded counts bytes of the final output that are safely on disk
+	// (completed segment files), not raw network traffic: discarded retry
+	// bytes must never show up as progress.
+	downloaded atomic.Int64
+	doneCount  atomic.Int64
+	failCount  atomic.Int64
+	baseBytes  int64   // stored bytes restored from the journal at startup
+	baseDone   int     // completed segments restored from the journal at startup
+	pending    []int64 // segment indexes to download, set by prepareRun
+}
+
+func (r *hlsRun) statsSnapshot() Stats {
+	return Stats{
+		SegmentsTotal:  len(r.segs),
+		SegmentsDone:   r.baseDone + int(r.doneCount.Load()),
+		SegmentsFailed: int(r.failCount.Load()),
+	}
+}
+
+type Fetcher struct {
+	fetcher.DefaultFetcher
+	meta   *fetcher.FetcherMeta
+	config *config
+
+	// mu guards the fields below and every lifecycle transition. Progress and
+	// Stats are read from the engine's checkpoint goroutine while a run is
+	// active; they only take mu to snapshot the active run pointer, then read
+	// run-owned atomics lock-free.
+	mu             sync.Mutex
+	extra          *ReqExtra
+	client         *http.Client
+	state          *fetcherState
+	activeRun      *hlsRun
+	closed         bool
+	lastStats      Stats
+	lastDownloaded int64
+
+	impSession *httpclient.ImpersonationSession
+}
+
+func (f *Fetcher) Setup(ctl *controller.Controller) {
+	// Initializes Ctl and DoneCh, which Wait() depends on.
+	f.DefaultFetcher.Setup(ctl)
+	if f.meta == nil {
+		f.meta = &fetcher.FetcherMeta{}
+	}
+	f.impSession = httpclient.NewImpersonationSession()
+	f.config = &config{}
+	f.Ctl.GetConfig(f.config)
+	f.config.normalize()
+	// Restored fetchers receive their request through Setup (the engine calls
+	// it after the Restore builder): parse the extra headers so resumed
+	// segment/key requests keep Referer/Cookie and other anti-hotlink headers.
+	f.mu.Lock()
+	f.reloadExtraLocked()
+	f.mu.Unlock()
+}
+
+// reloadExtraLocked refreshes f.extra from the typed extra of meta.Req.
+func (f *Fetcher) reloadExtraLocked() {
+	if f.meta == nil || f.meta.Req == nil {
+		return
+	}
+	if err := base.ParseReqExtra[ReqExtra](f.meta.Req); err != nil {
+		return
+	}
+	if e, ok := f.meta.Req.Extra.(*ReqExtra); ok {
+		f.extra = e
+	}
+}
+
+func (f *Fetcher) Meta() *fetcher.FetcherMeta {
+	return f.meta
+}
+
+func (f *Fetcher) Resolve(req *base.Request) (err error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.meta.Req = req
+
+	f.extra = &ReqExtra{}
+	if err = base.ParseReqExtra[ReqExtra](req); err != nil {
+		return
+	}
+	if e, ok := req.Extra.(*ReqExtra); ok {
+		f.extra = e
+	}
+	if f.client == nil {
+		f.client = f.buildClient()
+	}
+
+	state, name, err := f.resolvePlanLocked(context.Background(), "")
+	if err != nil {
+		return err
+	}
+	state.StagingID = randomStagingID()
+	f.state = state
+	size := planTotalSize(state.Segments)
+	f.meta.Res = &base.Resource{
+		Range: false,
+		Files: []*base.FileInfo{
+			{
+				Name: name,
+				Size: size,
+			},
+		},
+		Size: size,
+	}
+	return nil
+}
+
+// resolvePlanLocked fetches and parses the playlist into a fresh state. It
+// must be called with f.mu held while the fetcher is quiescent. When keepName
+// is non-empty the output keeps that file name (used when re-resolving an
+// existing task so a refreshed URL does not rename the file).
+func (f *Fetcher) resolvePlanLocked(ctx context.Context, keepName string) (*fetcherState, string, error) {
+	content, finalURL, err := f.fetchText(ctx, f.playlistMethod(), f.meta.Req.URL)
+	if err != nil {
+		return nil, "", fmt.Errorf("fetch playlist failed: %w", err)
+	}
+	baseURL, err := url.Parse(finalURL)
+	if err != nil {
+		return nil, "", err
+	}
+
+	mediaURL := finalURL
+	if IsMasterPlaylist(content) {
+		master, err := ParseMasterPlaylist(content, baseURL)
+		if err != nil {
+			return nil, "", err
+		}
+		best := PickBestVariant(master.Variants)
+		if err := checkAudioRendition(master, best); err != nil {
+			return nil, "", err
+		}
+		variantContent, variantURL, err := f.fetchText(ctx, http.MethodGet, best.URI)
+		if err != nil {
+			return nil, "", fmt.Errorf("fetch variant playlist failed: %w", err)
+		}
+		variantBase, err := url.Parse(variantURL)
+		if err != nil {
+			return nil, "", err
+		}
+		content = variantContent
+		baseURL = variantBase
+		mediaURL = variantURL
+	}
+	media, err := ParseMedia(content, baseURL)
+	if err != nil {
+		return nil, "", err
+	}
+	if err := validateSupported(media); err != nil {
+		return nil, "", err
+	}
+
+	outputName := keepName
+	if outputName == "" {
+		outputName = DeriveOutputName(mediaURL, media)
+	}
+	state := &fetcherState{
+		MediaURL:   mediaURL,
+		OutputName: outputName,
+		Segments:   media.Segments,
+	}
+	if f.config.PrefetchContentLength {
+		f.prefetchSize(media.Segments)
+	}
+	return state, outputName, nil
+}
+
+func (f *Fetcher) Patch(req *base.Request, opts *base.Options) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.activeRun != nil {
+		return errors.New("task is running; pause it before changing its settings")
+	}
+	if req != nil {
+		cur := f.meta.Req
+		if cur == nil {
+			f.meta.Req = req
+			cur = req
+		}
+		if req.URL != "" && req.URL != cur.URL {
+			cur.URL = req.URL
+			// The playlist URL changed (e.g. refreshed signed link): drop the
+			// plan so the engine re-resolves on next start (it does when Res
+			// is nil). Only explicitly supplied fields are applied, so a
+			// header-only or rename-only Patch keeps the resolved plan and
+			// the output path.
+			f.dropPlanLocked()
+		}
+		if err := mergeReqExtra(cur, req); err != nil {
+			return err
+		}
+		if req.Proxy != nil && cur.Proxy != req.Proxy {
+			cur.Proxy = req.Proxy
+			// Transport settings changed: rebuild the client before the
+			// next run.
+			f.client = nil
+		}
+		if len(req.Labels) > 0 {
+			if cur.Labels == nil {
+				cur.Labels = make(map[string]string, len(req.Labels))
+			}
+			for key, value := range req.Labels {
+				cur.Labels[key] = value
+			}
+		}
+		// SkipVerifyCert is a plain bool, so a partial update cannot tell an
+		// absent field from an explicit false: it is intentionally not merged
+		// (the HTTP protocol Patch ignores it as well).
+	}
+	if opts != nil {
+		if f.meta.Opts == nil {
+			f.meta.Opts = opts
+		} else {
+			if opts.Name != "" {
+				f.meta.Opts.Name = opts.Name
+			}
+			if opts.Path != "" {
+				f.meta.Opts.Path = opts.Path
+			}
+		}
+	}
+	f.reloadExtraLocked()
+	return nil
+}
+
+// mergeReqExtra merges the typed extra of incoming into cur following the
+// HTTP protocol semantics: Method/Body are overridden when non-empty and
+// headers are merged per key.
+func mergeReqExtra(cur *base.Request, incoming *base.Request) error {
+	if incoming.Extra == nil {
+		return nil
+	}
+	if err := base.ParseReqExtra[ReqExtra](incoming); err != nil {
+		return err
+	}
+	inc, ok := incoming.Extra.(*ReqExtra)
+	if !ok {
+		return nil
+	}
+	if err := base.ParseReqExtra[ReqExtra](cur); err != nil {
+		return err
+	}
+	target, ok := cur.Extra.(*ReqExtra)
+	if !ok {
+		target = &ReqExtra{}
+		cur.Extra = target
+	}
+	if inc.Method != "" {
+		target.Method = inc.Method
+	}
+	if inc.Body != "" {
+		target.Body = inc.Body
+	}
+	if len(inc.Header) > 0 {
+		if target.Header == nil {
+			target.Header = make(map[string]string, len(inc.Header))
+		}
+		for key, value := range inc.Header {
+			target.Header[key] = value
+		}
+	}
+	return nil
+}
+
+// dropPlanLocked discards the resolved plan after a URL change. The staging
+// folder of the dropped plan is removed too: this only runs while the
+// fetcher is quiescent, so no run can still be writing into it.
+func (f *Fetcher) dropPlanLocked() {
+	if f.state != nil && f.state.StagingDir != "" {
+		os.RemoveAll(f.state.StagingDir)
+	}
+	f.state = nil
+	f.meta.Res = nil
+}
+
+// existingOutputNameLocked returns the output file name the task already
+// uses, so a re-resolve does not rename an in-progress download.
+func (f *Fetcher) existingOutputNameLocked() string {
+	if f.meta.Opts != nil && f.meta.Opts.Name != "" {
+		return f.meta.Opts.Name
+	}
+	if res := f.meta.Res; res != nil && len(res.Files) > 0 && res.Files[0] != nil {
+		return res.Files[0].Name
+	}
+	return ""
+}
+
+func (f *Fetcher) Start() error {
+	f.mu.Lock()
+	if f.closed {
+		f.mu.Unlock()
+		return errors.New("hls fetcher is closed")
+	}
+	if f.activeRun != nil {
+		f.mu.Unlock()
+		return errors.New("hls fetcher already running")
+	}
+	if f.state == nil {
+		if f.meta.Req == nil || f.meta.Res == nil {
+			f.mu.Unlock()
+			return errors.New("hls fetcher is not resolved")
+		}
+		// Crash window: the engine persists the task (with its resource)
+		// before the first HLS state checkpoint lands, so a restored task
+		// can have a resource but no plan. Rebuild the plan instead of
+		// failing, keeping the existing output name.
+		if f.client == nil {
+			f.client = f.buildClient()
+		}
+		state, _, err := f.resolvePlanLocked(context.Background(), f.existingOutputNameLocked())
+		if err != nil {
+			f.mu.Unlock()
+			return fmt.Errorf("re-resolve failed: %w", err)
+		}
+		f.state = state
+		size := planTotalSize(state.Segments)
+		if res := f.meta.Res; res != nil {
+			res.Size = size
+			if len(res.Files) > 0 && res.Files[0] != nil {
+				res.Files[0].Size = size
+			}
+		}
+	}
+	// The client is built here, before any worker exists, so segment
+	// goroutines never race on lazy initialization.
+	if f.client == nil {
+		f.client = f.buildClient()
+	}
+	if f.meta.Res == nil {
+		// A restored plan without a resource cannot determine its output
+		// path; the engine re-resolves when Res is nil.
+		f.mu.Unlock()
+		return errors.New("hls fetcher is not resolved")
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	run := &hlsRun{
+		ctx:        ctx,
+		cancel:     cancel,
+		done:       make(chan struct{}),
+		segs:       f.state.Segments,
+		extra:      copyReqExtra(f.extra),
+		client:     f.client,
+		outputPath: f.meta.SingleFilepath(),
+		stagingID:  f.state.StagingID,
+		planHash:   planFingerprint(f.state),
+		tempDir:    f.resolveStagingDirLocked(),
+		keyCache:   make(map[string][]byte),
+		journal:    make(map[int64]int64),
+	}
+	// Prepare staging and the completed-segment counters BEFORE publishing
+	// the run: Stats/Progress may observe it immediately afterwards and must
+	// never read half-initialized plain fields.
+	if err := f.prepareRun(run); err != nil {
+		f.mu.Unlock()
+		run.cancel()
+		close(run.done)
+		return err
+	}
+	f.activeRun = run
+	f.mu.Unlock()
+
+	f.launchWorkers(run)
+	go f.supervise(run)
+	return nil
+}
+
+// Pause stops all segment downloads synchronously. It waits for the queue
+// producer, every worker AND the supervisor (including a merge in flight)
+// before returning, so a Store right after Pause sees a consistent state.
+func (f *Fetcher) Pause() error {
+	f.mu.Lock()
+	run := f.activeRun
+	f.mu.Unlock()
+	if run == nil {
+		return nil
+	}
+	run.cancel()
+	<-run.done
+	f.clearActiveRun(run)
+	return nil
+}
+
+// Close pauses any active run and only removes the staging folder once every
+// run goroutine has stopped writing to it.
+func (f *Fetcher) Close() error {
+	f.mu.Lock()
+	f.closed = true
+	run := f.activeRun
+	tempDir := ""
+	if f.state != nil {
+		tempDir = f.resolveStagingDirLocked()
+	}
+	f.mu.Unlock()
+
+	if run != nil {
+		run.cancel()
+		<-run.done
+		f.clearActiveRun(run)
+	}
+	if f.impSession != nil {
+		f.impSession.Clear()
+	}
+	if tempDir != "" {
+		os.RemoveAll(tempDir)
+	}
+	return nil
+}
+
+// clearActiveRun detaches a finished run and keeps its counters as the last
+// known values for idle Stats/Progress reporting.
+func (f *Fetcher) clearActiveRun(run *hlsRun) {
+	f.mu.Lock()
+	if f.activeRun == run {
+		f.activeRun = nil
+		f.lastStats = run.statsSnapshot()
+		f.lastDownloaded = run.downloaded.Load()
+	}
+	f.mu.Unlock()
+}
+
+// Progress reports final-output bytes stored on disk for the single file.
+func (f *Fetcher) Progress() fetcher.Progress {
+	f.mu.Lock()
+	run := f.activeRun
+	if run != nil {
+		f.mu.Unlock()
+		return fetcher.Progress{run.downloaded.Load()}
+	}
+	last := f.lastDownloaded
+	f.mu.Unlock()
+	return fetcher.Progress{last}
+}
+
+func (f *Fetcher) Stats() *fetcher.Stats {
+	f.mu.Lock()
+	run := f.activeRun
+	state := f.state
+	if run != nil {
+		f.mu.Unlock()
+		snap := run.statsSnapshot()
+		return &fetcher.Stats{Snapshot: &snap}
+	}
+	snap := f.lastStats
+	f.mu.Unlock()
+	if snap.SegmentsTotal == 0 && state != nil {
+		snap.SegmentsTotal = len(state.Segments)
+	}
+	return &fetcher.Stats{Snapshot: &snap}
+}
+
+// supervise waits for the segment workers, then merges. A canceled context
+// exits silently (the engine is pausing), everything else is reported through
+// DoneCh exactly once per run.
+func (f *Fetcher) supervise(run *hlsRun) {
+	run.wg.Wait()
+	defer close(run.done)
+
+	if run.ctx.Err() != nil {
+		f.clearActiveRun(run)
+		return
+	}
+	var err error
+	if failed := run.failCount.Load(); failed > 0 {
+		err = fmt.Errorf("%d segment(s) failed to download", failed)
+	} else {
+		err = f.merge(run)
+		if err == nil {
+			if run.ctx.Err() != nil {
+				// Paused while the merge was in flight: keep the staged
+				// segments and exit silently; the next run re-merges.
+				f.clearActiveRun(run)
+				return
+			}
+			os.RemoveAll(run.tempDir)
+		}
+	}
+	f.clearActiveRun(run)
+	select {
+	case f.DoneCh <- err:
+	default:
+	}
+}
+
+// prepareRun prepares the staging folder and loads the completed-segment
+// journal into run.baseBytes/baseDone/pending. It performs no goroutine
+// launches and no context-bound work, so it runs safely under f.mu before
+// the run is published.
+func (f *Fetcher) prepareRun(run *hlsRun) error {
+	if err := os.MkdirAll(run.tempDir, 0777); err != nil {
+		return err
+	}
+	run.journalPath = filepath.Join(run.tempDir, "journal.json")
+	if err := loadJournal(run); err != nil {
+		return err
+	}
+	for i := range run.segs {
+		if size, ok := run.journal[int64(i)]; ok {
+			if info, err := os.Stat(segmentPath(run.tempDir, int64(i))); err == nil && info.Size() == size {
+				run.baseBytes += size
+				run.baseDone++
+				continue
+			}
+		}
+		run.pending = append(run.pending, int64(i))
+	}
+	run.downloaded.Store(run.baseBytes)
+	return nil
+}
+
+// launchWorkers starts the queue producer and the segment download workers
+// for a published run. Every goroutine registers itself in run.wg so Pause
+// waits for all of them.
+func (f *Fetcher) launchWorkers(run *hlsRun) {
+	if len(run.pending) == 0 {
+		return
+	}
+	queue := make(chan int64)
+	run.wg.Add(1)
+	go func() {
+		defer run.wg.Done()
+		defer close(queue)
+		for _, idx := range run.pending {
+			select {
+			case <-run.ctx.Done():
+				return
+			case queue <- idx:
+			}
+		}
+	}()
+
+	workers := min(f.config.SegmentConnections, len(run.pending))
+	for i := 0; i < workers; i++ {
+		run.wg.Add(1)
+		go func() {
+			defer run.wg.Done()
+			for {
+				select {
+				case <-run.ctx.Done():
+					return
+				case idx, ok := <-queue:
+					if !ok {
+						return
+					}
+					if err := f.downloadSegment(run, idx); err != nil {
+						if errors.Is(err, context.Canceled) {
+							return
+						}
+						run.failCount.Add(1)
+					}
+				}
+			}
+		}()
+	}
+}
+
+func (f *Fetcher) downloadSegment(run *hlsRun, idx int64) error {
+	seg := run.segs[idx]
+	data, err := f.fetchSegmentData(run, seg)
+	if err != nil {
+		return err
+	}
+	if seg.Key != nil {
+		key, err := f.fetchKey(run, seg.Key)
+		if err != nil {
+			return err
+		}
+		iv := seg.Key.IV
+		if iv == nil {
+			iv = sequenceIV(seg.Sequence)
+		}
+		data, err = decryptAES128(data, key, iv)
+		if err != nil {
+			return err
+		}
+	}
+	if err := storeSegment(run, idx, data); err != nil {
+		return err
+	}
+	run.doneCount.Add(1)
+	run.downloaded.Add(int64(len(data)))
+	return nil
+}
+
+// fetchSegmentData downloads one segment with retries, returning its (still
+// encrypted) content.
+func (f *Fetcher) fetchSegmentData(run *hlsRun, seg *Segment) ([]byte, error) {
+	var lastErr error
+	for attempt := 0; attempt <= f.config.MaxRetries; attempt++ {
+		if err := run.ctx.Err(); err != nil {
+			return nil, err
+		}
+		if attempt > 0 {
+			select {
+			case <-run.ctx.Done():
+				return nil, run.ctx.Err()
+			case <-time.After(time.Duration(attempt) * time.Second):
+			}
+		}
+		data, err := f.tryGetSegment(run, seg)
+		if err == nil {
+			return data, nil
+		}
+		if errors.Is(err, context.Canceled) {
+			return nil, err
+		}
+		lastErr = err
+	}
+	return nil, lastErr
+}
+
+func (f *Fetcher) tryGetSegment(run *hlsRun, seg *Segment) ([]byte, error) {
+	resp, err := f.do(run.ctx, run.client, run.extra, http.MethodGet, seg.URI, seg.Byterange)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("segment %s: unexpected status %d", seg.URI, resp.StatusCode)
+	}
+	reader := &stallReader{rc: resp.Body, timeout: f.timeout()}
+	var buf bytes.Buffer
+	chunk := make([]byte, 64<<10)
+	for {
+		n, err := reader.Read(chunk)
+		if n > 0 {
+			buf.Write(chunk[:n])
+		}
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			return nil, err
+		}
+	}
+	if seg.Byterange != nil && int64(buf.Len()) != seg.Byterange.Length {
+		return nil, fmt.Errorf("segment %s: size mismatch, got %d want %d", seg.URI, buf.Len(), seg.Byterange.Length)
+	}
+	return buf.Bytes(), nil
+}
+
+func (f *Fetcher) fetchKey(run *hlsRun, key *Key) ([]byte, error) {
+	run.keyCacheMu.Lock()
+	if cached, ok := run.keyCache[key.URI]; ok {
+		run.keyCacheMu.Unlock()
+		return cached, nil
+	}
+	run.keyCacheMu.Unlock()
+
+	var data []byte
+	var err error
+	for attempt := 0; attempt <= f.config.MaxRetries; attempt++ {
+		if err = run.ctx.Err(); err != nil {
+			return nil, err
+		}
+		if attempt > 0 {
+			select {
+			case <-run.ctx.Done():
+				return nil, run.ctx.Err()
+			case <-time.After(time.Duration(attempt) * time.Second):
+			}
+		}
+		resp, reqErr := f.do(run.ctx, run.client, run.extra, http.MethodGet, key.URI, nil)
+		if reqErr != nil {
+			err = reqErr
+			continue
+		}
+		if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+			resp.Body.Close()
+			err = fmt.Errorf("key %s: unexpected status %d", key.URI, resp.StatusCode)
+			continue
+		}
+		data, err = io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		resp.Body.Close()
+		if err == nil {
+			break
+		}
+	}
+	if err != nil {
+		return nil, err
+	}
+	if len(data) != 16 {
+		return nil, fmt.Errorf("key %s: invalid key size %d", key.URI, len(data))
+	}
+	run.keyCacheMu.Lock()
+	run.keyCache[key.URI] = data
+	run.keyCacheMu.Unlock()
+	return data, nil
+}
+
+// merge concatenates the downloaded segments in plan order into the final
+// output file. Segments are stored decrypted, so this is pure I/O. The merge
+// writes to a unique temporary file next to the target, checks write and
+// close errors, and only then replaces the target: a failed merge leaves the
+// staged segments intact so it can be retried, and the unique part name keeps
+// concurrent tasks that share an output path from clobbering each other. The
+// final size is published through Progress: the engine backfills Res.Size
+// from Progress().TotalDownloaded() on completion.
+func (f *Fetcher) merge(run *hlsRun) error {
+	target := run.outputPath
+	if err := os.MkdirAll(filepath.Dir(target), 0777); err != nil {
+		return err
+	}
+	partPath := target + tempDirPrefix + run.stagingID + ".part"
+	out, err := os.Create(partPath)
+	if err != nil {
+		return err
+	}
+	var total int64
+	for i := range run.segs {
+		data, err := os.ReadFile(segmentPath(run.tempDir, int64(i)))
+		if err != nil {
+			out.Close()
+			os.Remove(partPath)
+			return fmt.Errorf("read segment %d failed: %w", i, err)
+		}
+		if _, err := out.Write(data); err != nil {
+			out.Close()
+			os.Remove(partPath)
+			return err
+		}
+		total += int64(len(data))
+	}
+	if err := out.Close(); err != nil {
+		os.Remove(partPath)
+		return err
+	}
+	// Remove-then-rename keeps this idempotent: if a previous merge already
+	// renamed its output before a crash lost the bookkeeping, re-merging
+	// must still succeed.
+	if err := os.Remove(target); err != nil && !os.IsNotExist(err) {
+		os.Remove(partPath)
+		return err
+	}
+	if err := os.Rename(partPath, target); err != nil {
+		os.Remove(partPath)
+		return err
+	}
+	run.downloaded.Store(total)
+	return nil
+}
+
+func storeSegment(run *hlsRun, idx int64, data []byte) error {
+	partPath := segmentPath(run.tempDir, idx) + ".part"
+	if err := os.WriteFile(partPath, data, 0666); err != nil {
+		return err
+	}
+	if err := os.Rename(partPath, segmentPath(run.tempDir, idx)); err != nil {
+		return err
+	}
+	run.journalMu.Lock()
+	defer run.journalMu.Unlock()
+	run.journal[idx] = int64(len(data))
+	return saveJournal(run)
+}
+
+func segmentPath(tempDir string, idx int64) string {
+	return filepath.Join(tempDir, "seg-"+strconv.FormatInt(idx, 10))
+}
+
+// resolveStagingDirLocked returns the staging folder of the current plan,
+// deriving and pinning it on first use so later output renames or moves do
+// not orphan the staged segments. It lives next to the task output, which is
+// exactly opts.Path for a single-file task. Must be called with f.mu held.
+func (f *Fetcher) resolveStagingDirLocked() string {
+	if f.state.StagingDir == "" {
+		if f.state.StagingID == "" {
+			// Legacy state (or a hand-crafted plan): migrate to a fresh task
+			// owned identity. The old URL-hash folder is deliberately not
+			// reused: its contents cannot be proven to belong to this plan,
+			// and sharing it with another same-URL task is exactly the bug
+			// being fixed. It is left behind as orphaned temp data.
+			f.state.StagingID = randomStagingID()
+		}
+		dir := ""
+		if f.meta.Opts != nil {
+			dir = f.meta.Opts.Path
+		}
+		f.state.StagingDir = filepath.Join(dir, tempDirPrefix+f.state.StagingID)
+	}
+	return f.state.StagingDir
+}
+
+// prefetchSize probes segment Content-Length via HEAD. Any failure resets all
+// sizes to zero: a partial size estimate would corrupt progress reporting.
+func (f *Fetcher) prefetchSize(segments []*Segment) {
+	var need []*Segment
+	for _, seg := range segments {
+		if seg.Size <= 0 {
+			need = append(need, seg)
+		}
+	}
+	if len(need) == 0 || len(need) > maxPrefetchSizeSegments {
+		return
+	}
+
+	workerCount := min(f.config.SegmentConnections, 8)
+	var failed atomic.Bool
+	queue := make(chan *Segment)
+	var wg sync.WaitGroup
+	for i := 0; i < workerCount; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for seg := range queue {
+				ctx, cancel := context.WithTimeout(context.Background(), f.timeout())
+				seg.Size = f.headContentLength(ctx, seg.URI)
+				cancel()
+				if seg.Size <= 0 {
+					failed.Store(true)
+				}
+			}
+		}()
+	}
+	for _, seg := range need {
+		queue <- seg
+	}
+	close(queue)
+	wg.Wait()
+	if failed.Load() {
+		for _, seg := range segments {
+			seg.Size = 0
+		}
+	}
+}
+
+func (f *Fetcher) headContentLength(ctx context.Context, u string) int64 {
+	req, err := buildRequest(ctx, f.extra, http.MethodHead, u, nil, nil)
+	if err != nil {
+		return 0
+	}
+	resp, err := f.client.Do(req)
+	if err != nil {
+		return 0
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return 0
+	}
+	return resp.ContentLength
+}
+
+func (f *Fetcher) fetchText(ctx context.Context, method, u string) (string, string, error) {
+	resp, err := f.do(ctx, f.client, f.extra, method, u, nil)
+	if err != nil {
+		return "", "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return "", "", fmt.Errorf("unexpected status %d for %s", resp.StatusCode, u)
+	}
+	data, err := io.ReadAll(io.LimitReader(&stallReader{rc: resp.Body, timeout: f.timeout()}, maxPlaylistSize))
+	if err != nil {
+		return "", "", err
+	}
+	return string(data), resp.Request.URL.String(), nil
+}
+
+func (f *Fetcher) do(ctx context.Context, client *http.Client, extra *ReqExtra, method, u string, byterange *ByteRange) (*http.Response, error) {
+	if method == "" {
+		method = http.MethodGet
+	}
+	req, err := buildRequest(ctx, extra, method, u, nil, byterange)
+	if err != nil {
+		return nil, err
+	}
+	return client.Do(req)
+}
+
+func (f *Fetcher) playlistMethod() string {
+	if f.extra != nil && f.extra.Method != "" {
+		return f.extra.Method
+	}
+	return http.MethodGet
+}
+
+// planTotalSize sums the known segment sizes. It returns 0 unless every
+// segment is unencrypted with a known size: ciphertext lengths overstate the
+// final output (CBC padding is removed on decrypt), and partial estimates
+// would make progress stall below 100%. For indeterminate plans the engine
+// backfills Res.Size from Progress().TotalDownloaded() when the task
+// completes (downloader.go watch).
+func planTotalSize(segments []*Segment) int64 {
+	var total int64
+	for _, seg := range segments {
+		if seg.Key != nil {
+			return 0
+		}
+		if seg.Size <= 0 {
+			return 0
+		}
+		total += seg.Size
+	}
+	return total
+}

internal/protocol/hls/fetcher_manager.go

@@ -0,0 +1,100 @@
+package hls
+
+import (
+	"net/url"
+	"path"
+	"strings"
+
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+)
+
+type FetcherManager struct {
+}
+
+func (fm *FetcherManager) Name() string {
+	return "hls"
+}
+
+// Filters registers the .m3u8 extension. The manager must be registered BEFORE
+// the http manager in the downloader config: protocol routing picks the first
+// manager whose filter matches, and the http filter claims every http(s) URL.
+func (fm *FetcherManager) Filters() []*fetcher.SchemeFilter {
+	return []*fetcher.SchemeFilter{
+		{
+			Type:    fetcher.FilterTypeFile,
+			Pattern: "M3U8",
+		},
+	}
+}
+
+func (fm *FetcherManager) Build() fetcher.Fetcher {
+	return &Fetcher{}
+}
+
+func (fm *FetcherManager) ParseName(u string) string {
+	parsed, err := url.Parse(u)
+	if err != nil {
+		return ""
+	}
+	name := path.Base(parsed.Path)
+	name = strings.TrimSuffix(name, path.Ext(name))
+	if name == "" || name == "/" || name == "." {
+		name = parsed.Hostname()
+	}
+	return name
+}
+
+func (fm *FetcherManager) AutoRename() bool {
+	return true
+}
+
+func (fm *FetcherManager) DefaultConfig() any {
+	return &config{
+		SegmentConnections:    defaultSegmentConnections,
+		MaxRetries:            defaultMaxRetries,
+		TimeoutSeconds:        defaultTimeoutSeconds,
+		PrefetchContentLength: true,
+	}
+}
+
+func (fm *FetcherManager) Store(f fetcher.Fetcher) (data any, err error) {
+	_f := f.(*Fetcher)
+	_f.mu.Lock()
+	defer _f.mu.Unlock()
+	if _f.state == nil {
+		return nil, nil
+	}
+	// The engine's periodic checkpoint calls Store without holding the task
+	// lock and serializes the returned value afterwards, while Resolve/Patch/
+	// Start mutate the live state under the fetcher mutex: return a snapshot
+	// copy taken under that mutex, mirroring the HTTP protocol's Store.
+	return cloneState(_f.state), nil
+}
+
+func cloneState(state *fetcherState) *fetcherState {
+	cloned := *state
+	cloned.Segments = make([]*Segment, len(state.Segments))
+	for i, seg := range state.Segments {
+		s := *seg
+		cloned.Segments[i] = &s
+	}
+	return &cloned
+}
+
+func (fm *FetcherManager) Restore() (v any, f func(meta *fetcher.FetcherMeta, v any) fetcher.Fetcher) {
+	return &fetcherState{}, func(meta *fetcher.FetcherMeta, v any) fetcher.Fetcher {
+		fb := &FetcherManager{}
+		restored := fb.Build().(*Fetcher)
+		restored.meta = meta
+		if state, ok := v.(*fetcherState); ok && state.MediaURL != "" {
+			restored.state = state
+		}
+		// Setup is invoked by the engine (restoreFetcher) after this builder
+		// returns; ReqExtra parsing happens there as well.
+		return restored
+	}
+}
+
+func (fm *FetcherManager) Close() error {
+	return nil
+}

internal/protocol/hls/fetcher_test.go

@@ -0,0 +1,865 @@
+package hls
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/controller"
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+	"github.com/GopeedLab/gopeed/pkg/base"
+)
+
+func pkcs7PadForTest(data []byte, blockSize int) []byte {
+	pad := blockSize - len(data)%blockSize
+	return append(data, bytes.Repeat([]byte{byte(pad)}, pad)...)
+}
+
+func encryptSegment(plain, key, iv []byte) []byte {
+	padded := pkcs7PadForTest(plain, aes.BlockSize)
+	block, _ := aes.NewCipher(key)
+	encrypted := make([]byte, len(padded))
+	cipher.NewCBCEncrypter(block, iv).CryptBlocks(encrypted, padded)
+	return encrypted
+}
+
+// serveContentWithReferer is a helper handler that enforces an optional
+// Referer requirement and reports request counts.
+type cdnHandler struct {
+	mux            *http.ServeMux
+	requireReferer string
+	requests       atomic.Int64
+}
+
+func (h *cdnHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	h.requests.Add(1)
+	if h.requireReferer != "" && r.Header.Get("Referer") != h.requireReferer {
+		w.WriteHeader(http.StatusForbidden)
+		return
+	}
+	h.mux.ServeHTTP(w, r)
+}
+
+func newTestFetcher(t *testing.T, cfg config) *Fetcher {
+	t.Helper()
+	fm := &FetcherManager{}
+	f := fm.Build().(*Fetcher)
+	ctl := controller.NewController()
+	ctl.GetConfig = func(v any) {
+		if c, ok := v.(*config); ok {
+			*c = cfg
+		}
+	}
+	f.Setup(ctl)
+	return f
+}
+
+func testConfig() config {
+	return config{
+		SegmentConnections:    4,
+		MaxRetries:            2,
+		TimeoutSeconds:        5,
+		PrefetchContentLength: true,
+	}
+}
+
+func mustResolve(t *testing.T, f *Fetcher, playlistURL, referer string) {
+	t.Helper()
+	req := &base.Request{URL: playlistURL}
+	if referer != "" {
+		req.Extra = &ReqExtra{Header: map[string]string{"Referer": referer}}
+	}
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(req); err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+}
+
+func mustRun(t *testing.T, f *Fetcher) {
+	t.Helper()
+	if err := f.Start(); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("wait: %v", err)
+	}
+}
+
+func statsOf(t *testing.T, f *Fetcher) Stats {
+	t.Helper()
+	s, ok := f.Stats().Snapshot.(*Stats)
+	if !ok {
+		t.Fatalf("unexpected stats snapshot type %T", f.Stats().Snapshot)
+	}
+	return *s
+}
+
+func readOutput(t *testing.T, f *Fetcher) []byte {
+	t.Helper()
+	data, err := os.ReadFile(f.meta.SingleFilepath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return data
+}
+
+func TestFetcherE2E_MasterTS(t *testing.T) {
+	seg := func(i int) []byte {
+		return []byte(fmt.Sprintf("SEGMENT-%02d-PAYLOAD", i))
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/master.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("#EXTM3U\n" +
+			"#EXT-X-STREAM-INF:BANDWIDTH=800000\nv1/index.m3u8\n" +
+			"#EXT-X-STREAM-INF:BANDWIDTH=2000000\nv2/index.m3u8\n"))
+	})
+	mux.HandleFunc("/v1/index.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("#EXTM3U\n#EXTINF:4,\nlow-0.ts\n#EXT-X-ENDLIST\n"))
+	})
+	mux.HandleFunc("/v2/index.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		var b strings.Builder
+		b.WriteString("#EXTM3U\n")
+		for i := 0; i < 5; i++ {
+			b.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+		}
+		b.WriteString("#EXT-X-ENDLIST\n")
+		w.Write([]byte(b.String()))
+	})
+	for i := 0; i < 5; i++ {
+		content := seg(i)
+		path := "/v2/seg-" + strconv.Itoa(i) + ".ts"
+		mux.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Length", strconv.Itoa(len(content)))
+			w.Write(content)
+		})
+	}
+	server := httptest.NewServer(&cdnHandler{mux: mux})
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	mustResolve(t, f, server.URL+"/master.m3u8", "")
+	// Master resolution picked the 2000000 variant.
+	if f.state.MediaURL != server.URL+"/v2/index.m3u8" {
+		t.Fatalf("wrong variant picked: %s", f.state.MediaURL)
+	}
+	// HEAD prefetch should have computed the exact total size.
+	if f.meta.Res.Size != int64(5*len(seg(0))) {
+		t.Fatalf("prefetched size wrong: %d", f.meta.Res.Size)
+	}
+	mustRun(t, f)
+
+	var want []byte
+	for i := 0; i < 5; i++ {
+		want = append(want, seg(i)...)
+	}
+	got := readOutput(t, f)
+	if !bytes.Equal(got, want) {
+		t.Errorf("merged output mismatch: %q", got)
+	}
+	// The staging folder must be cleaned up after a successful merge; only
+	// the output file remains in the task directory.
+	if entries, _ := os.ReadDir(filepath.Dir(f.meta.SingleFilepath())); len(entries) != 1 {
+		for _, e := range entries {
+			t.Logf("leftover entry: %s", e.Name())
+		}
+		t.Errorf("staging dir should be cleaned up after merge")
+	}
+	if f.meta.Res.Size != int64(len(want)) {
+		t.Errorf("final size wrong: %d", f.meta.Res.Size)
+	}
+}
+
+func TestFetcherE2E_RefererEnforced(t *testing.T) {
+	page := "https://player.example.com/watch/123"
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	segments := make(map[string][]byte)
+	for i := 0; i < 3; i++ {
+		name := fmt.Sprintf("seg-%d.ts", i)
+		segments["/"+name] = []byte(fmt.Sprintf("DATA-%d", i))
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\n%s\n", name))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	for path, content := range segments {
+		c := content
+		mux.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
+			w.Write(c)
+		})
+	}
+	server := httptest.NewServer(&cdnHandler{mux: mux, requireReferer: page})
+	defer server.Close()
+
+	// Without Referer the resolve itself must fail (403 on the playlist).
+	blocked := newTestFetcher(t, testConfig())
+	req := &base.Request{URL: server.URL + "/video.m3u8"}
+	blocked.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := blocked.Resolve(req); err == nil {
+		t.Fatal("resolve without Referer should fail")
+	}
+
+	// With the Referer set through the task extra headers it must succeed.
+	allowed := newTestFetcher(t, testConfig())
+	allowedReq := &base.Request{
+		URL:   server.URL + "/video.m3u8",
+		Extra: &ReqExtra{Header: map[string]string{"Referer": page}},
+	}
+	allowed.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := allowed.Resolve(allowedReq); err != nil {
+		t.Fatal(err)
+	}
+	mustRun(t, allowed)
+	want := []byte("DATA-0DATA-1DATA-2")
+	if !bytes.Equal(readOutput(t, allowed), want) {
+		t.Error("output mismatch with Referer download")
+	}
+}
+
+func TestFetcherE2E_AES128KeyRotation(t *testing.T) {
+	key1 := []byte("0123456789abcdef")
+	key2 := []byte("fedcba9876543210")
+	iv1 := []byte("aaaaaaaaaaaaaaaa")
+	plain1 := []byte("ENCRYPTED-SEGMENT-ONE!!") // padded on encrypt
+	plain2 := []byte("ENCRYPTED-SEGMENT-TWO!!")
+	// seg-2 has no explicit IV: derived from media sequence 1.
+	enc1 := encryptSegment(plain1, key1, iv1)
+	enc2 := encryptSegment(plain2, key2, sequenceIV(1))
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("#EXTM3U\n" +
+			"#EXT-X-MEDIA-SEQUENCE:0\n" +
+			"#EXT-X-KEY:METHOD=AES-128,URI=\"key-1.bin\",IV=0x" + hexEncode(iv1) + "\n" +
+			"#EXTINF:5,\nseg-1.ts\n" +
+			"#EXT-X-KEY:METHOD=AES-128,URI=\"key-2.bin\"\n" +
+			"#EXTINF:5,\nseg-2.ts\n" +
+			"#EXT-X-ENDLIST\n"))
+	})
+	mux.HandleFunc("/key-1.bin", func(w http.ResponseWriter, r *http.Request) {
+		w.Write(key1)
+	})
+	mux.HandleFunc("/key-2.bin", func(w http.ResponseWriter, r *http.Request) {
+		w.Write(key2)
+	})
+	mux.HandleFunc("/seg-1.ts", func(w http.ResponseWriter, r *http.Request) {
+		w.Write(enc1)
+	})
+	mux.HandleFunc("/seg-2.ts", func(w http.ResponseWriter, r *http.Request) {
+		w.Write(enc2)
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	mustResolve(t, f, server.URL+"/video.m3u8", "")
+	// Ciphertext sizes overstate the final output after decryption, so an
+	// encrypted plan must report an indeterminate size.
+	if f.meta.Res.Size != 0 {
+		t.Errorf("encrypted plan should report size 0, got %d", f.meta.Res.Size)
+	}
+	mustRun(t, f)
+
+	want := append(append([]byte{}, plain1...), plain2...)
+	if !bytes.Equal(readOutput(t, f), want) {
+		t.Errorf("decrypted output mismatch: %q", readOutput(t, f))
+	}
+}
+
+func TestFetcherE2E_ByteRange(t *testing.T) {
+	data := []byte("0123456789ABCDEFGHIJ") // 20 bytes
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("#EXTM3U\n" +
+			"#EXT-X-BYTERANGE:10@0\nblob.bin\n" +
+			"#EXT-X-BYTERANGE:10\nblob.bin\n" +
+			"#EXT-X-ENDLIST\n"))
+	})
+	mux.HandleFunc("/blob.bin", func(w http.ResponseWriter, r *http.Request) {
+		rng := r.Header.Get("Range")
+		if rng == "" {
+			w.Write(data)
+			return
+		}
+		// bytes=start-end
+		var start, end int
+		fmt.Sscanf(rng, "bytes=%d-%d", &start, &end)
+		w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, end, len(data)))
+		w.WriteHeader(http.StatusPartialContent)
+		w.Write(data[start : end+1])
+	})
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	mustResolve(t, f, server.URL+"/video.m3u8", "")
+	if f.meta.Res.Size != 20 {
+		t.Fatalf("byterange sizes should be known from the playlist, got %d", f.meta.Res.Size)
+	}
+	mustRun(t, f)
+	if !bytes.Equal(readOutput(t, f), data) {
+		t.Errorf("byterange merge mismatch: %q", readOutput(t, f))
+	}
+}
+
+func TestFetcherE2E_PauseResume(t *testing.T) {
+	const total = 8
+	var served atomic.Int64
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		var b strings.Builder
+		b.WriteString("#EXTM3U\n")
+		for i := 0; i < total; i++ {
+			b.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+		}
+		b.WriteString("#EXT-X-ENDLIST\n")
+		w.Write([]byte(b.String()))
+	})
+	segments := make(map[int][]byte)
+	for i := 0; i < total; i++ {
+		segments[i] = []byte(fmt.Sprintf("SLOW-SEGMENT-%02d", i))
+	}
+	for i := 0; i < total; i++ {
+		idx := i
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", i), func(w http.ResponseWriter, r *http.Request) {
+			time.Sleep(150 * time.Millisecond)
+			served.Add(1)
+			w.Write(segments[idx])
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	cfg := testConfig()
+	cfg.SegmentConnections = 2
+	cfg.PrefetchContentLength = false
+	f := newTestFetcher(t, cfg)
+	mustResolve(t, f, server.URL+"/video.m3u8", "")
+
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	// Let a couple of segments finish, then pause.
+	time.Sleep(400 * time.Millisecond)
+	if err := f.Pause(); err != nil {
+		t.Fatal(err)
+	}
+	doneBefore := statsOf(t, f).SegmentsDone
+	if doneBefore == 0 {
+		t.Fatal("expected some segments to complete before pause")
+	}
+	if doneBefore == total {
+		t.Fatal("all segments finished before pause, test is not exercising resume")
+	}
+
+	// Resume must finish the rest and produce the full output.
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	var want []byte
+	for i := 0; i < total; i++ {
+		want = append(want, segments[i]...)
+	}
+	if !bytes.Equal(readOutput(t, f), want) {
+		t.Errorf("resumed output mismatch: %q", readOutput(t, f))
+	}
+}
+
+func TestFetcherE2E_StoreRestoreResume(t *testing.T) {
+	const total = 6
+	var served atomic.Int64
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		var b strings.Builder
+		b.WriteString("#EXTM3U\n")
+		for i := 0; i < total; i++ {
+			b.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+		}
+		b.WriteString("#EXT-X-ENDLIST\n")
+		w.Write([]byte(b.String()))
+	})
+	segments := make(map[int][]byte)
+	for i := 0; i < total; i++ {
+		segments[i] = []byte(fmt.Sprintf("RESTORE-SEGMENT-%02d", i))
+	}
+	for i := 0; i < total; i++ {
+		idx := i
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", i), func(w http.ResponseWriter, r *http.Request) {
+			time.Sleep(120 * time.Millisecond)
+			served.Add(1)
+			w.Write(segments[idx])
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	cfg := testConfig()
+	cfg.SegmentConnections = 2
+	cfg.PrefetchContentLength = false
+
+	f := newTestFetcher(t, cfg)
+	mustResolve(t, f, server.URL+"/video.m3u8", "")
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	time.Sleep(350 * time.Millisecond)
+	if err := f.Pause(); err != nil {
+		t.Fatal(err)
+	}
+	doneBefore := statsOf(t, f).SegmentsDone
+	if doneBefore == 0 {
+		t.Fatal("expected some segments to finish before simulated restart")
+	}
+
+	// Simulate an app restart: persist, then restore into a fresh fetcher.
+	fm := &FetcherManager{}
+	state, err := fm.Store(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if state == nil {
+		t.Fatal("state should be persisted")
+	}
+	ctl := controller.NewController()
+	ctl.GetConfig = func(v any) {
+		if c, ok := v.(*config); ok {
+			*c = cfg
+		}
+	}
+	holder := fm.Build().(*Fetcher)
+	holder.Setup(ctl)
+	holder.meta = &fetcher.FetcherMeta{
+		Req:  f.meta.Req,
+		Opts: f.meta.Opts,
+		Res:  f.meta.Res,
+	}
+	_, builder := fm.Restore()
+	rf := builder(holder.meta, state).(*Fetcher)
+	// The engine calls Setup on the builder result (restoreFetcher).
+	rf.Setup(ctl)
+	if rf.state == nil || len(rf.state.Segments) != total {
+		t.Fatal("restored state missing segment plan")
+	}
+
+	if err := rf.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := rf.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	if done := statsOf(t, rf).SegmentsDone; done != total {
+		t.Errorf("want %d done, got %d", total, done)
+	}
+	var want []byte
+	for i := 0; i < total; i++ {
+		want = append(want, segments[i]...)
+	}
+	if !bytes.Equal(readOutput(t, rf), want) {
+		t.Errorf("restored output mismatch: %q", readOutput(t, rf))
+	}
+}
+
+func hexEncode(b []byte) string {
+	const digits = "0123456789abcdef"
+	out := make([]byte, 0, len(b)*2)
+	for _, v := range b {
+		out = append(out, digits[v>>4], digits[v&0x0f])
+	}
+	return string(out)
+}
+
+// restoreLikeEngine round-trips the persisted state and the task meta through
+// JSON the way the engine storage does, then builds a fresh fetcher. This is
+// the path that historically lost the request extra headers.
+func restoreLikeEngine(t *testing.T, f *Fetcher, cfg config) *Fetcher {
+	t.Helper()
+	fm := &FetcherManager{}
+	stateAny, err := fm.Store(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rawState, err := json.Marshal(stateAny)
+	if err != nil {
+		t.Fatal(err)
+	}
+	storedState := &fetcherState{}
+	if err := json.Unmarshal(rawState, storedState); err != nil {
+		t.Fatal(err)
+	}
+	rawMeta, err := json.Marshal(f.meta)
+	if err != nil {
+		t.Fatal(err)
+	}
+	restoredMeta := &fetcher.FetcherMeta{}
+	if err := json.Unmarshal(rawMeta, restoredMeta); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := restoredMeta.Req.Extra.(*ReqExtra); ok {
+		t.Fatal("storage round trip should yield a map-shaped extra, like the engine")
+	}
+	ctl := controller.NewController()
+	ctl.GetConfig = func(v any) {
+		if c, ok := v.(*config); ok {
+			*c = cfg
+		}
+	}
+	_, builder := fm.Restore()
+	rf := builder(restoredMeta, storedState).(*Fetcher)
+	// The engine calls Setup on the builder result (restoreFetcher).
+	rf.Setup(ctl)
+	return rf
+}
+
+func TestFetcherE2E_StoreRestoreAuthenticated(t *testing.T) {
+	const total = 4
+	page := "https://player.example.com/watch/42"
+	var served atomic.Int64
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < total; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	segments := make(map[int][]byte)
+	for i := 0; i < total; i++ {
+		segments[i] = []byte(fmt.Sprintf("AUTH-SEGMENT-%02d", i))
+		idx := i
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", idx), func(w http.ResponseWriter, r *http.Request) {
+			time.Sleep(80 * time.Millisecond)
+			served.Add(1)
+			w.Write(segments[idx])
+		})
+	}
+	server := httptest.NewServer(&cdnHandler{mux: mux, requireReferer: page})
+	defer server.Close()
+
+	cfg := testConfig()
+	cfg.SegmentConnections = 2
+	cfg.PrefetchContentLength = false
+
+	f := newTestFetcher(t, cfg)
+	req := &base.Request{
+		URL:   server.URL + "/video.m3u8",
+		Extra: &ReqExtra{Header: map[string]string{"Referer": page}},
+	}
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(req); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	time.Sleep(150 * time.Millisecond)
+	if err := f.Pause(); err != nil {
+		t.Fatal(err)
+	}
+
+	rf := restoreLikeEngine(t, f, cfg)
+	if rf.extra == nil || rf.extra.Header["Referer"] != page {
+		t.Fatalf("restored fetcher lost the request extra headers: %+v", rf.extra)
+	}
+	if err := rf.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := rf.Wait(); err != nil {
+		t.Fatalf("resumed download failed (request headers lost?): %v", err)
+	}
+	var want []byte
+	for i := 0; i < total; i++ {
+		want = append(want, segments[i]...)
+	}
+	if !bytes.Equal(readOutput(t, rf), want) {
+		t.Errorf("restored output mismatch: %q", readOutput(t, rf))
+	}
+}
+
+func TestFetcherE2E_PatchPartialUpdate(t *testing.T) {
+	page := "https://player.example.com/watch/7"
+	var requiredReferer atomic.Value // string
+	requiredReferer.Store(page)
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	segments := make(map[string][]byte)
+	for i := 0; i < 3; i++ {
+		segments[fmt.Sprintf("/s%d.ts", i)] = []byte(fmt.Sprintf("PATCH-%d", i))
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\ns%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	for path, content := range segments {
+		c := content
+		mux.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
+			w.Write(c)
+		})
+	}
+	// The Referer requirement can be flipped mid-test to prove that a patched
+	// header is actually sent by the next run.
+	dyn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if want, _ := requiredReferer.Load().(string); want != "" && r.Header.Get("Referer") != want {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		mux.ServeHTTP(w, r)
+	})
+	server := httptest.NewServer(dyn)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	req := &base.Request{
+		URL:   server.URL + "/video.m3u8",
+		Extra: &ReqExtra{Header: map[string]string{"Referer": page}},
+	}
+	opts := &base.Options{Path: t.TempDir()}
+	f.Meta().Opts = opts
+	if err := f.Resolve(req); err != nil {
+		t.Fatal(err)
+	}
+
+	// A nil/nil patch must be a no-op, not a panic.
+	if err := f.Patch(nil, nil); err != nil {
+		t.Fatalf("nil patch should be accepted: %v", err)
+	}
+
+	// Header-only patch: the resolved plan and output options are retained
+	// while the new header takes effect on the next run.
+	newReferer := "https://player.example.com/watch/9"
+	if err := f.Patch(&base.Request{
+		URL:   server.URL + "/video.m3u8",
+		Extra: &ReqExtra{Header: map[string]string{"Referer": newReferer}},
+	}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if f.state == nil || f.meta.Res == nil {
+		t.Fatal("header-only patch must keep the resolved plan")
+	}
+	if f.meta.Opts.Path != opts.Path {
+		t.Fatalf("header-only patch must keep the output path: %s", f.meta.Opts.Path)
+	}
+	if f.extra.Header["Referer"] != newReferer {
+		t.Fatalf("patched header not applied: %+v", f.extra.Header)
+	}
+	requiredReferer.Store(newReferer)
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("run with patched header failed: %v", err)
+	}
+	if got := readOutput(t, f); string(got) != "PATCH-0PATCH-1PATCH-2" {
+		t.Errorf("output mismatch after header patch: %q", got)
+	}
+
+	// Options-only patch: renaming the task keeps the resolved plan.
+	if err := f.Patch(nil, &base.Options{Name: "renamed.ts"}); err != nil {
+		t.Fatal(err)
+	}
+	if f.state == nil {
+		t.Fatal("options-only patch must keep the resolved plan")
+	}
+	if f.meta.Opts.Name != "renamed.ts" || f.meta.Opts.Path != opts.Path {
+		t.Fatalf("options patch misapplied: %+v", f.meta.Opts)
+	}
+
+	// URL-only patch: the plan is dropped for a re-resolve but the output
+	// path and renamed file survive.
+	if err := f.Patch(&base.Request{URL: server.URL + "/refreshed.m3u8"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if f.state != nil || f.meta.Res != nil {
+		t.Fatal("URL patch must drop the resolved plan")
+	}
+	if f.meta.Opts.Path != opts.Path || f.meta.Opts.Name != "renamed.ts" {
+		t.Fatal("URL patch must keep the output options")
+	}
+}
+
+func TestFetcherE2E_PatchWhileRunningRejected(t *testing.T) {
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < 6; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	for i := 0; i < 6; i++ {
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", i), func(w http.ResponseWriter, r *http.Request) {
+			time.Sleep(150 * time.Millisecond)
+			w.Write([]byte("X"))
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Patch(&base.Request{URL: server.URL + "/other.m3u8"}, nil); err == nil {
+		t.Fatal("patching a running task must be rejected")
+	}
+	if err := f.Pause(); err != nil {
+		t.Fatal(err)
+	}
+	// After the pause the patch goes through and only then drops the plan.
+	if err := f.Patch(&base.Request{URL: server.URL + "/other.m3u8"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if f.state != nil {
+		t.Fatal("URL patch after pause must drop the plan")
+	}
+}
+
+func TestFetcherE2E_RetryAfterFailure(t *testing.T) {
+	const total = 4
+	var healthy atomic.Bool
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < total; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	segments := make(map[int][]byte)
+	for i := 0; i < total; i++ {
+		segments[i] = []byte(fmt.Sprintf("RETRY-SEGMENT-%02d", i))
+		idx := i
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", idx), func(w http.ResponseWriter, r *http.Request) {
+			if idx == 1 && !healthy.Load() {
+				w.WriteHeader(http.StatusInternalServerError)
+				return
+			}
+			time.Sleep(60 * time.Millisecond)
+			w.Write(segments[idx])
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	cfg := testConfig()
+	cfg.MaxRetries = 0 // fail the run on the first bad segment
+	cfg.PrefetchContentLength = false
+	f := newTestFetcher(t, cfg)
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err == nil {
+		t.Fatal("first run should fail while the segment endpoint is down")
+	}
+	if got := statsOf(t, f).SegmentsFailed; got == 0 {
+		t.Fatal("failed segments should be reported in stats")
+	}
+
+	// Server recovered: a fresh run must succeed and report zero failures.
+	healthy.Store(true)
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("retry run failed: %v", err)
+	}
+	stats := statsOf(t, f)
+	if stats.SegmentsFailed != 0 {
+		t.Errorf("failures must reset per run, got %d", stats.SegmentsFailed)
+	}
+	if stats.SegmentsDone != total {
+		t.Errorf("want %d done, got %d", total, stats.SegmentsDone)
+	}
+	var want []byte
+	for i := 0; i < total; i++ {
+		want = append(want, segments[i]...)
+	}
+	if !bytes.Equal(readOutput(t, f), want) {
+		t.Errorf("retry output mismatch: %q", readOutput(t, f))
+	}
+}
+
+func TestFetcherE2E_StateMissingSelfHeal(t *testing.T) {
+	const total = 3
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < total; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	segments := make(map[int][]byte)
+	for i := 0; i < total; i++ {
+		segments[i] = []byte(fmt.Sprintf("SELFHEAL-%02d", i))
+		idx := i
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", idx), func(w http.ResponseWriter, r *http.Request) {
+			w.Write(segments[idx])
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	// Simulate the crash window where the engine persisted the task with its
+	// resource but the HLS plan was never checkpointed.
+	f.state = nil
+	outputName := f.meta.Res.Files[0].Name
+	if err := f.Start(); err != nil {
+		t.Fatalf("start should self-heal a missing plan: %v", err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("self-healed run failed: %v", err)
+	}
+	if f.state == nil || len(f.state.Segments) != total {
+		t.Fatal("self-heal should rebuild the segment plan")
+	}
+	if f.meta.Res.Files[0].Name != outputName {
+		t.Fatalf("self-heal renamed the output: %s", f.meta.Res.Files[0].Name)
+	}
+	var want []byte
+	for i := 0; i < total; i++ {
+		want = append(want, segments[i]...)
+	}
+	if !bytes.Equal(readOutput(t, f), want) {
+		t.Errorf("self-healed output mismatch: %q", readOutput(t, f))
+	}
+}

internal/protocol/hls/helper.go

@@ -0,0 +1,100 @@
+package hls
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/cookiejar"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/httpclient"
+	"github.com/GopeedLab/gopeed/pkg/base"
+)
+
+const defaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36"
+
+const maxPlaylistSize = 10 << 20 // 10MB, playlists are small text files
+
+func (f *Fetcher) timeout() time.Duration {
+	return time.Duration(f.config.TimeoutSeconds) * time.Second
+}
+
+// buildClient builds an HTTP client honoring the task proxy and TLS settings.
+// The client has no total timeout on purpose: large segments over slow links
+// must not be aborted; body stalls are handled by stallReader instead. It is
+// only called while the fetcher is quiescent (Resolve/Start), never from
+// inside running worker goroutines.
+func (f *Fetcher) buildClient() *http.Client {
+	var proxy *base.RequestProxy
+	skipVerify := false
+	if req := f.meta.Req; req != nil {
+		proxy = req.Proxy
+		skipVerify = req.SkipVerifyCert
+	}
+	jar, _ := cookiejar.New(nil)
+	client, err := httpclient.NewClient(httpclient.Options{
+		Client: httpclient.ClientOptions{
+			Jar: jar,
+		},
+		Transport: httpclient.TransportOptions{
+			DialContext: (&net.Dialer{
+				Timeout: f.timeout(),
+			}).DialContext,
+			Proxy: f.Ctl.GetProxy(proxy),
+			TLSClientConfig: &tls.Config{
+				InsecureSkipVerify: skipVerify,
+			},
+			TLSHandshakeTimeout: f.timeout(),
+		},
+		Impersonation: httpclient.ImpersonationOptions{
+			Mode:    httpclient.ImpersonationAuto,
+			Session: f.impSession,
+		},
+	})
+	if err != nil {
+		panic(fmt.Sprintf("build HTTP client: %v", err))
+	}
+	return client
+}
+
+// buildRequest builds a request with task extra headers, the default user
+// agent and an optional byte range. extra may be nil.
+func buildRequest(ctx context.Context, extra *ReqExtra, method, u string, body io.Reader, byterange *ByteRange) (*http.Request, error) {
+	req, err := http.NewRequestWithContext(ctx, method, u, body)
+	if err != nil {
+		return nil, err
+	}
+	if extra != nil {
+		for key, value := range extra.Header {
+			req.Header.Set(key, value)
+		}
+	}
+	if req.Header.Get("User-Agent") == "" {
+		req.Header.Set("User-Agent", defaultUserAgent)
+	}
+	if byterange != nil {
+		req.Header.Set("Range", fmt.Sprintf("bytes=%d-%d", byterange.Offset, byterange.Offset+byterange.Length-1))
+	}
+	return req, nil
+}
+
+// stallReader aborts reads that see no data for the configured timeout.
+type stallReader struct {
+	rc      io.ReadCloser
+	timeout time.Duration
+}
+
+func (r *stallReader) Read(p []byte) (int, error) {
+	timer := time.AfterFunc(r.timeout, func() {
+		r.rc.Close()
+	})
+	defer timer.Stop()
+	return r.rc.Read(p)
+}
+
+func (r *stallReader) Close() error {
+	return r.rc.Close()
+}

internal/protocol/hls/journal.go

@@ -0,0 +1,112 @@
+package hls
+
+import (
+	"crypto/rand"
+	"crypto/sha1"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+)
+
+// journalFile is the persisted completed-segment ledger. It is bound to the
+// exact download plan: a journal whose fingerprint does not match the current
+// plan is discarded instead of being applied to the wrong segments.
+type journalFile struct {
+	StagingID    string           `json:"stagingID"`
+	PlanHash     string           `json:"planHash"`
+	SegmentCount int              `json:"segmentCount"`
+	Sizes        map[string]int64 `json:"sizes"`
+}
+
+// randomStagingID returns a random identifier used to give every task its own
+// staging folder, stable across app restarts through the persisted state.
+func randomStagingID() string {
+	buf := make([]byte, 6)
+	if _, err := rand.Read(buf); err != nil {
+		// crypto/rand failing is catastrophic anyway; fall back to address
+		// entropy rather than crashing the fetch.
+		return fmt.Sprintf("%x", sha1.Sum([]byte(fmt.Sprintf("%p", buf))))[:12]
+	}
+	return hex.EncodeToString(buf)
+}
+
+// planFingerprint hashes everything that defines the download plan: the media
+// URL, the ordered segments with their sequence numbers, byte ranges, keys
+// and init markers. Two tasks resolve to different fingerprints even when
+// they point at the same playlist URL.
+func planFingerprint(state *fetcherState) string {
+	h := sha1.New()
+	io.WriteString(h, state.MediaURL+"\n")
+	io.WriteString(h, strconv.Itoa(len(state.Segments))+"\n")
+	for _, seg := range state.Segments {
+		fmt.Fprintf(h, "%d|%s|", seg.Sequence, seg.URI)
+		if seg.Byterange != nil {
+			fmt.Fprintf(h, "%d@%d|", seg.Byterange.Offset, seg.Byterange.Length)
+		}
+		if seg.Key != nil {
+			// The IV is part of the plan: same URI with a rotated IV would
+			// silently decrypt to garbage if the journal were reused.
+			fmt.Fprintf(h, "key=%s iv=%x|", seg.Key.URI, seg.Key.IV)
+		}
+		if seg.IsInit {
+			io.WriteString(h, "init|")
+		}
+		io.WriteString(h, "\n")
+	}
+	return hex.EncodeToString(h.Sum(nil))[:16]
+}
+
+// loadJournal reads the journal of a run, discarding anything that cannot be
+// proven to belong to the current plan: foreign or legacy journals, corrupted
+// files, and entries whose recorded size no longer matches the plan.
+func loadJournal(run *hlsRun) error {
+	data, err := os.ReadFile(run.journalPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	var file journalFile
+	if err := json.Unmarshal(data, &file); err != nil {
+		// A broken or legacy journal must not kill a restartable download.
+		return nil
+	}
+	if file.StagingID != run.stagingID || file.PlanHash != run.planHash || file.SegmentCount != len(run.segs) {
+		return nil
+	}
+	for key, size := range file.Sizes {
+		idx, err := strconv.ParseInt(key, 10, 64)
+		if err != nil || idx < 0 || idx >= int64(len(run.segs)) || size <= 0 {
+			continue
+		}
+		run.journal[idx] = size
+	}
+	return nil
+}
+
+// saveJournal atomically rewrites the journal through a temp file + rename so
+// a crash never leaves a half-written ledger behind.
+func saveJournal(run *hlsRun) error {
+	file := journalFile{
+		StagingID:    run.stagingID,
+		PlanHash:     run.planHash,
+		SegmentCount: len(run.segs),
+		Sizes:        make(map[string]int64, len(run.journal)),
+	}
+	for idx, size := range run.journal {
+		file.Sizes[strconv.FormatInt(idx, 10)] = size
+	}
+	data, err := json.Marshal(file)
+	if err != nil {
+		return err
+	}
+	tmp := run.journalPath + ".tmp"
+	if err := os.WriteFile(tmp, data, 0666); err != nil {
+		return err
+	}
+	return os.Rename(tmp, run.journalPath)
+}

internal/protocol/hls/media_validate_test.go

@@ -0,0 +1,300 @@
+package hls
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/GopeedLab/gopeed/pkg/base"
+)
+
+// The validators below check real media structure, not just byte
+// concatenation: TS packets are verified on the 188 byte grid with
+// continuity-counter rules, PAT/PMT presence and PES start codes; fMP4
+// output is verified by walking the ISO-BMFF box hierarchy.
+
+func be32(b []byte) int {
+	return int(b[0])<<24 | int(b[1])<<16 | int(b[2])<<8 | int(b[3])
+}
+
+// validateTS asserts structural validity of a merged MPEG-2 TS stream.
+func validateTS(t *testing.T, data []byte) {
+	t.Helper()
+	if len(data) == 0 || len(data)%188 != 0 {
+		t.Fatalf("TS size %d is not a positive multiple of 188", len(data))
+	}
+	type pidState struct{ cc int }
+	ccByPID := map[int]int{}
+	patSeen, pmtSeen, pesSeen := false, false, false
+	for off := 0; off < len(data); off += 188 {
+		pkt := data[off : off+188]
+		if pkt[0] != 0x47 {
+			t.Fatalf("bad TS sync byte at offset %d", off)
+		}
+		pid := (int(pkt[1]&0x1F) << 8) | int(pkt[2])
+		pusi := pkt[1]&0x40 != 0
+		afc := (pkt[3] >> 4) & 0x3
+		if afc == 0 {
+			continue // reserved
+		}
+		idx := 4
+		if afc&0x2 != 0 { // adaptation field present
+			afLen := int(pkt[4])
+			if afLen > 0 && pkt[5]&0x80 != 0 {
+				// discontinuity_indicator: restart the CC expectation
+				delete(ccByPID, pid)
+			}
+			idx += 1 + afLen
+			if afc == 2 {
+				continue // adaptation only, no payload: no CC rule
+			}
+		}
+		if idx > 188 {
+			t.Fatalf("adaptation field overruns packet at offset %d", off)
+		}
+		if pid == 0x1FFF {
+			continue // null packet
+		}
+		payload := pkt[idx:]
+		if pusi && len(payload) >= 3 && pid != 0 && payload[0] == 0 && payload[1] == 0 && payload[2] == 1 {
+			pesSeen = true
+		}
+		if pid == 0 {
+			if ptr := int(payload[0]); 1+ptr < len(payload) && payload[1+ptr] == 0x00 {
+				patSeen = true // program_association_section table_id
+			}
+		} else if pusi && len(payload) >= 2 && payload[0] == 0 && payload[1] == 0x02 {
+			pmtSeen = true // program_map_section table_id
+		}
+		cc := int(pkt[3] & 0x0F)
+		prev, ok := ccByPID[pid]
+		if !ok {
+			ccByPID[pid] = cc
+			continue
+		}
+		// CC increments by one per payload-bearing packet; a repeated value
+		// models the single legal duplicate packet.
+		if cc != (prev+1)%16 && cc != prev {
+			t.Fatalf("continuity error on PID %d: %d after %d at offset %d", pid, cc, prev, off)
+		}
+		ccByPID[pid] = cc
+	}
+	if !patSeen {
+		t.Error("no PAT found in merged TS")
+	}
+	if !pmtSeen {
+		t.Error("no PMT found in merged TS")
+	}
+	if !pesSeen {
+		t.Error("no PES start code found in merged TS")
+	}
+}
+
+// walkBoxes iterates the top-level ISO-BMFF boxes of data[off:end].
+func walkBoxes(t *testing.T, data []byte, off, end int) []string {
+	t.Helper()
+	var types []string
+	for off+8 <= end {
+		size := be32(data[off:])
+		typ := string(data[off+4 : off+8])
+		if size < 8 || off+size > end {
+			t.Fatalf("invalid box %q at offset %d (size %d)", typ, off, size)
+		}
+		types = append(types, typ)
+		off += size
+	}
+	return types
+}
+
+// validateFMP4 asserts the merged fMP4 output is init section followed by
+// well-formed moof+mdat fragments.
+func validateFMP4(t *testing.T, merged []byte, wantFragments int) {
+	t.Helper()
+	types := walkBoxes(t, merged, 0, len(merged))
+	hasFtyp, hasMoov := false, false
+	fragments := 0
+	expectFragment := false
+	for i, typ := range types {
+		switch typ {
+		case "ftyp":
+			if i != 0 {
+				t.Errorf("ftyp not at stream start")
+			}
+			hasFtyp = true
+		case "moov":
+			if i != 1 {
+				t.Errorf("moov must follow ftyp, found at index %d", i)
+			}
+			hasMoov = true
+		case "styp":
+			expectFragment = true
+		case "moof":
+			if !hasMoov {
+				t.Errorf("fragment before moov")
+			}
+			expectFragment = true
+		case "mdat":
+			if !expectFragment {
+				t.Errorf("mdat outside of a fragment at index %d", i)
+			}
+			expectFragment = false
+			fragments++
+		case "mfra":
+			// optional trailer
+		default:
+			t.Errorf("unexpected top-level box %q", typ)
+		}
+	}
+	if !hasFtyp || !hasMoov {
+		t.Error("merged fMP4 missing ftyp/moov init section")
+	}
+	if fragments != wantFragments {
+		t.Errorf("want %d fragments in merged fMP4, got %d", wantFragments, fragments)
+	}
+}
+
+func mediaFixture(t *testing.T, name string) []byte {
+	t.Helper()
+	data, err := os.ReadFile("testdata/media/" + name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return data
+}
+
+func serveFixtureServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	fs := http.FileServer(http.Dir("testdata/media"))
+	mux.Handle("/", fs)
+	return httptest.NewServer(mux)
+}
+
+func TestHLSRealMedia_TS(t *testing.T) {
+	seg0 := mediaFixture(t, "sample-00.ts")
+	seg1 := mediaFixture(t, "sample-01.ts")
+	playlist := "#EXTM3U\n" +
+		"#EXTINF:0.5,\nsample-00.ts\n" +
+		"#EXTINF:0.5,\nsample-01.ts\n" +
+		"#EXT-X-ENDLIST\n"
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist))
+	})
+	mux.Handle("/", http.FileServer(http.Dir("testdata/media")))
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	got := readOutput(t, f)
+	if !bytes.Equal(got, append(append([]byte{}, seg0...), seg1...)) {
+		t.Fatal("merged TS is not the exact concatenation of the segments")
+	}
+	validateTS(t, got)
+}
+
+func TestHLSRealMedia_FMP4(t *testing.T) {
+	init := mediaFixture(t, "fmp4-init.mp4")
+	frag1 := mediaFixture(t, "fmp4-seg1.m4s")
+	frag2 := mediaFixture(t, "fmp4-seg2.m4s")
+	frag3 := mediaFixture(t, "fmp4-seg3.m4s")
+	playlist := "#EXTM3U\n" +
+		"#EXT-X-MAP:URI=\"fmp4-init.mp4\"\n" +
+		"#EXTINF:0.5,\nfmp4-seg1.m4s\n" +
+		"#EXTINF:0.5,\nfmp4-seg2.m4s\n" +
+		"#EXTINF:0.5,\nfmp4-seg3.m4s\n" +
+		"#EXT-X-ENDLIST\n"
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist))
+	})
+	mux.Handle("/", http.FileServer(http.Dir("testdata/media")))
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	got := readOutput(t, f)
+	want := append(append(append(append([]byte{}, init...), frag1...), frag2...), frag3...)
+	if !bytes.Equal(got, want) {
+		t.Fatal("merged fMP4 is not the exact concatenation of init + fragments")
+	}
+	validateFMP4(t, got, 3)
+}
+
+func TestHLSRealMedia_AES128(t *testing.T) {
+	keys := [][]byte{[]byte("key-A-0123456789"), []byte("key-B-9876543210")}
+	iv := []byte("iv-1337-01234567")
+	plain := [][]byte{mediaFixture(t, "sample-00.ts"), mediaFixture(t, "sample-01.ts")}
+
+	playlist := "#EXTM3U\n" +
+		"#EXT-X-MEDIA-SEQUENCE:0\n" +
+		"#EXT-X-KEY:METHOD=AES-128,URI=\"key-0.bin\",IV=0x" + hexEncode(iv) + "\n" +
+		"#EXTINF:0.5,\nenc-0.ts\n" +
+		"#EXT-X-KEY:METHOD=AES-128,URI=\"key-1.bin\"\n" +
+		"#EXTINF:0.5,\nenc-1.ts\n" +
+		"#EXT-X-ENDLIST\n"
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist))
+	})
+	for i, key := range keys {
+		k := key
+		mux.HandleFunc(fmt.Sprintf("/key-%d.bin", i), func(w http.ResponseWriter, r *http.Request) {
+			w.Write(k)
+		})
+		// Segment 0 has an explicit IV, segment 1 derives it from its media
+		// sequence number (1).
+		enc := encryptSegment(plain[i], k, map[bool][]byte{true: iv, false: sequenceIV(int64(i))}[i == 0])
+		mux.HandleFunc(fmt.Sprintf("/enc-%d.ts", i), func(w http.ResponseWriter, r *http.Request) {
+			w.Write(enc)
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	if f.meta.Res.Size != 0 {
+		t.Errorf("encrypted plan must report indeterminate size, got %d", f.meta.Res.Size)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	got := readOutput(t, f)
+	if !bytes.Equal(got, append(append([]byte{}, plain[0]...), plain[1]...)) {
+		t.Fatal("decrypted output mismatch")
+	}
+	validateTS(t, got)
+	if p := f.Progress(); p.TotalDownloaded() != int64(len(got)) {
+		t.Errorf("final progress %d != merged size %d", p.TotalDownloaded(), len(got))
+	}
+}

internal/protocol/hls/playlist.go

@@ -0,0 +1,479 @@
+package hls
+
+import (
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net/url"
+	"path"
+	"strconv"
+	"strings"
+)
+
+// Variant is one rendition entry of a master playlist.
+type Variant struct {
+	URI          string
+	Bandwidth    int64
+	AvgBandwidth int64
+	Resolution   string
+	Codecs       string
+	Name         string
+	AudioGroup   string // AUDIO attribute: group id of the audio renditions
+}
+
+// MediaRendition is one EXT-X-MEDIA entry of a master playlist. Only the
+// fields needed to detect unsupported track layouts are kept.
+type MediaRendition struct {
+	Type    string
+	GroupID string
+	URI     string
+}
+
+// MasterPlaylist is a parsed master playlist with its rendition groups.
+type MasterPlaylist struct {
+	Variants  []*Variant
+	Rendition map[string][]*MediaRendition // group id -> all EXT-X-MEDIA members
+}
+
+// Key is the decryption key applied to the segments that follow its tag, until
+// the next EXT-X-KEY tag or the end of the playlist.
+type Key struct {
+	Method string
+	URI    string // absolute URI
+	IV     []byte // explicit IV; nil means derive from the media sequence number
+}
+
+// ByteRange is an EXT-X-BYTERANGE sub range of the segment resource.
+type ByteRange struct {
+	Length int64
+	Offset int64
+}
+
+// Segment is one downloadable piece of a media playlist. The init section of
+// an fMP4 stream is represented as a segment with IsInit set.
+type Segment struct {
+	URI       string
+	Sequence  int64 // media sequence number, used to derive the default AES IV
+	Byterange *ByteRange
+	Key       *Key // nil means unencrypted
+	IsInit    bool
+	Gap       bool
+	Duration  float64
+	Size      int64 // exact size in bytes when known (byterange / HEAD probe), 0 when unknown
+}
+
+// Media is a parsed media playlist.
+type Media struct {
+	Segments      []*Segment
+	Version       int
+	Live          bool // no EXT-X-ENDLIST tag
+	IsFMP4        bool // playlist declares an init section via EXT-X-MAP
+	Discontinuity bool // playlist contains EXT-X-DISCONTINUITY
+}
+
+const (
+	keyMethodNone      = "NONE"
+	keyMethodAES128    = "AES-128"
+	keyMethodSampleAES = "SAMPLE-AES"
+)
+
+// IsMasterPlaylist reports whether the content looks like a master playlist.
+func IsMasterPlaylist(content string) bool {
+	return strings.Contains(content, "#EXT-X-STREAM-INF")
+}
+
+func validateM3U8Header(content string) error {
+	for _, line := range strings.Split(content, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if line != "#EXTM3U" {
+			return errors.New("content is not a valid m3u8 playlist")
+		}
+		return nil
+	}
+	return errors.New("empty m3u8 playlist")
+}
+
+// ParseMaster parses a master playlist and returns all variants.
+func ParseMaster(content string, baseURL *url.URL) ([]*Variant, error) {
+	master, err := ParseMasterPlaylist(content, baseURL)
+	if err != nil {
+		return nil, err
+	}
+	return master.Variants, nil
+}
+
+// ParseMasterPlaylist parses a master playlist including its EXT-X-MEDIA
+// rendition groups.
+func ParseMasterPlaylist(content string, baseURL *url.URL) (*MasterPlaylist, error) {
+	if err := validateM3U8Header(content); err != nil {
+		return nil, err
+	}
+	master := &MasterPlaylist{Rendition: make(map[string][]*MediaRendition)}
+	var pending *Variant
+	for _, line := range strings.Split(content, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if strings.HasPrefix(line, "#EXT-X-STREAM-INF:") {
+			attrs := parseAttributes(line[len("#EXT-X-STREAM-INF:"):])
+			pending = &Variant{
+				Bandwidth:    parseInt64(attrs["BANDWIDTH"]),
+				AvgBandwidth: parseInt64(attrs["AVERAGE-BANDWIDTH"]),
+				Resolution:   attrs["RESOLUTION"],
+				Codecs:       unquote(attrs["CODECS"]),
+				Name:         unquote(attrs["NAME"]),
+				AudioGroup:   unquote(attrs["AUDIO"]),
+			}
+			continue
+		}
+		if strings.HasPrefix(line, "#EXT-X-MEDIA:") {
+			attrs := parseAttributes(line[len("#EXT-X-MEDIA:"):])
+			rendition := &MediaRendition{
+				Type:    strings.ToUpper(attrs["TYPE"]),
+				GroupID: unquote(attrs["GROUP-ID"]),
+			}
+			// Only an explicit URI means a separate track; resolving an empty
+			// reference would fabricate one out of the playlist URL.
+			if uri := unquote(attrs["URI"]); uri != "" {
+				rendition.URI = resolveURL(baseURL, uri)
+			}
+			if rendition.GroupID != "" {
+				// Keep every member: a group is unsupported as a whole when
+				// ANY of its members carries its own URI.
+				master.Rendition[rendition.GroupID] = append(master.Rendition[rendition.GroupID], rendition)
+			}
+			continue
+		}
+		if pending != nil {
+			if line[0] != '#' {
+				pending.URI = resolveURL(baseURL, line)
+				master.Variants = append(master.Variants, pending)
+			}
+			pending = nil
+		}
+	}
+	if len(master.Variants) == 0 {
+		return nil, errors.New("master playlist has no variants")
+	}
+	return master, nil
+}
+
+// checkAudioRendition rejects the selected variant when its AUDIO group
+// carries a separate audio track: downloading only the video variant would
+// silently produce a silent file. Groups the variant does not reference are
+// ignored (variants without an AUDIO attribute are assumed self-contained).
+func checkAudioRendition(master *MasterPlaylist, best *Variant) error {
+	if best == nil || best.AudioGroup == "" {
+		return nil
+	}
+	for _, rendition := range master.Rendition[best.AudioGroup] {
+		if rendition == nil || rendition.Type != "AUDIO" || rendition.URI == "" {
+			continue
+		}
+		return fmt.Errorf(
+			"selected variant uses a separate audio rendition (group %q), which is not supported: the merged output would have no audio",
+			best.AudioGroup)
+	}
+	return nil
+}
+
+// PickBestVariant selects the highest-bandwidth variant.
+func PickBestVariant(variants []*Variant) *Variant {
+	var best *Variant
+	for _, v := range variants {
+		if best == nil || v.Bandwidth > best.Bandwidth {
+			best = v
+		}
+	}
+	return best
+}
+
+// ParseMedia parses a media playlist into an ordered segment plan.
+func ParseMedia(content string, baseURL *url.URL) (*Media, error) {
+	if err := validateM3U8Header(content); err != nil {
+		return nil, err
+	}
+
+	media := &Media{Live: true}
+	var currentKey *Key
+	var pendingByterange *ByteRange
+	var pendingGap bool
+	var pendingDuration float64
+	var lastRangeEnd int64
+	var sequence int64
+	var mapIdentity string // normalized identity of the current EXT-X-MAP
+
+	for _, line := range strings.Split(content, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if line[0] != '#' {
+			// Every non-comment line in a media playlist is a segment URI.
+			seg := &Segment{
+				URI:       resolveURL(baseURL, line),
+				Sequence:  sequence,
+				Byterange: pendingByterange,
+				Key:       currentKey,
+				Gap:       pendingGap,
+				Duration:  pendingDuration,
+			}
+			if pendingByterange != nil {
+				// Byterange segments have exact sizes straight from the playlist.
+				seg.Size = pendingByterange.Length
+			}
+			sequence++
+			pendingByterange = nil
+			pendingGap = false
+			pendingDuration = 0
+			media.Segments = append(media.Segments, seg)
+			continue
+		}
+
+		switch {
+		case strings.HasPrefix(line, "#EXTINF:"):
+			value := line[len("#EXTINF:"):]
+			if idx := strings.Index(value, ","); idx >= 0 {
+				value = value[:idx]
+			}
+			pendingDuration = parseFloat(value)
+		case strings.HasPrefix(line, "#EXT-X-KEY:"):
+			key, err := parseKey(line[len("#EXT-X-KEY:"):], baseURL)
+			if err != nil {
+				return nil, err
+			}
+			currentKey = key
+		case strings.HasPrefix(line, "#EXT-X-MAP:"):
+			attrs := parseAttributes(line[len("#EXT-X-MAP:"):])
+			uriAttr := unquote(attrs["URI"])
+			if uriAttr == "" {
+				return nil, errors.New("EXT-X-MAP without URI is not supported")
+			}
+			resolved := resolveURL(baseURL, uriAttr)
+			// The init section identity covers every attribute, not just the
+			// URI: a repeated tag with a different BYTERANGE addresses
+			// different bytes and changes the init section. NUL keeps the
+			// two parts unambiguously separated.
+			identity := resolved + "\x00" + attrs["BYTERANGE"]
+			if mapIdentity != "" {
+				if mapIdentity != identity {
+					return nil, errors.New("changing init sections are not supported")
+				}
+				media.IsFMP4 = true
+				continue
+			}
+			mapIdentity = identity
+			init := &Segment{
+				URI:      resolved,
+				Sequence: sequence,
+				IsInit:   true,
+				Key:      currentKey,
+			}
+			if attrs["BYTERANGE"] != "" {
+				init.Byterange = parseByteRange(attrs["BYTERANGE"], 0)
+				if init.Byterange == nil {
+					return nil, fmt.Errorf("invalid EXT-X-MAP BYTERANGE: %s", attrs["BYTERANGE"])
+				}
+			}
+			if init.Key != nil && init.Key.IV == nil {
+				// RFC 8216 only defines sequence-derived IVs for media
+				// segments; guessing one for the init section produces
+				// corrupt output, so require the playlist to be explicit.
+				return nil, errors.New("encrypted EXT-X-MAP without an explicit IV is not supported")
+			}
+			// The init section is prepended to the segment plan, it takes
+			// the media sequence number of the playlist for IV derivation.
+			media.Segments = append(media.Segments, init)
+			media.IsFMP4 = true
+		case strings.HasPrefix(line, "#EXT-X-BYTERANGE:"):
+			pendingByterange = parseByteRange(line[len("#EXT-X-BYTERANGE:"):], lastRangeEnd)
+			if pendingByterange == nil {
+				return nil, fmt.Errorf("invalid EXT-X-BYTERANGE: %s", line)
+			}
+		case line == "#EXT-X-GAP":
+			pendingGap = true
+		case line == "#EXT-X-DISCONTINUITY":
+			media.Discontinuity = true
+		case line == "#EXT-X-ENDLIST":
+			media.Live = false
+		case strings.HasPrefix(line, "#EXT-X-MEDIA-SEQUENCE:"):
+			sequence = parseInt64(line[len("#EXT-X-MEDIA-SEQUENCE:"):])
+		case strings.HasPrefix(line, "#EXT-X-VERSION:"):
+			media.Version = int(parseInt64(line[len("#EXT-X-VERSION:"):]))
+		}
+
+		if pendingByterange != nil {
+			// Non-segment tags between BYTERANGE and its URI must not reset the
+			// running offset, so it is tracked here after each parse.
+			lastRangeEnd = pendingByterange.Offset + pendingByterange.Length
+		}
+	}
+
+	if len(media.Segments) == 0 {
+		return nil, errors.New("media playlist has no segments")
+	}
+	return media, nil
+}
+
+// validateSupported rejects playlist features the byte-concatenation merge
+// cannot reproduce faithfully. Skipping such features silently would report
+// success while producing a broken file.
+func validateSupported(media *Media) error {
+	if media.Live {
+		return errors.New("live streams are not supported yet")
+	}
+	if media.Discontinuity {
+		return errors.New("EXT-X-DISCONTINUITY is not supported: the merged output would have a broken timeline")
+	}
+	for _, seg := range media.Segments {
+		if seg.Gap {
+			return errors.New("EXT-X-GAP is not supported: the missing segment would leave a hole in the merged output")
+		}
+	}
+	return nil
+}
+
+func parseKey(attrs string, baseURL *url.URL) (*Key, error) {
+	parsed := parseAttributes(attrs)
+	switch method := parsed["METHOD"]; method {
+	case keyMethodNone:
+		return nil, nil
+	case keyMethodAES128:
+		uri := unquote(parsed["URI"])
+		if uri == "" {
+			return nil, errors.New("AES-128 EXT-X-KEY without URI")
+		}
+		if format := unquote(parsed["KEYFORMAT"]); format != "" && format != "identity" {
+			return nil, fmt.Errorf("unsupported EXT-X-KEY KEYFORMAT: %s", format)
+		}
+		key := &Key{Method: keyMethodAES128, URI: resolveURL(baseURL, uri)}
+		if iv, ok := parsed["IV"]; ok {
+			value := strings.TrimPrefix(strings.ToLower(iv), "0x")
+			decoded, err := hex.DecodeString(value)
+			if err != nil || len(decoded) != 16 {
+				return nil, fmt.Errorf("invalid EXT-X-KEY IV: %s", iv)
+			}
+			key.IV = decoded
+		}
+		return key, nil
+	case keyMethodSampleAES:
+		return nil, errors.New("SAMPLE-AES encryption is not supported")
+	default:
+		return nil, fmt.Errorf("unsupported encryption method: %s", method)
+	}
+}
+
+func parseByteRange(value string, defaultOffset int64) *ByteRange {
+	lengthPart := value
+	offsetPart := ""
+	if idx := strings.Index(value, "@"); idx >= 0 {
+		lengthPart = value[:idx]
+		offsetPart = value[idx+1:]
+	}
+	length := parseInt64(lengthPart)
+	if length <= 0 {
+		return nil
+	}
+	offset := defaultOffset
+	if offsetPart != "" {
+		offset = parseInt64(offsetPart)
+		if offset < 0 {
+			return nil
+		}
+	}
+	return &ByteRange{Length: length, Offset: offset}
+}
+
+// resolveURL resolves a playlist URI reference against the playlist URL
+// following RFC 3986.
+func resolveURL(baseURL *url.URL, ref string) string {
+	refURL, err := url.Parse(ref)
+	if err != nil {
+		return ref
+	}
+	return baseURL.ResolveReference(refURL).String()
+}
+
+// parseAttributes parses an HLS attribute list like FOO="bar",NUM=42.
+func parseAttributes(s string) map[string]string {
+	attrs := make(map[string]string)
+	var key, val strings.Builder
+	inKey := true
+	inQuote := false
+	flush := func() {
+		name := strings.ToUpper(strings.TrimSpace(key.String()))
+		if name != "" {
+			attrs[name] = strings.TrimSpace(val.String())
+		}
+		key.Reset()
+		val.Reset()
+		inKey = true
+	}
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		if inKey {
+			if c == '=' {
+				inKey = false
+			} else {
+				key.WriteByte(c)
+			}
+			continue
+		}
+		if c == '"' {
+			inQuote = !inQuote
+			continue
+		}
+		if c == ',' && !inQuote {
+			flush()
+			continue
+		}
+		val.WriteByte(c)
+	}
+	flush()
+	return attrs
+}
+
+func unquote(s string) string {
+	s = strings.TrimSpace(s)
+	if len(s) >= 2 && strings.HasPrefix(s, "\"") && strings.HasSuffix(s, "\"") {
+		return s[1 : len(s)-1]
+	}
+	return s
+}
+
+func parseInt64(s string) int64 {
+	value, _ := strconv.ParseInt(strings.TrimSpace(s), 10, 64)
+	return value
+}
+
+func parseFloat(s string) float64 {
+	value, _ := strconv.ParseFloat(strings.TrimSpace(s), 64)
+	return value
+}
+
+// OutputExtension returns the container file extension for the playlist.
+func (m *Media) OutputExtension() string {
+	if m.IsFMP4 {
+		return ".mp4"
+	}
+	return ".ts"
+}
+
+// DeriveOutputName builds the merged output file name from a playlist URL.
+func DeriveOutputName(playlistURL string, media *Media) string {
+	name := ""
+	if u, err := url.Parse(playlistURL); err == nil {
+		name = path.Base(u.Path)
+		name = strings.TrimSuffix(name, path.Ext(name))
+	}
+	if name == "" || name == "/" || name == "." {
+		if u, err := url.Parse(playlistURL); err == nil {
+			name = u.Hostname()
+		}
+	}
+	return name + media.OutputExtension()
+}

internal/protocol/hls/playlist_realworld_test.go

@@ -0,0 +1,39 @@
+package hls
+
+import (
+	_ "embed"
+	"net/url"
+	"testing"
+)
+
+//go:embed testdata/olemovienews.m3u8
+var realWorldPlaylist string
+
+// TestParseMediaRealWorld guards parsing against a real site playlist
+// (olemovienews.com VOD, 138 TS segments).
+func TestParseMediaRealWorld(t *testing.T) {
+	base, err := url.Parse("https://europe.olemovienews.com/ts2/20230125/afAxfjit/mp4/afAxfjit.mp4/index-v1-a1.m3u8")
+	if err != nil {
+		t.Fatal(err)
+	}
+	media, err := ParseMedia(realWorldPlaylist, base)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if media.Live {
+		t.Error("real VOD playlist should not be live")
+	}
+	if media.IsFMP4 {
+		t.Error("playlist should be detected as TS")
+	}
+	if len(media.Segments) != 138 {
+		t.Errorf("want 138 segments, got %d", len(media.Segments))
+	}
+	first := media.Segments[0]
+	if first.URI != "https://europe.olemovienews.com/ts2/20230125/afAxfjit/mp4/afAxfjit.mp4/seg-1-v1-a1.ts" {
+		t.Errorf("segment URI resolution wrong: %s", first.URI)
+	}
+	if media.Segments[0].Sequence != 1 {
+		t.Errorf("first sequence = %d, want 1", media.Segments[0].Sequence)
+	}
+}

internal/protocol/hls/playlist_test.go

@@ -0,0 +1,252 @@
+package hls
+
+import (
+	"net/url"
+	"testing"
+)
+
+func mustURL(t *testing.T, raw string) *url.URL {
+	t.Helper()
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return u
+}
+
+func TestParseMediaTS(t *testing.T) {
+	content := "#EXTM3U\n" +
+		"#EXT-X-TARGETDURATION:20\n" +
+		"#EXT-X-VERSION:3\n" +
+		"#EXT-X-MEDIA-SEQUENCE:1\n" +
+		"#EXTINF:20.000,\n" +
+		"seg-1.ts\n" +
+		"#EXTINF:20.000,\n" +
+		"seg-2.ts\n" +
+		"#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if media.Live {
+		t.Error("VOD playlist should not be live")
+	}
+	if media.IsFMP4 {
+		t.Error("TS playlist should not be fMP4")
+	}
+	if len(media.Segments) != 2 {
+		t.Fatalf("want 2 segments, got %d", len(media.Segments))
+	}
+	want := "https://cdn.example.com/vod/seg-1.ts"
+	if media.Segments[0].URI != want {
+		t.Errorf("want uri %s, got %s", want, media.Segments[0].URI)
+	}
+	if media.Segments[0].Sequence != 1 {
+		t.Errorf("want sequence 1, got %d", media.Segments[0].Sequence)
+	}
+	if media.Segments[0].Key != nil {
+		t.Error("segment should be unencrypted")
+	}
+}
+
+func TestParseMediaWithoutExtinf(t *testing.T) {
+	// Some playlists list segment URIs without EXTINF lines.
+	content := "#EXTM3U\nseg-1.ts\nseg-2.ts\n#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/a/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(media.Segments) != 2 {
+		t.Fatalf("want 2 segments, got %d", len(media.Segments))
+	}
+}
+
+func TestParseMediaLive(t *testing.T) {
+	content := "#EXTM3U\n#EXT-X-TARGETDURATION:6\n#EXTINF:6.0,\nseg-1.ts\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/live/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !media.Live {
+		t.Error("playlist without ENDLIST should be live")
+	}
+}
+
+func TestParseMediaFMP4(t *testing.T) {
+	content := "#EXTM3U\n" +
+		"#EXT-X-VERSION:6\n" +
+		"#EXT-X-MAP:URI=\"init.mp4\"\n" +
+		"#EXTINF:5.0,\n" +
+		"seg-1.m4s\n" +
+		"#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !media.IsFMP4 {
+		t.Error("playlist with MAP should be fMP4")
+	}
+	if len(media.Segments) != 2 {
+		t.Fatalf("want 2 segments (init + 1), got %d", len(media.Segments))
+	}
+	if !media.Segments[0].IsInit {
+		t.Error("first segment should be the init section")
+	}
+	if media.Segments[0].URI != "https://cdn.example.com/vod/init.mp4" {
+		t.Errorf("init uri wrong: %s", media.Segments[0].URI)
+	}
+	if media.OutputExtension() != ".mp4" {
+		t.Errorf("want .mp4, got %s", media.OutputExtension())
+	}
+}
+
+func TestParseMediaMultiMapError(t *testing.T) {
+	content := "#EXTM3U\n" +
+		"#EXT-X-MAP:URI=\"init1.mp4\"\n" +
+		"#EXTINF:5.0,\nseg-1.m4s\n" +
+		"#EXT-X-DISCONTINUITY\n" +
+		"#EXT-X-MAP:URI=\"init2.mp4\"\n" +
+		"#EXTINF:5.0,\nseg-2.m4s\n" +
+		"#EXT-X-ENDLIST\n"
+	if _, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8")); err == nil {
+		t.Error("multi-period fMP4 should be rejected")
+	}
+}
+
+func TestParseMediaKeyRotation(t *testing.T) {
+	content := "#EXTM3U\n" +
+		"#EXT-X-KEY:METHOD=AES-128,URI=\"key1.bin\",IV=0x00000000000000000000000000000001\n" +
+		"#EXTINF:5.0,\nseg-1.ts\n" +
+		"#EXT-X-KEY:METHOD=AES-128,URI=\"key2.bin\"\n" +
+		"#EXTINF:5.0,\nseg-2.ts\n" +
+		"#EXT-X-KEY:METHOD=NONE\n" +
+		"#EXTINF:5.0,\nseg-3.ts\n" +
+		"#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if media.Segments[0].Key == nil || media.Segments[0].Key.URI != "https://cdn.example.com/vod/key1.bin" {
+		t.Fatalf("segment 1 key wrong: %+v", media.Segments[0].Key)
+	}
+	if len(media.Segments[0].Key.IV) != 16 || media.Segments[0].Key.IV[15] != 1 {
+		t.Error("explicit IV not parsed")
+	}
+	if media.Segments[1].Key == nil || media.Segments[1].Key.URI != "https://cdn.example.com/vod/key2.bin" {
+		t.Fatalf("segment 2 key wrong: %+v", media.Segments[1].Key)
+	}
+	if media.Segments[1].Key.IV != nil {
+		t.Error("key without IV should leave IV nil (sequence-derived)")
+	}
+	if media.Segments[2].Key != nil {
+		t.Error("segment 3 should be unencrypted after METHOD=NONE")
+	}
+}
+
+func TestParseMediaSampleAESError(t *testing.T) {
+	content := "#EXTM3U\n#EXT-X-KEY:METHOD=SAMPLE-AES,URI=\"skd://key\"\n#EXTINF:5.0,\nseg-1.ts\n"
+	if _, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8")); err == nil {
+		t.Error("SAMPLE-AES should be rejected")
+	}
+}
+
+func TestParseMediaByterange(t *testing.T) {
+	content := "#EXTM3U\n" +
+		"#EXT-X-BYTERANGE:1000@0\nseg.ts\n" +
+		"#EXT-X-BYTERANGE:2000\nseg.ts\n" +
+		"#EXT-X-BYTERANGE:3000\nseg.ts\n" +
+		"#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	ranges := [][2]int64{{0, 1000}, {1000, 2000}, {3000, 3000}}
+	for i, want := range ranges {
+		br := media.Segments[i].Byterange
+		if br == nil {
+			t.Fatalf("segment %d byterange missing", i)
+		}
+		if br.Offset != want[0] || br.Length != want[1] {
+			t.Errorf("segment %d: want offset %d length %d, got %d/%d", i, want[0], want[1], br.Offset, br.Length)
+		}
+	}
+}
+
+func TestParseMediaGap(t *testing.T) {
+	content := "#EXTM3U\n#EXTINF:5.0,\nseg-1.ts\n#EXT-X-GAP\n#EXTINF:5.0,\nseg-2.ts\n#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(content, mustURL(t, "https://cdn.example.com/vod/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if media.Segments[0].Gap || !media.Segments[1].Gap {
+		t.Error("gap flags wrong")
+	}
+}
+
+func TestParseMediaInvalidHeader(t *testing.T) {
+	if _, err := ParseMedia("not a playlist", mustURL(t, "https://cdn.example.com/a.m3u8")); err == nil {
+		t.Error("invalid content should be rejected")
+	}
+}
+
+func TestParseMasterPickBest(t *testing.T) {
+	content := "#EXTM3U\n" +
+		"#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"en\",DEFAULT=YES,URI=\"audio/index.m3u8\"\n" +
+		"#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360\n" +
+		"360p/index.m3u8\n" +
+		"#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,CODECS=\"avc1.640028,mp4a.40.2\"\n" +
+		"1080p/index.m3u8?sign=abc\n" +
+		"#EXT-X-ENDLIST\n"
+	variants, err := ParseMaster(content, mustURL(t, "https://cdn.example.com/vod/master.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(variants) != 2 {
+		t.Fatalf("want 2 variants, got %d", len(variants))
+	}
+	best := PickBestVariant(variants)
+	if best.Bandwidth != 2500000 {
+		t.Errorf("want highest bandwidth variant, got %d", best.Bandwidth)
+	}
+	if best.URI != "https://cdn.example.com/vod/1080p/index.m3u8?sign=abc" {
+		t.Errorf("variant uri wrong: %s", best.URI)
+	}
+}
+
+func TestResolveURLQueryNotInherited(t *testing.T) {
+	base := mustURL(t, "https://cdn.example.com/vod/index.m3u8?sign=abc")
+	got := resolveURL(base, "seg-1.ts")
+	if got != "https://cdn.example.com/vod/seg-1.ts" {
+		t.Errorf("relative resolution should follow RFC3986 (no query inheritance), got %s", got)
+	}
+}
+
+func TestDeriveOutputName(t *testing.T) {
+	media := &Media{}
+	if got := DeriveOutputName("https://cdn.example.com/ts2/a/index-v1-a1.m3u8", media); got != "index-v1-a1.ts" {
+		t.Errorf("want index-v1-a1.ts, got %s", got)
+	}
+	fmp4 := &Media{IsFMP4: true}
+	if got := DeriveOutputName("https://cdn.example.com/ts2/a/index.m3u8", fmp4); got != "index.mp4" {
+		t.Errorf("want index.mp4, got %s", got)
+	}
+	if got := DeriveOutputName("https://cdn.example.com/play?token=x", media); got != "play.ts" {
+		t.Errorf("want play.ts, got %s", got)
+	}
+	if got := DeriveOutputName("https://cdn.example.com/", media); got != "cdn.example.com.ts" {
+		t.Errorf("want host fallback, got %s", got)
+	}
+}
+
+func TestParseAttributesQuotedComma(t *testing.T) {
+	attrs := parseAttributes(`URI="a,b.ts",IV=0xABCDEF00000000000000000000000001,NAME="x"`)
+	if attrs["URI"] != "a,b.ts" {
+		t.Errorf("quoted comma value wrong: %q", attrs["URI"])
+	}
+	if attrs["IV"] != "0xABCDEF00000000000000000000000001" {
+		t.Errorf("hex value wrong: %q", attrs["IV"])
+	}
+	if attrs["NAME"] != "x" {
+		t.Errorf("quoted value wrong: %q", attrs["NAME"])
+	}
+}

internal/protocol/hls/staging_test.go

@@ -0,0 +1,304 @@
+package hls
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/pkg/base"
+)
+
+func TestFetcherE2E_SameURLTwoTasks(t *testing.T) {
+	const total = 6
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < total; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	segments := make(map[int][]byte)
+	for i := 0; i < total; i++ {
+		segments[i] = []byte(fmt.Sprintf("SHARED-SEGMENT-%02d", i))
+		idx := i
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", idx), func(w http.ResponseWriter, r *http.Request) {
+			time.Sleep(120 * time.Millisecond)
+			w.Write(segments[idx])
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	cfg := testConfig()
+	cfg.SegmentConnections = 2
+	cfg.PrefetchContentLength = false
+	dir := t.TempDir()
+
+	// Two tasks for the same playlist URL into the same directory, like a
+	// user duplicating a task. The engine would rename the second output
+	// (AutoRename); mirror that here.
+	f1 := newTestFetcher(t, cfg)
+	f1.Meta().Opts = &base.Options{Path: dir}
+	if err := f1.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	f2 := newTestFetcher(t, cfg)
+	f2.Meta().Opts = &base.Options{Path: dir, Name: "video-2.ts"}
+	if err := f2.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	if f1.state.StagingID == "" || f1.state.StagingID == f2.state.StagingID {
+		t.Fatal("staging identities must be distinct per task")
+	}
+	if f1.state.StagingDir != "" || f2.state.StagingDir != "" {
+		t.Fatal("Resolve pinned an output directory")
+	}
+
+	// Start task 1, let it stage some segments, then pause it.
+	if err := f1.Start(); err != nil {
+		t.Fatal(err)
+	}
+	time.Sleep(250 * time.Millisecond)
+	if err := f1.Pause(); err != nil {
+		t.Fatal(err)
+	}
+	staged1, err := os.ReadDir(f1.state.StagingDir)
+	if err != nil || len(staged1) == 0 {
+		t.Fatalf("task 1 should have staged segments, dir: %s", f1.state.StagingDir)
+	}
+
+	// Task 2 must complete without touching task 1's staging data...
+	if err := f2.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f2.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	stillThere, err := os.ReadDir(f1.state.StagingDir)
+	if err != nil || len(stillThere) != len(staged1) {
+		t.Fatalf("task 2 disturbed task 1 staging: had %d entries, now %d", len(staged1), len(stillThere))
+	}
+
+	// ...and task 1 resumes to a complete, correct output of its own.
+	if err := f1.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f1.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	var want []byte
+	for i := 0; i < total; i++ {
+		want = append(want, segments[i]...)
+	}
+	if !bytes.Equal(readOutput(t, f1), want) || !bytes.Equal(readOutput(t, f2), want) {
+		t.Error("same-URL task outputs mismatch")
+	}
+	entries, _ := os.ReadDir(dir)
+	if len(entries) != 2 {
+		names := make([]string, 0, len(entries))
+		for _, e := range entries {
+			names = append(names, e.Name())
+		}
+		t.Errorf("expected only the two outputs to remain, got %v", names)
+	}
+}
+
+func TestFetcherE2E_ForeignJournalDiscarded(t *testing.T) {
+	const total = 3
+	var served atomic.Int64
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < total; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	for i := 0; i < total; i++ {
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", i), func(w http.ResponseWriter, r *http.Request) {
+			served.Add(1)
+			w.Write([]byte("DATA"))
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	cfg := testConfig()
+	cfg.PrefetchContentLength = false
+	f := newTestFetcher(t, cfg)
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	// Plant a journal that does not belong to this plan (wrong fingerprint).
+	tempDir := f.resolveStagingDirLocked()
+	if err := os.MkdirAll(tempDir, 0777); err != nil {
+		t.Fatal(err)
+	}
+	foreign := journalFile{
+		StagingID:    "some-other-task",
+		PlanHash:     "deadbeef",
+		SegmentCount: total,
+		Sizes:        map[string]int64{"0": 4, "1": 4, "2": 4},
+	}
+	data, _ := json.Marshal(foreign)
+	if err := os.WriteFile(filepath.Join(tempDir, "journal.json"), data, 0666); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	if got := served.Load(); got != total {
+		t.Errorf("foreign journal must be discarded, want %d downloads, got %d", total, got)
+	}
+}
+
+func TestFetcherE2E_MergeFailurePreservesStaging(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("#EXTM3U\n#EXTINF:4,\na.ts\n#EXTINF:4,\nb.ts\n#EXT-X-ENDLIST\n"))
+	})
+	mux.HandleFunc("/a.ts", func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("AAAA")) })
+	mux.HandleFunc("/b.ts", func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("BBBB")) })
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	run := &hlsRun{
+		ctx:        context.Background(),
+		cancel:     func() {},
+		done:       make(chan struct{}),
+		segs:       f.state.Segments,
+		outputPath: f.meta.SingleFilepath(),
+		stagingID:  f.state.StagingID,
+		planHash:   planFingerprint(f.state),
+		tempDir:    f.resolveStagingDirLocked(),
+		keyCache:   make(map[string][]byte),
+		journal:    make(map[int64]int64),
+	}
+	run.journalPath = filepath.Join(run.tempDir, "journal.json")
+	if err := os.MkdirAll(run.tempDir, 0777); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(segmentPath(run.tempDir, 0), []byte("AAAA"), 0666); err != nil {
+		t.Fatal(err)
+	}
+	// Segment 1 is missing on disk: the merge must fail without deleting the
+	// staged data or leaving a partial output behind.
+	if err := f.merge(run); err == nil {
+		t.Fatal("merge with a missing segment should fail")
+	}
+	if _, err := os.Stat(segmentPath(run.tempDir, 0)); err != nil {
+		t.Fatal("merge failure must preserve staged segments")
+	}
+	entries, _ := os.ReadDir(filepath.Dir(run.outputPath))
+	for _, e := range entries {
+		if strings.HasSuffix(e.Name(), ".part") {
+			t.Errorf("failed merge left a partial output behind: %s", e.Name())
+		}
+	}
+
+	// Recover the segment: the retried merge succeeds.
+	if err := os.WriteFile(segmentPath(run.tempDir, 1), []byte("BBBB"), 0666); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.merge(run); err != nil {
+		t.Fatalf("retried merge failed: %v", err)
+	}
+	got, err := os.ReadFile(run.outputPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "AAAABBBB" {
+		t.Errorf("retried merge output mismatch: %q", got)
+	}
+}
+
+func TestFetcherE2E_ReMergeOverExistingOutput(t *testing.T) {
+	const total = 2
+	mux := http.NewServeMux()
+	var playlist strings.Builder
+	playlist.WriteString("#EXTM3U\n")
+	for i := 0; i < total; i++ {
+		playlist.WriteString(fmt.Sprintf("#EXTINF:4,\nseg-%d.ts\n", i))
+	}
+	playlist.WriteString("#EXT-X-ENDLIST\n")
+	mux.HandleFunc("/video.m3u8", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(playlist.String()))
+	})
+	for i := 0; i < total; i++ {
+		mux.HandleFunc(fmt.Sprintf("/seg-%d.ts", i), func(w http.ResponseWriter, r *http.Request) {
+			w.Write([]byte("DATA"))
+		})
+	}
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	f := newTestFetcher(t, testConfig())
+	f.Meta().Opts = &base.Options{Path: t.TempDir()}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/video.m3u8"}); err != nil {
+		t.Fatal(err)
+	}
+	tempDir := f.resolveStagingDirLocked()
+	if err := os.MkdirAll(tempDir, 0777); err != nil {
+		t.Fatal(err)
+	}
+	// Simulate the crash window after a completed rename but before the task
+	// was marked done: a stale output file, a complete journal and all
+	// segments staged.
+	stale := filepath.Join(filepath.Dir(f.meta.SingleFilepath()), f.state.OutputName)
+	if err := os.WriteFile(stale, []byte("STALE-OUTPUT"), 0666); err != nil {
+		t.Fatal(err)
+	}
+	jr := &hlsRun{
+		segs:        f.state.Segments,
+		stagingID:   f.state.StagingID,
+		planHash:    planFingerprint(f.state),
+		journalPath: filepath.Join(tempDir, "journal.json"),
+		journal:     map[int64]int64{0: 4, 1: 4},
+	}
+	if err := saveJournal(jr); err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < total; i++ {
+		if err := os.WriteFile(segmentPath(tempDir, int64(i)), []byte("DATA"), 0666); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("re-merge over an existing output failed: %v", err)
+	}
+	got, err := os.ReadFile(stale)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "DATADATA" {
+		t.Errorf("stale output was not replaced: %q", got)
+	}
+}

internal/protocol/hls/subset_test.go

@@ -0,0 +1,146 @@
+package hls
+
+import (
+	"net/url"
+	"strings"
+	"testing"
+)
+
+func mustParseURL(t *testing.T, raw string) *url.URL {
+	t.Helper()
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return u
+}
+
+// subsetCase is a media playlist plus the error substring the pipeline must
+// reject it with; wantOK playlists must parse AND validate cleanly.
+type subsetCase struct {
+	name     string
+	playlist string
+	wantErr  string
+}
+
+func TestSubsetRejections(t *testing.T) {
+	cases := []subsetCase{
+		{
+			name:     "gap",
+			playlist: "#EXTM3U\n#EXTINF:4,\na.ts\n#EXT-X-GAP\n#EXTINF:4,\nb.ts\n#EXT-X-ENDLIST\n",
+			wantErr:  "EXT-X-GAP",
+		},
+		{
+			name:     "gap-before-first-segment",
+			playlist: "#EXTM3U\n#EXT-X-GAP\n#EXTINF:4,\na.ts\n#EXT-X-ENDLIST\n",
+			wantErr:  "EXT-X-GAP",
+		},
+		{
+			name:     "discontinuity",
+			playlist: "#EXTM3U\n#EXTINF:4,\na.ts\n#EXT-X-DISCONTINUITY\n#EXTINF:4,\nb.ts\n#EXT-X-ENDLIST\n",
+			wantErr:  "EXT-X-DISCONTINUITY",
+		},
+		{
+			name:     "live",
+			playlist: "#EXTM3U\n#EXTINF:4,\na.ts\n",
+			wantErr:  "live",
+		},
+		{
+			name:     "keyformat",
+			playlist: "#EXTM3U\n#EXT-X-KEY:METHOD=AES-128,URI=\"k\",KEYFORMAT=\"com.apple.streamingkeydelivery\"\n#EXTINF:4,\na.ts\n#EXT-X-ENDLIST\n",
+			wantErr:  "KEYFORMAT",
+		},
+		{
+			name:     "encrypted-map-without-iv",
+			playlist: "#EXTM3U\n#EXT-X-KEY:METHOD=AES-128,URI=\"k\"\n#EXT-X-MAP:URI=\"init.mp4\"\n#EXTINF:4,\na.m4s\n#EXT-X-ENDLIST\n",
+			wantErr:  "explicit IV",
+		},
+		{
+			name:     "map-change-byterange",
+			playlist: "#EXTM3U\n#EXT-X-MAP:URI=\"init.mp4\",BYTERANGE=\"100@0\"\n#EXTINF:4,\na.m4s\n#EXT-X-MAP:URI=\"init.mp4\",BYTERANGE=\"100@100\"\n#EXTINF:4,\nb.m4s\n#EXT-X-ENDLIST\n",
+			wantErr:  "changing init sections",
+		},
+		{
+			name:     "map-change-uri",
+			playlist: "#EXTM3U\n#EXT-X-MAP:URI=\"init1.mp4\"\n#EXTINF:4,\na.m4s\n#EXT-X-MAP:URI=\"init2.mp4\"\n#EXTINF:4,\nb.m4s\n#EXT-X-ENDLIST\n",
+			wantErr:  "changing init sections",
+		},
+	}
+	baseURL := mustParseURL(t, "https://cdn.example.com/vod/index.m3u8")
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			media, parseErr := ParseMedia(tc.playlist, baseURL)
+			if parseErr != nil {
+				if !strings.Contains(parseErr.Error(), tc.wantErr) {
+					t.Fatalf("parse error %q does not mention %q", parseErr, tc.wantErr)
+				}
+				return
+			}
+			err := validateSupported(media)
+			if err == nil {
+				t.Fatalf("playlist should be rejected with %q", tc.wantErr)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Fatalf("error %q does not mention %q", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestSubsetRepeatedSameMapAllowed(t *testing.T) {
+	playlist := "#EXTM3U\n" +
+		"#EXT-X-MAP:URI=\"init.mp4\",BYTERANGE=\"100@0\"\n" +
+		"#EXTINF:4,\na.m4s\n" +
+		"#EXT-X-MAP:URI=\"init.mp4\",BYTERANGE=\"100@0\"\n" +
+		"#EXTINF:4,\nb.m4s\n" +
+		"#EXT-X-ENDLIST\n"
+	media, err := ParseMedia(playlist, mustParseURL(t, "https://cdn.example.com/vod/index.m3u8"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := validateSupported(media); err != nil {
+		t.Fatalf("identical repeated MAP must be allowed: %v", err)
+	}
+	if len(media.Segments) != 3 { // init + 2 segments, no duplicate init
+		t.Fatalf("want 3 segments (init + 2), got %d", len(media.Segments))
+	}
+}
+
+func TestMasterAudioRenditionDetection(t *testing.T) {
+	masterURL := mustParseURL(t, "https://cdn.example.com/master.m3u8")
+
+	separateAudio := "#EXTM3U\n" +
+		"#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"en\",DEFAULT=YES,URI=\"audio/index.m3u8\"\n" +
+		"#EXT-X-STREAM-INF:BANDWIDTH=1000000,AUDIO=\"aud\"\nvideo/index.m3u8\n"
+	master, err := ParseMasterPlaylist(separateAudio, masterURL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := checkAudioRendition(master, PickBestVariant(master.Variants)); err == nil {
+		t.Fatal("selected variant with a separate audio rendition must be rejected")
+	}
+
+	// A group the variant does not reference must not cause a false positive.
+	unrelatedGroup := "#EXTM3U\n" +
+		"#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"en\",DEFAULT=YES,URI=\"audio/index.m3u8\"\n" +
+		"#EXT-X-STREAM-INF:BANDWIDTH=1000000\nvideo/index.m3u8\n"
+	master, err = ParseMasterPlaylist(unrelatedGroup, masterURL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := checkAudioRendition(master, PickBestVariant(master.Variants)); err != nil {
+		t.Fatalf("unreferenced audio group must not be rejected: %v", err)
+	}
+
+	// A rendition group without URIs (muxed tracks) is fine.
+	groupWithoutURI := "#EXTM3U\n" +
+		"#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"en\",DEFAULT=YES\n" +
+		"#EXT-X-STREAM-INF:BANDWIDTH=1000000,AUDIO=\"aud\"\nvideo/index.m3u8\n"
+	master, err = ParseMasterPlaylist(groupWithoutURI, masterURL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := checkAudioRendition(master, PickBestVariant(master.Variants)); err != nil {
+		t.Fatalf("audio group without URI must not be rejected: %v", err)
+	}
+}

internal/protocol/hls/testdata/media/README.md

@@ -0,0 +1,10 @@
+Media fixtures generated locally with FFmpeg 7.0.2 (testsrc + sine sources,
+no third-party content):
+
+- sample-00.ts / sample-01.ts: one continuous MPEG-2 TS encode split at a
+  packet boundary, so continuity counters and PCR are consistent across the
+  segment join exactly like segments cut from a single real-time stream.
+- fmp4-init.mp4: ftyp+moov init section of a fragmented MP4.
+- fmp4-seg1.m4s .. fmp4-seg3.m4s: moof+mdat media fragments (styp omitted by
+  the muxer, which is legal) split at moof boundaries from one fragmented MP4
+  (-movflags +frag_keyframe+empty_moov+default_base_moof -frag_duration 500000).

internal/protocol/hls/testdata/olemovienews.m3u8

@@ -0,0 +1,283 @@
+#EXTM3U
+#EXT-X-TARGETDURATION:20
+#EXT-X-ALLOW-CACHE:YES
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXT-X-VERSION:3
+#EXT-X-MEDIA-SEQUENCE:1
+#EXTINF:20.000,
+seg-1-v1-a1.ts
+#EXTINF:20.000,
+seg-2-v1-a1.ts
+#EXTINF:20.000,
+seg-3-v1-a1.ts
+#EXTINF:20.000,
+seg-4-v1-a1.ts
+#EXTINF:20.000,
+seg-5-v1-a1.ts
+#EXTINF:20.000,
+seg-6-v1-a1.ts
+#EXTINF:20.000,
+seg-7-v1-a1.ts
+#EXTINF:20.000,
+seg-8-v1-a1.ts
+#EXTINF:20.000,
+seg-9-v1-a1.ts
+#EXTINF:20.000,
+seg-10-v1-a1.ts
+#EXTINF:20.000,
+seg-11-v1-a1.ts
+#EXTINF:20.000,
+seg-12-v1-a1.ts
+#EXTINF:20.000,
+seg-13-v1-a1.ts
+#EXTINF:20.000,
+seg-14-v1-a1.ts
+#EXTINF:20.000,
+seg-15-v1-a1.ts
+#EXTINF:20.000,
+seg-16-v1-a1.ts
+#EXTINF:20.000,
+seg-17-v1-a1.ts
+#EXTINF:20.000,
+seg-18-v1-a1.ts
+#EXTINF:20.000,
+seg-19-v1-a1.ts
+#EXTINF:20.000,
+seg-20-v1-a1.ts
+#EXTINF:20.000,
+seg-21-v1-a1.ts
+#EXTINF:20.000,
+seg-22-v1-a1.ts
+#EXTINF:20.000,
+seg-23-v1-a1.ts
+#EXTINF:20.000,
+seg-24-v1-a1.ts
+#EXTINF:20.000,
+seg-25-v1-a1.ts
+#EXTINF:20.000,
+seg-26-v1-a1.ts
+#EXTINF:20.000,
+seg-27-v1-a1.ts
+#EXTINF:20.000,
+seg-28-v1-a1.ts
+#EXTINF:20.000,
+seg-29-v1-a1.ts
+#EXTINF:20.000,
+seg-30-v1-a1.ts
+#EXTINF:20.000,
+seg-31-v1-a1.ts
+#EXTINF:20.000,
+seg-32-v1-a1.ts
+#EXTINF:20.000,
+seg-33-v1-a1.ts
+#EXTINF:20.000,
+seg-34-v1-a1.ts
+#EXTINF:20.000,
+seg-35-v1-a1.ts
+#EXTINF:20.000,
+seg-36-v1-a1.ts
+#EXTINF:20.000,
+seg-37-v1-a1.ts
+#EXTINF:20.000,
+seg-38-v1-a1.ts
+#EXTINF:20.000,
+seg-39-v1-a1.ts
+#EXTINF:20.000,
+seg-40-v1-a1.ts
+#EXTINF:20.000,
+seg-41-v1-a1.ts
+#EXTINF:20.000,
+seg-42-v1-a1.ts
+#EXTINF:20.000,
+seg-43-v1-a1.ts
+#EXTINF:20.000,
+seg-44-v1-a1.ts
+#EXTINF:20.000,
+seg-45-v1-a1.ts
+#EXTINF:20.000,
+seg-46-v1-a1.ts
+#EXTINF:20.000,
+seg-47-v1-a1.ts
+#EXTINF:20.000,
+seg-48-v1-a1.ts
+#EXTINF:20.000,
+seg-49-v1-a1.ts
+#EXTINF:20.000,
+seg-50-v1-a1.ts
+#EXTINF:20.000,
+seg-51-v1-a1.ts
+#EXTINF:20.000,
+seg-52-v1-a1.ts
+#EXTINF:20.000,
+seg-53-v1-a1.ts
+#EXTINF:20.000,
+seg-54-v1-a1.ts
+#EXTINF:20.000,
+seg-55-v1-a1.ts
+#EXTINF:20.000,
+seg-56-v1-a1.ts
+#EXTINF:20.000,
+seg-57-v1-a1.ts
+#EXTINF:20.000,
+seg-58-v1-a1.ts
+#EXTINF:20.000,
+seg-59-v1-a1.ts
+#EXTINF:20.000,
+seg-60-v1-a1.ts
+#EXTINF:20.000,
+seg-61-v1-a1.ts
+#EXTINF:20.000,
+seg-62-v1-a1.ts
+#EXTINF:20.000,
+seg-63-v1-a1.ts
+#EXTINF:20.000,
+seg-64-v1-a1.ts
+#EXTINF:20.000,
+seg-65-v1-a1.ts
+#EXTINF:20.000,
+seg-66-v1-a1.ts
+#EXTINF:20.000,
+seg-67-v1-a1.ts
+#EXTINF:20.000,
+seg-68-v1-a1.ts
+#EXTINF:20.000,
+seg-69-v1-a1.ts
+#EXTINF:20.000,
+seg-70-v1-a1.ts
+#EXTINF:20.000,
+seg-71-v1-a1.ts
+#EXTINF:20.000,
+seg-72-v1-a1.ts
+#EXTINF:20.000,
+seg-73-v1-a1.ts
+#EXTINF:20.000,
+seg-74-v1-a1.ts
+#EXTINF:20.000,
+seg-75-v1-a1.ts
+#EXTINF:20.000,
+seg-76-v1-a1.ts
+#EXTINF:20.000,
+seg-77-v1-a1.ts
+#EXTINF:20.000,
+seg-78-v1-a1.ts
+#EXTINF:20.000,
+seg-79-v1-a1.ts
+#EXTINF:20.000,
+seg-80-v1-a1.ts
+#EXTINF:20.000,
+seg-81-v1-a1.ts
+#EXTINF:20.000,
+seg-82-v1-a1.ts
+#EXTINF:20.000,
+seg-83-v1-a1.ts
+#EXTINF:20.000,
+seg-84-v1-a1.ts
+#EXTINF:20.000,
+seg-85-v1-a1.ts
+#EXTINF:20.000,
+seg-86-v1-a1.ts
+#EXTINF:20.000,
+seg-87-v1-a1.ts
+#EXTINF:20.000,
+seg-88-v1-a1.ts
+#EXTINF:20.000,
+seg-89-v1-a1.ts
+#EXTINF:20.000,
+seg-90-v1-a1.ts
+#EXTINF:20.000,
+seg-91-v1-a1.ts
+#EXTINF:20.000,
+seg-92-v1-a1.ts
+#EXTINF:20.000,
+seg-93-v1-a1.ts
+#EXTINF:20.000,
+seg-94-v1-a1.ts
+#EXTINF:20.000,
+seg-95-v1-a1.ts
+#EXTINF:20.000,
+seg-96-v1-a1.ts
+#EXTINF:20.000,
+seg-97-v1-a1.ts
+#EXTINF:20.000,
+seg-98-v1-a1.ts
+#EXTINF:20.000,
+seg-99-v1-a1.ts
+#EXTINF:20.000,
+seg-100-v1-a1.ts
+#EXTINF:20.000,
+seg-101-v1-a1.ts
+#EXTINF:20.000,
+seg-102-v1-a1.ts
+#EXTINF:20.000,
+seg-103-v1-a1.ts
+#EXTINF:20.000,
+seg-104-v1-a1.ts
+#EXTINF:20.000,
+seg-105-v1-a1.ts
+#EXTINF:20.000,
+seg-106-v1-a1.ts
+#EXTINF:20.000,
+seg-107-v1-a1.ts
+#EXTINF:20.000,
+seg-108-v1-a1.ts
+#EXTINF:20.000,
+seg-109-v1-a1.ts
+#EXTINF:20.000,
+seg-110-v1-a1.ts
+#EXTINF:20.000,
+seg-111-v1-a1.ts
+#EXTINF:20.000,
+seg-112-v1-a1.ts
+#EXTINF:20.000,
+seg-113-v1-a1.ts
+#EXTINF:20.000,
+seg-114-v1-a1.ts
+#EXTINF:20.000,
+seg-115-v1-a1.ts
+#EXTINF:20.000,
+seg-116-v1-a1.ts
+#EXTINF:20.000,
+seg-117-v1-a1.ts
+#EXTINF:20.000,
+seg-118-v1-a1.ts
+#EXTINF:20.000,
+seg-119-v1-a1.ts
+#EXTINF:20.000,
+seg-120-v1-a1.ts
+#EXTINF:20.000,
+seg-121-v1-a1.ts
+#EXTINF:20.000,
+seg-122-v1-a1.ts
+#EXTINF:20.000,
+seg-123-v1-a1.ts
+#EXTINF:20.000,
+seg-124-v1-a1.ts
+#EXTINF:20.000,
+seg-125-v1-a1.ts
+#EXTINF:20.000,
+seg-126-v1-a1.ts
+#EXTINF:20.000,
+seg-127-v1-a1.ts
+#EXTINF:20.000,
+seg-128-v1-a1.ts
+#EXTINF:20.000,
+seg-129-v1-a1.ts
+#EXTINF:20.000,
+seg-130-v1-a1.ts
+#EXTINF:20.000,
+seg-131-v1-a1.ts
+#EXTINF:20.000,
+seg-132-v1-a1.ts
+#EXTINF:20.000,
+seg-133-v1-a1.ts
+#EXTINF:20.000,
+seg-134-v1-a1.ts
+#EXTINF:20.000,
+seg-135-v1-a1.ts
+#EXTINF:20.000,
+seg-136-v1-a1.ts
+#EXTINF:20.000,
+seg-137-v1-a1.ts
+#EXTINF:4.111,
+seg-138-v1-a1.ts
+#EXT-X-ENDLIST

internal/protocol/http/config.go

@@ -1,5 +1,8 @@
 package http
 
+// DefaultUserAgent is shared by HTTP downloads and extension HTTP requests.
+const DefaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36"
+
 type config struct {
 	UserAgent      string `json:"userAgent"`
 	Connections    int    `json:"connections"`

internal/protocol/http/fetcher.go

@@ -2,8 +2,13 @@ package http
 
 import (
 	"context"
+	"crypto/md5"
+	"crypto/sha1"
+	"crypto/sha256"
+	"encoding/hex"
 	"errors"
 	"fmt"
+	"hash"
 	"io"
 	"net/http"
 	"net/url"
@@ -34,6 +39,11 @@ const (
 	stealMinChunkSize     = 512 * 1024 // Min steal size: 512KB (avoid tiny chunks)
 )
 
+// connReadBufferSize is the read buffer each connection allocates once and
+// reuses for its lifetime. 64 KiB keeps per-read overhead low on fast links;
+// at 256 connections it is 16 MiB per task.
+const connReadBufferSize = 64 * 1024
+
 var (
 	errRangeRequestIgnored  = errors.New("server ignored HTTP range request")
 	errInvalidRangeResponse = errors.New("invalid HTTP range response")
@@ -150,7 +160,7 @@ type slowStartController struct {
 	totalLaunched  int
 	batchPending   int           // Connections in current batch waiting for HTTP response
 	batchReady     int           // Connections in current batch that succeeded
-	nextBatchSize  int           // Next batch size: 1, 2, 4, 8...
+	nextBatchSize  int           // Next batch size: 1, 2, 4, 16, 256... (capped)
 	expansionCh    chan struct{} // Signal to trigger next expansion
 	paused         bool          // Pause expansion (e.g., on 429)
 }
@@ -229,7 +239,15 @@ func (s *slowStartController) commitBatch(count int) {
 	defer s.mu.Unlock()
 
 	s.totalLaunched += count
-	s.nextBatchSize = s.nextBatchSize * 2 // Exponential growth: 1, 2, 4, 8...
+	if s.nextBatchSize == 1 {
+		// Bootstrap growth: squaring one would never increase the batch size.
+		s.nextBatchSize = min(2, s.maxConnections)
+	} else if s.nextBatchSize > s.maxConnections/s.nextBatchSize {
+		// Cap before multiplying to avoid integer overflow.
+		s.nextBatchSize = s.maxConnections
+	} else {
+		s.nextBatchSize *= s.nextBatchSize
+	}
 	s.batchPending = count
 	s.batchReady = 0
 }
@@ -272,6 +290,12 @@ type Fetcher struct {
 	primaryReadyOnce sync.Once
 	primaryReadyCh   chan struct{}
 
+	// checksumFailed marks that the last completed download failed
+	// checksum verification, so the next retry must force a full
+	// re-download instead of skipping connections that already
+	// reported Completed.
+	checksumFailed atomic.Bool
+
 	// Start pending mechanism
 	startPending   atomic.Bool
 	resolvedCh     chan struct{} // Signal when resolve completes
@@ -292,13 +316,17 @@ type Fetcher struct {
 	resolveFallback  atomic.Bool   // Resolve prefetch is still available until the first Range request takes over
 
 	// Target file
-	file                  *os.File
-	fileMu                sync.Mutex
-	redirectURL           string
-	redirectLock          sync.Mutex
-	ifRange               string
-	rangeReprobeEligible  bool
-	rangeValidatorPinned  bool
+	file                 *os.File
+	fileMu               sync.Mutex
+	redirectURL          string
+	redirectLock         sync.Mutex
+	ifRange              string
+	rangeReprobeEligible bool
+	rangeValidatorPinned bool
+	// sizeKnown distinguishes a display estimate from an HTTP-confirmed length,
+	// including zero. Nil preserves the interpretation of legacy snapshots.
+	sizeKnown *bool
+	// An interrupted chunked sequential response must restart from byte zero.
 	sequentialSizeUnknown bool
 
 	// Lifecycle control
@@ -345,6 +373,40 @@ func (f *Fetcher) setState(s fetcherState) {
 	f.state.Store(int32(s))
 }
 
+// Size state is read under connMu or before download workers are started.
+func (f *Fetcher) hasKnownSize() bool {
+	if f.sizeKnown != nil {
+		return *f.sizeKnown
+	}
+	return f.meta != nil && f.meta.Res != nil && f.meta.Res.Size > 0 && !f.sequentialSizeUnknown
+}
+
+func (f *Fetcher) knownSize() int64 {
+	if f.hasKnownSize() {
+		return f.meta.Res.Size
+	}
+	return 0
+}
+
+func (f *Fetcher) sizeHint() int64 {
+	if f.meta.Opts != nil && f.meta.Opts.Size > 0 {
+		return f.meta.Opts.Size
+	}
+	return 0
+}
+
+// setResourceSizeLocked publishes the value and its authority in one snapshot.
+func (f *Fetcher) setResourceSizeLocked(size int64, known bool) {
+	if !known {
+		size = f.sizeHint()
+	}
+	f.sizeKnown = &known
+	f.meta.Res.Size = size
+	if len(f.meta.Res.Files) > 0 && f.meta.Res.Files[0] != nil {
+		f.meta.Res.Files[0].Size = size
+	}
+}
+
 // updateMaxConnTime updates maxConnTime if the new duration is larger
 func (f *Fetcher) updateMaxConnTime(d time.Duration) {
 	newVal := int64(d)
@@ -353,30 +415,11 @@ func (f *Fetcher) updateMaxConnTime(d time.Duration) {
 	}
 }
 
-func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
+func (f *Fetcher) Resolve(req *base.Request) error {
 	if err := base.ParseReqExtra[fhttp.ReqExtra](req); err != nil {
 		return err
 	}
 	f.meta.Req = req
-	f.meta.Opts = opts
-	if f.meta.Opts == nil {
-		f.meta.Opts = &base.Options{}
-	}
-
-	// Parse options
-	if err := base.ParseOptExtra[fhttp.OptsExtra](opts); err != nil {
-		return err
-	}
-	if opts.Extra == nil {
-		opts.Extra = &fhttp.OptsExtra{}
-	}
-	extra := opts.Extra.(*fhttp.OptsExtra)
-	if extra.Connections <= 0 {
-		extra.Connections = f.config.Connections
-		if extra.Connections <= 0 {
-			extra.Connections = 1
-		}
-	}
 
 	f.setState(stateResolving)
 
@@ -420,13 +463,34 @@ func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
 		res.Range = true
 	}
 
-	// Get content length from Content-Length header
-	contentLength := resp.Header.Get(base.HttpHeaderContentLength)
-	if contentLength != "" {
-		parse, err := strconv.ParseInt(contentLength, 10, 64)
-		if err == nil {
-			res.Size = parse
+	// A partial response describes one segment, not the whole resource.
+	reuseResolveBody := true
+	if resp.StatusCode == base.HttpCodePartialContent {
+		start, _, total, err := parseRangeResponse(resp)
+		if err != nil {
+			resp.Body.Close()
+			f.setState(stateError)
+			return err
 		}
+		res.Size = total
+		res.Range = true
+		// Prefetch is a contiguous prefix copied at offset zero. A segment
+		// starting elsewhere must be fetched again through the Range path.
+		reuseResolveBody = start == 0
+	} else {
+		contentLength := resp.Header.Get(base.HttpHeaderContentLength)
+		if contentLength != "" {
+			if size, err := strconv.ParseInt(contentLength, 10, 64); err == nil {
+				res.Size = size
+			}
+		}
+	}
+	// A hint is only a display value, even when the origin advertises Range.
+	known := resp.StatusCode == base.HttpCodePartialContent || resp.ContentLength >= 0
+	f.sizeKnown = &known
+	f.sequentialSizeUnknown = !res.Range && !known
+	if !known {
+		res.Size = f.sizeHint()
 	}
 
 	// Parse last modified time
@@ -459,6 +523,7 @@ func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
 	if file.Name == "" || file.Name == "/" || file.Name == "." {
 		file.Name = httpReq.URL.Hostname()
 	}
+	file.Name = appendFilenameExtension(file.Name, resp.Header.Get("Content-Type"))
 
 	res.Files = append(res.Files, file)
 	f.meta.Res = res
@@ -469,7 +534,12 @@ func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
 	// IMPORTANT: Keep the response body open for downloading in Start phase
 	// This is crucial for one-time URLs that can only be accessed once
 	f.resolveRespLock.Lock()
-	f.resolveResp = resp
+	if reuseResolveBody {
+		f.resolveResp = resp
+	} else {
+		resp.Body.Close()
+		f.prefetchDone.Store(true)
+	}
 	f.resolveRespLock.Unlock()
 
 	f.setState(stateResolved)
@@ -481,7 +551,7 @@ func (f *Fetcher) Resolve(req *base.Request, opts *base.Options) error {
 
 	// Start async prefetch in background (only for range-supported resources)
 	// For non-range resources, the response will be used directly in Start
-	if res.Range {
+	if res.Range && reuseResolveBody {
 		f.prefetchStopCh = make(chan struct{})
 		f.resolveFallback.Store(true)
 		go f.asyncPrefetch()
@@ -511,17 +581,9 @@ func (f *Fetcher) asyncPrefetch() {
 		return
 	}
 
-	// Create temporary file for prefetch data
-	tmpFile, err := os.CreateTemp("", "gopeed-prefetch-*")
-	if err != nil {
-		f.prefetchErr = err
-		return
-	}
-	f.prefetchFile = tmpFile
-	f.prefetchFilePath = tmpFile.Name()
-
 	defer func() {
-		// Close response body when prefetch stops
+		// Close the response even if temporary-file setup fails or shutdown
+		// rejects a late prefetch. Otherwise the server can remain blocked writing.
 		f.resolveRespLock.Lock()
 		if f.resolveResp != nil {
 			f.resolveResp.Body.Close()
@@ -530,8 +592,33 @@ func (f *Fetcher) asyncPrefetch() {
 		f.resolveRespLock.Unlock()
 	}()
 
+	// Create temporary file for prefetch data
+	tempDir := ""
+	if f.ctl != nil && f.ctl.TempDir != "" {
+		tempDir = f.ctl.TempDir
+		if err := os.MkdirAll(tempDir, 0700); err != nil {
+			f.prefetchErr = err
+			return
+		}
+	}
+	tmpFile, err := os.CreateTemp(tempDir, "gopeed-prefetch-*")
+	if err != nil {
+		f.prefetchErr = err
+		return
+	}
+	if f.ctl != nil {
+		if err := f.ctl.TempFiles.Track(tmpFile.Name()); err != nil {
+			tmpFile.Close()
+			os.Remove(tmpFile.Name())
+			f.prefetchErr = err
+			return
+		}
+	}
+	f.prefetchFile = tmpFile
+	f.prefetchFilePath = tmpFile.Name()
+
 	buf := make([]byte, 32*1024) // 32KB buffer
-	reader := NewTimeoutReader(resp.Body, readTimeout)
+	reader := f.responseReader(resp)
 
 	for {
 		select {
@@ -575,7 +662,7 @@ func (f *Fetcher) stopPrefetchAndCopyData() int64 {
 	}
 
 	// Wait for prefetch to finish (with timeout)
-	for i := 0; i < 1000 && !f.prefetchDone.Load(); i++ {
+	for i := 0; f.prefetchStopCh != nil && i < 1000 && !f.prefetchDone.Load(); i++ {
 		time.Sleep(10 * time.Millisecond)
 	}
 
@@ -616,7 +703,11 @@ func (f *Fetcher) cleanupPrefetchFile() {
 		f.prefetchFile = nil
 	}
 	if f.prefetchFilePath != "" {
-		os.Remove(f.prefetchFilePath)
+		if f.ctl != nil {
+			f.ctl.TempFiles.Remove(f.prefetchFilePath)
+		} else {
+			os.Remove(f.prefetchFilePath)
+		}
 		f.prefetchFilePath = ""
 	}
 	// The byte count is only reusable while the backing prefetch file exists.
@@ -626,7 +717,53 @@ func (f *Fetcher) cleanupPrefetchFile() {
 	f.resolveFallback.Store(false)
 }
 
+// prepareFullRedownload resets all fetcher connection and prefetch state
+// after a checksum mismatch so the subsequent Start takes the fresh-start path.
+func (f *Fetcher) prepareFullRedownload() {
+	f.connMu.Lock()
+	if f.meta.Res.Range {
+		f.connections = nil
+		f.resolveConn = nil
+		f.rangeReprobeEligible = false
+		f.rangeValidatorPinned = false
+	}
+	f.connMu.Unlock()
+
+	f.cleanupPrefetchFile()
+	f.resolveDataPos.Store(0)
+}
+
+// Options may be replaced between Resolve and Start when creating a resolved task.
+func (f *Fetcher) initOptions() error {
+	if f.meta.Opts == nil {
+		f.meta.Opts = &base.Options{}
+	}
+	opts := f.meta.Opts
+	// Parse options
+	if err := base.ParseOptExtra[fhttp.OptsExtra](opts); err != nil {
+		return err
+	}
+	if opts.Extra == nil {
+		opts.Extra = &fhttp.OptsExtra{}
+	}
+	extra := opts.Extra.(*fhttp.OptsExtra)
+	if extra.Connections <= 0 {
+		extra.Connections = f.config.Connections
+		if extra.Connections <= 0 {
+			extra.Connections = 1
+		}
+	}
+	if err := extra.Checksum.Validate(); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 func (f *Fetcher) Start() error {
+	if err := f.initOptions(); err != nil {
+		return err
+	}
 	state := f.getState()
 
 	switch state {
@@ -673,11 +810,26 @@ func (f *Fetcher) doStart() error {
 
 	// If retrying after error, reset connection states for retry
 	if state == stateError {
+		fullRedownload := f.checksumFailed.Swap(false)
+		if fullRedownload {
+			// Checksum mismatch: the file content itself is wrong even
+			// though every connection reported Completed. Truncate the
+			// corrupt file so stale bytes cannot linger if the retry is
+			// interrupted before every connection re-writes its chunk.
+			if err := os.Truncate(f.meta.SingleFilepath(), 0); err != nil && !os.IsNotExist(err) {
+				return fmt.Errorf("failed to reset file after checksum mismatch: %w", err)
+			}
+			f.prepareFullRedownload()
+		}
 		f.connMu.Lock()
 		for _, conn := range f.connections {
-			// Reset connections that can be retried
-			if !conn.Completed && conn.State != connCompleted {
-				if !f.hasSequentialPrefixLocked(conn) {
+			// On a normal error, only reset connections that didn't
+			// finish. On a checksum mismatch, reset EVERY connection —
+			// "Completed" only means the download loop finished, not
+			// that the bytes were verified correct.
+			shouldReset := fullRedownload || (!conn.Completed && conn.State != connCompleted)
+			if shouldReset {
+				if fullRedownload || !f.hasSequentialPrefixLocked(conn) {
 					f.resetConnectionForRestart(conn)
 				}
 				conn.State = connNotStarted
@@ -696,7 +848,7 @@ func (f *Fetcher) doStart() error {
 	_, err = os.Stat(name)
 	if err != nil {
 		if os.IsNotExist(err) {
-			file, err = f.ctl.Touch(name, f.meta.Res.Size)
+			file, err = f.ctl.Touch(name, f.knownSize())
 		} else {
 			return err
 		}
@@ -714,7 +866,7 @@ func (f *Fetcher) doStart() error {
 	// For non-range resources, the response will be used directly
 	var prefetchedBytes int64
 	if f.meta.Res.Range {
-		resolveComplete := f.meta.Res.Size > 0 && f.prefetchDone.Load() && f.prefetchErr == nil && f.prefetchSize.Load() >= f.meta.Res.Size
+		resolveComplete := f.knownSize() > 0 && f.prefetchDone.Load() && f.prefetchErr == nil && f.prefetchSize.Load() >= f.knownSize()
 		if f.resolveFallback.Load() && !resolveComplete {
 			// Keep Resolve downloading until the first Range response has been
 			// validated. The Range request starts at a stable snapshot; a valid
@@ -886,7 +1038,7 @@ func (f *Fetcher) expandConnections() {
 		return
 	}
 
-	totalSize := f.meta.Res.Size
+	totalSize := f.knownSize()
 
 	f.connMu.Lock()
 
@@ -908,8 +1060,14 @@ func (f *Fetcher) expandConnections() {
 			}
 			f.fileMu.Unlock()
 
-			f.setState(stateDone)
-			f.doneCh <- nil
+			var err error
+			if chkErr := f.verifyChecksum(); chkErr != nil {
+				err = chkErr
+				f.setState(stateError)
+			} else {
+				f.setState(stateDone)
+			}
+			f.doneCh <- err
 			return
 		}
 
@@ -1028,7 +1186,7 @@ func (f *Fetcher) runConnection(conn *connection) {
 
 	// Use fast-fail client for quick retry during download phase
 	client := f.buildFastFailClient()
-	buf := make([]byte, 8192)
+	buf := make([]byte, connReadBufferSize)
 
 	retries := 0
 	f.connMu.Lock()
@@ -1171,7 +1329,7 @@ func (f *Fetcher) downloadChunkOnce(conn *connection, client *http.Client, buf [
 	rangeMode := f.meta.Res.Range
 	ifRange := ""
 	if resumeProbe {
-		end := f.meta.Res.Size - 1
+		end := f.knownSize() - 1
 		rangeEnd = &end
 		ifRange = f.ifRange
 	} else if rangeMode && (f.rangeValidatorPinned || f.resolveFallback.Load()) {
@@ -1251,7 +1409,7 @@ func (f *Fetcher) downloadChunkOnce(conn *connection, client *http.Client, buf [
 	}
 	if rangeRequested && resp.StatusCode == base.HttpCodePartialContent {
 		var responseTotal int64
-		expectedResponseLength, responseTotal, err = validateRangeResponse(resp, rangeStart, rangeEnd, f.meta.Res.Size)
+		expectedResponseLength, responseTotal, err = validateRangeResponse(resp, rangeStart, rangeEnd, f.knownSize())
 		if err != nil {
 			resp.Body.Close()
 			return err
@@ -1276,7 +1434,7 @@ func (f *Fetcher) downloadChunkOnce(conn *connection, client *http.Client, buf [
 			f.rangeValidatorPinned = true
 			f.sequentialSizeUnknown = false
 			conn.Chunk.Begin = 0
-			conn.Chunk.setEnd(f.meta.Res.Size - 1)
+			conn.Chunk.setEnd(f.knownSize() - 1)
 			f.connMu.Unlock()
 		}
 	}
@@ -1301,7 +1459,7 @@ func (f *Fetcher) downloadChunkOnce(conn *connection, client *http.Client, buf [
 				resp.Body.Close()
 				return err
 			}
-		} else if f.meta.Res.Size > 0 {
+		} else if f.hasKnownSize() && f.meta.Res.Size > 0 {
 			expectedResponseLength = f.meta.Res.Size
 			if resp.ContentLength >= 0 && resp.ContentLength != expectedResponseLength {
 				resp.Body.Close()
@@ -1328,7 +1486,7 @@ func (f *Fetcher) downloadChunkOnce(conn *connection, client *http.Client, buf [
 		f.slowStart.onConnectSuccess()
 	}
 
-	reader := NewTimeoutReader(resp.Body, readTimeout)
+	reader := f.responseReader(resp)
 	var responseBytesRead int64
 	for {
 		if conn.ctx.Err() != nil {
@@ -1437,7 +1595,7 @@ func (f *Fetcher) commitResolveTakeover(conn *connection, requestedStart int64)
 	}
 
 	prefetched := f.stopPrefetchAndCopyData()
-	if prefetched < requestedStart || prefetched > f.meta.Res.Size {
+	if prefetched < requestedStart || prefetched > f.knownSize() {
 		return 0, fmt.Errorf("resolve prefetch advanced to invalid offset %d for range start %d", prefetched, requestedStart)
 	}
 	f.resolveDataPos.Store(prefetched)
@@ -1468,7 +1626,7 @@ func (f *Fetcher) completeFromResolveFallback(conn *connection) bool {
 		}
 		time.Sleep(10 * time.Millisecond)
 	}
-	knownSize := f.meta.Res.Size > 0
+	knownSize := f.hasKnownSize()
 	if f.prefetchErr != nil || (knownSize && f.prefetchSize.Load() != f.meta.Res.Size) {
 		f.cleanupPrefetchFile()
 		return false
@@ -1482,10 +1640,7 @@ func (f *Fetcher) completeFromResolveFallback(conn *connection) bool {
 
 	f.connMu.Lock()
 	if !knownSize {
-		f.meta.Res.Size = prefetched
-		if len(f.meta.Res.Files) > 0 && f.meta.Res.Files[0] != nil {
-			f.meta.Res.Files[0].Size = prefetched
-		}
+		f.setResourceSizeLocked(prefetched, true)
 	}
 	f.meta.Res.Range = false
 	f.rangeReprobeEligible = false
@@ -1501,27 +1656,41 @@ func (f *Fetcher) completeFromResolveFallback(conn *connection) bool {
 	return true
 }
 
-func validateRangeResponse(resp *http.Response, requestedStart int64, requestedEnd *int64, totalSize int64) (int64, int64, error) {
+// parseRangeResponse validates a single byte range with a known complete length.
+// Unknown totals are rejected: a segment length cannot stand in for resource size.
+func parseRangeResponse(resp *http.Response) (int64, int64, int64, error) {
 	contentRange := resp.Header.Get(base.HttpHeaderContentRange)
 	fields := strings.Fields(contentRange)
 	if len(fields) != 2 || !strings.EqualFold(fields[0], base.HttpHeaderBytes) {
-		return 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
+		return 0, 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
 	}
 
 	rangeAndTotal := strings.Split(fields[1], "/")
 	if len(rangeAndTotal) != 2 {
-		return 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
+		return 0, 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
 	}
 	bounds := strings.Split(rangeAndTotal[0], "-")
 	if len(bounds) != 2 {
-		return 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
+		return 0, 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
 	}
 
 	start, startErr := strconv.ParseInt(bounds[0], 10, 64)
 	end, endErr := strconv.ParseInt(bounds[1], 10, 64)
 	total, totalErr := strconv.ParseInt(rangeAndTotal[1], 10, 64)
 	if startErr != nil || endErr != nil || totalErr != nil || start < 0 || end < start || total <= end {
-		return 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
+		return 0, 0, 0, fmt.Errorf("%w: malformed Content-Range %q", errInvalidRangeResponse, contentRange)
+	}
+	expectedLength := end - start + 1
+	if resp.ContentLength >= 0 && resp.ContentLength != expectedLength {
+		return 0, 0, 0, fmt.Errorf("%w: Content-Length %d does not match range length %d", errInvalidRangeResponse, resp.ContentLength, expectedLength)
+	}
+	return start, end, total, nil
+}
+
+func validateRangeResponse(resp *http.Response, requestedStart int64, requestedEnd *int64, totalSize int64) (int64, int64, error) {
+	start, end, total, err := parseRangeResponse(resp)
+	if err != nil {
+		return 0, 0, err
 	}
 	if start != requestedStart || (requestedEnd != nil && end != *requestedEnd) || (requestedEnd == nil && end != total-1) {
 		return 0, 0, fmt.Errorf("%w: Content-Range %d-%d does not match requested range", errInvalidRangeResponse, start, end)
@@ -1530,11 +1699,7 @@ func validateRangeResponse(resp *http.Response, requestedStart int64, requestedE
 		return 0, 0, fmt.Errorf("%w: Content-Range total %d does not match resource size %d", errInvalidRangeResponse, total, totalSize)
 	}
 
-	expectedLength := end - start + 1
-	if resp.ContentLength >= 0 && resp.ContentLength != expectedLength {
-		return 0, 0, fmt.Errorf("%w: Content-Length %d does not match range length %d", errInvalidRangeResponse, resp.ContentLength, expectedLength)
-	}
-	return expectedLength, total, nil
+	return end - start + 1, total, nil
 }
 
 func (f *Fetcher) resolveOpenEndedRange(conn *connection, totalSize int64) error {
@@ -1557,10 +1722,7 @@ func (f *Fetcher) resolveOpenEndedRange(conn *connection, totalSize int64) error
 		f.connMu.Unlock()
 		return err
 	}
-	f.meta.Res.Size = totalSize
-	if len(f.meta.Res.Files) > 0 && f.meta.Res.Files[0] != nil {
-		f.meta.Res.Files[0].Size = totalSize
-	}
+	f.setResourceSizeLocked(totalSize, true)
 	conn.Chunk.setEnd(totalSize - 1)
 	f.connMu.Unlock()
 	return nil
@@ -1632,10 +1794,7 @@ func (f *Fetcher) resizeSequentialResource(size int64) error {
 		return err
 	}
 
-	f.meta.Res.Size = size
-	if len(f.meta.Res.Files) > 0 {
-		f.meta.Res.Files[0].Size = size
-	}
+	f.setResourceSizeLocked(size, true)
 	f.sequentialSizeUnknown = false
 	f.connMu.Unlock()
 	return nil
@@ -1660,10 +1819,7 @@ func (f *Fetcher) beginUnknownSizeSequentialResource() error {
 		return err
 	}
 
-	f.meta.Res.Size = 0
-	if len(f.meta.Res.Files) > 0 {
-		f.meta.Res.Files[0].Size = 0
-	}
+	f.setResourceSizeLocked(0, false)
 	f.sequentialSizeUnknown = true
 	f.ifRange = ""
 	f.rangeValidatorPinned = false
@@ -1680,7 +1836,7 @@ func (f *Fetcher) runConnectionWithResolveResp(conn *connection) {
 	conn.State = connConnecting
 	f.connMu.Unlock()
 
-	buf := make([]byte, 8192)
+	buf := make([]byte, connReadBufferSize)
 
 	// Get the resolve response
 	f.resolveRespLock.Lock()
@@ -1710,7 +1866,7 @@ func (f *Fetcher) runConnectionWithResolveResp(conn *connection) {
 	}
 
 	// Download data from resolve response
-	reader := NewTimeoutReader(resp.Body, readTimeout)
+	reader := f.responseReader(resp)
 	for {
 		if conn.ctx.Err() != nil {
 			return
@@ -1747,11 +1903,9 @@ func (f *Fetcher) runConnectionWithResolveResp(conn *connection) {
 		if err != nil {
 			if err == io.EOF {
 				f.connMu.Lock()
-				if f.meta.Res.Size == 0 {
-					f.meta.Res.Size = conn.Downloaded
-					if len(f.meta.Res.Files) > 0 && f.meta.Res.Files[0] != nil {
-						f.meta.Res.Files[0].Size = conn.Downloaded
-					}
+				if !f.hasKnownSize() {
+					f.setResourceSizeLocked(conn.Downloaded, true)
+					f.sequentialSizeUnknown = false
 				}
 				conn.Completed = true
 				conn.State = connCompleted
@@ -1774,7 +1928,7 @@ func (f *Fetcher) runConnectionWithResolveResp(conn *connection) {
 func (f *Fetcher) runConnectionFallback(conn *connection) {
 	// Use fast-fail client for quick retry during download phase
 	client := f.buildFastFailClient()
-	buf := make([]byte, 8192)
+	buf := make([]byte, connReadBufferSize)
 
 	retries := 0
 	countedRetries := 0
@@ -1790,78 +1944,15 @@ func (f *Fetcher) runConnectionFallback(conn *connection) {
 		}
 
 		f.connMu.Lock()
+		if retries > 0 {
+			f.resetConnectionForRestart(conn)
+		}
 		conn.State = connConnecting
 		f.connMu.Unlock()
 
-		err := func() error {
-			httpReq, err := f.buildRequest(conn.ctx, f.meta.Req)
-			if err != nil {
-				return err
-			}
-
-			// Record connection start time for adaptive timeout tracking
-			connStartTime := time.Now()
-
-			resp, err := client.Do(httpReq)
-			if err != nil {
-				return err
-			}
-			defer resp.Body.Close()
-
-			if resp.StatusCode != base.HttpCodeOK && resp.StatusCode != base.HttpCodePartialContent {
-				return NewRequestError(resp.StatusCode)
-			}
-
-			// Record successful connection time for adaptive timeout
-			f.updateMaxConnTime(time.Since(connStartTime))
-
-			f.connMu.Lock()
-			conn.State = connDownloading
-			conn.failed = false
-			f.connMu.Unlock()
-
-			f.primaryReadyOnce.Do(func() {
-				close(f.primaryReadyCh)
-			})
-			if f.slowStart != nil {
-				f.slowStart.onConnectSuccess()
-			}
-
-			reader := NewTimeoutReader(resp.Body, readTimeout)
-			for {
-				if conn.ctx.Err() != nil {
-					return conn.ctx.Err()
-				}
-
-				n, err := reader.Read(buf)
-				if n > 0 {
-					f.connMu.Lock()
-					writeOffset := conn.Chunk.Downloaded
-					f.connMu.Unlock()
-
-					f.fileMu.Lock()
-					if f.file != nil {
-						_, writeErr := f.file.WriteAt(buf[:n], writeOffset)
-						if writeErr != nil {
-							f.fileMu.Unlock()
-							return writeErr
-						}
-					}
-					f.fileMu.Unlock()
-
-					f.connMu.Lock()
-					conn.Chunk.Downloaded += int64(n)
-					conn.Downloaded += int64(n)
-					f.connMu.Unlock()
-				}
-				if err != nil {
-					if err == io.EOF {
-						return nil
-					}
-					return err
-				}
-			}
-		}()
+		// Restored tasks without a reusable Resolve response need the same
+		// length handling and restart semantics as other sequential requests.
+		err := f.downloadChunkOnce(conn, client, buf)
 
 		if err == nil {
 			f.connMu.Lock()
@@ -1995,7 +2086,7 @@ func (f *Fetcher) resetConnectionForRestart(conn *connection) {
 	// so pause/retry must restart instead of continuing from the old offset.
 	if conn.Chunk == nil {
 		conn.Chunk = newChunk(0, 0)
-	} else {
+	} else if !f.meta.Res.Range {
 		conn.Chunk.Begin = 0
 		conn.Chunk.setEnd(0)
 		conn.Chunk.Downloaded = 0
@@ -2010,14 +2101,14 @@ func (f *Fetcher) resetConnectionForRestart(conn *connection) {
 // hasSequentialPrefixLocked reports whether a single sequential connection has
 // a useful contiguous prefix. The caller must hold connMu.
 func (f *Fetcher) hasSequentialPrefixLocked(conn *connection) bool {
-	if f.meta == nil || f.meta.Res == nil || f.meta.Res.Range || !f.rangeReprobeEligible || f.meta.Res.Size <= 0 {
+	if f.meta == nil || f.meta.Res == nil || f.meta.Res.Range || !f.rangeReprobeEligible || f.knownSize() <= 0 {
 		return false
 	}
 	if conn == nil || conn.ID != 0 || len(f.connections) != 1 || conn.Chunk == nil {
 		return false
 	}
 	downloaded := conn.Chunk.Downloaded
-	return downloaded > 0 && downloaded < f.meta.Res.Size
+	return downloaded > 0 && downloaded < f.knownSize()
 }
 
 // canProbeSequentialResumeLocked reports whether the prefix can be resumed
@@ -2103,7 +2194,7 @@ func (f *Fetcher) onDownloadComplete() {
 		needsMoreData := false
 		if f.meta.Res.Range {
 			needsMoreData = conn.Chunk != nil && (conn.Chunk.openEnded() || conn.Chunk.remain() > 0)
-		} else if f.meta.Res.Size > 0 {
+		} else if f.hasKnownSize() && f.meta.Res.Size > 0 {
 			needsMoreData = conn.Downloaded < f.meta.Res.Size
 		} else {
 			needsMoreData = !conn.Completed && conn.State != connCompleted
@@ -2113,7 +2204,7 @@ func (f *Fetcher) onDownloadComplete() {
 			// This connection has remaining work and isn't done
 			// Check if it failed with 403 (server limit) - these can be ignored if other connections completed the work
 			if conn.State == connFailed && conn.failed {
-				if re := extractRequestError(conn.lastErr); re != nil && re.Code == 403 {
+				if re := extractRequestError(conn.lastErr); re != nil && re.Code == 403 && f.hasKnownSize() {
 					// 403 is server connection limit, check if other connections will complete this chunk
 					continue
 				}
@@ -2124,7 +2215,7 @@ func (f *Fetcher) onDownloadComplete() {
 	}
 
 	// If total downloaded matches file size, consider it a success regardless of connection failures
-	downloadComplete := f.meta.Res.Size > 0 && totalDownloaded >= f.meta.Res.Size
+	downloadComplete := f.hasKnownSize() && f.meta.Res.Size > 0 && totalDownloaded >= f.meta.Res.Size
 
 	// Integrity errors must win over byte-count completion. A malformed response
 	// may be detected only after the expected bytes have already been written.
@@ -2141,7 +2232,7 @@ func (f *Fetcher) onDownloadComplete() {
 		for _, conn := range f.connections {
 			if conn.State == connFailed && conn.failed {
 				// Skip 403 errors (server connection limit) - these are expected when exceeding server's limit
-				if re := extractRequestError(conn.lastErr); re != nil && re.Code == 403 {
+				if re := extractRequestError(conn.lastErr); re != nil && re.Code == 403 && f.hasKnownSize() {
 					continue
 				}
 				if re := extractRequestError(conn.lastErr); re != nil {
@@ -2166,10 +2257,15 @@ func (f *Fetcher) onDownloadComplete() {
 	}
 	f.fileMu.Unlock()
 
-	if finalErr != nil {
-		f.setState(stateError)
+	if finalErr == nil {
+		if chkErr := f.verifyChecksum(); chkErr != nil {
+			finalErr = chkErr
+			f.setState(stateError)
+		} else {
+			f.setState(stateDone)
+		}
 	} else {
-		f.setState(stateDone)
+		f.setState(stateError)
 	}
 
 	select {
@@ -2178,6 +2274,51 @@ func (f *Fetcher) onDownloadComplete() {
 	}
 }
 
+func (f *Fetcher) verifyChecksum() error {
+	if f.meta == nil || f.meta.Opts == nil || f.meta.Opts.Extra == nil {
+		return nil
+	}
+	extra, ok := f.meta.Opts.Extra.(*fhttp.OptsExtra)
+	if !ok || extra.Checksum == nil {
+		return nil
+	}
+	chk := extra.Checksum
+	if chk.Algorithm == "" && chk.Expected == "" {
+		return nil
+	}
+	var h hash.Hash
+	switch strings.ToLower(strings.TrimSpace(chk.Algorithm)) {
+	case "md5":
+		h = md5.New()
+	case "sha1", "sha-1":
+		h = sha1.New()
+	case "sha256", "sha-256":
+		h = sha256.New()
+	default:
+		return fmt.Errorf("unsupported checksum algorithm: %s", chk.Algorithm)
+	}
+
+	filePath := f.meta.SingleFilepath()
+	file, err := os.Open(filePath)
+	if err != nil {
+		return fmt.Errorf("open file for checksum verification failed: %w", err)
+	}
+	defer file.Close()
+
+	buf := make([]byte, 64*1024)
+	if _, err := io.CopyBuffer(h, file, buf); err != nil {
+		return fmt.Errorf("calculate checksum failed: %w", err)
+	}
+
+	actual := hex.EncodeToString(h.Sum(nil))
+	expected := strings.ToLower(strings.TrimSpace(chk.Expected))
+	if !strings.EqualFold(actual, expected) {
+		f.checksumFailed.Store(true)
+		return fmt.Errorf("checksum mismatch: expected %s, got %s", expected, actual)
+	}
+	return nil
+}
+
 func (f *Fetcher) checkCompletion() bool {
 	// Check if all data has been downloaded
 	f.connMu.Lock()
@@ -2191,7 +2332,7 @@ func (f *Fetcher) checkCompletion() bool {
 		totalDownloaded += conn.Downloaded
 	}
 
-	if f.meta.Res.Size > 0 && totalDownloaded >= f.meta.Res.Size {
+	if f.hasKnownSize() && f.meta.Res.Size > 0 && totalDownloaded >= f.meta.Res.Size {
 		// Don't start a new goroutine - let the caller handle completion
 		return true
 	}
@@ -2218,6 +2359,14 @@ func (f *Fetcher) checkCompletion() bool {
 
 // Patch modifies the HTTP request information.
 func (f *Fetcher) Patch(req *base.Request, opts *base.Options) error {
+	if opts != nil && opts.Size > 0 {
+		f.connMu.Lock()
+		f.meta.Opts.Size = opts.Size
+		if f.meta.Res != nil && !f.hasKnownSize() {
+			f.setResourceSizeLocked(0, false)
+		}
+		f.connMu.Unlock()
+	}
 	// Patch request info
 	if req != nil {
 		if req.URL != "" {
@@ -2315,8 +2464,8 @@ func (f *Fetcher) Pause() error {
 				conn := f.connections[0]
 				if conn != nil && conn.ID == 0 && conn.Chunk != nil && !conn.Completed {
 					conn.Chunk.Begin = prefetched
-					if f.meta.Res.Size > 0 {
-						conn.Chunk.setEnd(f.meta.Res.Size - 1)
+					if f.knownSize() > 0 {
+						conn.Chunk.setEnd(f.knownSize() - 1)
 					} else {
 						conn.Chunk.End = nil
 					}
@@ -2450,3 +2599,12 @@ func (f *Fetcher) Progress() fetcher.Progress {
 func (f *Fetcher) Wait() error {
 	return <-f.doneCh
 }
+
+// Generated output can pause while its producer waits for processing capacity.
+// Its producer owns upstream deadlines; cancellation still closes the response.
+func (f *Fetcher) responseReader(resp *http.Response) io.Reader {
+	if f.ctl != nil && f.ctl.ManagedProduction != nil && resp.Request != nil && f.ctl.ManagedProduction(resp.Request.URL.String()) {
+		return resp.Body
+	}
+	return NewTimeoutReader(resp.Body, readTimeout)
+}

internal/protocol/http/fetcher_checksum_retry_test.go

@@ -0,0 +1,391 @@
+package http
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	gohttp "net/http"
+	"net/http/httptest"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/pkg/base"
+	"github.com/GopeedLab/gopeed/pkg/protocol/http"
+)
+
+// serveRangeContent serves byte range requests or full responses from data.
+func serveRangeContent(w gohttp.ResponseWriter, r *gohttp.Request, data []byte) {
+	w.Header().Set(base.HttpHeaderAcceptRanges, base.HttpHeaderBytes)
+	rangeHdr := r.Header.Get(base.HttpHeaderRange)
+	total := int64(len(data))
+	if rangeHdr == "" {
+		w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", total))
+		w.WriteHeader(gohttp.StatusOK)
+		_, _ = w.Write(data)
+		return
+	}
+
+	// Parse bytes=start-end or bytes=start-
+	if !strings.HasPrefix(rangeHdr, "bytes=") {
+		w.WriteHeader(gohttp.StatusBadRequest)
+		return
+	}
+	spec := strings.TrimPrefix(rangeHdr, "bytes=")
+	parts := strings.Split(spec, "-")
+	start, err := strconv.ParseInt(parts[0], 10, 64)
+	if err != nil || start < 0 || start >= total {
+		w.WriteHeader(gohttp.StatusRequestedRangeNotSatisfiable)
+		return
+	}
+	end := total - 1
+	if len(parts) > 1 && parts[1] != "" {
+		if parsedEnd, err := strconv.ParseInt(parts[1], 10, 64); err == nil && parsedEnd >= start && parsedEnd < total {
+			end = parsedEnd
+		}
+	}
+
+	contentLength := end - start + 1
+	w.Header().Set(base.HttpHeaderContentRange, fmt.Sprintf("bytes %d-%d/%d", start, end, total))
+	w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", contentLength))
+	w.WriteHeader(gohttp.StatusPartialContent)
+	_, _ = w.Write(data[start : end+1])
+}
+
+func TestFetcher_ChecksumMismatch_Retry(t *testing.T) {
+	corruptContent := []byte("Corrupt Initial Download Data 33B")
+	correctContent := []byte("Correct Retried Download Data 33B")
+
+	correctSha256Hasher := sha256.New()
+	correctSha256Hasher.Write(correctContent)
+	correctSha256 := hex.EncodeToString(correctSha256Hasher.Sum(nil))
+
+	var phase atomic.Int32 // 0: serve corruptContent, 1: serve correctContent
+	server := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+		var served []byte
+		if phase.Load() == 0 {
+			served = corruptContent
+		} else {
+			served = correctContent
+		}
+		serveRangeContent(w, r, served)
+	}))
+	defer server.Close()
+
+	downloadDir := t.TempDir()
+	fileName := "test_checksum_retry.txt"
+
+	f := buildFetcher()
+	defer f.Close()
+
+	opts := &base.Options{
+		Path: downloadDir,
+		Name: fileName,
+		Extra: &http.OptsExtra{
+			Connections: 1,
+			Checksum: &http.ChecksumOption{
+				Algorithm: "sha256",
+				Expected:  correctSha256,
+			},
+		},
+	}
+
+	// 1. Initial attempt -> will download corruptContent, failing checksum verification
+	if err := f.Resolve(&base.Request{URL: server.URL + "/retry_test.txt"}); err != nil {
+		t.Fatalf("Resolve error: %v", err)
+	}
+	f.Meta().Opts = opts
+	if err := f.Start(); err != nil {
+		t.Fatalf("Start error: %v", err)
+	}
+	err := f.Wait()
+	if err == nil {
+		t.Fatal("expected checksum mismatch error on initial attempt, got nil")
+	}
+	if !strings.Contains(err.Error(), "checksum mismatch") {
+		t.Fatalf("expected 'checksum mismatch' in error, got %v", err)
+	}
+	if f.getState() != stateError {
+		t.Fatalf("expected stateError after checksum mismatch, got %v", f.getState())
+	}
+
+	// Flip phase to 1 after observing checksum mismatch
+	phase.Store(1)
+
+	// 2. Retry download -> should trigger forced full reset, truncate file, and re-download correctContent
+	if err := f.Start(); err != nil {
+		t.Fatalf("Start error on retry: %v", err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("Wait error on retry (expected success): %v", err)
+	}
+	if f.getState() != stateDone {
+		t.Fatalf("expected stateDone after successful retry, got %v", f.getState())
+	}
+
+	// 3. Verify on-disk file content matches the re-downloaded bytes
+	filePath := f.meta.SingleFilepath()
+	fileBytes, err := os.ReadFile(filePath)
+	if err != nil {
+		t.Fatalf("failed to read completed file: %v", err)
+	}
+	if string(fileBytes) != string(correctContent) {
+		t.Fatalf("on-disk file content mismatch:\ngot:  %q\nwant: %q", string(fileBytes), string(correctContent))
+	}
+
+	// 4. Compute hash independently and verify
+	actualHasher := sha256.New()
+	actualHasher.Write(fileBytes)
+	actualHash := hex.EncodeToString(actualHasher.Sum(nil))
+	if actualHash != correctSha256 {
+		t.Fatalf("re-computed on-disk hash mismatch: got %s, want %s", actualHash, correctSha256)
+	}
+}
+
+func TestFetcher_ChecksumMismatch_Retry_PartialPrefetch(t *testing.T) {
+	corruptContent := []byte("Corrupt Initial Download Data 33B")
+	correctContent := []byte("Correct Retried Download Data 33B")
+
+	correctSha256Hasher := sha256.New()
+	correctSha256Hasher.Write(correctContent)
+	correctSha256 := hex.EncodeToString(correctSha256Hasher.Sum(nil))
+
+	var phase atomic.Int32 // 0: corrupt, 1: correct
+	var isFirstRequest atomic.Bool
+	isFirstRequest.Store(true)
+
+	releasePrefetch := make(chan struct{})
+	var closeReleaseOnce sync.Once
+
+	var mu sync.Mutex
+	var phase1Ranges []string
+
+	server := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+		curPhase := phase.Load()
+		if curPhase == 1 {
+			mu.Lock()
+			phase1Ranges = append(phase1Ranges, r.Header.Get(base.HttpHeaderRange))
+			mu.Unlock()
+			serveRangeContent(w, r, correctContent)
+			return
+		}
+
+		// Phase 0: First request is Resolve GET without Range header.
+		// Write exactly 7 bytes and flush, then block until release channel closes or context is done.
+		if isFirstRequest.CompareAndSwap(true, false) {
+			w.Header().Set(base.HttpHeaderAcceptRanges, base.HttpHeaderBytes)
+			w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", len(corruptContent)))
+			w.WriteHeader(gohttp.StatusOK)
+			_, _ = w.Write(corruptContent[:7])
+			if flusher, ok := w.(gohttp.Flusher); ok {
+				flusher.Flush()
+			}
+			select {
+			case <-releasePrefetch:
+			case <-r.Context().Done():
+			}
+			return
+		}
+
+		// Subsequent requests in Phase 0 (such as Range request from Start)
+		serveRangeContent(w, r, corruptContent)
+	}))
+	defer server.Close()
+	defer closeReleaseOnce.Do(func() { close(releasePrefetch) })
+
+	downloadDir := t.TempDir()
+	fileName := "test_checksum_prefetch_retry.txt"
+
+	f := buildFetcher()
+	defer f.Close()
+
+	opts := &base.Options{
+		Path: downloadDir,
+		Name: fileName,
+		Extra: &http.OptsExtra{
+			Connections: 1,
+			Checksum: &http.ChecksumOption{
+				Algorithm: "sha256",
+				Expected:  correctSha256,
+			},
+		},
+	}
+
+	// 1. Resolve phase
+	if err := f.Resolve(&base.Request{URL: server.URL + "/prefetch_retry.txt"}); err != nil {
+		t.Fatalf("Resolve error: %v", err)
+	}
+	f.Meta().Opts = opts
+
+	// Wait until prefetch has received exactly 7 bytes
+	for i := 0; i < 200; i++ {
+		if f.prefetchSize.Load() >= 7 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if f.prefetchSize.Load() < 7 {
+		t.Fatalf("expected at least 7 prefetched bytes, got %d", f.prefetchSize.Load())
+	}
+
+	// Release prefetch handler right before Start
+	closeReleaseOnce.Do(func() { close(releasePrefetch) })
+
+	// 2. Start initial download attempt (will complete with corruptContent and fail checksum)
+	if err := f.Start(); err != nil {
+		t.Fatalf("Start error: %v", err)
+	}
+	err := f.Wait()
+	if err == nil {
+		t.Fatal("expected checksum mismatch error on initial attempt, got nil")
+	}
+	if !strings.Contains(err.Error(), "checksum mismatch") {
+		t.Fatalf("expected 'checksum mismatch' in error, got %v", err)
+	}
+	if f.getState() != stateError {
+		t.Fatalf("expected stateError after checksum mismatch, got %v", f.getState())
+	}
+
+	// 3. Flip to phase 1 (correctContent) and retry
+	phase.Store(1)
+
+	if err := f.Start(); err != nil {
+		t.Fatalf("Start error on retry: %v", err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("Wait error on retry (expected success): %v", err)
+	}
+	if f.getState() != stateDone {
+		t.Fatalf("expected stateDone after successful retry, got %v", f.getState())
+	}
+
+	// Verify that in Phase 1 at least one Range request started at byte 0
+	mu.Lock()
+	rangesSeen := append([]string(nil), phase1Ranges...)
+	mu.Unlock()
+
+	hasByteZero := false
+	for _, r := range rangesSeen {
+		if strings.HasPrefix(r, "bytes=0-") {
+			hasByteZero = true
+			break
+		}
+	}
+	if !hasByteZero {
+		t.Fatalf("expected at least one Phase 1 Range request starting at byte 0, saw: %v", rangesSeen)
+	}
+
+	// Verify on-disk content matches correctContent exactly
+	filePath := f.meta.SingleFilepath()
+	fileBytes, err := os.ReadFile(filePath)
+	if err != nil {
+		t.Fatalf("failed to read completed file: %v", err)
+	}
+	if string(fileBytes) != string(correctContent) {
+		t.Fatalf("on-disk file content mismatch:\ngot:  %q\nwant: %q", string(fileBytes), string(correctContent))
+	}
+
+	// Compute hash independently and verify
+	actualHasher := sha256.New()
+	actualHasher.Write(fileBytes)
+	actualHash := hex.EncodeToString(actualHasher.Sum(nil))
+	if actualHash != correctSha256 {
+		t.Fatalf("re-computed on-disk hash mismatch: got %s, want %s", actualHash, correctSha256)
+	}
+}
+
+func TestFetcher_ChecksumMismatch_Retry_NonRange(t *testing.T) {
+	corruptContent := []byte("Corrupt Non-Range Initial Data 33B")
+	correctContent := []byte("Correct Non-Range Retried Data 33B")
+
+	correctSha256Hasher := sha256.New()
+	correctSha256Hasher.Write(correctContent)
+	correctSha256 := hex.EncodeToString(correctSha256Hasher.Sum(nil))
+
+	var phase atomic.Int32 // 0: corrupt, 1: correct
+	server := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+		// Server does not support Range (always returns full content 200 OK)
+		var served []byte
+		if phase.Load() == 0 {
+			served = corruptContent
+		} else {
+			served = correctContent
+		}
+		w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", len(served)))
+		w.WriteHeader(gohttp.StatusOK)
+		_, _ = w.Write(served)
+	}))
+	defer server.Close()
+
+	downloadDir := t.TempDir()
+	fileName := "test_checksum_nonrange_retry.txt"
+
+	f := buildFetcher()
+	defer f.Close()
+
+	opts := &base.Options{
+		Path: downloadDir,
+		Name: fileName,
+		Extra: &http.OptsExtra{
+			Connections: 1,
+			Checksum: &http.ChecksumOption{
+				Algorithm: "sha256",
+				Expected:  correctSha256,
+			},
+		},
+	}
+
+	// 1. Resolve and start initial attempt
+	if err := f.Resolve(&base.Request{URL: server.URL + "/nonrange_retry.txt"}); err != nil {
+		t.Fatalf("Resolve error: %v", err)
+	}
+	f.Meta().Opts = opts
+	if err := f.Start(); err != nil {
+		t.Fatalf("Start error: %v", err)
+	}
+	err := f.Wait()
+	if err == nil {
+		t.Fatal("expected checksum mismatch error on initial non-range attempt, got nil")
+	}
+	if !strings.Contains(err.Error(), "checksum mismatch") {
+		t.Fatalf("expected 'checksum mismatch' in error, got %v", err)
+	}
+	if f.getState() != stateError {
+		t.Fatalf("expected stateError after checksum mismatch, got %v", f.getState())
+	}
+
+	// 2. Switch phase and retry
+	phase.Store(1)
+
+	if err := f.Start(); err != nil {
+		t.Fatalf("Start error on non-range retry: %v", err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatalf("Wait error on non-range retry (expected success): %v", err)
+	}
+	if f.getState() != stateDone {
+		t.Fatalf("expected stateDone after successful non-range retry, got %v", f.getState())
+	}
+
+	// 3. Verify on-disk file content
+	filePath := f.meta.SingleFilepath()
+	fileBytes, err := os.ReadFile(filePath)
+	if err != nil {
+		t.Fatalf("failed to read completed file: %v", err)
+	}
+	if string(fileBytes) != string(correctContent) {
+		t.Fatalf("on-disk file content mismatch:\ngot:  %q\nwant: %q", string(fileBytes), string(correctContent))
+	}
+
+	// 4. Compute hash independently and verify
+	actualHasher := sha256.New()
+	actualHasher.Write(fileBytes)
+	actualHash := hex.EncodeToString(actualHasher.Sum(nil))
+	if actualHash != correctSha256 {
+		t.Fatalf("re-computed on-disk hash mismatch: got %s, want %s", actualHash, correctSha256)
+	}
+}

internal/protocol/http/fetcher_checksum_test.go

@@ -0,0 +1,327 @@
+package http
+
+import (
+	"crypto/md5"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	gohttp "net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"github.com/GopeedLab/gopeed/internal/test"
+	"github.com/GopeedLab/gopeed/pkg/base"
+	"github.com/GopeedLab/gopeed/pkg/protocol/http"
+)
+
+func TestFetcher_ChecksumVerification(t *testing.T) {
+	content := []byte("Hello, Gopeed Checksum Verification Test Data!")
+	md5Hasher := md5.New()
+	md5Hasher.Write(content)
+	correctMd5 := hex.EncodeToString(md5Hasher.Sum(nil))
+
+	sha256Hasher := sha256.New()
+	sha256Hasher.Write(content)
+	correctSha256 := hex.EncodeToString(sha256Hasher.Sum(nil))
+
+	wrongHash := "0123456789abcdef0123456789abcdef"
+
+	server := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+		w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", len(content)))
+		w.Header().Set(base.HttpHeaderAcceptRanges, base.HttpHeaderBytes)
+		w.WriteHeader(gohttp.StatusOK)
+		_, _ = w.Write(content)
+	}))
+	defer server.Close()
+
+	t.Run("Valid MD5", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_valid_md5.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "md5",
+					Expected:  correctMd5,
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		if err := f.Wait(); err != nil {
+			t.Fatalf("Wait error (expected success): %v", err)
+		}
+	})
+
+	t.Run("Valid SHA256", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_valid_sha256.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "sha256",
+					Expected:  correctSha256,
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		if err := f.Wait(); err != nil {
+			t.Fatalf("Wait error (expected success): %v", err)
+		}
+	})
+
+	t.Run("Wrong MD5 mismatch", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_wrong_md5.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "md5",
+					Expected:  wrongHash,
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		err := f.Wait()
+		if err == nil {
+			t.Fatal("Wait expected checksum mismatch error, got nil")
+		}
+		if !strings.Contains(err.Error(), "checksum mismatch") {
+			t.Fatalf("expected 'checksum mismatch' in error, got %v", err)
+		}
+	})
+
+	t.Run("Unsupported Algorithm", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_unsupported.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "invalid-algo",
+					Expected:  wrongHash,
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+		f.Meta().Opts = opts
+		err := f.Start()
+		if err == nil {
+			t.Fatal("Start expected error for unsupported algorithm, got nil")
+		}
+		if !strings.Contains(err.Error(), "unsupported checksum algorithm") {
+			t.Fatalf("expected 'unsupported checksum algorithm' in error, got %v", err)
+		}
+		if f.checksumFailed.Load() {
+			t.Fatal("checksumFailed flag should NOT be set on unsupported algorithm error")
+		}
+	})
+
+	t.Run("Case-Insensitive Hash Comparison", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_case_insensitive.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "sha256",
+					Expected:  strings.ToUpper(correctSha256),
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		if err := f.Wait(); err != nil {
+			t.Fatalf("Wait error (expected success with upper case hash): %v", err)
+		}
+	})
+
+	t.Run("Empty Expected Checksum (Skipped)", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_empty_expected.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "",
+					Expected:  "",
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		if err := f.Wait(); err != nil {
+			t.Fatalf("Wait error (expected skip and success): %v", err)
+		}
+	})
+
+	t.Run("Large File Multi-Chunk Streaming (>64KB)", func(t *testing.T) {
+		largeData := make([]byte, 128*1024)
+		for i := range largeData {
+			largeData[i] = byte(i % 256)
+		}
+		largeSha256Hasher := sha256.New()
+		largeSha256Hasher.Write(largeData)
+		largeSha256 := hex.EncodeToString(largeSha256Hasher.Sum(nil))
+
+		largeServer := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+			w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", len(largeData)))
+			w.Header().Set(base.HttpHeaderAcceptRanges, base.HttpHeaderBytes)
+			w.WriteHeader(gohttp.StatusOK)
+			_, _ = w.Write(largeData)
+		}))
+		defer largeServer.Close()
+
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_large_file.bin",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "sha256",
+					Expected:  largeSha256,
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: largeServer.URL + "/large.bin"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		if err := f.Wait(); err != nil {
+			t.Fatalf("Wait error (expected large file checksum success): %v", err)
+		}
+	})
+
+	t.Run("No Checksum (Opt-in backward compatibility)", func(t *testing.T) {
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: test.DownloadName,
+			Extra: &http.OptsExtra{
+				Connections: 1,
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: server.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+
+		f.Meta().Opts = opts
+		if err := f.Start(); err != nil {
+			t.Fatalf("Start error: %v", err)
+		}
+		if err := f.Wait(); err != nil {
+			t.Fatalf("Wait error: %v", err)
+		}
+	})
+
+	t.Run("Invalid Checksum In Start Makes No Additional Requests", func(t *testing.T) {
+		var reqReceived atomic.Int32
+		customServer := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+			reqReceived.Add(1)
+			w.WriteHeader(gohttp.StatusOK)
+			_, _ = w.Write([]byte("some data"))
+		}))
+		defer customServer.Close()
+
+		f := buildFetcher()
+		defer f.Close()
+
+		opts := &base.Options{
+			Path: t.TempDir(),
+			Name: "test_invalid_checksum.txt",
+			Extra: &http.OptsExtra{
+				Connections: 1,
+				Checksum: &http.ChecksumOption{
+					Algorithm: "sha256",
+					Expected:  "invalid-hex-chars-not-valid-hex-00000000000000000000000000000000",
+				},
+			},
+		}
+
+		if err := f.Resolve(&base.Request{URL: customServer.URL + "/test.txt"}); err != nil {
+			t.Fatalf("Resolve error: %v", err)
+		}
+		requestsAfterResolve := reqReceived.Load()
+		f.Meta().Opts = opts
+		err := f.Start()
+		if err == nil {
+			t.Fatal("Start expected error for invalid checksum hash, got nil")
+		}
+		if got := reqReceived.Load(); got != requestsAfterResolve {
+			t.Fatalf("invalid checksum in Start issued additional requests: got %d, had %d after Resolve", got, requestsAfterResolve)
+		}
+	})
+}

internal/protocol/http/fetcher_manager.go

@@ -19,10 +19,11 @@ type fetcherData struct {
 	IfRange               string // Strong ETag or Last-Modified validator for safe resume
 	RangeReprobeEligible  bool   // Origin advertised Range before falling back to sequential mode
 	RangeValidatorPinned  bool   // Recovered Range mode must keep the same If-Range validator
-	SequentialSizeUnknown bool   // Interrupted chunked restart must retry from byte zero
+	SequentialSizeUnknown bool   // Interrupted chunked sequential streams restart from byte zero
+	SizeKnown             *bool  // Nil for legacy snapshots; false means Size is only a display estimate
 	Range                 *bool  // Authoritative Range mode; nil for records saved by older versions
-	ResourceSize          *int64 // Authoritative resource size from the same snapshot as Connections
-	FileSize              *int64 // Authoritative single-file size; nil for older records
+	ResourceSize          *int64 // Display size from the same snapshot; authority is recorded by SizeKnown
+	FileSize              *int64 // Single-file size from the same snapshot; nil for older records
 }
 
 // ============================================================================
@@ -72,7 +73,7 @@ func (fm *FetcherManager) AutoRename() bool {
 
 func (fm *FetcherManager) DefaultConfig() any {
 	return &config{
-		UserAgent:   "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
+		UserAgent:   DefaultUserAgent,
 		Connections: 16,
 	}
 }
@@ -93,6 +94,7 @@ func (fm *FetcherManager) Store(f fetcher.Fetcher) (data any, err error) {
 	rangeReprobeEligible := _f.rangeReprobeEligible
 	rangeValidatorPinned := _f.rangeValidatorPinned
 	sequentialSizeUnknown := _f.sequentialSizeUnknown
+	sizeKnown := _f.hasKnownSize()
 	var rangeMode *bool
 	var resourceSize *int64
 	var fileSize *int64
@@ -115,6 +117,7 @@ func (fm *FetcherManager) Store(f fetcher.Fetcher) (data any, err error) {
 		RangeReprobeEligible:  rangeReprobeEligible,
 		RangeValidatorPinned:  rangeValidatorPinned,
 		SequentialSizeUnknown: sequentialSizeUnknown,
+		SizeKnown:             &sizeKnown,
 		Range:                 rangeMode,
 		ResourceSize:          resourceSize,
 		FileSize:              fileSize,
@@ -168,6 +171,10 @@ func (fm *FetcherManager) Restore() (v any, f func(meta *fetcher.FetcherMeta, v
 		fetcher.rangeReprobeEligible = fd.RangeReprobeEligible
 		fetcher.rangeValidatorPinned = fd.RangeValidatorPinned
 		fetcher.sequentialSizeUnknown = fd.SequentialSizeUnknown
+		if fd.SizeKnown != nil {
+			known := *fd.SizeKnown
+			fetcher.sizeKnown = &known
+		}
 		if fd.Range != nil && fetcher.meta.Res != nil {
 			// Recovery-critical resource fields live in the same persisted snapshot
 			// as Connections, making them authoritative over task metadata that may

internal/protocol/http/fetcher_test.go

@@ -13,6 +13,7 @@ import (
 	"net/url"
 	"os"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
@@ -221,11 +222,40 @@ func TestFetcher_Resolve(t *testing.T) {
 	})
 }
 
+func TestFetcher_ResolveFilenameFromContentType(t *testing.T) {
+	server := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
+		w.Header().Set("Content-Type", "image/webp")
+		w.WriteHeader(gohttp.StatusOK)
+	}))
+	defer server.Close()
+
+	fetcher := buildFetcher()
+	defer fetcher.Pause()
+
+	const opaqueName = "OIP-C.u5nEXTXND3PJF0gNTgw5YgHaFP"
+	fetcher.Meta().Opts = &base.Options{
+		Name: test.DownloadName,
+		Path: test.Dir,
+	}
+	err := fetcher.Resolve(&base.Request{URL: server.URL + "/" + opaqueName})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if got := fetcher.meta.Res.Files[0].Name; got != opaqueName+".webp" {
+		t.Fatalf("resolved filename = %q, want %q", got, opaqueName+".webp")
+	}
+}
+
 func TestFetcher_ResolveWithHostHeader(t *testing.T) {
 	listener := test.StartTestHostHeaderServer()
 	defer listener.Close()
 
 	fetcher := buildFetcher()
+	fetcher.Meta().Opts = &base.Options{
+		Name: test.DownloadName,
+		Path: test.Dir,
+	}
 	err := fetcher.Resolve(&base.Request{
 		URL: "http://" + listener.Addr().String() + "/",
 		Extra: &http.ReqExtra{
@@ -233,9 +263,6 @@ func TestFetcher_ResolveWithHostHeader(t *testing.T) {
 				"Host": "test",
 			},
 		},
-	}, &base.Options{
-		Name: test.DownloadName,
-		Path: test.Dir,
 	})
 	// The server should return 400 for invalid Host header
 	if err == nil || !strings.Contains(err.Error(), "400") {
@@ -249,6 +276,10 @@ func TestFetcher_ResolveWithInvalidHeader(t *testing.T) {
 
 	fetcher := buildFetcher()
 	defer fetcher.Pause() // Close the resolve response to allow server shutdown
+	fetcher.Meta().Opts = &base.Options{
+		Name: test.DownloadName,
+		Path: test.Dir,
+	}
 	err := fetcher.Resolve(&base.Request{
 		URL: "http://" + listener.Addr().String() + "/",
 		Extra: &http.ReqExtra{
@@ -256,9 +287,6 @@ func TestFetcher_ResolveWithInvalidHeader(t *testing.T) {
 				"Referer": "\rtest",
 			},
 		},
-	}, &base.Options{
-		Name: test.DownloadName,
-		Path: test.Dir,
 	})
 	// Invalid header with \r should be sanitized by Go's http client, allowing the request to succeed
 	if err != nil {
@@ -278,12 +306,13 @@ func TestFetcher_ResolveAutomaticallyFallsBackToBrowserFingerprint(t *testing.T)
 
 	fetcher := buildFetcher()
 	defer fetcher.Pause()
+	fetcher.Meta().Opts = &base.Options{
+		Name: test.DownloadName,
+		Path: test.Dir,
+	}
 	err := fetcher.Resolve(&base.Request{
 		URL:            server.URL + "/file.bin",
 		SkipVerifyCert: true,
-	}, &base.Options{
-		Name: test.DownloadName,
-		Path: test.Dir,
 	})
 	if err != nil {
 		t.Fatalf("Resolve() error = %v", err)
@@ -344,11 +373,12 @@ func testResolve(startTestServer func() net.Listener, path string, t *testing.T,
 	defer listener.Close()
 	fetcher := buildFetcher()
 	defer fetcher.Pause() // Close the resolve response to allow server shutdown
-	err := fetcher.Resolve(&base.Request{
-		URL: "http://" + listener.Addr().String() + "/" + path,
-	}, &base.Options{
+	fetcher.Meta().Opts = &base.Options{
 		Name: test.DownloadName,
 		Path: test.Dir,
+	}
+	err := fetcher.Resolve(&base.Request{
+		URL: "http://" + listener.Addr().String() + "/" + path,
 	})
 	want, err := wantFn(err)
 	if err != nil {
@@ -400,13 +430,14 @@ func TestFetcher_PauseBeforeStartDiscardsPrefetchProgress(t *testing.T) {
 	defer server.Close()
 
 	fetcher := buildFetcher()
-	if err := fetcher.Resolve(&base.Request{URL: server.URL + "/" + test.BuildName}, &base.Options{
+	fetcher.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: test.DownloadName,
 		Extra: &http.OptsExtra{
 			Connections: 2,
 		},
-	}); err != nil {
+	}
+	if err := fetcher.Resolve(&base.Request{URL: server.URL + "/" + test.BuildName}); err != nil {
 		t.Fatal(err)
 	}
 	select {
@@ -747,13 +778,14 @@ func TestFetcher_SequentialRetryReprobesRange(t *testing.T) {
 			defer server.Close()
 
 			f := buildFetcher()
-			if err := f.Resolve(&base.Request{URL: server.URL + "/dynamic-range.data"}, &base.Options{
+			f.Meta().Opts = &base.Options{
 				Path: t.TempDir(),
 				Name: "dynamic-range.data",
 				Extra: &http.OptsExtra{
 					Connections: 4,
 				},
-			}); err != nil {
+			}
+			if err := f.Resolve(&base.Request{URL: server.URL + "/dynamic-range.data"}); err != nil {
 				t.Fatal(err)
 			}
 			if err := f.Start(); err != nil {
@@ -829,31 +861,44 @@ func TestFetcher_InitialIgnoredRangeUsesResponseSize(t *testing.T) {
 	resolvePayload := bytes.Repeat([]byte("resolve"), 64*1024)
 	replacement := bytes.Repeat([]byte("replacement"), 24*1024)
 	var rangeRequests atomic.Int32
+	rangeStarted := make(chan struct{})
+	releaseResolve := sync.OnceFunc(func() { close(rangeStarted) })
 
 	server := httptest.NewServer(gohttp.HandlerFunc(func(w gohttp.ResponseWriter, r *gohttp.Request) {
 		w.Header().Set(base.HttpHeaderAcceptRanges, base.HttpHeaderBytes)
 		if r.Header.Get(base.HttpHeaderRange) == "" {
 			w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", len(resolvePayload)))
 			w.WriteHeader(gohttp.StatusOK)
+			w.(gohttp.Flusher).Flush()
+			// Keep Resolve prefetch incomplete until the Range request starts.
+			// Otherwise Start may reuse the completed body and skip this scenario.
+			select {
+			case <-rangeStarted:
+			case <-r.Context().Done():
+				return
+			}
 			_, _ = w.Write(resolvePayload)
 			return
 		}
 
 		rangeRequests.Add(1)
+		releaseResolve()
 		w.Header().Set(base.HttpHeaderContentLength, fmt.Sprintf("%d", len(replacement)))
 		w.WriteHeader(gohttp.StatusOK)
 		_, _ = w.Write(replacement)
 	}))
 	defer server.Close()
+	defer releaseResolve()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/ignored-range.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "ignored-range.data",
 		Extra: &http.OptsExtra{
 			Connections: 4,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/ignored-range.data"}); err != nil {
 		t.Fatal(err)
 	}
 	if err := f.Start(); err != nil {
@@ -944,13 +989,14 @@ func TestFetcher_InterruptedChunkedReplacementRestartsFromZero(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/chunked-replacement.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "chunked-replacement.data",
 		Extra: &http.OptsExtra{
 			Connections: 4,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/chunked-replacement.data"}); err != nil {
 		t.Fatal(err)
 	}
 	if err := f.Start(); err != nil {
@@ -1130,13 +1176,14 @@ func TestFetcher_UsesResolveResponseWhenRangeTakeoverFails(t *testing.T) {
 			defer server.Close()
 
 			f := buildFetcher()
-			if err := f.Resolve(&base.Request{URL: server.URL + "/resolve-fallback.data"}, &base.Options{
+			f.Meta().Opts = &base.Options{
 				Path: t.TempDir(),
 				Name: "resolve-fallback.data",
 				Extra: &http.OptsExtra{
 					Connections: 1,
 				},
-			}); err != nil {
+			}
+			if err := f.Resolve(&base.Request{URL: server.URL + "/resolve-fallback.data"}); err != nil {
 				t.Fatal(err)
 			}
 			defer f.Close()
@@ -1209,13 +1256,14 @@ func TestFetcher_ValidRangeTakesOverResolveResponse(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/resolve-takeover.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "resolve-takeover.data",
 		Extra: &http.OptsExtra{
 			Connections: 4,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/resolve-takeover.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
@@ -1239,6 +1287,12 @@ func TestFetcher_ValidRangeTakesOverResolveResponse(t *testing.T) {
 }
 
 func TestFetcher_UnknownSizeRangeUsesOpenEndedWorker(t *testing.T) {
+	for _, hint := range []int64{0, 3, 8 * 1024 * 1024} {
+		t.Run(fmt.Sprint(hint), func(t *testing.T) { testFetcherUnknownSizeRange(t, hint) })
+	}
+}
+
+func testFetcherUnknownSizeRange(t *testing.T, hint int64) {
 	const resolveETag = `"unknown-size-v1"`
 	payload := make([]byte, 4*1024*1024)
 	for i := range payload {
@@ -1303,18 +1357,20 @@ func TestFetcher_UnknownSizeRangeUsesOpenEndedWorker(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/unknown-size-range.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
+		Size: hint,
 		Path: t.TempDir(),
 		Name: "unknown-size-range.data",
 		Extra: &http.OptsExtra{
 			Connections: 4,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/unknown-size-range.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
 
-	if f.meta.Res.Size != 0 || !f.meta.Res.Range {
+	if f.meta.Res.Size != hint || f.hasKnownSize() || !f.meta.Res.Range {
 		t.Fatalf("resolved resource = %+v, want unknown size with Range support", f.meta.Res)
 	}
 	if err := f.Start(); err != nil {
@@ -1397,13 +1453,14 @@ func TestFetcher_UnknownSizeRangeRetriesShortPartialBody(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/short-range.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "short-range.data",
 		Extra: &http.OptsExtra{
 			Connections: 1,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/short-range.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
@@ -1456,13 +1513,14 @@ func TestFetcher_UnknownSizeRangeFallsBackToResolve(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/unknown-size-fallback.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "unknown-size-fallback.data",
 		Extra: &http.OptsExtra{
 			Connections: 1,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/unknown-size-fallback.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
@@ -1543,13 +1601,15 @@ func TestFetcher_UnknownSizeRangeRemainsOpenEndedAfterPause(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/pause-open-range.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
+		Size: 3,
 		Path: t.TempDir(),
 		Name: "pause-open-range.data",
 		Extra: &http.OptsExtra{
 			Connections: 1,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/pause-open-range.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
@@ -1598,13 +1658,14 @@ func TestFetcher_UnknownSizeResolveReadErrorFailsTask(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/broken-chunked.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "broken-chunked.data",
 		Extra: &http.OptsExtra{
 			Connections: 1,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/broken-chunked.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
@@ -1630,13 +1691,14 @@ func TestFetcher_UnknownSizeResolveCleanEOFUpdatesSize(t *testing.T) {
 	defer server.Close()
 
 	f := buildFetcher()
-	if err := f.Resolve(&base.Request{URL: server.URL + "/unknown-size.data"}, &base.Options{
+	f.Meta().Opts = &base.Options{
 		Path: t.TempDir(),
 		Name: "unknown-size.data",
 		Extra: &http.OptsExtra{
 			Connections: 1,
 		},
-	}); err != nil {
+	}
+	if err := f.Resolve(&base.Request{URL: server.URL + "/unknown-size.data"}); err != nil {
 		t.Fatal(err)
 	}
 	defer f.Close()
@@ -2232,14 +2294,15 @@ func TestFetcher_DownloadOneTimeURL(t *testing.T) {
 	defer listener.Close()
 
 	fetcher := buildFetcher()
-	err := fetcher.Resolve(&base.Request{
-		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-	}, &base.Options{
+	fetcher.Meta().Opts = &base.Options{
 		Name: test.DownloadName,
 		Path: test.Dir,
 		Extra: &http.OptsExtra{
 			Connections: 4, // Try to use multiple connections, but only first should work
 		},
+	}
+	err := fetcher.Resolve(&base.Request{
+		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -2298,14 +2361,15 @@ func TestFetcher_SlowStartExpansion(t *testing.T) {
 				Connections: tc.maxConns,
 			})
 
-			err := fetcher.Resolve(&base.Request{
-				URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-			}, &base.Options{
+			fetcher.Meta().Opts = &base.Options{
 				Name: test.DownloadName,
 				Path: test.Dir,
 				Extra: &http.OptsExtra{
 					Connections: tc.maxConns,
 				},
+			}
+			err := fetcher.Resolve(&base.Request{
+				URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 			})
 			if err != nil {
 				cleanup()
@@ -2361,14 +2425,15 @@ func TestFetcher_AsyncPrefetch(t *testing.T) {
 		defer listener.Close()
 
 		fetcher := buildFetcher()
-		err := fetcher.Resolve(&base.Request{
-			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-		}, &base.Options{
+		fetcher.Meta().Opts = &base.Options{
 			Name: test.DownloadName,
 			Path: test.Dir,
 			Extra: &http.OptsExtra{
 				Connections: 4,
 			},
+		}
+		err := fetcher.Resolve(&base.Request{
+			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 		})
 		if err != nil {
 			t.Fatal(err)
@@ -2432,14 +2497,15 @@ func TestFetcher_AsyncPrefetch(t *testing.T) {
 		defer listener.Close()
 
 		fetcher := buildFetcher()
-		err := fetcher.Resolve(&base.Request{
-			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-		}, &base.Options{
+		fetcher.Meta().Opts = &base.Options{
 			Name: test.DownloadName,
 			Path: test.Dir,
 			Extra: &http.OptsExtra{
 				Connections: 4,
 			},
+		}
+		err := fetcher.Resolve(&base.Request{
+			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 		})
 		if err != nil {
 			t.Fatal(err)
@@ -2514,14 +2580,15 @@ func TestFetcher_DownloadExpiringRedirectURL(t *testing.T) {
 		defer listener.Close()
 
 		fetcher := buildFetcher()
-		err := fetcher.Resolve(&base.Request{
-			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-		}, &base.Options{
+		fetcher.Meta().Opts = &base.Options{
 			Name: test.DownloadName,
 			Path: test.Dir,
 			Extra: &http.OptsExtra{
 				Connections: 4, // Use multiple connections to trigger redirect expiration
 			},
+		}
+		err := fetcher.Resolve(&base.Request{
+			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 		})
 		if err != nil {
 			t.Fatal(err)
@@ -2555,14 +2622,15 @@ func TestFetcher_DownloadExpiringRedirectURL(t *testing.T) {
 		defer listener.Close()
 
 		fetcher := buildFetcher()
-		err := fetcher.Resolve(&base.Request{
-			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-		}, &base.Options{
+		fetcher.Meta().Opts = &base.Options{
 			Name: test.DownloadName,
 			Path: test.Dir,
 			Extra: &http.OptsExtra{
 				Connections: 8,
 			},
+		}
+		err := fetcher.Resolve(&base.Request{
+			URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 		})
 		if err != nil {
 			t.Fatal(err)
@@ -2602,14 +2670,15 @@ func TestFetcher_RetryAfterError(t *testing.T) {
 	defer listener.Close()
 
 	fetcher := buildFetcher()
-	err := fetcher.Resolve(&base.Request{
-		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-	}, &base.Options{
+	fetcher.Meta().Opts = &base.Options{
 		Name: test.DownloadName,
 		Path: test.Dir,
 		Extra: &http.OptsExtra{
 			Connections: 1, // Use single connection to simplify test
 		},
+	}
+	err := fetcher.Resolve(&base.Request{
+		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -3030,9 +3099,10 @@ func doDownloadReady(f fetcher.Fetcher, listener net.Listener, connections int,
 		Path:  test.Dir,
 		Extra: extra,
 	}
+	f.Meta().Opts = opts
 	err := f.Resolve(&base.Request{
 		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-	}, opts)
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -3081,7 +3151,8 @@ func downloadPost(listener net.Listener, connections int, t *testing.T) {
 			Body: fmt.Sprintf(`{"name":"%s"}`, test.BuildName),
 		},
 	}
-	err := f.Resolve(req, opts)
+	f.Meta().Opts = opts
+	err := f.Resolve(req)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -3127,11 +3198,12 @@ func downloadContinue(listener net.Listener, connections int, t *testing.T) {
 
 func downloadError(listener net.Listener, connections int, t *testing.T) {
 	fetcher := buildFetcher()
-	err := fetcher.Resolve(&base.Request{
-		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-	}, &base.Options{
+	fetcher.Meta().Opts = &base.Options{
 		Name: test.DownloadName,
 		Path: test.Dir,
+	}
+	err := fetcher.Resolve(&base.Request{
+		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 	})
 	// With the new async design, Resolve may succeed (HTTP response received)
 	// but errors occur during async download or Start/Wait
@@ -3255,7 +3327,8 @@ func TestFetcher_Patch_URLChange(t *testing.T) {
 	}
 
 	// Step 1: Try to resolve with bad URL - should fail with error
-	err := f.Resolve(&base.Request{URL: badURL}, opts)
+	f.Meta().Opts = opts
+	err := f.Resolve(&base.Request{URL: badURL})
 	if err == nil {
 		t.Fatal("Expected error for bad URL, got nil")
 	}
@@ -3265,7 +3338,8 @@ func TestFetcher_Patch_URLChange(t *testing.T) {
 	f2 := buildFetcher()
 
 	// First resolve with good URL to create a valid fetcher state
-	err = f2.Resolve(&base.Request{URL: goodURL}, opts)
+	f2.Meta().Opts = opts
+	err = f2.Resolve(&base.Request{URL: goodURL})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -3317,13 +3391,14 @@ func TestFetcher_Patch_Labels(t *testing.T) {
 		Extra: &http.OptsExtra{Connections: 1},
 	}
 
+	f.Meta().Opts = opts
 	err := f.Resolve(&base.Request{
 		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 		Labels: map[string]string{
 			"key1": "value1",
 			"key3": "value3",
 		},
-	}, opts)
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -3374,6 +3449,7 @@ func TestFetcher_Patch_Extra(t *testing.T) {
 	}
 
 	// Resolve with initial Extra
+	f.Meta().Opts = opts
 	err := f.Resolve(&base.Request{
 		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
 		Extra: &http.ReqExtra{
@@ -3384,7 +3460,7 @@ func TestFetcher_Patch_Extra(t *testing.T) {
 				"X-Custom":      "original",
 			},
 		},
-	}, opts)
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -3462,9 +3538,10 @@ func TestFetcher_Patch_NilData(t *testing.T) {
 		Extra: &http.OptsExtra{Connections: 1},
 	}
 
+	f.Meta().Opts = opts
 	err := f.Resolve(&base.Request{
 		URL: "http://" + listener.Addr().String() + "/" + test.BuildName,
-	}, opts)
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -3514,6 +3591,7 @@ func TestFetcher_Patch_CookieExpired(t *testing.T) {
 
 	// Step 1: Resolve with old_token - should succeed (first request accepts old_token)
 	f := buildFetcher()
+	f.Meta().Opts = opts
 	err := f.Resolve(&base.Request{
 		URL: downloadURL,
 		Extra: &http.ReqExtra{
@@ -3521,7 +3599,7 @@ func TestFetcher_Patch_CookieExpired(t *testing.T) {
 				"Cookie": "session=old_token",
 			},
 		},
-	}, opts)
+	})
 	if err != nil {
 		t.Fatalf("Resolve should succeed with old_token: %v", err)
 	}

internal/protocol/http/filename_parse_test.go

@@ -136,3 +136,52 @@ func TestUnescapeHTMLEntities(t *testing.T) {
 		})
 	}
 }
+
+func TestAppendFilenameExtension(t *testing.T) {
+	tests := []struct {
+		name        string
+		filename    string
+		contentType string
+		want        string
+	}{
+		{
+			name:        "adds extension from content type",
+			filename:    "download",
+			contentType: "image/png",
+			want:        "download.png",
+		},
+		{
+			name:        "parses MIME parameters",
+			filename:    "download",
+			contentType: "image/png; charset=binary",
+			want:        "download.png",
+		},
+		{
+			name:        "preserves existing extension",
+			filename:    "download.zip",
+			contentType: "application/zip",
+			want:        "download.zip",
+		},
+		{
+			name:        "ignores invalid content type",
+			filename:    "download",
+			contentType: "not a content type",
+			want:        "download",
+		},
+		{
+			name:        "ignores unknown content type",
+			filename:    "download",
+			contentType: "application/x-gopeed-unknown",
+			want:        "download",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := appendFilenameExtension(tt.filename, tt.contentType)
+			if got != tt.want {
+				t.Errorf("appendFilenameExtension() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

internal/protocol/http/helper.go

@@ -12,6 +12,7 @@ import (
 	"net/http"
 	"net/http/cookiejar"
 	"net/url"
+	"path"
 	"strings"
 	"time"
 	"unicode/utf8"
@@ -314,6 +315,28 @@ func parseFilename(contentDisposition string) string {
 	return parseFilenameFallback(contentDisposition)
 }
 
+// appendFilenameExtension adds a MIME-derived extension when the resolved
+// filename has no usable extension. Some image hosts use opaque path segments
+// that look like extensions, even though the response Content-Type is the
+// only reliable source for the file type.
+func appendFilenameExtension(filename, contentType string) string {
+	mediaType, _, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		return filename
+	}
+
+	extensions, err := mime.ExtensionsByType(mediaType)
+	if err != nil || len(extensions) == 0 {
+		return filename
+	}
+
+	ext := path.Ext(filename)
+	if len(ext) > 1 && len(ext) <= 20 {
+		return filename
+	}
+	return filename + extensions[0]
+}
+
 // parseFilenameExtended handles RFC 5987 extended notation (filename*=)
 // Format: filename*=charset'language'value (e.g., UTF-8”%E6%B5%8B%E8%AF%95.zip)
 func parseFilenameExtended(cd string) string {

internal/protocol/http/prefetch_setup_test.go

@@ -0,0 +1,74 @@
+package http
+
+import (
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/GopeedLab/gopeed/internal/controller"
+	"github.com/GopeedLab/gopeed/internal/tempfiles"
+)
+
+type prefetchSetupBody struct {
+	io.Reader
+	closed bool
+}
+
+func (b *prefetchSetupBody) Close() error {
+	b.closed = true
+	return nil
+}
+
+func TestPrefetchSetupFailureClosesResponse(t *testing.T) {
+	for _, closedScope := range []bool{false, true} {
+		name := "invalid_temp_directory"
+		if closedScope {
+			name = "downloader_already_closed"
+		}
+		t.Run(name, func(t *testing.T) {
+			root := t.TempDir()
+			scope := &tempfiles.Scope{}
+			dir := root
+			if closedScope {
+				if err := scope.Close(); err != nil {
+					t.Fatal(err)
+				}
+			} else {
+				dir = filepath.Join(root, "file")
+				if err := os.WriteFile(dir, nil, 0600); err != nil {
+					t.Fatal(err)
+				}
+			}
+			body := &prefetchSetupBody{Reader: strings.NewReader("unused response")}
+			f := &Fetcher{
+				ctl:         &controller.Controller{TempDir: dir, TempFiles: scope},
+				resolveResp: &http.Response{Body: body},
+			}
+			f.asyncPrefetch()
+			if f.prefetchErr == nil {
+				t.Fatal("expected temporary-file initialization to fail")
+			}
+			if !body.closed {
+				t.Error("prefetch setup failure left the response body open")
+			}
+			if f.resolveResp != nil {
+				t.Error("prefetch retained its failed resolve response")
+			}
+			if !f.prefetchDone.Load() {
+				t.Error("prefetch did not report completion")
+			}
+			if closedScope {
+				entries, err := os.ReadDir(root)
+				if err != nil {
+					t.Fatal(err)
+				}
+				if len(entries) != 0 {
+					t.Errorf("late prefetch left temporary files: %v", entries)
+				}
+			}
+		})
+	}
+}

internal/protocol/http/resolve_range_test.go

@@ -0,0 +1,121 @@
+package http
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/GopeedLab/gopeed/pkg/base"
+	fhttp "github.com/GopeedLab/gopeed/pkg/protocol/http"
+)
+
+func TestResolveResponseSize(t *testing.T) {
+	for _, tc := range []struct {
+		name                 string
+		status               int
+		length, contentRange string
+		size                 int64
+		invalid              bool
+	}{
+		{"full", 200, "801571015", "", 801571015, false},
+		{"partial_prefix", 206, "472321339", "bytes 0-472321338/801571015", 801571015, false},
+		{"partial_nonzero", 206, "100000", "bytes 100000-199999/801571015", 801571015, false},
+		{"second_report", 206, "335134409", "bytes 0-335134408/552140234", 552140234, false},
+		{"length_mismatch", 206, "10", "bytes 0-19/100", 0, true},
+		{"unknown_total", 206, "472321339", "bytes 0-472321338/*", 0, true},
+		{"missing_range", 206, "10", "", 0, true},
+		{"malformed_range", 206, "10", "bytes invalid", 0, true},
+		{"invalid_bounds", 206, "10", "bytes 20-10/100", 0, true},
+		{"invalid_total", 206, "10", "bytes 0-9/9", 0, true},
+		{"overflow", 206, "10", "bytes 0-9/9223372036854775808", 0, true},
+		{"chunked_partial", 206, "", "bytes 0-9/100", 100, false},
+		{"unknown_full", 200, "", "", 0, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if tc.length != "" {
+					w.Header().Set("Content-Length", tc.length)
+				}
+				if tc.contentRange != "" {
+					w.Header().Set("Content-Range", tc.contentRange)
+				}
+				w.WriteHeader(tc.status)
+				w.(http.Flusher).Flush()
+			}))
+			defer server.Close()
+			f := buildFetcher()
+			defer f.Close()
+			f.Meta().Opts = &base.Options{Path: t.TempDir()}
+			err := f.Resolve(&base.Request{URL: server.URL + "/file"})
+			if tc.invalid {
+				if !errors.Is(err, errInvalidRangeResponse) {
+					t.Fatalf("Resolve error = %v, want invalid range", err)
+				}
+				if f.meta.Res != nil || f.resolveResp != nil || f.getState() != stateError {
+					t.Fatal("invalid response was retained or published")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if f.meta.Res.Size != tc.size || f.meta.Res.Files[0].Size != tc.size {
+				t.Fatalf("resource/file size = %d/%d, want %d", f.meta.Res.Size, f.meta.Res.Files[0].Size, tc.size)
+			}
+			if tc.status == 206 && !f.meta.Res.Range {
+				t.Fatal("partial response must enable Range downloads")
+			}
+		})
+	}
+}
+
+func TestDownloadPartialResolve(t *testing.T) {
+	payload := make([]byte, 256*1024)
+	for i := range payload {
+		payload[i] = byte(i*31 + i/251)
+	}
+	for _, start := range []int{0, 100000} {
+		for _, connections := range []int{1, 4} {
+			t.Run(fmt.Sprintf("start_%d_connections_%d", start, connections), func(t *testing.T) {
+				server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					begin, end := start, start+9999
+					if h := r.Header.Get("Range"); h != "" {
+						if _, err := fmt.Sscanf(h, "bytes=%d-%d", &begin, &end); err != nil {
+							t.Errorf("invalid request range %q: %v", h, err)
+							w.WriteHeader(400)
+							return
+						}
+					}
+					w.Header().Set("Content-Length", fmt.Sprint(end-begin+1))
+					w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", begin, end, len(payload)))
+					w.WriteHeader(206)
+					w.Write(payload[begin : end+1])
+				}))
+				defer server.Close()
+				f := buildFetcher()
+				defer f.Close()
+				f.Meta().Opts = &base.Options{Path: t.TempDir(), Name: "file", Extra: &fhttp.OptsExtra{Connections: connections}}
+				if err := f.Resolve(&base.Request{URL: server.URL + "/file"}); err != nil {
+					t.Fatal(err)
+				}
+				if err := f.Start(); err != nil {
+					t.Fatal(err)
+				}
+				if err := f.Wait(); err != nil {
+					t.Fatal(err)
+				}
+				got, err := os.ReadFile(f.meta.SingleFilepath())
+				if err != nil {
+					t.Fatal(err)
+				}
+				if !bytes.Equal(got, payload) {
+					t.Fatalf("download content mismatch: got %d bytes, want %d", len(got), len(payload))
+				}
+			})
+		}
+	}
+}

internal/protocol/http/restore_prefetch_test.go

@@ -0,0 +1,79 @@
+package http
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/controller"
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+	"github.com/GopeedLab/gopeed/internal/test"
+	"github.com/GopeedLab/gopeed/pkg/base"
+	fhttp "github.com/GopeedLab/gopeed/pkg/protocol/http"
+)
+
+func TestFetcher_RestoredStartSkipsAbsentPrefetch(t *testing.T) {
+	data := bytes.Repeat([]byte("0123456789abcdef"), 64*1024)
+	var firstRequest atomic.Int64
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		firstRequest.CompareAndSwap(0, time.Now().UnixNano())
+		http.ServeContent(w, r, "restored.bin", time.Time{}, bytes.NewReader(data))
+	}))
+	defer server.Close()
+
+	dir := t.TempDir()
+	size := int64(len(data))
+	half := size / 2
+	file := filepath.Join(dir, "restored.bin")
+	if err := os.WriteFile(file, data[:half], 0600); err != nil {
+		t.Fatal(err)
+	}
+	conn := &connection{ID: 0, Role: rolePrimary, State: connNotStarted, Chunk: newChunk(0, size-1), Downloaded: half}
+	conn.Chunk.Downloaded = half
+	rangeMode := true
+	saved := &fetcherData{Connections: []*connection{conn}, Range: &rangeMode, ResourceSize: &size, FileSize: &size}
+	meta := &fetcher.FetcherMeta{
+		Req:  &base.Request{URL: server.URL + "/restored.bin"},
+		Res:  &base.Resource{Size: size, Range: true, Files: []*base.FileInfo{{Name: "restored.bin", Size: size}}},
+		Opts: &base.Options{Path: dir, Name: "restored.bin", Extra: &fhttp.OptsExtra{Connections: 1}},
+	}
+	fm := new(FetcherManager)
+	_, restore := fm.Restore()
+	f := restore(meta, saved).(*Fetcher)
+	ctl := controller.NewController()
+	ctl.GetConfig = func(v any) {
+		if err := json.Unmarshal([]byte(test.ToJson(fm.DefaultConfig())), v); err != nil {
+			t.Error(err)
+		}
+	}
+	f.Setup(ctl)
+	defer f.Close()
+	started := time.Now()
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err != nil {
+		t.Fatal(err)
+	}
+	actual, err := os.ReadFile(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(actual, data) {
+		t.Fatal("restored download differs from the complete server content")
+	}
+	if firstRequest.Load() == 0 {
+		t.Fatal("restored download did not request the remaining content")
+	}
+	delay := time.Duration(firstRequest.Load() - started.UnixNano())
+	t.Logf("first restored request after %s", delay)
+	if delay > 2*time.Second {
+		t.Errorf("restored download waited %s before its first request", delay)
+	}
+}

internal/protocol/http/size_hint_test.go

@@ -0,0 +1,245 @@
+package http
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+
+	"github.com/GopeedLab/gopeed/pkg/base"
+)
+
+func TestFetcher_OptionsSizeHintAndPatch(t *testing.T) {
+	for _, known := range []bool{false, true} {
+		for _, payload := range []string{"", "0123456789"} {
+			t.Run(fmt.Sprintf("known=%v/bytes=%d", known, len(payload)), func(t *testing.T) {
+				server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					if known {
+						w.Header().Set("Content-Length", fmt.Sprint(len(payload)))
+					}
+					w.(http.Flusher).Flush()
+					fmt.Fprint(w, payload)
+				}))
+				defer server.Close()
+				f := buildFetcher()
+				defer f.Close()
+				f.Meta().Opts = &base.Options{Size: 7, Path: t.TempDir(), Name: "output.bin"}
+				if err := f.Resolve(&base.Request{URL: server.URL}); err != nil {
+					t.Fatal(err)
+				}
+				want := int64(7)
+				if known {
+					want = int64(len(payload))
+				}
+				if f.meta.Res.Size != want || f.hasKnownSize() != known {
+					t.Fatalf("resolved size=%d known=%v", f.meta.Res.Size, f.hasKnownSize())
+				}
+				if err := f.Patch(nil, &base.Options{Size: 9}); err != nil {
+					t.Fatal(err)
+				}
+				if !known {
+					want = 9
+				}
+				if f.meta.Res.Size != want {
+					t.Fatal("hint update overrode a real size or failed to update an estimate")
+				}
+				if err := f.Start(); err != nil {
+					t.Fatal(err)
+				}
+				if err := f.Wait(); err != nil {
+					t.Fatal(err)
+				}
+				if f.meta.Res.Size != int64(len(payload)) || !f.hasKnownSize() {
+					t.Fatalf("final size=%d known=%v", f.meta.Res.Size, f.hasKnownSize())
+				}
+				snapshot, err := new(FetcherManager).Store(f)
+				if err != nil {
+					t.Fatal(err)
+				}
+				fd := snapshot.(*fetcherData)
+				if fd.SizeKnown == nil || !*fd.SizeKnown {
+					t.Fatal("snapshot lost confirmed size authority")
+				}
+				_, restore := new(FetcherManager).Restore()
+				restored := restore(f.meta, fd).(*Fetcher)
+				if !restored.hasKnownSize() || restored.knownSize() != int64(len(payload)) {
+					t.Fatal("restored size lost authority, including known zero")
+				}
+			})
+		}
+	}
+}
+
+func TestFetcher_SizeHintCannotCompleteForbiddenUnknownRange(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Range") != "" {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		w.Header().Set("Accept-Ranges", "bytes")
+		w.(http.Flusher).Flush()
+		fmt.Fprint(w, "0123456789")
+		w.(http.Flusher).Flush()
+		<-r.Context().Done()
+	}))
+	defer server.Close()
+	f := buildFetcher()
+	defer f.Close()
+	f.Meta().Opts = &base.Options{Size: 3, Path: t.TempDir(), Name: "output.bin"}
+	if err := f.Resolve(&base.Request{URL: server.URL}); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Wait(); err == nil {
+		t.Fatal("a failed unknown-length Range request was completed from an estimate")
+	}
+}
+
+func TestFetcher_SizeHintPreservesHTTPIntegrity(t *testing.T) {
+	for _, chunked := range []bool{false, true} {
+		for _, broken := range []bool{false, true} {
+			t.Run(fmt.Sprintf("chunked=%v/broken=%v", chunked, broken), func(t *testing.T) {
+				payload := []byte("0123456789")
+				server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					if chunked && broken {
+						conn, rw, err := w.(http.Hijacker).Hijack()
+						if err != nil {
+							t.Error(err)
+							return
+						}
+						defer conn.Close()
+						fmt.Fprint(rw, "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\nConnection: close\r\n\r\na\r\n0123456789\r\n")
+						rw.Flush() // Omit the final chunk to simulate a connection interruption.
+						return
+					}
+					if !chunked {
+						length := len(payload)
+						if broken {
+							length++
+						}
+						w.Header().Set("Content-Length", fmt.Sprint(length))
+					}
+					w.(http.Flusher).Flush()
+					w.Write(payload)
+				}))
+				defer server.Close()
+				f := buildFetcher()
+				defer f.Close()
+				f.Meta().Opts = &base.Options{Size: 3, Path: t.TempDir(), Name: "output.bin"}
+				if err := f.Resolve(&base.Request{URL: server.URL}); err != nil {
+					t.Fatal(err)
+				}
+				if !chunked {
+					length := int64(len(payload))
+					if broken {
+						length++
+					}
+					if f.meta.Res.Size != length || f.sequentialSizeUnknown {
+						t.Fatal("HTTP length did not override size hint")
+					}
+				} else if f.meta.Res.Size != 3 || !f.sequentialSizeUnknown {
+					t.Fatal("unknown HTTP length did not retain the display hint")
+				}
+				if err := f.Start(); err != nil {
+					t.Fatal(err)
+				}
+				err := f.Wait()
+				if broken {
+					if err == nil {
+						t.Fatal("truncated HTTP response succeeded after exceeding the size hint")
+					}
+					return
+				}
+				if err != nil {
+					t.Fatal(err)
+				}
+				if f.meta.Res.Size != int64(len(payload)) || f.sequentialSizeUnknown {
+					t.Fatalf("completed size=%d unknown=%v", f.meta.Res.Size, f.sequentialSizeUnknown)
+				}
+			})
+		}
+	}
+}
+
+func TestFetcher_SizeHintSurvivesRestore(t *testing.T) {
+	for _, partial := range []bool{false, true} {
+		for _, fixedLength := range []bool{false, true} {
+			t.Run(fmt.Sprintf("partial=%v/fixedLength=%v", partial, fixedLength), func(t *testing.T) {
+				payload := []byte("0123456789")
+				var requests atomic.Int64
+				server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					request := requests.Add(1)
+					if got := r.Header.Get("Range"); got != "" {
+						t.Errorf("estimated sizes must not be used for resume ranges: %s", got)
+					}
+					if fixedLength && request > 1 {
+						w.Header().Set("Content-Length", fmt.Sprint(len(payload)))
+					}
+					w.(http.Flusher).Flush()
+					if fixedLength && request == 2 {
+						w.Write(payload[:4]) // Retry must discard this interrupted attempt.
+						return
+					}
+					w.Write(payload)
+				}))
+				defer server.Close()
+				f := buildFetcher()
+				opts := &base.Options{Size: 3, Path: t.TempDir(), Name: "output.bin"}
+				f.Meta().Opts = opts
+				if err := f.Resolve(&base.Request{URL: server.URL}); err != nil {
+					t.Fatal(err)
+				}
+				fm := new(FetcherManager)
+				snapshot, err := fm.Store(f)
+				if err != nil {
+					t.Fatal(err)
+				}
+				data, err := json.Marshal(snapshot)
+				if err != nil {
+					t.Fatal(err)
+				}
+				var saved fetcherData
+				if err := json.Unmarshal(data, &saved); err != nil {
+					t.Fatal(err)
+				}
+				if !saved.SequentialSizeUnknown || saved.SizeKnown == nil || *saved.SizeKnown || *saved.ResourceSize != 3 {
+					t.Fatal("snapshot lost the size hint or its advisory state")
+				}
+				f.Close()
+				// An interrupted earlier attempt left a tail longer than the new output.
+				if err := os.WriteFile(filepath.Join(opts.Path, opts.Name), bytes.Repeat([]byte("old"), 100), 0600); err != nil {
+					t.Fatal(err)
+				}
+				if partial {
+					chunk := newChunk(0, 0)
+					chunk.Downloaded = 7 // Already exceeds the display estimate.
+					saved.Connections = []*connection{{ID: 0, Role: rolePrimary, State: connNotStarted, Chunk: chunk, Downloaded: 7}}
+				}
+				_, restore := fm.Restore()
+				restored := restore(f.meta, &saved).(*Fetcher)
+				restored.Setup(f.ctl)
+				defer restored.Close()
+				if err := restored.Start(); err != nil {
+					t.Fatal(err)
+				}
+				if err := restored.Wait(); err != nil {
+					t.Fatal(err)
+				}
+				body, err := os.ReadFile(restored.meta.SingleFilepath())
+				if err != nil {
+					t.Fatal(err)
+				}
+				if !bytes.Equal(body, payload) || restored.meta.Res.Size != int64(len(payload)) || restored.Progress().TotalDownloaded() != int64(len(payload)) {
+					t.Fatalf("restored stream retained an estimate or stale bytes: body=%q size=%d progress=%d", body, restored.meta.Res.Size, restored.Progress().TotalDownloaded())
+				}
+			})
+		}
+	}
+}

internal/tempfiles/scope.go

@@ -0,0 +1,63 @@
+// Package tempfiles tracks temporary paths owned by one downloader, without
+// requiring a private parent directory or scanning the shared system temp root.
+package tempfiles
+
+import (
+	"errors"
+	"io"
+	"os"
+	"sync"
+)
+
+type Scope struct {
+	mu     sync.Mutex
+	paths  map[string]struct{}
+	closed bool
+}
+
+// Track adopts a newly created unique path. Late creations are removed when
+// shutdown has already begun. A nil scope leaves cleanup to the resource owner.
+func (s *Scope) Track(path string) error {
+	if s == nil {
+		return nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return errors.Join(io.ErrClosedPipe, os.RemoveAll(path))
+	}
+	if s.paths == nil {
+		s.paths = make(map[string]struct{})
+	}
+	s.paths[path] = struct{}{}
+	return nil
+}
+func (s *Scope) Remove(path string) error {
+	if s == nil {
+		return os.RemoveAll(path)
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if err := os.RemoveAll(path); err != nil {
+		return err
+	}
+	delete(s.paths, path)
+	return nil
+}
+func (s *Scope) Close() error {
+	if s == nil {
+		return nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.closed = true
+	var result error
+	for path := range s.paths {
+		if err := os.RemoveAll(path); err != nil {
+			result = errors.Join(result, err)
+		} else {
+			delete(s.paths, path)
+		}
+	}
+	return result
+}

internal/tempfiles/scope_test.go

@@ -0,0 +1,76 @@
+package tempfiles
+
+import (
+	"errors"
+	"io"
+	"os"
+	"sync"
+	"testing"
+)
+
+func TestSharedDirectoryOwnersAndLateCreation(t *testing.T) {
+	root := t.TempDir()
+	a, b := &Scope{}, &Scope{}
+	own := func(scope *Scope) string {
+		t.Helper()
+		dir, err := os.MkdirTemp(root, "gopeed-media-")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := scope.Track(dir); err != nil {
+			t.Fatal(err)
+		}
+		return dir
+	}
+	first, second := own(a), own(b)
+	if err := a.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(first); !os.IsNotExist(err) {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(second); err != nil {
+		t.Fatal("removed other owner's path", err)
+	}
+	late, err := os.MkdirTemp(root, "gopeed-media-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.Track(late); !errors.Is(err, io.ErrClosedPipe) {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(late); !os.IsNotExist(err) {
+		t.Fatal("late creation leaked", err)
+	}
+	if err := b.Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestConcurrentCreationAndShutdown(t *testing.T) {
+	root := t.TempDir()
+	scope := &Scope{}
+	var wg sync.WaitGroup
+	for i := 0; i < 20; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			dir, err := os.MkdirTemp(root, "gopeed-media-")
+			if err != nil {
+				t.Error(err)
+				return
+			}
+			if err := scope.Track(dir); err != nil && !errors.Is(err, io.ErrClosedPipe) {
+				t.Error(err)
+			}
+		}()
+	}
+	if err := scope.Close(); err != nil {
+		t.Fatal(err)
+	}
+	wg.Wait()
+	entries, err := os.ReadDir(root)
+	if err != nil || len(entries) != 0 {
+		t.Fatal("shutdown leaked paths", entries, err)
+	}
+}

internal/webview/README.md

@@ -0,0 +1,109 @@
+# Extension browser host configuration
+
+The downloader wraps each provider with the extension's stable identity before
+constructing the runtime. `OpenOptions.ProfileID`, `DataPath`, and `ProxyURL` are
+host-only fields. `parseOpenOptions` never reads them from extension JavaScript.
+The extension API is unchanged. The Flutter host uses the fork's public
+`WebViewProfile`, `InAppWebViewSettings.profileId`, and profile-scoped
+`CookieManager` APIs; the library has no Gopeed-specific method-channel bridge.
+Only the Gopeed extension JavaScript boundary keeps these options host-only.
+
+Profiles are persistent and shared across invocations/pages of the same extension.
+Different identities use different native stores. Go providers use a SHA-256-based
+path under `<StorageDir>/webview`; Apple RPC hosts use a stable UUID data store;
+Android uses a named WebView profile. Cookie operations select that same store,
+including `clearCookies`. Closing an execution closes its pages, not its profile.
+Uninstall closes the extension's pages, prevents its old runtimes from opening
+new pages, and removes its native profile before deleting the extension record.
+Cleanup failures abort uninstall and can be retried. Reinstallation starts with
+empty browser data; an ordinary extension update keeps the existing profile.
+Windows/Linux delete the profile directory; Apple removes the named WebKit store.
+Android cannot delete a profile already loaded by the current process: when
+DELETE_BROWSING_DATA is supported it clears all site data immediately, and records
+an empty-profile deletion in SharedPreferences for the next process start. A
+reinstallation may reuse that cleared profile and cancels the pending deletion.
+If the full-data clearing API is unavailable, uninstall fails with a restart
+instruction; the pending profile is deleted at startup before it can be loaded.
+No removal operation is exposed through extension JavaScript.
+
+Existing shared browser data is not copied into every extension's new profile.
+
+The downloader lazily owns one loopback forward proxy with HTTP and SOCKS5
+listeners. Windows/Linux/Android use HTTP; Apple uses SOCKS5 because its HTTP
+CONNECT configuration may bypass plain HTTP. The forwarder reads the current
+Gopeed proxy config for each new request/tunnel and supports direct, system,
+HTTP(S) upstream proxies with Basic authentication, and authenticated SOCKS5.
+Credentials remain in Go and are never sent over the WebView RPC.
+
+Changes affect new requests/connections. Existing CONNECT/SOCKS tunnels keep their
+route until closed; opening another page in the same profile does not reset it.
+SOCKS carries host/port rather than a full URL: system proxy/PAC selection for
+Apple is host-based, with port 80 treated as HTTP and other ports as HTTPS.
+Path-dependent PAC rules cannot be reproduced from a SOCKS connection.
+
+Apple requires macOS 14 / iOS 17. Android checks MULTI_PROFILE and PROXY_OVERRIDE.
+Unsupported hosts fail explicitly instead of silently sharing browser storage or
+ignoring the proxy.
+
+## Validation
+
+- `go test -race ./internal/webview/proxy ./pkg/download/engine/webview`
+- `go test ./pkg/download -run 'TestWebViewProfileBound|TestDownloader_ExtensionRuntimeWebView'`
+- Windows/Linux: `go test -tags webview -v ./internal/webview/goprovider` (Linux: run under `xvfb-run -a`).
+- macOS: start the normal Flutter app, then run `go test -tags webview -v ./internal/webview/rpcprovider` with its socket address. See `rpcprovider/README.md`.
+- In webview_go: `go test -tags webview_integration -v -count=1 .` (Linux: run under `xvfb-run -a`).
+
+The shared provider contract covers HTTP/HTTPS proxy routing, concurrent pages,
+HttpOnly cookies, LocalStorage, IndexedDB, profile-scoped clearing, reopening,
+and removal without affecting another profile. HTTPS routing is checked with a
+rejecting upstream tunnel; no test-only certificate bypass is added to the app.
+Go proxy unit tests separately cover successful TLS forwarding and authentication.
+These cases run in the existing `test.yml` WebView jobs; existing mobile build jobs
+compile the Android/iOS bridge. No separate Flutter test application is required.
+
+## Extension events and host environment
+
+`gopeed.host.env.version` is the host's build version (`dev` for development
+builds). `gopeed.info.version` continues to identify the extension's own version.
+`gopeed.host.env.os` and `gopeed.host.env.arch` match the REST info endpoint's `os` and
+`arch`: the host's Go `runtime.GOOS` and `runtime.GOARCH` values (for example,
+`windows` / `amd64` or `darwin` / `arm64`).
+See [extension-api.d.ts](extension-api.d.ts) for the event payloads.
+
+```js
+const page = await gopeed.runtime.webview.open();
+const unsubscribe = await page.on("url-changed", ({ url, sameDocument }) => {
+  gopeed.logger.info(url, sameDocument);
+});
+await page.on("closed", ({ reason }) => gopeed.logger.info(reason));
+await page.addInitScript("globalThis.extensionReady = true");
+await page.goto("https://example.com");
+unsubscribe();
+await page.close();
+```
+
+Registration resolves only after the listener is installed; it does not replay
+current state. `url-changed` reports actual address changes, including hash,
+pushState, replaceState and history navigation. `load` follows the main document's
+`window.load`, including reloads, and does not wait for business-level async work.
+Iframe loads and subresource failures do not become main-page notifications.
+`closed` distinguishes the user's close action from API closure and is terminal.
+Unsubscribe is idempotent. Notifications cannot block navigation; the engine does
+not await promises returned by handlers. Catch async errors inside the handler.
+
+`addInitScript` applies to future document contexts only. Use `execute` to run
+code on the current page. Executable functions are serialized and cannot capture
+extension-side lexical variables; pass values explicitly as arguments.
+
+The RPC host uses an NDJSON `page.events` response whose first record is
+`{"ready":true}`. Subsequent records are `{event,data}`. Closing a page sends the
+terminal record before ending the stream. The native backend uses document-start
+notifications for main-document URL/load events and native callbacks for
+navigation failures and user closure.
+
+Additional validation:
+
+- `go test -race ./pkg/download/engine/webview ./internal/webview/rpcprovider`
+- `go test ./pkg/download -run 'TestExtension(WebViewEvents|InfoHostVersion)'`
+- macOS native: `go test -tags webview_native ./internal/webview/goprovider -run TestProviderEvents`
+- Running Flutter host: `go test -tags webview ./internal/webview/rpcprovider -run TestProviderEvents`

internal/webview/extension-api.d.ts

@@ -0,0 +1,60 @@
+/** Public extension API additions. info.version remains the extension version. */
+export interface ExtensionInfo {
+  identity: string;
+  name: string;
+  author: string;
+  title: string;
+  version: string;
+}
+
+/** Available as gopeed.host. */
+export interface Host {
+  env: HostEnv;
+}
+
+export interface HostEnv {
+  /** Host build version; "dev" for development builds. */
+  version: string;
+  /** Host OS and architecture, matching the REST info endpoint (Go GOOS/GOARCH). */
+  os: string;
+  arch: string;
+}
+
+/** Functions are serialized; they cannot capture extension-side variables. */
+export type WebviewExecutable<T = unknown> =
+  | string
+  | ((...args: unknown[]) => T | Promise<T>);
+
+export type WebviewUnsubscribe = () => void;
+
+/** Navigation and load notifications are for the main document only. */
+export interface WebviewEventMap {
+  "url-changed": { url: string; sameDocument: boolean };
+  /** window.load, including reloads, excluding hash/History API navigation. */
+  "load": { url: string };
+  "load-error": { url: string; message: string };
+  "closed": { reason: "user" | "api" };
+}
+
+export interface WebviewGotoOptions {
+  timeoutMs?: number;
+  waitUntil?: "load" | "domcontentloaded";
+}
+
+/** These members extend the existing WebviewPage API. */
+export interface WebviewPage {
+  /**
+   * Resolves when listening is ready. Does not replay current state.
+   * Register before goto() to observe navigation. Unsubscribe is idempotent.
+   * Closed is delivered once, then listeners are released automatically.
+   * Callbacks cannot cancel navigation; returned promises are not awaited.
+   * Callers handle errors in asynchronous callbacks.
+   */
+  on<K extends keyof WebviewEventMap>(
+    event: K,
+    handler: (data: WebviewEventMap[K]) => void,
+  ): Promise<WebviewUnsubscribe>;
+  /** Runs at document creation on future navigations, never immediately. */
+  addInitScript(script: string): Promise<void>;
+  goto(url: string, opts?: WebviewGotoOptions): Promise<void>;
+}

internal/webview/goprovider/events_darwin_test.go

@@ -0,0 +1,12 @@
+//go:build cgo && darwin && webview_native
+
+package goprovider
+
+import (
+	"github.com/GopeedLab/gopeed/internal/webview/integrationtest"
+	"os"
+	"testing"
+)
+
+func TestMain(m *testing.M)           { os.Exit(RunMainThreadLoop(m.Run)) }
+func TestProviderEvents(t *testing.T) { integrationtest.RunEventContract(t, New()) }

internal/webview/goprovider/events_script_test.go

@@ -0,0 +1,49 @@
+//go:build cgo
+
+package goprovider
+
+import (
+	enginewebview "github.com/GopeedLab/gopeed/pkg/download/engine/webview"
+	webview "github.com/GopeedLab/webview_go"
+	"github.com/dop251/goja"
+	"testing"
+	"time"
+)
+
+func TestInternalErrorDocumentDoesNotReportPageEvents(t *testing.T) {
+	vm := goja.New()
+	if _, err := vm.RunString(`
+  var window = globalThis;
+  window.top = window;
+  var location = {protocol: "chrome-error:", href: "chrome-error://chromewebdata/"};
+  var notifications = [];
+  var listeners = [];
+  function notify(payload) { notifications.push(payload); }
+  window.addEventListener = (name) => listeners.push(name);
+ `); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := vm.RunString(buildLoadNotifyScript("notify")); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"notifications", "listeners"} {
+		value, err := vm.RunString(name + ".length")
+		if err != nil || value.ToInteger() != 0 {
+			t.Fatalf("internal error page registered %s: %v (%v)", name, value, err)
+		}
+	}
+	// The provider must wait for the native failure, preserving the failed URL.
+	page := newPageWrapper(enginewebview.OpenOptions{})
+	got := make(chan string, 1)
+	_, err := page.On("load-error", func(e enginewebview.Event) { got <- e.Data["url"].(string) })
+	if err != nil {
+		t.Fatal(err)
+	}
+	page.handleNativeEvent(webview.Event{Name: "load-error", URL: "https://example.test/failure", Message: "TLS handshake failed"})
+	if err := page.waitForNavigation(time.Second, "load"); err == nil {
+		t.Fatal("native failure completed navigation successfully")
+	}
+	if url := <-got; url != "https://example.test/failure" {
+		t.Fatal(url)
+	}
+}

internal/webview/goprovider/mainthread_linux.go

@@ -0,0 +1,47 @@
+//go:build linux && cgo
+
+package goprovider
+
+/*
+#cgo pkg-config: gtk+-3.0
+#include <gtk/gtk.h>
+static void pumpGTK(void) {
+  // Bound each batch so Go creation/removal requests cannot be starved.
+  for (int i = 0; i < 64 && g_main_context_pending(NULL); ++i)
+    g_main_context_iteration(NULL, FALSE);
+}
+*/
+import "C"
+
+import (
+	"runtime"
+	"sync"
+	"time"
+)
+
+var gtkThreadOnce sync.Once
+var gtkThreadTasks = make(chan func())
+
+func RunMainThreadLoop(run func() int) int { return run() }
+
+func postMainThreadTask(task func()) bool {
+	gtkThreadOnce.Do(func() {
+		go func() {
+			runtime.LockOSThread()
+			// WebKit must always use its original UI thread, including after
+			// the last page closes. A page cannot stop this shared event loop.
+			ticker := time.NewTicker(10 * time.Millisecond)
+			defer ticker.Stop()
+			for {
+				select {
+				case task := <-gtkThreadTasks:
+					task()
+				case <-ticker.C:
+				}
+				C.pumpGTK()
+			}
+		}()
+	})
+	gtkThreadTasks <- task
+	return true
+}

internal/webview/goprovider/mainthread_other.go

@@ -1,4 +1,4 @@
-//go:build !darwin
+//go:build !darwin && (!linux || !cgo)
 
 package goprovider
 

internal/webview/goprovider/provider.go

@@ -6,7 +6,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"net/url"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -37,7 +36,9 @@ func (p *Provider) Open(opts enginewebview.OpenOptions) (enginewebview.Page, err
 }
 
 type pageWrapper struct {
-	opts enginewebview.OpenOptions
+	opts             enginewebview.OpenOptions
+	events           enginewebview.EventHub
+	navigationErrors chan error
 
 	callbackName string
 	readyID      string
@@ -49,19 +50,23 @@ type pageWrapper struct {
 	url     string
 	closed  bool
 
-	ready chan error
-	done  chan struct{}
-	loads chan string
+	ready        chan error
+	done         chan struct{}
+	loads        chan string
+	domReady     chan struct{}
+	sameDocument chan struct{}
 }
 
 type evalMessage struct {
-	ID    string `json:"id"`
-	Ready bool   `json:"ready,omitempty"`
-	Load  bool   `json:"load,omitempty"`
-	URL   string `json:"url,omitempty"`
-	OK    bool   `json:"ok,omitempty"`
-	Value any    `json:"value,omitempty"`
-	Error string `json:"error,omitempty"`
+	Event        string `json:"event,omitempty"`
+	SameDocument bool   `json:"sameDocument,omitempty"`
+	ID           string `json:"id"`
+	Ready        bool   `json:"ready,omitempty"`
+	Load         bool   `json:"load,omitempty"`
+	URL          string `json:"url,omitempty"`
+	OK           bool   `json:"ok,omitempty"`
+	Value        any    `json:"value,omitempty"`
+	Error        string `json:"error,omitempty"`
 }
 
 type evalResult struct {
@@ -88,13 +93,16 @@ const startupTimeout = time.Minute
 func newPageWrapper(opts enginewebview.OpenOptions) *pageWrapper {
 	seq := providerSeq.Add(1)
 	return &pageWrapper{
-		opts:         opts,
-		callbackName: fmt.Sprintf("__gopeedWebViewCallback_%d", seq),
-		readyID:      fmt.Sprintf("__ready__%d", seq),
-		pending:      make(map[string]chan evalResult),
-		ready:        make(chan error, 1),
-		done:         make(chan struct{}),
-		loads:        make(chan string, 8),
+		opts:             opts,
+		navigationErrors: make(chan error, 8),
+		callbackName:     fmt.Sprintf("__gopeedWebViewCallback_%d", seq),
+		readyID:          fmt.Sprintf("__ready__%d", seq),
+		pending:          make(map[string]chan evalResult),
+		ready:            make(chan error, 1),
+		done:             make(chan struct{}),
+		loads:            make(chan string, 8),
+		domReady:         make(chan struct{}, 8),
+		sameDocument:     make(chan struct{}, 8),
 	}
 }
 
@@ -105,12 +113,21 @@ func (p *pageWrapper) start() error {
 		defer runtimepkg.UnlockOSThread()
 
 		var w webview.WebView
-		if p.opts.Headless {
+		if p.opts.DataPath != "" {
+			var err error
+			w, err = webview.NewWithOptions(webview.Options{Debug: p.opts.Debug, Headless: p.opts.Headless, DataPath: p.opts.DataPath, ProxyURL: p.opts.ProxyURL})
+			if err != nil {
+				p.ready <- err
+				close(p.done)
+				return
+			}
+		} else if p.opts.Headless {
 			w = webview.NewHeadless(p.opts.Debug)
 		} else {
 			w = webview.New(p.opts.Debug)
 		}
 		p.view = w
+		w.SetEventHandler(p.handleNativeEvent)
 		w.SetTitle(firstNonEmpty(p.opts.Title, "Gopeed WebView"))
 		w.SetSize(defaultWindowDimension(p.opts.Width, 1280), defaultWindowDimension(p.opts.Height, 800), webview.HintNone)
 
@@ -122,18 +139,25 @@ func (p *pageWrapper) start() error {
 				setter.SetUserAgent(p.opts.UserAgent)
 			}
 		}
-		w.Init(buildLoadNotifyScript(p.callbackName))
 
 		if err := w.Bind(p.callbackName, func(payload string) error {
 			return p.handleCallback(payload)
 		}); err != nil {
+			w.Destroy()
 			p.ready <- err
+			close(p.done)
 			return
 		}
 
+		w.Init(buildLoadNotifyScript(p.callbackName))
 		applyWindowOptions(w, p.opts)
 		w.SetHtml(buildBootstrapHTML(p.callbackName, p.readyID))
+		if runtimepkg.GOOS == "linux" {
+			// All GTK pages share the process-wide event loop below.
+			return
+		}
 		w.Run()
+		p.handleNativeEvent(webview.Event{Name: "closed"})
 		w.Destroy()
 		close(p.done)
 	}
@@ -162,10 +186,15 @@ func (p *pageWrapper) AddInitScript(script string) error {
 func (p *pageWrapper) Goto(url string, opts enginewebview.GotoOptions) error {
 	startedAt := time.Now()
 	p.drainLoads()
+	for {
+		select {
+		case <-p.navigationErrors:
+			continue
+		default:
+		}
+		break
+	}
 	if err := p.dispatch(func(w webview.WebView) error {
-		p.mu.Lock()
-		p.url = url
-		p.mu.Unlock()
 		w.Navigate(url)
 		return nil
 	}); err != nil {
@@ -179,7 +208,7 @@ func (p *pageWrapper) Goto(url string, opts enginewebview.GotoOptions) error {
 	if waitUntil == "" {
 		waitUntil = "load"
 	}
-	err := p.waitForNavigation(url, timeout, waitUntil)
+	err := p.waitForNavigation(timeout, waitUntil)
 	if err != nil {
 		p.tracef("goto failed %dms url=%s err=%v", time.Since(startedAt).Milliseconds(), url, err)
 		return err
@@ -219,7 +248,12 @@ func (p *pageWrapper) Execute(expression string, args ...any) (any, error) {
 		return nil, err
 	}
 
-	result := <-ch
+	var result evalResult
+	select {
+	case result = <-ch:
+	case <-p.done:
+		return nil, fmt.Errorf("webview page is closed")
+	}
 	if result.err != nil {
 		p.tracef("execute failed %dms err=%v", time.Since(startedAt).Milliseconds(), result.err)
 		return result.value, result.err
@@ -307,6 +341,7 @@ func (p *pageWrapper) Close() error {
 		return nil
 	}
 	p.closed = true
+	p.failPendingLocked()
 	w := p.view
 	wait := p.done
 	p.mu.Unlock()
@@ -318,12 +353,18 @@ func (p *pageWrapper) Close() error {
 		// the quit message lands on the correct queue.
 		terminateDone := make(chan struct{})
 		w.Dispatch(func() {
-			w.Terminate()
+			if runtimepkg.GOOS == "linux" {
+				w.Destroy()
+				close(p.done)
+			} else {
+				w.Terminate()
+			}
 			close(terminateDone)
 		})
 		<-terminateDone
 	}
 	<-wait
+	p.events.Emit(enginewebview.Event{Name: "closed", Data: map[string]any{"reason": "api"}})
 	return nil
 }
 
@@ -334,94 +375,29 @@ func (p *pageWrapper) tracef(format string, args ...any) {
 	fmt.Printf("goprovider "+format+"\n", args...)
 }
 
-func (p *pageWrapper) waitForNavigation(targetURL string, timeout time.Duration, waitUntil string) error {
-	deadline := time.Now().Add(timeout)
-	ticker := time.NewTicker(100 * time.Millisecond)
-	defer ticker.Stop()
-
+func (p *pageWrapper) waitForNavigation(timeout time.Duration, waitUntil string) error {
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
 	for {
 		select {
+		case <-p.done:
+			return fmt.Errorf("webview page is closed")
+		case err := <-p.navigationErrors:
+			return err
+		case <-timer.C:
+			return fmt.Errorf("webview navigation timeout")
+		case <-p.sameDocument:
+			return nil
+		case <-p.domReady:
+			if waitUntil == "domcontentloaded" {
+				return nil
+			}
 		case <-p.loads:
-			if waitUntil == "load" {
-				return nil
-			}
-		case <-ticker.C:
-			state, err := p.navigationState()
-			if err == nil && state.ready(targetURL, waitUntil) {
-				return nil
-			}
-			if time.Now().After(deadline) {
-				return fmt.Errorf("webview navigation timeout")
-			}
+			return nil
 		}
 	}
 }
 
-type navigationState struct {
-	URL        string `json:"url"`
-	ReadyState string `json:"readyState"`
-}
-
-func (s navigationState) ready(targetURL string, waitUntil string) bool {
-	if s.URL == "" || s.URL == "about:blank" {
-		return false
-	}
-	switch waitUntil {
-	case "domcontentloaded":
-		if s.ReadyState == "loading" || s.ReadyState == "" {
-			return false
-		}
-	default:
-		if s.ReadyState != "complete" {
-			return false
-		}
-	}
-	if targetURL == "" {
-		return true
-	}
-	if s.URL == targetURL {
-		return true
-	}
-	target, err := parseURL(targetURL)
-	if err != nil {
-		return true
-	}
-	current, err := parseURL(s.URL)
-	if err != nil {
-		return true
-	}
-	if current.Scheme == target.Scheme && current.Host == target.Host && current.Path == target.Path {
-		return true
-	}
-	return false
-}
-
-func parseURL(raw string) (*url.URL, error) {
-	return url.Parse(raw)
-}
-
-func (p *pageWrapper) navigationState() (navigationState, error) {
-	value, err := p.Execute(`() => ({
-		url: String(location.href || ""),
-		readyState: document.readyState || "",
-	})`)
-	if err != nil {
-		return navigationState{}, err
-	}
-	stateMap, ok := value.(map[string]any)
-	if !ok {
-		return navigationState{}, fmt.Errorf("invalid navigation state")
-	}
-	state := navigationState{}
-	if urlValue, ok := stateMap["url"].(string); ok {
-		state.URL = urlValue
-	}
-	if readyValue, ok := stateMap["readyState"].(string); ok {
-		state.ReadyState = readyValue
-	}
-	return state, nil
-}
-
 func (p *pageWrapper) dispatch(fn func(w webview.WebView) error) error {
 	p.mu.Lock()
 	if p.closed {
@@ -438,7 +414,12 @@ func (p *pageWrapper) dispatch(fn func(w webview.WebView) error) error {
 	w.Dispatch(func() {
 		done <- fn(w)
 	})
-	return <-done
+	select {
+	case err := <-done:
+		return err
+	case <-p.done:
+		return fmt.Errorf("webview page is closed")
+	}
 }
 
 func (p *pageWrapper) nativeCookies() ([]nativeCookieJSON, error) {
@@ -496,7 +477,31 @@ func (p *pageWrapper) handleCallback(payload string) error {
 		}
 		return nil
 	}
+	if msg.Event == "domcontentloaded" {
+		select {
+		case p.domReady <- struct{}{}:
+		default:
+		}
+		return nil
+	}
+	if msg.Event == "url-changed" {
+		if msg.SameDocument {
+			select {
+			case p.sameDocument <- struct{}{}:
+			default:
+			}
+		}
+		p.mu.Lock()
+		changed := p.url != msg.URL
+		p.url = msg.URL
+		p.mu.Unlock()
+		if changed {
+			p.events.Emit(enginewebview.Event{Name: "url-changed", Data: map[string]any{"url": msg.URL, "sameDocument": msg.SameDocument}})
+		}
+		return nil
+	}
 	if msg.Load {
+		p.events.Emit(enginewebview.Event{Name: "load", Data: map[string]any{"url": msg.URL}})
 		select {
 		case p.loads <- msg.URL:
 		default:
@@ -521,6 +526,22 @@ func (p *pageWrapper) handleCallback(payload string) error {
 }
 
 func (p *pageWrapper) drainLoads() {
+	for {
+		select {
+		case <-p.domReady:
+			continue
+		default:
+		}
+		break
+	}
+	for {
+		select {
+		case <-p.sameDocument:
+			continue
+		default:
+		}
+		break
+	}
 	for {
 		select {
 		case <-p.loads:
@@ -582,19 +603,77 @@ func buildExecuteScript(callbackName string, reqID string, expression string, ar
 func buildLoadNotifyScript(callbackName string) string {
 	callbackJSON, _ := json.Marshal(callbackName)
 	return fmt.Sprintf(`(() => {
-  window.addEventListener("load", () => {
-    const __cb = globalThis[%s];
-    if (typeof __cb !== "function") {
-      return;
-    }
-    __cb(JSON.stringify({
-      load: true,
-      url: String(location.href || ""),
-    }));
-  }, { once: true });
+  if (window !== window.top) return;
+  // WebView2 runs init scripts in its internal error document too. Its load
+  // must not complete goto() before the native NavigationCompleted failure.
+  if (location.protocol === "chrome-error:") return;
+  const send = (message) => {
+    const cb = globalThis[%s];
+    if (typeof cb === "function") cb(JSON.stringify(message));
+  };
+  let lastURL = String(location.href);
+  const changed = () => {
+    const url = String(location.href);
+    if (url === lastURL) return;
+    lastURL = url;
+    send({event: "url-changed", url, sameDocument: true});
+  };
+  send({event: "url-changed", url: lastURL, sameDocument: false});
+  for (const name of ["pushState", "replaceState"]) {
+    const original = history[name];
+    history[name] = function(...args) {
+      const result = Reflect.apply(original, this, args);
+      changed();
+      return result;
+    };
+  }
+  window.addEventListener("hashchange", changed);
+  window.addEventListener("popstate", changed);
+  window.addEventListener("pageshow", (event) => {
+    if (event.persisted) send({event: "url-changed", url: String(location.href), sameDocument: false});
+    else changed();
+  });
+  window.addEventListener("DOMContentLoaded", () => send({event: "domcontentloaded"}), {once:true});
+  window.addEventListener("load", () => send({load: true, url: String(location.href)}), {once: true});
 })();`, string(callbackJSON))
 }
 
+func (p *pageWrapper) On(name string, handler func(enginewebview.Event)) (func(), error) {
+	return p.events.On(name, handler)
+}
+
+func (p *pageWrapper) failPendingLocked() {
+	for id, ch := range p.pending {
+		ch <- evalResult{err: fmt.Errorf("webview page is closed")}
+		delete(p.pending, id)
+	}
+}
+
+func (p *pageWrapper) handleNativeEvent(event webview.Event) {
+	switch event.Name {
+	case "load-error":
+		p.events.Emit(enginewebview.Event{Name: "load-error", Data: map[string]any{"url": event.URL, "message": event.Message}})
+		select {
+		case p.navigationErrors <- errors.New(event.Message):
+		default:
+		}
+	case "closed":
+		p.mu.Lock()
+		api := p.closed
+		p.closed = true
+		p.failPendingLocked()
+		p.mu.Unlock()
+		reason := "user"
+		if api {
+			reason = "api"
+		}
+		p.events.Emit(enginewebview.Event{Name: "closed", Data: map[string]any{"reason": reason}})
+		if runtimepkg.GOOS == "linux" && !api {
+			p.view.Dispatch(func() { p.view.Destroy(); close(p.done) })
+		}
+	}
+}
+
 func defaultWindowDimension(value int, fallback int) int {
 	if value > 0 {
 		return value
@@ -610,3 +689,12 @@ func firstNonEmpty(values ...string) string {
 	}
 	return ""
 }
+
+func (p *Provider) RemoveProfile(profileID, dataPath string) error {
+	done := make(chan error, 1)
+	run := func() { done <- webview.RemoveProfile(dataPath) }
+	if !postMainThreadTask(run) {
+		run()
+	}
+	return <-done
+}

internal/webview/goprovider/provider_integration_test.go

@@ -13,3 +13,7 @@ func TestProviderContract(t *testing.T) {
 		CookieDomainMode: integrationtest.CookieDomainModeRequired,
 	})
 }
+
+func TestProviderProfiles(t *testing.T) { integrationtest.RunProfileContract(t, New()) }
+
+func TestProviderEvents(t *testing.T) { integrationtest.RunEventContract(t, New()) }

internal/webview/integrationtest/contract.go

@@ -1,10 +1,14 @@
 package integrationtest
 
 import (
+	"crypto/sha256"
 	"fmt"
+	webviewproxy "github.com/GopeedLab/gopeed/internal/webview/proxy"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 	"time"
@@ -104,8 +108,10 @@ func RunProviderContract(t *testing.T, provider enginewebview.Provider, opts Con
 		t.Fatalf("expected click count to be 1, got %v", clickCount)
 	}
 
+	// Hidden WebViews can throttle timers on shared CI runners. Keep the
+	// positive asynchronous waits within the same budget as navigation.
 	found, err := page.WaitForSelector("#delayed", map[string]any{
-		"timeoutMs":      5000,
+		"timeoutMs":      10000,
 		"pollIntervalMs": 25,
 		"visible":        true,
 	})
@@ -113,11 +119,18 @@ func RunProviderContract(t *testing.T, provider enginewebview.Provider, opts Con
 		t.Fatalf("waitForSelector failed: %v", err)
 	}
 	if !found {
-		t.Fatal("expected delayed selector to appear")
+		diagnostic, diagnosticErr := page.Execute(`() => {
+			const element = document.querySelector('#delayed');
+			const rect = element && element.getBoundingClientRect();
+			return {url: location.href, readyState: document.readyState,
+				visibility: document.visibilityState, exists: !!element,
+				width: rect && rect.width, height: rect && rect.height};
+		}`)
+		t.Fatalf("expected delayed selector to appear: state=%v, diagnostic error=%v", diagnostic, diagnosticErr)
 	}
 
 	value, err := page.WaitForFunction(`() => window.__readyValue`, map[string]any{
-		"timeoutMs":      5000,
+		"timeoutMs":      10000,
 		"pollIntervalMs": 25,
 	})
 	if err != nil {
@@ -219,7 +232,19 @@ func openTestPage(t *testing.T, provider enginewebview.Provider, opts enginewebv
 	}))
 	t.Cleanup(server.Close)
 
-	runtime := enginewebview.NewRuntime(provider, true)
+	proxy, err := webviewproxy.New(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { proxy.Close() })
+	path := filepath.Join(t.TempDir(), "profile")
+	sum := sha256.Sum256([]byte(path))
+	profileID := fmt.Sprintf("%x-%x-%x-%x-%x", sum[:4], sum[4:6], sum[6:8], sum[8:10], sum[10:16])
+	proxyURL := proxy.URL()
+	if runtime.GOOS == "darwin" {
+		proxyURL = proxy.SOCKSURL()
+	}
+	runtime := enginewebview.NewRuntime(&configuredOpener{provider: provider, profileID: profileID, dataPath: path, proxyURL: proxyURL}, true)
 	page, err := runtime.Open(map[string]any{
 		"headless":  opts.Headless,
 		"debug":     opts.Debug,
@@ -232,7 +257,14 @@ func openTestPage(t *testing.T, provider enginewebview.Provider, opts enginewebv
 		t.Fatalf("failed to open webview: %v", err)
 	}
 	t.Cleanup(func() {
-		_ = runtime.Close()
+		if err := runtime.Close(); err != nil {
+			t.Errorf("close contract page: %v", err)
+		}
+		if remover, ok := provider.(enginewebview.ProfileRemover); ok {
+			if err := remover.RemoveProfile(profileID, path); err != nil {
+				t.Errorf("remove contract profile: %v", err)
+			}
+		}
 	})
 
 	return page, server, server.URL
@@ -380,3 +412,15 @@ func hasCookie(cookies []enginewebview.Cookie, name string, value string) bool {
 	}
 	return false
 }
+
+type configuredOpener struct {
+	provider                      enginewebview.Provider
+	profileID, dataPath, proxyURL string
+}
+
+func (o *configuredOpener) Open(opts enginewebview.OpenOptions) (enginewebview.Page, error) {
+	opts.ProfileID = o.profileID
+	opts.DataPath = o.dataPath
+	opts.ProxyURL = o.proxyURL
+	return o.provider.Open(opts)
+}

internal/webview/integrationtest/events.go

@@ -0,0 +1,110 @@
+package integrationtest
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	wv "github.com/GopeedLab/gopeed/pkg/download/engine/webview"
+)
+
+// RunEventContract exercises the same public semantics on native and RPC hosts.
+func RunEventContract(t *testing.T, provider wv.Provider) {
+	t.Helper()
+	page, _, url := openTestPage(t, provider, wv.OpenOptions{Headless: true, Title: "WebView event contract"})
+	events := make(chan wv.Event, 100)
+	for _, name := range []string{"url-changed", "load", "load-error", "closed"} {
+		if _, err := page.On(name, func(e wv.Event) { events <- e }); err != nil {
+			t.Fatal(err)
+		}
+	}
+	next := func(name string) wv.Event {
+		t.Helper()
+		select {
+		case event := <-events:
+			if event.Name != name {
+				t.Fatalf("got event %s (%v), want %s", event.Name, event.Data, name)
+			}
+			return event
+		case <-time.After(10 * time.Second):
+			t.Fatalf("timed out waiting for %s", name)
+		}
+		return wv.Event{}
+	}
+	quiet := func() {
+		t.Helper()
+		select {
+		case e := <-events:
+			t.Fatalf("unexpected event: %+v", e)
+		case <-time.After(150 * time.Millisecond):
+		}
+	}
+	quiet()
+	if err := page.AddInitScript(`globalThis.__initBeforePage = document.readyState`); err != nil {
+		t.Fatal(err)
+	}
+	if err := page.Goto(url, map[string]any{"timeoutMs": 10000}); err != nil {
+		t.Fatal(err)
+	}
+	e := next("url-changed")
+	if strings.TrimRight(fmt.Sprint(e.Data["url"]), "/") != strings.TrimRight(url, "/") || e.Data["sameDocument"] != false {
+		t.Fatal(e)
+	}
+	next("load")
+	if result, err := page.Execute(`() => globalThis.__initBeforePage`); err != nil || result != "loading" {
+		t.Fatalf("init script: %v %v", result, err)
+	}
+	if err := page.AddInitScript(`globalThis.__onlyNext = true`); err != nil {
+		t.Fatal(err)
+	}
+	if result, err := page.Execute(`() => typeof globalThis.__onlyNext`); err != nil || result != "undefined" {
+		t.Fatalf("init ran in current page: %v %v", result, err)
+	}
+	for _, expression := range []string{
+		`() => { history.pushState({}, '', '#push'); }`,
+		`() => { history.replaceState({}, '', '#replace'); }`,
+		`() => { location.hash = 'hash'; }`,
+	} {
+		if _, err := page.Execute(expression); err != nil {
+			t.Fatal(err)
+		}
+		e := next("url-changed")
+		if e.Data["sameDocument"] != true {
+			t.Fatal(e)
+		}
+		quiet()
+	}
+	if _, err := page.Execute(`() => { location.reload(); }`); err != nil {
+		t.Fatal(err)
+	}
+	next("load") // Same address on refresh is not a URL change.
+	if result, err := page.Execute(`() => globalThis.__onlyNext`); err != nil || result != true {
+		t.Fatalf("next init: %v %v", result, err)
+	}
+	if _, err := page.Execute(`() => { const f=document.createElement('iframe'); f.src='/next'; document.body.append(f); }`); err != nil {
+		t.Fatal(err)
+	}
+	quiet()
+	// The fixture serves plain HTTP. Attempting TLS against it produces a
+	// real navigation failure through both HTTP CONNECT and SOCKS proxies.
+	// An unreachable HTTP origin would instead become a valid 502 document
+	// when the host's HTTP proxy handles the connection error.
+	failedURL := strings.Replace(url, "http://", "https://", 1) + "/failure"
+	if err := page.Goto(failedURL, map[string]any{"timeoutMs": 3000}); err == nil {
+		t.Fatal("failed navigation succeeded")
+	}
+	e = next("load-error")
+	if e.Data["message"] == "" || !strings.Contains(fmt.Sprint(e.Data["url"]), "/failure") {
+		t.Fatal(e)
+	}
+	quiet() // A handled failure must not load a browser-generated fallback page.
+	if err := page.Close(); err != nil {
+		t.Fatal(err)
+	}
+	e = next("closed")
+	if e.Data["reason"] != "api" {
+		t.Fatal(e)
+	}
+	quiet()
+}

internal/webview/integrationtest/profiles.go

@@ -0,0 +1,247 @@
+package integrationtest
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	webviewproxy "github.com/GopeedLab/gopeed/internal/webview/proxy"
+	webview "github.com/GopeedLab/gopeed/pkg/download/engine/webview"
+)
+
+// RunProfileContract exercises the same host API through both native and RPC
+// providers. It never bypasses the host bridge with direct Flutter plugin calls.
+func RunProfileContract(t *testing.T, provider webview.Provider) {
+	t.Helper()
+	waitForProviderAvailable(t, provider, defaultAvailabilityTimeout)
+	remover, ok := provider.(webview.ProfileRemover)
+	if !ok {
+		t.Fatal("provider does not implement host profile removal")
+	}
+	proxyURL, secureHits := profileProxy(t)
+	a := newContractProfile(t, provider, remover, proxyURL)
+	b := newContractProfile(t, provider, remover, proxyURL)
+	first := a.open(t)
+	assertProfileValue(t, first, `async () => { localStorage.setItem('owner','a'); return 'a'; }`, "a")
+	assertProfileValue(t, first, profileDatabaseScript(true), "saved")
+	if err := first.SetCookie(webview.Cookie{Name: "session", Value: "a", Domain: "profiles.invalid", Path: "/", HTTPOnly: true, Expires: time.Now().Add(time.Hour)}); err != nil {
+		t.Fatal(err)
+	}
+	second := b.open(t)
+	assertProfileValue(t, second, `() => localStorage.getItem('owner')`, nil)
+	assertProfileValue(t, second, profileDatabaseScript(false), nil)
+	assertProfileCookies(t, second, "", "new profile B")
+	assertProfileValue(t, second, `() => { localStorage.setItem('owner','b'); return 'b'; }`, "b")
+	if err := second.SetCookie(webview.Cookie{Name: "session", Value: "b", Domain: "profiles.invalid", Path: "/", HTTPOnly: true}); err != nil {
+		t.Fatal(err)
+	}
+	shared := a.open(t)
+	assertProfileValue(t, shared, `() => localStorage.getItem('owner')`, "a")
+	assertProfileValue(t, shared, profileDatabaseScript(false), "saved")
+	assertProfileCookies(t, shared, "a", "shared profile A")
+	storedCookies, err := shared.GetCookies()
+	if err != nil || len(storedCookies) != 1 || storedCookies[0].Expires.Before(time.Now()) {
+		t.Fatalf("persistent cookie lost its expiration: %#v, error %v", storedCookies, err)
+	}
+	assertProfileValue(t, shared, `() => document.cookie`, "") // HttpOnly stays hidden.
+	if err := second.ClearCookies(); err != nil {
+		t.Fatal(err)
+	}
+	assertProfileCookies(t, first, "a", "clearing B leaves A intact")
+	if err := second.SetCookie(webview.Cookie{Name: "session", Value: "b", Domain: "profiles.invalid", Path: "/", HTTPOnly: true}); err != nil {
+		t.Fatal(err)
+	}
+	a.close(t)
+	reopened := a.open(t)
+	assertProfileValue(t, reopened, `() => localStorage.getItem('owner')`, "a")
+	assertProfileValue(t, reopened, profileDatabaseScript(false), "saved")
+	assertProfileCookies(t, reopened, "a", "reopened profile A")
+	// Include a session cookie immediately before deletion to catch stale
+	// in-process CookieStore caches when the same profile is recreated.
+	if err := reopened.SetCookie(webview.Cookie{Name: "session", Value: "remove-me", Domain: "profiles.invalid", Path: "/", HTTPOnly: true}); err != nil {
+		t.Fatal(err)
+	}
+	a.close(t)
+	a.remove(t)
+	a.remove(t) // Retrying a successful uninstall is harmless.
+	reinstalled := a.open(t)
+	assertProfileValue(t, reinstalled, `() => localStorage.getItem('owner')`, nil)
+	assertProfileValue(t, reinstalled, profileDatabaseScript(false), nil)
+	assertProfileCookies(t, reinstalled, "", "reinstalled profile A")
+	assertProfileValue(t, second, `() => localStorage.getItem('owner')`, "b")
+	assertProfileCookies(t, second, "b", "B after removing A")
+	// Refuse the HTTPS tunnel deliberately. Seeing it at our proxy proves HTTPS
+	// routing without adding a certificate-validation bypass to the test host.
+	// WebView2 may commit its built-in error page and report navigation as
+	// complete. The invariant here is that the HTTPS tunnel reaches the proxy.
+	_ = reinstalled.Goto("https://profiles.invalid/", webview.GotoOptions{TimeoutMS: 5000})
+	deadline := time.Now().Add(5 * time.Second)
+	for secureHits.Load() == 0 && time.Now().Before(deadline) {
+		time.Sleep(10 * time.Millisecond)
+	}
+	if secureHits.Load() == 0 {
+		t.Fatal("HTTPS bypassed the host proxy")
+	}
+}
+
+type contractProfile struct {
+	provider webview.Provider
+	remover  webview.ProfileRemover
+	options  webview.OpenOptions
+	pages    []webview.Page
+}
+
+func newContractProfile(t *testing.T, provider webview.Provider, remover webview.ProfileRemover, proxyURL string) *contractProfile {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "profile")
+	hash := sha256.Sum256([]byte(path))
+	id := fmt.Sprintf("%x-%x-%x-%x-%x", hash[:4], hash[4:6], hash[6:8], hash[8:10], hash[10:16])
+	p := &contractProfile{provider: provider, remover: remover, options: webview.OpenOptions{ProfileID: id, DataPath: path, ProxyURL: proxyURL, Headless: true, Title: "Gopeed profile contract"}}
+	t.Cleanup(func() { p.close(t); p.remove(t) })
+	return p
+}
+func (p *contractProfile) open(t *testing.T) webview.Page {
+	t.Helper()
+	page, err := p.provider.Open(p.options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	p.pages = append(p.pages, page)
+	if err := page.Goto("http://profiles.invalid/", webview.GotoOptions{TimeoutMS: 10000}); err != nil {
+		t.Fatal(err)
+	}
+	return page
+}
+func (p *contractProfile) close(t *testing.T) {
+	t.Helper()
+	for _, page := range p.pages {
+		if err := page.Close(); err != nil {
+			t.Errorf("close profile page: %v", err)
+		}
+	}
+	p.pages = nil
+}
+func (p *contractProfile) remove(t *testing.T) {
+	t.Helper()
+	if err := p.remover.RemoveProfile(p.options.ProfileID, p.options.DataPath); err != nil {
+		t.Errorf("remove profile: %v", err)
+	}
+}
+func assertProfileValue(t *testing.T, page webview.Page, script string, want any) {
+	t.Helper()
+	got, err := page.Execute(script)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("script %s: got %#v, want %#v", script, got, want)
+	}
+}
+func assertProfileCookies(t *testing.T, page webview.Page, want, stage string) {
+	t.Helper()
+	// Native cookie managers propagate updates across browser processes
+	// asynchronously. Wait for the expected state rather than assuming the
+	// first IPC read already includes the preceding write.
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		cookies, err := page.GetCookies()
+		if err != nil {
+			t.Fatalf("%s: %v", stage, err)
+		}
+		matches := len(cookies) == 0 && want == "" || len(cookies) == 1 && want != "" && cookies[0].Name == "session" && cookies[0].Value == want && cookies[0].HTTPOnly
+		if matches {
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("%s: cookies %#v, want %q", stage, cookies, want)
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+}
+func profileDatabaseScript(write bool) string {
+	operation := "store.get('owner')"
+	if write {
+		operation = "store.put('saved','owner')"
+	}
+	return fmt.Sprintf(`async () => await new Promise((resolve,reject)=>{
+ const request=indexedDB.open('profile-contract',1);
+ request.onupgradeneeded=()=>request.result.createObjectStore('state');
+ request.onerror=()=>reject(String(request.error));
+ request.onsuccess=()=>{
+  const db=request.result, tx=db.transaction('state','readwrite'), store=tx.objectStore('state');
+  const op=%s; let value;
+  op.onsuccess=()=>value=%s;
+  tx.oncomplete=()=>{db.close();resolve(value===undefined?null:value)};
+  tx.onerror=()=>{db.close();reject(String(tx.error))};
+ };
+})`, operation, map[bool]string{true: "'saved'", false: "op.result"}[write])
+}
+
+func profileProxy(t *testing.T) (string, *atomic.Int32) {
+	t.Helper()
+	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.Header().Set("Cache-Control", "no-store")
+		fmt.Fprint(w, "<!doctype html><title>Profile contract</title>")
+	}))
+	t.Cleanup(origin.Close)
+	secureHits := &atomic.Int32{}
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodConnect {
+			origin.Config.Handler.ServeHTTP(w, r)
+			return
+		}
+		if r.Host == "profiles.invalid:443" {
+			secureHits.Add(1)
+			http.Error(w, "HTTPS routing fixture rejects tunnels", http.StatusBadGateway)
+			return
+		}
+		if r.Host != "profiles.invalid:80" {
+			http.Error(w, "unexpected target", http.StatusBadGateway)
+			return
+		}
+		remote, err := net.DialTimeout("tcp", origin.Listener.Addr().String(), 5*time.Second)
+		if err != nil {
+			http.Error(w, "origin unavailable", http.StatusBadGateway)
+			return
+		}
+		defer remote.Close()
+		client, buffer, err := w.(http.Hijacker).Hijack()
+		if err != nil {
+			return
+		}
+		defer client.Close()
+		if _, err := buffer.WriteString("HTTP/1.1 200 Connection Established\r\n\r\n"); err != nil {
+			return
+		}
+		if err := buffer.Flush(); err != nil {
+			return
+		}
+		go func() { io.Copy(remote, buffer); remote.Close() }()
+		io.Copy(client, remote)
+	}))
+	t.Cleanup(upstream.Close)
+	upstreamURL, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proxy, err := webviewproxy.New(func(*http.Request) (*url.URL, error) { return upstreamURL, nil })
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { proxy.Close() })
+	if runtime.GOOS == "darwin" {
+		return proxy.SOCKSURL(), secureHits
+	}
+	return proxy.URL(), secureHits
+}

internal/webview/proxy/server.go

@@ -0,0 +1,341 @@
+// Package proxy provides the host-owned WebView forward proxy. Browser engines
+// always use this endpoint; Gopeed decides the upstream route for each request.
+package proxy
+
+import (
+	"bufio"
+	"context"
+	"crypto/tls"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/armon/go-socks5"
+	xproxy "golang.org/x/net/proxy"
+)
+
+type Selector func(*http.Request) (*url.URL, error)
+
+type Server struct {
+	listener      net.Listener
+	socksListener net.Listener
+	server        *http.Server
+	transport     *http.Transport
+	selectProxy   Selector
+	mu            sync.Mutex
+	connections   map[io.Closer]struct{}
+	closed        bool
+}
+
+func New(selectProxy Selector) (*Server, error) {
+	if selectProxy == nil {
+		selectProxy = func(*http.Request) (*url.URL, error) { return nil, nil }
+	}
+	listener, err := net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		return nil, err
+	}
+	s := &Server{listener: listener, selectProxy: selectProxy, connections: make(map[io.Closer]struct{})}
+	s.transport = &http.Transport{Proxy: selectProxy, DisableKeepAlives: true, TLSHandshakeTimeout: 15 * time.Second, ResponseHeaderTimeout: 30 * time.Second}
+	s.server = &http.Server{Handler: s, ReadHeaderTimeout: 15 * time.Second}
+	s.socksListener, err = net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		listener.Close()
+		return nil, err
+	}
+	socks, err := socks5.New(&socks5.Config{Logger: log.New(io.Discard, "", 0), Resolver: unresolvedDNS{}, Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
+		_, port, _ := net.SplitHostPort(address)
+		scheme := "https"
+		if port == "80" {
+			scheme = "http"
+		}
+		request := &http.Request{URL: &url.URL{Scheme: scheme, Host: address}, Header: make(http.Header)}
+		upstream, err := selectProxy(request)
+		if err != nil {
+			return nil, err
+		}
+		timed, cancel := context.WithTimeout(ctx, 30*time.Second)
+		defer cancel()
+		conn, err := dialTunnel(timed, address, upstream)
+		if err != nil {
+			return nil, err
+		}
+		return s.track(conn)
+	}})
+	if err != nil {
+		listener.Close()
+		s.socksListener.Close()
+		return nil, err
+	}
+	go s.server.Serve(listener)
+	go socks.Serve(&trackedListener{Listener: s.socksListener, server: s})
+	return s, nil
+}
+
+func (s *Server) URL() string { return "http://" + s.listener.Addr().String() }
+
+func (s *Server) SOCKSURL() string { return "socks5://" + s.socksListener.Addr().String() }
+
+func (s *Server) Close() error {
+	s.mu.Lock()
+	s.closed = true
+	connections := make([]io.Closer, 0, len(s.connections))
+	for c := range s.connections {
+		connections = append(connections, c)
+	}
+	s.mu.Unlock()
+	for _, c := range connections {
+		c.Close()
+	}
+	s.socksListener.Close()
+	s.transport.CloseIdleConnections()
+	return s.server.Close()
+}
+
+func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.Method == http.MethodConnect {
+		s.connect(w, r)
+		return
+	}
+	if !r.URL.IsAbs() || (r.URL.Scheme != "http" && r.URL.Scheme != "https") {
+		http.Error(w, "absolute HTTP URL required", http.StatusBadRequest)
+		return
+	}
+	out := r.Clone(r.Context())
+	out.RequestURI = ""
+	upgrade := out.Header.Get("Upgrade")
+	stripHopHeaders(out.Header)
+	if upgrade != "" {
+		out.Header.Set("Connection", "Upgrade")
+		out.Header.Set("Upgrade", upgrade)
+	}
+	resp, err := s.transport.RoundTrip(out)
+	if err != nil {
+		http.Error(w, "upstream request failed", http.StatusBadGateway)
+		return
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusSwitchingProtocols {
+		remote, ok := resp.Body.(io.ReadWriteCloser)
+		if !ok {
+			http.Error(w, "invalid upstream upgrade", 502)
+			return
+		}
+		client, buffer, err := w.(http.Hijacker).Hijack()
+		if err != nil {
+			return
+		}
+		defer client.Close()
+		resp.Body = nil
+		if err := resp.Write(buffer); err != nil {
+			return
+		}
+		if err := buffer.Flush(); err != nil {
+			return
+		}
+		s.bridge(client, buffer, remote)
+		return
+	}
+	stripHopHeaders(resp.Header)
+	for k, v := range resp.Header {
+		w.Header()[k] = v
+	}
+	w.WriteHeader(resp.StatusCode)
+	io.Copy(w, resp.Body)
+}
+
+func stripHopHeaders(h http.Header) {
+	for _, key := range strings.Split(h.Get("Connection"), ",") {
+		h.Del(strings.TrimSpace(key))
+	}
+	for _, key := range []string{"Connection", "Proxy-Connection", "Proxy-Authorization", "Proxy-Authenticate", "Keep-Alive", "TE", "Trailer", "Transfer-Encoding", "Upgrade"} {
+		h.Del(key)
+	}
+}
+
+func (s *Server) connect(w http.ResponseWriter, r *http.Request) {
+	if _, _, err := net.SplitHostPort(r.Host); err != nil {
+		http.Error(w, "invalid tunnel destination", 400)
+		return
+	}
+	target := r.Clone(r.Context())
+	target.URL = &url.URL{Scheme: "https", Host: r.Host}
+	upstream, err := s.selectProxy(target)
+	if err != nil {
+		http.Error(w, "proxy selection failed", 502)
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+	defer cancel()
+	remote, err := dialTunnel(ctx, r.Host, upstream)
+	if err != nil {
+		http.Error(w, "upstream connection failed", 502)
+		return
+	}
+	defer remote.Close()
+	client, buffer, err := w.(http.Hijacker).Hijack()
+	if err != nil {
+		return
+	}
+	defer client.Close()
+	if _, err := buffer.WriteString("HTTP/1.1 200 Connection Established\r\n\r\n"); err != nil {
+		return
+	}
+	if err := buffer.Flush(); err != nil {
+		return
+	}
+	s.bridge(client, buffer, remote)
+}
+
+func (s *Server) bridge(client net.Conn, buffer *bufio.ReadWriter, remote io.ReadWriteCloser) {
+	s.mu.Lock()
+	if s.closed {
+		s.mu.Unlock()
+		return
+	}
+	s.connections[client] = struct{}{}
+	s.connections[remote] = struct{}{}
+	s.mu.Unlock()
+	defer func() { s.mu.Lock(); delete(s.connections, client); delete(s.connections, remote); s.mu.Unlock() }()
+
+	done := make(chan struct{})
+	go func() { io.Copy(remote, buffer); remote.Close(); close(done) }()
+	io.Copy(client, remote)
+	client.Close()
+	<-done
+}
+
+type bufferedConn struct {
+	net.Conn
+	reader *bufio.Reader
+}
+
+func (c *bufferedConn) Read(p []byte) (int, error) { return c.reader.Read(p) }
+
+func dialTunnel(ctx context.Context, target string, upstream *url.URL) (net.Conn, error) {
+	dialer := &net.Dialer{}
+	if upstream == nil {
+		return dialer.DialContext(ctx, "tcp", target)
+	}
+	if upstream.Scheme == "socks5" || upstream.Scheme == "socks5h" {
+		u := *upstream
+		u.Scheme = "socks5"
+		d, err := xproxy.FromURL(&u, dialer)
+		if err != nil {
+			return nil, err
+		}
+		return d.(xproxy.ContextDialer).DialContext(ctx, "tcp", target)
+	}
+	if upstream.Scheme != "http" && upstream.Scheme != "https" {
+		return nil, errors.New("unsupported proxy scheme")
+	}
+	host := upstream.Host
+	if upstream.Port() == "" {
+		port := "80"
+		if upstream.Scheme == "https" {
+			port = "443"
+		}
+		host = net.JoinHostPort(upstream.Hostname(), port)
+	}
+	conn, err := dialer.DialContext(ctx, "tcp", host)
+	if err != nil {
+		return nil, err
+	}
+	ok := false
+	defer func() {
+		if !ok {
+			conn.Close()
+		}
+	}()
+	if deadline, exists := ctx.Deadline(); exists {
+		conn.SetDeadline(deadline)
+	}
+	if upstream.Scheme == "https" {
+		secure := tls.Client(conn, &tls.Config{ServerName: upstream.Hostname(), MinVersion: tls.VersionTLS12})
+		if err := secure.HandshakeContext(ctx); err != nil {
+			return nil, err
+		}
+		conn = secure
+	}
+	request := &http.Request{Method: http.MethodConnect, URL: &url.URL{Opaque: target}, Host: target, Header: make(http.Header)}
+	if upstream.User != nil {
+		password, _ := upstream.User.Password()
+		request.Header.Set("Proxy-Authorization", "Basic "+base64.StdEncoding.EncodeToString([]byte(upstream.User.Username()+":"+password)))
+	}
+	if err := request.Write(conn); err != nil {
+		return nil, err
+	}
+	reader := bufio.NewReader(conn)
+	response, err := http.ReadResponse(reader, request)
+	if err != nil {
+		return nil, err
+	}
+	if response.StatusCode != 200 {
+		response.Body.Close()
+		return nil, fmt.Errorf("upstream CONNECT status %d", response.StatusCode)
+	}
+	conn.SetDeadline(time.Time{})
+	ok = true
+	return &bufferedConn{Conn: conn, reader: reader}, nil
+}
+
+// Leave hostname resolution to the selected upstream (SOCKS remote DNS / CONNECT).
+type unresolvedDNS struct{}
+
+func (unresolvedDNS) Resolve(ctx context.Context, name string) (context.Context, net.IP, error) {
+	return ctx, nil, nil
+}
+
+type trackedListener struct {
+	net.Listener
+	server *Server
+}
+
+func (l *trackedListener) Accept() (net.Conn, error) {
+	c, err := l.Listener.Accept()
+	if err != nil {
+		return nil, err
+	}
+	return l.server.track(c)
+}
+
+type trackedConn struct {
+	net.Conn
+	server *Server
+}
+
+func (c *trackedConn) Close() error {
+	err := c.Conn.Close()
+	c.server.mu.Lock()
+	delete(c.server.connections, c)
+	c.server.mu.Unlock()
+	return err
+}
+func (s *Server) track(c net.Conn) (net.Conn, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		c.Close()
+		return nil, net.ErrClosed
+	}
+	tracked := &trackedConn{Conn: c, server: s}
+	s.connections[tracked] = struct{}{}
+	return tracked, nil
+}
+
+func (c *trackedConn) CloseWrite() error  { return closeWrite(c.Conn) }
+func (c *bufferedConn) CloseWrite() error { return closeWrite(c.Conn) }
+func closeWrite(c net.Conn) error {
+	if writer, ok := c.(interface{ CloseWrite() error }); ok {
+		return writer.CloseWrite()
+	}
+	return c.Close()
+}

internal/webview/proxy/server_test.go

@@ -0,0 +1,315 @@
+package proxy
+
+import (
+	"bufio"
+	"context"
+	"crypto/tls"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/armon/go-socks5"
+)
+
+func TestRejectedProxyRequests(t *testing.T) {
+	secret := "upstream-password"
+	for _, tc := range []struct {
+		name, method, target string
+		status               int
+	}{
+		{"relative URL", "GET", "/relative", 400},
+		{"unsupported URL", "GET", "ftp://example.com/file", 400},
+		{"invalid CONNECT", "CONNECT", "example.com", 400},
+		{"HTTP selection failure", "GET", "http://example.com/", 502},
+		{"CONNECT selection failure", "CONNECT", "example.com:443", 502},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			s := &Server{selectProxy: func(*http.Request) (*url.URL, error) { return nil, errors.New(secret) }}
+			s.transport = &http.Transport{Proxy: s.selectProxy}
+			defer s.transport.CloseIdleConnections()
+			response := httptest.NewRecorder()
+			s.ServeHTTP(response, httptest.NewRequest(tc.method, tc.target, nil))
+			if response.Code != tc.status || strings.Contains(response.Body.String(), secret) {
+				t.Fatalf("unexpected proxy rejection: %d %q", response.Code, response.Body.String())
+			}
+		})
+	}
+}
+
+func TestTunnelRejectsUnsafeUpstreams(t *testing.T) {
+	rejected := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "authentication required", http.StatusProxyAuthRequired)
+	}))
+	defer rejected.Close()
+	secure := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Error("untrusted TLS proxy received a request")
+	}))
+	defer secure.Close()
+	for _, upstream := range []string{"ftp://127.0.0.1", rejected.URL, secure.URL} {
+		t.Run(upstream, func(t *testing.T) {
+			selected, err := url.Parse(upstream)
+			if err != nil {
+				t.Fatal(err)
+			}
+			ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+			defer cancel()
+			conn, err := dialTunnel(ctx, "example.com:443", selected)
+			if conn != nil {
+				conn.Close()
+			}
+			if err == nil {
+				t.Fatal("unsafe upstream unexpectedly accepted")
+			}
+		})
+	}
+}
+
+func TestRoutesAndAuthentication(t *testing.T) {
+	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Proxy-Authorization") != "" {
+			t.Error("proxy credentials leaked to origin")
+		}
+		w.Write([]byte("origin"))
+	}))
+	defer origin.Close()
+	secure := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("secure")) }))
+	defer secure.Close()
+	upstream, err := New(func(*http.Request) (*url.URL, error) { return nil, nil })
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer upstream.Close()
+	var authenticated atomic.Int32
+	authProxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Proxy-Authorization") != "Basic dXNlcjpwYXNz" {
+			http.Error(w, "authentication required", 407)
+			return
+		}
+		authenticated.Add(1)
+		upstream.ServeHTTP(w, r)
+	}))
+	defer authProxy.Close()
+	socks, err := socks5.New(&socks5.Config{Credentials: socks5.StaticCredentials{"user": "pass"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer listener.Close()
+	go socks.Serve(listener)
+	for _, route := range []string{"", authProxy.URL, "socks5://" + listener.Addr().String()} {
+		t.Run(route, func(t *testing.T) {
+			var selected *url.URL
+			if route != "" {
+				selected, _ = url.Parse(route)
+				selected.User = url.UserPassword("user", "pass")
+			}
+			local, err := New(func(r *http.Request) (*url.URL, error) { return selected, nil })
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer local.Close()
+			proxyURL, _ := url.Parse(local.URL())
+			transport := &http.Transport{Proxy: http.ProxyURL(proxyURL), TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}
+			defer transport.CloseIdleConnections()
+			client := &http.Client{Transport: transport, Timeout: 5 * time.Second}
+			for _, test := range []struct{ url, want string }{{origin.URL, "origin"}, {secure.URL, "secure"}} {
+				response, err := client.Get(test.url)
+				if err != nil {
+					t.Fatal(err)
+				}
+				body, _ := io.ReadAll(response.Body)
+				response.Body.Close()
+				if string(body) != test.want {
+					t.Fatalf("got status %d, body %q", response.StatusCode, body)
+				}
+			}
+		})
+	}
+	if authenticated.Load() != 2 {
+		t.Fatalf("expected authenticated HTTP and CONNECT, got %d", authenticated.Load())
+	}
+}
+
+func TestRoutingChangesAndFailureDoesNotBypassProxy(t *testing.T) {
+	var hits atomic.Int32
+	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { hits.Add(1); w.Write([]byte("direct")) }))
+	defer origin.Close()
+	var useProxy atomic.Bool
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("proxied")) }))
+	upstreamURL, _ := url.Parse(upstream.URL)
+	local, err := New(func(*http.Request) (*url.URL, error) {
+		if useProxy.Load() {
+			return upstreamURL, nil
+		}
+		return nil, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer local.Close()
+	endpoint, _ := url.Parse(local.URL())
+	transport := &http.Transport{Proxy: http.ProxyURL(endpoint)}
+	defer transport.CloseIdleConnections()
+	client := &http.Client{Transport: transport, Timeout: 3 * time.Second}
+	for _, want := range []string{"direct", "proxied", "upstream request failed\n"} {
+		resp, err := client.Get(origin.URL)
+		if err != nil {
+			t.Fatal(err)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		if string(body) != want {
+			t.Fatalf("got %q want %q", body, want)
+		}
+		if want == "direct" {
+			useProxy.Store(true)
+		} else if want == "proxied" {
+			upstream.Close()
+		}
+	}
+	if hits.Load() != 1 {
+		t.Fatal("failed proxy must not fall back to direct")
+	}
+}
+
+func TestCloseTerminatesTunnels(t *testing.T) {
+	echo, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer echo.Close()
+	go func() {
+		c, e := echo.Accept()
+		if e == nil {
+			defer c.Close()
+			io.Copy(c, c)
+		}
+	}()
+	s, err := New(func(*http.Request) (*url.URL, error) { return nil, nil })
+	if err != nil {
+		t.Fatal(err)
+	}
+	endpoint, _ := url.Parse(s.URL())
+	c, err := dialTunnel(context.Background(), echo.Addr().String(), endpoint)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close()
+	c.SetDeadline(time.Now().Add(3 * time.Second))
+	c.Write([]byte("hello\n"))
+	line, err := bufio.NewReader(c).ReadString('\n')
+	if err != nil || line != "hello\n" {
+		t.Fatalf("echo %q %v", line, err)
+	}
+	s.Close()
+	if _, err := c.Read(make([]byte, 1)); err == nil {
+		t.Fatal("tunnel stayed open")
+	}
+}
+
+func TestSOCKSIngressPreservesRemoteDNS(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "CONNECT" || r.Host != "unresolved.invalid:80" {
+			t.Errorf("lost destination: %s %s", r.Method, r.Host)
+		}
+		c, b, err := w.(http.Hijacker).Hijack()
+		if err != nil {
+			return
+		}
+		defer c.Close()
+		b.WriteString("HTTP/1.1 200 Connection Established\r\n\r\n")
+		b.Flush()
+		request, err := http.ReadRequest(b.Reader)
+		if err != nil {
+			t.Error(err)
+			return
+		}
+		request.Body.Close()
+		b.WriteString("HTTP/1.1 200 OK\r\nContent-Length: 7\r\nConnection: close\r\n\r\nproxied")
+		b.Flush()
+	}))
+	defer upstream.Close()
+	target, _ := url.Parse(upstream.URL)
+	local, err := New(func(r *http.Request) (*url.URL, error) {
+		if r.URL.Host != "unresolved.invalid:80" {
+			t.Errorf("selector lost hostname: %s", r.URL)
+		}
+		return target, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer local.Close()
+	endpoint, _ := url.Parse(local.SOCKSURL())
+	transport := &http.Transport{Proxy: http.ProxyURL(endpoint)}
+	defer transport.CloseIdleConnections()
+	client := &http.Client{Transport: transport, Timeout: 5 * time.Second}
+	response, err := client.Get("http://unresolved.invalid/")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer response.Body.Close()
+	body, _ := io.ReadAll(response.Body)
+	if string(body) != "proxied" {
+		t.Fatalf("unexpected body %q", body)
+	}
+}
+
+func TestHTTPUpgradeIsForwarded(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Upgrade") != "fixture" {
+			http.Error(w, "upgrade lost", 400)
+			return
+		}
+		c, b, err := w.(http.Hijacker).Hijack()
+		if err != nil {
+			return
+		}
+		defer c.Close()
+		b.WriteString("HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: fixture\r\n\r\n")
+		b.Flush()
+		line, err := b.ReadString('\n')
+		if err != nil {
+			return
+		}
+		b.WriteString(line)
+		b.Flush()
+	}))
+	defer upstream.Close()
+	local, err := New(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer local.Close()
+	endpoint, _ := url.Parse(local.URL())
+	c, err := net.Dial("tcp", endpoint.Host)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close()
+	c.SetDeadline(time.Now().Add(3 * time.Second))
+	io.WriteString(c, "GET "+upstream.URL+"/ HTTP/1.1\r\nHost: fixture\r\nConnection: Upgrade\r\nUpgrade: fixture\r\n\r\n")
+	reader := bufio.NewReader(c)
+	response, err := http.ReadResponse(reader, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if response.StatusCode != 101 {
+		t.Fatalf("upgrade failed: %s", response.Status)
+	}
+	io.WriteString(c, "hello\n")
+	line, err := reader.ReadString('\n')
+	if err != nil || line != "hello\n" {
+		t.Fatalf("upgraded echo %q %v", line, err)
+	}
+}

internal/webview/rpcprovider/README.md

@@ -1,5 +1,11 @@
 # rpcprovider
 
+The private Flutter native profile bridge is maintained in the
+[GopeedLab flutter_inappwebview fork](https://github.com/GopeedLab/flutter_inappwebview/tree/codex/gopeed-profiles).
+All three platform overrides pin one commit in `ui/flutter/pubspec.yaml`;
+see the fork’s [GOPEED.md](https://github.com/GopeedLab/flutter_inappwebview/blob/codex/gopeed-profiles/GOPEED.md)
+for patch scope and upstream synchronization.
+
 `rpcprovider` is the RPC-backed implementation of Gopeed's `webview.Provider` interface.
 
 It is intended for environments where WebView capability is owned by another process, most notably mobile hosts. This package does not implement a WebView itself. Instead, it translates the `pkg/download/engine/webview` page API into single-request `POST + JSON` calls sent to a local host-side RPC service.

internal/webview/rpcprovider/events_test.go

@@ -0,0 +1,207 @@
+package rpcprovider
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	wv "github.com/GopeedLab/gopeed/pkg/download/engine/webview"
+)
+
+func TestPageEventStream(t *testing.T) {
+	events := make(chan wv.Event, 8)
+	disconnected := make(chan struct{})
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var request wv.RPCRequest
+		if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+			t.Error(err)
+			return
+		}
+		if request.Method != "page.events" {
+			t.Errorf("unexpected method %s", request.Method)
+			return
+		}
+		if r.Header.Get("Authorization") != "Bearer test" {
+			t.Error("missing authorization")
+		}
+		defer close(disconnected)
+		enc := json.NewEncoder(w)
+		_ = enc.Encode(map[string]any{"ready": true})
+		w.(http.Flusher).Flush()
+		for {
+			select {
+			case e := <-events:
+				_ = enc.Encode(e)
+				w.(http.Flusher).Flush()
+				if e.Name == "closed" {
+					return
+				}
+			case <-r.Context().Done():
+				return
+			}
+		}
+	}))
+	defer server.Close()
+	p := &page{client: NewClient(wv.RPCConfig{Network: "tcp", Address: strings.TrimPrefix(server.URL, "http://"), Token: "test"}), id: "page-1"}
+	got := make(chan wv.Event, 8)
+	off, err := p.On("load", func(e wv.Event) { got <- e })
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = p.On("closed", func(e wv.Event) { got <- e })
+	if err != nil {
+		t.Fatal(err)
+	}
+	events <- wv.Event{Name: "load", Data: map[string]any{"url": "https://example.test"}}
+	select {
+	case e := <-got:
+		if e.Name != "load" {
+			t.Fatal(e)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("no load event")
+	}
+	off()
+	off()
+	events <- wv.Event{Name: "load"}
+	events <- wv.Event{Name: "closed", Data: map[string]any{"reason": "user"}}
+	select {
+	case e := <-got:
+		if e.Name != "closed" || e.Data["reason"] != "user" {
+			t.Fatal(e)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("no closed event")
+	}
+	select {
+	case <-disconnected:
+	case <-time.After(time.Second):
+		t.Fatal("stream retained after close")
+	}
+	if _, err = p.On("load", func(wv.Event) {}); err == nil {
+		t.Fatal("registration after close")
+	}
+}
+
+func TestPageEventStreamHandshakeFailureCanRetry(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		status int
+		body   string
+	}{
+		{"http_error", http.StatusUnauthorized, `{"ready":true}`},
+		{"invalid_json", http.StatusOK, `not json`},
+		{"not_ready", http.StatusOK, `{"ready":false}`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var requests atomic.Int32
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if requests.Add(1) == 1 {
+					w.WriteHeader(tc.status)
+					_, _ = io.WriteString(w, tc.body)
+					return
+				}
+				_, _ = io.WriteString(w, "{\"ready\":true}\n{\"event\":\"load\",\"data\":{\"url\":\"https://example.test\"}}\n")
+				w.(http.Flusher).Flush()
+				<-r.Context().Done()
+			}))
+			defer server.Close()
+			p := &page{client: NewClient(wv.RPCConfig{Network: "tcp", Address: strings.TrimPrefix(server.URL, "http://")}), id: "retry-page"}
+			if off, err := p.On("load", func(wv.Event) { t.Error("failed registration retained its listener") }); err == nil || off != nil {
+				t.Fatal("failed handshake accepted")
+			}
+			got := make(chan wv.Event, 1)
+			off, err := p.On("load", func(e wv.Event) { got <- e })
+			if err != nil {
+				t.Fatalf("retry: %v", err)
+			}
+			defer func() {
+				p.eventCancel()
+				<-p.eventDone
+			}()
+			defer off()
+			select {
+			case e := <-got:
+				if e.Data["url"] != "https://example.test" {
+					t.Fatal(e)
+				}
+			case <-time.After(time.Second):
+				t.Fatal("retry did not receive load notification")
+			}
+			if requests.Load() != 2 {
+				t.Fatalf("unexpected request count: %d", requests.Load())
+			}
+		})
+	}
+}
+
+func TestPageEventStreamDisconnectAndClose(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var request wv.RPCRequest
+		if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+			t.Error(err)
+			return
+		}
+		switch request.Method {
+		case wv.MethodPageEvents:
+			// End the stream without a terminal event, as if the host dropped it.
+			_, _ = io.WriteString(w, "{\"ready\":true}\n")
+		case wv.MethodPageClose:
+			_ = json.NewEncoder(w).Encode(wv.RPCResponse{})
+		default:
+			t.Errorf("unexpected method: %s", request.Method)
+		}
+	}))
+	defer server.Close()
+	p := &page{client: NewClient(wv.RPCConfig{Network: "tcp", Address: strings.TrimPrefix(server.URL, "http://")}), id: "disconnected-page"}
+	closed := make(chan wv.Event, 1)
+	if _, err := p.On("closed", func(e wv.Event) { closed <- e }); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case <-p.eventDone:
+	case <-time.After(time.Second):
+		t.Fatal("disconnected stream did not stop")
+	}
+	if _, err := p.On("load", func(wv.Event) {}); err == nil || !strings.Contains(err.Error(), "disconnected") {
+		t.Fatalf("registration hid stream failure: %v", err)
+	}
+	if err := p.Close(); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case event := <-closed:
+		if event.Data["reason"] != "api" {
+			t.Fatal(event)
+		}
+	default:
+		t.Fatal("API close did not release listeners after disconnect")
+	}
+	if err := p.Close(); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case event := <-closed:
+		t.Fatalf("duplicate close notification: %+v", event)
+	default:
+	}
+}
+
+func TestPageEventStreamConnectionFailureCanRetry(t *testing.T) {
+	server := httptest.NewServer(http.NotFoundHandler())
+	server.Close()
+	p := &page{client: NewClient(wv.RPCConfig{Network: "tcp", Address: strings.TrimPrefix(server.URL, "http://")}), id: "offline-page"}
+	for i := 0; i < 2; i++ {
+		if off, err := p.On("load", func(wv.Event) {}); err == nil || off != nil {
+			t.Fatal("registration to unavailable host succeeded")
+		}
+	}
+	if p.eventCancel != nil {
+		t.Fatal("failed connection retained an active stream")
+	}
+}

internal/webview/rpcprovider/provider.go

@@ -4,10 +4,13 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net"
 	"net/http"
 	"strings"
+	"sync"
+	"time"
 
 	enginewebview "github.com/GopeedLab/gopeed/pkg/download/engine/webview"
 )
@@ -48,8 +51,13 @@ func (p *Provider) Open(opts enginewebview.OpenOptions) (enginewebview.Page, err
 }
 
 type page struct {
-	client *Client
-	id     string
+	eventMu     sync.Mutex
+	events      enginewebview.EventHub
+	eventCancel context.CancelFunc
+	eventDone   chan struct{}
+	eventErr    error
+	client      *Client
+	id          string
 }
 
 func (p *page) AddInitScript(script string) error {
@@ -109,9 +117,28 @@ func (p *page) ClearCookies() error {
 }
 
 func (p *page) Close() error {
-	return p.client.Call(enginewebview.MethodPageClose, enginewebview.PageCloseParams{
-		PageID: p.id,
-	}, nil)
+	err := p.client.Call(enginewebview.MethodPageClose, enginewebview.PageCloseParams{PageID: p.id}, nil)
+	var rpcErr *enginewebview.RPCError
+	if errors.As(err, &rpcErr) && rpcErr.Code == enginewebview.ErrorCodePageNotFound {
+		err = nil
+	}
+	if err != nil {
+		return err
+	}
+	p.eventMu.Lock()
+	cancel, done := p.eventCancel, p.eventDone
+	p.eventMu.Unlock()
+	if cancel != nil {
+		// Drain the terminal notification before cancelling the transport, so
+		// already-sent navigation events keep their order before closed.
+		select {
+		case <-done:
+		case <-time.After(5 * time.Second):
+		}
+		cancel()
+	}
+	p.events.Emit(enginewebview.Event{Name: "closed", Data: map[string]any{"reason": "api"}})
+	return nil
 }
 
 type Client struct {
@@ -193,3 +220,83 @@ func (c *Client) Call(method string, params any, result any) error {
 	}
 	return json.Unmarshal(body.Result, result)
 }
+
+func (p *Provider) RemoveProfile(profileID, dataPath string) error {
+	return p.client.Call(enginewebview.MethodProfileRemove, enginewebview.ProfileRemoveParams{ProfileID: profileID}, nil)
+}
+
+// On starts one ordered notification stream per page. The ready record is sent
+// only after the host has installed its subscription.
+func (p *page) On(name string, handler func(enginewebview.Event)) (func(), error) {
+	p.eventMu.Lock()
+	defer p.eventMu.Unlock()
+	if p.eventErr != nil {
+		return nil, p.eventErr
+	}
+	unsubscribe, err := p.events.On(name, handler)
+	if err != nil {
+		return nil, err
+	}
+	if p.eventCancel != nil {
+		return unsubscribe, nil
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	payload, err := json.Marshal(enginewebview.RPCRequest{Method: enginewebview.MethodPageEvents, Params: enginewebview.PageCloseParams{PageID: p.id}})
+	if err != nil {
+		cancel()
+		unsubscribe()
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.client.endpoint, bytes.NewReader(payload))
+	if err != nil {
+		cancel()
+		unsubscribe()
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if p.client.token != "" {
+		req.Header.Set("Authorization", "Bearer "+p.client.token)
+	}
+	// A broken host must not leave registration pending indefinitely.
+	timer := time.AfterFunc(30*time.Second, cancel)
+	resp, err := p.client.http.Do(req)
+	if err != nil {
+		timer.Stop()
+		cancel()
+		unsubscribe()
+		return nil, err
+	}
+	decoder := json.NewDecoder(resp.Body)
+	var ready struct {
+		Ready bool `json:"ready"`
+	}
+	err = decoder.Decode(&ready)
+	timer.Stop()
+	if err != nil || !ready.Ready || resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		cancel()
+		unsubscribe()
+		return nil, fmt.Errorf("webview event stream did not become ready: %v", err)
+	}
+	p.eventCancel = cancel
+	p.eventDone = make(chan struct{})
+	go func() {
+		defer resp.Body.Close()
+		defer cancel()
+		defer close(p.eventDone)
+		for {
+			var event enginewebview.Event
+			if err := decoder.Decode(&event); err != nil {
+				p.eventMu.Lock()
+				p.eventErr = fmt.Errorf("webview event stream disconnected: %w", err)
+				p.eventMu.Unlock()
+				return
+			}
+			p.events.Emit(event)
+			if event.Name == "closed" {
+				return
+			}
+		}
+	}()
+	return unsubscribe, nil
+}

internal/webview/rpcprovider/provider_integration_test.go

@@ -37,3 +37,12 @@ func defaultWebViewRPCAddress() string {
 	}
 	return filepath.Join(homeDir, "Library", "Application Support", "com.gopeed.gopeed", "gopeed_webview.sock")
 }
+
+func TestProviderProfiles(t *testing.T) {
+	provider := New(enginewebview.RPCConfig{Network: *webViewRPCNetwork, Address: *webViewRPCAddress, Token: *webViewRPCToken})
+	integrationtest.RunProfileContract(t, provider)
+}
+
+func TestProviderEvents(t *testing.T) {
+	integrationtest.RunEventContract(t, New(enginewebview.RPCConfig{Network: *webViewRPCNetwork, Address: *webViewRPCAddress, Token: *webViewRPCToken}))
+}

internal/webview/rpcprovider/provider_test.go

@@ -184,3 +184,29 @@ func TestPageSetCookieParamsOmitsZeroExpires(t *testing.T) {
 		t.Fatalf("expected expires in payload: %s", got)
 	}
 }
+
+func TestRemoveProfileUsesPrivateHostRPC(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var request struct {
+			Method string            `json:"method"`
+			Params map[string]string `json:"params"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+			t.Error(err)
+		}
+		if request.Method != enginewebview.MethodProfileRemove || request.Params["profileId"] != "extension-profile" || len(request.Params) != 1 {
+			t.Errorf("unexpected profile removal request: %+v", request)
+		}
+		if r.Header.Get("Authorization") != "Bearer secret" {
+			t.Error("missing host authentication")
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"error":{"code":"PROFILE_REMOVE_FAILED","message":"store busy"}}`))
+	}))
+	defer server.Close()
+	provider := New(enginewebview.RPCConfig{Network: "tcp", Address: strings.TrimPrefix(server.URL, "http://"), Token: "secret"})
+	err := provider.(enginewebview.ProfileRemover).RemoveProfile("extension-profile", "/host-only/path")
+	if err == nil || err.Error() != "store busy" {
+		t.Fatalf("cleanup failure was lost: %v", err)
+	}
+}

pkg/api/events.go

@@ -10,8 +10,15 @@ import (
 type TaskEventMask uint64
 
 const (
+	// Keep these first two unchanged because Flutter already uses
+	// bit 0 for done and bit 1 for error.
 	TaskEventDone TaskEventMask = 1 << iota
 	TaskEventError
+
+	TaskEventStart
+	TaskEventProgress
+	TaskEventPause
+	TaskEventDelete
 )
 
 type TaskEvent struct {
@@ -42,11 +49,26 @@ func (s *Service) emitTaskEvent(event *download.Event) {
 	}
 
 	var mask TaskEventMask
+
 	switch event.Key {
 	case download.EventKeyDone:
 		mask = TaskEventDone
+
 	case download.EventKeyError:
 		mask = TaskEventError
+
+	case download.EventKeyStart:
+		mask = TaskEventStart
+
+	case download.EventKeyProgress:
+		mask = TaskEventProgress
+
+	case download.EventKeyPause:
+		mask = TaskEventPause
+
+	case download.EventKeyDelete:
+		mask = TaskEventDelete
+
 	default:
 		return
 	}

pkg/api/routes.go

@@ -2,6 +2,7 @@ package api
 
 import (
 	"fmt"
+	"net/url"
 	pathpkg "path"
 	"strings"
 )
@@ -75,7 +76,11 @@ func (r RouteSpec) Match(rawPath string) (map[string]string, bool) {
 	params := make(map[string]string)
 	for index, part := range r.parts {
 		if part.param != "" {
-			params[part.param] = segments[index]
+			value, err := url.PathUnescape(segments[index])
+			if err != nil {
+				return nil, false
+			}
+			params[part.param] = value
 			continue
 		}
 		if part.literal != segments[index] {

pkg/api/service.go

@@ -2,7 +2,9 @@ package api
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/url"
@@ -62,6 +64,8 @@ func NewService(downloader *download.Downloader) (*Service, error) {
 		newRoute(http.MethodGet, "/api/v1/tasks/{id}/status", service.getTaskStatus),
 		newRoute(http.MethodGet, "/api/v1/tasks", service.getTasks),
 		newRoute(http.MethodGet, "/api/v1/tasks/{id}/stats", service.getStats),
+		newRoute(http.MethodPost, "/api/v1/protocols/{protocol}/jobs/{name}/trigger", service.triggerProtocolJob),
+		newRoute(http.MethodPost, "/api/v1/mirrors/{provider}/candidates", service.mirrorCandidates),
 		newRoute(http.MethodGet, "/api/v1/config", service.getConfig),
 		newRoute(http.MethodPut, "/api/v1/config", service.putConfig),
 		newRoute(http.MethodPost, "/api/v1/extensions", service.installExtension),
@@ -139,7 +143,7 @@ func (s *Service) resolve(ctx *Context) *Response {
 	if response := decodeRequest(ctx.Body, &request); response != nil {
 		return response
 	}
-	result, err := s.Downloader.Resolve(request.Req, request.Opts)
+	result, err := s.Downloader.Resolve(request.Req)
 	if err != nil {
 		return newErrorResponse(err.Error())
 	}
@@ -156,7 +160,7 @@ func (s *Service) createTask(ctx *Context) *Response {
 		err    error
 	)
 	if request.Rid != "" {
-		taskID, err = s.Downloader.Create(request.Rid)
+		taskID, err = s.Downloader.CreateWithOptions(request.Rid, request.Opts)
 	} else if request.Req != nil {
 		taskID, err = s.Downloader.CreateDirect(request.Req, request.Opts)
 	} else {
@@ -188,7 +192,7 @@ func (s *Service) patchTask(ctx *Context) *Response {
 	if taskID == "" {
 		return invalidIDResponse()
 	}
-	var request restmodel.ResolveTask
+	var request restmodel.PatchTask
 	if response := decodeRequest(ctx.Body, &request); response != nil {
 		return response
 	}
@@ -294,6 +298,36 @@ func (s *Service) getStats(ctx *Context) *Response {
 	return newOKResponse(stats)
 }
 
+func (s *Service) triggerProtocolJob(ctx *Context) *Response {
+	if err := s.Downloader.TriggerProtocolJob(context.Background(), ctx.PathParam("protocol"), ctx.PathParam("name")); err != nil {
+		status := http.StatusBadRequest
+		if errors.Is(err, download.ErrUnSupportedProtocol) || errors.Is(err, download.ErrProtocolJobNotFound) {
+			status = http.StatusNotFound
+		}
+		return newStatusResponse(status, restmodel.NewErrorResult(err.Error()))
+	}
+	return newNilResponse()
+}
+
+func (s *Service) mirrorCandidates(ctx *Context) *Response {
+	var request restmodel.MirrorCandidatesReq
+	if response := decodeRequest(ctx.Body, &request); response != nil {
+		return response
+	}
+	urls, err := s.Downloader.GetMirrorCandidates(ctx.PathParam("provider"), request.URL)
+	if err != nil {
+		status := http.StatusInternalServerError
+		switch {
+		case errors.Is(err, download.ErrMirrorProviderNotFound):
+			status = http.StatusNotFound
+		case errors.Is(err, download.ErrInvalidMirrorURL):
+			status = http.StatusBadRequest
+		}
+		return newStatusResponse(status, restmodel.NewErrorResult(err.Error()))
+	}
+	return newOKResponse(&restmodel.MirrorCandidatesResp{URLs: urls})
+}
+
 func (s *Service) getConfig(_ *Context) *Response {
 	config, err := s.Downloader.GetConfig()
 	if err != nil {

pkg/api/service_test.go

@@ -0,0 +1,269 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/GopeedLab/gopeed/internal/fetcher"
+	httpProtocol "github.com/GopeedLab/gopeed/internal/protocol/http"
+	"github.com/GopeedLab/gopeed/pkg/base"
+	"github.com/GopeedLab/gopeed/pkg/download"
+	restmodel "github.com/GopeedLab/gopeed/pkg/rest/model"
+)
+
+func TestResolveThenCreateWithDownloadOptions(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Disposition", `attachment; filename="payload.txt"`)
+		w.Header().Set("Content-Length", "4")
+		_, _ = w.Write([]byte("test"))
+	}))
+	t.Cleanup(upstream.Close)
+	d := download.NewDownloader(&download.DownloaderConfig{StorageDir: t.TempDir()})
+	if err := d.Setup(); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := d.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	// Resolving must work even when the default download directory is unusable.
+	blocked := filepath.Join(t.TempDir(), "not-a-directory")
+	if err := os.WriteFile(blocked, nil, 0600); err != nil {
+		t.Fatal(err)
+	}
+	current, err := d.GetConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	config := *current
+	config.DownloadDir = blocked
+	config.MaxRunning = 0 // Inspect the created task before it starts downloading.
+	if err := d.PutConfig(&config); err != nil {
+		t.Fatal(err)
+	}
+	service, err := NewService(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolved := serviceTestRequest[*download.ResolveResult](t, service, http.MethodPost, "/api/v1/resolve", &restmodel.ResolveTask{
+		Req: &base.Request{URL: upstream.URL},
+	})
+	if resolved.ID == "" || resolved.Res.Size != 4 || resolved.Res.Files[0].Name != "payload.txt" {
+		t.Fatalf("unexpected resolved resource: %+v", resolved)
+	}
+	dir := filepath.Join(t.TempDir(), "chosen-after-resolve")
+	opts := &base.Options{Path: dir, Name: "renamed.txt", SelectFiles: []int{0}}
+	id := serviceTestRequest[string](t, service, http.MethodPost, "/api/v1/tasks", &restmodel.CreateTask{Rid: resolved.ID, Opts: opts})
+	task := serviceTestRequest[*download.Task](t, service, http.MethodGet, "/api/v1/tasks/"+id, nil)
+	if task.Meta.Opts.Path != dir || task.Meta.Opts.Name != opts.Name || !reflect.DeepEqual(task.Meta.Opts.SelectFiles, opts.SelectFiles) {
+		t.Fatalf("creation lost submitted download options: %+v", task.Meta.Opts)
+	}
+}
+
+func serviceTestRequest[T any](t *testing.T, service *Service, method, path string, body any) T {
+	t.Helper()
+	encoded, err := json.Marshal(body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	status, response := service.JSON(method, path, nil, encoded, nil)
+	var result restmodel.Result[T]
+	if err := json.Unmarshal(response, &result); err != nil {
+		t.Fatal(err)
+	}
+	if status != http.StatusOK || result.Code != restmodel.CodeOk {
+		t.Fatalf("%s %s failed: status=%d response=%s", method, path, status, response)
+	}
+	return result.Data
+}
+
+func TestFullConfigDispatch(t *testing.T) {
+	d := download.NewDownloader(&download.DownloaderConfig{StorageDir: t.TempDir(), TempDir: t.TempDir(), FetchManagers: []fetcher.FetcherManager{&httpProtocol.FetcherManager{}}})
+	if err := d.Setup(); err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+	service, err := NewService(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	response := service.Dispatch(http.MethodPut, "/api/v1/config", nil, []byte(`{"protocolConfig":{"http":{"connections":3,"useServerCtime":false}}}`), nil)
+	if response.StatusCode != http.StatusOK {
+		t.Fatalf("%+v", response)
+	}
+	status, body := service.JSON(http.MethodGet, "/api/v1/config", nil, nil, nil)
+	var result struct {
+		Data struct {
+			ProtocolConfig map[string]struct {
+				Connections int `json:"connections"`
+			} `json:"protocolConfig"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		t.Fatal(err)
+	}
+	if status != http.StatusOK || result.Data.ProtocolConfig["http"].Connections != 3 {
+		t.Fatalf("%d %s", status, body)
+	}
+	if response := service.Dispatch(http.MethodPost, "/api/v1/protocols/http/jobs/missing/trigger", nil, nil, nil); response.StatusCode != http.StatusNotFound {
+		t.Fatalf("%+v", response)
+	}
+}
+
+func TestNativePathParametersAreDecodedOnce(t *testing.T) {
+	route := newRoute(http.MethodGet, "/api/v1/tasks/{id}/status", func(c *Context) *Response { return newOKResponse(c.PathParam("id")) })
+	for _, test := range []struct{ path, want string }{
+		{"/api/v1/tasks/%E5%BC%80%E5%8F%91%E8%80%85%40name/status", "开发者@name"},
+		{"/api/v1/tasks/literal%252Fname/status", "literal%2Fname"},
+	} {
+		response := (&Service{routes: []RouteSpec{route}}).Dispatch(http.MethodGet, test.path, nil, nil, nil)
+		raw, _ := json.Marshal(response.Body)
+		var body struct {
+			Data string `json:"data"`
+		}
+		_ = json.Unmarshal(raw, &body)
+		if body.Data != test.want {
+			t.Fatalf("%s => %q", test.path, body.Data)
+		}
+	}
+}
+
+func TestMirrorCandidates(t *testing.T) {
+	d := download.NewDownloader(&download.DownloaderConfig{StorageDir: t.TempDir(), TempDir: t.TempDir(), FetchManagers: []fetcher.FetcherManager{&httpProtocol.FetcherManager{}}})
+	if err := d.Setup(); err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+	cfg, _ := d.GetConfig()
+	cfg.GithubMirror = &base.GithubMirrorConfig{Enabled: true, Mirrors: []base.GithubMirror{
+		{Type: "jsdelivr", URL: "https://cdn.example/gh"},
+		{Type: "ghProxy", URL: "https://proxy.example"},
+		{Type: "ghProxy", URL: "https://proxy.example"},
+	}}
+	if err := d.PutConfig(cfg); err != nil {
+		t.Fatal(err)
+	}
+	service, err := NewService(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, official := range []string{
+		"https://github.com/GopeedLab/gopeed/releases/download/v2.0.0/package.zip",
+		"https://raw.githubusercontent.com/owner/repo/main/trackers.txt",
+	} {
+		request, _ := json.Marshal(map[string]string{"url": official})
+		status, raw := service.JSON(http.MethodPost, "/api/v1/mirrors/github/candidates", nil, request, nil)
+		var body struct {
+			Data struct {
+				URLs []string `json:"urls"`
+			} `json:"data"`
+		}
+		if err := json.Unmarshal(raw, &body); err != nil {
+			t.Fatal(err)
+		}
+		want := 2
+		if official == "https://raw.githubusercontent.com/owner/repo/main/trackers.txt" {
+			want = 3
+		}
+		urls := body.Data.URLs
+		if status != http.StatusOK || len(urls) != want || urls[0] != official || urls[len(urls)-1] != "https://proxy.example/"+official {
+			t.Fatalf("%d %s", status, raw)
+		}
+	}
+	for _, invalid := range []string{"https://api.github.com/repos/GopeedLab/gopeed/releases?per_page=10", "", "https://example.com/x", "http://github.com/x", "https://github.com.evil.test/x", "https://[email protected]/x", "https://github.com:443/x", "https://github.com:/x", "https://github.com/x#fragment", "https://github.com/x#", "/relative", "https://github.com%2fevil.test/x"} {
+		request, _ := json.Marshal(map[string]string{"url": invalid})
+		if response := service.Dispatch(http.MethodPost, "/api/v1/mirrors/github/candidates", nil, request, nil); response.StatusCode != http.StatusBadRequest {
+			t.Fatalf("accepted %s: %+v", invalid, response)
+		}
+	}
+	cfg.GithubMirror.Enabled = false
+	if err := d.PutConfig(cfg); err != nil {
+		t.Fatal(err)
+	}
+	status, raw := service.JSON(http.MethodPost, "/api/v1/mirrors/github/candidates", nil, []byte(`{"url":"https://github.com/owner/repo"}`), nil)
+	var body struct {
+		Data struct {
+			URLs []string `json:"urls"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &body); err != nil || status != http.StatusOK || len(body.Data.URLs) != 1 || body.Data.URLs[0] != "https://github.com/owner/repo" {
+		t.Fatalf("%d %s", status, raw)
+	}
+
+	for _, provider := range []string{"unknown", "GitHub"} {
+		if response := service.Dispatch(http.MethodPost, "/api/v1/mirrors/"+provider+"/candidates", nil, []byte(`{"url":"https://github.com/owner/repo"}`), nil); response.StatusCode != http.StatusNotFound {
+			t.Fatalf("unknown provider accepted: %+v", response)
+		}
+	}
+}
+
+type apiJobState struct {
+	Runs int `json:"runs"`
+}
+type apiJobConfig struct {
+	fetcher.ConfigState[apiJobState]
+	Writable int `json:"writable"`
+}
+type apiStateJobManager struct{ httpProtocol.FetcherManager }
+
+func (*apiStateJobManager) Name() string       { return "state-api" }
+func (*apiStateJobManager) DefaultConfig() any { return &apiJobConfig{Writable: 7} }
+func (*apiStateJobManager) CronJobs(host fetcher.ProtocolHost) []fetcher.CronJob {
+	return []fetcher.CronJob{{Name: "refresh", Every: time.Hour, Timeout: time.Second, Run: func(_ context.Context, source fetcher.TriggerSource) error {
+		if source == fetcher.TriggerScheduled {
+			return fetcher.ErrJobSkipped
+		}
+		return fetcher.UpdateState[apiJobConfig, apiJobState](host, func(cfg *apiJobConfig, state *apiJobState) error { cfg.Writable = 999; state.Runs++; return nil })
+	}}}
+}
+
+func TestFullConfigAndJobTriggerShareProtectedProtocolState(t *testing.T) {
+	d := download.NewDownloader(&download.DownloaderConfig{StorageDir: t.TempDir(), TempDir: t.TempDir(), FetchManagers: []fetcher.FetcherManager{&apiStateJobManager{}}})
+	if err := d.Setup(); err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+	service, err := NewService(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	put := []byte(`{"protocolConfig":{"state-api":{"writable":9,"state":"ignore forged state"}}}`)
+	if response := service.Dispatch(http.MethodPut, "/api/v1/config", nil, put, nil); response.StatusCode != http.StatusOK {
+		t.Fatalf("%+v", response)
+	}
+	if response := service.Dispatch(http.MethodPost, "/api/v1/protocols/state-api/jobs/refresh/trigger", nil, nil, nil); response.StatusCode != http.StatusOK {
+		t.Fatalf("%+v", response)
+	}
+	status, raw := service.JSON(http.MethodGet, "/api/v1/config", nil, nil, nil)
+	var response struct {
+		Data struct {
+			ProtocolConfig map[string]apiJobConfig `json:"protocolConfig"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &response); err != nil {
+		t.Fatal(err)
+	}
+	cfg := response.Data.ProtocolConfig["state-api"]
+	if status != http.StatusOK || cfg.Writable != 9 || cfg.State.Runs != 1 {
+		t.Fatalf("%d %s", status, raw)
+	}
+	// Replaying an old full PUT must not undo the manual job's state change.
+	if response := service.Dispatch(http.MethodPut, "/api/v1/config", nil, put, nil); response.StatusCode != http.StatusOK {
+		t.Fatalf("%+v", response)
+	}
+	_, raw = service.JSON(http.MethodGet, "/api/v1/config", nil, nil, nil)
+	if err := json.Unmarshal(raw, &response); err != nil {
+		t.Fatal(err)
+	}
+	if response.Data.ProtocolConfig["state-api"].State.Runs != 1 {
+		t.Fatalf("job state overwritten: %s", raw)
+	}
+}