@simplysm/service-server 13.0.100 → 14.0.1

package/src/core/define-service.ts

@@ -5,7 +5,7 @@ import { obj } from "@simplysm/core-common";
 import { getConfig } from "../utils/config-manager";
 import path from "path";
 
-// ── Context ──
+// ── 컨텍스트 ──
 
 export interface ServiceContext<TAuthInfo = unknown> {
   server: ServiceServer<TAuthInfo>;
@@ -15,7 +15,7 @@ export interface ServiceContext<TAuthInfo = unknown> {
     authTokenPayload?: AuthTokenPayload<TAuthInfo>;
   };
 
-  /** V1 legacy context (auto-update only) */
+  /** V1 레거시 컨텍스트 (자동 업데이트 전용) */
   legacy?: {
     clientName?: string;
   };
@@ -49,7 +49,7 @@ export function createServiceContext<TAuthInfo = unknown>(
       if (name == null) return undefined;
 
       if (name === "" || name.includes("..") || name.includes("/") || name.includes("\\")) {
-        throw new Error(`Invalid client name: ${name}`);
+        throw new Error(`유효하지 않은 클라이언트 이름: ${name}`);
       }
 
       return name;
@@ -79,28 +79,28 @@ export function createServiceContext<TAuthInfo = unknown>(
       }
 
       const config = configParent[section];
-      if (config == null) throw new Error(`Configuration section not found: ${section}`);
+      if (config == null) throw new Error(`설정 섹션을 찾을 수 없습니다: ${section}`);
       return config;
     },
   };
 }
 
-// ── Auth ──
+// ── 인증 ──
 
 const AUTH_PERMISSIONS = Symbol("authPermissions");
 
-/** Read auth permissions from an auth()-wrapped function. Returns undefined if not wrapped. */
+/** auth()로 래핑된 함수에서 인증 권한을 읽는다. 래핑되지 않은 경우 undefined를 반환한다. */
 export function getServiceAuthPermissions(fn: Function): string[] | undefined {
   return (fn as unknown as Record<symbol, unknown>)[AUTH_PERMISSIONS] as string[] | undefined;
 }
 
 /**
- * Auth wrapper for service factories and methods.
+ * 서비스 팩토리 및 메서드용 인증 래퍼.
  *
- * - Service-level: `auth((ctx) => ({ ... }))` — all methods require login
- * - Service-level with roles: `auth(["admin"], (ctx) => ({ ... }))`
- * - Method-level: `auth(() => result)` — this method requires login
- * - Method-level with roles: `auth(["admin"], () => result)`
+ * - 서비스 수준: `auth((ctx) => ({ ... }))` — 모든 메서드에 로그인 필요
+ * - 서비스 수준 (역할 지정): `auth(["admin"], (ctx) => ({ ... }))`
+ * - 메서드 수준: `auth(() => result)` — 해당 메서드에 로그인 필요
+ * - 메서드 수준 (역할 지정): `auth(["admin"], () => result)`
  */
 export function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
 export function auth<TFunction extends (...args: any[]) => any>(
@@ -111,14 +111,14 @@ export function auth(permissionsOrFn: string[] | Function, maybeFn?: Function):
   const permissions = Array.isArray(permissionsOrFn) ? permissionsOrFn : [];
   const fn = Array.isArray(permissionsOrFn) ? maybeFn! : permissionsOrFn;
 
-  // Create wrapper that preserves call behavior
+  // 호출 동작을 유지하는 래퍼 생성
   const wrapper = (...args: unknown[]) => fn(...args);
   (wrapper as unknown as Record<symbol, unknown>)[AUTH_PERMISSIONS] = permissions;
 
   return wrapper;
 }
 
-// ── Service Definition ──
+// ── 서비스 정의 ──
 
 export interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
   name: string;
@@ -127,15 +127,15 @@ export interface ServiceDefinition<TMethods = Record<string, (...args: any[]) =>
 }
 
 /**
- * Define a service with a name and factory function.
+ * 이름과 팩토리 함수로 서비스를 정의한다.
  *
  * @example
- * // Basic service
+ * // 기본 서비스
  * const HealthService = defineService("Health", (ctx) => ({
  *   check: () => ({ status: "ok" }),
  * }));
  *
- * // Service with auth
+ * // 인증이 필요한 서비스
  * const UserService = defineService("User", auth((ctx) => ({
  *   getProfile: () => ctx.authInfo,
  *   adminOnly: auth(["admin"], () => "admin"),
@@ -152,14 +152,14 @@ export function defineService<TMethods extends Record<string, (...args: any[]) =
   };
 }
 
-// ── Type Utility ──
+// ── 타입 유틸리티 ──
 
 /**
- * Extract method signatures from a ServiceDefinition for client-side type sharing.
+ * 클라이언트 측 타입 공유를 위해 ServiceDefinition에서 메서드 시그니처를 추출한다.
  *
  * @example
  * export type UserServiceType = ServiceMethods<typeof UserService>;
- * // Client: client.getService<UserServiceType>("User");
+ * // 클라이언트: client.getService<UserServiceType>("User");
  */
 export type ServiceMethods<TDefinition> =
   TDefinition extends ServiceDefinition<infer M> ? M : never;

package/src/core/service-executor.ts

@@ -13,55 +13,61 @@ export async function executeServiceMethod(
     http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
   },
 ): Promise<unknown> {
-  // Find service definition
+  // 서비스 정의 검색
   const serviceDef = server.options.services.find((item) => item.name === def.serviceName);
 
   if (serviceDef == null) {
-    throw new Error(`Service [${def.serviceName}] not found.`);
+    throw new Error(`서비스 [${def.serviceName}]를 찾을 수 없습니다.`);
   }
 
-  // Request validation (gatekeeper)
+  // 요청 유효성 검증 (게이트키퍼)
   const clientName = def.socket?.clientName ?? def.http?.clientName;
   if (clientName != null) {
     if (clientName.includes("..") || clientName.includes("/") || clientName.includes("\\")) {
-      throw new Error(`[Security] Invalid client name: ${clientName}`);
+      throw new Error(`[보안] 유효하지 않은 클라이언트 이름: ${clientName}`);
     }
   }
 
-  // Create context
+  // 컨텍스트 생성
   const ctx = createServiceContext(server, def.socket, def.http);
 
-  // Invoke factory to create method object
+  // 팩토리를 호출하여 메서드 객체 생성
   const methods = serviceDef.factory(ctx);
 
-  // Find method
+  // 메서드 검색
   const method = (methods as Record<string, unknown>)[def.methodName];
   if (typeof method !== "function") {
-    throw new Error(`Method [${def.serviceName}.${def.methodName}] not found.`);
+    throw new Error(`메서드 [${def.serviceName}.${def.methodName}]를 찾을 수 없습니다.`);
   }
 
-  // Auth check
-  if (server.options.auth != null) {
-    // Check method-level auth first, fallback to service-level
-    const methodPerms = getServiceAuthPermissions(method);
-    const requiredPerms = methodPerms ?? serviceDef.authPermissions;
+  // 인증 확인
+  const methodPerms = getServiceAuthPermissions(method);
+  const requiredPerms = methodPerms ?? serviceDef.authPermissions;
 
-    if (requiredPerms != null) {
+  if (requiredPerms != null) {
+    if (server.options.auth === undefined) {
+      // auth 설정 누락 — 설정 오류
+      throw new Error("auth 설정이 필요합니다. auth 서비스를 사용하려면 서버 옵션에 auth를 설정하세요.");
+    }
+
+    if (server.options.auth !== false) {
+      // auth가 설정되어 있으면 인증 검사 수행
       const authTokenPayload = def.socket?.authTokenPayload ?? def.http?.authTokenPayload;
 
       if (authTokenPayload == null) {
-        throw new Error("Login is required.");
+        throw new Error("로그인이 필요합니다.");
       }
 
       if (requiredPerms.length > 0) {
         const hasPerm = requiredPerms.some((perm) => authTokenPayload.roles.includes(perm));
         if (!hasPerm) {
-          throw new Error("Insufficient permissions.");
+          throw new Error("권한이 부족합니다.");
         }
       }
     }
+    // auth === false → 의도적 비활성화, 인증 스킵
   }
 
-  // Execute
+  // 실행
   return await method(...def.params);
 }

package/src/index.ts

@@ -1,36 +1,34 @@
-// Types
+// 타입
 export * from "./types/server-options";
 
-// Auth
+// 인증
 export * from "./auth/auth-token-payload";
 export * from "./auth/jwt-manager";
 
-// Core
+// 코어
 export * from "./core/define-service";
 export * from "./core/service-executor";
 
-// Transport - Socket
+// 전송 계층 - Socket
 export * from "./transport/socket/websocket-handler";
 export * from "./transport/socket/service-socket";
 
-// Transport - HTTP
+// 전송 계층 - HTTP
 export * from "./transport/http/http-request-handler";
 export * from "./transport/http/upload-handler";
 export * from "./transport/http/static-file-handler";
 
-// Protocol
+// 프로토콜
 export * from "./protocol/protocol-wrapper";
 
-// Services
+// 서비스
 export * from "./services/orm-service";
 export * from "./services/auto-update-service";
-export * from "./services/smtp-client-service";
-
-// Utils
+// 유틸리티
 export * from "./utils/config-manager";
 
-// Legacy
+// 레거시
 export * from "./legacy/v1-auto-update-handler";
 
-// Main
+// 메인
 export * from "./service-server";

package/src/legacy/v1-auto-update-handler.ts

@@ -18,27 +18,27 @@ interface IV1Response {
 }
 
 /**
- * V1 legacy client handler (only auto-update supported).
- * All other requests return an upgrade-required error.
+ * V1 레거시 클라이언트 핸들러 (자동 업데이트만 지원).
+ * 그 외 모든 요청은 업그레이드 필요 에러를 반환한다.
  */
 export function handleV1Connection(
   socket: WebSocket,
   autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
   clientNameSetter?: (clientName: string | undefined) => void,
 ) {
-  // Notify connection established
+  // 연결 성립 알림
   socket.send(JSON.stringify({ name: "connected" }));
 
-  socket.on("message", (data) => {
+  socket.on("message", async (data) => {
     try {
       const msg = JSON.parse(data.toString()) as IV1Request;
 
-      // Only allow SdAutoUpdateService.getLastVersion
+      // SdAutoUpdateService.getLastVersion만 허용
       if (msg.command === "SdAutoUpdateService.getLastVersion") {
-        // Set legacy context
+        // 레거시 컨텍스트 설정
         clientNameSetter?.(msg.clientName);
 
-        const result = autoUpdateMethods.getLastVersion(msg.params[0] as string);
+        const result = await autoUpdateMethods.getLastVersion(msg.params[0] as string);
 
         const response: IV1Response = {
           name: "response",
@@ -48,20 +48,20 @@ export function handleV1Connection(
         };
         socket.send(JSON.stringify(response));
       } else {
-        // All other requests prompt for upgrade
+        // 그 외 모든 요청은 업그레이드 요구
         const response: IV1Response = {
           name: "response",
           reqUuid: msg.uuid,
           state: "error",
           body: {
-            message: "App upgrade is required.",
+            message: "앱 업그레이드가 필요합니다.",
             code: "UPGRADE_REQUIRED",
           },
         };
         socket.send(JSON.stringify(response));
       }
     } catch (err) {
-      logger.warn("V1 message processing error", err);
+      logger.warn("V1 메시지 처리 에러", err);
     }
   });
 }

package/src/protocol/protocol-wrapper.ts

@@ -5,29 +5,29 @@ import { createServiceProtocol } from "@simplysm/service-common";
 import type * as ServiceProtocolWorkerModule from "../workers/service-protocol.worker";
 
 /**
- * Protocol wrapper interface
+ * 프로토콜 래퍼 인터페이스
  *
- * Automatically offloads heavy message encoding/decoding to a worker thread
- * while using main thread for lightweight operations.
+ * 무거운 메시지 인코딩/디코딩을 worker 스레드에 자동으로 위임하고,
+ * 가벼운 작업은 메인 스레드에서 처리한다.
  */
 export interface ServerProtocolWrapper {
   /**
-   * Encode message (auto worker delegation)
+   * 메시지를 인코딩한다 (worker 자동 위임)
    */
   encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
 
   /**
-   * Decode message (auto worker delegation)
+   * 메시지를 디코딩한다 (worker 자동 위임)
    */
   decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
 
   /**
-   * Dispose protocol resources
+   * 프로토콜 리소스를 해제한다
    */
   dispose(): void;
 }
 
-// Shared worker instance (lazy singleton)
+// 공유 worker 인스턴스 (지연 싱글턴)
 let sharedWorker: WorkerProxy<typeof ServiceProtocolWorkerModule> | undefined;
 
 function getWorker(): WorkerProxy<typeof ServiceProtocolWorkerModule> {
@@ -43,37 +43,37 @@ function getWorker(): WorkerProxy<typeof ServiceProtocolWorkerModule> {
 }
 
 /**
- * Create a protocol wrapper instance
+ * 프로토콜 래퍼 인스턴스를 생성한다
  *
- * Automatically offloads heavy message encoding/decoding to a worker thread
- * while using main thread for lightweight operations.
+ * 무거운 메시지 인코딩/디코딩을 worker 스레드에 자동으로 위임하고,
+ * 가벼운 작업은 메인 스레드에서 처리한다.
  */
 export function createServerProtocolWrapper(): ServerProtocolWrapper {
   // -------------------------------------------------------------------
-  // State
+  // 상태
   // -------------------------------------------------------------------
 
   const protocol = createServiceProtocol();
   const SIZE_THRESHOLD = 30 * 1024; // 30KB
 
   // -------------------------------------------------------------------
-  // Helpers
+  // 헬퍼
   // -------------------------------------------------------------------
 
   /**
-   * Check if message should use worker for encoding
+   * 메시지 인코딩에 worker를 사용해야 하는지 확인한다
    */
   function shouldUseWorkerForEncode(msg: ServiceMessage): boolean {
     if (!("body" in msg)) return false;
 
     const body = msg.body;
 
-    // Uint8Array: always use worker
+    // Uint8Array: 항상 worker 사용
     if (body instanceof Uint8Array) {
       return true;
     }
 
-    // Array: check for Uint8Array elements (ORM results, etc.)
+    // 배열: Uint8Array 요소 존재 여부 확인 (ORM 결과 등)
     if (Array.isArray(body)) {
       return body.length > 0 && body.some((item) => item instanceof Uint8Array);
     }
@@ -82,7 +82,7 @@ export function createServerProtocolWrapper(): ServerProtocolWrapper {
   }
 
   // -------------------------------------------------------------------
-  // Public API
+  // 공개 API
   // -------------------------------------------------------------------
 
   return {

package/src/service-server.ts

@@ -31,14 +31,18 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
   isOpen = false;
 
   private readonly _wsHandler: ReturnType<typeof createWebSocketHandler>;
+  private readonly _jwtSecret: string | undefined;
+  private _shutdownRegistered = false;
 
   readonly fastify: FastifyInstance;
 
   constructor(readonly options: ServiceServerOptions) {
     super();
 
-    // SSL configuration (synchronous)
-    // Note: Fastify HTTPS requires Buffer type (Uint8Array not directly usable)
+    this._jwtSecret = options.auth != null && options.auth !== false ? options.auth.jwtSecret : undefined;
+
+    // SSL 설정 (동기)
+    // 참고: Fastify HTTPS는 Buffer 타입이 필요함 (Uint8Array를 직접 사용할 수 없음)
     const httpsConf = options.ssl
       ? { pfx: Buffer.from(options.ssl.pfxBytes), passphrase: options.ssl.passphrase }
       : null;
@@ -47,17 +51,27 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
 
     this._wsHandler = createWebSocketHandler(
       (def) => executeServiceMethod(this, def),
-      options.auth?.jwtSecret,
+      this._jwtSecret,
     );
   }
 
   async listen(): Promise<void> {
-    logger.info(`Server starting... ${env.VER ?? ""}`);
+    logger.info(`서버 시작 중... ${env.VER ?? ""}`);
+
+    // auth 설정 검증: auth 미설정(undefined)인데 auth 요구 서비스가 있으면 에러
+    if (this.options.auth === undefined) {
+      const authRequiredService = this.options.services.find((s) => s.authPermissions != null);
+      if (authRequiredService != null) {
+        throw new Error(
+          `auth 설정이 필요합니다: 서비스 [${authRequiredService.name}]에 auth가 설정되어 있습니다.`,
+        );
+      }
+    }
 
-    // WebSocket plugin
+    // WebSocket 플러그인
     await this.fastify.register(fastifyWebsocket);
 
-    // Security plugin
+    // 보안 플러그인
     await this.fastify.register(fastifyHelmet, {
       global: true,
       contentSecurityPolicy: {
@@ -78,17 +92,17 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       originAgentCluster: false,
     });
 
-    // Upload plugin
+    // 업로드 플러그인
     await this.fastify.register(fastifyMultipart);
 
-    // Register @fastify/static
+    // @fastify/static 등록
     await this.fastify.register(fastifyStatic, {
       root: path.resolve(this.options.rootPath, "www"),
       wildcard: false,
       serve: false,
     });
 
-    // CORS configuration
+    // CORS 설정
     await this.fastify.register(fastifyCors, {
       origin: (_origin, cb) => {
         cb(null, true);
@@ -97,7 +111,7 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       exposedHeaders: ["Content-Disposition", "Content-Length"],
     });
 
-    // JSON parser
+    // JSON 파서
     this.fastify.addContentTypeParser(
       "application/json",
       { parseAs: "string" },
@@ -113,22 +127,22 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       },
     );
 
-    // JSON serializer
+    // JSON 직렬화기
     this.fastify.setSerializerCompiler(() => (data) => json.stringify(data));
 
-    // API routes
+    // API 라우트
     this.fastify.all("/api/:service/:method", async (req, reply) => {
-      await handleHttpRequest(req, reply, this.options.auth?.jwtSecret, (def) =>
+      await handleHttpRequest(req, reply, this._jwtSecret, (def) =>
         executeServiceMethod(this, def),
       );
     });
 
-    // Upload route
+    // 업로드 라우트
     this.fastify.all("/upload", async (req, reply) => {
-      await handleUpload(req, reply, this.options.rootPath, this.options.auth?.jwtSecret);
+      await handleUpload(req, reply, this.options.rootPath, this._jwtSecret);
     });
 
-    // WebSocket route
+    // WebSocket 라우트
     const onWebSocketConnected = (socket: WebSocket, req: FastifyRequest) => {
       const { ver, clientId, clientName } = req.query as {
         ver: string | undefined;
@@ -138,15 +152,15 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
 
       if (ver === "2") {
         if (clientId == null || clientName == null) {
-          socket.close(1008, "Missing Client ID/NAME");
+          socket.close(1008, "클라이언트 ID/NAME이 누락되었습니다");
           return;
         }
         this._wsHandler.addSocket(socket, clientId, clientName, req);
       } else {
-        // V1 legacy support (auto-update only)
+        // V1 레거시 지원 (자동 업데이트 전용)
         const autoUpdateDef = this.options.services.find((s) => s.name === "AutoUpdate");
         if (autoUpdateDef == null) {
-          socket.close(1008, "AutoUpdate service not configured");
+          socket.close(1008, "AutoUpdate 서비스가 설정되지 않았습니다");
           return;
         }
 
@@ -163,7 +177,7 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
     this.fastify.get("/", { websocket: true }, onWebSocketConnected.bind(this));
     this.fastify.get("/ws", { websocket: true }, onWebSocketConnected.bind(this));
 
-    // Static file wildcard handler
+    // 정적 파일 와일드카드 핸들러
     this.fastify.route({
       method: ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"],
       url: "/*",
@@ -175,19 +189,19 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       },
     });
 
-    // HTTP server-level error handling
+    // HTTP 서버 수준 에러 핸들링
     this.fastify.server.on("error", (err) => {
-      logger.error("HTTP server error", err);
+      logger.error("HTTP 서버 에러", err);
     });
 
-    // Listen
+    // 리슨
     await this.fastify.listen({ port: this.options.port, host: "0.0.0.0" });
 
-    // Register graceful shutdown handler
+    // 정상 종료 핸들러 등록
     this._registerGracefulShutdown();
 
     this.isOpen = true;
-    logger.info(`Server started (port: ${this.options.port})`);
+    logger.info(`서버 시작됨 (포트: ${this.options.port})`);
     this.emit("ready");
   }
 
@@ -196,12 +210,12 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
     await this.fastify.close();
 
     this.isOpen = false;
-    logger.debug("Server closed");
+    logger.debug("서버 종료됨");
     this.emit("close");
   }
 
   async broadcastReload(clientName: string | undefined, changedFileSet: Set<string>) {
-    logger.debug("Broadcasting RELOAD to all server clients");
+    logger.debug("모든 서버 클라이언트에 RELOAD 브로드캐스팅");
     await this._wsHandler.broadcastReload(clientName, changedFileSet);
   }
 
@@ -214,25 +228,24 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
   }
 
   async signAuthToken(payload: AuthTokenPayload<TAuthInfo>) {
-    const jwtSecret = this.options.auth?.jwtSecret;
-    if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
-
-    return signJwt(jwtSecret, payload);
+    if (this._jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
+    return signJwt(this._jwtSecret, payload);
   }
 
   async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>> {
-    const jwtSecret = this.options.auth?.jwtSecret;
-    if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
-
-    return verifyJwt(jwtSecret, token);
+    if (this._jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
+    return verifyJwt(this._jwtSecret, token);
   }
 
   private _registerGracefulShutdown() {
+    if (this._shutdownRegistered) return;
+    this._shutdownRegistered = true;
+
     const shutdownHandler = async (signal: string) => {
-      logger.info(`${signal} signal received. Starting server shutdown...`);
+      logger.info(`${signal} 시그널 수신됨. 서버 종료를 시작합니다...`);
 
       const forceExitTimer = setTimeout(() => {
-        logger.error("Server shutdown timed out (10s). Forcing exit.");
+        logger.error("서버 종료 시간 초과 (10초). 강제 종료합니다.");
         process.exit(1);
       }, 10000);
 
@@ -240,11 +253,11 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
         if (this.isOpen) {
           await this.close();
         }
-        logger.info("Server shut down gracefully.");
+        logger.info("서버가 정상적으로 종료되었습니다.");
         clearTimeout(forceExitTimer);
         process.exit(0);
       } catch (err) {
-        logger.error("Error during server shutdown", err);
+        logger.error("서버 종료 중 에러 발생", err);
         process.exit(1);
       }
     };

package/src/services/auto-update-service.ts

@@ -12,7 +12,7 @@ export const AutoUpdateService = defineService("AutoUpdate", (ctx) => ({
     | undefined
   > {
     const clientPath = ctx.clientPath;
-    if (clientPath == null) throw new Error("Client path not found.");
+    if (clientPath == null) throw new Error("클라이언트 경로를 찾을 수 없습니다.");
 
     if (!(await fsx.exists(path.resolve(clientPath, platform, "updates")))) return undefined;