@simplysm/service-server 13.0.96 → 13.0.98

package/docs/builtin-services.md

@@ -1,249 +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;
-  cc?: string;
-  bcc?: string;
-  subject: string;
-  html: string;
-  attachments?: SmtpClientSendAttachment[];
-}
-```
-
-### SmtpClientSendByDefaultOption
-
-```typescript
-interface SmtpClientSendByDefaultOption {
-  to: string;
-  cc?: string;
-  bcc?: string;
-  subject: string;
-  html: string;
-  attachments?: SmtpClientSendAttachment[];
-}
-```
-
-### SmtpClientSendAttachment
-
-```typescript
-interface SmtpClientSendAttachment {
-  filename: string;
-  content?: string | Uint8Array;
-  path?: any;
-  contentType?: string;
-}
-```
-
-### 설정 예시
-
-`.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)로 변경 시 자동 리로드
-- 파일 삭제 시 캐시에서 제거 및 감시 해제
-- 캐시 만료 시 감시도 함께 해제