@simplysm/service-client 13.0.100 → 14.0.4

package/src/protocol/client-protocol-wrapper.ts

@@ -5,23 +5,26 @@ import type {
   ServiceMessage,
   ServiceProtocol,
 } from "@simplysm/service-common";
+import type { WorkerLike } from "../types/browser-compat";
+import { isWorkerSupported, createBrowserWorker } from "../types/browser-compat";
 
 export interface ClientProtocolWrapper {
   encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
   decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
 }
 
-// Shared worker state (singleton pattern)
-let worker: Worker | undefined;
+// 공유 worker 상태 (싱글턴 패턴)
+let worker: WorkerLike | undefined;
 const workerResolvers = new LazyGcMap<
   string,
   { resolve: (res: unknown) => void; reject: (err: Error) => void }
 >({
-  gcInterval: 5 * 1000, // Check for expired entries every 5s
-  expireTime: 60 * 1000, // Expire after 60s (timeout)
+  gcInterval: 5 * 1000, // 5초마다 만료된 항목 확인
+  expireTime: 60 * 1000, // 60초 후 만료 (타임아웃)
   onExpire: (key, item) => {
-    // Reject on expiry (critical for preventing memory leaks)
-    item.reject(new Error(`Worker task timed out (uuid: ${key})`));
+    // 만료 시 reject (메모리 누수 방지에 필수)
+    item.reject(new Error(`Worker 작업 시간 초과 (uuid: ${key})`));
   },
 });
 
@@ -29,22 +32,24 @@ let workerAvailable: boolean | undefined;
 
 function isWorkerAvailable(): boolean {
   if (workerAvailable === undefined) {
-    workerAvailable = typeof Worker !== "undefined";
+    workerAvailable = isWorkerSupported();
   }
   return workerAvailable;
 }
 
-function getWorker(): Worker | undefined {
+function getWorker(): WorkerLike | undefined {
   if (!isWorkerAvailable()) {
     return undefined;
   }
 
   if (!worker) {
-    // Modern bundlers (Vite/Esbuild/Webpack) use this syntax to split/load the Worker as a separate file
-    // Note: use relative path instead of import.meta.resolve (Vite compatibility)
-    worker = new Worker(new URL("../workers/client-protocol.worker.ts", import.meta.url), {
-      type: "module",
-    });
+    // 모던 번들러 (Vite/Esbuild/Webpack)가 이 구문을 사용하여 Worker를 별도 파일로 분리/로드함
+    // 참고: import.meta.resolve 대신 상대 경로 사용 (Vite 호환성)
+    worker = createBrowserWorker(
+      new URL("../workers/client-protocol.worker.ts", import.meta.url),
+      { type: "module" },
+    );
+    if (worker == null) return undefined;
 
     worker.onmessage = (event: MessageEvent) => {
       const { id, type, result, error } = event.data as {
@@ -59,7 +64,7 @@ function getWorker(): Worker | undefined {
         if (type === "success") {
           resolver.resolve(result);
         } else {
-          const err = new Error(error?.message ?? "Unknown worker error");
+          const err = new Error(error?.message ?? "알 수 없는 worker 에러");
           err.stack = error?.stack;
           resolver.reject(err);
         }
@@ -71,32 +76,32 @@ function getWorker(): Worker | undefined {
 }
 
 /**
- * Delegate work to Worker and await result
- * Note: only call when workerAvailable is true
+ * Worker에 작업을 위임하고 결과를 대기
+ * 참고: workerAvailable이 true일 때만 호출할 것
  */
 async function runWorker(
   type: "encode" | "decode",
   data: unknown,
-  transferables: Transferable[] = [],
+  transferables: ArrayBuffer[] = [],
 ): Promise<unknown> {
   return new Promise((resolve, reject) => {
     const id = Uuid.generate().toString();
 
     workerResolvers.set(id, { resolve, reject });
-    // Called after workerAvailable check, so worker always exists
-    getWorker()!.postMessage({ id, type, data }, { transfer: transferables });
+    // workerAvailable 확인 후 호출되므로 worker는 항상 존재
+    getWorker()!.postMessage({ id, type, data }, transferables);
   });
 }
 
 export function createClientProtocolWrapper(protocol: ServiceProtocol): ClientProtocolWrapper {
-  // Threshold: 30KB
+  // 임계값: 30KB
   const SIZE_THRESHOLD = 30 * 1024;
 
   function shouldUseWorkerForEncode(msg: ServiceMessage): boolean {
     if (!("body" in msg)) return false;
     const body = msg.body;
 
-    // Use worker if Uint8Array is present or array length is large
+    // Uint8Array가 있거나 배열 길이가 큰 경우 worker 사용
     if (body instanceof Uint8Array) return true;
     if (typeof body === "string" && body.length > SIZE_THRESHOLD) return true;
     if (Array.isArray(body)) {
@@ -110,14 +115,14 @@ export function createClientProtocolWrapper(protocol: ServiceProtocol): ClientPr
     uuid: string,
     message: ServiceMessage,
   ): Promise<{ chunks: Bytes[]; totalSize: number }> {
-    // Process on main thread if no Worker or small data
+    // Worker가 없거나 데이터가 작으면 메인 스레드에서 처리
     if (!isWorkerAvailable() || !shouldUseWorkerForEncode(message)) {
       return protocol.encode(uuid, message);
     }
 
     // [Worker]
-    // Encode requires sending an object, so Structured Clone occurs.
-    // But the benefit of offloading JSON.stringify cost from the main thread is greater.
+    // 인코딩은 객체 전송이 필요하므로 Structured Clone이 발생함.
+    // 하지만 메인 스레드에서 JSON.stringify 비용을 오프로드하는 이점이 더 큼.
     return (await runWorker("encode", { uuid, message })) as {
       chunks: Bytes[];
       totalSize: number;
@@ -127,21 +132,25 @@ export function createClientProtocolWrapper(protocol: ServiceProtocol): ClientPr
   async function decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>> {
     const totalSize = bytes.length;
 
-    // Process on main thread if no Worker or small data
+    // Worker가 없거나 데이터가 작으면 메인 스레드에서 처리
     if (!isWorkerAvailable() || totalSize <= SIZE_THRESHOLD) {
       return protocol.decode(bytes);
     }
 
     // [Worker]
-    // Zero-copy transfer (buffer ownership moves to Worker)
-    const rawResult = await runWorker("decode", bytes, [bytes.buffer]);
+    // Zero-copy 전송 (버퍼 소유권이 Worker로 이동)
+    const rawResult = await runWorker("decode", bytes, [bytes.buffer as ArrayBuffer]);
 
-    // Restore class instances (DateTime, etc.) from Worker's plain object result
+    // Worker의 plain object 결과에서 클래스 인스턴스 복원 (DateTime 등)
     return transfer.decode(rawResult) as ServiceMessageDecodeResult<ServiceMessage>;
   }
 
   return {
     encode,
     decode,
+    dispose() {
+      protocol.dispose();
+      workerResolvers.dispose();
+    },
   };
 }

package/src/service-client.ts

@@ -3,33 +3,35 @@ import { EventEmitter } from "@simplysm/core-common";
 import type { ServiceEventDef } from "@simplysm/service-common";
 import { createServiceProtocol } from "@simplysm/service-common";
 
+import type { BlobInput, FileCollection } from "./types/browser-compat";
 import type { ServiceConnectionOptions } from "./types/connection-options";
 import type { ServiceProgress, ServiceProgressState } from "./types/progress.types";
 import { createServiceTransport, type ServiceTransport } from "./transport/service-transport";
 import { createSocketProvider, type SocketProvider } from "./transport/socket-provider";
 import { createEventClient, type EventClient } from "./features/event-client";
 import { createFileClient, type FileClient } from "./features/file-client";
-import { createClientProtocolWrapper } from "./protocol/client-protocol-wrapper";
+import { createClientProtocolWrapper, type ClientProtocolWrapper } from "./protocol/client-protocol-wrapper";
 
 const logger = consola.withTag("service-client:ServiceClient");
 
 interface ServiceClientEvents {
   "request-progress": ServiceProgressState;
   "response-progress": ServiceProgressState;
+  "server-progress": ServiceProgressState;
   "state": "connected" | "closed" | "reconnecting";
-  "reload": Set<string>;
 }
 
 export class ServiceClient extends EventEmitter<ServiceClientEvents> {
-  // Modules
+  // 모듈
   private readonly _socket: SocketProvider;
   private readonly _transport: ServiceTransport;
   private readonly _eventClient: EventClient;
   private readonly _fileClient: FileClient;
 
+  private readonly _protocolWrapper: ClientProtocolWrapper;
   private _authToken?: string;
 
-  // State accessors
+  // 상태 접근자
   get connected() {
     return this._socket.connected;
   }
@@ -47,37 +49,34 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     const wsProtocol = options.ssl ? "wss" : "ws";
     const wsUrl = `${wsProtocol}://${options.host}:${options.port}/ws`;
 
-    // Initialize modules
+    // 모듈 초기화
     this._socket = createSocketProvider(wsUrl, this.name, this.options.maxReconnectCount ?? 10);
     const protocol = createServiceProtocol();
-    const protocolWrapper = createClientProtocolWrapper(protocol);
-    this._transport = createServiceTransport(this._socket, protocolWrapper);
+    this._protocolWrapper = createClientProtocolWrapper(protocol);
+    this._transport = createServiceTransport(this._socket, this._protocolWrapper);
     this._eventClient = createEventClient(this._transport);
     this._fileClient = createFileClient(this.hostUrl, this.name);
 
-    // Event bindings
+    // 이벤트 바인딩
     this._socket.on("state", async (state) => {
       this.emit("state", state);
 
-      // Auto-recover event listeners on reconnect
+      // 재연결 시 이벤트 리스너 자동 복구
       if (state === "connected") {
         try {
           if (this._authToken != null) {
-            await this.auth(this._authToken); // Re-authenticate
+            await this.auth(this._authToken); // 재인증
           }
           await this._eventClient.resubscribeAll();
         } catch (err) {
-          logger.error("Failed to recover event listeners", err);
+          logger.error("이벤트 리스너 복구 실패", err);
         }
       }
     });
 
-    this._transport.on("reload", (changedFiles) => {
-      this.emit("reload", changedFiles);
-    });
   }
 
-  // Proxy creation method for type safety
+  // 타입 안전성을 위한 프록시 생성 메서드
   getService<TService>(serviceName: string): ServiceProxy<TService> {
     return new Proxy({} as ServiceProxy<TService>, {
       get: (_target, prop) => {
@@ -95,6 +94,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
 
   async close(): Promise<void> {
     await this._socket.close();
+    this._protocolWrapper.dispose();
   }
 
   async send(
@@ -117,6 +117,10 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
           this.emit("response-progress", state);
           progress?.response?.(state);
         },
+        server: (state) => {
+          this.emit("server-progress", state);
+          progress?.server?.(state);
+        },
       },
     );
   }
@@ -131,7 +135,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     info: TInfo,
     cb: (data: TData) => PromiseLike<void>,
   ): Promise<string> {
-    if (!this.connected) throw new Error("Not connected to the server.");
+    if (!this.connected) throw new Error("서버에 연결되지 않았습니다.");
     return this._eventClient.addListener(eventDef, info, cb);
   }
 
@@ -147,10 +151,10 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     await this._eventClient.emit(eventDef, infoSelector, data);
   }
 
-  async uploadFile(files: File[] | FileList | { name: string; data: BlobPart }[]) {
+  async uploadFile(files: File[] | FileCollection | { name: string; data: BlobInput }[]) {
     if (this._authToken == null) {
       throw new Error(
-        "No authentication token found. Call auth() to authenticate before uploading files.",
+        "인증 토큰이 없습니다. 파일 업로드 전에 auth()를 호출하여 인증해 주세요.",
       );
     }
     return this._fileClient.upload(files, this._authToken);
@@ -161,11 +165,11 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
   }
 }
 
-// Type transformer that wraps all method return types of TService with Promise
+// TService의 모든 메서드 반환 타입을 Promise로 래핑하는 타입 변환기
 export type ServiceProxy<TService> = {
   [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
     ? (...args: P) => Promise<Awaited<R>>
-    : never; // Non-function properties are excluded
+    : never; // 함수가 아닌 속성은 제외
 };
 
 export function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient {

package/src/transport/service-transport.ts

@@ -10,7 +10,6 @@ import type { ServiceProgress } from "../types/progress.types";
 import type { SocketProvider } from "./socket-provider";
 
 export interface ServiceTransportEvents {
-  reload: Set<string>;
   event: { keys: string[]; data: unknown };
 }
 
@@ -41,34 +40,34 @@ export function createServiceTransport(
     }
   >();
 
-  // Store response progress totalSize (for emitting 100% on complete)
+  // 응답 progress totalSize 저장 (완료 시 100% 전송용)
   const responseProgressTotalSize = new Map<string, number>();
 
   socket.on("message", onMessage);
 
-  // When socket disconnects, reject all pending requests to free memory
+  // 소켓 연결 끊김 시 메모리 해제를 위해 모든 대기 중인 요청을 reject
   socket.on("state", (state) => {
     if (state === "closed" || state === "reconnecting") {
-      cancelAllRequests("Socket connection lost");
+      cancelAllRequests("소켓 연결이 끊어졌습니다");
     }
   });
 
   async function send(message: ServiceClientMessage, progress?: ServiceProgress): Promise<unknown> {
     const uuid = Uuid.generate().toString();
 
-    // Start awaiting response (register listener before sending request for safety)
+    // 응답 대기 시작 (안전을 위해 요청 전송 전에 리스너 등록)
     const responsePromise = new Promise((resolve, reject) => {
       pendingRequests.set(uuid, { resolve, reject, progress });
     });
 
-    // Prevent unhandled rejection when the promise is orphaned (e.g., during HMR cleanup)
+    // Promise가 고아가 되었을 때 unhandled rejection 방지 (예: 소켓 연결 끊김 시)
     responsePromise.catch(() => {});
 
-    // Send request
+    // 요청 전송
     try {
       const { chunks, totalSize } = await protocol.encode(uuid, message);
 
-      // Initialize progress
+      // progress 초기화
       if (chunks.length > 1) {
         progress?.request?.({
           uuid,
@@ -77,18 +76,18 @@ export function createServiceTransport(
         });
       }
 
-      // Send
+      // 전송
       for (const chunk of chunks) {
         await socket.send(chunk);
       }
     } catch (err) {
-      // Clean up immediately on send failure
+      // 전송 실패 시 즉시 정리
       pendingRequests.get(uuid)?.reject(err as Error);
       pendingRequests.delete(uuid);
       throw err;
     }
 
-    // Return response result
+    // 응답 결과 반환
     return responsePromise;
   }
 
@@ -99,7 +98,7 @@ export function createServiceTransport(
 
     try {
       if (decoded.type === "progress") {
-        // Remember totalSize (for emitting 100% on complete)
+        // totalSize 기억 (완료 시 100% 전송용)
         responseProgressTotalSize.set(decoded.uuid, decoded.totalSize);
 
         listenerInfo?.progress?.response?.({
@@ -110,13 +109,13 @@ export function createServiceTransport(
       } else {
         if (decoded.message.name === "progress") {
           const body = decoded.message.body as { totalSize: number; completedSize: number };
-          listenerInfo?.progress?.request?.({
+          listenerInfo?.progress?.server?.({
             uuid: decoded.uuid,
             totalSize: body.totalSize,
             completedSize: body.completedSize,
           });
         } else if (decoded.message.name === "response") {
-          // Emit 100% progress if it was a split message
+          // 분할 메시지였을 경우 100% progress 전송
           const totalSize = responseProgressTotalSize.get(decoded.uuid);
           if (totalSize != null) {
             responseProgressTotalSize.delete(decoded.uuid);
@@ -127,28 +126,23 @@ export function createServiceTransport(
             });
           }
 
-          // Remove from Map since response received
+          // 응답 수신으로 Map에서 제거
           pendingRequests.delete(decoded.uuid);
 
           listenerInfo?.resolve(decoded.message.body as ServiceResponseMessage);
         } else if (decoded.message.name === "error") {
-          // Clean up progress totalSize
+          // progress totalSize 정리
           responseProgressTotalSize.delete(decoded.uuid);
 
-          // Remove from Map since error received
+          // 에러 수신으로 Map에서 제거
           pendingRequests.delete(decoded.uuid);
 
           listenerInfo?.reject(toError(decoded.message.body));
-        } else if (decoded.message.name === "reload") {
-          const body = decoded.message.body as { clientName: string; changedFileSet: Set<string> };
-          if (socket.clientName === body.clientName) {
-            emitter.emit("reload", body.changedFileSet);
-          }
         } else if (decoded.message.name === "evt:on") {
           const body = decoded.message.body as { keys: string[]; data: unknown };
           emitter.emit("event", { keys: body.keys, data: body.data });
         } else {
-          throw new Error("Invalid message received from server.");
+          throw new Error("서버로부터 잘못된 메시지를 수신했습니다.");
         }
       }
     } catch (err) {
@@ -156,10 +150,10 @@ export function createServiceTransport(
     }
   }
 
-  // Cancel all pending requests
+  // 모든 대기 중인 요청 취소
   function cancelAllRequests(reason: string): void {
     for (const listenerInfo of pendingRequests.values()) {
-      listenerInfo.reject(new Error(`Request canceled: ${reason}`));
+      listenerInfo.reject(new Error(`요청 취소됨: ${reason}`));
     }
     pendingRequests.clear();
     responseProgressTotalSize.clear();

package/src/transport/socket-provider.ts

@@ -2,6 +2,12 @@ import type { Bytes } from "@simplysm/core-common";
 import { EventEmitter, Uuid, wait } from "@simplysm/core-common";
 import consola from "consola";
 
+// Node.js 환경에서 글로벌 WebSocket이 없으면 ws 패키지로 polyfill
+if (typeof globalThis.WebSocket === "undefined") {
+  const { WebSocket } = await import("ws");
+  globalThis.WebSocket = WebSocket as never;
+}
+
 const logger = consola.withTag("service-client:SocketProvider");
 
 export interface SocketProviderEvents {
@@ -30,15 +36,15 @@ export function createSocketProvider(
   clientName: string,
   maxReconnectCount: number,
 ): SocketProvider {
-  // Configuration constants
-  const HEARTBEAT_TIMEOUT = 30000; // Consider disconnected if no message for 30s
-  const HEARTBEAT_INTERVAL = 5000; // Send ping every 5s
-  const RECONNECT_DELAY = 3000; // Retry reconnect every 3s
+  // 설정 상수
+  const HEARTBEAT_TIMEOUT = 30000; // 30초 동안 메시지가 없으면 연결 끊김으로 간주
+  const HEARTBEAT_INTERVAL = 5000; // 5초마다 ping 전송
+  const RECONNECT_DELAY = 3000; // 3초마다 재연결 시도
 
-  // Pre-allocate 1-byte buffer (saves memory)
+  // 1바이트 버퍼 사전 할당 (메모리 절약)
   const PING_PACKET = new Uint8Array([0x01]);
 
-  // State
+  // 상태
   let ws: WebSocket | undefined;
   let isManualClose = false;
   let reconnectCount = 0;
@@ -58,10 +64,10 @@ export function createSocketProvider(
     try {
       await createSocket();
       startHeartbeat();
-      reconnectCount = 0; // Reset count on successful connection
+      reconnectCount = 0; // 연결 성공 시 카운트 초기화
       emitter.emit("state", "connected");
     } catch (err) {
-      // Throw on initial connection failure (so the caller can handle it)
+      // 초기 연결 실패 시 예외를 던짐 (호출자가 처리할 수 있도록)
       throw err;
     }
   }
@@ -72,7 +78,7 @@ export function createSocketProvider(
     const currentWs = ws;
     if (currentWs != null) {
       currentWs.close();
-      // Wait until fully closed (graceful shutdown)
+      // 완전히 닫힐 때까지 대기 (정상 종료)
       await wait.until(() => currentWs.readyState === WebSocket.CLOSED, 100, 30).catch(() => {});
     }
     emitter.emit("state", "closed");
@@ -82,11 +88,11 @@ export function createSocketProvider(
     try {
       await wait.until(() => isConnected(), undefined, 50);
     } catch {
-      throw new Error("Not connected to the server. Please check your internet connection.");
+      throw new Error("서버에 연결되지 않았습니다. 인터넷 연결을 확인해 주세요.");
     }
     const currentWs = ws;
     if (currentWs == null) {
-      throw new Error("WebSocket is not connected.");
+      throw new Error("WebSocket이 연결되지 않았습니다.");
     }
     currentWs.send(data);
   }
@@ -109,7 +115,7 @@ export function createSocketProvider(
       };
 
       newWs.onerror = (event: Event) => {
-        // Reject on error during connection
+        // 연결 중 에러 발생 시 reject
         if (!isConnected()) {
           const errorEvent = event as ErrorEvent;
           const msg = errorEvent.message;
@@ -118,21 +124,21 @@ export function createSocketProvider(
       };
     });
 
-    // At this point ws is always assigned (assigned in ws.onopen)
+    // 이 시점에서 ws는 항상 할당됨 (ws.onopen에서 할당됨)
     const currentWs = ws;
     if (currentWs == null) {
-      throw new Error("WebSocket initialization failed");
+      throw new Error("WebSocket 초기화 실패");
     }
 
     currentWs.onmessage = (event) => {
-      lastHeartbeatTime = Date.now(); // Update heartbeat
+      lastHeartbeatTime = Date.now(); // 하트비트 갱신
 
       const data = event.data as ArrayBuffer;
       const bytes = new Uint8Array(data);
 
-      // Raw Ping/Pong handling (checked first)
-      // If 1 byte and first byte is 0x02 (Pong), ignore
-      // (only heartbeat timestamp was updated, nothing else to do)
+      // Raw Ping/Pong 처리 (먼저 확인)
+      // 1바이트이고 첫 번째 바이트가 0x02 (Pong)이면 무시
+      // (하트비트 타임스탬프만 갱신되었으므로 추가 작업 불필요)
       if (bytes.length === 1 && bytes[0] === 0x02) return;
 
       emitter.emit("message", bytes);
@@ -147,11 +153,11 @@ export function createSocketProvider(
   }
 
   async function tryReconnect(): Promise<void> {
-    // Loop-based reconnect (used instead of recursion for stack safety)
+    // 루프 기반 재연결 (스택 안전성을 위해 재귀 대신 사용)
     while (reconnectCount < maxReconnectCount) {
       reconnectCount++;
       emitter.emit("state", "reconnecting");
-      logger.warn("WebSocket disconnected. Attempting reconnect...", {
+      logger.warn("WebSocket 연결 끊김. 재연결 시도 중...", {
         reconnectCount,
         maxReconnectCount,
       });
@@ -162,16 +168,16 @@ export function createSocketProvider(
         await createSocket();
         startHeartbeat();
         reconnectCount = 0;
-        emitter.emit("state", "connected"); // Notify reconnect success
-        logger.info("WebSocket reconnected successfully");
-        return; // Exit on successful reconnect
+        emitter.emit("state", "connected"); // 재연결 성공 알림
+        logger.info("WebSocket 재연결 성공");
+        return; // 재연결 성공 시 루프 종료
       } catch {
-        // Continue loop on failure
+        // 실패 시 루프 계속
       }
     }
 
-    // Max retry count exceeded
-    logger.error("Reconnect retry limit exceeded. Giving up.");
+    // 최대 재시도 횟수 초과
+    logger.error("재연결 재시도 한도 초과. 연결을 포기합니다.");
     emitter.emit("state", "closed");
   }
 
@@ -180,32 +186,32 @@ export function createSocketProvider(
     lastHeartbeatTime = Date.now();
 
     heartbeatTimer = setInterval(() => {
-      // Timeout check
+      // 타임아웃 확인
       if (Date.now() - lastHeartbeatTime > HEARTBEAT_TIMEOUT) {
-        logger.warn("Heartbeat Timeout. Connection lost.");
+        logger.warn("하트비트 타임아웃. 연결이 끊어졌습니다.");
 
-        // Stop the timer immediately on timeout to prevent repeated execution.
+        // 반복 실행 방지를 위해 타임아웃 시 즉시 타이머 중지
         stopHeartbeat();
 
-        // Don't wait for socket close (onclose may not fire); force cleanup and reconnect.
+        // 소켓 종료를 기다리지 않음 (onclose가 발생하지 않을 수 있음); 강제 정리 후 재연결
         if (ws != null) {
           const tempWs = ws;
-          ws = undefined; // Consider connection as disconnected
+          ws = undefined; // 연결 끊김으로 간주
 
-          // Remove event handlers from old socket
-          // Prevent duplicate reconnect from late onclose events
+          // 이전 소켓에서 이벤트 핸들러 제거
+          // 늦게 발생하는 onclose 이벤트로 인한 중복 재연결 방지
           tempWs.onclose = null;
           tempWs.onerror = null;
           tempWs.onmessage = null;
 
-          // Attempt to close socket (ignore errors)
+          // 소켓 닫기 시도 (에러 무시)
           try {
             tempWs.close();
           } catch {
-            // ignore
+            // 무시
           }
 
-          // Force reconnect logic if not a manual close
+          // 수동 종료가 아닌 경우 강제 재연결 로직 실행
           if (!isManualClose) {
             void tryReconnect();
           }
@@ -213,13 +219,13 @@ export function createSocketProvider(
         return;
       }
 
-      // Send ping
+      // ping 전송
       const currentWs = ws;
       if (isConnected() && currentWs != null) {
         try {
           currentWs.send(PING_PACKET);
         } catch (err) {
-          logger.warn("Ping send failed", err);
+          logger.warn("ping 전송 실패", err);
         }
       }
     }, HEARTBEAT_INTERVAL);