@simplysm/service-server 14.0.23 → 14.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "14.0.23",
+  "version": "14.0.25",
   "description": "심플리즘 패키지 - 서비스 (server)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,8 +14,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "docs"
+    "src"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -31,11 +30,11 @@
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.20.0",
-    "@simplysm/orm-common": "14.0.23",
-    "@simplysm/core-common": "14.0.23",
-    "@simplysm/orm-node": "14.0.23",
-    "@simplysm/core-node": "14.0.23",
-    "@simplysm/service-common": "14.0.23"
+    "@simplysm/core-node": "14.0.25",
+    "@simplysm/core-common": "14.0.25",
+    "@simplysm/orm-node": "14.0.25",
+    "@simplysm/orm-common": "14.0.25",
+    "@simplysm/service-common": "14.0.25"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/README.md

@@ -1,174 +0,0 @@
-# @simplysm/service-server
-
-Fastify-based RPC server with WebSocket support, JWT authentication, service definitions, file upload/download, static file serving, and built-in ORM/auto-update services. Depends on `@simplysm/service-common` for shared protocol and types.
-
-## Installation
-
-```bash
-npm install @simplysm/service-server
-```
-
-## API Overview
-
-### Server Options
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceServerOptions` | `interface` | Server configuration (rootPath, port, SSL, auth, services) |
-
-→ See [docs/server-options.md](./docs/server-options.md) for details.
-
-### Authentication (JWT)
-| API | Type | Description |
-|-----|------|-------------|
-| `AuthTokenPayload` | `interface` | JWT token payload with roles and custom data |
-| `signJwt` | `function` | Signs a JWT token (HS256, 12h expiry) |
-| `verifyJwt` | `function` | Verifies a JWT token |
-| `decodeJwt` | `function` | Decodes a JWT token without verification |
-
-→ See [docs/auth.md](./docs/auth.md) for details.
-
-### Service Definition/Context
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceContext` | `interface` | Service execution context (server, socket, auth, config) |
-| `createServiceContext` | `function` | Creates a service context instance |
-| `getServiceAuthPermissions` | `function` | Reads auth permissions from an auth-wrapped function |
-| `auth` | `function` | Authentication wrapper for service factories and methods |
-| `ServiceDefinition` | `interface` | Service definition with name and factory |
-| `defineService` | `function` | Defines a named service with a factory function |
-| `ServiceMethods` | `type` | Extracts method signatures from a ServiceDefinition |
-
-→ See [docs/service-definition.md](./docs/service-definition.md) for details.
-
-### Service Executor
-| API | Type | Description |
-|-----|------|-------------|
-| `executeServiceMethod` | `function` | Executes a service method with auth checking |
-
-→ See [docs/service-executor.md](./docs/service-executor.md) for details.
-
-### WebSocket Handler
-| API | Type | Description |
-|-----|------|-------------|
-| `WebSocketHandler` | `interface` | Multi-connection WebSocket handler with event broadcasting |
-| `createWebSocketHandler` | `function` | Creates a WebSocket handler instance |
-
-→ See [docs/websocket-handler.md](./docs/websocket-handler.md) for details.
-
-### Service Socket
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceSocket` | `interface` | Single WebSocket connection with protocol and events |
-| `createServiceSocket` | `function` | Creates a service socket instance |
-
-→ See [docs/service-socket.md](./docs/service-socket.md) for details.
-
-### HTTP Handlers
-| API | Type | Description |
-|-----|------|-------------|
-| `handleHttpRequest` | `function` | Handles HTTP RPC requests (GET/POST) |
-| `handleUpload` | `function` | Handles multipart file uploads |
-| `handleStaticFile` | `function` | Serves static files with security guards |
-
-→ See [docs/http-handlers.md](./docs/http-handlers.md) for details.
-
-### Protocol Wrapper
-| API | Type | Description |
-|-----|------|-------------|
-| `ServerProtocolWrapper` | `interface` | Server-side protocol wrapper with worker thread offloading |
-| `createServerProtocolWrapper` | `function` | Creates a server protocol wrapper instance |
-
-→ See [docs/protocol-wrapper.md](./docs/protocol-wrapper.md) for details.
-
-### ORM/AutoUpdate Services
-| API | Type | Description |
-|-----|------|-------------|
-| `OrmService` | `const (ServiceDefinition)` | Built-in ORM service definition |
-| `OrmServiceType` | `type` | ORM service method signatures |
-| `AutoUpdateService` | `const (ServiceDefinition)` | Built-in auto-update service definition |
-| `AutoUpdateServiceType` | `type` | Auto-update service method signatures |
-
-→ See [docs/built-in-services.md](./docs/built-in-services.md) for details.
-
-### Config Manager
-| API | Type | Description |
-|-----|------|-------------|
-| `getConfig` | `function` | Loads JSON config with file-watching and caching |
-
-→ See [docs/config-manager.md](./docs/config-manager.md) for details.
-
-### Legacy V1
-| API | Type | Description |
-|-----|------|-------------|
-| `handleV1Connection` | `function` | V1 legacy WebSocket handler (auto-update only) |
-
-→ See [docs/legacy-v1.md](./docs/legacy-v1.md) for details.
-
-### Main ServiceServer
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceServer` | `class` | Main server class (Fastify + WebSocket + auth) |
-| `createServiceServer` | `function` | Factory function to create a ServiceServer |
-
-→ See [docs/service-server.md](./docs/service-server.md) for details.
-
-## Usage Examples
-
-### Basic Server Setup
-
-```typescript
-import { createServiceServer, defineService, auth } from "@simplysm/service-server";
-
-const GreetService = defineService("Greet", (ctx) => ({
-  hello(name: string) {
-    return \`Hello, \${name}!\`;
-  },
-  secret: auth(["admin"], (msg: string) => {
-    return \`Secret for \${ctx.authInfo}: \${msg}\`;
-  }),
-}));
-
-const server = createServiceServer({
-  rootPath: process.cwd(),
-  port: 3000,
-  auth: { jwtSecret: "my-secret" },
-  services: [GreetService],
-});
-
-await server.listen();
-```
-
-### JWT Authentication
-
-```typescript
-import { signJwt, verifyJwt } from "@simplysm/service-server";
-
-const token = await signJwt("my-secret", {
-  roles: ["admin"],
-  data: { userId: 1 },
-});
-
-const payload = await verifyJwt("my-secret", token);
-```
-
-### Event Broadcasting
-
-```typescript
-import { defineEvent } from "@simplysm/service-common";
-
-const NotifyEvent = defineEvent<{ userId: number }, { text: string }>("Notify");
-await server.emitEvent(NotifyEvent, (info) => info.userId === 42, { text: "Hello!" });
-```
-
-### Built-in ORM Service
-
-```typescript
-import { createServiceServer, OrmService } from "@simplysm/service-server";
-
-const server = createServiceServer({
-  rootPath: process.cwd(),
-  port: 3000,
-  auth: { jwtSecret: "my-secret" },
-  services: [OrmService],
-});
-```

package/docs/auth.md

@@ -1,74 +0,0 @@
-# Authentication (JWT)
-
-## `AuthTokenPayload`
-
-JWT token payload extending `JWTPayload` from `jose`. Contains roles and custom authentication data.
-
-```typescript
-export interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
-  roles: string[];
-  data: TAuthInfo;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `roles` | `string[]` | User roles for permission checking |
-| `data` | `TAuthInfo` | Custom authentication data (user info, etc.) |
-| *(inherited from JWTPayload)* | | Standard JWT claims (`iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`) |
-
-## `signJwt`
-
-Signs a JWT token using HS256 algorithm with 12-hour expiration.
-
-```typescript
-export async function signJwt<TAuthInfo = unknown>(
-  jwtSecret: string,
-  payload: AuthTokenPayload<TAuthInfo>,
-): Promise<string>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `jwtSecret` | `string` | JWT signing secret |
-| `payload` | `AuthTokenPayload<TAuthInfo>` | Token payload with roles and data |
-
-**Returns:** `Promise<string>` -- Signed JWT token string.
-
-## `verifyJwt`
-
-Verifies a JWT token and returns the decoded payload. Throws on expired or invalid tokens.
-
-```typescript
-export async function verifyJwt<TAuthInfo = unknown>(
-  jwtSecret: string,
-  token: string,
-): Promise<AuthTokenPayload<TAuthInfo>>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `jwtSecret` | `string` | JWT verification secret |
-| `token` | `string` | JWT token string to verify |
-
-**Returns:** `Promise<AuthTokenPayload<TAuthInfo>>` -- Decoded token payload.
-
-**Throws:**
-- `Error("토큰이 만료되었습니다.")` when the token has expired
-- `Error("유효하지 않은 토큰입니다.")` for any other verification failure
-
-## `decodeJwt`
-
-Decodes a JWT token without verification. Useful for reading claims before verification.
-
-```typescript
-export function decodeJwt<TAuthInfo = unknown>(
-  token: string,
-): AuthTokenPayload<TAuthInfo>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `token` | `string` | JWT token string to decode |
-
-**Returns:** `AuthTokenPayload<TAuthInfo>` -- Decoded token payload (not verified).

package/docs/built-in-services.md

@@ -1,61 +0,0 @@
-# ORM/AutoUpdate Services
-
-## `OrmService`
-
-Built-in ORM service definition. Provides database connection, transaction management, and query execution over the WebSocket RPC layer. Requires authentication (wrapped with `auth()`).
-
-```typescript
-export const OrmService: ServiceDefinition;
-```
-
-The ORM service is registered with the name `"Orm"` and requires WebSocket transport (HTTP is not supported).
-
-Database connections are tracked per socket. When a WebSocket connection closes, all associated DB connections are automatically cleaned up.
-
-Methods (matching the `OrmService` interface from `@simplysm/service-common`):
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | Gets database info from server config |
-| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | Opens a DB connection. Returns connection ID |
-| `close` | `connId: number` | `Promise<void>` | Closes a DB connection |
-| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | Begins a transaction |
-| `commitTransaction` | `connId: number` | `Promise<void>` | Commits a transaction |
-| `rollbackTransaction` | `connId: number` | `Promise<void>` | Rolls back a transaction |
-| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | Executes a parameterized query |
-| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | Executes query definitions with optional result parsing |
-| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | Performs bulk insert |
-
-Configuration: Reads from the `"orm"` section of the server config file (`.config.json`).
-
-## `OrmServiceType`
-
-Type alias for the ORM service methods. Useful for client-side type sharing.
-
-```typescript
-export type OrmServiceType = ServiceMethods<typeof OrmService>;
-```
-
-## `AutoUpdateService`
-
-Built-in auto-update service definition. Provides version lookup for client applications. Does not require authentication.
-
-```typescript
-export const AutoUpdateService: ServiceDefinition;
-```
-
-Registered with the name `"AutoUpdate"`. Scans `{clientPath}/{platform}/updates/` for versioned files (`.exe` for desktop, `.apk` for Android).
-
-Methods:
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Returns the latest version info for the given platform. Uses `semver.maxSatisfying` to find the highest version |
-
-## `AutoUpdateServiceType`
-
-Type alias for the auto-update service methods.
-
-```typescript
-export type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
-```

package/docs/config-manager.md

@@ -1,24 +0,0 @@
-# Config Manager
-
-## `getConfig`
-
-Loads a JSON configuration file with automatic caching and file-watching for live reload.
-
-```typescript
-export async function getConfig<TConfig>(
-  filePath: string,
-): Promise<TConfig | undefined>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | `string` | Absolute path to the JSON config file |
-
-**Returns:** `Promise<TConfig | undefined>` -- Parsed config object, or `undefined` if the file does not exist.
-
-Behavior:
-- **Caching:** Uses `LazyGcMap` with 10-minute GC interval and 1-hour expiry
-- **File watching:** Registers a file watcher on first load. Config is automatically reloaded when the file changes
-- **Expiry:** When a cache entry expires, the associated file watcher is cleaned up
-- **Deletion:** If the config file is deleted, the cache entry and watcher are removed
-- Used internally by `ServiceContext.getConfig()` to load root and client config files

package/docs/http-handlers.md

@@ -1,83 +0,0 @@
-# HTTP Handlers
-
-## `handleHttpRequest`
-
-Handles HTTP RPC requests. Supports both GET (with JSON query parameter) and POST (with JSON array body) methods.
-
-```typescript
-export 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 request (expects `/:service/:method` route params) |
-| `reply` | `FastifyReply` | Fastify reply |
-| `jwtSecret` | `string \| undefined` | JWT secret for token verification |
-| `runMethod` | callback | Service method executor |
-
-Request requirements:
-- Header `x-sd-client-name` is required
-- GET: requires `?json=<encoded-params>` query parameter
-- POST: requires JSON array body
-- Authorization header (optional): `Bearer <token>`
-
-## `handleUpload`
-
-Handles multipart file uploads. Saves files to `{rootPath}/www/uploads/` with UUID-based filenames.
-
-```typescript
-export async function handleUpload(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  jwtSecret: string | undefined,
-): Promise<void>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify multipart request |
-| `reply` | `FastifyReply` | Fastify reply |
-| `rootPath` | `string` | Server root path |
-| `jwtSecret` | `string \| undefined` | JWT secret for authentication |
-
-Behavior:
-- Requires multipart request and valid Authorization header
-- Saves each file with a UUID filename preserving the original extension
-- Returns `ServiceUploadResult[]` on success
-- Cleans up all files on error (both partially written and already saved)
-
-## `handleStaticFile`
-
-Serves static files from `{rootPath}/www/` with security guards.
-
-```typescript
-export async function handleStaticFile(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  urlPath: string,
-): Promise<void>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify request |
-| `reply` | `FastifyReply` | Fastify reply |
-| `rootPath` | `string` | Server root path |
-| `urlPath` | `string` | Decoded URL path (without leading slash) |
-
-Security:
-- Path traversal attack prevention (rejects paths outside `{rootPath}/www/`)
-- Hidden file access denied (files starting with `.` return 403)
-- Directory requests redirect to add trailing slash, then serve `index.html`

package/docs/legacy-v1.md

@@ -1,25 +0,0 @@
-# Legacy V1
-
-## `handleV1Connection`
-
-Handles V1 legacy WebSocket connections. Only supports the `SdAutoUpdateService.getLastVersion` command. All other requests return an upgrade-required error.
-
-```typescript
-export function handleV1Connection(
-  socket: WebSocket,
-  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
-  clientNameSetter?: (clientName: string | undefined) => void,
-): void;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `WebSocket` (from `ws`) | Raw WebSocket connection |
-| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update method implementations |
-| `clientNameSetter` | `((clientName: string \| undefined) => void)?` | Callback to set the legacy client name on the context |
-
-V1 protocol:
-- Sends `{ name: "connected" }` on connection
-- Expects JSON messages with `{ uuid, command, params, clientName? }` format
-- Responds with `{ name: "response", reqUuid, state: "success"|"error", body }` format
-- Only `SdAutoUpdateService.getLastVersion` is supported; all other commands return `UPGRADE_REQUIRED` error

package/docs/protocol-wrapper.md

@@ -1,37 +0,0 @@
-# Protocol Wrapper
-
-## `ServerProtocolWrapper`
-
-Server-side protocol wrapper that automatically offloads heavy message encoding/decoding to a worker thread. Light operations are processed on the main thread.
-
-```typescript
-export interface ServerProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `encode` | `uuid: string, message: ServiceMessage` | `Promise<{ chunks: Bytes[]; totalSize: number }>` | Encodes a message. Offloads to worker for messages with `Uint8Array` bodies |
-| `decode` | `bytes: Bytes` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | Decodes binary data. Offloads to worker for payloads > 30KB |
-| `dispose` | none | `void` | Disposes the underlying protocol's GC timer |
-
-## `createServerProtocolWrapper`
-
-Creates a `ServerProtocolWrapper` instance.
-
-```typescript
-export function createServerProtocolWrapper(): ServerProtocolWrapper;
-```
-
-**Returns:** `ServerProtocolWrapper`
-
-Worker thread details:
-- Uses `@simplysm/core-node` `Worker` (Node.js `worker_threads`)
-- Shared singleton worker instance across all protocol wrappers
-- Worker memory limit: 4096 MB (old generation)
-- Size threshold for worker offloading: 30KB
-- Encode uses worker when body contains `Uint8Array` elements
-- Decode uses worker when total bytes exceed 30KB

package/docs/server-options.md

@@ -1,31 +0,0 @@
-# Server Options
-
-## `ServiceServerOptions`
-
-Server configuration options.
-
-```typescript
-export interface ServiceServerOptions {
-  rootPath: string;
-  port: number;
-  ssl?: {
-    pfxBytes: Uint8Array;
-    passphrase: string;
-  };
-  auth?: {
-    jwtSecret: string;
-  } | false;
-  services: ServiceDefinition[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `rootPath` | `string` | Root directory path. Static files are served from `{rootPath}/www/`, config loaded from `{rootPath}/.config.json` |
-| `port` | `number` | Server listen port |
-| `ssl` | `{ pfxBytes: Uint8Array; passphrase: string }?` | SSL/TLS configuration using PFX certificate |
-| `ssl.pfxBytes` | `Uint8Array` | PFX certificate file contents |
-| `ssl.passphrase` | `string` | PFX certificate passphrase |
-| `auth` | `{ jwtSecret: string } \| false` | Authentication configuration. `undefined` = auto-detect (error if auth-wrapped services exist). `false` = explicitly disable auth checks. `{ jwtSecret }` = enable JWT auth |
-| `auth.jwtSecret` | `string` | JWT signing/verification secret (HS256) |
-| `services` | `ServiceDefinition[]` | Array of service definitions to register |

package/docs/service-definition.md

@@ -1,151 +0,0 @@
-# Service Definition/Context
-
-## `ServiceContext`
-
-Service execution context providing access to the server, socket, authentication info, and configuration.
-
-```typescript
-export 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>;
-}
-```
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `server` | `ServiceServer<TAuthInfo>` | The server instance |
-| `socket` | `ServiceSocket?` | WebSocket connection (undefined for HTTP requests) |
-| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }?` | HTTP request context (undefined for WebSocket requests) |
-| `legacy` | `{ clientName?: string }?` | V1 legacy context (auto-update only) |
-| `authInfo` | `TAuthInfo \| undefined` (getter) | Authenticated user data from socket or HTTP auth token |
-| `clientName` | `string \| undefined` (getter) | Client name from socket, HTTP, or legacy context. Validates against path traversal |
-| `clientPath` | `string \| undefined` (getter) | Resolved client path: `{rootPath}/www/{clientName}` |
-| `getConfig<T>(section)` | `(section: string) => Promise<T>` | Loads config section from root and client `.config.json` files (merged) |
-
-## `createServiceContext`
-
-Creates a `ServiceContext` instance.
-
-```typescript
-export 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>` | The server instance |
-| `socket` | `ServiceSocket?` | WebSocket connection |
-| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }?` | HTTP request context |
-| `legacy` | `{ clientName?: string }?` | V1 legacy context |
-
-## `getServiceAuthPermissions`
-
-Reads auth permissions from a function wrapped by `auth()`. Returns `undefined` for unwrapped functions.
-
-```typescript
-export function getServiceAuthPermissions(fn: Function): string[] | undefined;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `fn` | `Function` | The function to check for auth permissions |
-
-**Returns:** `string[] | undefined` -- Permission array if auth-wrapped, `undefined` otherwise.
-
-## `auth`
-
-Authentication wrapper for service factories and methods. Marks functions as requiring authentication, optionally with specific role permissions.
-
-```typescript
-// No role restriction (login required)
-export function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
-
-// Role restriction (specific roles required)
-export 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) => ({ ... }))` -- All methods require specific roles
-- **Method level:** `auth(() => result)` -- Specific method requires login
-- **Method level with roles:** `auth(["admin"], () => result)` -- Specific method requires specific roles
-
-## `ServiceDefinition`
-
-Service definition with a name and factory function.
-
-```typescript
-export interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
-  name: string;
-  factory: (ctx: ServiceContext) => TMethods;
-  authPermissions?: string[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Service name (used in RPC routing) |
-| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function that creates service methods from a context |
-| `authPermissions` | `string[]?` | Service-level auth permissions (extracted from `auth()` wrapper) |
-
-## `defineService`
-
-Defines a named service with a factory function.
-
-```typescript
-export function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
-  name: string,
-  factory: (ctx: ServiceContext) => TMethods,
-): ServiceDefinition<TMethods>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Service name |
-| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function creating service methods |
-
-**Returns:** `ServiceDefinition<TMethods>`
-
-**Example:**
-
-```typescript
-const UserService = defineService("User", auth((ctx) => ({
-  getProfile: () => ctx.authInfo,
-  adminOnly: auth(["admin"], () => "admin-data"),
-})));
-```
-
-## `ServiceMethods`
-
-Type utility that extracts method signatures from a `ServiceDefinition`. Useful for sharing types between server and client.
-
-```typescript
-export type ServiceMethods<TDefinition> =
-  TDefinition extends ServiceDefinition<infer M> ? M : never;
-```
-
-**Example:**
-
-```typescript
-export type UserServiceType = ServiceMethods<typeof UserService>;
-// Client: client.getService<UserServiceType>("User");
-```

package/docs/service-executor.md

@@ -1,42 +0,0 @@
-# Service Executor
-
-## `executeServiceMethod`
-
-Executes a service method with full validation and authentication checking.
-
-```typescript
-export 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` | The server instance (used to find service definitions and check auth config) |
-| `def.serviceName` | `string` | Service name to look up |
-| `def.methodName` | `string` | Method name to invoke |
-| `def.params` | `unknown[]` | Method parameters |
-| `def.socket` | `ServiceSocket?` | WebSocket connection (for WebSocket requests) |
-| `def.http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload }?` | HTTP context (for HTTP requests) |
-
-**Returns:** `Promise<unknown>` -- The method return value.
-
-**Execution flow:**
-1. Finds the service definition by name (throws if not found)
-2. Validates client name for path traversal attacks
-3. Creates a `ServiceContext`
-4. Calls the factory to create the method object
-5. Looks up the method by name (throws if not a function)
-6. Checks authentication:
-   - Method-level `auth()` permissions take precedence over service-level
-   - If `server.options.auth === undefined` and auth is required, throws configuration error
-   - If `server.options.auth === false`, skips all auth checks
-   - Otherwise, verifies `authTokenPayload` exists and has required roles
-7. Invokes the method with parameters

package/docs/service-server.md

@@ -1,80 +0,0 @@
-# Main ServiceServer
-
-## `ServiceServer`
-
-Main server class built on Fastify with WebSocket support, JWT authentication, and graceful shutdown. Extends `EventEmitter` with `ready` and `close` events.
-
-```typescript
-export class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
-  ready: void;
-  close: void;
-}> {
-  constructor(options: ServiceServerOptions);
-}
-```
-
-### Events
-
-| Event | Data Type | Description |
-|-------|-----------|-------------|
-| `ready` | `void` | Emitted when the server starts listening |
-| `close` | `void` | Emitted when the server is closed |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `options` | `ServiceServerOptions` (readonly) | Server configuration options |
-| `fastify` | `FastifyInstance` (readonly) | The underlying Fastify instance for custom route registration |
-| `isOpen` | `boolean` | Whether the server is currently listening |
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `listen` | `listen(): Promise<void>` | Starts the server. Registers all plugins, routes, and WebSocket handlers. Listens on `0.0.0.0:{port}` |
-| `close` | `close(): Promise<void>` | Closes all WebSocket connections and stops the Fastify server |
-| `emitEvent` | `emitEvent<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>` | Broadcasts an event to connected clients matching the info selector |
-| `signAuthToken` | `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>` | Signs a JWT token using the server's secret |
-| `verifyAuthToken` | `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>` | Verifies a JWT token using the server's secret |
-
-### Registered Routes
-
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/api/:service/:method` | GET, POST | HTTP RPC endpoint |
-| `/upload` | POST | Multipart file upload endpoint |
-| `/` | WebSocket | WebSocket endpoint (V1 and V2) |
-| `/ws` | WebSocket | WebSocket endpoint (V1 and V2) |
-| `/*` | GET, POST, PUT, DELETE, PATCH, HEAD | Static file handler |
-
-### Registered Plugins
-
-- `@fastify/websocket` -- WebSocket support
-- `@fastify/helmet` -- Security headers (CSP configured for permissive defaults)
-- `@fastify/multipart` -- File upload support
-- `@fastify/static` -- Static file serving (manual serving via handler)
-- `@fastify/cors` -- Cross-origin support (allows all origins)
-
-### Graceful Shutdown
-
-Registers `SIGINT` and `SIGTERM` handlers that:
-1. Close all WebSocket connections
-2. Stop the Fastify server
-3. Force exit after 10 seconds if shutdown hangs
-
-## `createServiceServer`
-
-Factory function to create a `ServiceServer` instance.
-
-```typescript
-export function createServiceServer<TAuthInfo = unknown>(
-  options: ServiceServerOptions,
-): ServiceServer<TAuthInfo>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `options` | `ServiceServerOptions` | Server configuration options |
-
-**Returns:** `ServiceServer<TAuthInfo>`

package/docs/service-socket.md

@@ -1,73 +0,0 @@
-# Service Socket
-
-## `ServiceSocket`
-
-Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keepalive, and event listener tracking.
-
-```typescript
-export 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;
-}
-```
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `connectedAtDateTime` | `DateTime` (readonly) | Timestamp when the connection was established |
-| `clientName` | `string` (readonly) | Client identifier name |
-| `connReq` | `FastifyRequest` (readonly) | Original Fastify request object |
-| `authTokenPayload` | `AuthTokenPayload?` | Authenticated token payload (set via auth message) |
-
-### Methods
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `close` | none | `void` | Terminates the WebSocket connection |
-| `send` | `uuid: string, msg: ServiceServerMessage` | `Promise<number>` | Sends a message to the client. Returns total bytes sent |
-| `addListener` | `key: string, eventName: string, info: unknown` | `void` | Registers an event listener |
-| `removeListener` | `key: string` | `void` | Removes an event listener by key |
-| `getEventListeners` | `eventName: string` | `Array<{ key: string; info: unknown }>` | Gets all listeners for an event name |
-| `filterEventTargetKeys` | `targetKeys: string[]` | `string[]` | Filters target keys that exist in this socket's listeners |
-| `on("error")` | `handler: (err: Error) => void` | `void` | Registers error event handler |
-| `on("close")` | `handler: (code: number) => void` | `void` | Registers close event handler |
-| `on("message")` | `handler: (data: { uuid: string; msg: ServiceClientMessage }) => void` | `void` | Registers message event handler |
-
-## `createServiceSocket`
-
-Creates a `ServiceSocket` instance wrapping a raw WebSocket.
-
-```typescript
-export function createServiceSocket(
-  socket: WebSocket,
-  clientId: string,
-  clientName: string,
-  connReq: FastifyRequest,
-): ServiceSocket;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `WebSocket` (from `ws`) | Raw WebSocket connection |
-| `clientId` | `string` | Client unique identifier |
-| `clientName` | `string` | Client name |
-| `connReq` | `FastifyRequest` | Original request object |
-
-Internal behavior:
-- Ping interval: 5 seconds (terminates connection if no pong response)
-- Responds to client ping (`0x01`) with pong (`0x02`)
-- Uses `ServerProtocolWrapper` for encode/decode
-- Reports chunk progress back to client during message reassembly

package/docs/websocket-handler.md

@@ -1,58 +0,0 @@
-# WebSocket Handler
-
-## `WebSocketHandler`
-
-Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
-
-```typescript
-export interface WebSocketHandler {
-  addSocket(
-    socket: WebSocket,
-    clientId: string,
-    clientName: string,
-    connReq: FastifyRequest,
-  ): void;
-  closeAll(): void;
-  emit<TInfo, TData>(
-    eventDef: ServiceEventDef<TInfo, TData>,
-    infoSelector: (item: TInfo) => boolean,
-    data: TData,
-  ): Promise<void>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `addSocket` | `socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest` | `void` | Registers a new WebSocket connection. Closes any existing connection with the same `clientId` |
-| `closeAll` | none | `void` | Closes all active WebSocket connections |
-| `emit` | `eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData` | `Promise<void>` | Broadcasts an event to all sockets that have matching event listeners |
-
-## `createWebSocketHandler`
-
-Creates a `WebSocketHandler` instance.
-
-```typescript
-export 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>` | Callback to execute service methods |
-| `jwtSecret` | `string \| undefined` | JWT secret for auth message verification |
-
-Message routing:
-- `${service}.${method}` -- Invokes `runMethod` and sends response
-- `evt:add` -- Registers an event listener on the socket
-- `evt:remove` -- Removes an event listener from the socket
-- `evt:gets` -- Returns all listener infos for an event name across all sockets
-- `evt:emit` -- Dispatches an event to target listener keys across all sockets
-- `auth` -- Verifies JWT token and stores payload on the socket
-- Other -- Returns `BAD_MESSAGE` error