[FEAT] 청중용 라이브 토론 공유 페이지 구현

public/locales/en/translation.json

@@ -260,5 +260,19 @@
   "503 서비스가 일시적으로 중단됨": "503 Service Unavailable",
   "504 게이트웨이 시간 초과": "504 Gateway Timeout",
   "나의 토론 주제": "My Debate Topic",
-  "나의 시간표": "My Timetable"
+  "나의 시간표": "My Timetable",
+  "유효하지 않은 토론방 ID입니다.": "Invalid debate room ID.",
+  "실시간 연결 주소를 확인할 수 없어요.": "Could not verify live connection address.",
+  "토론방 연결이 거부되었어요.": "Connection to the debate room was rejected.",
+  "실시간 연결에서 서버 오류가 발생했어요.": "A server error occurred during live connection.",
+  "실시간 연결을 복구하지 못했어요.": "Failed to recover the live connection.",
+  "토론 상태를 오래 받지 못했어요.": "Did not receive debate status for a long time.",
+  "서버에서 토론 진행 오류를 전달했어요.": "The server reported a debate progress error.",
+  "알 수 없는 실시간 오류가 발생했어요.": "An unknown live error occurred.",
+  "토론 시작을 대기 중입니다.": "Waiting for the debate to start.",
+  "토론이 종료되었습니다.": "The debate has ended.",
+  "페이지 닫기": "Close page",
+  "남은 시간": "Time Remaining",
+  "현재 발언 중": "Currently speaking",
+  "발언 중": "Speaking"
 }

public/locales/ko/translation.json

@@ -260,5 +260,19 @@
   "503 서비스가 일시적으로 중단됨": "503 서비스가 일시적으로 중단됨",
   "504 게이트웨이 시간 초과": "504 게이트웨이 시간 초과",
   "나의 토론 주제": "나의 토론 주제",
-  "나의 시간표": "나의 시간표"
+  "나의 시간표": "나의 시간표",
+  "유효하지 않은 토론방 ID입니다.": "유효하지 않은 토론방 ID입니다.",
+  "실시간 연결 주소를 확인할 수 없어요.": "실시간 연결 주소를 확인할 수 없어요.",
+  "토론방 연결이 거부되었어요.": "토론방 연결이 거부되었어요.",
+  "실시간 연결에서 서버 오류가 발생했어요.": "실시간 연결에서 서버 오류가 발생했어요.",
+  "실시간 연결을 복구하지 못했어요.": "실시간 연결을 복구하지 못했어요.",
+  "토론 상태를 오래 받지 못했어요.": "토론 상태를 오래 받지 못했어요.",
+  "서버에서 토론 진행 오류를 전달했어요.": "서버에서 토론 진행 오류를 전달했어요.",
+  "알 수 없는 실시간 오류가 발생했어요.": "알 수 없는 실시간 오류가 발생했어요.",
+  "토론 시작을 대기 중입니다.": "토론 시작을 대기 중입니다.",
+  "토론이 종료되었습니다.": "토론이 종료되었습니다.",
+  "페이지 닫기": "페이지 닫기",
+  "남은 시간": "남은 시간",
+  "현재 발언 중": "현재 발언 중",
+  "발언 중": "발언 중"
 }

src/apis/sockets/SocketManager.test.ts

@@ -166,6 +166,7 @@ describe('SocketManager', () => {
       socketManager.connect({ baseRetryDelayMs: 1000 });
 
       const client = getLatestClient();
+      client.config.onConnect?.({} as IFrame); // 연결 성공 상태로 만들기
 
       // 초기 딜레이: calculateBackoffDelay(0) = 500 + 10
       expect(client.reconnectDelay).toBe(500 + 10);
@@ -182,6 +183,7 @@ describe('SocketManager', () => {
     it('최대 재시도 횟수 초과 시 재시도 딜레이를 0으로 설정하고 연결을 해제해야 한다', () => {
       socketManager.connect({ maxRetries: 3 });
       const client = getLatestClient();
+      client.config.onConnect?.({} as IFrame); // 연결 성공 상태로 만들기
 
       // 3번까지는 아직 maxRetries 미초과 → deactivate 호출 안 됨
       for (let i = 0; i < 3; i++) {
@@ -199,6 +201,7 @@ describe('SocketManager', () => {
       vi.spyOn(Math, 'random').mockReturnValue(0.5);
       socketManager.connect({ baseRetryDelayMs: 1000, maxRetries: 5 });
       const client = getLatestClient();
+      client.config.onConnect?.({} as IFrame); // 처음 연결 성공 상태로 만들기
 
       // 끊김 2번 → retryCount = 2
       client.config.onWebSocketClose?.({} as CloseEvent);
@@ -307,4 +310,122 @@ describe('SocketManager', () => {
       expect(listener).not.toHaveBeenCalled();
     });
   });
+
+  describe('Error Events & Publishing', () => {
+    it('오류 리스너가 등록되면 SocketError를 받고, 해제 후에는 호출되지 않아야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+
+      // trigger error by failing URL
+      socketManager.connect({ url: '', baseUrl: '' });
+      expect(listener).toHaveBeenCalledOnce();
+      const error = listener.mock.calls[0][0];
+      expect(error.code).toBe('SOCKET_URL_UNAVAILABLE');
+
+      listener.mockClear();
+      socketManager.offErrorEvent(listener);
+      socketManager.connect({ url: '', baseUrl: '' });
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('연결 URL을 결정할 수 없는 경우 SOCKET_URL_UNAVAILABLE 코드와 기술 원인을 가진 오류를 한 번 발행해야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+
+      socketManager.connect({ url: '', baseUrl: '' });
+
+      expect(listener).toHaveBeenCalledOnce();
+      const error = listener.mock.calls[0][0];
+      expect(error.code).toBe('SOCKET_URL_UNAVAILABLE');
+    });
+
+    it('STOMP onStompError 발생 시 SOCKET_STOMP_ERROR 코드와 frame의 message/body 상세를 가진 오류가 발행되어야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+      socketManager.connect();
+
+      const client = getLatestClient();
+      client.config.onStompError?.({
+        headers: { message: 'stomp msg' },
+        body: 'body content',
+      } as unknown as IFrame);
+
+      expect(listener).toHaveBeenCalledOnce();
+      const error = listener.mock.calls[0][0];
+      expect(error.code).toBe('SOCKET_STOMP_ERROR');
+      expect(error.message).toBe('stomp msg');
+      expect(error.detail).toEqual({
+        headers: { message: 'stomp msg' },
+        body: 'body content',
+      });
+    });
+
+    it('한 번도 연결 성공하지 못한 세션에서 WebSocket close가 발생하면 SOCKET_SERVER_REJECTED 오류가 발행되어야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+      socketManager.connect();
+
+      const client = getLatestClient();
+      client.config.onWebSocketClose?.({} as CloseEvent);
+
+      expect(listener).toHaveBeenCalledOnce();
+      const error = listener.mock.calls[0][0];
+      expect(error.code).toBe('SOCKET_SERVER_REJECTED');
+    });
+
+    it('연결 성공 후 close는 기존 재연결 횟수가 남아 있는 동안 오류를 발행하지 않고, 최대 재시도 소진 시 SOCKET_RETRY_EXHAUSTED 오류를 발행해야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+      socketManager.connect({ maxRetries: 2 });
+
+      const client = getLatestClient();
+      client.config.onConnect?.({} as IFrame); // 연결 성공
+
+      // 1차 끊김: 오류 발행 안됨
+      client.config.onWebSocketClose?.({} as CloseEvent);
+      expect(listener).not.toHaveBeenCalled();
+
+      // 2차 끊김: 오류 발행 안됨
+      client.config.onWebSocketClose?.({} as CloseEvent);
+      expect(listener).not.toHaveBeenCalled();
+
+      // 3차 끊김: 재시도 초과 -> 오류 발행
+      client.config.onWebSocketClose?.({} as CloseEvent);
+      expect(listener).toHaveBeenCalledOnce();
+      const error = listener.mock.calls[0][0];
+      expect(error.code).toBe('SOCKET_RETRY_EXHAUSTED');
+    });
+
+    it('STOMP heartbeat 누락으로 onWebSocketClose가 발생한 경우에도 같은 재시도 정책을 따르고, 재시도 소진 후 SOCKET_RETRY_EXHAUSTED로 종료되어야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+      socketManager.connect({ maxRetries: 1 });
+
+      const client = getLatestClient();
+      client.config.onConnect?.({} as IFrame); // 연결 성공
+
+      // 하트비트 누락에 의한 1차 끊김: 오류 발행 안됨
+      client.config.onWebSocketClose?.({} as CloseEvent);
+      expect(listener).not.toHaveBeenCalled();
+
+      // 2차 끊김: 재시도 초과 -> 오류 발행
+      client.config.onWebSocketClose?.({} as CloseEvent);
+      expect(listener).toHaveBeenCalledOnce();
+      const error = listener.mock.calls[0][0];
+      expect(error.code).toBe('SOCKET_RETRY_EXHAUSTED');
+    });
+
+    it('명시적 disconnect 후에는 지연 이벤트가 오류를 발행하지 않아야 한다', () => {
+      const listener = vi.fn();
+      socketManager.onErrorEvent(listener);
+      socketManager.connect();
+
+      const client = getLatestClient();
+      socketManager.disconnect();
+
+      // 과거 세션 이벤트
+      client.config.onWebSocketClose?.({} as CloseEvent);
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
 });

src/apis/sockets/SocketManager.ts

@@ -1,6 +1,7 @@
 import { Client, IMessage, StompHeaders } from '@stomp/stompjs';
 import SockJS from 'sockjs-client';
 import { SocketMessage } from './type';
+import { SocketError } from './error';
 
 /**
  * 소켓 설정을 정하는 인터페이스
@@ -72,6 +73,9 @@ class SocketManager {
   // - 발행자(publisher)는 재연결 여부를 알리는 이 클래스 (SocketManager)
   private connectListeners: Set<() => void> = new Set();
   private closeListeners: Set<() => void> = new Set();
+  private errorListeners: Set<(error: SocketError) => void> = new Set();
+
+  private hasConnected: boolean = false;
 
   /**
    * 관찰자를 등록하는 함수
@@ -105,6 +109,27 @@ class SocketManager {
     this.closeListeners.delete(listener);
   }
 
+  public onErrorEvent(listener: (error: SocketError) => void) {
+    this.errorListeners.add(listener);
+  }
+
+  public offErrorEvent(listener: (error: SocketError) => void) {
+    this.errorListeners.delete(listener);
+  }
+
+  private dispatchError(error: SocketError) {
+    this.errorListeners.forEach((listener) => {
+      try {
+        listener(error);
+      } catch (e) {
+        console.error(
+          '오류 리스너 실행 중 오류 발생. 다음 리스너로 진행합니다.',
+          e,
+        );
+      }
+    });
+  }
+
   /**
    * 연결 여부를 확인하는 함수
    * @returns 연결 여부
@@ -129,13 +154,20 @@ class SocketManager {
 
     // 사용자가 지정한 옵션이 있다면 덮어쓰기
     this.retryCount = 0;
+    this.hasConnected = false;
     this.currentOptions = { ...DEFAULT_OPTIONS, ...options };
 
     const wsUrl = this.resolveWebSocketUrl(this.currentOptions);
     if (!wsUrl) {
       console.error(
         '웹소켓 연결 주소를 결정할 수 없습니다. url 또는 baseUrl 옵션, 혹은 VITE_API_BASE_URL 환경 변수를 확인해주세요.',
       );
+      this.dispatchError(
+        new SocketError(
+          'SOCKET_URL_UNAVAILABLE',
+          '웹소켓 연결 주소를 결정할 수 없습니다.',
+        ),
+      );
       return;
     }
 
@@ -158,6 +190,7 @@ class SocketManager {
       onConnect: () => {
         console.log('✅ 웹 소켓(STOMP) 연결 성공');
         this.retryCount = 0;
+        this.hasConnected = true;
 
         // 모든 관찰자에게 연결이 수립되었다고 알림
         this.connectListeners.forEach((listener) => {
@@ -172,6 +205,13 @@ class SocketManager {
       onStompError: (frame) => {
         console.error('❌ 브로커 에러 발생:', frame.headers['message']);
         console.error('상세 내용:', frame.body);
+        this.dispatchError(
+          new SocketError(
+            'SOCKET_STOMP_ERROR',
+            frame.headers['message'] || 'STOMP 오류 발생',
+            { headers: frame.headers, body: frame.body },
+          ),
+        );
       },
 
       onWebSocketClose: () => {
@@ -192,6 +232,24 @@ class SocketManager {
             );
           }
         });
+
+        if (!this.hasConnected) {
+          this.dispatchError(
+            new SocketError(
+              'SOCKET_SERVER_REJECTED',
+              '서버에 의해 웹소켓 연결이 거부되었거나 즉시 종료되었습니다.',
+            ),
+          );
+
+          if (this.client) {
+            this.client.reconnectDelay = 0;
+            const clientToDeactivate = this.client;
+            this.client = null;
+            clientToDeactivate.deactivate();
+          }
+          return;
+        }
+
         this.handleReconnection();
       },
     });
@@ -215,6 +273,7 @@ class SocketManager {
       this.currentOptions = DEFAULT_OPTIONS;
       this.connectListeners.clear();
       this.closeListeners.clear();
+      this.errorListeners.clear();
 
       console.log('🛑 웹 소켓 연결을 수동으로 해제했습니다.');
     }
@@ -271,6 +330,12 @@ class SocketManager {
       console.error(
         '🚨 최대 재연결 시도 횟수를 초과했습니다. 연결을 포기합니다.',
       );
+      this.dispatchError(
+        new SocketError(
+          'SOCKET_RETRY_EXHAUSTED',
+          '최대 재연결 시도 횟수를 초과했습니다.',
+        ),
+      );
       this.client.reconnectDelay = 0;
 
       // 클라이언트 분리

src/apis/sockets/error.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { SocketError, isSocketError } from './error';
+
+describe('SocketError', () => {
+  it('SocketError 인스턴스는 지정된 코드와 상세 내용을 가져야 한다', () => {
+    const error = new SocketError('SOCKET_URL_UNAVAILABLE', 'Message', {
+      foo: 'bar',
+    });
+    expect(error.code).toBe('SOCKET_URL_UNAVAILABLE');
+    expect(error.message).toBe('Message');
+    expect(error.detail).toEqual({ foo: 'bar' });
+    expect(error.name).toBe('SocketError');
+  });
+
+  it('isSocketError는 SocketError 인스턴스에 대해 true를 반환한다', () => {
+    const error = new SocketError('SOCKET_STOMP_ERROR', 'Message');
+    expect(isSocketError(error)).toBe(true);
+  });
+
+  it('isSocketError는 일반 Error 인스턴스에 대해 false를 반환한다', () => {
+    const error = new Error('Message');
+    expect(isSocketError(error)).toBe(false);
+  });
+});

src/apis/sockets/error.ts

@@ -0,0 +1,21 @@
+export type SocketErrorCode =
+  | 'SOCKET_URL_UNAVAILABLE'
+  | 'SOCKET_SERVER_REJECTED'
+  | 'SOCKET_STOMP_ERROR'
+  | 'SOCKET_RETRY_EXHAUSTED';
+
+export class SocketError extends Error {
+  public readonly code: SocketErrorCode;
+  public readonly detail?: unknown;
+
+  constructor(code: SocketErrorCode, message: string, detail?: unknown) {
+    super(message);
+    this.name = 'SocketError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+export function isSocketError(error: unknown): error is SocketError {
+  return error instanceof SocketError;
+}