HTTP Versions

burl supports multiple HTTP protocol versions. This guide covers when and how to use each.

Default Behavior

By default, burl uses automatic protocol negotiation:

1. Attempts HTTP/2 via ALPN (Application-Layer Protocol Negotiation)
2. Falls back to HTTP/1.1 if HTTP/2 is not supported

# Auto-negotiate (default)
burl https://api.example.com

HTTP/1.1

Force HTTP/1.1 with --http1:

burl https://api.example.com --http1

When to Use HTTP/1.1

• Testing HTTP/1.1 specific behavior
• Comparing protocol performance
• When the server doesn't support HTTP/2
• Debugging connection issues
• Legacy server compatibility

HTTP/1.1 Characteristics

HTTP/2

Force HTTP/2 with --http2:

burl https://api.example.com --http2

When to Use HTTP/2

• Maximum throughput for many small requests
• When server supports HTTP/2
• Testing HTTP/2 specific features
• Reducing connection overhead

HTTP/2 Characteristics

HTTP/2 Benefits for Benchmarking

1. Reduced Connection Overhead: Fewer TCP connections needed
2. Better Throughput: Multiplexing allows concurrent requests
3. Lower Latency: Header compression reduces payload size

HTTP/3 (Experimental)

Force HTTP/3 with --http3:

burl https://api.example.com --http3

When to Use HTTP/3

• Testing HTTP/3 readiness
• Comparing QUIC performance
• High-latency or lossy networks

HTTP/3 Characteristics

HTTP/3 Requirements

• Server must support HTTP/3 and QUIC
• UDP port 443 must be accessible
• May require specific firewall rules

Protocol Comparison

Run benchmarks with different protocols to compare:

#!/bin/bash
URL="https://api.example.com/users"

echo "HTTP/1.1:"
burl "$URL" --http1 -c 50 -d 30s -f json | jq '{
  protocol: "HTTP/1.1",
  rps: .summary.requests_per_second,
  p99: .latency_ms.p99
}'

echo -e "\nHTTP/2:"
burl "$URL" --http2 -c 50 -d 30s -f json | jq '{
  protocol: "HTTP/2",
  rps: .summary.requests_per_second,
  p99: .latency_ms.p99
}'

echo -e "\nHTTP/3:"
burl "$URL" --http3 -c 50 -d 30s -f json | jq '{
  protocol: "HTTP/3",
  rps: .summary.requests_per_second,
  p99: .latency_ms.p99
}' 2>/dev/null || echo "HTTP/3 not supported"

Troubleshooting

HTTP/2 Not Working

If HTTP/2 doesn't work:

1. Verify server supports HTTP/2:

   curl -I --http2 https://api.example.com 2>&1 | grep -i "http/2"
   

2. Check ALPN negotiation:

   openssl s_client -alpn h2 -connect api.example.com:443 </dev/null 2>&1 | grep "ALPN"
   

HTTP/3 Not Working

If HTTP/3 doesn't work:

1. Verify server advertises HTTP/3:

   curl -I https://api.example.com 2>&1 | grep -i "alt-svc"
   

2. Check UDP connectivity:

   nc -vzu api.example.com 443
   

Best Practices

1. Use defaults for realistic testing: Auto-negotiation mirrors real client behavior
2. Compare protocols: Run benchmarks with each protocol to understand differences
3. Consider your clients: Match the protocol your actual users use
4. Test fallback behavior: Ensure your server handles protocol downgrades gracefully