Skip to content

IMPLEMENTATION.md

Latest commit

 

History

History
442 lines (334 loc) · 11.6 KB

IMPLEMENTATION.md

File metadata and controls

442 lines (334 loc) · 11.6 KB

Flux Implementation Summary

Overview

Flux is a high-performance, container-native load testing tool built in Rust. This document provides a comprehensive overview of the implementation.

Architecture

Core Components

┌─────────────────────────────────────────────────────────────┐
│                         Main (main.rs)                       │
│  - Orchestration & Signal Handling                          │
│  - Configuration Loading                                     │
│  - Report Generation                                         │
└──────────────┬──────────────────────────────────────────────┘
               │
       ┌───────┴────────┬──────────────┬──────────────┐
       │                │              │              │
┌──────▼──────┐  ┌─────▼─────┐  ┌────▼─────┐  ┌────▼─────┐
│   Config    │  │  Executor  │  │ Metrics  │  │    UI    │
│  (config.rs)│  │(executor.rs)│  │(metrics.rs)│ │  (ui.rs) │
└─────────────┘  └──────┬──────┘  └──────────┘  └──────────┘
                        │
                 ┌──────▼──────┐
                 │   Client    │
                 │ (client.rs) │
                 └─────────────┘
                        │
                 ┌──────▼──────┐
                 │  Reporter   │
                 │(reporter.rs)│
                 └─────────────┘

Module Breakdown

1. Configuration Module (config.rs)

Purpose: Parse and validate YAML configuration files

Key Structures:

  • Config: Main configuration structure
  • Scenario: Multi-step scenario definition
  • MultipartPart: Multipart form data part
  • OutputConfig: Output file paths

Features:

  • YAML parsing with serde_yaml
  • Configuration validation
  • Duration parsing (s, m, h)
  • Support for simple mode and scenario mode

2. HTTP Client Module (client.rs)

Purpose: Handle HTTP requests with multipart support

Key Features:

  • Async HTTP client using reqwest
  • Multipart form-data support
  • File upload handling
  • Variable substitution in headers and body
  • Connection pooling for performance

Methods:

  • execute_simple(): Execute simple requests
  • execute_scenario(): Execute scenario steps
  • build_multipart_request(): Build multipart forms
  • substitute_variables(): Replace template variables

3. Executor Module (executor.rs)

Purpose: Execute load tests with async/sync modes

Key Features:

  • Async execution with Tokio
  • Sync execution with controlled concurrency
  • Multi-step scenario support
  • JSONPath variable extraction
  • Dependency management between steps

Execution Flow:

  1. Spawn worker tasks based on concurrency
  2. Each worker loops until duration expires
  3. Execute requests (simple or scenarios)
  4. Record metrics for each request
  5. Extract variables from responses

4. Metrics Module (metrics.rs)

Purpose: Collect and aggregate performance metrics

Key Structures:

  • RequestResult: Individual request result
  • MetricsCollector: Thread-safe metrics aggregator
  • MetricsSummary: Final statistics summary
  • LiveMetrics: Real-time metrics for UI

Metrics Collected:

  • Latency (min, max, mean, p50, p90, p95, p99)
  • Throughput (requests per second)
  • Status codes
  • Error rate and messages
  • Timestamps

Implementation:

  • Uses HDR Histogram for accurate percentile calculation
  • Thread-safe with Arc<Mutex<>>
  • Real-time and final summary generation

5. Reporter Module (reporter.rs)

Purpose: Generate JSON and HTML reports

Features:

  • JSON report with full raw data
  • HTML report with interactive charts
  • Tera template engine for HTML generation
  • Chart.js for visualizations

Report Contents:

  • Summary statistics
  • Latency distribution histogram
  • Latency over time line chart
  • Status code distribution pie chart
  • Percentiles table

6. Terminal UI Module (ui.rs)

Purpose: Display beautiful terminal output

Features:

  • Progress bar with indicatif
  • Colored output with colored crate
  • Real-time metrics display
  • JMeter-inspired layout

Display Elements:

  • Test configuration banner
  • Progress bar with live metrics
  • Final summary with statistics
  • Success/error messages

7. Main Orchestrator (main.rs)

Purpose: Coordinate all components

Flow:

  1. Initialize logging with tracing
  2. Load and validate configuration
  3. Setup graceful shutdown handler
  4. Create metrics collector
  5. Display initial banner
  6. Start executor
  7. Update UI with live metrics
  8. Generate reports
  9. Display final summary

Technical Decisions

1. Async Runtime: Tokio

Rationale:

  • Industry-standard async runtime for Rust
  • Excellent performance for I/O-bound workloads
  • Rich ecosystem of compatible libraries

2. HTTP Client: Reqwest

Rationale:

  • Built on hyper (high-performance HTTP)
  • Async/await support
  • Multipart form-data support
  • Connection pooling

3. Metrics: HDR Histogram

Rationale:

  • Accurate percentile calculation
  • Low memory overhead
  • Industry-standard for latency measurement

4. Configuration: YAML

Rationale:

  • Human-readable and writable
  • Supports complex nested structures
  • Wide adoption in DevOps tools

5. Reporting: Tera + Chart.js

Rationale:

  • Tera: Jinja2-like templating for Rust
  • Chart.js: Popular, feature-rich charting library
  • Self-contained HTML reports

Performance Characteristics

Memory Usage

  • Base: ~10-20 MB
  • Per Request: ~1-2 KB (stored in memory)
  • Optimization: Results stored in Vec, not streamed to disk during test

Throughput

  • Async Mode: 10,000+ RPS on modern hardware
  • Sync Mode: Limited by concurrency setting
  • Bottleneck: Usually network or target server

Latency Overhead

  • Minimal: <1ms overhead per request
  • Measurement: High-precision timestamps with chrono

Docker Implementation

Multi-Stage Build

Stage 1: Builder

  • Base: rust:1.75-slim
  • Compiles Rust binary
  • Caches dependencies

Stage 2: Runtime

  • Base: debian:bookworm-slim
  • Minimal runtime dependencies
  • Non-root user for security

Volume Mounts

  • /app/config.yaml: Configuration file
  • /app/data: Multipart file storage
  • /app/results: Output reports

Configuration Examples

Simple Mode

For single-endpoint testing:

target: "https://api.example.com/endpoint"
method: "POST"
headers:
  Content-Type: "application/json"
body: '{"key": "value"}'
concurrency: 20
duration: "30s"
mode: "async"

Scenario Mode

For multi-step workflows:

target: "https://api.example.com"
scenarios:
  - name: "login"
    method: "POST"
    url: "/auth/login"
    extract:
      token: "$.access_token"
  - name: "get-data"
    method: "GET"
    url: "/data"
    headers:
      Authorization: "Bearer {{ token }}"
    depends_on: "login"

Testing Strategy

Unit Tests

  • Configuration parsing
  • Variable substitution
  • Metrics calculation
  • Duration parsing

Integration Tests

  • End-to-end scenario execution
  • Report generation
  • Multipart uploads

Manual Testing

  • Docker build and run
  • Sample configurations
  • Real API endpoints

Error Handling

Strategy

  • anyhow: For general error propagation
  • thiserror: For custom error types
  • tracing: For structured logging

Graceful Degradation

  • Invalid JSONPath: Log warning, continue
  • Network errors: Record as failed request
  • Signal handling: Clean shutdown on SIGTERM

Security Considerations

Docker

  • Non-root user (UID 1000)
  • Minimal attack surface
  • No unnecessary capabilities

File Access

  • Restricted to mounted volumes
  • Validation of file paths
  • No arbitrary file system access

Future Enhancements (Phase 2)

Load Patterns

  • Ramp-up: Gradually increase load
  • Spike: Sudden load increase
  • Soak: Sustained load over time

Distributed Mode

  • Multiple nodes coordinated
  • Aggregated metrics
  • Horizontal scaling

Advanced Features

  • Prometheus metrics export
  • WebSocket support
  • gRPC support
  • Custom assertions
  • Think time between requests

Build and Deployment

Local Development

cargo build --release
cargo test
cargo clippy

Docker Build

docker build -t flux:latest .

Usage

docker run --rm \
  -v ./config.yaml:/app/config.yaml \
  -v ./data:/app/data \
  -v ./results:/app/results \
  flux:latest

Dependencies

Core Dependencies

  • tokio: Async runtime
  • reqwest: HTTP client
  • serde: Serialization
  • serde_yaml: YAML parsing
  • serde_json: JSON handling

Metrics & Reporting

  • hdrhistogram: Percentile calculation
  • tera: Template engine
  • chrono: Time handling

UI & Logging

  • indicatif: Progress bars
  • colored: Terminal colors
  • tracing: Structured logging

Utilities

  • anyhow: Error handling
  • jsonpath-rust: JSONPath extraction
  • signal-hook: Signal handling

File Structure

flux/
├── src/
│   ├── main.rs              # Entry point and orchestration
│   ├── config.rs            # YAML configuration parsing
│   ├── client.rs            # HTTP client wrapper
│   ├── executor.rs          # Load test execution engine
│   ├── metrics.rs           # Metrics collection
│   ├── reporter.rs          # Report generation
│   ├── ui.rs                # Terminal UI
│   └── templates/
│       └── report.html      # HTML report template
├── samples/
│   ├── simple-get.yaml      # GET example
│   ├── simple-post.yaml     # POST example
│   ├── multipart-upload.yaml # Upload example
│   ├── scenario-auth.yaml   # Scenario example
│   └── sample.txt           # Sample file
├── data/                    # Directory for multipart files
├── results/                 # Directory for output reports
├── target/                  # Build artifacts (gitignored)
├── Cargo.toml               # Rust dependencies
├── Cargo.lock               # Dependency lock file
├── Dockerfile               # Container image definition
├── Makefile                 # Build and development commands
├── build.sh                 # Build script
├── run-example.sh           # Run script
├── config.yaml              # Default configuration
├── .gitignore               # Git ignore rules
├── .dockerignore            # Docker ignore rules
├── README.md                # User documentation
├── IMPLEMENTATION.md        # This file (implementation details)
└── QUICKSTART.md            # Quick start guide

Conclusion

Flux is a production-ready load testing tool that combines:

  • Performance: Rust + Tokio for maximum throughput
  • Usability: YAML configuration + beautiful reports
  • Portability: Docker-only distribution
  • Flexibility: Simple mode + complex scenarios

The implementation follows Rust best practices, includes comprehensive error handling, and provides an excellent user experience through terminal UI and HTML reports.