@simplysm/service-server 13.0.95 → 13.0.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.95",
+  "version": "13.0.97",
   "description": "Simplysm package - service module (server)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -30,17 +30,17 @@
     "bufferutil": "^4.1.0",
     "consola": "^3.4.2",
     "fastify": "^5.8.2",
-    "jose": "^6.2.1",
+    "jose": "^6.2.2",
     "mime": "^4.1.0",
-    "nodemailer": "^8.0.2",
+    "nodemailer": "^8.0.3",
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.19.0",
-    "@simplysm/orm-node": "13.0.95",
-    "@simplysm/core-common": "13.0.95",
-    "@simplysm/orm-common": "13.0.95",
-    "@simplysm/core-node": "13.0.95",
-    "@simplysm/service-common": "13.0.95"
+    "@simplysm/core-common": "13.0.97",
+    "@simplysm/core-node": "13.0.97",
+    "@simplysm/orm-node": "13.0.97",
+    "@simplysm/orm-common": "13.0.97",
+    "@simplysm/service-common": "13.0.97"
   },
   "devDependencies": {
     "@types/nodemailer": "^7.0.11",

package/README.md

@@ -1,294 +0,0 @@
-# @simplysm/service-server
-
-Fastify 기반 서비스 서버. WebSocket RPC, HTTP API, JWT 인증, 이벤트 브로드캐스트, 파일 업로드, 정적 파일 서빙을 제공한다.
-
-## 설치
-
-```bash
-npm install @simplysm/service-server
-```
-
-**주요 의존성:** `fastify`, `@fastify/cors`, `@fastify/websocket`, `@fastify/static`, `@fastify/multipart`, `@fastify/helmet`, `jose`, `nodemailer`, `ws`
-
-**내부 의존성:** `@simplysm/core-common`, `@simplysm/core-node`, `@simplysm/orm-common`, `@simplysm/orm-node`, `@simplysm/service-common`
-
-## 서버 생성 및 실행
-
-```typescript
-import { createServiceServer, defineService, auth } from "@simplysm/service-server";
-
-const server = createServiceServer({
-  rootPath: "/app",
-  port: 3000,
-  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);                    // 검증 없이 디코드
-```
-
-## 이벤트 브로드캐스트
-
-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 레퍼런스
-
-- [내장 서비스 상세](docs/builtin-services.md) -- OrmService, AutoUpdateService, SmtpClientService 메서드 시그니처
-- [전송 계층 및 프로토콜](docs/transport-protocol.md) -- WebSocket 핸들러, ServiceSocket, 프로토콜 래퍼

package/docs/builtin-services.md

@@ -1,240 +0,0 @@
-# 내장 서비스 상세 API
-
-## OrmService
-
-서비스 이름: `"Orm"`. 인증 필수 (`auth` 래핑). WebSocket 전용 -- HTTP로는 사용 불가.
-
-소켓별로 DB 커넥션을 `WeakMap<ServiceSocket, Map<number, DbConn>>`으로 관리한다. 소켓 `close` 이벤트 시 해당 소켓의 모든 커넥션을 자동 정리한다.
-
-### 메서드
-
-```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
-
-`@simplysm/service-common`에서 가져온다.
-
-```typescript
-type DbConnOptions = {
-  configName?: string;
-  config?: Record<string, unknown>;  // .config.json 설정 오버라이드
-};
-```
-
-### 설정 예시
-
-`.config.json`:
-
-```json
-{
-  "orm": {
-    "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"
-    }
-  }
-}
-```
-
-### 타입 내보내기
-
-```typescript
-import type { OrmServiceType } from "@simplysm/service-server";
-// 클라이언트에서 타입 공유: client.getService<OrmServiceType>("Orm")
-```
-
----
-
-## AutoUpdateService
-
-서비스 이름: `"AutoUpdate"`. 인증 불필요. `clientPath/{platform}/updates/` 디렉토리에서 semver 기준 최신 버전 파일을 탐색한다.
-
-### 메서드
-
-```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`으로 최신 버전을 결정한다.
-
-### V1 레거시 호환
-
-V1 프로토콜 클라이언트(WebSocket `ver` 쿼리 파라미터 없음)도 `SdAutoUpdateService.getLastVersion` 명령으로 자동 업데이트를 요청할 수 있다. V1 클라이언트의 다른 요청은 `UPGRADE_REQUIRED` 에러를 반환한다.
-
-### 타입 내보내기
-
-```typescript
-import type { AutoUpdateServiceType } from "@simplysm/service-server";
-```
-
----
-
-## SmtpClientService
-
-서비스 이름: `"SmtpClient"`. 인증 불필요. nodemailer 기반 이메일 전송.
-
-### 메서드
-
-```typescript
-// 직접 SMTP 설정으로 전송
-async send(options: SmtpClientSendOption): Promise<string>
-// 반환값: messageId
-
-// .config.json의 smtp 설정으로 전송
-async sendByConfig(configName: string, options: SmtpClientSendByDefaultOption): Promise<string>
-// 반환값: messageId
-```
-
-### SmtpClientSendOption
-
-`@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
-{
-  "smtp": {
-    "default": {
-      "host": "smtp.example.com",
-      "port": 587,
-      "secure": false,
-      "user": "noreply@example.com",
-      "pass": "password",
-      "senderName": "My App",
-      "senderEmail": "noreply@example.com"
-    }
-  }
-}
-```
-
-`senderEmail`이 없으면 `user`가 발신자 이메일로 사용된다.
-
-### 사용 예시
-
-```typescript
-// 서버에서 직접 사용
-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>",
-});
-```
-
-### 타입 내보내기
-
-```typescript
-import type { SmtpClientServiceType } from "@simplysm/service-server";
-```

package/docs/transport-protocol.md

@@ -1,200 +0,0 @@
-# 전송 계층 및 프로토콜
-
-## 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)로 변경 시 자동 리로드
-- 파일 삭제 시 캐시에서 제거 및 감시 해제
-- 캐시 만료 시 감시도 함께 해제