@simplysm/service-server 13.0.29 → 13.0.31

package/README.md

@@ -16,41 +16,49 @@ pnpm add @simplysm/service-server
 
 ### Core Functions and Classes
 
-- [`createServiceServer`](#basic-server-configuration) - Factory function for creating a ServiceServer instance
-- [`ServiceServer`](docs/server.md#serviceserver) - Main server class. Creates Fastify instance and configures routes/plugins
+- [`createServiceServer`](#basic-server-configuration) - Factory function for creating a `ServiceServer` instance
+- [`ServiceServer`](docs/server.md#serviceserver) - Main server class. Creates a Fastify instance and configures routes/plugins
 - [`defineService`](#custom-services) - Defines a service with a factory function pattern
-- `ServiceExecutor` - Internal executor that handles service method discovery, auth checks, and execution
+- [`ServiceContext`](docs/server.md#servicecontext) - Context object passed to service factory functions
+- `runServiceMethod` - Internal function that dispatches a service method call (auth checks + execution)
 
 ### Authentication
 
-- [`auth`](#authentication) - Function wrapper that sets authentication permissions at service or method level
-- [`getServiceAuthPermissions`](#authentication) - Queries auth permissions for a service or method (used internally by `ServiceExecutor`)
-- [`JwtManager`](docs/authentication.md#jwtmanager) - JWT token generation/verification/decoding based on jose library (HS256, 12-hour expiration)
+- [`auth`](#authentication) - Wrapper that sets authentication requirements at service or method level
+- [`getServiceAuthPermissions`](docs/authentication.md#getserviceauthpermissions) - Reads auth permissions from an `auth()`-wrapped function
+- [`signJwt`](docs/authentication.md#jwt-functions) - Generate a JWT token (HS256, 12-hour expiration)
+- [`verifyJwt`](docs/authentication.md#jwt-functions) - Verify and decode a JWT token
+- [`decodeJwt`](docs/authentication.md#jwt-functions) - Decode a JWT token without verification (synchronous)
 - [`AuthTokenPayload`](docs/authentication.md#authtokenpayload) - JWT payload interface (includes `roles`, `data`)
 
 ### Transport Layer - WebSocket
 
-- `WebSocketHandler` - Handles WebSocket connection management, message routing, and event distribution
-- [`ServiceSocket`](docs/transport.md#servicesocket) - Wraps individual WebSocket connections. Manages ping/pong, protocol encoding/decoding, event listener management
+- [`WebSocketHandler`](docs/transport.md#websockethandler) - Interface for managing multiple WebSocket connections, routing messages, and broadcasting events
+- `createWebSocketHandler` - Factory function that creates a `WebSocketHandler` instance
+- [`ServiceSocket`](docs/transport.md#servicesocket) - Interface wrapping a single WebSocket connection. Manages ping/pong, protocol encoding/decoding, event listener management
+- `createServiceSocket` - Factory function that creates a `ServiceSocket` instance
 
 ### Transport Layer - HTTP
 
-- `HttpRequestHandler` - Calls service methods via HTTP at `/api/:service/:method` route
-- [`UploadHandler`](docs/transport.md#file-upload) - Handles multipart file upload at `/upload` route (auth required)
-- `StaticFileHandler` - Serves static files. Prevents path traversal and blocks hidden files
+- `handleHttpRequest` - Handles service method calls via HTTP at `/api/:service/:method`
+- `handleUpload` - Handles multipart file upload at `/upload` (auth required)
+- `handleStaticFile` - Serves static files from `rootPath/www/`. Prevents path traversal and blocks hidden files
 
 ### Protocol
 
-- [`ProtocolWrapper`](docs/transport.md#protocolwrapper) - Message encoding/decoding wrapper. Messages over 30KB are processed in worker threads
+- [`ProtocolWrapper`](docs/transport.md#protocolwrapper) - Interface for message encoding/decoding. Messages over 30KB are processed in worker threads
+- `createProtocolWrapper` - Factory function that creates a `ProtocolWrapper` instance
 
 ### Built-in Services
 
 - [`OrmService`](docs/built-in-services.md#ormservice) - DB connection/transaction/query execution (WebSocket only, auth required)
+- `OrmServiceType` - Type alias for `OrmService` method signatures (for client-side type sharing)
 - [`AutoUpdateService`](docs/built-in-services.md#autoupdateservice) - App auto-update (provides latest version query and download path)
+- `AutoUpdateServiceType` - Type alias for `AutoUpdateService` method signatures (for client-side type sharing)
 
 ### Utilities
 
-- [`getConfig`](docs/server.md#getconfig) - JSON config file loading with caching and real-time file watching (auto expiration based on LazyGcMap)
+- [`getConfig`](docs/server.md#getconfig) - JSON config file loading with caching and real-time file watching
 
 ### Legacy
 
@@ -119,7 +127,8 @@ The `ctx` parameter provides access to server resources:
 - `ctx.http` - HTTP request/reply objects (HTTP only, undefined for WebSocket)
 - `ctx.authInfo` - Authentication info (set via JWT token)
 - `ctx.clientName` - Client identifier
-- `ctx.getConfig(name)` - Get server config by name
+- `ctx.clientPath` - Resolved per-client directory path (`rootPath/www/{clientName}`)
+- `ctx.getConfig(section)` - Get server config by section name
 
 ### Authentication
 

package/docs/authentication.md

@@ -41,7 +41,7 @@ Method-level `auth()` overrides service-level settings.
 
 ## getServiceAuthPermissions
 
-Query auth permissions for a given service definition or method. Primarily used internally by `ServiceExecutor`, but exported for advanced use cases.
+Read auth permissions from an `auth()`-wrapped function. Returns `undefined` if the function is not wrapped with `auth()`. Primarily used internally by `runServiceMethod`, but exported for advanced use cases.
 
 ```typescript
 import { defineService, auth, getServiceAuthPermissions } from "@simplysm/service-server";
@@ -55,43 +55,52 @@ const servicePerms = someServiceDef.authPermissions;
 // string[] if service-level auth is set, or undefined for public
 ```
 
-## JWT Token Management
+| Signature | Returns | Description |
+|-----------|---------|------|
+| `getServiceAuthPermissions(fn: Function)` | `string[] \| undefined` | Returns the permission array attached by `auth()`, or `undefined` if not wrapped |
 
-### JwtManager
+## JWT Functions
 
-`JwtManager<TAuthInfo>` handles JWT operations internally. Access its functionality through `ServiceServer` methods.
-
-| Method | Returns | Description |
-|--------|---------|------|
-| `sign(payload)` | `Promise<string>` | Generate a JWT token (HS256, 12-hour expiration) |
-| `verify(token)` | `Promise<AuthTokenPayload<TAuthInfo>>` | Verify token signature and expiration, return payload |
-| `decode(token)` | `AuthTokenPayload<TAuthInfo>` | Decode token without verification (synchronous) |
-
-Generate and verify JWT tokens through the `ServiceServer` instance:
+Standalone functions for JWT token generation and verification using the `jose` library (HS256 algorithm, 12-hour expiration).
 
 ```typescript
-import { createServiceServer } from "@simplysm/service-server";
-
-const server = createServiceServer({
-  port: 8080,
-  rootPath: "/app/data",
-  auth: { jwtSecret: "my-secret-key" },
-  services: [],
-});
+import { signJwt, verifyJwt, decodeJwt } from "@simplysm/service-server";
 
 // Generate token (12-hour expiration, HS256 algorithm)
-const token = await server.generateAuthToken({
+const token = await signJwt("my-secret-key", {
   roles: ["admin", "user"],
   data: { userId: 1, name: "John" },
 });
 
-// Verify token
-const payload = await server.verifyAuthToken(token);
+// Verify token (throws on expiry or invalid signature)
+const payload = await verifyJwt("my-secret-key", token);
 // payload.roles: ["admin", "user"]
 // payload.data: { userId: 1, name: "John" }
+
+// Decode token without verification (synchronous, no secret needed)
+const decoded = decodeJwt(token);
+```
+
+| Function | Returns | Description |
+|----------|---------|------|
+| `signJwt<TAuthInfo>(jwtSecret, payload)` | `Promise<string>` | Generate a JWT token (HS256, 12-hour expiration) |
+| `verifyJwt<TAuthInfo>(jwtSecret, token)` | `Promise<AuthTokenPayload<TAuthInfo>>` | Verify token signature and expiration, return payload. Throws on invalid or expired tokens |
+| `decodeJwt<TAuthInfo>(token)` | `AuthTokenPayload<TAuthInfo>` | Decode token without verification (synchronous) |
+
+In most cases, use `ServiceServer` methods instead of calling these functions directly:
+
+```typescript
+// Generate token via server (preferred)
+const token = await server.generateAuthToken({
+  roles: ["admin"],
+  data: { userId: 1 },
+});
+
+// Verify token via server (preferred)
+const payload = await server.verifyAuthToken(token);
 ```
 
-### AuthTokenPayload
+## AuthTokenPayload
 
 ```typescript
 import type { AuthTokenPayload } from "@simplysm/service-server";

package/docs/built-in-services.md

@@ -2,7 +2,7 @@
 
 ## OrmService
 
-Provides database connection/query/transaction via WebSocket. `auth()` wrapper is applied, requiring login.
+Provides database connection/query/transaction via WebSocket. The `auth()` wrapper is applied, requiring login.
 
 ```typescript
 import { createServiceServer, OrmService } from "@simplysm/service-server";
@@ -48,39 +48,16 @@ Methods provided by `OrmService`:
 
 When a WebSocket connection is closed, all DB connections opened from that socket are automatically cleaned up.
 
-## CryptoService
-
-Provides SHA256 hash and AES-256-CBC symmetric key encryption/decryption.
+Use `OrmServiceType` to share method signatures with the client:
 
 ```typescript
-import { createServiceServer, CryptoService } from "@simplysm/service-server";
-
-const server = createServiceServer({
-  port: 8080,
-  rootPath: "/app/data",
-  services: [CryptoService],
-});
-```
-
-`.config.json` config:
-
-```json
-{
-  "crypto": {
-    "key": "your-32-byte-secret-key-here!!"
-  }
-}
+import type { OrmServiceType } from "@simplysm/service-server";
+// OrmServiceType = ServiceMethods<typeof OrmService>
 ```
 
-| Method | Returns | Description |
-|--------|---------|------|
-| `encrypt(data)` | `Promise<string>` | Generate SHA256 HMAC hash (one-way). `data` is `string \| Uint8Array` |
-| `encryptAes(data)` | `Promise<string>` | AES-256-CBC encryption. `data` is `Uint8Array`. Returns hex string in `iv:encrypted` format |
-| `decryptAes(encText)` | `Promise<Uint8Array>` | AES-256-CBC decryption. Returns original binary |
-
 ## AutoUpdateService
 
-Supports auto-update for client apps. Searches for latest version files by platform in the client directory.
+Supports auto-update for client apps. Searches for the latest version files by platform in the client directory. No auth is required.
 
 ```typescript
 import { createServiceServer, AutoUpdateService } from "@simplysm/service-server";
@@ -104,7 +81,7 @@ rootPath/www/{clientName}/{platform}/updates/
 
 | Method | Returns | Description |
 |--------|---------|------|
-| `getLastVersion(platform)` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Returns latest version and download path for the platform. Returns `undefined` if no update |
+| `getLastVersion(platform)` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Returns the latest version and download path for the platform. Returns `undefined` if no update files exist |
 
 Return value example:
 
@@ -114,3 +91,10 @@ Return value example:
   downloadPath: "/my-app/android/updates/1.0.1.apk",
 }
 ```
+
+Use `AutoUpdateServiceType` to share method signatures with the client:
+
+```typescript
+import type { AutoUpdateServiceType } from "@simplysm/service-server";
+// AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>
+```

package/docs/server.md

@@ -133,6 +133,7 @@ The `ctx` parameter provides access to server resources within service methods.
 | `ctx.server` | `ServiceServer<TAuthInfo>` | Server instance reference |
 | `ctx.socket` | `ServiceSocket \| undefined` | WebSocket connection (`undefined` for HTTP calls) |
 | `ctx.http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> } \| undefined` | HTTP request context |
+| `ctx.legacy` | `{ clientName?: string } \| undefined` | V1 legacy context (auto-update only) |
 | `ctx.authInfo` | `TAuthInfo \| undefined` | Authenticated user's custom data (from JWT `data` field) |
 | `ctx.clientName` | `string \| undefined` | Client app name (validated against path traversal) |
 | `ctx.clientPath` | `string \| undefined` | Resolved per-client directory path (`rootPath/www/{clientName}`) |
@@ -143,6 +144,16 @@ The `ctx` parameter provides access to server resources within service methods.
 |--------|---------|------|
 | `ctx.getConfig<T>(section)` | `Promise<T>` | Read a section from `.config.json` (root + client configs merged) |
 
+### createServiceContext
+
+Factory function that creates a `ServiceContext` object. Used internally by the server and exported for advanced use cases (e.g., calling services programmatically without an active connection).
+
+```typescript
+import { createServiceContext } from "@simplysm/service-server";
+
+const ctx = createServiceContext(server, socket, httpContext, legacyContext);
+```
+
 ## Config File Reference
 
 Read sections from `.config.json` files using `ctx.getConfig()`. Root and per-client configs are automatically merged.
@@ -217,7 +228,7 @@ The following routes are automatically registered when `ServiceServer.listen()`
 ## Full Server Example
 
 ```typescript
-import { createServiceServer, defineService, auth, OrmService, CryptoService } from "@simplysm/service-server";
+import { createServiceServer, defineService, auth, OrmService } from "@simplysm/service-server";
 import { defineEvent } from "@simplysm/service-common";
 
 // Define a custom service with auth
@@ -244,7 +255,7 @@ const server = createServiceServer({
   port: 8080,
   rootPath: "/app/data",
   auth: { jwtSecret: "my-secret-key" },
-  services: [UserService, PublicService, OrmService, CryptoService],
+  services: [UserService, PublicService, OrmService],
 });
 
 server.on("ready", () => {

package/docs/transport.md

@@ -1,8 +1,23 @@
 # Transport Layer
 
+## WebSocketHandler
+
+`WebSocketHandler` is an interface that manages multiple WebSocket connections, routes messages to services, and handles event broadcasting. Create an instance with `createWebSocketHandler`.
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|------|
+| `addSocket(socket, clientId, clientName, connReq)` | `void` | Add a new WebSocket connection. If a connection with the same `clientId` already exists, it is closed first |
+| `closeAll()` | `void` | Close all active connections |
+| `broadcastReload(clientName, changedFileSet)` | `Promise<void>` | Send a reload message to all connected clients |
+| `emitToServer(eventDef, infoSelector, data)` | `Promise<void>` | Emit an event to clients whose registered event listeners match the `infoSelector` |
+
+`WebSocketHandler` is created and managed internally by `ServiceServer`. Access its functionality through `ServiceServer` methods (`emitEvent`, `broadcastReload`).
+
 ## ServiceSocket
 
-`ServiceSocket` extends `EventEmitter` and wraps an individual WebSocket connection. It is available in service methods as `ctx.socket` when the request comes via WebSocket.
+`ServiceSocket` is an interface wrapping a single WebSocket connection. It is available in service methods as `ctx.socket` when the request comes via WebSocket. Create an instance with `createServiceSocket`.
 
 **Properties:**
 
@@ -22,6 +37,8 @@
 | `addEventListener(key, eventName, info)` | `void` | Register an event listener for this socket |
 | `removeEventListener(key)` | `void` | Remove an event listener by key |
 | `getEventListeners(eventName)` | `{ key, info }[]` | Get all event listeners for a given event name |
+| `filterEventTargetKeys(targetKeys)` | `string[]` | Filter the given keys to only those registered on this socket |
+| `on(event, handler)` | `void` | Register an event handler (`error`, `close`, or `message`) |
 
 **Events:**
 
@@ -57,6 +74,16 @@ Body: ["World"]
 - Parameters are passed in array form (in the order of method arguments).
 - For GET requests, pass a JSON-serialized array in the `json` query parameter.
 
+### handleHttpRequest
+
+The internal handler function registered at `/api/:service/:method`. Exported for advanced use cases.
+
+```typescript
+import { handleHttpRequest } from "@simplysm/service-server";
+
+await handleHttpRequest(req, reply, jwtSecret, runMethod);
+```
+
 ## File Upload
 
 Upload files via multipart request to the `/upload` endpoint. Auth token is required.
@@ -81,6 +108,31 @@ const results = await response.json();
 
 Uploaded files are stored in the `rootPath/www/uploads/` directory with UUID-based filenames.
 
+### handleUpload
+
+The internal handler function registered at `/upload`. Exported for advanced use cases.
+
+```typescript
+import { handleUpload } from "@simplysm/service-server";
+
+await handleUpload(req, reply, rootPath, jwtSecret);
+```
+
+### handleStaticFile
+
+The internal handler function for static file serving. Exported for advanced use cases.
+
+```typescript
+import { handleStaticFile } from "@simplysm/service-server";
+
+await handleStaticFile(req, reply, rootPath, urlPath);
+```
+
+Security behavior:
+- Blocks path traversal (`..`, outside `rootPath/www/`)
+- Returns 403 for files starting with `.` (hidden files)
+- Redirects directory paths without trailing slash to path with trailing slash
+
 ## Real-time Event Publishing
 
 Publish events to connected clients from the server using `defineEvent` from `@simplysm/service-common`.
@@ -108,7 +160,7 @@ await server.broadcastReload("my-app", new Set(["main.js"]));
 
 ## ProtocolWrapper
 
-Handles encoding/decoding of WebSocket messages. Automatically branches between main thread and worker thread based on message size.
+`ProtocolWrapper` is an interface for encoding/decoding WebSocket messages. Create an instance with `createProtocolWrapper`. Automatically branches between main thread and worker thread based on message size.
 
 ```typescript
 import { createProtocolWrapper } from "@simplysm/service-server";
@@ -138,7 +190,7 @@ Worker thread branching:
 | 30KB or less | Processed directly in main thread |
 | Over 30KB | Processed in worker thread (max 4GB memory allocation) |
 
-Messages containing large binary data (Uint8Array) also branch to worker thread.
+Messages containing large binary data (Uint8Array) also branch to worker thread regardless of size.
 
 ## Legacy: handleV1Connection
 
@@ -148,5 +200,11 @@ Handles V1 protocol WebSocket clients. Only supports the `SdAutoUpdateService.ge
 import { handleV1Connection, AutoUpdateService } from "@simplysm/service-server";
 
 // Used internally by ServiceServer for WebSocket connections without ver=2 query parameter
-handleV1Connection(webSocket, autoUpdateService);
+handleV1Connection(webSocket, autoUpdateMethods, clientNameSetter);
 ```
+
+| Parameter | Type | Description |
+|-----------|------|------|
+| `socket` | `WebSocket` | The raw WebSocket connection |
+| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update service methods |
+| `clientNameSetter` | `((clientName: string \| undefined) => void) \| undefined` | Optional callback to set the client name from the V1 request |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.29",
+  "version": "13.0.31",
   "description": "심플리즘 패키지 - 서비스 모듈 (server)",
   "author": "김석래",
   "license": "Apache-2.0",
@@ -34,11 +34,11 @@
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.19.0",
-    "@simplysm/core-common": "13.0.29",
-    "@simplysm/core-node": "13.0.29",
-    "@simplysm/orm-node": "13.0.29",
-    "@simplysm/orm-common": "13.0.29",
-    "@simplysm/service-common": "13.0.29"
+    "@simplysm/core-common": "13.0.31",
+    "@simplysm/core-node": "13.0.31",
+    "@simplysm/orm-common": "13.0.31",
+    "@simplysm/orm-node": "13.0.31",
+    "@simplysm/service-common": "13.0.31"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",