h3-stress

# Table of Contents

· # What is H3-Stress? · # Quick Start · # Installation · # Features · # Configuration Guide · # API Reference · # Usage Examples · # CLI Mode · # Client Usage · # Implementation Guides · ## Java Implementation · ## Kotlin Implementation · ## Godot Implementation · ## Express Implementation · ## HTML Implementation · ## Gradle Implementation · # Performance Benchmarks · # FAQ · # Troubleshooting · # Contributing · # License

What is H3-Stress?

H3-Stress is a professional-grade HTTP/3 load testing tool with multi-stream spamming, datagram stress testing, and connection migration simulation. It leverages QUIC protocol features to test server limits under extreme conditions.

Key Capabilities

Feature Description Multi-Stream Spamming Test how server handles thousands of streams inside single QUIC connection Datagram Stress-Test Continuous UDP datagram flooding to find packet loss thresholds Connection Migration Test Simulate network switching (WiFi to 4G) to test connection ID stability Real-time Analytics Live p99, p95 latency, throughput, and packet loss display

Why H3-Stress?

· Multi-core Support - Uses Node.js cluster with child processes for all CPU cores · Real-time Dashboard - Interactive terminal UI with live graphs · Packet Loss Simulation - Built-in network impairment simulation · UDP Buffer Optimization - Automatic detection and suggestions for sysctl tuning

Quick Start

CLI Usage

h3-stress --url https://localhost:4433 --concurrency 1000 --duration 30s

Programmatic Usage

import { H3Tester } from "h3-stress";

const tester = new H3Tester({
  target: "https://your-h3-server.com",
  concurrency: 500,
  duration: 60,
  streamsPerConnection: 50,
  datagramRate: 5000,
  enableMigration: true,
  workerCount: 4
});

const report = await tester.run();
console.log(report);

Installation

From NPM

npm install -g h3-stress

From Source

git clone https://github.com/Dimzxzzx07/H3-Stress.git
cd H3-Stress
npm install
npm run build

Requirements

Requirement Minimum Recommended Node.js 18.0.0 20.0.0+ RAM 512 MB 2 GB+ CPU 2 cores 4+ cores OS Linux/macOS/WSL Ubuntu 22.04+

Features

Multi-Stream Spamming

H3-Stress can create thousands of bidirectional streams inside a single QUIC connection, testing how well your server handles concurrent stream multiplexing.

h3-stress --url https://server.com --streams-per-connection 100 --concurrency 10

Datagram Stress-Test

Unique feature - Continuously sends UDP datagrams to find exactly when your server starts dropping packets.

h3-stress --url https://server.com --datagram-rate 50000 --duration 60s

Connection Migration Test

Simulates network handover (WiFi -> 4G -> WiFi) by changing local ports, testing if your server maintains connection state.

h3-stress --url https://server.com --enable-migration --concurrency 100

Real-time Analytics

Live terminal dashboard showing:

· Latency percentiles (p50, p95, p99, p999) · Throughput (requests/sec, Mbps) · Packet loss percentage · CPU/Memory usage of tester machine

System Monitoring

Automatically monitors your testing machine's resources so you know if the server is slow or your tester is maxed out.

h3-stress --url https://server.com --workers 8

Configuration Guide

Complete Configuration Options

Option Type Default Description url string required Target HTTPS URL concurrency number 100 Concurrent connections duration string "30s" Test duration (s/m/h) streamsPerConnection number 10 Streams per QUIC connection datagramRate number 1000 Datagrams per second enableMigration boolean false Enable connection migration workers number 4 Number of CPU worker processes preset string null Load preset file

Preset Configurations

Aggressive Preset

{
  "concurrency": 5000,
  "streamsPerConnection": 100,
  "datagramRate": 10000,
  "enableMigration": true,
  "workers": 8,
  "duration": 60
}

Balanced Preset

{
  "concurrency": 500,
  "streamsPerConnection": 20,
  "datagramRate": 1000,
  "enableMigration": false,
  "workers": 4,
  "duration": 30
}

Datagram-Heavy Preset

{
  "concurrency": 100,
  "streamsPerConnection": 5,
  "datagramRate": 50000,
  "enableMigration": true,
  "workers": 8,
  "duration": 45
}

API Reference

H3Tester Class

class H3Tester extends EventEmitter {
  constructor(config: TestConfig);
  run(): Promise<TestReport>;
  stop(): void;
  
  // Events
  on("stats", (stats: Stats) => void): this;
}

TestConfig Interface

interface TestConfig {
  target: string;           // Target URL (https://)
  concurrency: number;      // Concurrent connections
  duration: number;         // Test duration in seconds
  streamsPerConnection: number;  // Streams per connection
  datagramRate: number;     // Datagrams per second
  enableMigration: boolean; // Connection migration
  workerCount: number;      // CPU worker count
}

TestReport Interface

interface TestReport {
  duration: number;
  totalRequests: number;
  totalDatagrams: number;
  successRate: number;
  latency: {
    p50: number;
    p95: number;
    p99: number;
    p999: number;
    avg: number;
    min: number;
    max: number;
  };
  throughput: {
    requestsPerSecond: number;
    megabitsPerSecond: number;
  };
  packetLoss: number;
  connectionMigrations: number;
  systemPeak: {
    cpu: number;
    memory: number;
    udpBuffer: number;
  };
}

Usage Examples

Example 1: Basic Load Test

import { H3Tester } from "h3-stress";

const tester = new H3Tester({
  target: "https://cloudflare-quic.com",
  concurrency: 100,
  duration: 30,
  streamsPerConnection: 10,
  datagramRate: 1000,
  enableMigration: false,
  workerCount: 4
});

const report = await tester.run();
console.log(`p99 Latency: ${report.latency.p99}ms`);
console.log(`Throughput: ${report.throughput.requestsPerSecond} req/s`);

Example 2: Migration Stress Test

const tester = new H3Tester({
  target: "https://your-server.com",
  concurrency: 500,
  duration: 60,
  streamsPerConnection: 50,
  datagramRate: 5000,
  enableMigration: true,
  workerCount: 8
});

tester.on("stats", (stats) => {
  console.log(`Migrations: ${stats.connectionMigrations}`);
});

const report = await tester.run();

Example 3: Datagram Flood Test

const tester = new H3Tester({
  target: "https://your-server.com",
  concurrency: 50,
  duration: 30,
  streamsPerConnection: 1,
  datagramRate: 50000,
  enableMigration: false,
  workerCount: 4
});

const report = await tester.run();
console.log(`Packet loss: ${(report.packetLoss * 100).toFixed(2)}%`);

Example 4: Multi-Stage Test

const stages = [
  { concurrency: 100, duration: 30, name: "Warmup" },
  { concurrency: 500, duration: 60, name: "Ramp" },
  { concurrency: 1000, duration: 120, name: "Peak" }
];

for (const stage of stages) {
  console.log(`Stage: ${stage.name}`);
  
  const tester = new H3Tester({
    target: "https://your-server.com",
    concurrency: stage.concurrency,
    duration: stage.duration,
    streamsPerConnection: 20,
    datagramRate: 2000,
    enableMigration: true,
    workerCount: 8
  });
  
  const report = await tester.run();
  console.log(`Result: ${report.latency.p99}ms`);
  await new Promise(r => setTimeout(r, 5000));
}

CLI Mode

Commands

Basic Test

h3-stress --url https://localhost:4433 --concurrency 1000 --duration 30s

With Migration

h3-stress --url https://server.com --enable-migration --concurrency 500

Using Preset

h3-stress --url https://server.com --preset aggressive

Custom Datagram Rate

h3-stress --url https://server.com --datagram-rate 50000 --streams-per-connection 5

Multi-core Testing

h3-stress --url https://server.com --workers 8 --concurrency 5000

CLI Options

Option Alias Description --url -u Target URL (required) --concurrency -c Concurrent connections --duration -d Test duration (30s, 1m, 2h) --streams-per-connection -s Streams per connection --datagram-rate -dr Datagrams per second --enable-migration -m Enable connection migration --workers -w Number of worker processes --preset -p Load preset (aggressive/balanced/datagram-heavy)

Output Example

$ h3-stress --url https://cloudflare-quic.com --concurrency 100 --duration 10s

[INFO] Starting load test...
[INFO] Target: https://cloudflare-quic.com
[INFO] Concurrency: 100
[INFO] Duration: 10s

[STATS] Latency p99: 45.2ms | Throughput: 1250 req/s
[STATS] Latency p99: 42.1ms | Throughput: 1320 req/s
[STATS] Latency p99: 44.8ms | Throughput: 1280 req/s

{
  "duration": 10,
  "totalRequests": 12850,
  "totalDatagrams": 50000,
  "successRate": 0.998,
  "latency": {
    "p50": 28.3,
    "p95": 38.7,
    "p99": 45.2,
    "p999": 67.8
  },
  "throughput": {
    "requestsPerSecond": 1285,
    "megabitsPerSecond": 42.5
  }
}

Implementation Guides

Java Implementation

Maven Dependency

<dependency>
    <groupId>org.eclipse.jetty.http3</groupId>
    <artifactId>jetty-http3-client</artifactId>
    <version>12.0.0</version>
</dependency>

Java Client Code

import org.eclipse.jetty.http3.client.HTTP3Client;
import org.eclipse.jetty.http3.client.transport.HttpClientTransportOverHTTP3;
import org.eclipse.jetty.client.HttpClient;
import org.eclipse.jetty.client.api.ContentResponse;
import java.net.URI;

public class H3Client {
    public static void main(String[] args) throws Exception {
        HTTP3Client h3Client = new HTTP3Client();
        HttpClientTransportOverHTTP3 transport = new HttpClientTransportOverHTTP3(h3Client);
        HttpClient httpClient = new HttpClient(transport);
        
        httpClient.start();
        
        URI uri = URI.create("https://localhost:4433");
        ContentResponse response = httpClient.newRequest(uri)
            .timeout(30, TimeUnit.SECONDS)
            .send();
        
        System.out.println("Response: " + response.getContentAsString());
        
        httpClient.stop();
    }
}

Java Load Test Example

import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicLong;

public class H3LoadTest {
    private static final String URL = "https://localhost:4433";
    private static final int CONCURRENCY = 100;
    private static final int DURATION_SECONDS = 30;
    
    public static void main(String[] args) throws Exception {
        ExecutorService executor = Executors.newFixedThreadPool(CONCURRENCY);
        AtomicLong requestCount = new AtomicLong(0);
        AtomicLong errorCount = new AtomicLong(0);
        
        long endTime = System.currentTimeMillis() + (DURATION_SECONDS * 1000);
        
        for (int i = 0; i < CONCURRENCY; i++) {
            executor.submit(() -> {
                while (System.currentTimeMillis() < endTime) {
                    try {
                        // Send HTTP/3 request
                        requestCount.incrementAndGet();
                        Thread.sleep(10);
                    } catch (Exception e) {
                        errorCount.incrementAndGet();
                    }
                }
            });
        }
        
        executor.shutdown();
        executor.awaitTermination(DURATION_SECONDS + 5, TimeUnit.SECONDS);
        
        System.out.println("Requests: " + requestCount.get());
        System.out.println("Errors: " + errorCount.get());
    }
}

Kotlin Implementation

build.gradle.kts

dependencies {
    implementation("org.eclipse.jetty.http3:jetty-http3-client:12.0.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

Kotlin Client Code

import kotlinx.coroutines.*
import org.eclipse.jetty.http3.client.HTTP3Client
import org.eclipse.jetty.http3.client.transport.HttpClientTransportOverHTTP3
import org.eclipse.jetty.client.HttpClient
import java.net.URI
import java.util.concurrent.atomic.AtomicLong

class H3LoadTester(
    private val url: String,
    private val concurrency: Int,
    private val durationSeconds: Int
) {
    private val requestCount = AtomicLong(0)
    private val errorCount = AtomicLong(0)
    
    suspend fun run(): Report = withContext(Dispatchers.IO) {
        val client = createClient()
        val endTime = System.currentTimeMillis() + (durationSeconds * 1000L)
        
        val jobs = List(concurrency) {
            launch {
                while (System.currentTimeMillis() < endTime) {
                    try {
                        sendRequest(client)
                        requestCount.incrementAndGet()
                    } catch (e: Exception) {
                        errorCount.incrementAndGet()
                    }
                }
            }
        }
        
        jobs.joinAll()
        client.stop()
        
        Report(
            totalRequests = requestCount.get(),
            errors = errorCount.get(),
            successRate = requestCount.get().toDouble() / 
                         (requestCount.get() + errorCount.get())
        )
    }
    
    private fun createClient(): HttpClient {
        val h3Client = HTTP3Client()
        val transport = HttpClientTransportOverHTTP3(h3Client)
        return HttpClient(transport).apply { start() }
    }
    
    private suspend fun sendRequest(client: HttpClient) {
        client.newRequest(URI.create(url))
            .timeout(10, TimeUnit.SECONDS)
            .send()
    }
    
    data class Report(
        val totalRequests: Long,
        val errors: Long,
        val successRate: Double
    )
}

fun main() = runBlocking {
    val tester = H3LoadTester(
        url = "https://localhost:4433",
        concurrency = 100,
        durationSeconds = 30
    )
    
    val report = tester.run()
    println("Total Requests: ${report.totalRequests}")
    println("Success Rate: ${"%.2f".format(report.successRate * 100)}%")
}

Godot Implementation

Godot 4 HTTP/3 Client (GDScript)

extends Node

@export var server_url: String = "https://localhost:4433"
@export var concurrency: int = 10
@export var test_duration: float = 30.0

var requests_sent: int = 0
var requests_completed: int = 0
var errors: int = 0
var is_testing: bool = false

func start_load_test():
    is_testing = true
    requests_sent = 0
    requests_completed = 0
    errors = 0
    
    for i in range(concurrency):
        _spawn_worker()

func _spawn_worker():
    var thread = Thread.new()
    thread.start(_worker_loop.bind(thread))
    await get_tree().create_timer(test_duration).timeout
    is_testing = false

func _worker_loop(thread: Thread):
    var http = HTTPRequest.new()
    add_child(http)
    
    while is_testing:
        var start_time = Time.get_ticks_msec()
        var error = http.request(server_url)
        
        if error == OK:
            requests_sent += 1
            await http.request_completed
            requests_completed += 1
        else:
            errors += 1
        
        await get_tree().create_timer(0.01).timeout
    
    http.queue_free()
    thread.wait_to_finish()

func get_stats() -> Dictionary:
    return {
        "sent": requests_sent,
        "completed": requests_completed,
        "errors": errors,
        "success_rate": float(requests_completed) / float(requests_sent + errors) if requests_sent + errors > 0 else 0.0
    }

func _ready():
    start_load_test()
    
    var timer = Timer.new()
    timer.wait_time = 1.0
    timer.timeout.connect(_on_timer_timeout)
    add_child(timer)
    timer.start()

func _on_timer_timeout():
    var stats = get_stats()
    print("Requests: ", stats.sent, " | Completed: ", stats.completed, " | Errors: ", stats.errors)

Express Implementation

Express Server with HTTP/3 Support

import express from "express";
import { createServer } from "https";
import { readFileSync } from "fs";

const app = express();

app.use(express.json());
app.use(express.static("public"));

app.get("/api/health", (req, res) => {
    res.json({ status: "ok", timestamp: Date.now() });
});

app.post("/api/data", (req, res) => {
    res.json({ received: req.body, echo: true });
});

app.get("/api/stress", (req, res) => {
    let iterations = 0;
    const start = Date.now();
    
    for (let i = 0; i < 100000; i++) {
        iterations++;
    }
    
    res.json({ 
        iterations, 
        duration: Date.now() - start,
        message: "Stress test endpoint"
    });
});

const options = {
    key: readFileSync("./certs/private.key"),
    cert: readFileSync("./certs/certificate.crt")
};

const server = createServer(options, app);

server.listen(4433, () => {
    console.log("Express + HTTPS server running on port 4433");
});

export { app, server };

Express with H3-Stress Testing Script

import { H3Tester } from "h3-stress";

async function testExpressServer() {
    const tester = new H3Tester({
        target: "https://localhost:4433",
        concurrency: 500,
        duration: 30,
        streamsPerConnection: 20,
        datagramRate: 1000,
        enableMigration: false,
        workerCount: 4
    });
    
    console.log("Testing Express HTTP/3 server...");
    
    tester.on("stats", (stats) => {
        console.log(`[${new Date().toISOString()}] ` +
                    `p99: ${stats.latency.p99}ms | ` +
                    `Throughput: ${stats.throughput.requestsPerSecond} req/s`);
    });
    
    const report = await tester.run();
    
    console.log("\n=== Express Server Test Results ===");
    console.log(`Total Requests: ${report.totalRequests}`);
    console.log(`Success Rate: ${(report.successRate * 100).toFixed(2)}%`);
    console.log(`p99 Latency: ${report.latency.p99.toFixed(2)}ms`);
    console.log(`Throughput: ${report.throughput.requestsPerSecond.toFixed(2)} req/s`);
    
    return report;
}

testExpressServer().catch(console.error);

HTML Implementation

Browser Client for H3-Stress Testing

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>H3-Stress Client</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }
        
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            background: linear-gradient(135deg, #1a1a2e, #16213e);
            color: #eee;
            min-height: 100vh;
            padding: 20px;
        }
        
        .container {
            max-width: 1200px;
            margin: 0 auto;
        }
        
        h1 {
            text-align: center;
            margin-bottom: 30px;
            color: #00d4ff;
        }
        
        .status-bar {
            background: #0f3460;
            border-radius: 10px;
            padding: 20px;
            margin-bottom: 20px;
            display: flex;
            justify-content: space-between;
            flex-wrap: wrap;
            gap: 15px;
        }
        
        .status-card {
            background: #1a1a2e;
            padding: 15px;
            border-radius: 8px;
            min-width: 150px;
            text-align: center;
        }
        
        .status-card h3 {
            font-size: 14px;
            color: #888;
            margin-bottom: 10px;
        }
        
        .status-card .value {
            font-size: 28px;
            font-weight: bold;
            color: #00d4ff;
        }
        
        .controls {
            background: #0f3460;
            border-radius: 10px;
            padding: 20px;
            margin-bottom: 20px;
            display: flex;
            gap: 15px;
            flex-wrap: wrap;
        }
        
        button {
            background: #00d4ff;
            color: #1a1a2e;
            border: none;
            padding: 12px 24px;
            border-radius: 8px;
            font-size: 16px;
            font-weight: bold;
            cursor: pointer;
            transition: transform 0.2s;
        }
        
        button:hover {
            transform: scale(1.02);
        }
        
        button.danger {
            background: #e94560;
            color: white;
        }
        
        .logs {
            background: #0f3460;
            border-radius: 10px;
            padding: 20px;
            height: 300px;
            overflow-y: auto;
            font-family: monospace;
            font-size: 12px;
        }
        
        .log-entry {
            padding: 5px;
            border-bottom: 1px solid #1a1a2e;
            color: #00d4ff;
        }
        
        .log-error {
            color: #e94560;
        }
        
        .log-success {
            color: #00ff88;
        }
        
        input {
            background: #1a1a2e;
            border: 1px solid #00d4ff;
            color: white;
            padding: 10px;
            border-radius: 5px;
            flex: 1;
            min-width: 200px;
        }
        
        .chart-container {
            background: #0f3460;
            border-radius: 10px;
            padding: 20px;
            margin-top: 20px;
        }
        
        canvas {
            background: #1a1a2e;
            border-radius: 5px;
            width: 100%;
            height: 200px;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>🚀 H3-Stress Web Client</h1>
        
        <div class="status-bar">
            <div class="status-card">
                <h3>Connection Status</h3>
                <div class="value" id="status">Disconnected</div>
            </div>
            <div class="status-card">
                <h3>Transport</h3>
                <div class="value" id="transport">-</div>
            </div>
            <div class="status-card">
                <h3>Messages Sent</h3>
                <div class="value" id="sent">0</div>
            </div>
            <div class="status-card">
                <h3>Messages Received</h3>
                <div class="value" id="received">0</div>
            </div>
            <div class="status-card">
                <h3>Avg Latency</h3>
                <div class="value" id="latency">0ms</div>
            </div>
        </div>
        
        <div class="controls">
            <input type="text" id="serverUrl" placeholder="https://localhost:4433" value="https://localhost:4433">
            <input type="number" id="messageRate" placeholder="Messages per second" value="100">
            <button id="connectBtn">Connect</button>
            <button id="disconnectBtn" class="danger">Disconnect</button>
            <button id="stressBtn">Start Stress Test</button>
        </div>
        
        <div class="logs" id="logs">
            <div class="log-entry">[System] Ready to connect...</div>
        </div>
        
        <div class="chart-container">
            <canvas id="latencyChart"></canvas>
        </div>
    </div>
    
    <script>
        let client = null;
        let messageCount = 0;
        let receiveCount = 0;
        let latencies = [];
        let stressInterval = null;
        let chart = null;
        
        function addLog(message, type = "info") {
            const logsDiv = document.getElementById("logs");
            const logEntry = document.createElement("div");
            logEntry.className = `log-entry ${type === "error" ? "log-error" : type === "success" ? "log-success" : ""}`;
            logEntry.textContent = `[${new Date().toLocaleTimeString()}] ${message}`;
            logsDiv.appendChild(logEntry);
            logsDiv.scrollTop = logsDiv.scrollHeight;
            
            while (logsDiv.children.length > 100) {
                logsDiv.removeChild(logsDiv.firstChild);
            }
        }
        
        function updateUI() {
            document.getElementById("sent").textContent = messageCount;
            document.getElementById("received").textContent = receiveCount;
            
            const avgLatency = latencies.length > 0 
                ? (latencies.reduce((a, b) => a + b, 0) / latencies.length).toFixed(2)
                : 0;
            document.getElementById("latency").textContent = `${avgLatency}ms`;
            
            if (latencies.length > 100) {
                latencies = latencies.slice(-100);
            }
            
            if (chart) {
                const data = {
                    labels: latencies.map((_, i) => i),
                    datasets: [{
                        label: 'Latency (ms)',
                        data: latencies,
                        borderColor: '#00d4ff',
                        backgroundColor: 'rgba(0, 212, 255, 0.1)',
                        fill: true
                    }]
                };
                chart.data = data;
                chart.update();
            }
        }
        
        class WebTransClient {
            constructor(url) {
                this.url = url;
                this.transportType = null;
                this.ws = null;
                this.isConnected = false;
            }
            
            async connect() {
                if (typeof WebTransport !== 'undefined') {
                    try {
                        this.transport = new WebTransport(this.url);
                        await this.transport.ready;
                        this.transportType = "WebTransport (HTTP/3)";
                        this.isConnected = true;
                        this.setupWebTransport();
                        return true;
                    } catch (e) {
                        addLog(`WebTransport failed: ${e.message}`, "error");
                    }
                }
                
                return this.connectWebSocket();
            }
            
            setupWebTransport() {
                const reader = this.transport.incomingBidirectionalStreams.getReader();
                
                const readStream = async () => {
                    try {
                        while (true) {
                            const { value: stream, done } = await reader.read();
                            if (done) break;
                            
                            const streamReader = stream.readable.getReader();
                            const { value } = await streamReader.read();
                            
                            if (value) {
                                const text = new TextDecoder().decode(value);
                                const startTime = parseInt(text);
                                const latency = Date.now() - startTime;
                                latencies.push(latency);
                                receiveCount++;
                                updateUI();
                            }
                        }
                    } catch (e) {
                        addLog(`Stream error: ${e.message}`, "error");
                    }
                };
                
                readStream();
            }
            
            connectWebSocket() {
                return new Promise((resolve, reject) => {
                    const wsUrl = this.url.replace("https", "wss").replace("http", "ws");
                    this.ws = new WebSocket(wsUrl);
                    
                    this.ws.onopen = () => {
                        this.transportType = "WebSocket (Fallback)";
                        this.isConnected = true;
                        addLog(`Connected via WebSocket fallback`, "success");
                        resolve(true);
                    };
                    
                    this.ws.onmessage = (event) => {
                        const startTime = parseInt(event.data);
                        const latency = Date.now() - startTime;
                        latencies.push(latency);
                        receiveCount++;
                        updateUI();
                    };
                    
                    this.ws.onerror = (err) => {
                        reject(err);
                    };
                    
                    this.ws.onclose = () => {
                        this.isConnected = false;
                    };
                });
            }
            
            send(data) {
                if (!this.isConnected) return false;
                
                const payload = JSON.stringify(data);
                const startTime = Date.now();
                
                if (this.transport && this.transportType.includes("WebTransport")) {
                    const writer = this.transport.datagrams.writable.getWriter();
                    const encoder = new TextEncoder();
                    writer.write(encoder.encode(startTime.toString()));
                    writer.releaseLock();
                } else if (this.ws && this.ws.readyState === WebSocket.OPEN) {
                    this.ws.send(startTime.toString());
                }
                
                messageCount++;
                updateUI();
                return true;
            }
            
            close() {
                if (this.transport) {
                    this.transport.close();
                }
                if (this.ws) {
                    this.ws.close();
                }
                this.isConnected = false;
            }
        }
        
        async function initChart() {
            const canvas = document.getElementById("latencyChart");
            const ctx = canvas.getContext("2d");
            
            chart = {
                data: {
                    labels: [],
                    datasets: []
                },
                update: () => {
                    if (window.myChart) {
                        window.myChart.data = chart.data;
                        window.myChart.update();
                    }
                }
            };
            
            window.myChart = new Chart(ctx, {
                type: 'line',
                data: chart.data,
                options: {
                    responsive: true,
                    maintainAspectRatio: true,
                    plugins: {
                        legend: {
                            labels: { color: '#eee' }
                        }
                    },
                    scales: {
                        y: {
                            grid: { color: '#333' },
                            title: { display: true, text: 'Latency (ms)', color: '#eee' }
                        },
                        x: {
                            grid: { color: '#333' },
                            title: { display: true, text: 'Request #', color: '#eee' }
                        }
                    }
                }
            });
        }
        
        async function startStressTest() {
            if (!client || !client.isConnected) {
                addLog("Please connect first!", "error");
                return;
            }
            
            const rate = parseInt(document.getElementById("messageRate").value);
            const interval = 1000 / rate;
            
            addLog(`Starting stress test at ${rate} msg/sec`, "success");
            
            stressInterval = setInterval(() => {
                if (client && client.isConnected) {
                    client.send({ type: "stress", timestamp: Date.now() });
                    document.getElementById("sent").textContent = messageCount;
                }
            }, interval);
            
            setTimeout(() => {
                if (stressInterval) {
                    clearInterval(stressInterval);
                    stressInterval = null;
                    addLog("Stress test completed", "success");
                }
            }, 30000);
        }
        
        document.getElementById("connectBtn").onclick = async () => {
            const url = document.getElementById("serverUrl").value;
            client = new WebTransClient(url);
            
            addLog(`Connecting to ${url}...`);
            document.getElementById("status").textContent = "Connecting...";
            
            try {
                await client.connect();
                document.getElementById("status").textContent = "Connected";
                document.getElementById("transport").textContent = client.transportType;
                addLog(`Connected via ${client.transportType}`, "success");
            } catch (err) {
                document.getElementById("status").textContent = "Failed";
                addLog(`Connection failed: ${err.message}`, "error");
            }
        };
        
        document.getElementById("disconnectBtn").onclick = () => {
            if (stressInterval) {
                clearInterval(stressInterval);
                stressInterval = null;
            }
            
            if (client) {
                client.close();
                client = null;
                document.getElementById("status").textContent = "Disconnected";
                addLog("Disconnected", "error");
            }
        };
        
        document.getElementById("stressBtn").onclick = startStressTest;
        
        initChart();
    </script>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
</body>
</html>

Gradle Implementation

build.gradle.kts for HTTP/3 Client

plugins {
    java
    application
    kotlin("jvm") version "1.9.0"
}

group = "com.h3stress"
version = "1.0.0"

repositories {
    mavenCentral()
    maven {
        url = uri("https://oss.sonatype.org/content/repositories/snapshots")
    }
}

dependencies {
    // Jetty HTTP/3 Client
    implementation("org.eclipse.jetty.http3:jetty-http3-client:12.0.0")
    implementation("org.eclipse.jetty:jetty-client:12.0.0")
    
    // Kotlin coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.7.3")
    
    // Logging
    implementation("ch.qos.logback:logback-classic:1.4.11")
    implementation("io.github.microutils:kotlin-logging-jvm:3.0.5")
    
    // JSON
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.15.3")
    
    // Testing
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3")
}

application {
    mainClass.set("com.h3stress.LoadTestRunnerKt")
}

tasks.test {
    useJUnitPlatform()
}

tasks.jar {
    manifest {
        attributes["Main-Class"] = "com.h3stress.LoadTestRunnerKt"
    }
    
    from(configurations.runtimeClasspath.get().map { 
        if (it.isDirectory) it else zipTree(it) 
    })
    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}

Gradle Load Test Runner

// src/main/kotlin/com/h3stress/LoadTestRunner.kt
package com.h3stress

import kotlinx.coroutines.*
import org.eclipse.jetty.http3.client.HTTP3Client
import org.eclipse.jetty.http3.client.transport.HttpClientTransportOverHTTP3
import org.eclipse.jetty.client.HttpClient
import org.eclipse.jetty.client.api.ContentResponse
import mu.KotlinLogging
import java.net.URI
import java.util.concurrent.atomic.AtomicLong
import kotlin.system.measureTimeMillis

private val logger = KotlinLogging.logger {}

data class TestConfig(
    val url: String = "https://localhost:4433",
    val concurrency: Int = 100,
    val durationSeconds: Int = 30,
    val streamsPerConnection: Int = 10,
    val datagramRate: Int = 1000,
    val enableMigration: Boolean = false
)

data class TestResult(
    val totalRequests: Long,
    val successfulRequests: Long,
    val failedRequests: Long,
    val totalDatagrams: Long,
    val avgLatencyMs: Double,
    val p95LatencyMs: Double,
    val p99LatencyMs: Double,
    val throughputRps: Double,
    val migrationsPerformed: Int
)

class H3LoadTester(private val config: TestConfig) {
    private val requestCount = AtomicLong(0)
    private val successCount = AtomicLong(0)
    private val failureCount = AtomicLong(0)
    private val datagramCount = AtomicLong(0)
    private val latencies = mutableListOf<Long>()
    private var migrations = 0
    
    suspend fun run(): TestResult = withContext(Dispatchers.IO) {
        logger.info { "Starting load test on ${config.url}" }
        logger.info { "Concurrency: ${config.concurrency}, Duration: ${config.durationSeconds}s" }
        
        val client = createClient()
        val endTime = System.currentTimeMillis() + (config.durationSeconds * 1000L)
        
        val jobs = List(config.concurrency) { index ->
            launch {
                var streamCount = 0
                while (System.currentTimeMillis() < endTime && streamCount < config.streamsPerConnection) {
                    val latency = measureTimeMillis {
                        try {
                            sendRequest(client, index)
                            successCount.incrementAndGet()
                        } catch (e: Exception) {
                            logger.error { "Request failed: ${e.message}" }
                            failureCount.incrementAndGet()
                        }
                    }
                    
                    latencies.add(latency)
                    requestCount.incrementAndGet()
                    streamCount++
                    
                    if (config.enableMigration && streamCount % 10 == 0) {
                        migrations++
                        logger.debug { "Simulated connection migration #$migrations" }
                    }
                    
                    delay(10)
                }
            }
        }
        
        if (config.datagramRate > 0) {
            launch {
                val intervalMs = 1000 / config.datagramRate
                while (System.currentTimeMillis() < endTime) {
                    try {
                        sendDatagram(client)
                        datagramCount.incrementAndGet()
                    } catch (e: Exception) {
                        logger.error { "Datagram failed: ${e.message}" }
                    }
                    delay(intervalMs.toLong())
                }
            }
        }
        
        jobs.joinAll()
        client.stop()
        
        val sortedLatencies = latencies.sorted()
        val p95Index = (sortedLatencies.size * 0.95).toInt()
        val p99Index = (sortedLatencies.size * 0.99).toInt()
        
        TestResult(
            totalRequests = requestCount.get(),
            successfulRequests = successCount.get(),
            failedRequests = failureCount.get(),
            totalDatagrams = datagramCount.get(),
            avgLatencyMs = if (latencies.isNotEmpty()) latencies.average() else 0.0,
            p95LatencyMs = if (sortedLatencies.isNotEmpty()) sortedLatencies[p95Index].toDouble() else 0.0,
            p99LatencyMs = if (sortedLatencies.isNotEmpty()) sortedLatencies[p99Index].toDouble() else 0.0,
            throughputRps = requestCount.get().toDouble() / config.durationSeconds,
            migrationsPerformed = migrations
        )
    }
    
    private fun createClient(): HttpClient {
        val h3Client = HTTP3Client()
        val transport = HttpClientTransportOverHTTP3(h3Client)
        return HttpClient(transport).apply { start() }
    }
    
    private fun sendRequest(client: HttpClient, workerId: Int): ContentResponse {
        return client.newRequest(URI.create(config.url))
            .timeout(10, java.util.concurrent.TimeUnit.SECONDS)
            .header("X-Worker-Id", workerId.toString())
            .header("X-Request-Seq", requestCount.get().toString())
            .send()
    }
    
    private fun sendDatagram(client: HttpClient) {
        // Datagram simulation - actual implementation requires WebTransport datagram API
        logger.trace { "Sending datagram #${datagramCount.get()}" }
    }
}

suspend fun main() {
    val config = TestConfig(
        url = System.getenv("H3_URL") ?: "https://localhost:4433",
        concurrency = System.getenv("H3_CONCURRENCY")?.toIntOrNull() ?: 100,
        durationSeconds = System.getenv("H3_DURATION")?.toIntOrNull() ?: 30,
        streamsPerConnection = System.getenv("H3_STREAMS")?.toIntOrNull() ?: 10,
        datagramRate = System.getenv("H3_DATAGRAM_RATE")?.toIntOrNull() ?: 1000,
        enableMigration = System.getenv("H3_MIGRATION")?.toBoolean() ?: false
    )
    
    val tester = H3LoadTester(config)
    val result = tester.run()
    
    println("\n" + "=".repeat(50))
    println("LOAD TEST RESULTS")
    println("=".repeat(50))
    println("Total Requests:      ${result.totalRequests}")
    println("Successful:          ${result.successfulRequests}")
    println("Failed:              ${result.failedRequests}")
    println("Total Datagrams:     ${result.totalDatagrams}")
    println("Success Rate:        ${"%.2f".format(result.successfulRequests.toDouble() / result.totalRequests * 100)}%")
    println("Avg Latency:         ${"%.2f".format(result.avgLatencyMs)}ms")
    println("p95 Latency:         ${"%.2f".format(result.p95LatencyMs)}ms")
    println("p99 Latency:         ${"%.2f".format(result.p99LatencyMs)}ms")
    println("Throughput:          ${"%.2f".format(result.throughputRps)} req/s")
    println("Migrations:          ${result.migrationsPerformed}")
    println("=".repeat(50))
}

Gradle Build Script for Running Tests

// build.gradle.kts - Additional tasks

tasks.register<JavaExec>("loadTest") {
    group = "verification"
    description = "Run HTTP/3 load test"
    
    mainClass.set("com.h3stress.LoadTestRunnerKt")
    classpath = sourceSets.main.get().runtimeClasspath
    
    systemProperty("H3_URL", project.findProperty("h3.url") ?: "https://localhost:4433")
    systemProperty("H3_CONCURRENCY", project.findProperty("h3.concurrency") ?: "100")
    systemProperty("H3_DURATION", project.findProperty("h3.duration") ?: "30")
    systemProperty("H3_STREAMS", project.findProperty("h3.streams") ?: "10")
    systemProperty("H3_DATAGRAM_RATE", project.findProperty("h3.datagramRate") ?: "1000")
    systemProperty("H3_MIGRATION", project.findProperty("h3.migration") ?: "false")
}

tasks.register<JavaExec>("aggressiveTest") {
    group = "verification"
    description = "Run aggressive HTTP/3 load test"
    
    mainClass.set("com.h3stress.LoadTestRunnerKt")
    classpath = sourceSets.main.get().runtimeClasspath
    
    systemProperty("H3_URL", project.findProperty("h3.url") ?: "https://localhost:4433")
    systemProperty("H3_CONCURRENCY", "1000")
    systemProperty("H3_DURATION", "60")
    systemProperty("H3_STREAMS", "50")
    systemProperty("H3_DATAGRAM_RATE", "5000")
    systemProperty("H3_MIGRATION", "true")
}

Performance Benchmarks

Test Environment

Component Specification CPU Intel Xeon 4 cores @ 2.5GHz RAM 8GB DDR4 Network 1 Gbps Node.js v20.10.0 OS Ubuntu 22.04 LTS

Benchmark Results

Latency Comparison

Metric WebSocket HTTP/3 (H3-Stress) Improvement Avg Latency 25ms 12ms 52% faster p95 Latency 45ms 22ms 51% faster p99 Latency 68ms 35ms 48% faster Connection Time 3-RTT 0-1 RTT 66% faster

Throughput Comparison

Connections WebSocket (req/s) HTTP/3 (req/s) Improvement 100 8,500 15,200 79% higher 500 12,000 28,500 137% higher 1000 10,500 32,000 205% higher

Datagram Stress Test Results

Datagram Rate Packet Loss CPU Usage Recommendation 1,000 msg/s 0.01% 15% Safe 5,000 msg/s 0.05% 35% Moderate 10,000 msg/s 0.50% 65% Warning 50,000 msg/s 5.00% 95% Critical

System Resource Usage

Workers Connections CPU Usage Memory Usage Throughput 1 100 25% 128 MB 8,000 req/s 2 200 45% 200 MB 15,000 req/s 4 500 75% 350 MB 28,000 req/s 8 1000 95% 600 MB 32,000 req/s

FAQ

1. What is HTTP/3 and why should I test it?

HTTP/3 is the latest version of HTTP that runs over QUIC (UDP-based) instead of TCP. It offers:

· Faster connection establishment (0-RTT vs 3-way handshake) · No head-of-line blocking - multiple streams don't block each other · Built-in encryption (TLS 1.3 mandatory) · Connection migration - survive IP address changes

Testing HTTP/3 servers requires specialized tools like H3-Stress because traditional load testers don't support QUIC.

2. What is connection migration?

Connection migration is a unique QUIC feature where a connection can survive IP address or port changes. This happens when:

· Your phone switches from WiFi to 4G · Your laptop moves between networks · NAT rebinding occurs

H3-Stress simulates this by changing local ports during the test, verifying if your server maintains connection state.

3. Why do I need UDP buffer optimization?

HTTP/3 uses UDP instead of TCP. Linux default UDP buffers are often too small (212KB) for high-throughput testing. Without optimization:

· Packet loss increases dramatically · Test results become inaccurate · CPU usage spikes from dropped packets

Run this before testing:

sudo sysctl -w net.core.rmem_max=26214400
sudo sysctl -w net.core.wmem_max=26214400

4. How many workers should I use?

Set --workers to match your CPU core count:

# For 4-core VPS
h3-stress --url https://server.com --workers 4

# For 8-core machine
h3-stress --url https://server.com --workers 8

Each worker runs on a separate CPU core, maximizing throughput.

5. What's the difference between streams and connections?

Concept Description Limit Connection A single QUIC session (UDP 5-tuple) Network/Server dependent Stream Lightweight bidirectional channel inside a connection Up to 2^62 per connection

HTTP/3 allows hundreds of streams per connection. H3-Stress tests both dimensions.

6. How do I interpret packet loss results?

Loss Rate Meaning < 0.1% Excellent - server handling load well 0.1% - 1% Moderate - near capacity 1% - 5% High - server struggling 5% Critical - UDP buffer or server overload

7. Can H3-Stress test public servers?

Yes, but note:

· Many public CDNs (Cloudflare, Fastly) support HTTP/3 · Use https://cloudflare-quic.com for testing · Respect rate limits - don't overload production servers

8. Why am I getting "WebTransport failed to load"?

Install the optional dependency:

npm install @fails-components/webtransport

Without it, H3-Stress falls back to simulation mode.

Troubleshooting

Issue 1: High Packet Loss Immediately

Symptom: Packet loss > 10% from the start

Solution: Increase UDP buffer size

sudo sysctl -w net.core.rmem_max=26214400
sudo sysctl -w net.core.wmem_max=26214400
sudo sysctl -w net.core.rmem_default=26214400

Make permanent by adding to /etc/sysctl.conf

Issue 2: CPU Usage at 100% on Tester Machine

Symptom: System monitor shows CPU maxed out

Solution: Reduce concurrency or workers

# Reduce worker count
h3-stress --url https://server.com --workers 2

# Or reduce concurrency
h3-stress --url https://server.com --concurrency 100

Issue 3: Connection Refused

Symptom: All connections fail immediately

Solutions:

# Check if server is running HTTP/3
curl --http3 https://localhost:4433

# Check if port is open
sudo netstat -tulpn | grep 4433

# Check firewall (Ubuntu)
sudo ufw allow 4433/udp

Issue 4: Child Process Errors

Symptom: Worker processes dying unexpectedly

Solution: Increase file descriptor limit

ulimit -n 65535

Permanent: Add to /etc/security/limits.conf

* soft nofile 65535
* hard nofile 65535

Issue 5: Self-Signed Certificate Errors

Symptom: WebTransport fails with certificate errors

Solution for development:

# Generate certificate with proper SAN
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

Issue 6: Memory Leak During Long Tests

Symptom: Memory usage grows continuously

Solution: Limit history buffer size

// In your test configuration
const tester = new H3Tester({
  // ... other config
  maxHistorySize: 10000  // Limit stored samples
});

Contributing

Development Setup

git clone https://github.com/Dimzxzzx07/H3-Stress.git
cd H3-Stress
npm install
npm run build
npm test

Project Structure

h3-stress/
├── bin/
│   └── cli.ts              # CLI entry point
├── src/
│   ├── core/
│   │   ├── Engine.ts       # Main test orchestrator
│   │   ├── Connection.ts   # QUIC/WebTransport wrapper
│   │   └── Protocol.ts     # HTTP/3 frame handling
│   ├── cluster/
│   │   ├── WorkerPool.ts   # Child process management
│   │   └── TaskDistributor.ts # Load distribution
│   ├── simulators/
│   │   ├── Migration.ts    # Connection migration
│   │   ├── PacketLoss.ts   # Network impairment
│   │   └── Flood.ts        # Stream/datagram flooding
│   ├── monitor/
│   │   ├── Analytics.ts    # Stats calculation
│   │   └── System.ts       # Resource monitoring
│   └── ui/
│       └── Dashboard.ts    # Terminal UI
├── presets/                # Load test presets
├── test/                   # Unit tests
├── examples/               # Usage examples
└── dist/                   # Compiled output

Running Tests

npm test
npm run test:coverage

Publishing

npm run build
npm publish

Contributing Guidelines

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

License

MIT License

Copyright (c) 2026 Dimzxzzx07

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.