WebSocket 연결断开 재연결 메커니즘 완벽 구현 가이드

실시간 AI 스트리밍 애플리케이션에서 WebSocket 연결의 안정성은 사용자 경험의 핵심입니다. 이번 튜토리얼에서는 HolySheep AI를 활용하여 산업 수준의 재연결 메커니즘을 구현하는 방법을 상세히 다룹니다.

HolySheep AI vs 공식 API vs 기타 릴레이 서비스 비교

재연결 메커니즘이 중요한 이유

AI 실시간 스트리밍 환경에서 네트워크 불안정, 서버 과부하, 또는 일시적 장애는 빈번하게 발생합니다. HolySheep AI를 사용할 때도 마찬가지로 견고한 재연결 전략이 필수적입니다. 저는 과거 단일 연결만 시도하는 코드로 인해 대규모 배포 시 15% 이상의 사용자 요청이 실패하는 경험을 했습니다.

1. 지수 백오프(Exponential Backoff) 기반 재연결

가장 효과적인 재연결 전략은 연결 시도 간격을 지수적으로 증가시키는 방식입니다. HolySheep AI 게이트웨이와의 연결에서도 이 패턴을 적용하면 서버 부하를 줄이면서도 빠른 복구가 가능합니다.

TypeScript/JavaScript 구현

class HolySheepWebSocketManager {
    private ws: WebSocket | null = null;
    private apiKey: string;
    private baseUrl = 'wss://api.holysheep.ai/v1/realtime';
    private reconnectAttempts = 0;
    private maxReconnectAttempts = 10;
    private baseDelay = 1000; // 1초
    private maxDelay = 30000; // 30초
    private connectionState: 'disconnected' | 'connecting' | 'connected' = 'disconnected';
    private messageBuffer: any[] = [];
    private pingInterval: number | null = null;

    constructor(apiKey: string) {
        this.apiKey = apiKey;
    }

    private calculateBackoff(): number {
        // 지수 백오프 계산: 1초, 2초, 4초, 8초, ... 최대 30초
        const delay = Math.min(
            this.baseDelay * Math.pow(2, this.reconnectAttempts),
            this.maxDelay
        );
        // 랜덤 지터 추가 (서버 부하 분산)
        return delay + Math.random() * 1000;
    }

    private async connect(): Promise {
        if (this.connectionState === 'connecting') {
            console.log('이미 연결 시도 중입니다.');
            return;
        }

        this.connectionState = 'connecting';
        const backoffDelay = this.calculateBackoff();

        console.log(${backoffDelay}ms 후 연결 시도 (시도 ${this.reconnectAttempts + 1}/${this.maxReconnectAttempts}));

        await this.sleep(backoffDelay);

        try {
            this.ws = new WebSocket(${this.baseUrl}?api_key=${this.apiKey});
            this.setupEventHandlers();
        } catch (error) {
            console.error('WebSocket 생성 실패:', error);
            this.handleReconnect();
        }
    }

    private setupEventHandlers(): void {
        if (!this.ws) return;

        this.ws.onopen = () => {
            console.log('✅ HolySheep AI 연결 성공');
            this.connectionState = 'connected';
            this.reconnectAttempts = 0;
            this.startPingPong();
            this.flushMessageBuffer();
        };

        this.ws.onclose = (event) => {
            console.log(❌ 연결 종료: 코드 ${event.code}, 이유: ${event.reason});
            this.connectionState = 'disconnected';
            this.stopPingPong();
            this.handleReconnect();
        };

        this.ws.onerror = (error) => {
            console.error('⚠️ WebSocket 오류:', error);
        };

        this.ws.onmessage = (event) => {
            try {
                const data = JSON.parse(event.data);
                this.handleMessage(data);
            } catch (error) {
                console.error('메시지 파싱 실패:', error);
            }
        };
    }

    private handleReconnect(): void {
        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
            console.error('❌ 최대 재연결 시도 횟수 초과. 연결을 종료합니다.');
            this.emit('connection:failed', { reason: 'max_attempts_exceeded' });
            return;
        }

        this.reconnectAttempts++;
        this.connect();
    }

    private startPingPong(): void {
        this.pingInterval = window.setInterval(() => {
            if (this.ws?.readyState === WebSocket.OPEN) {
                this.ws.send(JSON.stringify({ type: 'ping', timestamp: Date.now() }));
            }
        }, 25000); // 25초마다 ping
    }

    private stopPingPong(): void {
        if (this.pingInterval) {
            clearInterval(this.pingInterval);
            this.pingInterval = null;
        }
    }

    private handleMessage(data: any): void {
        switch (data.type) {
            case 'pong':
                console.log('🏓 Pong 수신 - 연결 정상');
                break;
            case 'stream':
                this.emit('stream:data', data);
                break;
            case 'error':
                console.error('서버 오류:', data.message);
                this.emit('stream:error', data);
관련 리소스
📚 AI API 기술 문서
💰 요금제 보기
📖 개발자 문서
🚀 무료 가입
관련 문서
Claude API 에러 코드 완벽 가이드: 의미와 해결 방법
Axolotl 파인튜닝 설정实战 가이드: HolySheep AI 게이트웨이 활용
Codeium AI 완성 플러그인 설정 완벽 가이드