# Mozilla HTTP Documentation - Best Practices

**Authority Tier:** Tier 2 (Vendor/Industry Standard)
**Source:** https://developer.mozilla.org/en-US/docs/Web/HTTP
**Relevance:** TLS configuration, timeout recommendations, connection pooling

---

## HTTP Timeouts

### Connection Timeout

> **Recommended:** 10 seconds for initial TCP connection establishment.
>
> **Rationale:** If a server doesn't respond within 10 seconds, it's likely down or unreachable. Longer timeouts block connection establishment.

**Key Claim:**
- `httpclient/connect_timeout :: max_value = 10`
- **Consequence:** Unresponsive endpoints block connection pool

### Request Timeout

> **Recommended:** 30 seconds for total request/response cycle.
>
> **Rationale:** Most web requests complete within seconds. A 30-second timeout catches slow responses without being too aggressive.

**Key Claim:**
- `httpclient/request_timeout :: max_value = 30`
- **Consequence:** Slow services cause cascade failures in calling applications

### Read Timeout

> **Recommended:** 15-30 seconds for reading response body.
>
> **Note:** Should be lower than total request timeout. Prevents clients from hanging on slow streaming responses.

**Key Claim:**
- `httpclient/read_timeout :: max_value = 30`
- **Consequence:** Slow response bodies block thread pool

---

## TLS/SSL Configuration

### Certificate Validation

> **CRITICAL:** Always validate server certificates in production.
>
> **Never use:** `verify=false` or equivalent settings outside of local development.

**Key Claim:**
- `httpclient/tls/certificate_validation :: required = true`
- **Consequence:** Man-in-the-middle attacks, credential theft

### Minimum TLS Version

> **Recommended:** TLS 1.2 or higher (as of 2023).
>
> **Deprecated:** TLS 1.0 and 1.1 are vulnerable to known attacks (BEAST, POODLE).

**Key Claim:**
- `httpclient/tls/min_version :: min_value = 1.2`
- **Consequence:** Vulnerable to protocol downgrade attacks

### TLS Cipher Suites

> **Recommended:** Use modern cipher suites (ECDHE, AES-GCM).
>
> **Avoid:** RC4, 3DES, MD5-based ciphers.

**Key Claim:**
- `httpclient/tls/cipher_suites :: recommended = modern_only`
- **Consequence:** Weak ciphers enable decryption attacks

---

## Connection Pooling

### Pool Size

> **Recommended:** 50-100 connections per host in production.
>
> **Rationale:** HTTP/1.1 requires multiple connections for parallelism. Too few = low throughput. Too many = resource exhaustion.

**Key Claim:**
- `httpclient/pool_size :: recommended_range = 50-100`
- **Consequence:** Insufficient pool size limits throughput

### Idle Connection Cleanup

> **Best Practice:** Close idle connections after 60 seconds.
>
> **Rationale:** Prevents accumulation of stale connections. Aligns with typical server keep-alive timeouts.

**Key Claim:**
- `httpclient/idle_timeout :: default_value = 60`
- **Consequence:** Stale connections waste resources

---

## Retry Behavior

### Idempotent Requests

> **Safe to retry:** GET, HEAD, PUT, DELETE (idempotent methods).
>
> **NOT safe to retry:** POST (non-idempotent unless explicitly designed for idempotency).

**Key Claim:**
- `httpclient/retry/idempotent_only :: required = true`
- **Consequence:** Retrying POST requests may cause duplicate operations

### Retry Limit

> **Recommended:** 3 retries maximum with exponential backoff.
>
> **Rationale:** More retries amplify load during outages (retry storms).

**Key Claim:**
- `httpclient/retry/max_attempts :: max_value = 3`
- **Consequence:** Unlimited retries cause cascade failures

---

## User-Agent Header

### Identification

> **Best Practice:** Always send a User-Agent header identifying the client.
>
> **Format:** `<product>/<version> (<platform>)`

**Key Claim:**
- `httpclient/headers/user_agent :: required = true`
- **Consequence:** Servers may block or rate-limit requests without User-Agent

---

## HTTP/2 and HTTP/3

### Protocol Negotiation

> **Recommended:** Support HTTP/2 via ALPN (Application-Layer Protocol Negotiation).
>
> **Fallback:** HTTP/1.1 if server doesn't support HTTP/2.

**Key Claim:**
- `httpclient/protocol/http2_support :: recommended = true`
- **Consequence:** Suboptimal performance without HTTP/2 multiplexing

---

## Summary of Mozilla Recommendations

| Setting | Mozilla Recommendation | httpclient Value |
|---------|------------------------|------------------|
| **Connect Timeout** | 10 seconds | 10s |
| **Request Timeout** | 30 seconds | 30s |
| **TLS Min Version** | 1.2+ | 1.2 |
| **Certificate Validation** | Always enabled | true |
| **Idle Timeout** | 60 seconds | 60s |
| **Max Retries** | 3 with backoff | 3 |
| **Pool Size** | 50-100 per host | 50-100 |

**Authority Tier:** Tier 2 (Vendor guidelines widely adopted in industry)