@simplysm/service-server 13.0.85 → 13.0.86

package/README.md

@@ -1,40 +1,294 @@
 # @simplysm/service-server
 
-Fastify-based service server framework with WebSocket support, JWT authentication, service routing, file uploads, and built-in ORM/SMTP/auto-update services.
+Fastify 기반 서비스 서버. WebSocket RPC, HTTP API, JWT 인증, 이벤트 브로드캐스트, 파일 업로드, 정적 파일 서빙을 제공한다.
 
-## Installation
+## 설치
 
 ```bash
 npm install @simplysm/service-server
 ```
 
-## Quick Start
+**주요 의존성:** `fastify`, `@fastify/cors`, `@fastify/websocket`, `@fastify/static`, `@fastify/multipart`, `@fastify/helmet`, `jose`, `nodemailer`, `ws`
 
-```typescript
-import { createServiceServer, defineService } from "@simplysm/service-server";
+**내부 의존성:** `@simplysm/core-common`, `@simplysm/core-node`, `@simplysm/orm-common`, `@simplysm/orm-node`, `@simplysm/service-common`
 
-const HealthService = defineService("Health", (ctx) => ({
-  check: () => ({ status: "ok" }),
-}));
+## 서버 생성 및 실행
+
+```typescript
+import { createServiceServer, defineService, auth } from "@simplysm/service-server";
 
 const server = createServiceServer({
-  rootPath: process.cwd(),
+  rootPath: "/app",
   port: 3000,
-  services: [HealthService],
+  ssl: { pfxBytes, passphrase: "cert-pass" },  // 선택
+  auth: { jwtSecret: "my-secret" },             // 선택
+  services: [UserService, OrmService],
 });
 
 await server.listen();
+// ... 종료 시
+await server.close();
+```
+
+### ServiceServerOptions
+
+```typescript
+interface ServiceServerOptions {
+  rootPath: string;           // 루트 경로 (www/, .config.json 기준)
+  port: number;               // 리스닝 포트
+  ssl?: {                     // HTTPS 설정 (선택)
+    pfxBytes: Uint8Array;
+    passphrase: string;
+  };
+  auth?: {                    // JWT 인증 설정 (선택)
+    jwtSecret: string;
+  };
+  services: ServiceDefinition[];  // 등록할 서비스 목록
+}
+```
+
+## 서비스 정의
+
+`defineService`로 서비스를 정의하고, `auth`로 인증을 요구한다.
+
+```typescript
+import { defineService, auth } from "@simplysm/service-server";
+import type { ServiceContext, ServiceMethods } from "@simplysm/service-server";
+
+// 기본 서비스 (인증 불필요)
+const UserService = defineService("User", (ctx: ServiceContext) => ({
+  async findAll() {
+    return [{ id: 1, name: "Alice" }];
+  },
+  async findById(id: number) {
+    return { id, name: "Alice" };
+  },
+}));
+
+// 서비스 전체에 인증 필수
+const AdminService = defineService("Admin", auth((ctx) => ({
+  async getStats() {
+    const authInfo = ctx.authInfo; // 인증 정보 접근
+    return { users: 100 };
+  },
+})));
+
+// 서비스 전체에 역할 기반 인증
+const SecureService = defineService("Secure", auth(["admin", "manager"], (ctx) => ({
+  async deleteUser(id: number) { /* ... */ },
+})));
+
+// 메서드 단위 인증 (서비스 레벨은 공개, 특정 메서드만 인증)
+const MixedService = defineService("Mixed", (ctx) => ({
+  async publicMethod() { /* 누구나 호출 가능 */ },
+  adminOnly: auth(["admin"], async () => { /* admin만 호출 가능 */ }),
+}));
+
+// 클라이언트 타입 공유용
+export type UserServiceType = ServiceMethods<typeof UserService>;
+```
+
+### auth 래퍼
+
+`auth` 함수는 서비스 팩토리 또는 개별 메서드에 적용할 수 있다.
+
+```typescript
+// 서비스 레벨: 모든 메서드에 로그인 필수
+auth((ctx) => ({ ... }))
+
+// 서비스 레벨: 특정 역할 필수
+auth(["admin"], (ctx) => ({ ... }))
+
+// 메서드 레벨: 해당 메서드만 로그인 필수
+auth(() => result)
+
+// 메서드 레벨: 해당 메서드만 특정 역할 필수
+auth(["admin"], () => result)
+```
+
+인증 검사 우선순위: 메서드 레벨 > 서비스 레벨. 메서드에 `auth`가 있으면 서비스 레벨 설정을 무시한다.
+
+## ServiceContext
+
+서비스 메서드에 주입되는 컨텍스트 객체.
+
+```typescript
+interface ServiceContext<TAuthInfo = unknown> {
+  server: ServiceServer<TAuthInfo>;      // 서버 인스턴스
+  socket?: ServiceSocket;               // WebSocket 연결 (소켓 호출 시)
+  http?: {                              // HTTP 요청 (HTTP 호출 시)
+    clientName: string;
+    authTokenPayload?: AuthTokenPayload<TAuthInfo>;
+  };
+
+  get authInfo(): TAuthInfo | undefined;     // 인증 데이터 (socket 또는 http에서 추출)
+  get clientName(): string | undefined;      // 클라이언트 이름
+  get clientPath(): string | undefined;      // rootPath/www/{clientName} 경로
+  getConfig<T>(section: string): Promise<T>; // .config.json에서 설정 읽기
+}
+```
+
+`getConfig`는 `rootPath/.config.json`을 기본으로 읽고, `clientPath/.config.json`이 있으면 머지한다.
+
+## JWT 인증
+
+`jose` 라이브러리 기반. HS256 알고리즘, 토큰 유효기간 12시간.
+
+```typescript
+// 토큰 발행
+const token = await server.signAuthToken({
+  roles: ["admin"],
+  data: { userId: 1, name: "Alice" },
+});
+
+// 토큰 검증
+const payload = await server.verifyAuthToken(token);
+// { roles: ["admin"], data: { userId: 1, name: "Alice" } }
+```
+
+### AuthTokenPayload
+
+```typescript
+interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
+  roles: string[];    // 역할 목록 (권한 검사용)
+  data: TAuthInfo;    // 사용자 정의 인증 데이터
+}
+```
+
+### JWT 유틸리티 함수
+
+서버 인스턴스 없이 직접 사용할 수 있는 저수준 함수.
+
+```typescript
+import { signJwt, verifyJwt, decodeJwt } from "@simplysm/service-server";
+
+const token = await signJwt("secret", { roles: ["user"], data: { id: 1 } });
+const payload = await verifyJwt("secret", token);   // 검증 + 디코드 (만료 시 에러)
+const decoded = decodeJwt(token);                    // 검증 없이 디코드
 ```
 
-## Documentation
+## 이벤트 브로드캐스트
+
+WebSocket으로 연결된 클라이언트에게 이벤트를 전송한다.
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
+
+const OrderCreated = defineEvent<{ shopId: string }, { orderId: string; amount: number }>(
+  "order-created"
+);
+
+// 조건에 맞는 구독자에게 이벤트 전송
+await server.emitEvent(
+  OrderCreated,
+  (info) => info.shopId === "shop-1",
+  { orderId: "order-123", amount: 50000 }
+);
+
+// 클라이언트 리로드 알림 (개발 모드용)
+await server.broadcastReload("my-app", new Set(["file1.ts", "file2.ts"]));
+```
+
+## HTTP API
+
+자동으로 등록되는 HTTP 엔드포인트:
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/:service/:method?json=...` | 서비스 호출 (params: JSON 인코딩 배열) |
+| POST | `/api/:service/:method` | 서비스 호출 (params: body 배열) |
+| POST | `/upload` | 파일 업로드 (multipart, 인증 필수) |
+| GET | `/...` | 정적 파일 서빙 (`rootPath/www/`) |
+
+### HTTP 헤더
+
+- `x-sd-client-name` (필수): 클라이언트 이름
+- `Authorization: Bearer <token>` (선택): JWT 인증 토큰
+
+### 파일 업로드
+
+인증 필수. multipart/form-data로 전송. 파일은 `rootPath/www/uploads/`에 UUID 이름으로 저장된다.
+
+```typescript
+// 응답 타입
+interface ServiceUploadResult {
+  path: string;       // "uploads/{uuid}.ext"
+  filename: string;   // 원본 파일명
+  size: number;       // 바이트 크기
+}
+```
+
+## 내장 서비스
+
+상세 API는 [docs/builtin-services.md](docs/builtin-services.md) 참조.
+
+### OrmService
+
+인증 필수. WebSocket 전용. 소켓별 DB 커넥션 풀을 관리한다. 소켓 종료 시 자동 정리.
+
+```typescript
+import { OrmService } from "@simplysm/service-server";
+
+const server = createServiceServer({
+  services: [OrmService],
+  // ...
+});
+```
+
+`.config.json`에 DB 설정 필요:
+
+```json
+{
+  "orm": {
+    "main": {
+      "dialect": "mysql",
+      "host": "localhost",
+      "port": 3306,
+      "username": "root",
+      "password": "password"
+    }
+  }
+}
+```
+
+### AutoUpdateService
+
+`clientPath/{platform}/updates/` 디렉토리에서 최신 버전을 탐색한다. `.apk`(Android), `.exe`(Windows) 지원. V1 레거시 클라이언트 호환.
+
+```typescript
+import { AutoUpdateService } from "@simplysm/service-server";
+```
+
+### SmtpClientService
+
+nodemailer 기반 이메일 전송 서비스. 직접 설정 또는 `.config.json` 기반 전송을 지원한다.
+
+```typescript
+import { SmtpClientService } from "@simplysm/service-server";
+```
+
+## 설정 파일
+
+`rootPath/.config.json`에서 설정을 읽는다. LRU 캐시(1시간 만료, 10분 GC 주기)와 파일 감시로 자동 리로드된다.
+
+```typescript
+const dbConfig = await ctx.getConfig<DbConfig>("orm.main");
+```
+
+클라이언트별 설정이 있으면 (`rootPath/www/{clientName}/.config.json`) 루트 설정에 머지된다.
+
+## 서버 이벤트
+
+```typescript
+server.on("ready", () => { /* 서버 시작 완료 */ });
+server.on("close", () => { /* 서버 종료 완료 */ });
+```
+
+## Graceful Shutdown
+
+SIGINT/SIGTERM 시그널 수신 시 자동으로 graceful shutdown을 수행한다. 10초 타임아웃 후 강제 종료.
+
+## 상세 API 레퍼런스
 
-| Category | File | Description |
-|----------|------|-------------|
-| Server | [docs/server.md](docs/server.md) | `ServiceServer` class and `createServiceServer` factory |
-| Service Definition | [docs/service-definition.md](docs/service-definition.md) | `defineService`, `auth`, `ServiceContext`, `ServiceMethods` |
-| Authentication | [docs/authentication.md](docs/authentication.md) | JWT management and `AuthTokenPayload` |
-| Transport | [docs/transport.md](docs/transport.md) | WebSocket handler, HTTP request handler, upload handler, static file handler |
-| Protocol | [docs/protocol.md](docs/protocol.md) | `ServerProtocolWrapper` with worker thread offloading |
-| Built-in Services | [docs/builtin-services.md](docs/builtin-services.md) | `OrmService`, `AutoUpdateService`, `SmtpClientService` |
-| Utilities | [docs/utilities.md](docs/utilities.md) | `getConfig` with file watching and caching |
-| Legacy | [docs/legacy.md](docs/legacy.md) | V1 auto-update handler for backward compatibility |
+- [내장 서비스 상세](docs/builtin-services.md) -- OrmService, AutoUpdateService, SmtpClientService 메서드 시그니처
+- [전송 계층 및 프로토콜](docs/transport-protocol.md) -- WebSocket 핸들러, ServiceSocket, 프로토콜 래퍼

package/docs/builtin-services.md

@@ -1,91 +1,192 @@
-# Built-in Services
+# 내장 서비스 상세 API
 
-Pre-built service definitions ready to include in `ServiceServerOptions.services`.
+## OrmService
 
-## `OrmService`
+서비스 이름: `"Orm"`. 인증 필수 (`auth` 래핑). WebSocket 전용 -- HTTP로는 사용 불가.
 
-Database operations service using `@simplysm/orm-node`. Requires authentication (service-level `auth` wrapper). **WebSocket only** -- cannot be used over HTTP.
+소켓별로 DB 커넥션을 `WeakMap<ServiceSocket, Map<number, DbConn>>`으로 관리한다. 소켓 `close` 이벤트 시 해당 소켓의 모든 커넥션을 자동 정리한다.
 
-Manages database connections per WebSocket socket. Connections are automatically cleaned up when the socket closes.
+### 메서드
 
-### Methods
+```typescript
+// DB 정보 조회 (연결 없이)
+async getInfo(opt: DbConnOptions & { configName: string }): Promise<{
+  dialect: Dialect;        // "mysql" | "postgresql" | "mssql" (mssql-azure는 mssql로 반환)
+  database?: string;
+  schema?: string;
+}>
+
+// DB 연결 생성 (connId 반환)
+async connect(opt: DbConnOptions & { configName: string }): Promise<number>
+
+// DB 연결 종료
+async close(connId: number): Promise<void>
+
+// 트랜잭션 제어
+async beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>
+async commitTransaction(connId: number): Promise<void>
+async rollbackTransaction(connId: number): Promise<void>
+
+// 파라미터화된 쿼리 실행
+async executeParametrized(
+  connId: number,
+  query: string,
+  params?: unknown[],
+): Promise<unknown[][]>
+
+// QueryDef 기반 쿼리 실행 (쿼리 빌더 사용)
+async executeDefs(
+  connId: number,
+  defs: QueryDef[],
+  options?: (ResultMeta | undefined)[],
+): Promise<unknown[][]>
+
+// 벌크 인서트
+async bulkInsert(
+  connId: number,
+  tableName: string,
+  columnDefs: Record<string, ColumnMeta>,
+  records: Record<string, unknown>[],
+): Promise<void>
+```
+
+### DbConnOptions
 
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `getInfo` | `opt: DbConnOptions & { configName }` | `{ dialect, database?, schema? }` | Get database connection info from config |
-| `connect` | `opt: DbConnOptions & { configName }` | `number` (connId) | Open a database connection |
-| `close` | `connId: number` | `void` | Close a database connection |
-| `beginTransaction` | `connId, isolationLevel?` | `void` | Begin a transaction |
-| `commitTransaction` | `connId` | `void` | Commit the current transaction |
-| `rollbackTransaction` | `connId` | `void` | Rollback the current transaction |
-| `executeParametrized` | `connId, query, params?` | `unknown[][]` | Execute a parameterized query |
-| `executeDefs` | `connId, defs, options?` | `unknown[][]` | Execute query definitions with optional result parsing |
-| `bulkInsert` | `connId, tableName, columnDefs, records` | `void` | Perform bulk insert |
+`@simplysm/service-common`에서 가져온다.
 
-### Configuration
+```typescript
+type DbConnOptions = {
+  configName?: string;
+  config?: Record<string, unknown>;  // .config.json 설정 오버라이드
+};
+```
 
-Reads from the `"orm"` config section via `ctx.getConfig("orm")`. Config file (`.config.json`) example:
+### 설정 예시
+
+`.config.json`:
 
 ```json
 {
   "orm": {
-    "default": {
+    "main": {
       "dialect": "mysql",
       "host": "localhost",
       "port": 3306,
       "username": "root",
       "password": "password",
       "database": "mydb"
+    },
+    "secondary": {
+      "dialect": "postgresql",
+      "host": "pg-host",
+      "port": 5432,
+      "username": "admin",
+      "password": "password",
+      "database": "mydb",
+      "schema": "public"
     }
   }
 }
 ```
 
-### Type export
+### 타입 내보내기
 
 ```typescript
-export type OrmServiceType = ServiceMethods<typeof OrmService>;
+import type { OrmServiceType } from "@simplysm/service-server";
+// 클라이언트에서 타입 공유: client.getService<OrmServiceType>("Orm")
 ```
 
 ---
 
-## `AutoUpdateService`
+## AutoUpdateService
+
+서비스 이름: `"AutoUpdate"`. 인증 불필요. `clientPath/{platform}/updates/` 디렉토리에서 semver 기준 최신 버전 파일을 탐색한다.
 
-Provides app auto-update version checking. Scans `{clientPath}/{platform}/updates/` for versioned files.
+### 메서드
 
-### Methods
+```typescript
+async getLastVersion(platform: string): Promise<{
+  version: string;       // 최신 버전 문자열 (예: "1.2.3")
+  downloadPath: string;  // 다운로드 경로 (예: "/my-app/android/updates/1.2.3.apk")
+} | undefined>
+```
+
+### 지원 플랫폼
+
+| platform | 파일 확장자 | 디렉토리 경로 |
+|----------|------------|---------------|
+| `"android"` | `.apk` | `www/{clientName}/android/updates/` |
+| 기타 | `.exe` | `www/{clientName}/{platform}/updates/` |
+
+파일명은 버전 번호여야 한다 (예: `1.2.3.apk`, `2.0.0.exe`). `semver.maxSatisfying`으로 최신 버전을 결정한다.
 
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `getLastVersion` | `platform: string` | `{ version, downloadPath } \| undefined` | Get the latest version for a platform |
+### V1 레거시 호환
 
-- **Android**: Looks for `.apk` files
-- **Other platforms**: Looks for `.exe` files
-- Version is extracted from the filename (e.g., `1.2.3.apk`)
-- Uses `semver.maxSatisfying` to find the highest version
+V1 프로토콜 클라이언트(WebSocket `ver` 쿼리 파라미터 없음)도 `SdAutoUpdateService.getLastVersion` 명령으로 자동 업데이트를 요청할 수 있다. V1 클라이언트의 다른 요청은 `UPGRADE_REQUIRED` 에러를 반환한다.
 
-### Type export
+### 타입 내보내기
 
 ```typescript
-export type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
+import type { AutoUpdateServiceType } from "@simplysm/service-server";
 ```
 
 ---
 
-## `SmtpClientService`
+## SmtpClientService
 
-Email sending service using `nodemailer`.
+서비스 이름: `"SmtpClient"`. 인증 불필요. nodemailer 기반 이메일 전송.
 
-### Methods
+### 메서드
 
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `send` | `options: SmtpClientSendOption` | `string` (messageId) | Send an email with explicit SMTP settings |
-| `sendByConfig` | `configName, options: SmtpClientSendByDefaultOption` | `string` (messageId) | Send using a named SMTP configuration |
+```typescript
+// 직접 SMTP 설정으로 전송
+async send(options: SmtpClientSendOption): Promise<string>
+// 반환값: messageId
+
+// .config.json의 smtp 설정으로 전송
+async sendByConfig(configName: string, options: SmtpClientSendByDefaultOption): Promise<string>
+// 반환값: messageId
+```
 
-### Configuration
+### SmtpClientSendOption
 
-`sendByConfig` reads from the `"smtp"` config section. Config file (`.config.json`) example:
+`@simplysm/service-common`에서 가져온다.
+
+```typescript
+interface SmtpClientSendOption {
+  host: string;
+  port: number;
+  secure?: boolean;
+  user?: string;
+  pass?: string;
+  from: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  attachments?: Array<{ filename: string; content: Uint8Array }>;
+}
+```
+
+### SmtpClientSendByDefaultOption
+
+```typescript
+interface SmtpClientSendByDefaultOption {
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  attachments?: Array<{ filename: string; content: Uint8Array }>;
+}
+```
+
+### 설정 예시
+
+`.config.json`:
 
 ```json
 {
@@ -94,7 +195,7 @@ Email sending service using `nodemailer`.
       "host": "smtp.example.com",
       "port": 587,
       "secure": false,
-      "user": "user@example.com",
+      "user": "noreply@example.com",
       "pass": "password",
       "senderName": "My App",
       "senderEmail": "noreply@example.com"
@@ -103,28 +204,37 @@ Email sending service using `nodemailer`.
 }
 ```
 
-### Type export
+`senderEmail`이 없으면 `user`가 발신자 이메일로 사용된다.
+
+### 사용 예시
 
 ```typescript
-export type SmtpClientServiceType = ServiceMethods<typeof SmtpClientService>;
-```
+// 서버에서 직접 사용
+const ctx = createServiceContext(server);
+const methods = SmtpClientService.factory(ctx);
+
+// 직접 설정
+await methods.send({
+  host: "smtp.example.com",
+  port: 587,
+  user: "user@example.com",
+  pass: "pass",
+  from: '"My App" <noreply@example.com>',
+  to: "recipient@example.com",
+  subject: "테스트",
+  html: "<p>Hello</p>",
+});
 
----
+// .config.json 기반
+await methods.sendByConfig("default", {
+  to: "recipient@example.com",
+  subject: "테스트",
+  html: "<p>Hello</p>",
+});
+```
 
-## Registering Built-in Services
+### 타입 내보내기
 
 ```typescript
-import {
-  createServiceServer,
-  OrmService,
-  AutoUpdateService,
-  SmtpClientService,
-} from "@simplysm/service-server";
-
-const server = createServiceServer({
-  rootPath: process.cwd(),
-  port: 3000,
-  auth: { jwtSecret: "my-secret" },
-  services: [OrmService, AutoUpdateService, SmtpClientService],
-});
+import type { SmtpClientServiceType } from "@simplysm/service-server";
 ```

package/docs/transport-protocol.md

@@ -0,0 +1,200 @@
+# 전송 계층 및 프로토콜
+
+## WebSocket 전송
+
+### WebSocketHandler
+
+다수의 WebSocket 연결을 관리하고, 메시지를 서비스로 라우팅하며, 이벤트 브로드캐스트를 처리한다.
+
+```typescript
+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>;
+}
+
+function createWebSocketHandler(
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+  }) => Promise<unknown>,
+  jwtSecret: string | undefined,
+): WebSocketHandler;
+```
+
+### WebSocket 연결 흐름
+
+1. 클라이언트가 `/` 또는 `/ws`로 WebSocket 연결
+2. 쿼리 파라미터로 프로토콜 버전 구분:
+   - `ver=2&clientId=...&clientName=...` -- V2 프로토콜 (현재)
+   - 쿼리 없음 -- V1 레거시 (AutoUpdate만 지원)
+3. V2: `createServiceSocket`으로 소켓 래핑, 메시지 라우팅 시작
+4. 같은 `clientId`로 재연결 시 이전 소켓을 종료하고 새 소켓으로 교체
+
+### WebSocket 메시지 프로토콜
+
+V2 클라이언트 메시지 포맷 (`ServiceClientMessage`):
+
+| `name` | `body` | 설명 |
+|--------|--------|------|
+| `"{Service}.{Method}"` | `unknown[]` (파라미터 배열) | 서비스 메서드 호출 |
+| `"auth"` | `string` (JWT 토큰) | 인증 토큰 설정 |
+| `"evt:add"` | `{ key, name, info }` | 이벤트 리스너 등록 |
+| `"evt:remove"` | `{ key }` | 이벤트 리스너 제거 |
+| `"evt:gets"` | `{ name }` | 이벤트 리스너 목록 조회 |
+| `"evt:emit"` | `{ keys, data }` | 대상 키에 이벤트 전송 |
+
+V2 서버 응답 (`ServiceServerMessage`):
+
+| `name` | `body` | 설명 |
+|--------|--------|------|
+| `"response"` | `unknown` (결과) | 성공 응답 |
+| `"error"` | `{ name, message, code, stack }` | 에러 응답 |
+| `"progress"` | `{ totalSize, completedSize }` | 전송 진행률 |
+| `"evt:on"` | `{ keys, data }` | 이벤트 수신 |
+| `"reload"` | `{ clientName, changedFileSet }` | 리로드 알림 |
+
+---
+
+### ServiceSocket
+
+단일 WebSocket 연결을 관리하는 인터페이스. 프로토콜 인코딩/디코딩, ping/pong keep-alive(5초 간격), 이벤트 리스너 추적을 담당한다.
+
+```typescript
+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;
+  removeListener(key: string): void;
+  getEventListeners(eventName: string): Array<{ key: string; info: unknown }>;
+  filterEventTargetKeys(targetKeys: string[]): string[];
+
+  // 이벤트 핸들러 등록
+  on(event: "error", handler: (err: Error) => void): void;
+  on(event: "close", handler: (code: number) => void): void;
+  on(event: "message", handler: (data: { uuid: string; msg: ServiceClientMessage }) => void): void;
+}
+
+function createServiceSocket(
+  socket: WebSocket,
+  clientId: string,
+  clientName: string,
+  connReq: FastifyRequest,
+): ServiceSocket;
+```
+
+---
+
+## HTTP 전송
+
+### handleHttpRequest
+
+HTTP API 요청 처리 함수. 서버 내부에서 `/api/:service/:method` 라우트에 등록된다.
+
+```typescript
+async function handleHttpRequest<TAuthInfo>(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  jwtSecret: string | undefined,
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    http: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> };
+  }) => Promise<unknown>,
+): Promise<void>;
+```
+
+- GET: `?json=` 쿼리 파라미터에서 파라미터 배열을 JSON 파싱
+- POST: request body를 배열로 파싱
+- `x-sd-client-name` 헤더 필수
+- `Authorization: Bearer <token>` 헤더가 있으면 JWT 검증 후 `authTokenPayload`로 전달
+
+### handleUpload
+
+파일 업로드 처리 함수. `/upload` 라우트에 등록된다. 인증 필수.
+
+```typescript
+async function handleUpload(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  jwtSecret: string | undefined,
+): Promise<void>;
+```
+
+- multipart/form-data 필수
+- 파일을 `rootPath/www/uploads/{UUID}.{ext}`로 저장
+- 업로드 실패 시 불완전한 파일 자동 삭제
+- 응답: `ServiceUploadResult[]`
+
+### handleStaticFile
+
+정적 파일 서빙 함수. 와일드카드 라우트 `/*`에 등록된다.
+
+```typescript
+async function handleStaticFile(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  urlPath: string,
+): Promise<void>;
+```
+
+- `rootPath/www/` 디렉토리 기준
+- 디렉토리 접근 시 trailing slash 리다이렉트 + `index.html` 서빙
+- `.`으로 시작하는 파일은 403 거부
+- path traversal 방지 (보안 가드)
+
+---
+
+## 프로토콜 래퍼
+
+메시지 인코딩/디코딩을 자동으로 워커 스레드에 오프로드한다. 30KB 이상의 메시지 또는 `Uint8Array` 포함 메시지는 워커에서 처리하여 메인 스레드 블로킹을 방지한다.
+
+```typescript
+interface ServerProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+
+function createServerProtocolWrapper(): ServerProtocolWrapper;
+```
+
+### 워커 오프로드 조건
+
+- **인코딩**: 메시지 body가 `Uint8Array`이거나, 배열 내에 `Uint8Array` 요소가 있으면 워커 사용
+- **디코딩**: 메시지 크기가 30KB 초과이면 워커 사용
+- 워커는 lazy singleton으로 관리 (최대 4GB 메모리 제한)
+
+---
+
+## 설정 관리
+
+### getConfig
+
+`.config.json` 파일을 읽고 캐시하는 함수.
+
+```typescript
+async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
+```
+
+- LRU 캐시: 1시간 만료, 10분마다 GC
+- 파일 감시(FsWatcher)로 변경 시 자동 리로드
+- 파일 삭제 시 캐시에서 제거 및 감시 해제
+- 캐시 만료 시 감시도 함께 해제

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.85",
+  "version": "13.0.86",
   "description": "Simplysm package - service module (server)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -36,14 +36,14 @@
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.19.0",
-    "@simplysm/orm-common": "13.0.85",
-    "@simplysm/core-common": "13.0.85",
-    "@simplysm/orm-node": "13.0.85",
-    "@simplysm/service-common": "13.0.85",
-    "@simplysm/core-node": "13.0.85"
+    "@simplysm/core-common": "13.0.86",
+    "@simplysm/orm-common": "13.0.86",
+    "@simplysm/service-common": "13.0.86",
+    "@simplysm/core-node": "13.0.86",
+    "@simplysm/orm-node": "13.0.86"
   },
   "devDependencies": {
-    "@types/nodemailer": "^6.4.23",
+    "@types/nodemailer": "^7.0.11",
     "@types/semver": "^7.7.1",
     "@types/ws": "^8.18.1"
   }

package/docs/authentication.md

@@ -1,70 +0,0 @@
-# Authentication
-
-JWT-based authentication using the `jose` library with HS256 algorithm.
-
-## `AuthTokenPayload<TAuthInfo>`
-
-```typescript
-interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
-  roles: string[];    // Role strings for permission checks
-  data: TAuthInfo;    // Custom application-specific auth data
-}
-```
-
----
-
-## `signJwt<TAuthInfo>(jwtSecret, payload): Promise<string>`
-
-Signs a JWT token with HS256 algorithm. Tokens are issued with the current timestamp and expire after 12 hours.
-
-```typescript
-import { signJwt } from "@simplysm/service-server";
-
-const token = await signJwt("my-secret", {
-  roles: ["admin"],
-  data: { userId: 123, name: "John" },
-});
-```
-
----
-
-## `verifyJwt<TAuthInfo>(jwtSecret, token): Promise<AuthTokenPayload<TAuthInfo>>`
-
-Verifies a JWT token and returns the decoded payload. Throws a descriptive error for expired or invalid tokens.
-
-```typescript
-import { verifyJwt } from "@simplysm/service-server";
-
-try {
-  const payload = await verifyJwt("my-secret", token);
-  console.log(payload.roles, payload.data);
-} catch (err) {
-  // "Token has expired." or "Invalid token."
-}
-```
-
----
-
-## `decodeJwt<TAuthInfo>(token): AuthTokenPayload<TAuthInfo>`
-
-Decodes a JWT token **without** verifying its signature. Useful for reading token contents when verification is not needed.
-
-```typescript
-import { decodeJwt } from "@simplysm/service-server";
-
-const payload = decodeJwt(token);
-```
-
----
-
-## Server-level Auth Helpers
-
-`ServiceServer` provides convenience methods that delegate to the JWT functions using the configured `auth.jwtSecret`:
-
-```typescript
-// Sign a token
-const token = await server.signAuthToken({ roles: ["user"], data: myAuthInfo });
-
-// Verify a token
-const payload = await server.verifyAuthToken(token);
-```

package/docs/legacy.md

@@ -1,45 +0,0 @@
-# Legacy
-
-## `handleV1Connection(socket, autoUpdateMethods, clientNameSetter?): void`
-
-Handles V1 legacy WebSocket client connections. Only the `SdAutoUpdateService.getLastVersion` command is supported; all other requests receive an `UPGRADE_REQUIRED` error response.
-
-### Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `WebSocket` | The raw WebSocket connection |
-| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update method implementations |
-| `clientNameSetter` | `(clientName: string \| undefined) => void` | Optional callback to set the legacy client name on the context |
-
-### V1 Protocol
-
-**Request format:**
-```json
-{
-  "uuid": "request-id",
-  "command": "SdAutoUpdateService.getLastVersion",
-  "params": ["android"],
-  "clientName": "my-app"
-}
-```
-
-**Success response:**
-```json
-{
-  "name": "response",
-  "reqUuid": "request-id",
-  "state": "success",
-  "body": { "version": "1.2.3", "downloadPath": "/my-app/android/updates/1.2.3.apk" }
-}
-```
-
-**Upgrade-required response (for unsupported commands):**
-```json
-{
-  "name": "response",
-  "reqUuid": "request-id",
-  "state": "error",
-  "body": { "message": "App upgrade is required.", "code": "UPGRADE_REQUIRED" }
-}
-```

package/docs/protocol.md

@@ -1,34 +0,0 @@
-# Protocol
-
-Message encoding/decoding with automatic worker thread offloading for heavy payloads.
-
-## `ServerProtocolWrapper`
-
-```typescript
-interface ServerProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-## `createServerProtocolWrapper(): ServerProtocolWrapper`
-
-Creates a protocol wrapper instance that automatically delegates heavy operations to a shared worker thread.
-
-### Worker delegation strategy
-
-**Encoding** is offloaded to the worker when:
-- The message body is a `Uint8Array`
-- The message body is an array containing `Uint8Array` elements
-
-**Decoding** is offloaded to the worker when:
-- The incoming bytes exceed 30 KB
-
-Lightweight operations stay on the main thread for lower latency.
-
-### Worker details
-
-- Uses a lazy singleton worker thread shared across all protocol wrappers
-- Worker has a 4 GB memory limit (`maxOldGenerationSizeMb: 4096`)
-- Built on `@simplysm/core-node` `Worker` / `WorkerProxy`

package/docs/server.md

@@ -1,102 +0,0 @@
-# Server
-
-The main server class built on Fastify with WebSocket support, CORS, Helmet security, static file serving, and graceful shutdown.
-
-## `ServiceServer<TAuthInfo>`
-
-**Extends:** `EventEmitter<{ ready: void; close: void }>`
-
-### Constructor
-
-```typescript
-new ServiceServer<TAuthInfo>(options: ServiceServerOptions)
-```
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `isOpen` | `boolean` | Whether the server is currently listening |
-| `fastify` | `FastifyInstance` | The underlying Fastify instance |
-| `options` | `ServiceServerOptions` | The server configuration |
-
-### Methods
-
-#### `listen(): Promise<void>`
-
-Starts the server. Registers all Fastify plugins (WebSocket, Helmet, Multipart, Static, CORS), sets up routes (`/api/:service/:method`, `/upload`, `/ws`, `/*`), and begins listening on the configured port.
-
-Emits the `"ready"` event once listening.
-
-#### `close(): Promise<void>`
-
-Closes all WebSocket connections and shuts down the Fastify server. Emits the `"close"` event.
-
-#### `broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>`
-
-Broadcasts a reload message to all connected WebSocket clients.
-
-#### `emitEvent<TInfo, TData>(eventDef, infoSelector, data): Promise<void>`
-
-Emits a typed event to connected clients matching the `infoSelector` filter.
-
-```typescript
-await server.emitEvent(
-  myEventDef,
-  (info) => info.userId === targetUserId,
-  { message: "hello" },
-);
-```
-
-#### `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>`
-
-Signs a JWT token with the configured secret. Throws if `auth.jwtSecret` is not configured.
-
-#### `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>`
-
-Verifies and decodes a JWT token. Throws if expired or invalid.
-
-### Events
-
-| Event | Description |
-|-------|-------------|
-| `ready` | Emitted after the server starts listening |
-| `close` | Emitted after the server is closed |
-
-### Graceful Shutdown
-
-The server automatically registers `SIGINT` and `SIGTERM` handlers. On signal, it closes all connections and exits. If shutdown exceeds 10 seconds, the process is force-exited.
-
----
-
-## `createServiceServer<TAuthInfo>(options): ServiceServer<TAuthInfo>`
-
-Factory function that creates a new `ServiceServer` instance.
-
----
-
-## `ServiceServerOptions`
-
-```typescript
-interface ServiceServerOptions {
-  rootPath: string;        // Root directory for www/ static files and configs
-  port: number;            // Port to listen on
-  ssl?: {
-    pfxBytes: Uint8Array;  // PFX certificate bytes
-    passphrase: string;    // PFX passphrase
-  };
-  auth?: {
-    jwtSecret: string;     // Secret for JWT signing/verification
-  };
-  services: ServiceDefinition[];  // Array of service definitions
-}
-```
-
-## Routes
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/api/:service/:method` | GET, POST | HTTP service method invocation |
-| `/upload` | POST | Multipart file upload (requires auth) |
-| `/` or `/ws` | WebSocket | WebSocket connection endpoint |
-| `/*` | ALL | Static file serving from `{rootPath}/www/` |

package/docs/service-definition.md

@@ -1,134 +0,0 @@
-# Service Definition
-
-APIs for defining services, applying authentication, and sharing types with clients.
-
-## `defineService<TMethods>(name, factory): ServiceDefinition<TMethods>`
-
-Creates a service definition with a name and a factory function that receives a `ServiceContext` and returns an object of methods.
-
-```typescript
-import { defineService } from "@simplysm/service-server";
-
-const HealthService = defineService("Health", (ctx) => ({
-  check: () => ({ status: "ok" }),
-  getClientName: () => ctx.clientName,
-}));
-```
-
----
-
-## `auth(fn): Function`
-
-Wraps a service factory or individual method to require authentication. Accepts an optional array of role permissions.
-
-### Overloads
-
-```typescript
-// Require login (any authenticated user)
-auth(fn)
-
-// Require specific roles
-auth(["admin", "editor"], fn)
-```
-
-### Service-level auth
-
-All methods in the service require authentication:
-
-```typescript
-const UserService = defineService("User", auth((ctx) => ({
-  getProfile: () => ctx.authInfo,
-  updateProfile: (data: any) => { /* ... */ },
-})));
-```
-
-### Method-level auth
-
-Only specific methods require authentication or specific roles:
-
-```typescript
-const MixedService = defineService("Mixed", (ctx) => ({
-  publicMethod: () => "anyone can call this",
-  protectedMethod: auth(() => "login required"),
-  adminMethod: auth(["admin"], () => "admin only"),
-}));
-```
-
-### Permission resolution
-
-- Method-level auth takes precedence over service-level auth.
-- If `requiredPerms` is an empty array (`auth(fn)`), any authenticated user can access.
-- If `requiredPerms` contains roles (`auth(["admin"], fn)`), the user must have at least one matching role.
-
----
-
-## `ServiceContext<TAuthInfo>`
-
-The context object passed to service factory functions.
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `server` | `ServiceServer<TAuthInfo>` | The server instance |
-| `socket` | `ServiceSocket \| undefined` | WebSocket connection (if called via WebSocket) |
-| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload } \| undefined` | HTTP request info (if called via HTTP) |
-| `legacy` | `{ clientName?: string } \| undefined` | V1 legacy context (auto-update only) |
-
-### Computed Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `authInfo` | `TAuthInfo \| undefined` | The authenticated user's data from the JWT payload |
-| `clientName` | `string \| undefined` | Client application name (validated for path safety) |
-| `clientPath` | `string \| undefined` | Resolved path: `{rootPath}/www/{clientName}` |
-
-### Methods
-
-#### `getConfig<T>(section: string): Promise<T>`
-
-Reads a configuration section from `.config.json` files. Merges root-level config (`{rootPath}/.config.json`) with client-level config (`{clientPath}/.config.json`), where client values override root values.
-
-```typescript
-const dbConfig = await ctx.getConfig<DbSettings>("database");
-```
-
----
-
-## `ServiceDefinition<TMethods>`
-
-```typescript
-interface ServiceDefinition<TMethods> {
-  name: string;
-  factory: (ctx: ServiceContext) => TMethods;
-  authPermissions?: string[];
-}
-```
-
----
-
-## `ServiceMethods<TDefinition>`
-
-Type utility that extracts method signatures from a `ServiceDefinition`. Useful for sharing types with the client.
-
-```typescript
-const UserService = defineService("User", auth((ctx) => ({
-  getProfile: () => ctx.authInfo,
-})));
-
-// Export for client-side usage
-export type UserServiceType = ServiceMethods<typeof UserService>;
-
-// Client side:
-// client.getService<UserServiceType>("User");
-```
-
----
-
-## `executeServiceMethod(server, def): Promise<unknown>`
-
-Internal function that locates and invokes a service method. Performs service lookup, client name validation, context creation, auth checking, and method execution.
-
-## `getServiceAuthPermissions(fn): string[] | undefined`
-
-Reads auth permissions metadata from an `auth()`-wrapped function. Returns `undefined` if the function is not wrapped.

package/docs/transport.md

@@ -1,97 +0,0 @@
-# Transport
-
-Handles communication between clients and the server over WebSocket and HTTP.
-
-## WebSocket
-
-### `WebSocketHandler`
-
-Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
-
-```typescript
-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>;
-}
-```
-
-### `createWebSocketHandler(runMethod, jwtSecret): WebSocketHandler`
-
-Creates a WebSocket handler instance. The `runMethod` callback is invoked to execute service methods.
-
-**Message routing:**
-
-| Message Pattern | Action |
-|----------------|--------|
-| `"ServiceName.methodName"` | Invoke service method |
-| `"evt:add"` | Register event listener |
-| `"evt:remove"` | Remove event listener |
-| `"evt:gets"` | Get all listeners for an event |
-| `"evt:emit"` | Emit event to matching clients |
-| `"auth"` | Authenticate WebSocket connection via JWT |
-
----
-
-### `ServiceSocket`
-
-Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
-
-```typescript
-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;
-  removeListener(key: string): void;
-  getEventListeners(eventName: string): Array<{ key: string; info: unknown }>;
-  filterEventTargetKeys(targetKeys: string[]): string[];
-  on(event: "error" | "close" | "message", handler: Function): void;
-}
-```
-
-### `createServiceSocket(socket, clientId, clientName, connReq): ServiceSocket`
-
-Creates a service socket instance. Features:
-
-- **Protocol encoding/decoding** via `ServerProtocolWrapper` (with worker thread offloading)
-- **Ping/pong keep-alive** every 5 seconds; terminates unresponsive connections
-- **Event listener tracking** for pub/sub messaging
-- **Progress reporting** for chunked message transfers
-
----
-
-## HTTP
-
-### `handleHttpRequest<TAuthInfo>(req, reply, jwtSecret, runMethod): Promise<void>`
-
-Handles HTTP API requests on `/api/:service/:method`.
-
-- **GET**: Parameters parsed from `?json=` query parameter
-- **POST**: Parameters parsed from JSON request body (must be an array)
-- **Auth**: Reads `Authorization: Bearer <token>` header; returns 401 on failure
-- **Client name**: Required via `x-sd-client-name` header
-
-### `handleUpload(req, reply, rootPath, jwtSecret): Promise<void>`
-
-Handles multipart file uploads on `/upload`.
-
-- Requires authentication (JWT in `Authorization` header)
-- Files saved to `{rootPath}/www/uploads/` with UUID-based filenames
-- Returns `ServiceUploadResult[]` with path, original filename, and size
-- Cleans up incomplete files on failure
-
-### `handleStaticFile(req, reply, rootPath, urlPath): Promise<void>`
-
-Serves static files from `{rootPath}/www/`.
-
-- Path traversal protection
-- Auto-redirects directories to include trailing slash
-- Serves `index.html` for directory requests
-- Blocks access to hidden files (dotfiles) with 403
-- Returns appropriate HTML error pages for 403, 404, 500

package/docs/utilities.md

@@ -1,31 +0,0 @@
-# Utilities
-
-## `getConfig<TConfig>(filePath): Promise<TConfig | undefined>`
-
-Reads and caches a JSON configuration file with automatic live-reloading via file system watcher.
-
-### Features
-
-- **Caching**: Configurations are cached in a `LazyGcMap` with auto-renewal on access
-- **Live-reload**: File changes are detected and the cache is updated automatically (100ms debounce)
-- **Garbage collection**: Cache entries expire after 1 hour of inactivity; GC runs every 10 minutes
-- **Watcher cleanup**: File watchers are released when cache entries expire or files are deleted
-
-### Usage
-
-```typescript
-import { getConfig } from "@simplysm/service-server";
-
-const config = await getConfig<{ key: string }>("/path/to/.config.json");
-```
-
-This function is used internally by `ServiceContext.getConfig()` to load root and client-level configuration files.
-
-### Behavior
-
-1. Returns cached value if available (resets expiry timer)
-2. If file does not exist, returns `undefined`
-3. Reads and parses the JSON file, stores in cache
-4. Registers a file watcher for live-reload
-5. On file change: re-reads and updates cache
-6. On file deletion: removes cache entry and closes watcher