http-protocol

HTTP Protocol

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Felsefe

• Status code = semantic. Body'de error yasak.
• Idempotency contract — POST/PATCH için header zorunlu.
• Cache header explicit — Vary + ETag + stale-while-revalidate.
• HTTP/2 multiplex — HTTP/1.1 antipattern (resource concat) yasak.
• TLS 1.2+ + HSTS + ALPN.
• Webhook HMAC sign.

Ne Zaman Kullanılır

• API endpoint review (status code + headers + cache)
• HTTP/1.1 → /2 → /3 migration
• TLS audit (HSTS, cipher, version)
• Cache strategy review (browser + CDN)
• Webhook signing implementation
• Connection pool tuning (perf regression)
• CORS preflight cache audit
• SSE introduction
• gRPC-gateway HTTP layer

Workflow

1) Method + status code audit

# scan kod
rg "@app\.(get|post|put|patch|delete)" src/ --type py | head -20
rg "@(Get|Post|Put|Patch|Delete)Mapping" src/ --type java
rg "router\.(get|post|put|patch|delete)" src/ --type ts

# 200 body'de error tara
rg "return.*status.*200.*error|jsonify.*error.*200" src/

# POST retry-safe mi (Idempotency-Key check)
rg "@app\.post" src/ -A 5 | rg -B 5 "Idempotency-Key"

Audit tablo:

Endpoint	Method	Status	Idempotency-Key	Cache	Issue
POST /v1/orders	POST	201	✓	no-store	OK
POST /v1/refunds	POST	201	✗ ⚠	—	retry-unsafe
GET /v1/users/:id	GET	200	—	private,max-age=300	OK

2) Status code hygiene

Sorun	Fix
200 + { "error": ... }	4xx / 5xx + RFC 7807 problem detail
200 DELETE success	204 No Content
200 POST created	201 Created + Location: header
401 vs 403 karışık	401 = authn eksik; 403 = authz fail
500 her error	4xx for client; 5xx server only
429 yok rate limit	429 + Retry-After: 30

3) Idempotency-Key middleware

# FastAPI middleware
@app.middleware("http")
async def idempotency_middleware(request: Request, call_next):
    if request.method in ("POST", "PATCH") and request.url.path.startswith("/v1/"):
        key = request.headers.get("Idempotency-Key")
        if not key:
            return JSONResponse({"error": "Idempotency-Key required"}, status_code=400)
        cached = await idempotency_store.get(key)
        if cached:
            return JSONResponse(cached.body, status_code=cached.status)
    response = await call_next(request)
    if key:
        await idempotency_store.set(key, response, ttl=86400)
    return response

4) Cache strategy

Resource	Cache-Control
Static asset versioned (/_/abc123.js)	public, max-age=31536000, immutable
Static asset unversioned (/logo.png)	public, max-age=300, must-revalidate
HTML (auth-required)	private, no-cache
API json public	public, max-age=5, s-maxage=60, stale-while-revalidate=30
API json auth-required	private, max-age=0
API json mutation response	no-store

Vary zorunlu auth + accept-encoding + accept-language. ETag conditional GET implement.

5) HTTP/2 enable + verify

Nginx:

server {
  listen 443 ssl http2;
  http2_max_concurrent_streams 128;
  http2_max_field_size 16k;
  http2_max_header_size 32k;
  ...
}

Verify:

curl --http2 -I https://api.acme.com/
# HTTP/2 200

6) HTTP/3 (QUIC) enable

Cloudflare / Fastly / nginx-quic:

listen 443 quic reuseport;
listen 443 ssl http2;
add_header Alt-Svc 'h3=":443"; ma=86400' always;

Verify:

curl --http3 -I https://api.acme.com/
# HTTP/3 200

# alternative: chrome://flags QUIC enable + DevTools Network

7) TLS hardening

# audit
testssl.sh --severity HIGH https://api.acme.com

# expected
TLSv1.0      not offered ✓
TLSv1.1      not offered ✓
TLSv1.2      offered (OK)
TLSv1.3      offered (OK)
HSTS         63072000 (2 yıl), includeSubDomains, preload ✓
ALPN         h2, http/1.1 ✓
OCSP stapling offered ✓

8) Compression

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain application/json application/javascript text/css;

# brotli (with module)
brotli on;
brotli_static on;     # pre-compressed .br dosya serve
brotli_types text/plain application/json application/javascript text/css;

Static asset pre-compress:

find dist -type f \( -name "*.js" -o -name "*.css" -o -name "*.html" \) \
  -exec sh -c 'brotli -q 11 "$1" -o "$1.br"; gzip -9 -k "$1"' _ {} \;

9) Connection pool

# Python httpx
client = httpx.Client(
    limits=httpx.Limits(max_keepalive_connections=20, max_connections=100,
                        keepalive_expiry=30.0),
    timeout=httpx.Timeout(5.0, connect=3.0),
)

// Node undici
const agent = new Agent({
  connections: 100,
  pipelining: 1,        // HTTP/1.1
  keepAliveTimeout: 30_000,
});

Sizing: p99_concurrent_requests × 1.5; sınırsız yasak.

10) Webhook HMAC

import hmac, hashlib

def sign(payload: bytes, secret: bytes) -> str:
    return "sha256=" + hmac.new(secret, payload, hashlib.sha256).hexdigest()

def verify(request: Request, secret: bytes) -> bool:
    sig = request.headers.get("X-Hub-Signature-256")
    timestamp = int(request.headers.get("X-Webhook-Timestamp", 0))
    if abs(time.time() - timestamp) > 300:  # ±5dk replay
        return False
    body = request.body  # raw bytes
    return hmac.compare_digest(sign(body, secret), sig)

11) CORS

# FastAPI
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.acme.com", "https://admin.acme.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "Idempotency-Key"],
    max_age=600,
)

Preflight cache (Access-Control-Max-Age: 600) — 10 dk cache; her request preflight yapmaz.

Checklist

• Status code audit (200 + error body yok; 401/403 ayrımı)
• Method idempotency (POST/PATCH Idempotency-Key zorunlu)
• Cache-Control + Vary + ETag her endpoint
• stale-while-revalidate (CDN)
• HTTP/2 enable (multiplex)
• HTTP/3 Alt-Svc header + QUIC enable (varsa)
• TLS 1.2+ + 1.0/1.1 disabled
• HSTS 1 yıl + includeSubDomains + preload
• ALPN advertise (h2, h3)
• Compression (br > zstd > gzip); pre-compress static
• Connection pool sized (p99 × 1.5)
• Webhook HMAC sign + timestamp tolerance ±5dk
• CORS allowlist + Vary:Origin + Max-Age 600
• Server-Sent Events (varsa) text/event-stream + Cache-Control: no-store

Antipattern

• 200 + error body (status semantik bypass).
• Idempotency-Key yok POST retry.
• GET state-changing.
• PATCH idempotent kabul.
• CORS Allow-Origin: * + credentials.
• HSTS yok production.
• TLS 1.0/1.1 enabled.
• HTTP/1.1 ile resource concat antipattern HTTP/2'de.
• Server push (deprecated).
• Cache-Control eksik.
• no-cache vs no-store karıştırma.
• Vary eksik auth cache leak.
• Binary tekrar compress.
• Webhook unsigned.
• Connection pool sınırsız (FD exhaustion).
• Keep-alive timeout server > proxy (connection reset).
• CORS preflight cache yok (Max-Age 0).
• 401 vs 403 karışık.
• 5xx generic info leak.

Örnek Agent Davranışı

User: /http-audit api-svc
Agent (api-contract-guardian + backend-implementer + security-reviewer):

1. Method/status audit: 47 endpoint
   - 3 POST'ta Idempotency-Key middleware yok (retry-unsafe)
   - 1 endpoint 200 body'sinde {"error": ...} return (status semantik bypass)
   - 2 endpoint DELETE 200 dönüyor (204 olmalı)
   - 5 endpoint 401/403 karışık

2. Cache audit:
   - 18 GET endpoint Cache-Control header'sız
   - 4 endpoint Vary eksik (auth leak)
   - ETag implement yok 22 GET

3. TLS audit (testssl.sh):
   - TLS 1.0 enabled (CVE history)
   - HSTS max-age 86400 (1 gün; target 1 yıl)
   - ALPN h3 advertise yok

4. HTTP/2 enabled ama 6 endpoint HTTP/1.1 antipattern (asset bundling)

5. Webhook 3 outbound endpoint HMAC sign yok

6. CORS Allow-Origin = "*" + credentials = true (spec ihlal)

Findings:
- Critical: TLS 1.0 enabled
- Critical: CORS spec ihlal (allow-origin * + credentials)
- Critical: 3 POST Idempotency-Key yok
- High: 200 body'de error 1 endpoint
- High: HSTS 1 gün (1 yıl olmalı)
- High: 3 webhook unsigned
- Medium: Cache-Control eksik 18 GET
- Medium: Vary eksik 4 endpoint
- Low: HTTP/3 Alt-Svc yok

Action items: 9 issue

Çıktı Formatı

# HTTP Protocol Audit: <service>

## Method + Status code audit

## Idempotency-Key coverage

## Cache strategy (Cache-Control + Vary + ETag)

## HTTP/2 + HTTP/3 status

## TLS audit (testssl.sh output)

## Compression (br + zstd + gzip)

## Connection pool sizing

## Webhook signing

## CORS configuration

## Findings (Critical/High/Medium/Low)

## Action Items
| P | Aksiyon | Sahip | Bitiş |