@simplysm/service-server 13.0.82 → 13.0.83

package/README.md

@@ -0,0 +1,40 @@
+# @simplysm/service-server
+
+Fastify-based service server framework with WebSocket support, JWT authentication, service routing, file uploads, and built-in ORM/SMTP/auto-update services.
+
+## Installation
+
+```bash
+npm install @simplysm/service-server
+```
+
+## Quick Start
+
+```typescript
+import { createServiceServer, defineService } from "@simplysm/service-server";
+
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
+
+const server = createServiceServer({
+  rootPath: process.cwd(),
+  port: 3000,
+  services: [HealthService],
+});
+
+await server.listen();
+```
+
+## Documentation
+
+| Category | File | Description |
+|----------|------|-------------|
+| Server | [docs/server.md](docs/server.md) | `ServiceServer` class and `createServiceServer` factory |
+| Service Definition | [docs/service-definition.md](docs/service-definition.md) | `defineService`, `auth`, `ServiceContext`, `ServiceMethods` |
+| Authentication | [docs/authentication.md](docs/authentication.md) | JWT management and `AuthTokenPayload` |
+| Transport | [docs/transport.md](docs/transport.md) | WebSocket handler, HTTP request handler, upload handler, static file handler |
+| Protocol | [docs/protocol.md](docs/protocol.md) | `ServerProtocolWrapper` with worker thread offloading |
+| Built-in Services | [docs/builtin-services.md](docs/builtin-services.md) | `OrmService`, `AutoUpdateService`, `SmtpClientService` |
+| Utilities | [docs/utilities.md](docs/utilities.md) | `getConfig` with file watching and caching |
+| Legacy | [docs/legacy.md](docs/legacy.md) | V1 auto-update handler for backward compatibility |

package/docs/authentication.md

@@ -0,0 +1,70 @@
+# Authentication
+
+JWT-based authentication using the `jose` library with HS256 algorithm.
+
+## `AuthTokenPayload<TAuthInfo>`
+
+```typescript
+interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
+  roles: string[];    // Role strings for permission checks
+  data: TAuthInfo;    // Custom application-specific auth data
+}
+```
+
+---
+
+## `signJwt<TAuthInfo>(jwtSecret, payload): Promise<string>`
+
+Signs a JWT token with HS256 algorithm. Tokens are issued with the current timestamp and expire after 12 hours.
+
+```typescript
+import { signJwt } from "@simplysm/service-server";
+
+const token = await signJwt("my-secret", {
+  roles: ["admin"],
+  data: { userId: 123, name: "John" },
+});
+```
+
+---
+
+## `verifyJwt<TAuthInfo>(jwtSecret, token): Promise<AuthTokenPayload<TAuthInfo>>`
+
+Verifies a JWT token and returns the decoded payload. Throws a descriptive error for expired or invalid tokens.
+
+```typescript
+import { verifyJwt } from "@simplysm/service-server";
+
+try {
+  const payload = await verifyJwt("my-secret", token);
+  console.log(payload.roles, payload.data);
+} catch (err) {
+  // "Token has expired." or "Invalid token."
+}
+```
+
+---
+
+## `decodeJwt<TAuthInfo>(token): AuthTokenPayload<TAuthInfo>`
+
+Decodes a JWT token **without** verifying its signature. Useful for reading token contents when verification is not needed.
+
+```typescript
+import { decodeJwt } from "@simplysm/service-server";
+
+const payload = decodeJwt(token);
+```
+
+---
+
+## Server-level Auth Helpers
+
+`ServiceServer` provides convenience methods that delegate to the JWT functions using the configured `auth.jwtSecret`:
+
+```typescript
+// Sign a token
+const token = await server.signAuthToken({ roles: ["user"], data: myAuthInfo });
+
+// Verify a token
+const payload = await server.verifyAuthToken(token);
+```

package/docs/builtin-services.md

@@ -0,0 +1,130 @@
+# Built-in Services
+
+Pre-built service definitions ready to include in `ServiceServerOptions.services`.
+
+## `OrmService`
+
+Database operations service using `@simplysm/orm-node`. Requires authentication (service-level `auth` wrapper). **WebSocket only** -- cannot be used over HTTP.
+
+Manages database connections per WebSocket socket. Connections are automatically cleaned up when the socket closes.
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getInfo` | `opt: DbConnOptions & { configName }` | `{ dialect, database?, schema? }` | Get database connection info from config |
+| `connect` | `opt: DbConnOptions & { configName }` | `number` (connId) | Open a database connection |
+| `close` | `connId: number` | `void` | Close a database connection |
+| `beginTransaction` | `connId, isolationLevel?` | `void` | Begin a transaction |
+| `commitTransaction` | `connId` | `void` | Commit the current transaction |
+| `rollbackTransaction` | `connId` | `void` | Rollback the current transaction |
+| `executeParametrized` | `connId, query, params?` | `unknown[][]` | Execute a parameterized query |
+| `executeDefs` | `connId, defs, options?` | `unknown[][]` | Execute query definitions with optional result parsing |
+| `bulkInsert` | `connId, tableName, columnDefs, records` | `void` | Perform bulk insert |
+
+### Configuration
+
+Reads from the `"orm"` config section via `ctx.getConfig("orm")`. Config file (`.config.json`) example:
+
+```json
+{
+  "orm": {
+    "default": {
+      "dialect": "mysql",
+      "host": "localhost",
+      "port": 3306,
+      "username": "root",
+      "password": "password",
+      "database": "mydb"
+    }
+  }
+}
+```
+
+### Type export
+
+```typescript
+export type OrmServiceType = ServiceMethods<typeof OrmService>;
+```
+
+---
+
+## `AutoUpdateService`
+
+Provides app auto-update version checking. Scans `{clientPath}/{platform}/updates/` for versioned files.
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getLastVersion` | `platform: string` | `{ version, downloadPath } \| undefined` | Get the latest version for a platform |
+
+- **Android**: Looks for `.apk` files
+- **Other platforms**: Looks for `.exe` files
+- Version is extracted from the filename (e.g., `1.2.3.apk`)
+- Uses `semver.maxSatisfying` to find the highest version
+
+### Type export
+
+```typescript
+export type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
+```
+
+---
+
+## `SmtpClientService`
+
+Email sending service using `nodemailer`.
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `send` | `options: SmtpClientSendOption` | `string` (messageId) | Send an email with explicit SMTP settings |
+| `sendByConfig` | `configName, options: SmtpClientSendByDefaultOption` | `string` (messageId) | Send using a named SMTP configuration |
+
+### Configuration
+
+`sendByConfig` reads from the `"smtp"` config section. Config file (`.config.json`) example:
+
+```json
+{
+  "smtp": {
+    "default": {
+      "host": "smtp.example.com",
+      "port": 587,
+      "secure": false,
+      "user": "user@example.com",
+      "pass": "password",
+      "senderName": "My App",
+      "senderEmail": "noreply@example.com"
+    }
+  }
+}
+```
+
+### Type export
+
+```typescript
+export type SmtpClientServiceType = ServiceMethods<typeof SmtpClientService>;
+```
+
+---
+
+## Registering Built-in Services
+
+```typescript
+import {
+  createServiceServer,
+  OrmService,
+  AutoUpdateService,
+  SmtpClientService,
+} from "@simplysm/service-server";
+
+const server = createServiceServer({
+  rootPath: process.cwd(),
+  port: 3000,
+  auth: { jwtSecret: "my-secret" },
+  services: [OrmService, AutoUpdateService, SmtpClientService],
+});
+```

package/docs/legacy.md

@@ -0,0 +1,45 @@
+# Legacy
+
+## `handleV1Connection(socket, autoUpdateMethods, clientNameSetter?): void`
+
+Handles V1 legacy WebSocket client connections. Only the `SdAutoUpdateService.getLastVersion` command is supported; all other requests receive an `UPGRADE_REQUIRED` error response.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `WebSocket` | The raw WebSocket connection |
+| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update method implementations |
+| `clientNameSetter` | `(clientName: string \| undefined) => void` | Optional callback to set the legacy client name on the context |
+
+### V1 Protocol
+
+**Request format:**
+```json
+{
+  "uuid": "request-id",
+  "command": "SdAutoUpdateService.getLastVersion",
+  "params": ["android"],
+  "clientName": "my-app"
+}
+```
+
+**Success response:**
+```json
+{
+  "name": "response",
+  "reqUuid": "request-id",
+  "state": "success",
+  "body": { "version": "1.2.3", "downloadPath": "/my-app/android/updates/1.2.3.apk" }
+}
+```
+
+**Upgrade-required response (for unsupported commands):**
+```json
+{
+  "name": "response",
+  "reqUuid": "request-id",
+  "state": "error",
+  "body": { "message": "App upgrade is required.", "code": "UPGRADE_REQUIRED" }
+}
+```

package/docs/protocol.md

@@ -0,0 +1,34 @@
+# Protocol
+
+Message encoding/decoding with automatic worker thread offloading for heavy payloads.
+
+## `ServerProtocolWrapper`
+
+```typescript
+interface ServerProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+## `createServerProtocolWrapper(): ServerProtocolWrapper`
+
+Creates a protocol wrapper instance that automatically delegates heavy operations to a shared worker thread.
+
+### Worker delegation strategy
+
+**Encoding** is offloaded to the worker when:
+- The message body is a `Uint8Array`
+- The message body is an array containing `Uint8Array` elements
+
+**Decoding** is offloaded to the worker when:
+- The incoming bytes exceed 30 KB
+
+Lightweight operations stay on the main thread for lower latency.
+
+### Worker details
+
+- Uses a lazy singleton worker thread shared across all protocol wrappers
+- Worker has a 4 GB memory limit (`maxOldGenerationSizeMb: 4096`)
+- Built on `@simplysm/core-node` `Worker` / `WorkerProxy`

package/docs/server.md

@@ -0,0 +1,102 @@
+# Server
+
+The main server class built on Fastify with WebSocket support, CORS, Helmet security, static file serving, and graceful shutdown.
+
+## `ServiceServer<TAuthInfo>`
+
+**Extends:** `EventEmitter<{ ready: void; close: void }>`
+
+### Constructor
+
+```typescript
+new ServiceServer<TAuthInfo>(options: ServiceServerOptions)
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isOpen` | `boolean` | Whether the server is currently listening |
+| `fastify` | `FastifyInstance` | The underlying Fastify instance |
+| `options` | `ServiceServerOptions` | The server configuration |
+
+### Methods
+
+#### `listen(): Promise<void>`
+
+Starts the server. Registers all Fastify plugins (WebSocket, Helmet, Multipart, Static, CORS), sets up routes (`/api/:service/:method`, `/upload`, `/ws`, `/*`), and begins listening on the configured port.
+
+Emits the `"ready"` event once listening.
+
+#### `close(): Promise<void>`
+
+Closes all WebSocket connections and shuts down the Fastify server. Emits the `"close"` event.
+
+#### `broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>`
+
+Broadcasts a reload message to all connected WebSocket clients.
+
+#### `emitEvent<TInfo, TData>(eventDef, infoSelector, data): Promise<void>`
+
+Emits a typed event to connected clients matching the `infoSelector` filter.
+
+```typescript
+await server.emitEvent(
+  myEventDef,
+  (info) => info.userId === targetUserId,
+  { message: "hello" },
+);
+```
+
+#### `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>`
+
+Signs a JWT token with the configured secret. Throws if `auth.jwtSecret` is not configured.
+
+#### `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>`
+
+Verifies and decodes a JWT token. Throws if expired or invalid.
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `ready` | Emitted after the server starts listening |
+| `close` | Emitted after the server is closed |
+
+### Graceful Shutdown
+
+The server automatically registers `SIGINT` and `SIGTERM` handlers. On signal, it closes all connections and exits. If shutdown exceeds 10 seconds, the process is force-exited.
+
+---
+
+## `createServiceServer<TAuthInfo>(options): ServiceServer<TAuthInfo>`
+
+Factory function that creates a new `ServiceServer` instance.
+
+---
+
+## `ServiceServerOptions`
+
+```typescript
+interface ServiceServerOptions {
+  rootPath: string;        // Root directory for www/ static files and configs
+  port: number;            // Port to listen on
+  ssl?: {
+    pfxBytes: Uint8Array;  // PFX certificate bytes
+    passphrase: string;    // PFX passphrase
+  };
+  auth?: {
+    jwtSecret: string;     // Secret for JWT signing/verification
+  };
+  services: ServiceDefinition[];  // Array of service definitions
+}
+```
+
+## Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/api/:service/:method` | GET, POST | HTTP service method invocation |
+| `/upload` | POST | Multipart file upload (requires auth) |
+| `/` or `/ws` | WebSocket | WebSocket connection endpoint |
+| `/*` | ALL | Static file serving from `{rootPath}/www/` |

package/docs/service-definition.md

@@ -0,0 +1,134 @@
+# Service Definition
+
+APIs for defining services, applying authentication, and sharing types with clients.
+
+## `defineService<TMethods>(name, factory): ServiceDefinition<TMethods>`
+
+Creates a service definition with a name and a factory function that receives a `ServiceContext` and returns an object of methods.
+
+```typescript
+import { defineService } from "@simplysm/service-server";
+
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+  getClientName: () => ctx.clientName,
+}));
+```
+
+---
+
+## `auth(fn): Function`
+
+Wraps a service factory or individual method to require authentication. Accepts an optional array of role permissions.
+
+### Overloads
+
+```typescript
+// Require login (any authenticated user)
+auth(fn)
+
+// Require specific roles
+auth(["admin", "editor"], fn)
+```
+
+### Service-level auth
+
+All methods in the service require authentication:
+
+```typescript
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+  updateProfile: (data: any) => { /* ... */ },
+})));
+```
+
+### Method-level auth
+
+Only specific methods require authentication or specific roles:
+
+```typescript
+const MixedService = defineService("Mixed", (ctx) => ({
+  publicMethod: () => "anyone can call this",
+  protectedMethod: auth(() => "login required"),
+  adminMethod: auth(["admin"], () => "admin only"),
+}));
+```
+
+### Permission resolution
+
+- Method-level auth takes precedence over service-level auth.
+- If `requiredPerms` is an empty array (`auth(fn)`), any authenticated user can access.
+- If `requiredPerms` contains roles (`auth(["admin"], fn)`), the user must have at least one matching role.
+
+---
+
+## `ServiceContext<TAuthInfo>`
+
+The context object passed to service factory functions.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `server` | `ServiceServer<TAuthInfo>` | The server instance |
+| `socket` | `ServiceSocket \| undefined` | WebSocket connection (if called via WebSocket) |
+| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload } \| undefined` | HTTP request info (if called via HTTP) |
+| `legacy` | `{ clientName?: string } \| undefined` | V1 legacy context (auto-update only) |
+
+### Computed Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `authInfo` | `TAuthInfo \| undefined` | The authenticated user's data from the JWT payload |
+| `clientName` | `string \| undefined` | Client application name (validated for path safety) |
+| `clientPath` | `string \| undefined` | Resolved path: `{rootPath}/www/{clientName}` |
+
+### Methods
+
+#### `getConfig<T>(section: string): Promise<T>`
+
+Reads a configuration section from `.config.json` files. Merges root-level config (`{rootPath}/.config.json`) with client-level config (`{clientPath}/.config.json`), where client values override root values.
+
+```typescript
+const dbConfig = await ctx.getConfig<DbSettings>("database");
+```
+
+---
+
+## `ServiceDefinition<TMethods>`
+
+```typescript
+interface ServiceDefinition<TMethods> {
+  name: string;
+  factory: (ctx: ServiceContext) => TMethods;
+  authPermissions?: string[];
+}
+```
+
+---
+
+## `ServiceMethods<TDefinition>`
+
+Type utility that extracts method signatures from a `ServiceDefinition`. Useful for sharing types with the client.
+
+```typescript
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+})));
+
+// Export for client-side usage
+export type UserServiceType = ServiceMethods<typeof UserService>;
+
+// Client side:
+// client.getService<UserServiceType>("User");
+```
+
+---
+
+## `executeServiceMethod(server, def): Promise<unknown>`
+
+Internal function that locates and invokes a service method. Performs service lookup, client name validation, context creation, auth checking, and method execution.
+
+## `getServiceAuthPermissions(fn): string[] | undefined`
+
+Reads auth permissions metadata from an `auth()`-wrapped function. Returns `undefined` if the function is not wrapped.

package/docs/transport.md

@@ -0,0 +1,97 @@
+# Transport
+
+Handles communication between clients and the server over WebSocket and HTTP.
+
+## WebSocket
+
+### `WebSocketHandler`
+
+Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
+
+```typescript
+interface WebSocketHandler {
+  addSocket(socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest): void;
+  closeAll(): void;
+  broadcastReload(clientName: string | undefined, changedFileSet: Set<string>): Promise<void>;
+  emit<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>;
+}
+```
+
+### `createWebSocketHandler(runMethod, jwtSecret): WebSocketHandler`
+
+Creates a WebSocket handler instance. The `runMethod` callback is invoked to execute service methods.
+
+**Message routing:**
+
+| Message Pattern | Action |
+|----------------|--------|
+| `"ServiceName.methodName"` | Invoke service method |
+| `"evt:add"` | Register event listener |
+| `"evt:remove"` | Remove event listener |
+| `"evt:gets"` | Get all listeners for an event |
+| `"evt:emit"` | Emit event to matching clients |
+| `"auth"` | Authenticate WebSocket connection via JWT |
+
+---
+
+### `ServiceSocket`
+
+Manages a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
+
+```typescript
+interface ServiceSocket {
+  readonly connectedAtDateTime: DateTime;
+  readonly clientName: string;
+  readonly connReq: FastifyRequest;
+  authTokenPayload?: AuthTokenPayload;
+
+  close(): void;
+  send(uuid: string, msg: ServiceServerMessage): Promise<number>;
+  addListener(key: string, eventName: string, info: unknown): void;
+  removeListener(key: string): void;
+  getEventListeners(eventName: string): Array<{ key: string; info: unknown }>;
+  filterEventTargetKeys(targetKeys: string[]): string[];
+  on(event: "error" | "close" | "message", handler: Function): void;
+}
+```
+
+### `createServiceSocket(socket, clientId, clientName, connReq): ServiceSocket`
+
+Creates a service socket instance. Features:
+
+- **Protocol encoding/decoding** via `ServerProtocolWrapper` (with worker thread offloading)
+- **Ping/pong keep-alive** every 5 seconds; terminates unresponsive connections
+- **Event listener tracking** for pub/sub messaging
+- **Progress reporting** for chunked message transfers
+
+---
+
+## HTTP
+
+### `handleHttpRequest<TAuthInfo>(req, reply, jwtSecret, runMethod): Promise<void>`
+
+Handles HTTP API requests on `/api/:service/:method`.
+
+- **GET**: Parameters parsed from `?json=` query parameter
+- **POST**: Parameters parsed from JSON request body (must be an array)
+- **Auth**: Reads `Authorization: Bearer <token>` header; returns 401 on failure
+- **Client name**: Required via `x-sd-client-name` header
+
+### `handleUpload(req, reply, rootPath, jwtSecret): Promise<void>`
+
+Handles multipart file uploads on `/upload`.
+
+- Requires authentication (JWT in `Authorization` header)
+- Files saved to `{rootPath}/www/uploads/` with UUID-based filenames
+- Returns `ServiceUploadResult[]` with path, original filename, and size
+- Cleans up incomplete files on failure
+
+### `handleStaticFile(req, reply, rootPath, urlPath): Promise<void>`
+
+Serves static files from `{rootPath}/www/`.
+
+- Path traversal protection
+- Auto-redirects directories to include trailing slash
+- Serves `index.html` for directory requests
+- Blocks access to hidden files (dotfiles) with 403
+- Returns appropriate HTML error pages for 403, 404, 500

package/docs/utilities.md

@@ -0,0 +1,31 @@
+# Utilities
+
+## `getConfig<TConfig>(filePath): Promise<TConfig | undefined>`
+
+Reads and caches a JSON configuration file with automatic live-reloading via file system watcher.
+
+### Features
+
+- **Caching**: Configurations are cached in a `LazyGcMap` with auto-renewal on access
+- **Live-reload**: File changes are detected and the cache is updated automatically (100ms debounce)
+- **Garbage collection**: Cache entries expire after 1 hour of inactivity; GC runs every 10 minutes
+- **Watcher cleanup**: File watchers are released when cache entries expire or files are deleted
+
+### Usage
+
+```typescript
+import { getConfig } from "@simplysm/service-server";
+
+const config = await getConfig<{ key: string }>("/path/to/.config.json");
+```
+
+This function is used internally by `ServiceContext.getConfig()` to load root and client-level configuration files.
+
+### Behavior
+
+1. Returns cached value if available (resets expiry timer)
+2. If file does not exist, returns `undefined`
+3. Reads and parses the JSON file, stores in cache
+4. Registers a file watcher for live-reload
+5. On file change: re-reads and updates cache
+6. On file deletion: removes cache entry and closes watcher

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.82",
+  "version": "13.0.83",
   "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-common": "13.0.82",
-    "@simplysm/orm-node": "13.0.82",
-    "@simplysm/orm-common": "13.0.82",
-    "@simplysm/core-node": "13.0.82",
-    "@simplysm/service-common": "13.0.82"
+    "@simplysm/core-common": "13.0.83",
+    "@simplysm/core-node": "13.0.83",
+    "@simplysm/orm-common": "13.0.83",
+    "@simplysm/orm-node": "13.0.83",
+    "@simplysm/service-common": "13.0.83"
   },
   "devDependencies": {
     "@types/nodemailer": "^6.4.23",