@simplysm/service-server 13.0.69 → 13.0.70

package/src/service-server.ts

@@ -37,8 +37,8 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
   constructor(readonly options: ServiceServerOptions) {
     super();
 
-    // SSL 설정 (동기)
-    // Note: Fastify HTTPS 설정은 Buffer 타입을 요구함 (Uint8Array 직접 사용 불가)
+    // SSL configuration (synchronous)
+    // Note: Fastify HTTPS requires Buffer type (Uint8Array not directly usable)
     const httpsConf = options.ssl
       ? { pfx: Buffer.from(options.ssl.pfxBytes), passphrase: options.ssl.passphrase }
       : null;
@@ -52,12 +52,12 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
   }
 
   async listen(): Promise<void> {
-    logger.info(`서버 시작... ${env.VER ?? ""}`);
+    logger.info(`Server starting... ${env.VER ?? ""}`);
 
-    // Websocket 플러그인
+    // WebSocket plugin
     await this.fastify.register(fastifyWebsocket);
 
-    // 보안 플러그인
+    // Security plugin
     await this.fastify.register(fastifyHelmet, {
       global: true,
       contentSecurityPolicy: {
@@ -78,17 +78,17 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       originAgentCluster: false,
     });
 
-    // 업로드 플러그인
+    // Upload plugin
     await this.fastify.register(fastifyMultipart);
 
-    // @fastify/static 등록
+    // Register @fastify/static
     await this.fastify.register(fastifyStatic, {
       root: path.resolve(this.options.rootPath, "www"),
       wildcard: false,
       serve: false,
     });
 
-    // CORS 설정
+    // CORS configuration
     await this.fastify.register(fastifyCors, {
       origin: (_origin, cb) => {
         cb(null, true);
@@ -97,7 +97,7 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       exposedHeaders: ["Content-Disposition", "Content-Length"],
     });
 
-    // JSON 파서
+    // JSON parser
     this.fastify.addContentTypeParser(
       "application/json",
       { parseAs: "string" },
@@ -113,22 +113,22 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       },
     );
 
-    // JSON 생성기
+    // JSON serializer
     this.fastify.setSerializerCompiler(() => (data) => jsonStringify(data));
 
-    // API 라우트
+    // API routes
     this.fastify.all("/api/:service/:method", async (req, reply) => {
       await handleHttpRequest(req, reply, this.options.auth?.jwtSecret, (def) =>
         runServiceMethod(this, def),
       );
     });
 
-    // 업로드 라우트
+    // Upload route
     this.fastify.all("/upload", async (req, reply) => {
       await handleUpload(req, reply, this.options.rootPath, this.options.auth?.jwtSecret);
     });
 
-    // WebSocket 라우트
+    // WebSocket route
     const onWebSocketConnected = (socket: WebSocket, req: FastifyRequest) => {
       const { ver, clientId, clientName } = req.query as {
         ver: string | undefined;
@@ -143,7 +143,7 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
         }
         this._wsHandler.addSocket(socket, clientId, clientName, req);
       } else {
-        // V1 레거시 지원 (auto-update만)
+        // V1 legacy support (auto-update only)
         const autoUpdateDef = this.options.services.find((s) => s.name === "AutoUpdate");
         if (autoUpdateDef == null) {
           socket.close(1008, "AutoUpdate service not configured");
@@ -163,7 +163,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 +175,19 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
       },
     });
 
-    // HTTP 서버 수준의 에러 핸들링
+    // HTTP server-level error handling
     this.fastify.server.on("error", (err) => {
-      logger.error("HTTP 서버 오류 발생", err);
+      logger.error("HTTP server error", err);
     });
 
-    // 리슨
+    // Listen
     await this.fastify.listen({ port: this.options.port, host: "0.0.0.0" });
 
-    // Graceful Shutdown 핸들러 등록
+    // Register graceful shutdown handler
     this._registerGracefulShutdown();
 
     this.isOpen = true;
-    logger.info(`서버 시작됨 (port: ${this.options.port})`);
+    logger.info(`Server started (port: ${this.options.port})`);
     this.emit("ready");
   }
 
@@ -196,12 +196,12 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
     await this.fastify.close();
 
     this.isOpen = false;
-    logger.debug("서버 종료됨");
+    logger.debug("Server closed");
     this.emit("close");
   }
 
   async broadcastReload(clientName: string | undefined, changedFileSet: Set<string>) {
-    logger.debug("서버내 모든 클라이언트 RELOAD 명령 전송");
+    logger.debug("Broadcasting RELOAD to all server clients");
     await this._wsHandler.broadcastReload(clientName, changedFileSet);
   }
 
@@ -215,24 +215,24 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
 
   async generateAuthToken(payload: AuthTokenPayload<TAuthInfo>) {
     const jwtSecret = this.options.auth?.jwtSecret;
-    if (jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
+    if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
 
     return signJwt(jwtSecret, payload);
   }
 
   async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>> {
     const jwtSecret = this.options.auth?.jwtSecret;
-    if (jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
+    if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
 
     return verifyJwt(jwtSecret, token);
   }
 
   private _registerGracefulShutdown() {
     const shutdownHandler = async (signal: string) => {
-      logger.info(`${signal} 시그널 감지. 서버 종료 프로세스 시작...`);
+      logger.info(`${signal} signal received. Starting server shutdown...`);
 
       const forceExitTimer = setTimeout(() => {
-        logger.error("서버 종료 시간 초과 (10초). 강제 종료합니다.");
+        logger.error("Server shutdown timed out (10s). Forcing exit.");
         process.exit(1);
       }, 10000);
 
@@ -240,11 +240,11 @@ export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
         if (this.isOpen) {
           await this.close();
         }
-        logger.info("서버가 안전하게 종료되었습니다.");
+        logger.info("Server shut down gracefully.");
         clearTimeout(forceExitTimer);
         process.exit(0);
       } catch (err) {
-        logger.error("서버 종료 중 오류 발생", err);
+        logger.error("Error during server shutdown", 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("클라이언트 경로를 찾을 수 없습니다.");
+    if (clientPath == null) throw new Error("Client path not found.");
 
     if (!(await fsExists(path.resolve(clientPath, platform, "updates")))) return undefined;
 

package/src/services/orm-service.ts

@@ -24,7 +24,7 @@ export const OrmService = defineService(
     const sock = (): ServiceSocket => {
       const socket = ctx.socket;
       if (socket == null) {
-        throw new Error("WebSocket 연결이 필요합니다. HTTP로는 ORM 서비스를 사용할 수 없습니다.");
+        throw new Error("WebSocket connection is required. ORM service cannot be used over HTTP.");
       }
       return socket;
     };
@@ -34,7 +34,7 @@ export const OrmService = defineService(
         opt.configName
       ];
       if (config == null) {
-        throw new Error(`ORM 설정을 찾을 수 없습니다: ${opt.configName}`);
+        throw new Error(`ORM configuration not found: ${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("DB에 연결되어있지 않습니다. (Invalid Connection ID)");
+        throw new Error("Not connected to database. (Invalid Connection ID)");
       }
       return conn;
     };
@@ -71,7 +71,7 @@ export const OrmService = defineService(
           sock().on("close", async () => {
             if (myConns == null) return;
 
-            logger.debug("소켓 연결 종료 감지: 열려있는 모든 DB 연결을 정리합니다.");
+            logger.debug("Socket close detected: cleaning up all open DB connections.");
             const conns = Array.from(myConns.values());
 
             await Promise.all(
@@ -81,7 +81,7 @@ export const OrmService = defineService(
                     await conn.close();
                   }
                 } catch (err) {
-                  logger.warn("DB 연결 강제 종료 중 오류 무시됨", err);
+                  logger.warn("Error ignored during forced DB connection close", err);
                 }
               }),
             );
@@ -110,7 +110,7 @@ export const OrmService = defineService(
           const conn = getConn(connId);
           await conn.close();
         } catch (err) {
-          logger.warn("DB 연결 종료 중 오류 무시됨", err);
+          logger.warn("Error ignored during DB connection close", err);
         }
       },
 

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

@@ -16,16 +16,16 @@ export async function handleHttpRequest<TAuthInfo = unknown>(
 ): Promise<void> {
   const { service, method } = req.params as { service: string; method: string };
 
-  // ClientName 헤더
+  // ClientName header
   const clientName = req.headers["x-sd-client-name"] as string | undefined;
   if (clientName == null) throw new Error("ClientName header is required");
 
-  // Authorization 헤더 파싱 및 검증
+  // Parse and verify Authorization header
   let authTokenPayload: AuthTokenPayload<TAuthInfo> | undefined;
   try {
     const authHeader = req.headers.authorization;
     if (authHeader != null) {
-      if (jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
+      if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
 
       const token = authHeader.split(" ")[1]; // "Bearer <token>"
       authTokenPayload = await verifyJwt<TAuthInfo>(jwtSecret, token);
@@ -38,7 +38,7 @@ export async function handleHttpRequest<TAuthInfo = unknown>(
     return;
   }
 
-  // 파라미터 파싱
+  // Parse parameters
   let params: unknown[] | undefined;
   if (req.method === "GET") {
     const query = req.query as { json?: string };
@@ -58,7 +58,7 @@ export async function handleHttpRequest<TAuthInfo = unknown>(
     params = req.body as unknown[];
   }
 
-  // 서비스 실행 및 응답
+  // 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");
 
-  // targetPath 보안 방어 (Path Traversal 방지)
+  // Security guard for targetPath (prevent path traversal)
   if (targetFilePath !== allowedRootPath && !pathIsChildPath(targetFilePath, allowedRootPath)) {
     throw new Error("Access denied");
   }
 
-  // 디렉토리면 trailing slash 리다이렉트 (표준 웹 서버 동작)
+  // Redirect with trailing slash for directories (standard web server behavior)
   if ((await fsExists(targetFilePath)) && (await fsStat(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 = "파일을 사용할 권한이 없습니다.";
+    const errorMessage = "You do not have permission to access this file.";
     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 = "파일을 찾을 수 없습니다.";
+      const errorMessage = "File not found.";
       responseErrorHtml(reply, 404, errorMessage);
       logger.warn(`[404] ${errorMessage} (${targetFilePath})`);
     } else {
-      const errorMessage = "파일 전송 중 오류가 발생했습니다.";
+      const errorMessage = "An error occurred while sending the file.";
       responseErrorHtml(reply, 500, errorMessage);
       logger.error(`[500] ${errorMessage}`, err);
     }

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

@@ -21,14 +21,14 @@ export async function handleUpload(
     return;
   }
 
-  // 인증 검사
+  // Auth check
   try {
     const authHeader = req.headers.authorization;
     if (authHeader == null) {
-      throw new Error("인증 토큰이 없습니다.");
+      throw new Error("Authentication token is missing.");
     }
     if (jwtSecret == null) {
-      throw new Error("JWT Secret이 정의되지 않았습니다.");
+      throw new Error("JWT Secret is not defined.");
     }
     const token = authHeader.split(" ")[1];
     await verifyJwt(jwtSecret, token);

package/src/transport/socket/service-socket.ts

@@ -80,7 +80,7 @@ export function createServiceSocket(
   // State
   // -------------------------------------------------------------------
 
-  const PING_INTERVAL = 5000; // 5초마다 핑 전송
+  const PING_INTERVAL = 5000; // Send ping every 5s
   const PONG_PACKET = new Uint8Array([0x02]);
 
   const protocol = createProtocolWrapper();
@@ -125,7 +125,7 @@ export function createServiceSocket(
   // -------------------------------------------------------------------
 
   function onError(err: Error): void {
-    logger.error("WebSocket 클라이언트 오류 발생", err);
+    logger.error("WebSocket client error", err);
     emitEvent("error", err);
   }
 
@@ -137,7 +137,7 @@ export function createServiceSocket(
 
   async function onMessage(msgBuffer: Bytes): Promise<void> {
     try {
-      // ping에 대한 pong처리
+      // Handle pong response to ping
       if (msgBuffer.length === 1 && msgBuffer[0] === 0x01) {
         if (socket.readyState === WebSocket.OPEN) {
           socket.send(PONG_PACKET);
@@ -159,7 +159,7 @@ export function createServiceSocket(
         emitEvent("message", { uuid: decodeResult.uuid, msg });
       }
     } catch (err) {
-      logger.error("WebSocket 메시지 처리 중 오류 발생", err);
+      logger.error("Error processing WebSocket message", err);
     }
   }
 

package/src/transport/socket/websocket-handler.ts

@@ -114,13 +114,13 @@ export function createWebSocketHandler(
 
         return await serviceSocket.send(uuid, { name: "response" });
       } else if (message.name === "auth") {
-        if (jwtSecret == null) throw new Error("JWT Secret이 정의되지 않았습니다.");
+        if (jwtSecret == null) throw new Error("JWT Secret is not defined.");
 
         const token = message.body;
         serviceSocket.authTokenPayload = await verifyJwt(jwtSecret, token);
         return await serviceSocket.send(uuid, { name: "response" });
       } else {
-        const err = new Error("요청이 잘못되었습니다.");
+        const err = new Error("Invalid request.");
 
         return await serviceSocket.send(uuid, {
           name: "error",
@@ -136,7 +136,7 @@ export function createWebSocketHandler(
       const error =
         err instanceof Error
           ? err
-          : new Error(typeof err === "string" ? err : "알 수 없는 오류가 발생하였습니다.");
+          : new Error(typeof err === "string" ? err : "An unknown error has occurred.");
 
       return serviceSocket.send(uuid, {
         name: "error",
@@ -164,38 +164,40 @@ export function createWebSocketHandler(
       try {
         const serviceSocket = createServiceSocket(socket, clientId, clientName, connReq);
 
-        // 기존 연결 끊기
+        // Disconnect existing connection
         const prevServiceSocket = socketMap.get(clientId);
         if (prevServiceSocket != null) {
           prevServiceSocket.close();
 
           const connectionDateTimeText =
             prevServiceSocket.connectedAtDateTime.toFormatString("yyyy:MM:dd HH:mm:ss.fff");
-          logger.debug(`클라이언트 기존연결 끊음: ${clientId}: ${connectionDateTimeText}`);
+          logger.debug(
+            `Disconnected previous client connection: ${clientId}: ${connectionDateTimeText}`,
+          );
         }
 
         socketMap.set(clientId, serviceSocket);
 
         serviceSocket.on("close", (code) => {
-          logger.debug(`클라이언트 연결 끊김: (code: ${code})`);
+          logger.debug(`Client disconnected: (code: ${code})`);
 
           if (socketMap.get(clientId) !== serviceSocket) return;
           socketMap.delete(clientId);
         });
 
         serviceSocket.on("message", async ({ uuid, msg }) => {
-          logger.debug("요청 수신", msg);
+          logger.debug("Request received", msg);
           const sentSize = await processRequest(serviceSocket, uuid, msg);
-          logger.debug(`응답 전송 (size: ${sentSize})`);
+          logger.debug(`Response sent (size: ${sentSize})`);
         });
 
-        logger.debug("클라이언트 연결됨", {
+        logger.debug("Client connected", {
           clientId,
           remoteAddress: connReq.socket.remoteAddress,
           socketSize: socketMap.size,
         });
       } catch (err) {
-        logger.error("연결 처리 중 오류 발생", err);
+        logger.error("Error handling connection", err);
         socket.terminate();
       }
     },

package/src/utils/config-manager.ts

@@ -5,12 +5,12 @@ import consola from "consola";
 
 const logger = consola.withTag("service-server:ConfigManager");
 
-// 값: Config 객체, 키: 파일 경로
+// Value: Config object, Key: file path
 const _cache = new LazyGcMap<string, unknown>({
-  gcInterval: 10 * 60 * 1000, // 10분마다
-  expireTime: 60 * 60 * 1000, // 1시간 만료
+  gcInterval: 10 * 60 * 1000, // Every 10 minutes
+  expireTime: 60 * 60 * 1000, // Expire after 1 hour
   onExpire: async (filePath) => {
-    logger.debug(`설정 캐시 만료 및 감시 해제: ${path.basename(filePath)}`);
+    logger.debug(`Config cache expired and watcher released: ${path.basename(filePath)}`);
     await closeWatcher(filePath);
   },
 });
@@ -18,18 +18,18 @@ const _cache = new LazyGcMap<string, unknown>({
 const _watchers = new Map<string, FsWatcher>();
 
 export async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined> {
-  // 1. 캐시 적중 (시간 자동 갱신)
+  // 1. Cache hit (time auto-renewed)
   if (_cache.has(filePath)) {
     return _cache.get(filePath) as TConfig;
   }
 
   if (!(await fsExists(filePath))) return undefined;
 
-  // 2. 로드 및 캐시
+  // 2. Load and cache
   const config = await fsReadJson(filePath);
   _cache.set(filePath, config);
 
-  // 3. Watcher 등록
+  // 3. Register watcher
   if (!_watchers.has(filePath)) {
     try {
       const watcher = await FsWatcher.watch([filePath]);
@@ -39,20 +39,20 @@ export async function getConfig<TConfig>(filePath: string): Promise<TConfig | un
         if (!(await fsExists(filePath))) {
           _cache.delete(filePath);
           await closeWatcher(filePath);
-          logger.debug(`설정 파일 삭제됨: ${path.basename(filePath)}`);
+          logger.debug(`Config file deleted: ${path.basename(filePath)}`);
           return;
         }
 
         try {
           const newConfig = await fsReadJson(filePath);
           _cache.set(filePath, newConfig);
-          logger.debug(`설정 파일 실시간 갱신: ${path.basename(filePath)}`);
+          logger.debug(`Config file live-reloaded: ${path.basename(filePath)}`);
         } catch (err) {
-          logger.warn(`설정 파일 갱신 실패: ${filePath}`, err);
+          logger.warn(`Config file reload failed: ${filePath}`, err);
         }
       });
     } catch (err) {
-      logger.error(`감시 실패: ${filePath}`, err);
+      logger.error(`Watch failed: ${filePath}`, err);
     }
   }
 

package/tests/define-service.spec.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import { defineService, auth, getServiceAuthPermissions } from "@simplysm/service-server";
+
+describe("defineService", () => {
+  it("creates service definition with name and factory", () => {
+    const svc = defineService("Health", (_ctx) => ({
+      check: () => "ok",
+    }));
+
+    expect(svc.name).toBe("Health");
+    expect(typeof svc.factory).toBe("function");
+  });
+
+  it("factory generates methods when called with context", () => {
+    const svc = defineService("Echo", (_ctx) => ({
+      echo: (msg: string) => `Echo: ${msg}`,
+    }));
+
+    const methods = svc.factory({} as any);
+    expect(methods.echo("hello")).toBe("Echo: hello");
+  });
+});
+
+describe("Authentication", () => {
+  it("marks function with empty permissions (login required only)", () => {
+    const fn = auth(() => "result");
+    expect(getServiceAuthPermissions(fn)).toEqual([]);
+    expect(fn()).toBe("result");
+  });
+
+  it("marks function with specific permissions", () => {
+    const fn = auth(["admin"], (id: number) => id * 2);
+    expect(getServiceAuthPermissions(fn)).toEqual(["admin"]);
+    expect(fn(5)).toBe(10);
+  });
+
+  it("returns undefined for unmarked function", () => {
+    const fn = () => "plain";
+    expect(getServiceAuthPermissions(fn)).toBeUndefined();
+  });
+
+  it("works at service level (factory wrapping)", () => {
+    const svc = defineService(
+      "User",
+      auth((_ctx) => ({
+        getProfile: () => "profile",
+      })),
+    );
+
+    expect(svc.authPermissions).toEqual([]);
+  });
+
+  it("works at service-level with roles", () => {
+    const svc = defineService(
+      "Admin",
+      auth(["admin"], (_ctx) => ({
+        manage: () => "managed",
+      })),
+    );
+
+    expect(svc.authPermissions).toEqual(["admin"]);
+  });
+
+  it("service without auth has no authPermissions", () => {
+    const svc = defineService("Public", (_ctx) => ({
+      open: () => "open",
+    }));
+
+    expect(svc.authPermissions).toBeUndefined();
+  });
+
+  it("method-level auth is readable from returned methods", () => {
+    const svc = defineService(
+      "Mixed",
+      auth((_ctx) => ({
+        normal: () => "normal",
+        adminOnly: auth(["admin"], () => "admin"),
+      })),
+    );
+
+    const methods = svc.factory({} as any);
+    expect(getServiceAuthPermissions(methods.normal)).toBeUndefined();
+    expect(getServiceAuthPermissions(methods.adminOnly)).toEqual(["admin"]);
+  });
+});