HTTP Benchmark Tool

A powerful, flexible HTTP benchmarking tool written in Go that supports variable replacement, file-based configuration, and multiple HTTP methods. Perfect for load testing APIs with dynamic data and tracking individual request performance.

🚀 Features

• Multiple HTTP Methods: GET, POST, PUT, PATCH, DELETE support
• Variable Replacement: Dynamic [test_number] and [thread_number] substitution
• File-Based Configuration: JSON configuration files for complex scenarios
• POST Data Support: Inline data or file-based payloads
• Failure Dumping: Automatic capture of unique API failure responses
• Parallel Execution: Configurable concurrent workers
• Detailed Statistics: Response times, percentiles, success rates
• Custom Headers: Support for authentication and custom headers
• Query Parameters: Dynamic URL parameter generation
• Backward Compatible: Works with original command-line interface

📦 Installation

Option 1: Download Pre-built Binary

# Download from releases page
wget https://github.com/warkanum/go-http-bench/releases/latest/download/benchmark-linux-amd64
chmod +x benchmark-linux-amd64
mv benchmark-linux-amd64 /usr/local/bin/benchmark

Option 2: Build from Source

# Clone the repository
git clone https://github.com/warkanum/go-http-bench.git
cd http-benchmark

# Build the binary (outputs to bin/go-http-bench)
make build

# Optional: Install globally
sudo mv bin/go-http-bench /usr/local/bin/

Option 3: Install with Go

go install github.com/warkanum/go-http-bench@latest

🏃 Quick Start

Basic Usage

# Simple GET request benchmark
./benchmark -url "https://httpbin.org/get" -total 1000 -parallel 50

# POST request with JSON data
./benchmark \
    -url "https://httpbin.org/post" \
    -method POST \
    -post-data '{"message": "Hello World"}' \
    -total 500 \
    -parallel 20

Using Configuration Files

# Run with JSON configuration
./benchmark -config config.json

# Override config file settings
./benchmark -config config.json -total 2000 -parallel 100

📋 Configuration

Command Line Options

Flag	Description	Default	Example
-config	Configuration file path	-	-config config.json
-url	Target URL (required)	-	-url "https://api.example.com"
-method	HTTP method	GET	-method POST
-total	Total requests	100	-total 1000
-parallel	Parallel workers	10	-parallel 50
-timeout	Request timeout	30s	-timeout 60s
-token	Bearer token	-	-token "abc123"
-headers	Custom headers	-	-headers "Accept:application/json"
-params	Query parameters	-	-params "page=1,limit=10"
-post-data	Inline POST data	-	-post-data '{"key":"value"}'
-post-file	POST data file	-	-post-file data.json
-content-type	Content-Type header	application/json	-content-type "text/xml"
-dump-failures	Failure dump directory	-	-dump-failures "./failures"
-insecure	Skip TLS certificate verification (self-signed certs, IP hosts without SANs)	false	-insecure

JSON Configuration

Create a config.json file:

{
    "url": "https://api.example.com/users",
    "method": "POST",
    "total_requests": 1000,
    "parallel_count": 50,
    "timeout": "30s",
    "auth_token": "your-bearer-token",
    "content_type": "application/json",
    "dump_failures_dir": "./failures",
    "insecure": false,
    "headers": {
        "Accept": "application/json",
        "X-Request-ID": "bench-[test_number]-[thread_number]"
    },
    "parameters": {
        "source": "benchmark",
        "worker": "[thread_number]"
    },
    "post_data": "{\"id\": [test_number], \"worker\": [thread_number], \"timestamp\": \"2025-01-01T00:00:00Z\"}"
}

🔍 Failure Dumping

The tool automatically captures and saves unique API failure responses to help with debugging:

Features

• Automatic Detection: Any HTTP status outside 200-299 is considered a failure
• Unique Responses Only: Uses MD5 hashing to save only distinct failure types
• Detailed Reports: Each dump includes status code, response body, timestamp, and hash
• Organized Files: Named as failure_{number}_{timestamp}_status_{code}.txt

Example Usage

# Dump failures to a directory
./benchmark -url "https://api.example.com/test" -dump-failures "./debug" -total 1000

# JSON config with failure dumping
{
    "url": "https://api.example.com/endpoint",
    "dump_failures_dir": "./api_failures",
    "total_requests": 500
}

Sample Failure Dump

HTTP Benchmark Failure Report
Generated: 2025-01-30 14:30:52
Hash: a1b2c3d4e5f6...

Status Code: 404
Error Message: HTTP 404 response

Response Body:
{
  "error": "Resource not found",
  "message": "The requested endpoint does not exist"
}

🔄 Variable Replacement

The tool supports dynamic variable replacement in URLs, headers, parameters, and POST data:

• [test_number] - Replaced with the request index (0-based)
• [thread_number] - Replaced with the worker thread ID

Example Usage

./benchmark \
    -url "https://api.example.com/user/[test_number]" \
    -headers "X-Request-ID:req-[test_number]-[thread_number]" \
    -params "worker_id=[thread_number]" \
    -post-data '{"id": [test_number], "thread": [thread_number]}' \
    -total 100

Result: Each request gets unique values

• Request 0, Thread 0: user/0, req-0-0, worker_id=0, {"id": 0, "thread": 0}
• Request 5, Thread 2: user/5, req-5-2, worker_id=2, {"id": 5, "thread": 2}

📊 Example Scenarios

API Load Testing

{
    "url": "https://api.myservice.com/users",
    "method": "GET",
    "total_requests": 10000,
    "parallel_count": 100,
    "timeout": "30s",
    "auth_token": "your-api-token",
    "headers": {
        "Accept": "application/json",
        "X-Client-ID": "benchmark-client"
    },
    "parameters": {
        "page": "[test_number]",
        "limit": "50"
    }
}

User Registration Simulation

{
    "url": "https://api.myservice.com/register",
    "method": "POST",
    "total_requests": 1000,
    "parallel_count": 20,
    "timeout": "45s",
    "content_type": "application/json",
    "post_data": "{\"username\": \"user[test_number]\", \"email\": \"user[test_number]@example.com\", \"worker_id\": [thread_number]}"
}

File Upload Testing

# Create POST data file
echo '{"file_name": "upload[test_number].txt", "worker": [thread_number]}' > upload_data.json

# Run benchmark
./benchmark \
    -url "https://api.myservice.com/upload" \
    -method POST \
    -post-file upload_data.json \
    -headers "Authorization:Bearer token123" \
    -total 500

📈 Sample Output

Starting HTTP benchmark...
URL: https://api.example.com/users
Method: GET
Total requests: 1000
Parallel requests: 50
Timeout: 30s
Failure dump directory: ./failures
Custom headers: 2
  Accept: application/json
  X-Request-ID: bench-[test_number]-[thread_number]
----------------------------------------

Failure dump summary: 3 unique failure types saved to ./failures

========== BENCHMARK RESULTS ==========
Total requests:      1000
Successful requests: 995
Failed requests:     5
Success rate:        99.50%
----------------------------------------
Total time:          15.234s
Requests per second: 65.34
----------------------------------------
Response times:
  Average:           743ms
  Minimum:           156ms
  Maximum:           2.1s
  50th percentile:   682ms
  95th percentile:   1.2s
  99th percentile:   1.8s
========================================

🏗️ Advanced Examples

Multi-Stage API Testing

# Stage 1: Create users
./benchmark -config create_users.json

# Stage 2: Login users  
./benchmark -config login_users.json

# Stage 3: Fetch user data
./benchmark -config fetch_data.json

Rate Limiting Testing

# Test different concurrency levels
for workers in 10 20 50 100; do
    echo "Testing with $workers workers..."
    ./benchmark -url "https://api.example.com/data" -parallel $workers -total 1000
    sleep 5
done

🤝 Contributing

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

Development Setup

# Clone your fork
git clone https://github.com/yourusername/http-benchmark.git
cd http-benchmark

# Install dependencies
go mod tidy

# Run tests
make test

# Build (outputs to bin/go-http-bench)
make build

⚠️ Disclaimer

This tool is intended purely for benchmarking and authorized security testing. You may not use it to attack any website or service. Only test systems you own or have explicit permission to test.

The author takes no responsibility for how this tool is used. You are solely responsible for your actions and for complying with all applicable laws and terms of service.

📝 License

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

🐛 Issues and Support

• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Join Discussions

⭐ Show Your Support

Give a ⭐️ if this project helped you!