|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +cfspeedtest is a Rust CLI tool that provides an unofficial client for speed.cloudflare.com. It performs network speed tests by downloading and uploading data to Cloudflare's servers and provides detailed statistics including latency measurements. |
| 8 | + |
| 9 | +## Common Commands |
| 10 | + |
| 11 | +### Development |
| 12 | +```bash |
| 13 | +# Build the project |
| 14 | +cargo build |
| 15 | + |
| 16 | +# Run with debug logging |
| 17 | +RUST_LOG=debug cargo run |
| 18 | + |
| 19 | +# Format code (required for CI) |
| 20 | +cargo fmt |
| 21 | + |
| 22 | +# Run linter |
| 23 | +cargo clippy --all-targets --all-features |
| 24 | + |
| 25 | +# Run tests |
| 26 | +cargo test |
| 27 | + |
| 28 | +# Run examples |
| 29 | +cargo run --example simple_speedtest |
| 30 | +cargo run --example download_test |
| 31 | +cargo run --example latency_test |
| 32 | +``` |
| 33 | + |
| 34 | +### Release |
| 35 | +```bash |
| 36 | +# Create release (requires cargo-release) |
| 37 | +cargo release patch --execute |
| 38 | + |
| 39 | +# Manual publish to crates.io |
| 40 | +cargo publish --dry-run |
| 41 | +cargo package --list |
| 42 | +cargo publish |
| 43 | +``` |
| 44 | + |
| 45 | +## Architecture |
| 46 | + |
| 47 | +### Core Modules |
| 48 | + |
| 49 | +- **`main.rs`**: Entry point that handles CLI argument parsing and HTTP client setup with IPv4/IPv6 support |
| 50 | +- **`lib.rs`**: Defines CLI options structure and output format enums |
| 51 | +- **`speedtest.rs`**: Core speed testing logic with download/upload functionality and payload size management |
| 52 | +- **`measurements.rs`**: Statistics calculation and output formatting (CSV, JSON, stdout) |
| 53 | +- **`boxplot.rs`**: ASCII boxplot rendering for verbose output |
| 54 | +- **`progress.rs`**: Progress bar implementation for test execution |
| 55 | + |
| 56 | +### Key Components |
| 57 | + |
| 58 | +**SpeedTestCLIOptions**: Main configuration struct with options for: |
| 59 | +- Test parameters (number of tests, payload sizes) |
| 60 | +- Output formats (CSV, JSON, pretty JSON, stdout) |
| 61 | +- Network settings (IPv4/IPv6 forcing) |
| 62 | +- Test types (download-only, upload-only, or both) |
| 63 | + |
| 64 | +**PayloadSize enum**: Defines test payload sizes from 100KB to 100MB with string parsing |
| 65 | + |
| 66 | +**TestType enum**: Distinguishes between Download and Upload tests |
| 67 | + |
| 68 | +**Measurement struct**: Represents individual test results with test type, payload size, and speed in Mbit/s |
| 69 | + |
| 70 | +### Test Flow |
| 71 | + |
| 72 | +1. Initialize HTTP client with optional IPv4/IPv6 binding |
| 73 | +2. Run latency tests (25 by default) |
| 74 | +3. For each payload size (100KB to max configured): |
| 75 | + - Run download tests (10 by default) |
| 76 | + - Run upload tests (10 by default) |
| 77 | + - Calculate statistics (min, max, median, quartiles) |
| 78 | + - Optionally skip larger payloads if previous tests took >5 seconds |
| 79 | +4. Output results in requested format |
| 80 | + |
| 81 | +### Output Formats |
| 82 | + |
| 83 | +- **StdOut**: Human-readable with optional verbose boxplots |
| 84 | +- **CSV**: Comma-separated values for data analysis |
| 85 | +- **JSON/JsonPretty**: Machine-readable structured data |
| 86 | + |
| 87 | +## Testing |
| 88 | + |
| 89 | +The CI pipeline runs: |
| 90 | +- `cargo fmt -- --check` (formatting check) |
| 91 | +- `cargo build --verbose` |
| 92 | +- `cargo test --verbose` |
| 93 | +- All three examples |
| 94 | +- Full CLI execution |
| 95 | +- Clippy linting with warnings as errors |
| 96 | + |
| 97 | +## Dependencies |
| 98 | + |
| 99 | +Key external dependencies: |
| 100 | +- `reqwest`: HTTP client with blocking API and rustls-tls |
| 101 | +- `clap`: CLI argument parsing with derive features |
| 102 | +- `serde`: Serialization for JSON/CSV output |
| 103 | +- `csv`: CSV file generation |
| 104 | +- `regex`: URL pattern matching |
| 105 | +- `log`/`env_logger`: Debug logging support |
0 commit comments