@simplysm/service-common 14.0.49 → 14.0.50

package/README.md

@@ -21,71 +21,50 @@ npm install @simplysm/service-common
 
 ### Protocol
 
-| API | Type | Description |
-|-----|------|-------------|
-| `PROTOCOL_CONFIG` | const | 프로토콜 설정 상수 (최대 크기, 청킹 임계값, 청크 크기, GC 주기, 만료 시간) |
-| `ServiceMessage` | type | 양방향 메시지의 유니언 타입 |
-| `ServiceClientMessage` | type | 클라이언트 → 서버 메시지 유니언 |
-| `ServiceServerMessage` | type | 서버 → 클라이언트 메시지 유니언 |
-| `ServiceServerRawMessage` | type | 진행 상태를 포함한 서버 메시지 유니언 |
-| `ServiceProgressMessage` | interface | 청크 수신 진행 상태 알림 |
-| `ServiceErrorMessage` | interface | 서버 에러 알림 |
-| `ServiceAuthMessage` | interface | 클라이언트 인증 메시지 (토큰) |
-| `ServiceRequestMessage` | interface | 서비스 메서드 요청 |
-| `ServiceResponseMessage` | interface | 서비스 메서드 응답 |
-| `ServiceAddEventListenerMessage` | interface | 이벤트 리스너 추가 요청 |
-| `ServiceRemoveEventListenerMessage` | interface | 이벤트 리스너 제거 요청 |
-| `ServiceGetEventListenerInfosMessage` | interface | 이벤트 리스너 정보 목록 요청 |
-| `ServiceEmitEventMessage` | interface | 이벤트 발생 요청 |
-| `ServiceEventMessage` | interface | 서버 이벤트 알림 |
-| `ServiceProtocol` | interface | 바이너리 프로토콜 인코더/디코더 |
-| `ServiceMessageDecodeResult` | type | 디코딩 결과 유니언 (complete \| progress) |
-| `createServiceProtocol` | function | ServiceProtocol 인스턴스 생성 팩토리 |
-
-→ See [docs/protocol.md](./docs/protocol.md) for details.
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`PROTOCOL_CONFIG`](./docs/protocol/protocol-config.md) | const | 프로토콜 설정 상수 (최대 크기, 청킹 임계값, 청크 크기, GC 주기, 만료 시간) |
+| [`ServiceMessage`](./docs/protocol/service-message.md) | type | 양방향 메시지 유니언 (`ServiceClientMessage`, `ServiceServerMessage`, `ServiceServerRawMessage` 포함) |
+| [`ServiceProgressMessage`](./docs/protocol/service-progress-message.md) | interface | 청크 수신 진행 상태 알림 |
+| [`ServiceErrorMessage`](./docs/protocol/service-error-message.md) | interface | 서버 에러 알림 |
+| [`ServiceAuthMessage`](./docs/protocol/service-auth-message.md) | interface | 클라이언트 인증 메시지 (토큰) |
+| [`ServiceRequestMessage`](./docs/protocol/service-request-message.md) | interface | 서비스 메서드 요청 |
+| [`ServiceResponseMessage`](./docs/protocol/service-response-message.md) | interface | 서비스 메서드 응답 |
+| [`ServiceAddEventListenerMessage`](./docs/protocol/service-add-event-listener-message.md) | interface | 이벤트 리스너 추가 요청 |
+| [`ServiceRemoveEventListenerMessage`](./docs/protocol/service-remove-event-listener-message.md) | interface | 이벤트 리스너 제거 요청 |
+| [`ServiceGetEventListenerInfosMessage`](./docs/protocol/service-get-event-listener-infos-message.md) | interface | 이벤트 리스너 정보 목록 요청 |
+| [`ServiceEmitEventMessage`](./docs/protocol/service-emit-event-message.md) | interface | 이벤트 발생 요청 |
+| [`ServiceEventMessage`](./docs/protocol/service-event-message.md) | interface | 서버 이벤트 알림 |
+| [`createServiceProtocol`](./docs/protocol/create-service-protocol.md) | function | ServiceProtocol 인스턴스 생성 팩토리 (`ServiceProtocol`, `ServiceMessageDecodeResult` 포함) |
 
 ### Service Types
 
-| API | Type | Description |
-|-----|------|-------------|
-| `OrmService` | interface | DB 연결, 트랜잭션, 쿼리 실행 서비스 인터페이스 |
-| `DbConnOptions` | type | DB 연결 옵션 타입 |
-| `AutoUpdateService` | interface | 클라이언트 최신 버전 조회 서비스 인터페이스 |
-| `AppStructureService` | interface | 앱 구조 항목 조회 서비스 인터페이스 |
-
-→ See [docs/service-types.md](./docs/service-types.md) for details.
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`OrmService`](./docs/service-types/orm-service.md) | interface | DB 연결, 트랜잭션, 쿼리 실행 서비스 인터페이스 (`DbConnOptions` 포함) |
+| [`AutoUpdateService`](./docs/service-types/auto-update-service.md) | interface | 클라이언트 최신 버전 조회 서비스 인터페이스 |
+| [`AppStructureService`](./docs/service-types/app-structure-service.md) | interface | 앱 구조 항목 조회 서비스 인터페이스 |
 
 ### Types
 
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceUploadResult` | interface | 파일 업로드 결과 |
-
-→ See [docs/types.md](./docs/types.md) for details.
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`ServiceUploadResult`](./docs/types/service-upload-result.md) | interface | 파일 업로드 결과 |
 
 ### App Structure
 
-| API | Type | Description |
-|-----|------|-------------|
-| `AppStructureItem` | type | 앱 구조 항목 (그룹 또는 리프) |
-| `AppStructureGroupItem` | interface | 자식을 가진 그룹 메뉴 항목 |
-| `AppStructureLeafItem` | interface | 말단 메뉴 항목 (권한, URL 포함) |
-| `AppStructureSubPermission` | interface | 리프 항목의 하위 권한 정의 |
-| `FlatPermission` | interface | 플래트닝된 권한 결과 |
-| `isUsableModules` | function | 개별 항목의 모듈 접근 가능 여부 판단 |
-| `isUsableModulesChain` | function | 모듈 체인 전체의 접근 가능 여부 판단 |
-| `getFlatPermissions` | function | 앱 구조 트리를 플래트닝하여 권한 배열 반환 |
-
-→ See [docs/app-structure.md](./docs/app-structure.md) for details.
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`AppStructureItem`](./docs/app-structure/app-structure-item.md) | type | 앱 구조 항목 유니언 (`AppStructureGroupItem`, `AppStructureLeafItem`, `AppStructureSubPermission`, `FlatPermission` 포함) |
+| [`isUsableModules`](./docs/app-structure/is-usable-modules.md) | function | 단일 항목의 모듈 접근 가능 여부 판단 |
+| [`isUsableModulesChain`](./docs/app-structure/is-usable-modules-chain.md) | function | 모듈 체인 전체의 접근 가능 여부 판단 |
+| [`getFlatPermissions`](./docs/app-structure/get-flat-permissions.md) | function | 앱 구조 트리를 플래트닝하여 권한 배열 반환 |
 
 ### Events
 
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceEventDef` | interface | 타입 안전 이벤트 정의 인터페이스 |
-| `defineEvent` | function | 타입 안전 이벤트를 정의하는 팩토리 함수 |
-
-→ See [docs/events.md](./docs/events.md) for details.
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`defineEvent`](./docs/events/define-event.md) | function | 타입 안전 이벤트를 정의하는 팩토리 함수 (`ServiceEventDef` 포함) |
 
 ## Usage Examples
 

package/docs/app-structure/app-structure-item.md

@@ -0,0 +1,107 @@
+# AppStructureItem
+
+앱 구조 항목 유니언 타입. `children` 필드 유무로 그룹(`AppStructureGroupItem`)과 리프(`AppStructureLeafItem`)를 구분한다.
+
+```typescript
+export type AppStructureItem<TModule = unknown> =
+  | AppStructureGroupItem<TModule>
+  | AppStructureLeafItem<TModule>;
+```
+
+`TModule` 제네릭은 모듈 식별자 타입이다 (일반적으로 `string`).
+
+## Related Types
+
+### `AppStructureGroupItem`
+
+자식을 가진 그룹 메뉴 항목. `children` 필드로 하위 항목을 재귀적으로 포함한다.
+
+```typescript
+export interface AppStructureGroupItem<TModule> {
+  code: string;
+  title: string;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  icon?: string;
+  children: AppStructureItem<TModule>[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `string` | 항목 코드 (권한 코드 체인에 사용) |
+| `title` | `string` | 표시 이름 |
+| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건: 하나라도 있으면 접근 가능) |
+| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건: 모두 있어야 접근 가능) |
+| `icon` | `string?` | 아이콘 식별자 |
+| `children` | `AppStructureItem<TModule>[]` | 하위 메뉴 항목 배열 |
+
+### `AppStructureLeafItem`
+
+말단 메뉴 항목. 실제 페이지 URL과 권한(`perms`)을 가진다.
+
+```typescript
+export interface AppStructureLeafItem<TModule> {
+  code: string;
+  title: string;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  perms?: ("use" | "edit")[];
+  subPerms?: AppStructureSubPermission<TModule>[];
+  icon?: string;
+  url?: string;
+  isNotMenu?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `string` | 항목 코드 |
+| `title` | `string` | 표시 이름 |
+| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건) |
+| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건) |
+| `perms` | `("use" \| "edit")[]?` | 이 항목에 부여 가능한 권한 종류 |
+| `subPerms` | `AppStructureSubPermission<TModule>[]?` | 하위 권한 정의 배열 |
+| `icon` | `string?` | 아이콘 식별자 |
+| `url` | `string?` | 페이지 URL |
+| `isNotMenu` | `boolean?` | `true`이면 메뉴에 표시하지 않음 |
+
+### `AppStructureSubPermission`
+
+리프 항목의 하위 권한 정의. 각 하위 권한도 모듈 접근 제어를 가진다.
+
+```typescript
+export interface AppStructureSubPermission<TModule> {
+  code: string;
+  title: string;
+  modules?: TModule[];
+  requiredModules?: TModule[];
+  perms: ("use" | "edit")[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `string` | 하위 권한 코드 |
+| `title` | `string` | 하위 권한 표시 이름 |
+| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건) |
+| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건) |
+| `perms` | `("use" \| "edit")[]` | 부여 가능한 권한 종류 |
+
+### `FlatPermission`
+
+트리를 플래트닝한 권한 결과. [`getFlatPermissions`](./get-flat-permissions.md)의 반환 타입이다.
+
+```typescript
+export interface FlatPermission<TModule = unknown> {
+  titleChain: string[];
+  codeChain: string[];
+  modulesChain: TModule[][];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `titleChain` | `string[]` | 루트부터 현재 권한까지의 표시 이름 체인 (예: `["관리", "사용자"]`) |
+| `codeChain` | `string[]` | 루트부터 현재 권한까지의 코드 체인 (예: `["admin", "user", "use"]`) |
+| `modulesChain` | `TModule[][]` | 각 레벨에서 필요한 모듈 목록의 체인 |

package/docs/app-structure/get-flat-permissions.md

@@ -0,0 +1,57 @@
+# getFlatPermissions
+
+앱 구조 트리를 BFS로 순회하며 모듈 조건을 필터링하여 [`FlatPermission`](./app-structure-item.md)`[]`으로 플래트닝한다.
+
+```typescript
+export function getFlatPermissions<TModule>(
+  items: AppStructureItem<TModule>[],
+  usableModules: TModule[] | undefined,
+): FlatPermission<TModule>[];
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `items` | `AppStructureItem<TModule>[]` | 앱 구조 트리의 최상위 항목 배열 |
+| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록. `undefined`이면 모듈 조건이 없는 항목만 포함 |
+
+## Returns
+
+`FlatPermission<TModule>[]` — 모듈 조건을 만족하는 모든 권한의 플랫 목록.
+
+처리 로직:
+1. BFS로 트리를 순회하며 각 레벨의 `modules`(OR)와 `requiredModules`(AND) 조건을 체크
+2. 조건 미충족 항목은 하위 트리 전체를 건너뜀
+3. `AppStructureLeafItem`의 `perms`를 `codeChain`에 추가하여 `FlatPermission` 생성
+4. `subPerms`도 개별 모듈 조건을 체크하여 `FlatPermission`으로 변환
+
+## Usage
+
+```typescript
+import { getFlatPermissions } from "@simplysm/service-common";
+import type { AppStructureItem } from "@simplysm/service-common";
+
+const items: AppStructureItem<string>[] = [
+  {
+    code: "admin",
+    title: "관리",
+    children: [
+      { code: "user", title: "사용자", perms: ["use", "edit"] },
+    ],
+  },
+  {
+    code: "report",
+    title: "리포트",
+    modules: ["moduleA"],
+    perms: ["use"],
+  },
+];
+
+const perms = getFlatPermissions(items, ["moduleA"]);
+// [
+//   { titleChain: ["관리", "사용자"], codeChain: ["admin", "user", "use"], modulesChain: [] },
+//   { titleChain: ["관리", "사용자"], codeChain: ["admin", "user", "edit"], modulesChain: [] },
+//   { titleChain: ["리포트"], codeChain: ["report", "use"], modulesChain: [["moduleA"]] },
+// ]
+```

package/docs/app-structure/is-usable-modules-chain.md

@@ -0,0 +1,23 @@
+# isUsableModulesChain
+
+모듈 체인 전체의 접근 가능 여부를 판단한다. 트리의 각 레벨에서 모듈 조건을 모두 만족해야 한다.
+
+```typescript
+export function isUsableModulesChain<TModule>(
+  modulesChain: TModule[][],
+  requiredModulesChain: TModule[][],
+  usableModules: TModule[] | undefined,
+): boolean;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `modulesChain` | `TModule[][]` | 각 레벨의 OR 조건 모듈 배열 |
+| `requiredModulesChain` | `TModule[][]` | 각 레벨의 AND 조건 모듈 배열 |
+| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
+
+## Returns
+
+`boolean` — 모든 레벨의 조건을 만족하면 `true`. 하나라도 실패하면 `false`.

package/docs/app-structure/is-usable-modules.md

@@ -0,0 +1,42 @@
+# isUsableModules
+
+단일 항목의 모듈 접근 가능 여부를 판단한다.
+
+```typescript
+export function isUsableModules<TModule>(
+  modules: TModule[] | undefined,
+  requiredModules: TModule[] | undefined,
+  usableModules: TModule[] | undefined,
+): boolean;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `modules` | `TModule[] \| undefined` | OR 조건 모듈 목록. 하나라도 `usableModules`에 포함되면 통과 |
+| `requiredModules` | `TModule[] \| undefined` | AND 조건 모듈 목록. 모두 `usableModules`에 포함되어야 통과 |
+| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
+
+## Returns
+
+`boolean` — `modules`와 `requiredModules` 조건을 모두 만족하면 `true`.
+
+- `modules`가 `undefined`이거나 빈 배열이면 OR 조건은 자동 통과
+- `requiredModules`가 `undefined`이거나 빈 배열이면 AND 조건은 자동 통과
+- `usableModules`가 `undefined`이면 `modules`가 있을 때 `false`
+
+## Usage
+
+```typescript
+import { isUsableModules } from "@simplysm/service-common";
+
+// OR 조건: moduleA 또는 moduleB 중 하나라도 있으면 true
+isUsableModules(["moduleA", "moduleB"], undefined, ["moduleA"]); // true
+
+// AND 조건: 모두 있어야 true
+isUsableModules(undefined, ["moduleA", "moduleB"], ["moduleA"]); // false
+
+// 모듈 없음: 자동 통과
+isUsableModules(undefined, undefined, undefined); // true
+```

package/docs/{events.md → events/define-event.md}

@@ -1,6 +1,31 @@
-# Events
+# defineEvent
 
-## `ServiceEventDef`
+타입 안전한 서비스 이벤트를 정의하는 팩토리 함수.
+
+```typescript
+export function defineEvent<TInfo = unknown, TData = unknown>(
+  eventName: string,
+): ServiceEventDef<TInfo, TData>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `eventName` | `string` | 이벤트 이름 (고유해야 함) |
+
+| Type Parameter | Default | Description |
+|---------------|---------|-------------|
+| `TInfo` | `unknown` | 이벤트 필터링 조건의 타입. 구독 시 필터로 사용 |
+| `TData` | `unknown` | 이벤트 페이로드의 타입. 이벤트 발생/수신 시 데이터 타입 |
+
+## Returns
+
+`ServiceEventDef<TInfo, TData>` — 이벤트 정의 인스턴스.
+
+## Related Types
+
+### `ServiceEventDef`
 
 `defineEvent()`로 생성된 이벤트 정의. `$info`와 `$data`는 런타임에서 사용되지 않는 타입 전용 마커다.
 
@@ -18,32 +43,11 @@ export interface ServiceEventDef<TInfo = unknown, TData = unknown> {
 | `$info` | `TInfo` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 필터링 조건 타입 |
 | `$data` | `TData` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 페이로드 타입 |
 
-`TInfo`와 `TData`는 제네릭 파라미터로, `defineEvent<TInfo, TData>()` 호출 시 지정된 타입이 할당된다. 기본값은 `unknown`.
-
-## `defineEvent`
-
-타입 안전한 서비스 이벤트를 정의하는 팩토리 함수.
+## Usage
 
 ```typescript
-export function defineEvent<TInfo = unknown, TData = unknown>(
-  eventName: string,
-): ServiceEventDef<TInfo, TData>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `eventName` | `string` | 이벤트 이름 (고유해야 함) |
+import { defineEvent } from "@simplysm/service-common";
 
-| Type Parameter | Default | Description |
-|---------------|---------|-------------|
-| `TInfo` | `unknown` | 이벤트 필터링 조건의 타입. 구독 시 필터로 사용 |
-| `TData` | `unknown` | 이벤트 페이로드의 타입. 이벤트 발생/수신 시 데이터 타입 |
-
-반환: `ServiceEventDef<TInfo, TData>` 인스턴스.
-
-사용 예:
-
-```typescript
 // 서버에서 이벤트 정의 + 타입 export
 export const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
 
@@ -60,5 +64,5 @@ const key = await orderEvt.addListener({ orderId: 123 }, async (data) => {
 
 // 직접 호출 방식 (하위 호환)
 await server.emitEvent<typeof OrderUpdated>("OrderUpdated", (info) => info.orderId === 123, { status: "shipped" });
-await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => { ... });
+await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => { /* ... */ });
 ```

package/docs/protocol/create-service-protocol.md

@@ -0,0 +1,93 @@
+# createServiceProtocol
+
+ServiceProtocol 인스턴스를 생성하는 팩토리 함수.
+
+```typescript
+export function createServiceProtocol(): ServiceProtocol;
+```
+
+내부에 `LazyGcMap` 기반 청크 누적기를 캡슐화한다. 미완성 메시지는 60초 후 GC로 자동 정리된다. 사용 후 반드시 `dispose()`를 호출하여 GC 타이머를 해제해야 한다.
+
+## Returns
+
+`ServiceProtocol` — 인코딩/디코딩/해제 메서드를 포함한 프로토콜 인스턴스.
+
+## Related Types
+
+### `ServiceProtocol`
+
+바이너리 프로토콜 V2 인코더/디코더 인터페이스.
+
+```typescript
+export interface ServiceProtocol {
+  encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
+  decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
+  dispose(): void;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `encode` | `uuid: string, message: ServiceMessage` | `{ chunks: Bytes[]; totalSize: number }` | 메시지를 인코딩한다. 3MB 초과 시 300KB 청크로 자동 분할. `totalSize` > 100MB이면 `ArgumentError` 발생 |
+| `decode` | `bytes: Bytes` | `ServiceMessageDecodeResult<T>` | 청크를 디코딩한다. 청크가 모두 도착하면 `complete`, 아니면 `progress` 반환 |
+| `dispose` | 없음 | `void` | 내부 GC 타이머와 청크 누적기를 해제한다. 사용 후 반드시 호출 |
+
+헤더 구조 (28바이트, Big Endian):
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 0 | 16 | UUID (바이너리) |
+| 16 | 8 | TotalSize (uint64, 상위 4바이트 = 0) |
+| 24 | 4 | Index (uint32) |
+
+### `ServiceMessageDecodeResult`
+
+메시지 디코딩 결과 유니언 타입. `type` 필드로 분기한다.
+
+```typescript
+export type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
+  | { type: "complete"; uuid: string; message: TMessage }
+  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
+```
+
+**Variant: `complete`** — 모든 청크가 도착하여 메시지 재조립이 완료된 상태.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"complete"` | discriminant |
+| `uuid` | `string` | 메시지 UUID |
+| `message` | `TMessage` | 재조립된 메시지 |
+
+**Variant: `progress`** — 청크 메시지 수신 진행 중.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"progress"` | discriminant |
+| `uuid` | `string` | 메시지 UUID |
+| `totalSize` | `number` | 전체 크기 (바이트) |
+| `completedSize` | `number` | 수신 완료된 크기 (바이트) |
+
+## Usage
+
+```typescript
+import { createServiceProtocol } from "@simplysm/service-common";
+
+const protocol = createServiceProtocol();
+
+// 메시지 인코딩 (3MB 초과 시 자동 청킹)
+const { chunks, totalSize } = protocol.encode(uuid, {
+  name: "OrmService.connect",
+  body: [{ configName: "default" }],
+});
+
+// 메시지 디코딩 (청크 자동 재조립)
+for (const chunk of chunks) {
+  const result = protocol.decode(chunk);
+  if (result.type === "complete") {
+    // result.message: 재조립된 메시지
+  }
+}
+
+// 사용 후 반드시 해제
+protocol.dispose();
+```

package/docs/protocol/protocol-config.md

@@ -0,0 +1,21 @@
+# PROTOCOL_CONFIG
+
+서비스 프로토콜 설정 상수.
+
+```typescript
+export const PROTOCOL_CONFIG = {
+  MAX_TOTAL_SIZE: 100 * 1024 * 1024,
+  SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024,
+  CHUNK_SIZE: 300 * 1024,
+  GC_INTERVAL: 10 * 1000,
+  EXPIRE_TIME: 60 * 1000,
+} as const;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `MAX_TOTAL_SIZE` | `number` | 단일 메시지의 최대 허용 크기 (100MB). 초과 시 `ArgumentError` 발생 |
+| `SPLIT_MESSAGE_SIZE` | `number` | 이 크기를 초과하면 자동으로 청크 분할 (3MB) |
+| `CHUNK_SIZE` | `number` | 분할된 각 청크의 크기 (300KB) |
+| `GC_INTERVAL` | `number` | 내부 청크 누적기의 가비지 컬렉션 주기 (10초, 밀리초 단위) |
+| `EXPIRE_TIME` | `number` | 미완성 청크 메시지의 만료 시간 (60초). 이 시간 내에 모든 청크가 도착하지 않으면 제거 |

package/docs/protocol/service-add-event-listener-message.md

@@ -0,0 +1,23 @@
+# ServiceAddEventListenerMessage
+
+클라이언트가 보내는 이벤트 리스너 추가 메시지.
+
+```typescript
+export interface ServiceAddEventListenerMessage {
+  name: "evt:add";
+  body: {
+    key: string;
+    name: string;
+    info: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:add"` | 고정 문자열 discriminant |
+| `body.key` | `string` | 리스너 키 (UUID). `ServiceRemoveEventListenerMessage`에서 사용 |
+| `body.name` | `string` | 이벤트 이름 (`ServiceEventDef.eventName`) |
+| `body.info` | `unknown` | 이벤트 발생 시 필터링을 위한 추가 리스너 정보 |

package/docs/protocol/service-auth-message.md

@@ -0,0 +1,17 @@
+# ServiceAuthMessage
+
+클라이언트가 보내는 인증 메시지.
+
+```typescript
+export interface ServiceAuthMessage {
+  name: "auth";
+  body: string;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"auth"` | 고정 문자열 discriminant |
+| `body` | `string` | 인증 토큰 |

package/docs/protocol/service-emit-event-message.md

@@ -0,0 +1,21 @@
+# ServiceEmitEventMessage
+
+클라이언트가 보내는 이벤트 발생 메시지.
+
+```typescript
+export interface ServiceEmitEventMessage {
+  name: "evt:emit";
+  body: {
+    keys: string[];
+    data: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:emit"` | 고정 문자열 discriminant |
+| `body.keys` | `string[]` | 대상 리스너 키 목록 |
+| `body.data` | `unknown` | 이벤트 데이터 |

package/docs/protocol/service-error-message.md

@@ -0,0 +1,29 @@
+# ServiceErrorMessage
+
+서버가 보내는 에러 알림 메시지.
+
+```typescript
+export interface ServiceErrorMessage {
+  name: "error";
+  body: {
+    name: string;
+    message: string;
+    code: string;
+    stack?: string;
+    detail?: unknown;
+    cause?: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"error"` | 고정 문자열 discriminant |
+| `body.name` | `string` | 에러 이름 (클래스명) |
+| `body.message` | `string` | 에러 메시지 |
+| `body.code` | `string` | 에러 코드 |
+| `body.stack` | `string?` | 스택 트레이스 (선택) |
+| `body.detail` | `unknown?` | 추가 상세 정보 (선택) |
+| `body.cause` | `unknown?` | 원인 에러 (선택) |

package/docs/protocol/service-event-message.md

@@ -0,0 +1,21 @@
+# ServiceEventMessage
+
+서버가 보내는 이벤트 알림 메시지.
+
+```typescript
+export interface ServiceEventMessage {
+  name: "evt:on";
+  body: {
+    keys: string[];
+    data: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:on"` | 고정 문자열 discriminant |
+| `body.keys` | `string[]` | 대상 리스너 키 목록 |
+| `body.data` | `unknown` | 이벤트 데이터 |

package/docs/protocol/service-get-event-listener-infos-message.md

@@ -0,0 +1,19 @@
+# ServiceGetEventListenerInfosMessage
+
+클라이언트가 보내는 이벤트 리스너 정보 목록 요청 메시지.
+
+```typescript
+export interface ServiceGetEventListenerInfosMessage {
+  name: "evt:gets";
+  body: {
+    name: string;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:gets"` | 고정 문자열 discriminant |
+| `body.name` | `string` | 조회할 이벤트 이름 |