If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/GopeedLab/gopeed shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 21+ active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live GopeedLab/gopeed repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/GopeedLab/gopeed.

What it runs against: a local clone of GopeedLab/gopeed — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in GopeedLab/gopeed | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of GopeedLab/gopeed. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/GopeedLab/gopeed.git
#   cd gopeed
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of GopeedLab/gopeed and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "GopeedLab/gopeed(\\.git)?\\b" \\
  && ok "origin remote is GopeedLab/gopeed" \\
  || miss "origin remote is not GopeedLab/gopeed (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/gopeed/main.go" \\
  && ok "cmd/gopeed/main.go" \\
  || miss "missing critical file: cmd/gopeed/main.go"
test -f "cmd/web/main.go" \\
  && ok "cmd/web/main.go" \\
  || miss "missing critical file: cmd/web/main.go"
test -f "internal/controller/controller.go" \\
  && ok "internal/controller/controller.go" \\
  || miss "missing critical file: internal/controller/controller.go"
test -f "internal/fetcher/fetcher.go" \\
  && ok "internal/fetcher/fetcher.go" \\
  || miss "missing critical file: internal/fetcher/fetcher.go"
test -f "internal/protocol/http/fetcher.go" \\
  && ok "internal/protocol/http/fetcher.go" \\
  || miss "missing critical file: internal/protocol/http/fetcher.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/GopeedLab/gopeed"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gopeed is a high-performance download manager written in Go + Flutter that supports HTTP, BitTorrent, Magnet, and ED2K protocols across all platforms. It combines a Go backend (cmd/gopeed, cmd/api, cmd/host) with a Flutter-based cross-platform UI and offers extensibility through APIs and custom extensions for users to implement additional features. Monorepo structure: cmd/ contains CLI entry points (gopeed, api, host, updater) and server logic; bind/desktop and bind/mobile wrap the Go core for platform-specific webviews; pkg/ (inferred from imports) contains protocol handlers (torrent, ED2K, HTTP); ui/ (Flutter/Dart) is the cross-platform frontend; _examples/basic/main.go shows SDK usage patterns.

Power users and developers who need a modern, scriptable download manager with protocol support beyond HTTP, plus extension developers who want to add custom downloaders or integrations via the extension and API system documented at gopeed.com/docs/dev-api.

Production-ready and actively maintained: the repo shows recent Go 1.25.4 support, comprehensive CI/CD via GitHub Actions (.github/workflows/build.yml, release.yml, test.yml), and babel-test coverage via Codecov. Release strategy is automated (release-drafter.yml) and multi-language docs exist (README translations in 5 languages), indicating mature governance.

Moderate risk from torrent protocol complexity (anacrolix/torrent 1.60.1, monkeyWie/goed2k custom fork for ED2K) and tight integration between Go backend and Flutter frontend across desktop/mobile binds. Single-maintainer appearance and custom webview binding (GopeedLab/webview_go fork) suggest potential bus-factor risk; however, GitHub Actions and Docker setup show CI robustness.

Active development on version tracking (go 1.25.4 recent), CI/CD pipeline refinement (GitHub workflows), and localization (translator.yml.bak suggests i18n work). Release automation is in place; the repo maintains multiple platform-specific build targets (Windows amd64/arm64, macOS universal, inferred Linux).

git clone https://github.com/GopeedLab/gopeed.git
cd gopeed
go mod download
cd cmd/gopeed && go run main.go

For desktop/mobile builds, see bind/desktop/main.go or bind/mobile/main.go; Flutter setup required for UI development.

Daily commands: CLI mode: go run cmd/gopeed/main.go (see cmd/gopeed/flags.go for options). Desktop webview: build via bind/desktop/main.go (platform-specific webview initialization). API server: go run cmd/api/main.go. See .github/workflows/build.yml for official build matrix (Go + Flutter + native toolchains).

• cmd/gopeed/main.go — Main CLI entry point; understand how the application boots and initializes the download manager core
• cmd/web/main.go — Web server entry point for HTTP API; essential for understanding how the backend serves the UI and external clients
• internal/controller/controller.go — Core controller orchestrating download lifecycle; the heart of task management, state transitions, and protocol coordination
• internal/fetcher/fetcher.go — Fetcher abstraction delegating to protocol-specific implementations (HTTP, BitTorrent, ed2k); critical for adding new protocols
• internal/protocol/http/fetcher.go — HTTP protocol implementation; the most-used download path, containing resume logic and multi-threaded chunk handling
• internal/protocol/bt/fetcher.go — BitTorrent protocol implementation using anacrolix/torrent; mandatory for understanding P2P download support
• go.mod — Dependency manifest; review to understand external library choices and version constraints affecting maintainability

Add a new download protocol

1. Create a new protocol package under internal/protocol/PROTOCOL_NAME/ with a fetcher.go file (internal/protocol/http/fetcher.go)
2. Implement the Fetcher interface matching the signature used by HTTP/BT fetchers (Fetch, Pause, Resume methods) (internal/fetcher/fetcher.go)
3. Register the new protocol in the fetcher router by adding a URL scheme case (internal/fetcher/fetcher.go)
4. Add configuration file (e.g., internal/protocol/PROTOCOL_NAME/config.go) for protocol-specific settings (internal/protocol/http/config.go)
5. Create tests in internal/protocol/PROTOCOL_NAME/fetcher_test.go using test fixtures from internal/test/ (internal/protocol/http/fetcher_test.go)

Add a new API endpoint

1. Define a handler function in cmd/api/main.go or a separate handler file following the pattern (cmd/api/main.go)
2. Register the route with Gorilla mux using r.HandleFunc() or r.Handle() (cmd/api/main.go)
3. Call methods on the global controller instance (from internal/controller/) to perform operations (internal/controller/controller.go)
4. Return JSON responses using struct marshalling; errors are logged via internal/logger/logger.go (cmd/server.go)

Add a new CLI flag

1. Add a flag struct field to cmd/gopeed/flags.go or cmd/web/flags.go (cmd/gopeed/flags.go)
2. Parse the flag using the flag package and populate struct in the Parse() function (cmd/gopeed/flags.go)
3. Use the flag value in main() to configure the controller or server instance (cmd/gopeed/main.go)
4. Add unit tests in cmd/web/flags_test.go to validate parsing logic (cmd/web/flags_test.go)

• Golang — Enables fast concurrent downloads with goroutines, cross-platform compilation, and minimal runtime dependencies
• anacrolix/torrent — Provides mature BitTorrent protocol implementation avoiding reinventing P2P logic; enables magnet link support
• Gorilla mux + handlers — Standard Go HTTP routing library with CORS middleware support for REST API serving and WebSocket upgrades
• Flutter (UI layer, not in Go files) — Cross-platform native UI for desktop/mobile; decoupled from backend via REST API + WebSocket
• monkeyWie/goed2k — ED2K protocol support without rewriting legacy protocol stack; maintains compatibility with eMule ecosystem

• Concurrent chunk downloads with HTTP Range requests instead of streaming

  • Why: Maximizes bandwidth utilization and enables pause/resume at chunk granularity
  • Consequence: Requires tracking chunk state and merging; incompatible with servers that don't support Range headers (fallback to single stream)

• Separate CLI, Web API, and Desktop UI entry points instead of unified monolith

  • Why: Allows headless deployments, Docker containerization, and native desktop apps without imposing UI dependencies
  • Consequence: Code duplication in bootstrap logic; must maintain API compatibility across entry points

• Custom gblob protocol for peer-to-peer downloads among Gopeed clients

  • Why: Enables distributed downloads and source redundancy without relying on BitTorrent swarms
  • Consequence: Added protocol complexity; requires registry server for peer discovery (internal/protocol/gblob/registry.go)

• Goroutine-per-task model without explicit task queue

  • Why: Simple concurrency model leveraging Go's lightweight threading
  • Consequence: Potential unbounded goroutine growth if thousands of tasks created; no explicit backpressure mechanism

• Does not implement native P2P protocol discovery (BitTorrent DHT, DHT crawling) — relies on tracker servers and magnet links
• Not a streaming media player — downloads files but does not provide playback UI or codec integration
• Does not handle authentication or user login — no built-in account system (deployment-specific via reverse proxy)
• Not a cloud storage sync tool — one-time downloads only, no continuous folder monitoring
• Does not provide content blocking or filtering — leaves policy enforcement to deployment layer

Platform-specific builds required: cmd/host/dail_windows.go vs dail_other.go show conditional logic for proxy detection; bind/desktop/webview_provider_darwin.go has macOS-specific webview setup. ED2K support depends on custom monkeyWie/goed2k fork (non-standard). Extension loading expects specific directory layout (not documented in file list; check gopeed.com/docs/dev-extension). Flutter desktop/mobile setup requires native toolchains (Xcode, Visual Studio) beyond Go.

• BitTorrent Protocol & Magnet URIs — Gopeed's anacrolix/torrent integration enables magnet link parsing and distributed downloading; understanding torrent peer discovery and piece verification is essential for protocol handler debugging
• ED2K (eDonkey2000) Protocol — Gopeed's custom monkeyWie/goed2k fork implements ED2K hash-based file verification; rare in modern tools, understanding hash-tree validation is critical for contributor onboarding
• SOCKS5 Proxy (armon/go-socks5) — Gopeed supports proxy chaining via SOCKS5; cmd/host/{dail_windows,dail_other}.go show platform-specific proxy detection and tunneling, essential for network-restricted environments
• Multi-threaded HTTP Range Requests — HTTP downloads leverage range headers for parallel chunk downloads; core optimization in cmd/api/ that avoids single-connection bottlenecks
• BoltDB (bbolt) Embedded Database — go.etcd.io/bbolt provides persistent storage for download metadata, resumable session state, and history; understanding key-value schema is vital for database-layer modifications
• Cross-platform Webview Binding — Custom GopeedLab/webview_go fork (bind/desktop/{webview_provider_darwin,webview_provider_other}.go) bridges Go backend to Flutter UI; understanding platform-specific webview APIs (WKWebView on macOS, WebView2 on Windows) is crucial for desktop work
• JavaScript Extension Sandbox (goja) — github.com/dop251/goja + goja_nodejs enable custom JavaScript extensions for protocol handlers; understanding the extension execution model (sandboxing, module loading) is required for extension development

• aria2/aria2 — Alternative lightweight command-line download manager with protocol support; Gopeed differentiates with BitTorrent native support and Flutter UI
• rclone/rclone — Cloud storage and file transfer tool; shares architectural patterns (Go backend + CLI) but focuses on object storage rather than torrent/magnet protocols
• transmission/transmission — Canonical BitTorrent client; Gopeed reuses anacrolix/torrent library and follows similar protocol-agnostic design, but adds HTTP/ED2K and cross-platform UI
• flutter/flutter — UI framework used for Gopeed's cross-platform desktop/mobile frontend; essential dependency for ui/ directory development
• anacrolix/torrent — Go BitTorrent library underpinning Gopeed's magnet/torrent protocol; critical upstream dependency visible in go.mod

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for internal/fetcher/fetcher.go

The fetcher package is core to gopeed's download functionality (HTTP, BitTorrent, Magnet, ed2k support), but fetcher_test.go likely has minimal coverage given the complexity of protocol handling. This PR would add tests for error cases, protocol switching, retry logic, and edge cases in the fetcher's core download loop.

• [ ] Review internal/fetcher/fetcher.go and internal/fetcher/fetcher_test.go to identify untested code paths
• [ ] Add tests for each protocol handler (HTTP, torrent, magnet, ed2k) initialization and fallback scenarios
• [ ] Add tests for network error handling, timeout scenarios, and partial download resumption
• [ ] Add tests for concurrent request handling and resource cleanup
• [ ] Run go test -cover to verify coverage improvement and update codecov badge

Add GitHub Actions workflow for Docker image build and publish

The repo has Dockerfile and docker-compose.yml but no automated CI/CD pipeline to build and publish Docker images to Docker Hub or GitHub Container Registry. This would enable reproducible container deployments and make it easier for users to run gopeed as a service.

• [ ] Create .github/workflows/docker-build.yml workflow file
• [ ] Configure multi-platform builds (linux/amd64, linux/arm64) using docker/build-push-action
• [ ] Add conditional publishing to GHCR or Docker Hub on version tags (v*..)
• [ ] Add secrets documentation in CONTRIBUTING.md for maintainers to configure DOCKER_USERNAME and DOCKER_TOKEN
• [ ] Test the workflow by creating a tag and verifying the image builds and publishes successfully

Add unit tests for cmd/web/flags.go and cmd/gopeed/flags.go

The flags.go files parse CLI arguments for web and CLI modes but cmd/web/flags_test.go exists while cmd/gopeed likely lacks equivalent coverage. CLI flag parsing is critical for user-facing functionality and configuration validation. This PR would ensure flags are parsed correctly and validation errors are caught early.

• [ ] Review cmd/gopeed/flags.go to identify all flag definitions and validation logic
• [ ] Create cmd/gopeed/flags_test.go with tests for valid flag combinations, missing required flags, and invalid values
• [ ] Expand cmd/web/flags_test.go to cover edge cases like conflicting flags, port binding validation, and environment variable overrides
• [ ] Add tests for default flag values and environment variable precedence
• [ ] Verify all flag validation paths are exercised with go test -cover ./cmd/web ./cmd/gopeed

• Add HTTP/2 connection pooling tests in cmd/api/ to benchmark high-concurrency download scenarios; currently no benchmarks visible in file list
• Document the extension loading mechanism in _docs/ with code examples (currently only API docs exist at gopeed.com); add Dart/Kotlin/Swift examples to _examples/ matching _examples/basic/main.go
• Implement missing CONTRIBUTING translations (CONTRIBUTING_ja-JP.md, CONTRIBUTING_vi-VN.md, CONTRIBUTING_zh-CN.md, CONTRIBUTING_zh-TW.md exist but check consistency with CONTRIBUTING.md for localization gaps)

• High · Insecure Default Docker Configuration — Dockerfile, docker-compose.yml, entrypoint.sh. The Dockerfile and docker-compose.yml run the application with PUID=0 and PGID=0 by default, meaning the gopeed process runs as root inside the container. This violates the principle of least privilege and could allow privilege escalation if the application is compromised. Fix: Create a non-root user in the Dockerfile (e.g., 'gopeed' user with UID 1000) and run the application as that user. Update the entrypoint.sh to properly handle user switching only when explicitly configured, defaulting to non-root execution.
• High · Exposed HTTP Port Without Authentication by Default — docker-compose.yml, cmd/web/main.go. Port 9999 is exposed in docker-compose.yml without mandatory authentication enabled by default. The README mentions optional authentication flags (-u, -p) but they are not required, allowing unauthenticated access to the download manager API. Fix: Implement mandatory authentication by default or document security implications clearly. Add environment variables to enforce authentication requirements. Consider using network policies or reverse proxy with authentication.
• High · Potential Unsafe Deserialization with goja JavaScript Engine — internal/protocol/gblob/, go.mod. The dependency on 'github.com/dop251/goja' (JavaScript execution engine) combined with plugin/extension support (indicated by 'gblob' protocol) could allow arbitrary code execution if user-supplied scripts or plugins are not properly sandboxed. Fix: Implement strict sandboxing for JavaScript execution. Validate and sanitize all scripts before execution. Consider using seccomp or other OS-level isolation. Document security limitations of plugin system clearly.
• Medium · Use of Deprecated/Outdated SOCKS5 Library — go.mod (github.com/armon/go-socks5). The dependency 'github.com/armon/go-socks5' (last commit 2016) is outdated and may contain unpatched security vulnerabilities. No recent maintenance visible. Fix: Consider migrating to a more actively maintained SOCKS5 library or implementing SOCKS5 support using golang.org/x/net/proxy. Regularly audit dependencies for security patches.
• Medium · Potential Path Traversal in Archive Extraction — internal/protocol/, github.com/bodgit/sevenzip, github.com/mholt/archives. The codebase includes archive extraction functionality (sevenzip, archives libraries). Without proper validation, malicious archive files could extract files outside intended directories (zip slip vulnerability). Fix: Implement strict path validation during archive extraction. Ensure all extracted paths are within the target directory. Use libraries that handle zip slip protection automatically. Add tests for malicious archive files.
• Medium · Insecure DNS Cache Without Validation — internal/protocol/bt/dns_cache_resolver.go. The dns_cache_resolver in BitTorrent protocol caches DNS responses without apparent DNSSEC validation or TTL enforcement, potentially allowing DNS spoofing attacks. Fix: Implement DNSSEC validation for cached DNS records. Respect TTL values from DNS responses. Consider using a more robust DNS library with built-in security features.
• Medium · Unvalidated Torrent and Magnet Link Handling — internal/protocol/bt/fetcher.go. BitTorrent and Magnet link handlers may not properly validate metadata before downloading, potentially allowing malicious peers to serve harmful content or DHT poisoning attacks. Fix: Implement hash verification for all downloaded content. Add peer reputation checks. Validate metadata signatures where applicable. Implement rate limiting on DHT requests.
• Medium · Missing Security Headers in HTTP Responses — cmd/web/main.go, cmd/api/main.go. The web server uses gorilla/mux and gorilla/handlers without explicit security headers configuration (CSP, X-Frame-Options, X-Content-Type-Options, etc.) visible in the codebase. Fix: Add middleware to inject security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.