2nd/10_Wiki/Topics/Coding/Web_WebSocket_Reconnect.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
web-websocket-reconnect	WebSocket 재연결 패턴	Coding	draft	B	conceptual	2026-05-09	2026-05-09	web websocket networking resilience vibe-coding	language applicable_to TypeScript / browser Web Mobile		reconnect exponential backoff ping/pong heartbeat

WebSocket 재연결 패턴

모바일 / 약한 네트워크에서 WebSocket 은 끊긴다. 재연결 + 지수 백오프 + heartbeat + resume offset 4가지를 안 하면 사용자 경험 박살.

📖 핵심 개념

• 끊김 감지: onclose, onerror, ping timeout
• 재연결: 즉시 X. 지수 백오프 + jitter (1s, 2s, 4s, 8s, max 30s).
• Heartbeat: 30~60초마다 ping. 응답 없으면 재연결.
• Resume: 마지막 받은 메시지 id 보내고 그 이후만 받기.

💻 코드 패턴

class ReliableSocket {
  private ws: WebSocket | null = null;
  private retries = 0;
  private heartbeatTimer: any = null;
  private lastSeq = 0;
  private closed = false;

  constructor(private readonly url: () => string, private readonly onMessage: (data: any) => void) {
    this.connect();
  }

  private connect() {
    if (this.closed) return;
    const url = new URL(this.url());
    url.searchParams.set('lastSeq', String(this.lastSeq)); // resume
    this.ws = new WebSocket(url.toString());

    this.ws.onopen = () => { this.retries = 0; this.startHeartbeat(); };
    this.ws.onmessage = (e) => {
      const msg = JSON.parse(e.data);
      if (msg.type === 'pong') return;
      if (typeof msg.seq === 'number') this.lastSeq = msg.seq;
      this.onMessage(msg);
    };
    this.ws.onerror = () => this.ws?.close();
    this.ws.onclose = () => this.scheduleReconnect();
  }

  private startHeartbeat() {
    this.stopHeartbeat();
    this.heartbeatTimer = setInterval(() => {
      if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify({ type: 'ping' }));
    }, 30_000);
  }
  private stopHeartbeat() { if (this.heartbeatTimer) clearInterval(this.heartbeatTimer); }

  private scheduleReconnect() {
    this.stopHeartbeat();
    if (this.closed) return;
    const base = Math.min(30_000, 1000 * Math.pow(2, this.retries++));
    const jitter = Math.random() * base * 0.3;
    setTimeout(() => this.connect(), base + jitter);
  }

  send(data: any) {
    if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(data));
    // else: 큐잉 정책 결정 필요 (drop / queue / reject)
  }
  close() { this.closed = true; this.stopHeartbeat(); this.ws?.close(); }
}

🤔 의사결정 기준

메시지 종류	끊김 동안 정책
실시간 채팅 메시지	재연결 후 resume offset 으로 누락 fetch
라이브 시세 / 메트릭	drop. 최신만 중요
사용자 액션 (버튼 클릭)	큐 + 재연결 후 send (idempotency key 필수)
동시 sub 다수	한 socket 으로 multiplex (channel id)

❌ 안티패턴

• 즉시 재연결 루프: 서버 부하 + 네트워크 폭주. 백오프 필수.
• jitter 없음: 모든 클라이언트가 같은 시간에 동시 재연결 — thundering herd.
• heartbeat 없음: NAT/proxy 가 idle 끊음 (보통 60초). 끊긴지 모름.
• resume 없음: 끊긴 동안 메시지 손실. lastSeq 추적.
• 큐 무한 누적: 끊김 길면 OOM. bounded queue + drop 정책.
• 인증 토큰 만료된 채 재연결: 401 무한 재시도. 만료면 토큰 갱신 후 재연결.

🤖 LLM 활용 힌트

• "지수 백오프 + jitter + heartbeat + resume + bounded queue" 5종 세트 명시.
• 라이브러리 권장: partysocket, socket.io-client, reconnecting-websocket.

🔗 관련 문서

• Backpressure_Patterns
• Idempotent_Operations