@simplysm/service-server 13.0.100 → 14.0.4

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,15 +210,10 @@ 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");
-    await this._wsHandler.broadcastReload(clientName, changedFileSet);
-  }
-
   async emitEvent<TInfo, TData>(
     eventDef: ServiceEventDef<TInfo, TData>,
     infoSelector: (item: TInfo) => boolean,
@@ -214,25 +223,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 +248,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;
 

package/src/services/orm-service.ts

@@ -15,7 +15,7 @@ import consola from "consola";
 
 const logger = consola.withTag("service-server:OrmService");
 
-// Static state needs to live outside the factory (shared across calls)
+// 정적 상태는 팩토리 외부에 존재해야 함 (호출 간 공유)
 const socketConns = new WeakMap<ServiceSocket, Map<number, DbConn>>();
 
 export const OrmService = defineService(
@@ -24,7 +24,7 @@ export const OrmService = defineService(
     const sock = (): ServiceSocket => {
       const socket = ctx.socket;
       if (socket == null) {
-        throw new Error("WebSocket connection is required. ORM service cannot be used over HTTP.");
+        throw new Error("WebSocket 연결이 필요합니다. ORM 서비스는 HTTP로 사용할 수 없습니다.");
       }
       return socket;
     };
@@ -34,7 +34,7 @@ export const OrmService = defineService(
         opt.configName
       ];
       if (config == null) {
-        throw new Error(`ORM configuration not found: ${opt.configName}`);
+        throw new Error(`ORM 설정을 찾을 수 없습니다: ${opt.configName}`);
       }
       return { ...config, ...opt.config } as DbConnConfig;
     };
@@ -43,7 +43,7 @@ export const OrmService = defineService(
       const myConns = socketConns.get(sock());
       const conn = myConns?.get(connId);
       if (conn == null) {
-        throw new Error("Not connected to database. (Invalid Connection ID)");
+        throw new Error("데이터베이스에 연결되지 않았습니다. (유효하지 않은 연결 ID)");
       }
       return conn;
     };
@@ -71,7 +71,7 @@ export const OrmService = defineService(
           sock().on("close", async () => {
             if (myConns == null) return;
 
-            logger.debug("Socket close detected: cleaning up all open DB connections.");
+            logger.debug("소켓 종료 감지: 열린 모든 DB 연결을 정리합니다.");
             const conns = Array.from(myConns.values());
 
             await Promise.all(
@@ -81,7 +81,7 @@ export const OrmService = defineService(
                     await conn.close();
                   }
                 } catch (err) {
-                  logger.warn("Error ignored during forced DB connection close", err);
+                  logger.warn("강제 DB 연결 종료 중 에러 무시됨", err);
                 }
               }),
             );
@@ -110,7 +110,7 @@ export const OrmService = defineService(
           const conn = getConn(connId);
           await conn.close();
         } catch (err) {
-          logger.warn("Error ignored during DB connection close", err);
+          logger.warn("DB 연결 종료 중 에러 무시됨", err);
         }
       },
 

package/src/transport/http/http-request-handler.ts

@@ -16,49 +16,55 @@ export async function handleHttpRequest<TAuthInfo = unknown>(
 ): Promise<void> {
   const { service, method } = req.params as { service: string; method: string };
 
-  // ClientName header
+  // ClientName 헤더
   const clientName = req.headers["x-sd-client-name"] as string | undefined;
-  if (clientName == null) throw new Error("ClientName header is required");
+  if (clientName == null) throw new Error("ClientName 헤더가 필요합니다");
 
-  // Parse and verify Authorization header
+  // Authorization 헤더 파싱 및 검증
   let authTokenPayload: AuthTokenPayload<TAuthInfo> | undefined;
   try {
     const authHeader = req.headers.authorization;
     if (authHeader != null) {
-      if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
+      if (jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
 
       const token = authHeader.split(" ")[1]; // "Bearer <token>"
       authTokenPayload = await verifyJwt<TAuthInfo>(jwtSecret, token);
     }
   } catch (err) {
     reply.status(401).send({
-      error: "Unauthorized",
+      error: "인증 실패",
       message: err instanceof Error ? err.message : String(err),
     });
     return;
   }
 
-  // Parse parameters
+  // 매개변수 파싱
   let params: unknown[] | undefined;
   if (req.method === "GET") {
     const query = req.query as { json?: string };
     if (typeof query.json !== "string") {
-      throw new Error("JSON query parameter required");
+      throw new Error("JSON 쿼리 파라미터가 필요합니다");
     }
     params = json.parse(query.json);
   } else if (req.method === "POST") {
     if (!Array.isArray(req.body)) {
       reply.status(400).send({
-        error: "Bad Request",
-        message: "Request body must be an array.",
+        error: "잘못된 요청",
+        message: "요청 본문은 배열이어야 합니다.",
       });
       return;
     }
 
     params = req.body as unknown[];
+  } else {
+    reply.status(405).send({
+      error: "Method Not Allowed",
+      message: `${req.method} 메서드는 지원하지 않습니다.`,
+    });
+    return;
   }
 
-  // Execute service and send response
+  // 서비스 실행 및 응답 전송
   if (params != null) {
     const serviceResult = await runMethod({
       serviceName: service,

package/src/transport/http/static-file-handler.ts

@@ -14,12 +14,12 @@ export async function handleStaticFile(
   let targetFilePath = path.resolve(rootPath, "www", urlPath);
   const allowedRootPath = path.resolve(rootPath, "www");
 
-  // Security guard for targetPath (prevent path traversal)
+  // targetPath 보안 가드 (경로 탐색 공격 방지)
   if (targetFilePath !== allowedRootPath && !pathx.isChildPath(targetFilePath, allowedRootPath)) {
-    throw new Error("Access denied");
+    throw new Error("접근이 거부되었습니다");
   }
 
-  // Redirect with trailing slash for directories (standard web server behavior)
+  // 디렉토리에 대해 슬래시를 추가하여 리다이렉트 (표준 웹 서버 동작)
   if ((await fsx.exists(targetFilePath)) && (await fsx.stat(targetFilePath)).isDirectory()) {
     if (!urlPath.endsWith("/")) {
       const urlObj = new URL(req.raw.url!, "http://localhost");
@@ -29,15 +29,15 @@ export async function handleStaticFile(
     targetFilePath = path.resolve(targetFilePath, "index.html");
   }
 
-  // Permission check (hidden files, etc.)
+  // 권한 확인 (숨김 파일 등)
   if (path.basename(targetFilePath).startsWith(".")) {
-    const errorMessage = "You do not have permission to access this file.";
+    const errorMessage = "이 파일에 접근할 권한이 없습니다.";
     responseErrorHtml(reply, 403, errorMessage);
     logger.warn(`[403] ${errorMessage} (${targetFilePath})`);
     return;
   }
 
-  // Send file
+  // 파일 전송
   const filename = path.basename(targetFilePath);
   const directory = path.dirname(targetFilePath);
 
@@ -46,11 +46,11 @@ export async function handleStaticFile(
   } catch (err: unknown) {
     const error = err as { code?: string };
     if (error.code === "ENOENT") {
-      const errorMessage = "File not found.";
+      const errorMessage = "파일을 찾을 수 없습니다.";
       responseErrorHtml(reply, 404, errorMessage);
       logger.warn(`[404] ${errorMessage} (${targetFilePath})`);
     } else {
-      const errorMessage = "An error occurred while sending the file.";
+      const errorMessage = "파일 전송 중 에러가 발생했습니다.";
       responseErrorHtml(reply, 500, errorMessage);
       logger.error(`[500] ${errorMessage}`, err);
     }

package/src/transport/http/upload-handler.ts

@@ -17,24 +17,24 @@ export async function handleUpload(
   jwtSecret: string | undefined,
 ): Promise<void> {
   if (!req.isMultipart()) {
-    reply.status(400).send("Multipart request expected");
+    reply.status(400).send("Multipart 요청이 필요합니다");
     return;
   }
 
-  // Auth check
+  // 인증 확인
   try {
     const authHeader = req.headers.authorization;
     if (authHeader == null) {
-      throw new Error("Authentication token is missing.");
+      throw new Error("인증 토큰이 누락되었습니다.");
     }
     if (jwtSecret == null) {
-      throw new Error("JWT Secret is not defined.");
+      throw new Error("JWT Secret이 정의되지 않았습니다.");
     }
     const token = authHeader.split(" ")[1];
     await verifyJwt(jwtSecret, token);
   } catch (err) {
     reply.status(401).send({
-      error: "Unauthorized",
+      error: "인증 실패",
       message: err instanceof Error ? err.message : String(err),
     });
     return;
@@ -58,7 +58,7 @@ export async function handleUpload(
         await pipeline(part.file, createWriteStream(currentSavePath));
 
         if (part.file.truncated) {
-          throw new Error(`File limit exceeded: ${originalFilename}`);
+          throw new Error(`파일 크기 제한 초과: ${originalFilename}`);
         }
 
         const stats = await fsx.stat(currentSavePath);
@@ -75,13 +75,20 @@ export async function handleUpload(
 
     reply.send(result);
   } catch (err) {
-    logger.error("Upload Error", err);
+    logger.error("업로드 에러", err);
 
     if (currentSavePath != null) {
       await fsx.rm(currentSavePath).catch(() => {});
-      logger.warn(`Incomplete file deleted: ${currentSavePath}`);
+      logger.warn(`불완전한 파일 삭제됨: ${currentSavePath}`);
     }
 
-    reply.code(500).send("Upload Failed");
+    // 이미 저장된 파일 정리
+    for (const savedFile of result) {
+      const savedPath = path.resolve(rootPath, "www", savedFile.path);
+      await fsx.rm(savedPath).catch(() => {});
+      logger.warn(`이미 저장된 파일 삭제됨: ${savedPath}`);
+    }
+
+    reply.code(500).send("업로드 실패");
   }
 }