# guangyu-yu/cloudflarest-rust architecture

> Architecture diagram of the GitHub repository guangyu-yu/cloudflarest-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guangyu-yu/cloudflarest-rust
- Repository: https://github.com/guangyu-yu/cloudflarest-rust

## Overview

##### Project Type and Purpose
- CloudflareST-Rust is a command-line, open-source network speed-testing tool rewritten in Rust. It generates or consumes lists of IPs/CIDRs, performs ping (ICMP or TCP) and HTTP-based latency tests, then (optionally) conducts download throughput tests against Cloudflare edge servers and outputs results to console and CSV.

##### High-Level Architectural Overview
- This is a single-binary CLI application. It comprises a linear data-processing pipeline with the following stages:
- Input/Configuration
- IP/CIDR Generation or Retrieval
- Concurrency Pool & Task Dispatch
- Latency Tests (ICMP ping, TCP ping via tcping, HTTPing)
- Filter & Threshold Logic
- Download Throughput Tests
- Progress Reporting & Metrics Aggregation
- Output (console table, CSV file)

##### Main Components and Modules
- CLI Argument Parser (src/args.rs)
- Reads -ip, -ipurl, -url, -httping, -hu, thresholds, thread count, timeout, output options.
- IP Source (src/ip.rs)
- Streams IPs from CIDRs or files/URLs in real time.
- Concurrency Pool (src/pool.rs)
- Manages a thread/work queue for parallelizing tests.
- Latency Testers
- ICMP Module (src/icmp.rs) – raw ping jobs.
- TCP Module (src/tcping.rs) – TCP ping on given port.
- HTTPing Module (src/httping.rs) – HTTP GET to /cdn-cgi/trace or custom URL, with or without TLS.
- Download Module (src/download.rs)
- Executes HTTP(S) file downloads, measures MB/s.
- CSV Output (src/csv.rs)
- Streams results into CSV writer.
- Common Utilities (src/common.rs)
- Shared types, data structures, error handling.
- Progress & Reporting (src/progress.rs)
- Renders real-time progress bars, aggregates metrics.
- Orchestration (src/main.rs)
- Glues all modules, applies thresholds (tn, tl, sl, tlr), triggers download phase after ping threshold reached.

##### Interactions and Data Flow
CLI Parser → IP Source → Concurrency Pool → [Latency Testers] → Filter/Threshold → (if threshold met) → Download Module → Aggregator → Outputs
- Feedback loop: once ping count (-tn) is reached, pool is signaled to stop issuing ping tasks and switch to download tasks.

##### Architectural Patterns and Principles
- Streaming Pipeline: IPs are generated, tested, and discarded/filtered on the fly; minimal memory footprint.
- Thread Pool: Bounded concurrency to maximize throughput without oversubscription.
- Modular Separation: Each protocol/test type implemented in its own module.
- Real-Time Reporting: Progress module decouples UI updates from test logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Main["Orchestration (src/main.rs)"]:::orchestration
    CLI["CLI Argument Parser"]:::input
    IP["IP Source"]:::input
    Pool["Concurrency Pool"]:::infra
    ICMP["ICMP Module"]:::processing
    TCP["TCP Module"]:::processing
    HTTP["HTTPing Module"]:::processing
    Filter["Filter & Threshold Logic"]:::processing
    Download["Download Module"]:::processing
    Progress["Progress & Reporting"]:::util
    Common["Common Utilities"]:::util
    Console["Console Output"]:::output
    CSV["CSV Output"]:::output

    Main -->|initializes| CLI
    CLI -->|reads args| IP
    IP -->|streams IPs| Pool
    Pool -->|dispatch tasks| ICMP
    Pool -->|dispatch tasks| TCP
    Pool -->|dispatch tasks| HTTP
    ICMP -->|latency results| Filter
    TCP -->|latency results| Filter
    HTTP -->|latency results| Filter
    Filter -->|threshold met| Download
    Download -->|download metrics| Progress

    subgraph "Real-Time Metrics"
        Pool --> Progress
        ICMP --> Progress
        TCP --> Progress
        HTTP --> Progress
        Filter --> Progress
        CLI --> Progress
    end

    Progress -->|aggregated metrics| Console
    Progress -->|aggregated metrics| CSV

    Common -.-> Pool
    Common -.-> ICMP
    Common -.-> TCP
    Common -.-> HTTP
    Common -.-> Filter
    Common -.-> Download
    Common -.-> CSV
    Common -.-> Progress

    click Main "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/main.rs"
    click CLI "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/args.rs"
    click IP "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/ip.rs"
    click Pool "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/pool.rs"
    click ICMP "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/icmp.rs"
    click TCP "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/tcping.rs"
    click HTTP "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/httping.rs"
    click Download "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/download.rs"
    click CSV "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/csv.rs"
    click Common "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/common.rs"
    click Progress "https://github.com/guangyu-yu/cloudflarest-rust/blob/main/src/progress.rs"

    classDef input fill:#fdf6b2,stroke:#333,stroke-width:1px
    classDef processing fill:#b2dff9,stroke:#333,stroke-width:1px
    classDef infra fill:#f9d0b2,stroke:#333,stroke-width:1px
    classDef output fill:#b2f9b2,stroke:#333,stroke-width:1px
    classDef util fill:#e0b2f9,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ffe6e6,stroke:#333,stroke-width:1px
```
