@simplysm/service-server 13.0.96 → 13.0.98

package/README.md

@@ -1,364 +1,98 @@
 # @simplysm/service-server
 
-Fastify 기반 서비스 서버. WebSocket RPC, HTTP API, JWT 인증, 이벤트 브로드캐스트, 파일 업로드, 정적 파일 서빙을 제공한다.
+Service module (server) -- Fastify-based service server with WebSocket support, JWT authentication, and built-in ORM/SMTP/auto-update services.
 
-## 설치
+## Installation
 
 ```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`
-
-## 문서
-
-| 카테고리 | 설명 |
-|---------|------|
-| [내장 서비스](docs/builtin-services.md) | OrmService, AutoUpdateService, SmtpClientService 메서드 시그니처 |
-| [전송 계층 및 프로토콜](docs/transport-protocol.md) | WebSocket 핸들러, ServiceSocket, HTTP 핸들러, 프로토콜 래퍼 |
-
-## 빠른 시작
+## Exports
+
+```typescript
+import {
+  // Main
+  ServiceServer,
+  createServiceServer,
+  type ServiceServerOptions,
+  // Auth
+  type AuthTokenPayload,
+  signJwt,
+  verifyJwt,
+  decodeJwt,
+  // Core
+  type ServiceContext,
+  createServiceContext,
+  getServiceAuthPermissions,
+  auth,
+  type ServiceDefinition,
+  defineService,
+  type ServiceMethods,
+  executeServiceMethod,
+  // Transport - Socket
+  type WebSocketHandler,
+  createWebSocketHandler,
+  type ServiceSocket,
+  createServiceSocket,
+  // Transport - HTTP
+  handleHttpRequest,
+  handleUpload,
+  handleStaticFile,
+  // Protocol
+  type ServerProtocolWrapper,
+  createServerProtocolWrapper,
+  // Services
+  OrmService,
+  type OrmServiceType,
+  AutoUpdateService,
+  type AutoUpdateServiceType,
+  SmtpClientService,
+  type SmtpClientServiceType,
+  // Utils
+  getConfig,
+  // Legacy
+  handleV1Connection,
+} from "@simplysm/service-server";
+```
+
+## Quick Start
+
+```typescript
+import {
+  createServiceServer,
+  defineService,
+  auth,
+  OrmService,
+  AutoUpdateService,
+} from "@simplysm/service-server";
+
+// Define a custom service
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
 
-```typescript
-import { createServiceServer, defineService, auth } from "@simplysm/service-server";
+// Define an authenticated service
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+  adminOnly: auth(["admin"], () => "admin-only data"),
+})));
 
+// Create and start server
 const server = createServiceServer({
   rootPath: "/app",
   port: 3000,
-  ssl: { pfxBytes, passphrase: "cert-pass" },  // 선택
-  auth: { jwtSecret: "my-secret" },             // 선택
-  services: [UserService, OrmService],
+  auth: { jwtSecret: "my-secret" },
+  services: [HealthService, UserService, OrmService, AutoUpdateService],
 });
 
 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[];  // 등록할 서비스 목록
-}
-```
-
-### ServiceServer
-
-```typescript
-class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
-  ready: void;
-  close: void;
-}> {
-  isOpen: boolean;
-  readonly fastify: FastifyInstance;
-  readonly options: ServiceServerOptions;
-
-  constructor(options: ServiceServerOptions);
-  async listen(): Promise<void>;
-  async close(): Promise<void>;
-
-  // 이벤트 브로드캐스트
-  async broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>;
-  async emitEvent<TInfo, TData>(
-    eventDef: ServiceEventDef<TInfo, TData>,
-    infoSelector: (item: TInfo) => boolean,
-    data: TData,
-  ): Promise<void>;
-
-  // JWT 인증
-  async signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
-  async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
-}
-
-// 팩토리 함수
-function createServiceServer<TAuthInfo = unknown>(
-  options: ServiceServerOptions,
-): ServiceServer<TAuthInfo>;
-```
-
-## 서비스 정의
-
-`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>;
-```
-
-### defineService
-
-```typescript
-function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
-  name: string,
-  factory: (ctx: ServiceContext) => TMethods,
-): ServiceDefinition<TMethods>;
-```
-
-### ServiceDefinition
-
-```typescript
-interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
-  name: string;
-  factory: (ctx: ServiceContext) => TMethods;
-  authPermissions?: string[];
-}
-```
-
-### ServiceMethods (타입 유틸리티)
-
-`ServiceDefinition`에서 메서드 시그니처를 추출하는 타입. 클라이언트-서버 간 타입 공유에 사용한다.
-
-```typescript
-type ServiceMethods<TDefinition> =
-  TDefinition extends ServiceDefinition<infer M> ? M : never;
-
-// 사용 예시
-export type UserServiceType = ServiceMethods<typeof UserService>;
-// 클라이언트: client.getService<UserServiceType>("User");
-```
-
-### 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");
-```
-
-클라이언트별 설정이 있으면 (`rootPath/www/{clientName}/.config.json`) 루트 설정에 머지된다.
-
-## 서버 이벤트
-
-```typescript
-server.on("ready", () => { /* 서버 시작 완료 */ });
-server.on("close", () => { /* 서버 종료 완료 */ });
 ```
 
-## Graceful Shutdown
+## Documentation
 
-SIGINT/SIGTERM 시그널 수신 시 자동으로 graceful shutdown을 수행한다. 10초 타임아웃 후 강제 종료.
+- [Auth](docs/auth.md)
+- [Core](docs/core.md)
+- [Transport](docs/transport.md)
+- [Built-in Services](docs/services.md)
+- [Server](docs/server.md)

package/docs/auth.md

@@ -0,0 +1,48 @@
+# Auth
+
+JWT-based authentication utilities using the `jose` library (HS256 algorithm).
+
+## `AuthTokenPayload`
+
+JWT token payload structure. Extends `JWTPayload` from `jose`.
+
+```typescript
+interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
+  roles: string[];
+  data: TAuthInfo;
+}
+```
+
+## `signJwt`
+
+Sign a JWT token. Tokens expire after 12 hours.
+
+```typescript
+async function signJwt<TAuthInfo = unknown>(
+  jwtSecret: string,
+  payload: AuthTokenPayload<TAuthInfo>,
+): Promise<string>;
+```
+
+## `verifyJwt`
+
+Verify a JWT token and return the payload.
+
+```typescript
+async function verifyJwt<TAuthInfo = unknown>(
+  jwtSecret: string,
+  token: string,
+): Promise<AuthTokenPayload<TAuthInfo>>;
+```
+
+Throws:
+- `"Token has expired."` if the token is expired
+- `"Invalid token."` for all other verification failures
+
+## `decodeJwt`
+
+Decode a JWT token without verification.
+
+```typescript
+function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo>;
+```

package/docs/core.md

@@ -0,0 +1,161 @@
+# Core
+
+Service definition, context, authentication, and method execution.
+
+## ServiceContext
+
+Context object passed to service factory functions.
+
+```typescript
+interface ServiceContext<TAuthInfo = unknown> {
+  server: ServiceServer<TAuthInfo>;
+  socket?: ServiceSocket;
+  http?: {
+    clientName: string;
+    authTokenPayload?: AuthTokenPayload<TAuthInfo>;
+  };
+  legacy?: { clientName?: string };
+
+  get authInfo(): TAuthInfo | undefined;
+  get clientName(): string | undefined;
+  get clientPath(): string | undefined;
+  getConfig<T>(section: string): Promise<T>;
+}
+```
+
+**Properties:**
+- `authInfo` -- Authenticated user data (from socket or HTTP auth token)
+- `clientName` -- Client application name (validated for path traversal)
+- `clientPath` -- Resolved client directory path (`{rootPath}/www/{clientName}`)
+- `getConfig(section)` -- Reads config from `.config.json` files (root + client-specific, merged)
+
+### `createServiceContext`
+
+```typescript
+function createServiceContext<TAuthInfo = unknown>(
+  server: ServiceServer<TAuthInfo>,
+  socket?: ServiceSocket,
+  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> },
+  legacy?: { clientName?: string },
+): ServiceContext<TAuthInfo>;
+```
+
+---
+
+## Auth Helpers
+
+### `getServiceAuthPermissions`
+
+Read auth permissions from an `auth()`-wrapped function. Returns `undefined` if not wrapped.
+
+```typescript
+function getServiceAuthPermissions(fn: Function): string[] | undefined;
+```
+
+### `auth`
+
+Auth wrapper for service factories and methods.
+
+```typescript
+// Login required (no specific roles)
+function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
+
+// Login required with specific roles
+function auth<TFunction extends (...args: any[]) => any>(
+  permissions: string[],
+  fn: TFunction,
+): TFunction;
+```
+
+**Usage levels:**
+- 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)`
+
+---
+
+## Service Definition
+
+### `ServiceDefinition`
+
+```typescript
+interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
+  name: string;
+  factory: (ctx: ServiceContext) => TMethods;
+  authPermissions?: string[];
+}
+```
+
+### `defineService`
+
+Define a service with a name and factory function.
+
+```typescript
+function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
+  name: string,
+  factory: (ctx: ServiceContext) => TMethods,
+): ServiceDefinition<TMethods>;
+```
+
+**Example:**
+```typescript
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
+
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+  adminOnly: auth(["admin"], () => "admin"),
+})));
+```
+
+### `ServiceMethods`
+
+Extract method signatures from a `ServiceDefinition` for client-side type sharing.
+
+```typescript
+type ServiceMethods<TDefinition> =
+  TDefinition extends ServiceDefinition<infer M> ? M : never;
+```
+
+**Example:**
+```typescript
+export type UserServiceType = ServiceMethods<typeof UserService>;
+// Client: client.getService<UserServiceType>("User");
+```
+
+---
+
+## Service Execution
+
+### `executeServiceMethod`
+
+Execute a service method with auth checking.
+
+```typescript
+async function executeServiceMethod(
+  server: ServiceServer,
+  def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+    http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
+  },
+): Promise<unknown>;
+```
+
+**Behavior:**
+1. Finds the service definition by name
+2. Validates the client name (path traversal guard)
+3. Creates a `ServiceContext`
+4. Invokes the factory to create the method object
+5. Checks auth permissions (method-level first, then service-level fallback)
+6. Executes the method with provided params
+
+Throws:
+- `"Service [name] not found."` if service is not registered
+- `"Method [service.method] not found."` if method does not exist
+- `"Login is required."` if auth is required but no token is present
+- `"Insufficient permissions."` if the user lacks required roles