@simplysm/service-server 13.0.98 → 13.0.99

package/README.md

@@ -1,6 +1,8 @@
 # @simplysm/service-server
 
-Service module (server) -- Fastify-based service server with WebSocket support, JWT authentication, and built-in ORM/SMTP/auto-update services.
+Simplysm package - service module (server)
+
+Fastify-based service server with WebSocket support, JWT authentication, and built-in ORM/SMTP/auto-update services. Works with `@simplysm/service-client` for client-server communication.
 
 ## Installation
 
@@ -8,68 +10,108 @@ Service module (server) -- Fastify-based service server with WebSocket support,
 npm install @simplysm/service-server
 ```
 
-## Exports
+## API Overview
 
-```typescript
-import {
-  // Main
-  ServiceServer,
-  createServiceServer,
-  type ServiceServerOptions,
-  // Auth
-  type AuthTokenPayload,
-  signJwt,
-  verifyJwt,
-  decodeJwt,
-  // Core
-  type ServiceContext,
-  createServiceContext,
-  getServiceAuthPermissions,
-  auth,
-  type ServiceDefinition,
-  defineService,
-  type ServiceMethods,
-  executeServiceMethod,
-  // Transport - Socket
-  type WebSocketHandler,
-  createWebSocketHandler,
-  type ServiceSocket,
-  createServiceSocket,
-  // Transport - HTTP
-  handleHttpRequest,
-  handleUpload,
-  handleStaticFile,
-  // Protocol
-  type ServerProtocolWrapper,
-  createServerProtocolWrapper,
-  // Services
-  OrmService,
-  type OrmServiceType,
-  AutoUpdateService,
-  type AutoUpdateServiceType,
-  SmtpClientService,
-  type SmtpClientServiceType,
-  // Utils
-  getConfig,
-  // Legacy
-  handleV1Connection,
-} from "@simplysm/service-server";
-```
+### Types
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceServerOptions` | interface | Server config (rootPath, port, ssl, auth, services) |
+
+-> See [docs/server.md](./docs/server.md) for details.
+
+### Auth
+| API | Type | Description |
+|-----|------|-------------|
+| `AuthTokenPayload` | interface | JWT payload with roles and custom data |
+| `signJwt` | function | Sign a JWT token (HS256, 12h expiry) |
+| `verifyJwt` | function | Verify and decode a JWT token |
+| `decodeJwt` | function | Decode JWT without verification |
+
+-> See [docs/auth.md](./docs/auth.md) for details.
+
+### Core
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceContext` | interface | Context with server, socket, auth, config access |
+| `createServiceContext` | function | Create a service context |
+| `ServiceDefinition` | interface | Service definition (name, factory, auth) |
+| `defineService` | function | Define a service with name and factory |
+| `auth` | function | Auth wrapper for services/methods (login/roles) |
+| `getServiceAuthPermissions` | function | Read auth permissions from wrapped function |
+| `ServiceMethods` | type | Extract method types from ServiceDefinition |
+| `executeServiceMethod` | function | Execute service method with auth checks |
+
+-> See [docs/core.md](./docs/core.md) for details.
+
+### Transport - Socket
+| API | Type | Description |
+|-----|------|-------------|
+| `WebSocketHandler` | interface | Multi-connection WebSocket manager |
+| `createWebSocketHandler` | function | Create WebSocket handler |
+| `ServiceSocket` | interface | Single WebSocket connection manager |
+| `createServiceSocket` | function | Create service socket |
+
+-> See [docs/transport.md](./docs/transport.md) for details.
+
+### Transport - HTTP
+| API | Type | Description |
+|-----|------|-------------|
+| `handleHttpRequest` | function | Handle HTTP API requests |
+| `handleUpload` | function | Handle file upload (multipart) |
+| `handleStaticFile` | function | Serve static files from www/ |
+
+-> See [docs/transport.md](./docs/transport.md) for details.
+
+### Protocol
+| API | Type | Description |
+|-----|------|-------------|
+| `ServerProtocolWrapper` | interface | Server protocol with worker thread offloading |
+| `createServerProtocolWrapper` | function | Create server protocol wrapper |
+
+-> See [docs/transport.md](./docs/transport.md) for details.
+
+### Services
+| API | Type | Description |
+|-----|------|-------------|
+| `OrmService` | const | Built-in ORM service (DB connection, queries) |
+| `AutoUpdateService` | const | Built-in auto-update service |
+| `SmtpClientService` | const | Built-in SMTP email service |
+
+-> See [docs/services.md](./docs/services.md) for details.
+
+### Utils
+| API | Type | Description |
+|-----|------|-------------|
+| `getConfig` | function | Read JSON config with caching and live-reload |
 
-## Quick Start
+-> See [docs/server.md](./docs/server.md) for details.
+
+### Main
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceServer` | class | Main server (Fastify, WebSocket, auth, events) |
+| `createServiceServer` | function | Factory to create ServiceServer |
+
+-> See [docs/server.md](./docs/server.md) for details.
+
+### Legacy
+| API | Type | Description |
+|-----|------|-------------|
+| `handleV1Connection` | function | V1 legacy client handler (auto-update only) |
+
+-> See [docs/server.md](./docs/server.md) for details.
+
+## Usage Examples
+
+### Basic Server Setup
 
 ```typescript
-import {
-  createServiceServer,
-  defineService,
-  auth,
-  OrmService,
-  AutoUpdateService,
-} from "@simplysm/service-server";
+import { createServiceServer, defineService, auth } from "@simplysm/service-server";
+import { OrmService, AutoUpdateService } from "@simplysm/service-server";
 
 // Define a custom service
 const HealthService = defineService("Health", (ctx) => ({
-  check: () => ({ status: "ok" }),
+  check: () => ({ status: "ok", time: new Date().toISOString() }),
 }));
 
 // Define an authenticated service
@@ -89,10 +131,33 @@ const server = createServiceServer({
 await server.listen();
 ```
 
-## Documentation
+### JWT Authentication
+
+```typescript
+import { signJwt, verifyJwt } from "@simplysm/service-server";
 
-- [Auth](docs/auth.md)
-- [Core](docs/core.md)
-- [Transport](docs/transport.md)
-- [Built-in Services](docs/services.md)
-- [Server](docs/server.md)
+// Sign token (in login handler)
+const token = await server.signAuthToken({
+  roles: ["user", "admin"],
+  data: { userId: 123, name: "John" },
+});
+
+// Verify token
+const payload = await server.verifyAuthToken(token);
+console.log(payload.data.name); // "John"
+```
+
+### Server-Side Event Emission
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
+
+const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+
+// Emit to all listeners with matching orderId
+await server.emitEvent(
+  OrderUpdated,
+  (info) => info.orderId === 123,
+  { status: "shipped" },
+);
+```

package/docs/auth.md

@@ -4,7 +4,7 @@ JWT-based authentication utilities using the `jose` library (HS256 algorithm).
 
 ## `AuthTokenPayload`
 
-JWT token payload structure. Extends `JWTPayload` from `jose`.
+JWT token payload with roles and custom data. Extends `JWTPayload` from `jose`.
 
 ```typescript
 interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
@@ -13,9 +13,14 @@ interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
 }
 ```
 
+| Field | Type | Description |
+|-------|------|-------------|
+| `roles` | `string[]` | User roles for permission checking |
+| `data` | `TAuthInfo` | Custom auth data (user info, etc.) |
+
 ## `signJwt`
 
-Sign a JWT token. Tokens expire after 12 hours.
+Sign a JWT token with HS256 algorithm. Token expires in 12 hours.
 
 ```typescript
 async function signJwt<TAuthInfo = unknown>(
@@ -24,9 +29,14 @@ async function signJwt<TAuthInfo = unknown>(
 ): Promise<string>;
 ```
 
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `jwtSecret` | `string` | Secret key for signing |
+| `payload` | `AuthTokenPayload<TAuthInfo>` | Token payload |
+
 ## `verifyJwt`
 
-Verify a JWT token and return the payload.
+Verify and decode a JWT token. Throws on expired or invalid tokens.
 
 ```typescript
 async function verifyJwt<TAuthInfo = unknown>(
@@ -35,13 +45,14 @@ async function verifyJwt<TAuthInfo = unknown>(
 ): Promise<AuthTokenPayload<TAuthInfo>>;
 ```
 
-Throws:
-- `"Token has expired."` if the token is expired
-- `"Invalid token."` for all other verification failures
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `jwtSecret` | `string` | Secret key for verification |
+| `token` | `string` | JWT token string |
 
 ## `decodeJwt`
 
-Decode a JWT token without verification.
+Decode a JWT token without verification (for reading payload only).
 
 ```typescript
 function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo>;

package/docs/core.md

@@ -1,10 +1,8 @@
 # Core
 
-Service definition, context, authentication, and method execution.
+## `ServiceContext`
 
-## ServiceContext
-
-Context object passed to service factory functions.
+Context object passed to service factory functions. Provides access to server, socket, auth info, and configuration.
 
 ```typescript
 interface ServiceContext<TAuthInfo = unknown> {
@@ -14,7 +12,9 @@ interface ServiceContext<TAuthInfo = unknown> {
     clientName: string;
     authTokenPayload?: AuthTokenPayload<TAuthInfo>;
   };
-  legacy?: { clientName?: string };
+  legacy?: {
+    clientName?: string;
+  };
 
   get authInfo(): TAuthInfo | undefined;
   get clientName(): string | undefined;
@@ -23,13 +23,20 @@ interface ServiceContext<TAuthInfo = unknown> {
 }
 ```
 
-**Properties:**
-- `authInfo` -- Authenticated user data (from socket or HTTP auth token)
-- `clientName` -- Client application name (validated for path traversal)
-- `clientPath` -- Resolved client directory path (`{rootPath}/www/{clientName}`)
-- `getConfig(section)` -- Reads config from `.config.json` files (root + client-specific, merged)
+| Property | Type | Description |
+|----------|------|-------------|
+| `server` | `ServiceServer<TAuthInfo>` | Server instance |
+| `socket` | `ServiceSocket` | WebSocket connection (if via WebSocket) |
+| `http` | `object` | HTTP request info (if via HTTP) |
+| `legacy` | `object` | V1 legacy context (auto-update only) |
+| `authInfo` | `TAuthInfo \| undefined` | Authenticated user data |
+| `clientName` | `string \| undefined` | Client name |
+| `clientPath` | `string \| undefined` | Resolved client path on disk |
+| `getConfig()` | `<T>(section) => Promise<T>` | Read config from `.config.json` files |
+
+## `createServiceContext`
 
-### `createServiceContext`
+Create a service context instance.
 
 ```typescript
 function createServiceContext<TAuthInfo = unknown>(
@@ -40,44 +47,9 @@ function createServiceContext<TAuthInfo = unknown>(
 ): ServiceContext<TAuthInfo>;
 ```
 
----
-
-## Auth Helpers
-
-### `getServiceAuthPermissions`
-
-Read auth permissions from an `auth()`-wrapped function. Returns `undefined` if not wrapped.
-
-```typescript
-function getServiceAuthPermissions(fn: Function): string[] | undefined;
-```
-
-### `auth`
-
-Auth wrapper for service factories and methods.
-
-```typescript
-// Login required (no specific roles)
-function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
-
-// Login required with specific roles
-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) => ({ ... }))`
-- Method-level: `auth(() => result)` -- this method requires login
-- Method-level with roles: `auth(["admin"], () => result)`
-
----
+## `ServiceDefinition`
 
-## Service Definition
-
-### `ServiceDefinition`
+Service definition object. Contains name, factory function, and optional auth permissions.
 
 ```typescript
 interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
@@ -87,7 +59,13 @@ interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>>
 }
 ```
 
-### `defineService`
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Service name |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function that creates method object |
+| `authPermissions` | `string[]` | Required permissions (from `auth()` wrapper) |
+
+## `defineService`
 
 Define a service with a name and factory function.
 
@@ -98,40 +76,48 @@ function defineService<TMethods extends Record<string, (...args: any[]) => any>>
 ): ServiceDefinition<TMethods>;
 ```
 
-**Example:**
-```typescript
-const HealthService = defineService("Health", (ctx) => ({
-  check: () => ({ status: "ok" }),
-}));
-
-const UserService = defineService("User", auth((ctx) => ({
-  getProfile: () => ctx.authInfo,
-  adminOnly: auth(["admin"], () => "admin"),
-})));
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Service name |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function |
 
-### `ServiceMethods`
+## `auth`
 
-Extract method signatures from a `ServiceDefinition` for client-side type sharing.
+Auth wrapper for service factories and methods. Can be applied at service-level or method-level with optional role requirements.
 
 ```typescript
-type ServiceMethods<TDefinition> =
-  TDefinition extends ServiceDefinition<infer M> ? M : never;
+function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
+function auth<TFunction extends (...args: any[]) => any>(
+  permissions: string[],
+  fn: TFunction,
+): TFunction;
 ```
 
-**Example:**
+| Overload | Description |
+|----------|-------------|
+| `auth(fn)` | Require login (any authenticated user) |
+| `auth(["admin"], fn)` | Require specific roles |
+
+## `getServiceAuthPermissions`
+
+Read auth permissions from an `auth()`-wrapped function. Returns `undefined` if not wrapped.
+
 ```typescript
-export type UserServiceType = ServiceMethods<typeof UserService>;
-// Client: client.getService<UserServiceType>("User");
+function getServiceAuthPermissions(fn: Function): string[] | undefined;
 ```
 
----
+## `ServiceMethods`
+
+Extract method signatures from a `ServiceDefinition` for client-side type sharing.
 
-## Service Execution
+```typescript
+type ServiceMethods<TDefinition> =
+  TDefinition extends ServiceDefinition<infer M> ? M : never;
+```
 
-### `executeServiceMethod`
+## `executeServiceMethod`
 
-Execute a service method with auth checking.
+Execute a service method with authentication and authorization checks.
 
 ```typescript
 async function executeServiceMethod(
@@ -145,17 +131,3 @@ async function executeServiceMethod(
   },
 ): Promise<unknown>;
 ```
-
-**Behavior:**
-1. Finds the service definition by name
-2. Validates the client name (path traversal guard)
-3. Creates a `ServiceContext`
-4. Invokes the factory to create the method object
-5. Checks auth permissions (method-level first, then service-level fallback)
-6. Executes the method with provided params
-
-Throws:
-- `"Service [name] not found."` if service is not registered
-- `"Method [service.method] not found."` if method does not exist
-- `"Login is required."` if auth is required but no token is present
-- `"Insufficient permissions."` if the user lacks required roles

package/docs/server.md

@@ -1,8 +1,8 @@
 # Server
 
-## ServiceServerOptions
+## `ServiceServerOptions`
 
-Server configuration options.
+Configuration options for `ServiceServer`.
 
 ```typescript
 interface ServiceServerOptions {
@@ -19,188 +19,108 @@ interface ServiceServerOptions {
 }
 ```
 
-## ServerProtocolWrapper
+| Field | Type | Description |
+|-------|------|-------------|
+| `rootPath` | `string` | Root path for static files, uploads, and config |
+| `port` | `number` | Server port |
+| `ssl` | `object` | SSL/TLS config (PFX certificate) |
+| `ssl.pfxBytes` | `Uint8Array` | PFX certificate bytes |
+| `ssl.passphrase` | `string` | Certificate passphrase |
+| `auth` | `object` | Authentication config |
+| `auth.jwtSecret` | `string` | JWT signing secret |
+| `services` | `ServiceDefinition[]` | Service definitions to register |
 
-Server-side protocol wrapper. Automatically offloads heavy message encoding/decoding to a worker thread while using main thread for lightweight operations.
+## `ServiceServer`
 
-```typescript
-interface ServerProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-### `createServerProtocolWrapper`
-
-```typescript
-function createServerProtocolWrapper(): ServerProtocolWrapper;
-```
-
-**Behavior:**
-- Messages with `Uint8Array` body or arrays containing `Uint8Array` are encoded via worker thread
-- Messages larger than 30KB are decoded via worker thread
-- Worker is a lazy singleton shared across all protocol wrappers (4GB memory limit)
-- Small messages are processed on the main thread using `createServiceProtocol()`
-
----
-
-## Config Utilities
-
-### `getConfig`
-
-Read and cache a JSON config file with automatic live-reload via file watcher.
-
-```typescript
-async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
-```
-
-**Behavior:**
-- Returns `undefined` if file does not exist
-- Caches loaded config in a `LazyGcMap` (expires after 1 hour, GC runs every 10 minutes)
-- Registers a file watcher that live-reloads config on changes
-- Watcher is cleaned up when the cache entry expires
-
----
-
-## Legacy
-
-### `handleV1Connection`
-
-V1 legacy client handler. Only auto-update is supported; all other requests return an upgrade-required error.
-
-```typescript
-function handleV1Connection(
-  socket: WebSocket,
-  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
-  clientNameSetter?: (clientName: string | undefined) => void,
-): void;
-```
-
----
-
-## ServiceServer
-
-Main server class. Extends `EventEmitter<{ ready: void; close: void }>`.
+Fastify-based service server with WebSocket support, JWT authentication, and built-in services. Extends `EventEmitter`.
 
 ```typescript
-class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{ ready: void; close: void }> {
+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>;
-  async broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>;
-  async emitEvent<TInfo, TData>(
+  listen(): Promise<void>;
+  close(): Promise<void>;
+  broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>;
+  emitEvent<TInfo, TData>(
     eventDef: ServiceEventDef<TInfo, TData>,
     infoSelector: (item: TInfo) => boolean,
     data: TData,
   ): Promise<void>;
-  async signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
-  async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
+  signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
+  verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
 }
 ```
 
-### `listen`
+| Property | Type | Description |
+|----------|------|-------------|
+| `isOpen` | `boolean` | Whether server is listening |
+| `fastify` | `FastifyInstance` | Underlying Fastify instance |
+| `options` | `ServiceServerOptions` | Server options |
+
+| Method | Description |
+|--------|-------------|
+| `listen()` | Start the server (registers plugins, routes, WebSocket, graceful shutdown) |
+| `close()` | Stop the server (close all connections) |
+| `broadcastReload()` | Broadcast reload to all connected clients |
+| `emitEvent()` | Emit event to matching clients |
+| `signAuthToken()` | Sign a JWT token |
+| `verifyAuthToken()` | Verify and decode a JWT token |
+
+### Registered Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/api/:service/:method` | GET/POST | HTTP service method endpoint |
+| `/upload` | POST | File upload endpoint (multipart) |
+| `/ws` | WebSocket | WebSocket service endpoint (Protocol V2) |
+| `/` | WebSocket | WebSocket endpoint (V1 legacy + V2) |
+| `/*` | GET | Static file serving from `www/` |
+
+### Registered Plugins
+
+- `@fastify/websocket` - WebSocket support
+- `@fastify/helmet` - Security headers (CSP, HSTS)
+- `@fastify/multipart` - File upload
+- `@fastify/static` - Static file serving
+- `@fastify/cors` - CORS support
 
-Start the server. Registers all Fastify plugins and routes:
-
-- `@fastify/websocket` -- WebSocket support
-- `@fastify/helmet` -- Security headers
-- `@fastify/multipart` -- File upload support
-- `@fastify/static` -- Static file serving
-- `@fastify/cors` -- Cross-origin resource sharing
-
-**Routes:**
-- `GET/POST /api/:service/:method` -- HTTP API endpoint
-- `POST /upload` -- File upload endpoint
-- `GET /ws` or `GET /` (WebSocket) -- WebSocket connection (V2 protocol with V1 legacy fallback)
-- `GET/POST/PUT/DELETE/PATCH/HEAD /*` -- Static file wildcard handler
-
-Registers graceful shutdown handlers for `SIGINT` and `SIGTERM` (10s timeout before force exit).
-
-### `close`
-
-Close all WebSocket connections and shut down the Fastify server.
-
-### `broadcastReload`
-
-Broadcast a reload message to all connected WebSocket clients.
-
-```typescript
-async broadcastReload(
-  clientName: string | undefined,
-  changedFileSet: Set<string>,
-): Promise<void>;
-```
-
-### `emitEvent`
+## `createServiceServer`
 
-Emit an event to matching WebSocket clients.
+Factory function to create a `ServiceServer` instance.
 
 ```typescript
-async emitEvent<TInfo, TData>(
-  eventDef: ServiceEventDef<TInfo, TData>,
-  infoSelector: (item: TInfo) => boolean,
-  data: TData,
-): Promise<void>;
+function createServiceServer<TAuthInfo = unknown>(
+  options: ServiceServerOptions,
+): ServiceServer<TAuthInfo>;
 ```
 
-### `signAuthToken`
-
-Sign a JWT auth token.
-
-```typescript
-async signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
-```
+## Utils
 
-### `verifyAuthToken`
+### `getConfig`
 
-Verify a JWT auth token.
+Read JSON configuration from file with caching and live-reload via file watcher. Cache expires after 1 hour.
 
 ```typescript
-async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
+async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
 ```
 
-## `createServiceServer`
-
-Factory function.
+## Legacy
 
-```typescript
-function createServiceServer<TAuthInfo = unknown>(
-  options: ServiceServerOptions,
-): ServiceServer<TAuthInfo>;
-```
+### `handleV1Connection`
 
-## Example
+V1 legacy client handler. Only auto-update is supported; all other requests return an upgrade-required error.
 
 ```typescript
-import {
-  createServiceServer,
-  defineService,
-  auth,
-  OrmService,
-  AutoUpdateService,
-  SmtpClientService,
-} from "@simplysm/service-server";
-
-const MyService = defineService("My", auth((ctx) => ({
-  hello: (name: string) => `Hello, ${name}!`,
-})));
-
-const server = createServiceServer({
-  rootPath: "/app",
-  port: 3000,
-  auth: { jwtSecret: process.env.JWT_SECRET! },
-  services: [MyService, OrmService, AutoUpdateService, SmtpClientService],
-});
-
-server.on("ready", () => {
-  console.log("Server is ready");
-});
-
-await server.listen();
+function handleV1Connection(
+  socket: WebSocket,
+  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
+  clientNameSetter?: (clientName: string | undefined) => void,
+): void;
 ```

package/docs/services.md

@@ -2,175 +2,57 @@
 
 Pre-defined service definitions ready to use with `ServiceServer`.
 
-## OrmService
+## `OrmService`
 
-Database ORM service. Requires authentication (wrapped with `auth()`). Requires WebSocket connection (cannot be used over HTTP).
-
-```typescript
-import { OrmService, type OrmServiceType } from "@simplysm/service-server";
-```
-
-### Definition
+Server-side ORM service implementation. Requires authentication. Manages database connections per WebSocket socket (using `WeakMap`). Supports MySQL, MSSQL, and PostgreSQL via `@simplysm/orm-node`.
 
 ```typescript
 const OrmService: ServiceDefinition;
 ```
 
-Service name: `"Orm"`
-
-### Methods
+Implements the `OrmService` interface from `@simplysm/service-common`:
 
-```typescript
-interface OrmServiceType {
-  getInfo(opt: DbConnOptions & { configName: string }): Promise<{
-    dialect: Dialect;
-    database?: string;
-    schema?: string;
-  }>;
-  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
-  close(connId: number): Promise<void>;
-  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[][]>;
-  bulkInsert(
-    connId: number,
-    tableName: string,
-    columnDefs: Record<string, ColumnMeta>,
-    records: Record<string, unknown>[],
-  ): Promise<void>;
-}
-```
-
-**Behavior:**
-- Database connections are tracked per WebSocket socket using a `WeakMap`
-- Connections are automatically cleaned up when the socket closes
-- Configuration is loaded from `.config.json` under the `"orm"` section
-- Supports `mssql-azure` dialect (mapped to `mssql` for query building)
-
-**Configuration example** (`.config.json`):
-```json
-{
-  "orm": {
-    "myDb": {
-      "dialect": "mysql",
-      "host": "localhost",
-      "port": 3306,
-      "database": "mydb",
-      "user": "root",
-      "password": "secret"
-    }
-  }
-}
-```
+| Method | Description |
+|--------|-------------|
+| `getInfo()` | Get database dialect and connection info from config |
+| `connect()` | Open a new database connection, returns connection ID |
+| `close()` | Close a database connection |
+| `beginTransaction()` | Begin transaction |
+| `commitTransaction()` | Commit transaction |
+| `rollbackTransaction()` | Rollback transaction |
+| `executeParametrized()` | Execute parameterized SQL |
+| `executeDefs()` | Execute QueryDef array (builds SQL via QueryBuilder) |
+| `bulkInsert()` | Bulk insert records |
 
----
+**Note:** ORM service requires WebSocket connection (cannot be used over HTTP).
 
-## AutoUpdateService
+## `AutoUpdateService`
 
-Auto-update service for client applications. No authentication required.
-
-```typescript
-import { AutoUpdateService, type AutoUpdateServiceType } from "@simplysm/service-server";
-```
-
-### Definition
+Server-side auto-update service implementation. Scans the client's platform-specific `updates/` directory for version files.
 
 ```typescript
 const AutoUpdateService: ServiceDefinition;
 ```
 
-Service name: `"AutoUpdate"`
-
-### Methods
-
-```typescript
-interface AutoUpdateServiceType {
-  getLastVersion(platform: string): Promise<
-    | { version: string; downloadPath: string }
-    | undefined
-  >;
-}
-```
+Implements the `AutoUpdateService` interface from `@simplysm/service-common`:
 
-**Behavior:**
-- Scans `{clientPath}/{platform}/updates/` for version files
-- Android: looks for `.apk` files
-- Other platforms: looks for `.exe` files
-- Returns the highest semver version found
-- Returns `undefined` if no updates directory or no valid versions exist
+| Method | Description |
+|--------|-------------|
+| `getLastVersion(platform)` | Find latest version file for platform (win32, android, etc.) |
 
----
+Supported platforms and file extensions:
+- `android`: `.apk` files
+- Other platforms: `.exe` files
 
-## SmtpClientService
+## `SmtpClientService`
 
-SMTP email sending service. No authentication required.
-
-```typescript
-import { SmtpClientService, type SmtpClientServiceType } from "@simplysm/service-server";
-```
-
-### Definition
+Server-side SMTP email sending service. Uses `nodemailer` under the hood.
 
 ```typescript
 const SmtpClientService: ServiceDefinition;
 ```
 
-Service name: `"SmtpClient"`
-
-### Methods
-
-```typescript
-interface SmtpClientServiceType {
-  send(options: SmtpClientSendOption): Promise<string>;
-  sendByConfig(configName: string, options: SmtpClientSendByDefaultOption): Promise<string>;
-}
-```
-
-**`send`** -- Send email with explicit SMTP configuration. Returns the message ID.
-
-**`sendByConfig`** -- Send email using server-side SMTP configuration. Configuration is loaded from `.config.json` under the `"smtp"` section.
-
-**Configuration example** (`.config.json`):
-```json
-{
-  "smtp": {
-    "default": {
-      "senderName": "My App",
-      "senderEmail": "noreply@example.com",
-      "user": "smtp-user",
-      "pass": "smtp-pass",
-      "host": "smtp.example.com",
-      "port": 587,
-      "secure": false
-    }
-  }
-}
-```
-
----
-
-## Usage
-
-Register built-in services when creating the server:
-
-```typescript
-import {
-  createServiceServer,
-  OrmService,
-  AutoUpdateService,
-  SmtpClientService,
-} from "@simplysm/service-server";
-
-const server = createServiceServer({
-  rootPath: "/app",
-  port: 3000,
-  auth: { jwtSecret: "secret" },
-  services: [OrmService, AutoUpdateService, SmtpClientService],
-});
-```
+| Method | Description |
+|--------|-------------|
+| `send(options)` | Send email with full SMTP options |
+| `sendByDefault(options)` | Send email using server's default SMTP config |

package/docs/transport.md

@@ -4,7 +4,7 @@
 
 ### `WebSocketHandler`
 
-Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
+WebSocket handler interface. Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
 
 ```typescript
 interface WebSocketHandler {
@@ -19,31 +19,32 @@ interface WebSocketHandler {
 }
 ```
 
+| Method | Description |
+|--------|-------------|
+| `addSocket()` | Add a new WebSocket connection |
+| `closeAll()` | Close all active connections |
+| `broadcastReload()` | Broadcast reload message to all clients |
+| `emit()` | Emit event to matching clients |
+
 ### `createWebSocketHandler`
 
+Create a WebSocket handler instance.
+
 ```typescript
 function createWebSocketHandler(
   runMethod: (def: {
     serviceName: string;
     methodName: string;
     params: unknown[];
-    socket?: ServiceSocket;
+    socket: ServiceSocket;
   }) => Promise<unknown>,
-  jwtSecret: string | undefined,
+  jwtSecret?: string,
 ): WebSocketHandler;
 ```
 
-**Behavior:**
-- Routes incoming messages to service methods, auth, and event operations
-- Manages a map of connected `ServiceSocket` instances by client ID
-- Replaces existing connections for the same client ID
-- Handles `auth`, `evt:add`, `evt:remove`, `evt:gets`, `evt:emit`, and service method requests
-
----
-
 ### `ServiceSocket`
 
-Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
+Service socket interface. Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
 
 ```typescript
 interface ServiceSocket {
@@ -58,15 +59,33 @@ interface ServiceSocket {
   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;
 }
 ```
 
+| Property | Type | Description |
+|----------|------|-------------|
+| `connectedAtDateTime` | `DateTime` | Connection time |
+| `clientName` | `string` | Client name |
+| `connReq` | `FastifyRequest` | Original Fastify request |
+| `authTokenPayload` | `AuthTokenPayload` | Authenticated token payload |
+
+| Method | Description |
+|--------|-------------|
+| `close()` | Close the WebSocket connection |
+| `send()` | Send a message to the client |
+| `addListener()` | Register an event listener |
+| `removeListener()` | Remove an event listener |
+| `getEventListeners()` | Get all listeners for an event name |
+| `filterEventTargetKeys()` | Filter target keys that exist in this socket |
+| `on()` | Register event handlers (error, close, message) |
+
 ### `createServiceSocket`
 
+Create a service socket instance.
+
 ```typescript
 function createServiceSocket(
   socket: WebSocket,
@@ -76,20 +95,11 @@ function createServiceSocket(
 ): ServiceSocket;
 ```
 
-**Behavior:**
-- Wraps raw WebSocket with protocol encoding/decoding via `ServerProtocolWrapper`
-- Sends ping every 5s; terminates if pong not received
-- Handles raw ping/pong packets (`0x01` ping, `0x02` pong)
-- Tracks event listeners per socket for event broadcasting
-- Sends progress notifications for chunked message reception
-
----
-
 ## HTTP Transport
 
 ### `handleHttpRequest`
 
-Handle HTTP API requests (GET/POST) to `/api/:service/:method`.
+Handle HTTP API requests. Routes `POST/GET /api/:service/:method` to service methods.
 
 ```typescript
 async function handleHttpRequest<TAuthInfo = unknown>(
@@ -105,15 +115,9 @@ async function handleHttpRequest<TAuthInfo = unknown>(
 ): Promise<void>;
 ```
 
-**Behavior:**
-- Requires `x-sd-client-name` header
-- GET: reads params from `?json=...` query parameter
-- POST: reads params from request body (must be an array)
-- Parses `Authorization: Bearer <token>` header if present
-
 ### `handleUpload`
 
-Handle multipart file upload to `/upload`.
+Handle file upload requests. Accepts multipart form data with auth token.
 
 ```typescript
 async function handleUpload(
@@ -124,15 +128,9 @@ async function handleUpload(
 ): Promise<void>;
 ```
 
-**Behavior:**
-- Requires authentication (JWT token in Authorization header)
-- Saves files to `{rootPath}/www/uploads/` with UUID filenames
-- Returns `ServiceUploadResult[]` with path, filename, and size
-- Cleans up incomplete files on error
-
 ### `handleStaticFile`
 
-Handle static file serving.
+Handle static file serving. Serves files from `www/` directory with security checks (path traversal protection, hidden file blocking).
 
 ```typescript
 async function handleStaticFile(
@@ -143,10 +141,24 @@ async function handleStaticFile(
 ): Promise<void>;
 ```
 
-**Behavior:**
-- Serves files from `{rootPath}/www/`
-- Path traversal protection (rejects paths outside allowed root)
-- Redirects directories to trailing-slash URLs
-- Returns `index.html` for directory requests
-- Returns 403 for hidden files (starting with `.`)
-- Returns 404 for missing files
+## Protocol
+
+### `ServerProtocolWrapper`
+
+Server-side protocol wrapper interface. Automatically offloads heavy encoding/decoding to a worker thread (>30KB threshold).
+
+```typescript
+interface ServerProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+### `createServerProtocolWrapper`
+
+Create a server protocol wrapper instance.
+
+```typescript
+function createServerProtocolWrapper(): ServerProtocolWrapper;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.98",
+  "version": "13.0.99",
   "description": "Simplysm package - service module (server)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -36,11 +36,11 @@
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.19.0",
-    "@simplysm/core-node": "13.0.98",
-    "@simplysm/core-common": "13.0.98",
-    "@simplysm/orm-common": "13.0.98",
-    "@simplysm/service-common": "13.0.98",
-    "@simplysm/orm-node": "13.0.98"
+    "@simplysm/core-common": "13.0.99",
+    "@simplysm/orm-node": "13.0.99",
+    "@simplysm/core-node": "13.0.99",
+    "@simplysm/service-common": "13.0.99",
+    "@simplysm/orm-common": "13.0.99"
   },
   "devDependencies": {
     "@types/nodemailer": "^7.0.11",