🦀 RustyLoad

---

📖 Overview

RustyLoad is a command-line load testing tool designed to stress-test web servers, APIs, and TCP-based services like key-value databases. Built with Rust's async runtime (Tokio), it can send thousands of concurrent requests while efficiently managing system resources.

Whether you're testing your local development server, benchmarking a production API, or load testing your Redis-like FlashKV database, RustyLoad provides detailed latency statistics including percentiles (p50, p95, p99) to help you understand your service's performance characteristics.

Supported Protocols

• HTTP/HTTPS - REST APIs, web servers, microservices
• FlashKV (TCP) - Redis-like in-memory key-value databases

██████╗ ██╗   ██╗███████╗████████╗██╗   ██╗██╗      ██████╗  █████╗ ██████╗ 
██╔══██╗██║   ██║██╔════╝╚══██╔══╝╚██╗ ██╔╝██║     ██╔═══██╗██╔══██╗██╔══██╗
██████╔╝██║   ██║███████╗   ██║    ╚████╔╝ ██║     ██║   ██║███████║██║  ██║
██╔══██╗██║   ██║╚════██║   ██║     ╚██╔╝  ██║     ██║   ██║██╔══██║██║  ██║
██║  ██║╚██████╔╝███████║   ██║      ██║   ███████╗╚██████╔╝██║  ██║██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝      ╚═╝   ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═════╝ 
                                                                            

  ⚡ Blazingly Fast Load Testing Tool ⚡
     HTTP | FlashKV (TCP Key-Value)

---

✨ Features

Core Features

• 🚀 High Performance - Built with Rust and Tokio for maximum throughput
• ⚡ Concurrent Requests - Control concurrency level with semaphore-based limiting
• 📊 Detailed Statistics - Min, max, average latency plus p50, p95, p99 percentiles
• 🎯 Interactive Mode - Guided TUI for easy configuration (no need to memorize flags!)
• 🎨 Beautiful TUI - Colorful terminal output with progress bar
• 📈 Real-time Progress - Live progress bar showing request completion
• 🛡️ Error Handling - Graceful handling of failed requests with detailed reporting
• ⏱️ Configurable Timeout - Set request timeout in seconds

HTTP Features

• 🔧 HTTP Methods - Support for GET, POST, PUT, DELETE, PATCH, and HEAD
• 📝 Custom Headers - Add any custom headers including Authorization
• 📦 Request Body - Send JSON or any payload with POST/PUT/PATCH requests

FlashKV (TCP Key-Value) Features

• 🗄️ Redis-like Commands - PING, GET, SET, DEL, INCR, DECR, and more
• 🔑 Random Keys - Distribute load across key space with configurable random keys
• 📋 Mixed Workloads - Combine multiple commands (e.g., GET + SET)
• 🎲 Custom Commands - Send any raw TCP command to your database

---

📦 Installation

Option 1: Download Pre-built Binary (Easiest)

Download the latest release for your platform from the Releases page.

Linux

# Download the latest release
curl -LO https://github.com/arino08/rustyload/releases/latest/download/rustyload-linux-x86_64.tar.gz

# Extract the binary
tar xzf rustyload-linux-x86_64.tar.gz

# Move to a directory in your PATH
sudo mv rustyload /usr/local/bin/

# Verify installation
rustyload --version

macOS

# For Intel Macs
curl -LO https://github.com/arino08/rustyload/releases/latest/download/rustyload-macos-x86_64.tar.gz
tar xzf rustyload-macos-x86_64.tar.gz

# For Apple Silicon (M1/M2/M3)
curl -LO https://github.com/arino08/rustyload/releases/latest/download/rustyload-macos-aarch64.tar.gz
tar xzf rustyload-macos-aarch64.tar.gz

# Move to PATH
sudo mv rustyload /usr/local/bin/

# Verify installation
rustyload --version

Windows

1. Download rustyload-windows-x86_64.zip from the Releases page
2. Extract the .zip file
3. Move rustyload.exe to a directory in your PATH (e.g., C:\Windows\System32\ or create a custom directory)
4. Or run directly: .\rustyload.exe --version

Option 2: Install via Cargo

If you have Rust installed:

# Install directly from GitHub
cargo install --git https://github.com/arino08/rustyload

# Or clone and install locally
git clone https://github.com/arino08/rustyload
cd rustyload
cargo install --path .

The binary will be installed to ~/.cargo/bin/rustyload.

Option 3: Build from Source

# Clone the repository
git clone https://github.com/arino08/rustyload
cd rustyload

# Build in release mode (optimized)
cargo build --release

# The binary will be at ./target/release/rustyload
./target/release/rustyload --version

# Optionally, copy to your PATH
sudo cp target/release/rustyload /usr/local/bin/

---

🚀 Usage

RustyLoad offers two modes: Interactive Mode (beginner-friendly) and Quick Mode (for power users).

Interactive Mode (Recommended for Beginners)

Simply run without arguments, or use the -i flag:

# Launches interactive configuration wizard
rustyload

# Or explicitly request interactive mode
rustyload -i

The interactive mode will guide you through:

1. ✅ Select protocol (HTTP or FlashKV)
2. ✅ Target URL or host:port
3. ✅ Protocol-specific options (HTTP method or KV commands)
4. ✅ Number of requests
5. ✅ Concurrency level
6. ✅ Timeout settings
7. ✅ Additional options (headers, body, random keys)

HTTP Interactive Example

🚀 Interactive Mode - Let's configure your load test!
──────────────────────────────────────────────────

? Select protocol: HTTP/HTTPS (Web APIs, REST endpoints)
? Target URL: https://api.example.com/health
? HTTP Method: GET
? Number of requests: 100
? Concurrent requests: 10
? Timeout (seconds): 30
? Additional options: Skip (use defaults)

──────────────────────────────────────────────────
✅ Configuration complete!

FlashKV Interactive Example

🚀 Interactive Mode - Let's configure your load test!
──────────────────────────────────────────────────

? Select protocol: FlashKV (TCP key-value database)
🗄️  FlashKV Load Test Configuration

? FlashKV server host: localhost
? FlashKV server port: 6379
? Select workload type: GET + SET mixed workload
? Base key: testkey
? Value for SET operations: testvalue
? Use random keys? Yes
? Key prefix: user
? Key range (0 to N-1): 10000
? Number of requests: 1000
? Concurrent connections: 50
? Timeout (seconds): 10

──────────────────────────────────────────────────
✅ Configuration complete!

Quick Mode (For Power Users)

If you know what you want, use CLI arguments:

HTTP Examples

# Basic HTTP usage with defaults (100 requests, 10 concurrent)
rustyload -u https://httpbin.org/get

# Custom requests and concurrency
rustyload -u https://api.example.com/health -n 500 -c 50

# Skip confirmation prompt with -y
rustyload -u https://httpbin.org/get -n 100 -c 10 -y

FlashKV Examples

# Basic FlashKV PING test
rustyload -p flashkv -u localhost:6379 -n 1000 -c 50

# FlashKV with GET command
rustyload -p flashkv -u localhost:6379 --command "GET mykey" -n 1000 -c 50

# FlashKV with SET command
rustyload -p flashkv -u localhost:6379 --command "SET mykey myvalue" -n 1000 -c 50 -y

Command Line Options

Option	Short	Description	Default
--url	-u	Target URL (HTTP) or host:port (FlashKV)	-
--protocol	-p	Protocol: http, flashkv	http
--requests	-n	Total number of requests to send	100
--concurrency	-c	Number of concurrent requests	10
--command	-	FlashKV command (e.g., "GET key", "SET key value")	PING
--interactive	-i	Run in interactive mode	auto
--yes	-y	Skip confirmation prompt	false
--help	-h	Show help message	-
--version	-V	Show version	-

Note: If you don't provide a URL, RustyLoad automatically enters interactive mode!

Supported FlashKV Commands

Command	Description	Example
PING	Check server connectivity	PING
GET	Retrieve a value	GET mykey
SET	Store a value	SET mykey myvalue
DEL	Delete a key	DEL mykey
INCR	Increment a numeric value	INCR counter
DECR	Decrement a numeric value	DECR counter
EXISTS	Check if key exists	EXISTS mykey
EXPIRE	Set key expiration	EXPIRE mykey 3600
TTL	Get time to live	TTL mykey
KEYS	List keys matching pattern	KEYS user:*
LPUSH	Push to list	LPUSH mylist value
LPOP	Pop from list	LPOP mylist

Example Output

┌─────────────────────────────────────────────────┐
│ 📋 Configuration Summary                         │
├─────────────────────────────────────────────────┤
│ URL:               https://httpbin.org/post     │
│ Method:            POST                         │
│ Requests:          100                          │
│ Concurrency:       10                           │
│ Timeout:           30s                          │
├─────────────────────────────────────────────────┤
│ Headers:                                        │
│   Content-Type: application/json                │
│   Authorization: Bearer t...                    │
├─────────────────────────────────────────────────┤
│ Body:              {"name":"test"}              │
└─────────────────────────────────────────────────┘

? Start load test? Yes

🚀 Starting load test...

  [00:00:12] [████████████████████████████████████████] 100/100 (100%) Complete!

┌─────────────────────────────────────────────────┐
│ 📊 Results                                       │
├─────────────────────────────────────────────────┤
│ Total Requests:      100                        │
│ Successful:          100 (100.0%)               │
│ Failed:              0                          │
├─────────────────────────────────────────────────┤
│ ⏱️  Latency (ms)                                │
├─────────────────────────────────────────────────┤
│ Min:                 145 ms                     │
│ Max:                 892 ms                     │
│ Average:             234.56 ms                  │
├─────────────────────────────────────────────────┤
│ 📈 Percentiles                                   │
├─────────────────────────────────────────────────┤
│ p50 (median):        210 ms                     │
│ p95:                 445 ms                     │
│ p99:                 823 ms                     │
├─────────────────────────────────────────────────┤
│ 🚀 Throughput                                    │
├─────────────────────────────────────────────────┤
│ Requests/sec:        8.23                       │
│ Total time:          12156 ms                   │
└─────────────────────────────────────────────────┘

✅ Load test completed successfully!

---

🔍 How It Works

Understanding Percentiles

Percentiles help you understand the distribution of response times:

Percentile	Meaning
p50 (Median)	50% of requests were faster than this value
p95	95% of requests were faster - shows "almost worst case"
p99	99% of requests were faster - catches outliers

Why percentiles matter: If your average latency is 100ms but p99 is 2000ms, it means 1% of your users experience 20x slower response times!

Concurrency Control

RustyLoad uses a semaphore to control concurrency:

Concurrency = 3:

Request 1: ████████░░░░░░░░  (running)
Request 2: ░░██████████░░░░  (running)
Request 3: ░░░░████████████  (running)
Request 4: ░░░░░░░░░░░░████  (waiting, then runs when slot opens)

This prevents overwhelming both your system and the target server.

Request Flow

1. Configure - Interactive prompts or CLI args
2. Build HTTP client - Configure timeout, user agent
3. Create semaphore - Limit concurrent requests
4. Spawn async tasks - One task per request
5. Collect results - Gather timing and status from each request
6. Calculate statistics - Compute percentiles, averages, throughput
7. Display results - Pretty-print in terminal

---

🏗️ Architecture

rustyload/
├── .github/
│   └── workflows/
│       ├── ci.yml              # GitHub Actions CI/CD
│       └── release.yml         # Automated release builds
├── docs/
│   └── TECHNICAL_GUIDE.md      # Detailed technical documentation
├── src/
│   ├── main.rs                 # CLI parsing, orchestration
│   ├── client.rs               # HTTP client, load testing, statistics
│   └── interactive.rs          # Interactive TUI prompts
├── Cargo.toml                  # Dependencies and metadata
├── README.md                   # This file
└── LICENSE                     # MIT License

Module Breakdown

main.rs

• CLI Parsing: Uses clap for argument parsing
• Mode Selection: Chooses between interactive and quick mode
• Results Display: Shows statistics in a beautiful table

client.rs

• HTTP Client: Built on reqwest with custom configuration
• Concurrency: Tokio-based async with semaphore limiting
• Statistics: Percentile calculation with linear interpolation
• Progress: Real-time progress bar using indicatif
• Configuration: Builder pattern for flexible test setup

interactive.rs

• Guided Setup: Step-by-step configuration wizard
• Input Validation: Validates URLs, numbers, headers
• Smart Defaults: Sensible defaults for quick setup
• User-Friendly: Clear prompts with helpful descriptions

Key Dependencies

Crate	Purpose
tokio	Async runtime for concurrent execution
reqwest	HTTP client for making requests
clap	Command-line argument parsing
dialoguer	Interactive terminal prompts
indicatif	Progress bar and spinners
colored	Terminal colors and styling
anyhow	Ergonomic error handling

---

📊 Performance Characteristics

RustyLoad is designed to be efficient:

• Memory: Uses Arc for shared state, avoiding unnecessary clones
• CPU: Async I/O means threads aren't blocked waiting for responses
• Network: Reuses HTTP client connections where possible

Benchmarks

Tested on a local server (your results may vary):

Requests	Concurrency	Time	Req/sec
1,000	10	2.3s	434
1,000	50	0.8s	1,250
10,000	100	5.2s	1,923

---

🧪 Testing

RustyLoad includes a comprehensive test suite:

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run a specific test
cargo test test_percentile

Test Coverage

• Unit tests for percentile calculations
• Unit tests for statistics aggregation
• Unit tests for HTTP method parsing
• Unit tests for configuration builder

---

🛠️ Development

Running Locally

# Debug build (faster compile, slower runtime)
cargo build

# Run directly
cargo run -- -u https://httpbin.org/get -n 10

# Release build (slower compile, faster runtime)
cargo build --release

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Check for issues without building
cargo check

---

🗺️ Roadmap

Future enhancements planned:

• Output Formats: JSON, CSV export for CI/CD integration
• HTML Reports: Generate visual reports
• Request from File: Load URLs/requests from a file
• Distributed Testing: Run from multiple machines
• Latency Histogram: Visual ASCII distribution of response times
• Rate Limiting: Requests per second limiting
• Duration Mode: Run for X seconds instead of X requests
• Cookies: Cookie jar support for session testing
• HTTP/2: HTTP/2 protocol support
• Saved Profiles: Save and load test configurations

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Run cargo fmt before committing
• Ensure cargo clippy passes without warnings
• Add tests for new functionality
• Update README for user-facing changes

Areas for Contribution

• 🐛 Bug fixes
• 📝 Documentation improvements
• ✨ New features from the roadmap
• 🧪 Test coverage
• 🎨 TUI improvements

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Tokio - Async runtime for Rust
• reqwest - HTTP client
• clap - Command line argument parser
• dialoguer - Interactive prompts
• indicatif - Progress bars
• Inspired by tools like wrk, hey, and bombardier

---