# QUIC Multi-Stream Benchmarks

Comprehensive performance benchmarks for the `quic-multistream` crate covering all critical aspects of QUIC protocol performance.

## Overview

This benchmark suite provides **826 lines** of production-grade performance tests organized into 6 major categories with realistic workloads.

## Benchmark Categories

### 1. Stream Throughput (`benchmark_stream_throughput`)
**Target**: >100 MB/s per stream

Measures single stream data transfer performance across various payload sizes:
- **100 bytes**: Small message performance (chat, control messages)
- **10 KB**: Medium messages (API responses, JSON payloads)
- **100 KB**: Large messages (images, documents)
- **1 MB**: Bulk data transfer (video chunks, file uploads)

**Operations tested**:
- Unidirectional send
- Unidirectional receive
- Bidirectional send/receive

### 2. Stream Multiplexing (`benchmark_stream_multiplexing`)
**Target**: >50 concurrent streams

Tests concurrent stream handling capabilities:
- **10 streams**: Light multiplexing
- **50 streams**: Moderate multiplexing (target baseline)
- **100 streams**: Heavy multiplexing
- **500 streams**: Stress test

**Scenarios**:
- Uniform workload (all streams same size)
- Mixed workload (varied message sizes)
- Concurrent stream lifecycle management

### 3. Connection Establishment (`benchmark_connection_establishment`)
**Target**: <10ms for 1-RTT, <1ms for 0-RTT

Benchmarks connection handshake performance:
- **0-RTT handshake**: Instant connection (session resumption)
- **1-RTT handshake**: Standard TLS 1.3 handshake
- **Varying RTT**: 50μs to 5ms round-trip times
- **Connection + immediate data**: Handshake with piggybacked data

### 4. Backpressure Handling (`benchmark_backpressure_handling`)
**Target**: <100ms recovery time

Tests flow control and congestion management:
- **Buffer fill/drain cycles**: Memory pressure handling
- **Concurrent backpressure**: Multi-stream flow control
- **Chunked sending**: Smart data segmentation (64 KB chunks)
- **Buffer overflow recovery**: Graceful degradation

### 5. Priority Queue Performance (`benchmark_priority_queue`)
**Target**: <50μs priority switching

Evaluates stream prioritization efficiency:
- **Priority enqueue**: Adding streams to priority queue
- **Priority dequeue**: Retrieving highest priority streams
- **Mixed priority streams**: 4-level priority handling (Critical, High, Normal, Low)
- **Priority switching**: Dynamic priority changes during stream lifetime

### 6. Native Performance Characteristics (`benchmark_native_characteristics`)
**Target**: Establish baseline metrics

Platform-specific performance patterns:
- **Small allocations**: Many small buffers (100 bytes × 100 streams)
- **Large allocations**: Bulk memory (10 MB single allocation)
- **Connection pooling**: Reusing connections across requests
- **Statistics collection**: Monitoring overhead (1000 stat calls)

## Running Benchmarks

### Quick Start

```bash
# Run all benchmarks
cd crates/quic-multistream
cargo bench --bench quic_bench

# Run specific category
cargo bench --bench quic_bench stream_throughput
cargo bench --bench quic_bench multiplexing
cargo bench --bench quic_bench connection
cargo bench --bench quic_bench backpressure
cargo bench --bench quic_bench priority
cargo bench --bench quic_bench native
```

### Advanced Usage

```bash
# Save baseline for comparison
cargo bench --bench quic_bench -- --save-baseline main

# Compare against baseline
cargo bench --bench quic_bench -- --baseline main

# Generate HTML reports
cargo bench --bench quic_bench
open target/criterion/*/report/index.html

# Run with specific sample size
cargo bench --bench quic_bench -- --sample-size 200

# Profile specific benchmark
cargo bench --bench quic_bench stream_throughput -- --profile-time 20
```

## Performance Targets Summary

| Category | Metric | Target | Importance |
|----------|--------|--------|------------|
| **Stream Throughput** | Single stream | >100 MB/s | Critical |
| **Multiplexing** | Concurrent streams | >50 streams | Critical |
| **Connection** | 0-RTT latency | <1ms | High |
| **Connection** | 1-RTT latency | <10ms | High |
| **Backpressure** | Recovery time | <100ms | Medium |
| **Priority Queue** | Switch overhead | <50μs | Medium |
| **Statistics** | Collection overhead | <10μs | Low |

## Benchmark Configuration

### Throughput Benchmarks
- **Sample size**: 100
- **Measurement time**: 10 seconds
- **Warm-up time**: 3 seconds

### Multiplexing Benchmarks
- **Sample size**: 50 (due to complexity)
- **Measurement time**: 15 seconds
- **Warm-up time**: 3 seconds

### Connection Benchmarks
- **Sample size**: 200 (fast operations)
- **Measurement time**: 8 seconds
- **Warm-up time**: 2 seconds

### Backpressure Benchmarks
- **Sample size**: 50 (resource intensive)
- **Measurement time**: 12 seconds
- **Warm-up time**: 3 seconds

### Priority Benchmarks
- **Sample size**: 100
- **Measurement time**: 10 seconds
- **Warm-up time**: 2 seconds

### Native Benchmarks
- **Sample size**: 100
- **Measurement time**: 10 seconds
- **Warm-up time**: Default

## Mock Implementation Details

The benchmarks use a sophisticated mock implementation that simulates realistic QUIC behavior:

### MockConnection Features
- **RTT simulation**: Configurable round-trip time (50μs - 5ms)
- **Stream tracking**: Active stream count monitoring
- **Priority queue**: Binary heap for stream prioritization
- **Backpressure buffer**: 1 MB buffer with overflow detection
- **Statistics**: Real-time connection metrics

### MockStream Features
- **Network delay**: RTT-based delay + transmission time
- **Packet simulation**: 64 KB max packet size (QUIC standard)
- **Priority levels**: 4-tier priority system
- **Chunked transfer**: Configurable chunk sizes
- **Graceful cleanup**: RAII-based resource management

## Interpreting Results

### Criterion Output

```
stream_throughput/send/1MB
                        time:   [10.234 ms 10.456 ms 10.678 ms]
                        thrpt:  [95.83 MiB/s 97.92 MiB/s 100.01 MiB/s]
```

- **time**: Median execution time with confidence interval
- **thrpt**: Throughput (higher is better)

### HTML Reports

Criterion generates interactive HTML reports at:
```
target/criterion/<benchmark_name>/report/index.html
```

Features:
- Line plots showing performance over time
- Violin plots for distribution analysis
- Regression detection
- Historical comparisons

## CI/CD Integration

### GitHub Actions Example

```yaml
name: QUIC Benchmarks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  benchmark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable

      - name: Run benchmarks
        run: |
          cd crates/quic-multistream
          cargo bench --bench quic_bench -- --save-baseline ci

      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: benchmark-results
          path: target/criterion/
```

## Comparison with Other Implementations

### vs. quinn (Native QUIC)
- Mock benchmarks run **10-100x faster** (no network I/O)
- Use for algorithm optimization, not absolute performance
- Real-world tests needed for production validation

### vs. WebTransport (WASM)
- Native expected to be **2-5x faster** than WASM
- WASM lacks 0-RTT support in most browsers
- Different workload characteristics on web platforms

## Optimization Tips

### Based on Benchmark Results

1. **High throughput needed?**
   - Use larger message sizes (>10 KB)
   - Enable chunked transfer for >1 MB
   - Consider connection pooling

2. **Many concurrent streams?**
   - Monitor backpressure buffer
   - Use priority queues strategically
   - Implement stream recycling

3. **Low latency critical?**
   - Use 0-RTT when possible
   - Minimize handshake overhead
   - Reduce buffer sizes

4. **Limited bandwidth?**
   - Aggressive backpressure handling
   - Priority-based scheduling
   - Adaptive chunk sizing

## Future Enhancements

- [ ] Add WASM-specific benchmarks
- [ ] Network simulation (packet loss, jitter)
- [ ] Comparative benchmarks vs HTTP/2, HTTP/3
- [ ] Memory profiling integration
- [ ] CPU profiling with flamegraphs
- [ ] Real-world workload patterns (video streaming, file transfer)

## References

- [Criterion.rs Documentation](https://bheisler.github.io/criterion.rs/book/)
- [QUIC Specification (RFC 9000)](https://www.rfc-editor.org/rfc/rfc9000.html)
- [Quinn Implementation](https://github.com/quinn-rs/quinn)
- [WebTransport Specification](https://w3c.github.io/webtransport/)

---

**Created**: 2025-10-26
**Lines**: 826
**Categories**: 6
**Benchmarks**: 30+
**Status**: ✅ Production Ready