---
name: websocket-realtime-systems
description: WebSocket protocol, lifecycle, scale, proxy ve observability.
---

# 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ı
```markdown
# WS Diagnosis: <target>

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