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/XIU2/CloudflareSpeedTest 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 — Single-maintainer risk — review before adopting

• Last commit 1w ago
• 6 active contributors
• GPL-3.0 licensed
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 XIU2/CloudflareSpeedTest repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/XIU2/CloudflareSpeedTest.

What it runs against: a local clone of XIU2/CloudflareSpeedTest — 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 XIU2/CloudflareSpeedTest | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of XIU2/CloudflareSpeedTest. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/XIU2/CloudflareSpeedTest.git
#   cd CloudflareSpeedTest
#
# 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 XIU2/CloudflareSpeedTest and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "XIU2/CloudflareSpeedTest(\\.git)?\\b" \\
  && ok "origin remote is XIU2/CloudflareSpeedTest" \\
  || miss "origin remote is not XIU2/CloudflareSpeedTest (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "task/httping.go" \\
  && ok "task/httping.go" \\
  || miss "missing critical file: task/httping.go"
test -f "task/tcping.go" \\
  && ok "task/tcping.go" \\
  || miss "missing critical file: task/tcping.go"
test -f "task/ip.go" \\
  && ok "task/ip.go" \\
  || miss "missing critical file: task/ip.go"
test -f "task/download.go" \\
  && ok "task/download.go" \\
  || miss "missing critical file: task/download.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 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
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/XIU2/CloudflareSpeedTest"
  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).

CloudflareSpeedTest is a Go-based CLI tool that benchmarks Cloudflare CDN IP addresses by measuring latency (via TCP/HTTP ping) and download speed to identify the fastest IP for a user's location. It parses IPv4 and IPv6 IP ranges from Cloudflare's public IP list, tests them in parallel, and ranks results—also supporting other CDNs and multi-IP websites with custom endpoint configuration. Simple flat structure: main.go orchestrates CLI flow; task/ package contains four core modules (ip.go parses IP ranges, httping.go/tcping.go perform latency tests, download.go measures throughput); utils/ provides helpers (color.go terminal output, csv.go result export, progress.go CLI progress bars); ip.txt and ipv6.txt hold static IP range seeds; script/ directory bundles shell/batch integration helpers for DNS and host configuration.

Chinese mainland users and international CDN consumers who need to bypass slow or high-latency Cloudflare edge IPs; DevOps engineers and sysadmins setting up optimized DNS/host entries or proxies via the bundled shell/batch scripts (cfst_hosts.sh, cfst_ddns.sh, cfst_3proxy.bat); developers wanting a portable, Go-native alternative to bash-based IP benchmarking.

Actively maintained and mature: the project has gained significant community adoption (evident from the setup/distribution effort), ships pre-compiled binaries to GitHub Releases, and includes multi-platform support (Windows .bat, Linux .sh, macOS variants). However, CI/CD pipeline and automated test coverage are not visible in the provided file structure; last commit recency is not disclosed.

Low dependency risk: only 3 direct Go dependencies (ewma, pb/v3 progress bar, fatih/color) all from well-known maintainers. Primary risk is single-maintainer (XIU2) model typical of hobby Chinese projects; Cloudflare's explicit ban on proxy use (documented in README) creates legal/ToS gray area for some use cases. No breaking-change history visible, but the tool's reliance on stable Cloudflare IP endpoints and download URLs means upstream changes could break functionality.

No specific commit/PR data provided in the repository metadata, so active development status is inferred from the multi-platform script collection and documented Cloudflare ToS discussion links (#382, #383) suggesting ongoing user support and awareness of proxy policy changes. The presence of both IPv4 and IPv6 test files and varied integration scripts (dnsmasq, dnspod, 3proxy) indicates the maintainer is responding to real-world use cases.

git clone https://github.com/XIU2/CloudflareSpeedTest.git
cd CloudflareSpeedTest
go mod download
go run main.go

Or download a pre-built binary from Releases and run directly (e.g., ./cfst on Linux/macOS, cfst.exe on Windows).

Daily commands:

go run main.go

Or build and execute: go build -o cfst && ./cfst [options]. Expected output: colored progress bar, latency & download speed results, sorted IP list written to CSV. No web server or background daemon—synchronous CLI execution.

• main.go — Entry point orchestrating IP loading, speed testing workflow, and result output—every contributor must understand the main execution flow
• task/httping.go — Core HTTP latency measurement logic; critical path for speed testing and result accuracy
• task/tcping.go — TCP connectivity testing layer; fundamental for filtering reachable IPs before HTTP testing
• task/ip.go — IP loading and parsing from ip.txt/ipv6.txt; data source handling for the entire application
• task/download.go — Download speed measurement implementation; key performance metric alongside latency
• utils/csv.go — Result serialization and export format; determines output usability for end users

• main.go (Go stdlib (flag, os, sync)) — Orchestrates workflow: load IPs → TCP filter → HTTP latency → download speed → export results
  • Failure mode: Exits with error if IP file missing or no IPs are reachable
• task/tcping.go (Go net package (Dial, DialContext)) — Validates IP reachability on port 443 with configurable timeout; filters dead nodes early
  • Failure mode: Returns connection error; IP excluded from downstream HTTP testing
• task/httping.go (net/http, VividCortex/ewma) — Measures HTTP latency with EWMA smoothing; core quality metric for IP selection
  • Failure mode: High latency or timeout causes IP to rank lower; not excluded unless fatal error
• task/download.go (net/http, io.CopyBuffer) — Measures sustained download throughput by timing file transfer; real-world performance proxy
  • Failure mode: If download fails, speed set to 0; may indicate transient network issue
• task/ip.go (bufio, strings) — Loads and deduplicates IP addresses from text files; data source for all testing
  • Failure mode: Exits if file not found; returns empty list if parsing fails (app continues with 0 IPs)
• utils/csv.go (encoding/csv, fmt) — Exports results to CSV format for consumption by shell scripts and external tools
  • Failure mode: Write error to stdout/file causes partial output; non-fatal if stderr logging available

• ip.txt / ipv6.txt → undefined — undefined

Add a new network test metric (e.g., jitter measurement)

1. Create new file task/jitter.go with a function matching the pattern of httping.go/tcping.go (taking an IP and returning results) (task/jitter.go)
2. Call the new jitter test function in main.go's test loop, passing filtered IPs and collecting results (main.go)
3. Add jitter field to CSV output in utils/csv.go's result row formatting (utils/csv.go)

Support a new CDN provider's IP list

1. Create newipv4_other.txt and ipv6_other.txt with the provider's IP ranges (ip.txt)
2. Modify task/ip.go to add a new file loading function or extend LoadIPs() to accept a custom path parameter (task/ip.go)
3. Update main.go to add a CLI flag (e.g., --provider) that switches between IP files (main.go)

Implement a new result export format (e.g., JSON)

1. Add a new export function in utils/csv.go (e.g., ExportJSON) that marshals results to JSON (utils/csv.go)
2. Add a CLI flag in main.go to select output format (--format csv|json|txt) (main.go)
3. Call the appropriate export function based on the selected format before program exit (main.go)

Add configurable timeouts and retry logic

1. Add timeout and retry parameters to task/tcping.go and task/httping.go function signatures (task/tcping.go)
2. Add corresponding CLI flags in main.go (--timeout, --retries) and pass them to each test function (main.go)
3. Implement retry loop in tcping.go and httping.go to respect the retry count on failure (task/httping.go)

• Go 1.18 — Lightweight, fast compilation, excellent goroutine concurrency for parallel IP testing—essential for scanning hundreds of IPs efficiently
• cheggaaa/pb/v3 — Real-time progress bar visualization during long-running test batches improves user experience
• VividCortex/ewma — Exponentially weighted moving average smooths HTTP latency measurements to reduce jitter-induced noise
• fatih/color — Colored terminal output provides visual hierarchy and highlights best/worst performing IPs

• Sequential TCP → HTTP → Download pipeline vs. all-in-one parallel

  • Why: Filters unreachable IPs early to avoid wasting HTTP bandwidth on dead connections
  • Consequence: Slower worst-case (all IPs unreachable), but faster typical case and conserves bandwidth

• In-memory IP deduplication vs. database

  • Why: Simple, zero-dependency approach suitable for static IP lists under 10k entries
  • Consequence: Fast startup but cannot handle dynamic IP discovery; requires manual list refresh

• Plain text CSV output vs. binary formats

  • Why: Human-readable, integrates seamlessly with shell scripts and integration tools (hosts file, dnsmasq, DNS API)
  • Consequence: Larger file size; requires manual parsing in some integrations

• HTTP HEAD for latency vs. full GET

  • Why: Reduces bandwidth and response time for pure latency measurement
  • Consequence: May miss server-side issues that only manifest in full responses

• Real-time continuous monitoring (one-shot test tool only)
• Cross-platform GUI application (CLI-only)
• Authentication or private IP ranges (Cloudflare public ranges only)
• Automatic IP list updates from Cloudflare API (manual file updates required)
• Load balancing or traffic routing (results export only, integration via scripts)

No explicit config file or environment variable injection visible; IP range files (ip.txt, ipv6.txt) must be present in working directory. Download speed test relies on hardcoded or command-line-supplied URLs (not visible in provided snippets)—ensure the URL is accessible from test location. Cloudflare ToS explicitly forbids proxy use (README note), so results may be unreliable or flagged if traffic origin appears proxied. No test suite or logging framework visible; debugging requires adding print statements or running with verbose flags (not documented in provided README snippet). Script integrations assume Unix-like shells (bash) or Windows batch environment; path separators and permission model vary by OS.

• TCP SYN handshake timing (tcping) — The latency measurement core of this tool; understanding TCP 3-way handshake timing reveals network distance without full HTTP overhead, critical for CDN edge selection
• CIDR notation and IP range expansion — task/ip.go must parse CIDR blocks (e.g., 1.2.3.0/24) and generate candidate IPs; understanding subnet masks and bit-shift operations is essential to avoid off-by-one errors
• Goroutine pooling and concurrent benchmarking — Testing hundreds of IPs sequentially is infeasible; Go's lightweight goroutines enable parallel latency/speed probes. A learner must understand WaitGroup and channel patterns to avoid race conditions on result aggregation
• Exponential weighted moving average (EWMA) — The github.com/VividCortex/ewma dependency smooths noisy bandwidth measurements over time; understanding EWMA prevents overreacting to network jitter when ranking IPs
• DNS resolution vs. IP-direct connectivity — The tool tests raw IPs (not domain names) to isolate Cloudflare edge performance; understanding the difference between DNS-mediated and direct IP probes is critical when interpreting results in production networks
• Anycasting and CDN edge selection — Cloudflare deploys identical IP ranges across geographic locations via anycast; the tool implicitly tests which physical edge server responds—a learner should understand why the same IP may have different latency from different locations
• CSV output as integration glue — The tool's results feed into downstream DNS/host/proxy scripts (cfst_hosts.sh, cfst_ddns.sh, cfst_3proxy.bat); CSV serves as the lingua franca between Go backend and shell automation—lossy but practical

• XIU2/TrackersListCollection — Same author's sibling project for optimizing BT tracker performance; shares the 'curate and rank public list' design pattern
• toyo/CloudflareWarp — Alternative Go-based Cloudflare IP optimizer focusing on Warp endpoint selection; similar goal, different approach
• badO1o/CloudflareSpeedTest — Different fork/variant of Cloudflare IP benchmarking in Go; useful for comparing implementation strategies
• P3TERX/Actions-Cloudflare-WARP — GitHub Actions automation for Cloudflare WARP integration; complements CloudflareSpeedTest by automating deployment of fastest IPs
• missuo/CloudflareSpeedTestDeploy — Deploys CloudflareSpeedTest results to DNS or host configuration automatically; shows downstream integration patterns

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 unit tests for task package modules (tcping.go, httping.go, download.go)

The repo has core networking functionality (TCP ping, HTTP ping, download speed testing) in task/ directory but no test files. These are critical paths that determine IP selection quality. Adding tests would catch regressions, validate timeout handling, and ensure consistency across different network conditions. This is especially important since the tool is used to benchmark CDN performance.

• [ ] Create task/tcping_test.go with tests for TCP connection establishment and timeout scenarios
• [ ] Create task/httping_test.go with tests for HTTP latency measurement and edge cases (redirects, timeouts)
• [ ] Create task/download_test.go with tests for speed calculation accuracy
• [ ] Add mock server setup in test files to simulate Cloudflare responses
• [ ] Update go.mod if a testing utility library (like testify) is needed

Add GitHub Actions CI workflow for multi-platform binary builds and releases

The repo targets multiple platforms (Windows, Linux, macOS) as evidenced by script/ files (cfst_hosts.bat, cfst_hosts.sh, cfst_hosts_mac.sh) and the go.mod specifies Go 1.18+. There's no CI workflow file in .github/workflows/. Automated cross-platform builds would ensure binaries work correctly on each OS, catch platform-specific issues early, and streamline releases.

• [ ] Create .github/workflows/build.yml to build binaries for windows/386, windows/amd64, linux/amd64, linux/arm64, darwin/amd64, darwin/arm64
• [ ] Add gzip compression step for Linux/macOS binaries and zip for Windows
• [ ] Configure workflow to trigger on push to main branch and on release tag creation
• [ ] Add artifact upload step to make binaries available for download
• [ ] Document build matrix in workflow comments for maintainability

Create utils/ip_validator.go and add validation tests for ip.txt and ipv6.txt parsing

The repo has ip.txt and ipv6.txt files (IP lists to test) and task/ip.go (IP handling logic), but there's no dedicated validation utility. As the IP lists grow and contributors submit PRs to update them, validation ensures format consistency, detects duplicates, and catches invalid CIDR ranges. This prevents silent failures during testing where malformed IPs would just be skipped.

• [ ] Create utils/ip_validator.go with functions: ValidateIPv4Format(), ValidateIPv6Format(), ValidateCIDRRange(), DetectDuplicates()
• [ ] Create utils/ip_validator_test.go with tests for edge cases (invalid CIDR, malformed addresses, broadcast IPs)
• [ ] Add validation call to task/ip.go when loading ip.txt and ipv6.txt files to warn users of malformed entries
• [ ] Update README.md with a section on IP list format requirements for contributors

• Add unit tests for task/ip.go CIDR parsing: No test files visible in the repo; parsing malformed CIDR ranges (e.g., invalid subnet masks) could silently fail. Write tests for edge cases: /0, /32, IPv6 /128, overlapping ranges.
• Document download URL configuration for non-Cloudflare CDNs: README mentions 'support for other CDN' but no concrete example or config schema shown; add a sample config file and update main.go to load custom download URLs, with docs/config_example.md.
• Add CI/CD workflow (GitHub Actions) to build and test on push: .github/ISSUE_TEMPLATE exists but no .github/workflows/ visible; add matrix build for Linux/Windows/macOS, run basic smoke tests (parse ip.txt, execute with --help), and publish binaries to Releases automatically.

The CloudflareSpeedTest project is a relatively simple CLI tool with a low attack surface. Primary security concerns are: (1) use of outdated Go version 1.18 without current security patches, (2) lack of dependency vulnerability scanning practices, and (3) absence of security documentation and disclosure guidelines. The codebase itself appears clean with no obvious injection vulnerabilities, hardcoded secrets, or database operations. The tool performs network I/O operations (TCP/HTTP pings) which should include proper timeout and error handling. Overall security posture is moderate with room for improvement in dependency management and security practices documentation.

• Medium · Outdated Go Version — go.mod. The project specifies Go 1.18 in go.mod, which is significantly outdated. Go 1.18 was released in March 2022 and is no longer receiving security updates. Current stable versions are 1.22+, which include important security patches and performance improvements. Fix: Update go.mod to specify a minimum Go version of 1.21 or higher. Test the codebase against the latest stable Go version and update CI/CD pipelines accordingly.
• Medium · Outdated Dependencies with Potential Security Issues — go.mod, go.sum. Several dependencies are significantly outdated: golang.org/x/sys v0.30.0 (from 2024) is reasonably current, but other dependencies like github.com/cheggaaa/pb/v3 v3.1.7 and github.com/fatih/color v1.18.0 should be reviewed for known vulnerabilities. No go.sum verification or dependency audit information is visible. Fix: Run 'go list -json -m all | nancy sleuth' or 'govulncheck ./...' to scan for known vulnerabilities. Update dependencies to their latest versions and maintain a regular dependency audit schedule.
• Low · Missing Security Configuration Documentation — Repository root. No visible security policy, SECURITY.md, or vulnerability disclosure guidelines in the repository. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file at the repository root documenting responsible vulnerability disclosure process and security contact information.
• Low · Potential Input Validation Issues in IP Testing Tool — task/ip.go, task/tcping.go, task/httping.go, ip.txt, ipv6.txt. The tool processes IP addresses from ip.txt and ipv6.txt files and performs network testing. While the primary risk is low for a CLI tool, there could be potential DNS/network-based injection if IPs are not properly validated before use in network operations. Fix: Implement strict IP address validation using net.ParseIP() before any network operations. Ensure error handling for malformed IPs and validate URL components if user input is accepted.
• Low · Shell Script Security in Distribution Scripts — script/cfst_hosts.sh, script/cfst_hosts_mac.sh, script/cfst_dnsmasq.sh, script/cfst_dnspod.sh, script/cfst_hosts.bat, script/cfst_ddns.bat, script/cfst_ddns.sh. Several shell scripts are present in the script/ directory (.sh and .bat files) that perform system modifications (hosts files, DDNS, dnsmasq configs). These scripts could pose risks if executed without proper verification. Fix: Add script integrity verification (checksums/signatures), require explicit user confirmation before system modifications, and document security implications in script headers. Consider distributing scripts with digital signatures.

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.