websocket-realtime-systems

WebSocket Realtime Systems

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.

Sahip Agent

realtime-systems-reviewer — LB/ingress için platform-engineer, log forensic için devops-debugger delege.

Ne Zaman Kullanılır

• WS bağlantı kurulamıyor / 1006 close
• Idle disconnect (30-60s)
• Reconnect storm
• Mesaj sıralama / drop
• Scale: multi-replica fanout

Workflow

1. Handshake
   • URL şeması (ws/wss), path, query
   • Origin check
   • Auth (token nereye konuyor)
   • Subprotocol
2. Proxy
   • Nginx/ALB/CloudFront WS support
   • Upgrade header pass-through
   • Idle timeout >= heartbeat * 3
3. Lifecycle
   • Heartbeat 20-30s ping
   • Reconnect exp backoff + jitter
   • Close kod kullanım
4. Scale
   • Pub/sub backplane (Redis, NATS)
   • State external
   • Per-pod connection metric -> HPA
5. Mesaj
   • Versioned schema
   • Sequence num
   • Binary (msgpack/protobuf) hot path

Checklist

• Heartbeat impl
• Reconnect backoff + jitter (client)
• Origin check
• Token query string'de değil
• Proxy idle timeout >> heartbeat
• Backpressure (bufferedAmount / send queue)
• Slow consumer kick
• Pub/sub backplane multi-replica
• Metric: active_conn, msg_in/out, drop, lag
• Graceful shutdown SIGTERM (close 1001)

Antipattern

• setInterval(() => ws.send('ping')) ama pong dinleme yok
• Client reconnect backoff'suz -> herd
• Sticky session "zorunlu" (backplane düzgün ise gerek yok)
• Token query string ws://api/?token=... -> log/proxy leak
• Mesaj sıralama TCP'ye güvenmek (replay/retry'da bozulur, seq num şart)
• Browser tab arka plan -> heartbeat throttle (60s+); test et

Örnek Agent Davranışı

User: prod WS ~60s sonra kopuyor, staging OK
Agent:
1. Diff: prod ALB idle_timeout 60, staging 3600
2. Server heartbeat = 90s -> ALB önce drop
3. Çözüm: ALB 3600 + heartbeat 25s
4. Terraform diff + Nginx proxy_read_timeout 3600
5. wscat 5dk smoke

Çıktı Formatı

# WS Diagnosis: <target>

## Symptom
## Stack katmanları (client/proxy/server)
## Bulgu (her katman)
## Diff
## Smoke