@simplysm/service-server 14.0.49 → 14.0.51

package/docs/main/service-server.md

@@ -0,0 +1,106 @@
+# 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>>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `isOpen` | property | `boolean` | 서버가 리스닝 중인지 여부 |
+| `fastify` | property | `FastifyInstance` | 내부 Fastify 인스턴스. 직접 접근이 필요할 때 사용 |
+| `options` | property | `ServiceServerOptions` | 생성 시 전달된 옵션 |
+| `listen()` | method | `Promise<void>` | 서버를 시작한다. 플러그인 등록, 라우트 설정, SIGINT/SIGTERM 핸들러 등록을 수행한다. 완료 시 `ready` 이벤트를 발생시킨다 |
+| `close()` | method | `Promise<void>` | 모든 WebSocket 연결을 닫고 Fastify 서버를 종료한다. 완료 시 `close` 이벤트를 발생시킨다 |
+| `getEvent(eventName)` | method | `ServerEventProxy<TEventDef>` | 타입 안전한 이벤트 프록시를 반환한다. `emit(infoSelector, data)` 메서드를 포함 |
+| `emitEvent(eventName, infoSelector, data)` | method | `Promise<void>` | `infoSelector`에 매칭되는 WebSocket 클라이언트에 이벤트를 브로드캐스트한다 |
+| `signAuthToken(payload)` | method | `Promise<string>` | JWT 토큰을 서명한다. `options.auth`가 설정되지 않으면 에러를 던진다 |
+| `verifyAuthToken(token)` | method | `Promise<AuthTokenPayload<TAuthInfo>>` | 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)`로 강제 종료한다.
+
+## Related Types
+
+### `ServerEventProxy`
+
+`getEvent()`가 반환하는 타입 안전한 이벤트 프록시 인터페이스.
+
+```typescript
+interface ServerEventProxy<TEventDef extends ServiceEventDef> {
+  emit(
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `emit(infoSelector, data)` | `infoSelector`에 매칭되는 이벤트 리스너를 가진 WebSocket 클라이언트에 이벤트를 브로드캐스트한다 |
+
+## Usage
+
+```typescript
+import { createServiceServer, defineService, auth } from "@simplysm/service-server";
+
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
+
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+})));
+
+const server = createServiceServer<{ userId: string }>({
+  rootPath: "/app",
+  port: 3000,
+  auth: { jwtSecret: "my-secret" },
+  services: [HealthService, UserService],
+});
+
+await server.listen();
+
+// JWT 토큰 발급
+const token = await server.signAuthToken({
+  roles: ["admin"],
+  data: { userId: "123" },
+});
+
+// 이벤트 브로드캐스트
+const evt = server.getEvent<typeof MyEvent>("MyEvent");
+await evt.emit((info) => info.userId === "123", { name: "새 이름" });
+```

package/docs/{protocol.md → protocol/server-protocol-wrapper.md}

@@ -1,6 +1,4 @@
-# Protocol
-
-## `ServerProtocolWrapper`
+# ServerProtocolWrapper
 
 메시지 인코딩/디코딩 래퍼 인터페이스. 무거운 메시지는 worker 스레드에 자동으로 위임하고, 가벼운 작업은 메인 스레드에서 처리한다.
 
@@ -12,11 +10,13 @@ interface ServerProtocolWrapper {
 }
 ```
 
-| Method | Description |
-|--------|-------------|
-| `encode(uuid, message)` | 메시지를 인코딩한다. 바이너리 데이터(Uint8Array)가 포함된 메시지는 worker 스레드에 위임한다 |
-| `decode(bytes)` | 메시지를 디코딩한다. 30KB 초과 메시지는 worker 스레드에 위임한다 |
-| `dispose()` | 내부 프로토콜 리소스를 해제한다 |
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `encode(uuid, message)` | method | `Promise<{ chunks: Bytes[]; totalSize: number }>` | 메시지를 인코딩한다. 바이너리 데이터(Uint8Array)가 포함된 메시지는 worker 스레드에 위임한다 |
+| `decode(bytes)` | method | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | 메시지를 디코딩한다. 30KB 초과 메시지는 worker 스레드에 위임한다 |
+| `dispose()` | method | `void` | 내부 프로토콜 리소스를 해제한다 |
 
 Worker 위임 기준:
 - **encode**: 메시지 body가 `Uint8Array`이거나, 배열 내에 `Uint8Array` 요소가 있을 때 worker 사용
@@ -24,7 +24,9 @@ Worker 위임 기준:
 
 Worker는 지연 싱글턴으로 생성되며, `maxOldGenerationSizeMb: 4096`의 리소스 제한이 설정되어 있다.
 
-## `createServerProtocolWrapper`
+## Related Types
+
+### `createServerProtocolWrapper`
 
 `ServerProtocolWrapper` 인스턴스를 생성한다. 내부적으로 `@simplysm/service-common`의 `createServiceProtocol()`을 사용한다.
 

package/docs/services/app-structure-service.md

@@ -0,0 +1,54 @@
+# AppStructureService
+
+앱 구조 정보 서비스를 생성하는 팩토리 함수. `defineService`를 래핑하여 `Record<string, AppStructureItem[]>` 맵을 받아 서비스 정의를 반환한다. 인증 불필요.
+
+```typescript
+function AppStructureService(
+  itemsMap: Record<string, AppStructureItem[]>,
+): ServiceDefinition;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `itemsMap` | `Record<string, AppStructureItem[]>` | 앱 구조 아이템 맵. `AppStructureItem`은 `@simplysm/service-common`에서 import한다 |
+
+## Returns
+
+`ServiceDefinition` — `defineService("AppStructure", ...)`로 생성된 서비스 정의.
+
+제공 메서드:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getItems` | `() => Record<string, AppStructureItem[]>` | 생성 시 전달된 `itemsMap`을 그대로 반환한다 |
+
+## Related Types
+
+### `AppStructureServiceType`
+
+`AppStructureService`가 반환하는 서비스의 메서드 시그니처 타입.
+
+```typescript
+type AppStructureServiceType = ServiceMethods<ReturnType<typeof AppStructureService>>;
+```
+
+## Usage
+
+```typescript
+import { AppStructureService } from "@simplysm/service-server";
+import type { AppStructureItem } from "@simplysm/service-common";
+
+const itemsMap: Record<string, AppStructureItem[]> = {
+  "my-client": [
+    { title: "홈", path: "/home" },
+    { title: "설정", path: "/settings" },
+  ],
+};
+
+const server = createServiceServer({
+  services: [AppStructureService(itemsMap)],
+  // ...
+});
+```

package/docs/services/auto-update-service.md

@@ -0,0 +1,29 @@
+# AutoUpdateService
+
+자동 업데이트 서비스 정의. `defineService("AutoUpdate", (ctx) => ...)`로 정의되어 있다. 인증 불필요.
+
+```typescript
+const AutoUpdateService: ServiceDefinition;
+```
+
+## Members
+
+| 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`를 반환한다
+
+## Related Types
+
+### `AutoUpdateServiceType`
+
+`AutoUpdateService`의 메서드 시그니처 타입.
+
+```typescript
+type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
+```

package/docs/services/orm-service.md

@@ -0,0 +1,38 @@
+# OrmService
+
+ORM 브리지 서비스 정의. WebSocket 전용이며 `auth()`로 래핑되어 로그인이 필수다. `defineService("Orm", auth((ctx) => ...))`로 정의되어 있다.
+
+```typescript
+const OrmService: ServiceDefinition;
+```
+
+소켓별 DB 연결 관리:
+- `WeakMap<ServiceSocket, Map<number, DbConn>>`으로 소켓별 연결 상태를 관리한다
+- 소켓이 닫히면 해당 소켓의 열린 DB 연결을 모두 자동 종료한다
+- `getConfig("orm")`에서 `configName`으로 DB 연결 설정을 읽는다
+
+HTTP 요청 시 "WebSocket 연결이 필요합니다" 에러를 던진다.
+
+## Members
+
+| 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`가 모두 `undefined`이면 쿼리를 합쳐 한 번에 실행한다 |
+| `bulkInsert` | `(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]) => Promise<void>` | 대량 삽입을 수행한다 |
+
+## Related Types
+
+### `OrmServiceType`
+
+`OrmService`의 메서드 시그니처 타입. 클라이언트 측 타입 공유에 사용한다.
+
+```typescript
+type OrmServiceType = ServiceMethods<typeof OrmService>;
+```

package/docs/transport-http/handle-http-request.md

@@ -0,0 +1,33 @@
+# 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>;
+```
+
+## Parameters
+
+| Param | 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 응답을 반환한다.

package/docs/transport-http/handle-static-file.md

@@ -0,0 +1,29 @@
+# handleStaticFile
+
+정적 파일 서빙을 처리한다. 경로 탐색 공격 방지와 숨김 파일 접근 차단이 포함되어 있다.
+
+```typescript
+async function handleStaticFile(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  urlPath: string,
+): Promise<void>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `req` | `FastifyRequest` | Fastify 요청 객체 |
+| `reply` | `FastifyReply` | Fastify 응답 객체 |
+| `rootPath` | `string` | 서버 루트 경로. `{rootPath}/www/` 하위에서 파일을 찾는다 |
+| `urlPath` | `string` | 요청 URL 경로 (슬래시 제거됨) |
+
+보안 처리:
+- `{rootPath}/www/` 외부 경로 접근 시 에러를 던진다 (경로 탐색 공격 방지)
+- `.`으로 시작하는 파일은 403 Forbidden을 반환한다
+
+디렉토리 처리:
+- 디렉토리 요청 시 끝에 슬래시가 없으면 슬래시를 추가하여 리다이렉트한다
+- 디렉토리에 대해 `index.html`을 자동으로 서빙한다

package/docs/transport-http/handle-upload.md

@@ -0,0 +1,33 @@
+# handleUpload
+
+`/upload` 경로의 multipart 파일 업로드를 처리한다. 인증 필수 (Authorization 헤더 필수).
+
+```typescript
+async function handleUpload(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  jwtSecret: string | undefined,
+): Promise<void>;
+```
+
+## Parameters
+
+| Param | 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 }
+```

package/docs/transport-socket/service-socket.md

@@ -0,0 +1,64 @@
+# 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;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connectedAtDateTime` | property | `DateTime` | 연결 시점의 DateTime 객체 |
+| `clientName` | property | `string` | 클라이언트 앱 이름 |
+| `connReq` | property | `FastifyRequest` | 연결 시점의 Fastify 요청 객체 |
+| `authTokenPayload` | property | `AuthTokenPayload` (optional) | WebSocket `auth` 메시지로 검증된 토큰 페이로드 |
+| `close()` | method | `void` | WebSocket 연결을 종료한다 (`socket.terminate()`) |
+| `send(uuid, msg)` | method | `Promise<number>` | 메시지를 프로토콜 인코딩하여 전송한다. 전송된 바이트 수를 반환한다. 소켓이 닫혀있으면 0을 반환한다 |
+| `addListener(key, eventName, info)` | method | `void` | key/name/info로 이벤트 리스너를 등록한다 |
+| `removeListener(key)` | method | `void` | key로 이벤트 리스너를 제거한다 |
+| `getEventListeners(eventName)` | method | `Array<{ key: string; info: unknown }>` | 특정 이벤트 이름에 해당하는 모든 리스너의 배열을 반환한다 |
+| `filterEventTargetKeys(targetKeys)` | method | `string[]` | 이 소켓의 리스너에 존재하는 대상 키만 필터링하여 반환한다 |
+| `on(event, handler)` | method | `void` | `"error"`, `"close"`, `"message"` 이벤트 핸들러를 등록한다 |
+
+ping/pong: 5초 간격으로 ping을 전송하고, 클라이언트의 `0x01` 바이트(ping) 수신 시 `0x02` 바이트(pong)를 응답한다. pong 미수신 시 연결을 종료한다.
+
+프로토콜 메시지 처리: `createServerProtocolWrapper`를 사용하여 메시지를 인코딩/디코딩한다. 수신 메시지의 디코딩 결과가 `"progress"` 타입이면 진행률 메시지를 클라이언트에 전송한다.
+
+## Related Types
+
+### `createServiceSocket`
+
+`ServiceSocket` 인스턴스를 생성한다.
+
+```typescript
+function createServiceSocket(
+  socket: WebSocket,
+  clientId: string,
+  clientName: string,
+  connReq: FastifyRequest,
+): ServiceSocket;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `socket` | `WebSocket` | 기저 WebSocket 인스턴스 (`ws` 라이브러리) |
+| `clientId` | `string` | 클라이언트 고유 식별자 |
+| `clientName` | `string` | 클라이언트 앱 이름 |
+| `connReq` | `FastifyRequest` | 연결 시점의 Fastify 요청 객체 |

package/docs/transport-socket/websocket-handler.md

@@ -0,0 +1,57 @@
+# 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>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `addSocket(socket, clientId, clientName, connReq)` | method | `void` | 새 WebSocket 연결을 추가한다. 동일 `clientId`의 이전 연결이 있으면 해제한다 |
+| `closeAll()` | method | `void` | 모든 활성 연결을 닫는다 |
+| `emit(eventName, infoSelector, data)` | method | `Promise<void>` | `infoSelector`에 매칭되는 클라이언트에 이벤트를 브로드캐스트한다 |
+
+메시지 라우팅 (`processRequest` 내부):
+
+| `message.name` | 처리 |
+|-----------------|------|
+| `"SvcName.methodName"` (`.` 포함) | `runMethod`로 서비스 메서드 실행 |
+| `"evt:add"` | 이벤트 리스너 등록 (`key`, `name`, `info`) |
+| `"evt:remove"` | 이벤트 리스너 제거 (`key`) |
+| `"evt:gets"` | 전체 소켓의 특정 이벤트 리스너 조회 |
+| `"evt:emit"` | 지정된 키 대상 이벤트 발송 |
+| `"auth"` | JWT 토큰 검증 후 소켓에 `authTokenPayload` 저장 |
+
+## Related Types
+
+### `createWebSocketHandler`
+
+`WebSocketHandler` 인스턴스를 생성한다.
+
+```typescript
+function createWebSocketHandler(
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+  }) => Promise<unknown>,
+  jwtSecret: string | undefined,
+): WebSocketHandler;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `runMethod` | `(def: { serviceName, methodName, params, socket? }) => Promise<unknown>` | 서비스 메서드 실행 콜백 |
+| `jwtSecret` | `string \| undefined` | JWT 시크릿. `undefined`이면 `auth` 메시지 처리 시 에러를 던진다 |

package/docs/{types.md → types/service-server-options.md}

@@ -1,6 +1,4 @@
-# Types
-
-## `ServiceServerOptions`
+# ServiceServerOptions
 
 서버 생성 시 전달하는 옵션 인터페이스.
 
@@ -19,12 +17,14 @@ interface ServiceServerOptions {
 }
 ```
 
+## Fields
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `rootPath` | `string` | 서버 루트 경로. 정적 파일은 `{rootPath}/www/`에서 서빙되고, 설정 파일은 `{rootPath}/.config.json`에서 읽는다 |
 | `port` | `number` | 리스닝 포트 번호 |
 | `ssl` | `{ pfxBytes: Uint8Array; passphrase: string }` (optional) | HTTPS 설정. PFX 인증서 바이트와 비밀번호. 설정하지 않으면 HTTP로 동작한다 |
-| `auth` | `{ jwtSecret: string } \| false` (optional) | JWT 인증 설정. `{ jwtSecret }`이면 인증 활성화, `false`이면 인증 의도적 비활성화, `undefined`이면 인증 미사용 |
+| `auth` | `{ jwtSecret: string } \| false` (optional) | JWT 인증 설정. 세 가지 상태가 있다 |
 | `services` | `ServiceDefinition[]` | 등록할 서비스 정의 배열 |
 
 `auth` 필드의 세 가지 상태:

package/docs/{utils.md → utils/get-config.md}

@@ -1,6 +1,4 @@
-# Utils
-
-## `getConfig`
+# getConfig
 
 `.config.json` 파일을 읽고 캐싱한다. 파일 변경 시 자동 리로드되며, 캐시는 1시간 후 만료된다.
 
@@ -8,11 +6,15 @@
 async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
 | `filePath` | `string` | `.config.json` 파일의 절대 경로 |
 
-반환값: 파싱된 설정 객체. 파일이 존재하지 않으면 `undefined`.
+## Returns
+
+`Promise<TConfig | undefined>` — 파싱된 설정 객체. 파일이 존재하지 않으면 `undefined`.
 
 캐싱 동작:
 - `LazyGcMap`을 사용하여 캐시를 관리한다 (10분 간격 GC, 1시간 후 만료)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "14.0.49",
+  "version": "14.0.51",
   "description": "심플리즘 패키지 - 서비스 (server)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -31,11 +31,11 @@
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.20.0",
-    "@simplysm/orm-node": "14.0.49",
-    "@simplysm/core-node": "14.0.49",
-    "@simplysm/orm-common": "14.0.49",
-    "@simplysm/service-common": "14.0.49",
-    "@simplysm/core-common": "14.0.49"
+    "@simplysm/service-common": "14.0.51",
+    "@simplysm/core-node": "14.0.51",
+    "@simplysm/core-common": "14.0.51",
+    "@simplysm/orm-common": "14.0.51",
+    "@simplysm/orm-node": "14.0.51"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/auth/jwt-manager.ts

@@ -32,5 +32,5 @@ export async function verifyJwt<TAuthInfo = unknown>(
 }
 
 export function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo> {
-  return jose.decodeJwt(token) as AuthTokenPayload<TAuthInfo>;
+  return jose.decodeJwt(token);
 }

package/src/services/orm-service.ts

@@ -37,7 +37,7 @@ export const OrmService = defineService(
       if (config == null) {
         throw new Error(`ORM 설정을 찾을 수 없습니다: ${opt.configName}`);
       }
-      return { ...config, ...opt.config } as DbConnConfig;
+      return { ...config, ...opt.config };
     };
 
     const getConn = (connId: number): DbConn => {

package/src/transport/socket/websocket-handler.ts

@@ -80,21 +80,21 @@ export function createWebSocketHandler(
 
         return await serviceSocket.send(uuid, { name: "response", body: result });
       } else if (message.name === "evt:add") {
-        const { key, name, info } = message.body as { key: string; name: string; info: unknown };
+        const { key, name, info } = message.body;
         serviceSocket.addListener(key, name, info);
         return await serviceSocket.send(uuid, { name: "response" });
       } else if (message.name === "evt:remove") {
-        const { key } = message.body as { key: string };
+        const { key } = message.body;
         serviceSocket.removeListener(key);
         return await serviceSocket.send(uuid, { name: "response" });
       } else if (message.name === "evt:gets") {
-        const { name } = message.body as { name: string };
+        const { name } = message.body;
         const infos = Array.from(socketMap.values()).flatMap((subSock) =>
           subSock.getEventListeners(name),
         );
         return await serviceSocket.send(uuid, { name: "response", body: infos });
       } else if (message.name === "evt:emit") {
-        const { keys, data } = message.body as { keys: string[]; data: unknown };
+        const { keys, data } = message.body;
 
         await Promise.allSettled(
           Array.from(socketMap.values()).map(async (subSock) => {