@simplysm/service-server 13.0.100 → 14.0.4

package/docs/transport.md

@@ -1,58 +1,58 @@
 # Transport
 
+WebSocket and HTTP transport handlers for routing client messages to services.
+
 ## WebSocket Transport
 
-### `WebSocketHandler`
+### WebSocketHandler
 
-WebSocket handler interface. Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
+Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
 
-```typescript
+```ts
 interface WebSocketHandler {
   addSocket(socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest): void;
   closeAll(): void;
-  broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>;
-  emit<TInfo, TData>(
-    eventDef: ServiceEventDef<TInfo, TData>,
-    infoSelector: (item: TInfo) => boolean,
-    data: TData,
-  ): Promise<void>;
+  emit<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>;
 }
 ```
 
-| Method | Description |
-|--------|-------------|
-| `addSocket()` | Add a new WebSocket connection |
-| `closeAll()` | Close all active connections |
-| `broadcastReload()` | Broadcast reload message to all clients |
-| `emit()` | Emit event to matching clients |
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `addSocket` | `socket: WebSocket`, `clientId: string`, `clientName: string`, `connReq: FastifyRequest` | `void` | Register a new WebSocket connection |
+| `closeAll` | -- | `void` | Close all managed connections |
+| `emit` | `eventDef`, `infoSelector`, `data` | `Promise<void>` | Broadcast an event to matching listeners across all sockets |
 
-### `createWebSocketHandler`
+### createWebSocketHandler
 
-Create a WebSocket handler instance.
+Create a `WebSocketHandler` instance.
 
-```typescript
+```ts
 function createWebSocketHandler(
   runMethod: (def: {
     serviceName: string;
     methodName: string;
     params: unknown[];
-    socket: ServiceSocket;
+    socket?: ServiceSocket;
   }) => Promise<unknown>,
-  jwtSecret?: string,
+  jwtSecret: string | undefined,
 ): WebSocketHandler;
 ```
 
-### `ServiceSocket`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runMethod` | `(def) => Promise<unknown>` | Callback to execute a service method |
+| `jwtSecret` | `string \| undefined` | JWT secret for authenticating socket connections. `undefined` disables auth. |
+
+### ServiceSocket
 
-Service socket interface. Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
+Represents a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
 
-```typescript
+```ts
 interface ServiceSocket {
   readonly connectedAtDateTime: DateTime;
   readonly clientName: string;
   readonly connReq: FastifyRequest;
   authTokenPayload?: AuthTokenPayload;
-
   close(): void;
   send(uuid: string, msg: ServiceServerMessage): Promise<number>;
   addListener(key: string, eventName: string, info: unknown): void;
@@ -65,28 +65,27 @@ interface ServiceSocket {
 }
 ```
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `connectedAtDateTime` | `DateTime` | Connection time |
-| `clientName` | `string` | Client name |
-| `connReq` | `FastifyRequest` | Original Fastify request |
-| `authTokenPayload` | `AuthTokenPayload` | Authenticated token payload |
-
-| Method | Description |
-|--------|-------------|
-| `close()` | Close the WebSocket connection |
-| `send()` | Send a message to the client |
-| `addListener()` | Register an event listener |
-| `removeListener()` | Remove an event listener |
-| `getEventListeners()` | Get all listeners for an event name |
-| `filterEventTargetKeys()` | Filter target keys that exist in this socket |
-| `on()` | Register event handlers (error, close, message) |
-
-### `createServiceSocket`
-
-Create a service socket instance.
-
-```typescript
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connectedAtDateTime` | property | `DateTime` | Connection timestamp |
+| `clientName` | property | `string` | Client identifier |
+| `connReq` | property | `FastifyRequest` | Original Fastify request |
+| `authTokenPayload` | property | `AuthTokenPayload?` | Authenticated token payload (set after auth message) |
+| `close` | method | `() => void` | Close the socket |
+| `send` | method | `(uuid, msg) => Promise<number>` | Send a server message; returns number of bytes sent |
+| `addListener` | method | `(key, eventName, info) => void` | Register an event listener on this socket |
+| `removeListener` | method | `(key) => void` | Remove an event listener by key |
+| `getEventListeners` | method | `(eventName) => Array<{ key; info }>` | Get all listeners for an event name |
+| `filterEventTargetKeys` | method | `(targetKeys) => string[]` | Filter target keys to only those on this socket |
+| `on("error")` | method | `(handler) => void` | Subscribe to error events |
+| `on("close")` | method | `(handler) => void` | Subscribe to close events (with close code) |
+| `on("message")` | method | `(handler) => void` | Subscribe to decoded message events |
+
+### createServiceSocket
+
+Create a `ServiceSocket` instance wrapping a raw WebSocket.
+
+```ts
 function createServiceSocket(
   socket: WebSocket,
   clientId: string,
@@ -95,13 +94,20 @@ function createServiceSocket(
 ): ServiceSocket;
 ```
 
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `WebSocket` | Raw WebSocket instance |
+| `clientId` | `string` | Unique connection identifier |
+| `clientName` | `string` | Client name |
+| `connReq` | `FastifyRequest` | Fastify request that initiated the upgrade |
+
 ## HTTP Transport
 
-### `handleHttpRequest`
+### handleHttpRequest
 
-Handle HTTP API requests. Routes `POST/GET /api/:service/:method` to service methods.
+Handle an HTTP RPC request. Parses the request body, verifies authentication, executes the service method, and sends the response.
 
-```typescript
+```ts
 async function handleHttpRequest<TAuthInfo = unknown>(
   req: FastifyRequest,
   reply: FastifyReply,
@@ -115,11 +121,18 @@ async function handleHttpRequest<TAuthInfo = unknown>(
 ): Promise<void>;
 ```
 
-### `handleUpload`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `req` | `FastifyRequest` | Fastify request |
+| `reply` | `FastifyReply` | Fastify reply |
+| `jwtSecret` | `string \| undefined` | JWT secret. `undefined` disables auth verification. |
+| `runMethod` | `(def) => Promise<unknown>` | Callback to execute the service method |
 
-Handle file upload requests. Accepts multipart form data with auth token.
+### handleUpload
 
-```typescript
+Handle a file upload request. Saves uploaded files to the server's root path and returns upload results.
+
+```ts
 async function handleUpload(
   req: FastifyRequest,
   reply: FastifyReply,
@@ -128,11 +141,18 @@ async function handleUpload(
 ): Promise<void>;
 ```
 
-### `handleStaticFile`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `req` | `FastifyRequest` | Fastify request (multipart) |
+| `reply` | `FastifyReply` | Fastify reply |
+| `rootPath` | `string` | Server root path for file storage |
+| `jwtSecret` | `string \| undefined` | JWT secret for auth verification |
+
+### handleStaticFile
 
-Handle static file serving. Serves files from `www/` directory with security checks (path traversal protection, hidden file blocking).
+Serve a static file from the server's root path.
 
-```typescript
+```ts
 async function handleStaticFile(
   req: FastifyRequest,
   reply: FastifyReply,
@@ -141,24 +161,9 @@ async function handleStaticFile(
 ): Promise<void>;
 ```
 
-## Protocol
-
-### `ServerProtocolWrapper`
-
-Server-side protocol wrapper interface. Automatically offloads heavy encoding/decoding to a worker thread (>30KB threshold).
-
-```typescript
-interface ServerProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-### `createServerProtocolWrapper`
-
-Create a server protocol wrapper instance.
-
-```typescript
-function createServerProtocolWrapper(): ServerProtocolWrapper;
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `req` | `FastifyRequest` | Fastify request |
+| `reply` | `FastifyReply` | Fastify reply |
+| `rootPath` | `string` | Server root directory |
+| `urlPath` | `string` | URL path portion to resolve |

package/docs/types.md

@@ -0,0 +1,31 @@
+# Types
+
+## ServiceServerOptions
+
+Server configuration options passed to `createServiceServer`.
+
+```ts
+interface ServiceServerOptions {
+  rootPath: string;
+  port: number;
+  ssl?: {
+    pfxBytes: Uint8Array;
+    passphrase: string;
+  };
+  auth?: {
+    jwtSecret: string;
+  } | false;
+  services: ServiceDefinition[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rootPath` | `string` | Root directory path for static files and uploads |
+| `port` | `number` | Server listening port |
+| `ssl` | `{ pfxBytes: Uint8Array; passphrase: string }?` | SSL/TLS configuration using a PFX certificate |
+| `ssl.pfxBytes` | `Uint8Array` | PFX certificate bytes |
+| `ssl.passphrase` | `string` | PFX passphrase |
+| `auth` | `{ jwtSecret: string } \| false` | JWT authentication configuration. Set to `false` to disable authentication. |
+| `auth.jwtSecret` | `string` | Secret key for JWT signing and verification |
+| `services` | `ServiceDefinition[]` | Array of service definitions to register |

package/docs/utilities.md

@@ -0,0 +1,27 @@
+# Utilities
+
+## getConfig
+
+Read a configuration section from a JSON file.
+
+```ts
+async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | `string` | Path to the configuration JSON file |
+
+Returns the parsed configuration object typed as `TConfig`, or `undefined` if the file does not exist.
+
+```ts
+import { getConfig } from "@simplysm/service-server";
+
+interface DbConfig {
+  host: string;
+  port: number;
+  database: string;
+}
+
+const dbConfig = await getConfig<DbConfig>("config/db.json");
+```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.100",
-  "description": "Simplysm package - service module (server)",
-  "author": "simplysm",
+  "version": "14.0.4",
+  "description": "심플리즘 패키지 - 서비스 (server)",
+  "author": "심플리즘",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,9 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs",
     "src",
-    "tests"
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -29,18 +28,18 @@
     "@fastify/websocket": "^11.2.0",
     "bufferutil": "^4.1.0",
     "consola": "^3.4.2",
-    "fastify": "^5.8.2",
+    "fastify": "^5.8.4",
     "jose": "^6.2.2",
     "mime": "^4.1.0",
-    "nodemailer": "^8.0.3",
+    "nodemailer": "^8.0.4",
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
-    "ws": "^8.19.0",
-    "@simplysm/core-common": "13.0.100",
-    "@simplysm/core-node": "13.0.100",
-    "@simplysm/orm-common": "13.0.100",
-    "@simplysm/service-common": "13.0.100",
-    "@simplysm/orm-node": "13.0.100"
+    "ws": "^8.20.0",
+    "@simplysm/core-common": "14.0.4",
+    "@simplysm/orm-common": "14.0.4",
+    "@simplysm/orm-node": "14.0.4",
+    "@simplysm/service-common": "14.0.4",
+    "@simplysm/core-node": "14.0.4"
   },
   "devDependencies": {
     "@types/nodemailer": "^7.0.11",

package/src/auth/jwt-manager.ts

@@ -25,9 +25,9 @@ export async function verifyJwt<TAuthInfo = unknown>(
     return payload as AuthTokenPayload<TAuthInfo>;
   } catch (err) {
     if (err != null && typeof err === "object" && "code" in err && err.code === "ERR_JWT_EXPIRED") {
-      throw new Error("Token has expired.");
+      throw new Error("토큰이 만료되었습니다.");
     }
-    throw new Error("Invalid token.");
+    throw new Error("유효하지 않은 토큰입니다.");
   }
 }
 

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);
     }
   });
 }