@simplysm/service-server 14.0.48 → 14.0.51

package/docs/auth.md

@@ -1,64 +0,0 @@
-# Auth
-
-## `AuthTokenPayload`
-
-JWT 페이로드 인터페이스. `jose` 라이브러리의 `JWTPayload`를 확장한다.
-
-```typescript
-interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
-  roles: string[];
-  data: TAuthInfo;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `roles` | `string[]` | 사용자 역할 배열. `auth(["admin"], ...)` 등에서 역할 검사에 사용된다 |
-| `data` | `TAuthInfo` | 사용자 정의 인증 데이터. `ServiceContext.authInfo`로 접근 가능하다 |
-| (JWTPayload 상속) | — | `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti` 등 표준 JWT 클레임 |
-
-## `signJwt`
-
-HS256 알고리즘과 12시간 유효기간으로 JWT 토큰을 서명한다.
-
-```typescript
-async function signJwt<TAuthInfo = unknown>(
-  jwtSecret: string,
-  payload: AuthTokenPayload<TAuthInfo>,
-): Promise<string>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `jwtSecret` | `string` | HMAC 서명 시크릿 |
-| `payload` | `AuthTokenPayload<TAuthInfo>` | JWT 페이로드 |
-
-반환값: 서명된 JWT 토큰 문자열.
-
-## `verifyJwt`
-
-JWT 토큰을 검증하고 페이로드를 반환한다. 만료된 토큰은 "토큰이 만료되었습니다." 에러를, 그 외 유효하지 않은 토큰은 "유효하지 않은 토큰입니다." 에러를 던진다.
-
-```typescript
-async function verifyJwt<TAuthInfo = unknown>(
-  jwtSecret: string,
-  token: string,
-): Promise<AuthTokenPayload<TAuthInfo>>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `jwtSecret` | `string` | HMAC 서명 시크릿 |
-| `token` | `string` | 검증할 JWT 토큰 문자열 |
-
-## `decodeJwt`
-
-JWT 토큰을 검증 없이 디코딩한다. 서명 검증이나 만료 확인을 수행하지 않는다.
-
-```typescript
-function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `token` | `string` | 디코딩할 JWT 토큰 문자열 |

package/docs/core.md

@@ -1,174 +0,0 @@
-# Core
-
-## `ServiceContext`
-
-서비스 팩토리 함수에 전달되는 컨텍스트 인터페이스. 전송 방식(WebSocket/HTTP)에 무관하게 동일한 인터페이스를 제공한다.
-
-```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>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `server` | `ServiceServer<TAuthInfo>` | 서버 인스턴스 참조 |
-| `socket` | `ServiceSocket` (optional) | WebSocket 요청일 때만 존재하는 소켓 객체 |
-| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }` (optional) | HTTP 요청일 때만 존재 |
-| `legacy` | `{ clientName?: string }` (optional) | V1 레거시 컨텍스트 (자동 업데이트 전용) |
-
-| Accessor/Method | Return Type | Description |
-|------------------|-------------|-------------|
-| `authInfo` | `TAuthInfo \| undefined` | 토큰에서 추출한 사용자 데이터. WebSocket은 소켓의 `authTokenPayload.data`, HTTP는 헤더의 `authTokenPayload.data`에서 읽는다 |
-| `clientName` | `string \| undefined` | 클라이언트 앱 이름. `..`, `/`, `\`를 포함하면 에러를 던진다 (경로 탐색 공격 방지) |
-| `clientPath` | `string \| undefined` | `{rootPath}/www/{clientName}` 경로. `clientName`이 없으면 `undefined` |
-| `getConfig<T>(section)` | `Promise<T>` | `.config.json`에서 섹션을 읽는다. 루트 설정을 먼저 읽고 클라이언트별 설정으로 덮어쓴다. 섹션이 없으면 에러를 던진다 |
-
-## `createServiceContext`
-
-`ServiceContext` 인스턴스를 생성한다.
-
-```typescript
-function createServiceContext<TAuthInfo = unknown>(
-  server: ServiceServer<TAuthInfo>,
-  socket?: ServiceSocket,
-  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> },
-  legacy?: { clientName?: string },
-): ServiceContext<TAuthInfo>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `server` | `ServiceServer<TAuthInfo>` | 서버 인스턴스 |
-| `socket` | `ServiceSocket` (optional) | WebSocket 연결 (WebSocket 요청 시) |
-| `http` | `{ clientName: string; authTokenPayload? }` (optional) | HTTP 요청 정보 |
-| `legacy` | `{ clientName?: string }` (optional) | V1 레거시 컨텍스트 |
-
-## `auth`
-
-서비스 팩토리 또는 메서드에 인증을 요구하는 래퍼 함수. 래핑된 함수에 `AUTH_PERMISSIONS` 심볼로 권한 배열을 부착한다.
-
-```typescript
-function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
-function auth<TFunction extends (...args: any[]) => any>(
-  permissions: string[],
-  fn: TFunction,
-): TFunction;
-```
-
-| Overload | Description |
-|----------|-------------|
-| `auth(fn)` | 로그인만 요구 (역할 검사 없음). 권한 배열은 `[]` |
-| `auth(permissions, fn)` | 지정된 역할 중 하나를 가진 사용자만 허용 |
-
-사용 위치:
-- 서비스 수준: `defineService("Name", auth((ctx) => ({ ... })))` — 모든 메서드에 인증 적용
-- 메서드 수준: `{ methodName: auth(() => result) }` — 해당 메서드만 인증 적용
-- 메서드 수준이 서비스 수준보다 우선한다
-
-## `getServiceAuthPermissions`
-
-`auth()`로 래핑된 함수에서 인증 권한 배열을 읽는다. 래핑되지 않은 함수는 `undefined`를 반환한다.
-
-```typescript
-function getServiceAuthPermissions(fn: Function): string[] | undefined;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `fn` | `Function` | 검사할 함수 |
-
-## `ServiceDefinition`
-
-서비스 정의 구조체.
-
-```typescript
-interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
-  name: string;
-  factory: (ctx: ServiceContext) => TMethods;
-  authPermissions?: string[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | 서비스 이름. HTTP에서 `/api/{name}/{method}`, WebSocket에서 `{name}.{method}`로 라우팅된다 |
-| `factory` | `(ctx: ServiceContext) => TMethods` | 요청마다 호출되는 팩토리 함수. 메서드 객체를 반환한다 |
-| `authPermissions` | `string[]` (optional) | `auth()`로 래핑된 팩토리의 경우 서비스 수준 권한 배열 |
-
-## `defineService`
-
-이름과 팩토리 함수로 서비스를 정의한다. 팩토리가 `auth()`로 래핑되어 있으면 자동으로 `authPermissions`를 추출한다.
-
-```typescript
-function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
-  name: string,
-  factory: (ctx: ServiceContext) => TMethods,
-): ServiceDefinition<TMethods>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | 서비스 이름 |
-| `factory` | `(ctx: ServiceContext) => TMethods` | 메서드 객체를 반환하는 팩토리 함수 |
-
-## `ServiceMethods`
-
-`ServiceDefinition`에서 메서드 시그니처를 추출하는 유틸리티 타입. 클라이언트 측 타입 공유에 사용한다.
-
-```typescript
-type ServiceMethods<TDefinition> =
-  TDefinition extends ServiceDefinition<infer M> ? M : never;
-```
-
-사용 예:
-
-```typescript
-export type UserServiceType = ServiceMethods<typeof UserService>;
-```
-
-## `executeServiceMethod`
-
-서비스 조회 -> 컨텍스트 생성 -> 인증 확인 -> 메서드 실행 파이프라인을 수행한다.
-
-```typescript
-async function executeServiceMethod(
-  server: ServiceServer,
-  def: {
-    serviceName: string;
-    methodName: string;
-    params: unknown[];
-    socket?: ServiceSocket;
-    http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
-  },
-): Promise<unknown>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `server` | `ServiceServer` | 서버 인스턴스 |
-| `def.serviceName` | `string` | 호출할 서비스 이름 |
-| `def.methodName` | `string` | 호출할 메서드 이름 |
-| `def.params` | `unknown[]` | 메서드 매개변수 배열 |
-| `def.socket` | `ServiceSocket` (optional) | WebSocket 연결 (WebSocket 요청 시) |
-| `def.http` | `{ clientName: string; authTokenPayload? }` (optional) | HTTP 요청 정보 |
-
-인증 검사 로직:
-
-1. 메서드 수준 `auth()` 권한이 있으면 이를 사용하고, 없으면 서비스 수준 `authPermissions`를 사용한다
-2. 인증이 필요한데 `server.options.auth`가 `undefined`이면 설정 오류로 에러를 던진다
-3. `server.options.auth`가 `false`이면 인증 검사를 스킵한다
-4. 인증이 활성화되어 있으면 토큰 존재 여부를 확인하고, 역할 배열이 비어있지 않으면 역할 매칭을 수행한다

package/docs/main.md

@@ -1,88 +0,0 @@
-# Main
-
-## `ServiceServer`
-
-Fastify를 래핑한 서비스 서버 클래스. WebSocket/HTTP 이중 전송, JWT 인증, 이벤트 브로드캐스트, graceful shutdown을 처리한다. `EventEmitter<{ ready: void; close: void }>`를 확장한다.
-
-```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>;
-  getEvent<TEventDef extends ServiceEventDef>(eventName: string): ServerEventProxy<TEventDef>;
-  async emitEvent<TEventDef extends ServiceEventDef>(
-    eventName: string,
-    infoSelector: (item: TEventDef["$info"]) => boolean,
-    data: TEventDef["$data"],
-  ): Promise<void>;
-  async signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
-  async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
-}
-```
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `isOpen` | `boolean` | 서버가 리스닝 중인지 여부 |
-| `fastify` | `FastifyInstance` | 내부 Fastify 인스턴스. 직접 접근이 필요할 때 사용 |
-| `options` | `ServiceServerOptions` | 생성 시 전달된 옵션 |
-
-| Method | Description |
-|--------|-------------|
-| `listen()` | 서버를 시작한다. 플러그인 등록, 라우트 설정, SIGINT/SIGTERM 핸들러 등록을 수행한다. 완료 시 `ready` 이벤트를 발생시킨다 |
-| `close()` | 모든 WebSocket 연결을 닫고 Fastify 서버를 종료한다. 완료 시 `close` 이벤트를 발생시킨다 |
-| `getEvent(eventName)` | 타입 안전한 이벤트 프록시(`ServerEventProxy<TEventDef>`)를 반환한다. `emit(infoSelector, data)` 메서드를 포함. `getService()` 패턴과 동일 |
-| `emitEvent(eventName, infoSelector, data)` | `eventName`에 해당하는 이벤트 리스너 중 `infoSelector`에 매칭되는 WebSocket 클라이언트에 이벤트를 브로드캐스트한다. 제네릭 `TEventDef`로 타입 안전성 보장 |
-| `signAuthToken(payload)` | JWT 토큰을 서명한다. `options.auth`가 설정되지 않으면 에러를 던진다 |
-| `verifyAuthToken(token)` | JWT 토큰을 검증하고 페이로드를 반환한다. `options.auth`가 설정되지 않으면 에러를 던진다 |
-
-`listen()` 시 등록되는 라우트:
-
-| Route | Method | Handler |
-|-------|--------|---------|
-| `/api/:service/:method` | GET/POST | `handleHttpRequest` -- 서비스 메서드 호출 |
-| `/upload` | POST | `handleUpload` -- multipart 파일 업로드 |
-| `/`, `/ws` | WebSocket | WebSocket 핸들러. `ver=2` 쿼리 시 V2 프로토콜, 그 외 V1 레거시 |
-| `/*` | GET/POST/PUT/DELETE/PATCH/HEAD | `handleStaticFile` -- 정적 파일 서빙 |
-
-`listen()` 시 Fastify 플러그인 등록 순서: `@fastify/websocket` -> `@fastify/helmet` -> `@fastify/multipart` -> `@fastify/static` -> `@fastify/cors`
-
-Graceful shutdown: `SIGINT`/`SIGTERM` 시그널 수신 시 `close()`를 호출하고, 10초 내에 종료되지 않으면 `process.exit(1)`로 강제 종료한다.
-
-## `ServerEventProxy`
-
-`getEvent()`가 반환하는 타입 안전한 이벤트 프록시 인터페이스. `emit` 메서드만 포함한다.
-
-```typescript
-interface ServerEventProxy<TEventDef extends ServiceEventDef> {
-  emit(
-    infoSelector: (item: TEventDef["$info"]) => boolean,
-    data: TEventDef["$data"],
-  ): Promise<void>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `emit(infoSelector, data)` | `infoSelector`에 매칭되는 이벤트 리스너를 가진 WebSocket 클라이언트에 이벤트를 브로드캐스트한다 |
-
-## `createServiceServer`
-
-`ServiceServer` 인스턴스를 생성하는 팩토리 함수.
-
-```typescript
-function createServiceServer<TAuthInfo = unknown>(
-  options: ServiceServerOptions,
-): ServiceServer<TAuthInfo>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `options` | `ServiceServerOptions` | 서버 설정 옵션 |

package/docs/services.md

@@ -1,94 +0,0 @@
-# Services
-
-## `OrmService`
-
-ORM 브리지 서비스 정의. WebSocket 전용이며 `auth()`로 래핑되어 로그인이 필수다. `defineService("Orm", auth((ctx) => ...))`로 정의되어 있다.
-
-```typescript
-const OrmService: ServiceDefinition;
-```
-
-소켓별 DB 연결 관리:
-- `WeakMap<ServiceSocket, Map<number, DbConn>>`으로 소켓별 연결 상태를 관리한다
-- 소켓이 닫히면 해당 소켓의 열린 DB 연결을 모두 자동 종료한다
-- `getConfig("orm")`에서 `configName`으로 DB 연결 설정을 읽는다
-
-제공 메서드:
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getInfo` | `(opt: DbConnOptions & { configName: string }) => Promise<{ dialect: Dialect; database?: string; schema?: string }>` | DB 연결 정보를 반환한다. `mssql-azure` dialect은 `mssql`로 변환된다 |
-| `connect` | `(opt: DbConnOptions & { configName: string }) => Promise<number>` | DB에 연결하고 연결 ID를 반환한다 |
-| `close` | `(connId: number) => Promise<void>` | DB 연결을 종료한다 |
-| `beginTransaction` | `(connId: number, isolationLevel?: IsolationLevel) => Promise<void>` | 트랜잭션을 시작한다 |
-| `commitTransaction` | `(connId: number) => Promise<void>` | 트랜잭션을 커밋한다 |
-| `rollbackTransaction` | `(connId: number) => Promise<void>` | 트랜잭션을 롤백한다 |
-| `executeParametrized` | `(connId: number, query: string, params?: unknown[]) => Promise<unknown[][]>` | 파라미터화된 쿼리를 실행한다 |
-| `executeDefs` | `(connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]) => Promise<unknown[][]>` | QueryDef 배열을 SQL로 변환하여 실행한다. `options`가 모두 `null`이면 쿼리를 합쳐 한 번에 실행한다 |
-| `bulkInsert` | `(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]) => Promise<void>` | 대량 삽입을 수행한다 |
-
-HTTP 요청 시 "WebSocket 연결이 필요합니다" 에러를 던진다.
-
-## `OrmServiceType`
-
-`OrmService`의 메서드 시그니처 타입. 클라이언트 측 타입 공유에 사용한다.
-
-```typescript
-type OrmServiceType = ServiceMethods<typeof OrmService>;
-```
-
-## `AutoUpdateService`
-
-자동 업데이트 서비스 정의. `defineService("AutoUpdate", (ctx) => ...)`로 정의되어 있다. 인증 불필요.
-
-```typescript
-const AutoUpdateService: ServiceDefinition;
-```
-
-제공 메서드:
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getLastVersion` | `(platform: string) => Promise<{ version: string; downloadPath: string } \| undefined>` | `{clientPath}/{platform}/updates/` 디렉토리에서 최신 버전 파일을 찾아 반환한다 |
-
-`getLastVersion` 동작:
-- `platform`이 `"android"`이면 `.apk` 파일을, 그 외에는 `.exe` 파일을 탐색한다
-- 파일명이 `{version}.{ext}` 형식이어야 하며 (예: `1.2.3.apk`), `semver.maxSatisfying`으로 최대 버전을 결정한다
-- `clientPath`가 없으면 에러를 던진다
-- 업데이트 디렉토리나 매칭 파일이 없으면 `undefined`를 반환한다
-
-## `AutoUpdateServiceType`
-
-`AutoUpdateService`의 메서드 시그니처 타입.
-
-```typescript
-type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
-```
-
-## `AppStructureService`
-
-앱 구조 정보 서비스를 생성하는 팩토리 함수. `defineService`를 래핑하여 `Record<string, AppStructureItem[]>` 맵을 받아 서비스 정의를 반환한다. 인증 불필요.
-
-```typescript
-function AppStructureService(
-  itemsMap: Record<string, AppStructureItem[]>,
-): ServiceDefinition;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `itemsMap` | `Record<string, AppStructureItem[]>` | 앱 구조 아이템 맵. `AppStructureItem`은 `@simplysm/service-common`에서 import한다 |
-
-제공 메서드:
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getItems` | `() => Record<string, AppStructureItem[]>` | 생성 시 전달된 `itemsMap`을 그대로 반환한다 |
-
-## `AppStructureServiceType`
-
-`AppStructureService`가 반환하는 서비스의 메서드 시그니처 타입.
-
-```typescript
-type AppStructureServiceType = ServiceMethods<ReturnType<typeof AppStructureService>>;
-```

package/docs/transport-http.md

@@ -1,93 +0,0 @@
-# Transport - HTTP
-
-## `handleHttpRequest`
-
-GET/POST `/api/:service/:method` 경로의 HTTP 요청을 처리한다. `x-sd-client-name` 헤더가 필수이며, `Authorization` 헤더가 있으면 JWT 토큰을 검증한다.
-
-```typescript
-async function handleHttpRequest<TAuthInfo = unknown>(
-  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>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify 요청 객체 |
-| `reply` | `FastifyReply` | Fastify 응답 객체 |
-| `jwtSecret` | `string \| undefined` | JWT 시크릿. `Authorization` 헤더가 있는데 시크릿이 없으면 에러를 던진다 |
-| `runMethod` | `(def) => Promise<unknown>` | 서비스 메서드 실행 콜백 |
-
-요청 매개변수 파싱:
-- **GET**: `?json=` 쿼리 파라미터에서 JSON 배열을 파싱한다
-- **POST**: 요청 본문이 JSON 배열이어야 한다. 배열이 아니면 400을 반환한다
-- **그 외**: 405 Method Not Allowed를 반환한다
-
-인증 실패 시 401 응답을 반환한다.
-
-## `handleUpload`
-
-`/upload` 경로의 multipart 파일 업로드를 처리한다. 인증 필수 (Authorization 헤더 필수).
-
-```typescript
-async function handleUpload(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  jwtSecret: string | undefined,
-): Promise<void>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify 요청 객체 |
-| `reply` | `FastifyReply` | Fastify 응답 객체 |
-| `rootPath` | `string` | 서버 루트 경로. 파일은 `{rootPath}/www/uploads/`에 저장된다 |
-| `jwtSecret` | `string \| undefined` | JWT 시크릿 |
-
-동작:
-- 파일명은 UUID로 변환되고 원래 확장자를 유지한다
-- 파일 크기 제한 초과 시 에러를 던진다
-- 에러 발생 시 불완전한 파일과 이미 저장된 파일을 모두 정리한다
-
-응답: `ServiceUploadResult[]` (from `@simplysm/service-common`)
-
-```typescript
-// ServiceUploadResult 구조
-{ path: "uploads/{uuid}.ext", filename: "원본파일명.ext", size: number }
-```
-
-## `handleStaticFile`
-
-정적 파일 서빙을 처리한다. 경로 탐색 공격 방지와 숨김 파일 접근 차단이 포함되어 있다.
-
-```typescript
-async function handleStaticFile(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  urlPath: string,
-): Promise<void>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify 요청 객체 |
-| `reply` | `FastifyReply` | Fastify 응답 객체 |
-| `rootPath` | `string` | 서버 루트 경로. `{rootPath}/www/` 하위에서 파일을 찾는다 |
-| `urlPath` | `string` | 요청 URL 경로 (슬래시 제거됨) |
-
-보안 처리:
-- `{rootPath}/www/` 외부 경로 접근 시 에러를 던진다 (경로 탐색 공격 방지)
-- `.`으로 시작하는 파일은 403 Forbidden을 반환한다
-
-디렉토리 처리:
-- 디렉토리 요청 시 끝에 슬래시가 없으면 슬래시를 추가하여 리다이렉트한다
-- 디렉토리에 대해 `index.html`을 자동으로 서빙한다

package/docs/transport-socket.md

@@ -1,119 +0,0 @@
-# Transport - Socket
-
-## `WebSocketHandler`
-
-다중 WebSocket 연결을 관리하고, 메시지를 서비스로 라우팅하며, 이벤트 브로드캐스팅을 처리하는 인터페이스.
-
-```typescript
-interface WebSocketHandler {
-  addSocket(socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest): void;
-  closeAll(): void;
-  emit<TEventDef extends ServiceEventDef>(
-    eventName: string,
-    infoSelector: (item: TEventDef["$info"]) => boolean,
-    data: TEventDef["$data"],
-  ): Promise<void>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `addSocket(socket, clientId, clientName, connReq)` | 새 WebSocket 연결을 추가한다. 동일 `clientId`의 이전 연결이 있으면 해제한다 |
-| `closeAll()` | 모든 활성 연결을 닫는다 |
-| `emit(eventName, infoSelector, data)` | `eventName`에 해당하는 이벤트 리스너 중 `infoSelector`에 매칭되는 클라이언트에 이벤트를 브로드캐스트한다. 제네릭 `TEventDef`로 타입 안전성 보장 |
-
-메시지 라우팅 (`processRequest` 내부):
-
-| `message.name` | 처리 |
-|-----------------|------|
-| `"SvcName.methodName"` (`.` 포함) | `runMethod`로 서비스 메서드 실행 |
-| `"evt:add"` | 이벤트 리스너 등록 (`key`, `name`, `info`) |
-| `"evt:remove"` | 이벤트 리스너 제거 (`key`) |
-| `"evt:gets"` | 전체 소켓의 특정 이벤트 리스너 조회 |
-| `"evt:emit"` | 지정된 키 대상 이벤트 발송 |
-| `"auth"` | JWT 토큰 검증 후 소켓에 `authTokenPayload` 저장 |
-
-## `createWebSocketHandler`
-
-`WebSocketHandler` 인스턴스를 생성한다.
-
-```typescript
-function createWebSocketHandler(
-  runMethod: (def: {
-    serviceName: string;
-    methodName: string;
-    params: unknown[];
-    socket?: ServiceSocket;
-  }) => Promise<unknown>,
-  jwtSecret: string | undefined,
-): WebSocketHandler;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runMethod` | `(def: { serviceName, methodName, params, socket? }) => Promise<unknown>` | 서비스 메서드 실행 콜백 |
-| `jwtSecret` | `string \| undefined` | JWT 시크릿. `undefined`이면 `auth` 메시지 처리 시 에러를 던진다 |
-
-## `ServiceSocket`
-
-프로토콜 인코딩/디코딩, ping/pong 연결 유지, 이벤트 리스너 추적이 포함된 단일 WebSocket 연결 인터페이스.
-
-```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;
-}
-```
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `connectedAtDateTime` | `DateTime` | 연결 시점의 DateTime 객체 |
-| `clientName` | `string` | 클라이언트 앱 이름 |
-| `connReq` | `FastifyRequest` | 연결 시점의 Fastify 요청 객체 |
-| `authTokenPayload` | `AuthTokenPayload` (optional) | WebSocket `auth` 메시지로 검증된 토큰 페이로드 |
-
-| Method | Description |
-|--------|-------------|
-| `close()` | WebSocket 연결을 종료한다 (`socket.terminate()`) |
-| `send(uuid, msg)` | 메시지를 프로토콜 인코딩하여 전송한다. 전송된 바이트 수를 반환한다. 소켓이 닫혀있으면 0을 반환한다 |
-| `addListener(key, eventName, info)` | key/name/info로 이벤트 리스너를 등록한다 |
-| `removeListener(key)` | key로 이벤트 리스너를 제거한다 |
-| `getEventListeners(eventName)` | 특정 이벤트 이름에 해당하는 모든 리스너의 `{ key, info }` 배열을 반환한다 |
-| `filterEventTargetKeys(targetKeys)` | 이 소켓의 리스너에 존재하는 대상 키만 필터링하여 반환한다 |
-| `on(event, handler)` | `"error"`, `"close"`, `"message"` 이벤트 핸들러를 등록한다 |
-
-ping/pong: 5초 간격으로 ping을 전송하고, 클라이언트의 `0x01` 바이트(ping) 수신 시 `0x02` 바이트(pong)를 응답한다. pong 미수신 시 연결을 종료한다.
-
-프로토콜 메시지 처리: `createServerProtocolWrapper`를 사용하여 메시지를 인코딩/디코딩한다. 수신 메시지의 디코딩 결과가 `"progress"` 타입이면 진행률 메시지를 클라이언트에 전송한다.
-
-## `createServiceSocket`
-
-`ServiceSocket` 인스턴스를 생성한다.
-
-```typescript
-function createServiceSocket(
-  socket: WebSocket,
-  clientId: string,
-  clientName: string,
-  connReq: FastifyRequest,
-): ServiceSocket;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `WebSocket` | 기저 WebSocket 인스턴스 (`ws` 라이브러리) |
-| `clientId` | `string` | 클라이언트 고유 식별자 |
-| `clientName` | `string` | 클라이언트 앱 이름 |
-| `connReq` | `FastifyRequest` | 연결 시점의 Fastify 요청 객체 |