@simplysm/service-server 13.0.96 → 13.0.98

package/docs/server.md

@@ -0,0 +1,206 @@
+# Server
+
+## ServiceServerOptions
+
+Server configuration options.
+
+```typescript
+interface ServiceServerOptions {
+  rootPath: string;
+  port: number;
+  ssl?: {
+    pfxBytes: Uint8Array;
+    passphrase: string;
+  };
+  auth?: {
+    jwtSecret: string;
+  };
+  services: ServiceDefinition[];
+}
+```
+
+## ServerProtocolWrapper
+
+Server-side protocol wrapper. Automatically offloads heavy message encoding/decoding to a worker thread while using main thread for lightweight operations.
+
+```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 }>`.
+
+```typescript
+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>(
+    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>>;
+}
+```
+
+### `listen`
+
+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`
+
+Emit an event to matching WebSocket clients.
+
+```typescript
+async emitEvent<TInfo, TData>(
+  eventDef: ServiceEventDef<TInfo, TData>,
+  infoSelector: (item: TInfo) => boolean,
+  data: TData,
+): Promise<void>;
+```
+
+### `signAuthToken`
+
+Sign a JWT auth token.
+
+```typescript
+async signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
+```
+
+### `verifyAuthToken`
+
+Verify a JWT auth token.
+
+```typescript
+async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
+```
+
+## `createServiceServer`
+
+Factory function.
+
+```typescript
+function createServiceServer<TAuthInfo = unknown>(
+  options: ServiceServerOptions,
+): ServiceServer<TAuthInfo>;
+```
+
+## Example
+
+```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();
+```

package/docs/services.md

@@ -0,0 +1,176 @@
+# Built-in Services
+
+Pre-defined service definitions ready to use with `ServiceServer`.
+
+## 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
+
+```typescript
+const OrmService: ServiceDefinition;
+```
+
+Service name: `"Orm"`
+
+### Methods
+
+```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"
+    }
+  }
+}
+```
+
+---
+
+## AutoUpdateService
+
+Auto-update service for client applications. No authentication required.
+
+```typescript
+import { AutoUpdateService, type AutoUpdateServiceType } from "@simplysm/service-server";
+```
+
+### Definition
+
+```typescript
+const AutoUpdateService: ServiceDefinition;
+```
+
+Service name: `"AutoUpdate"`
+
+### Methods
+
+```typescript
+interface AutoUpdateServiceType {
+  getLastVersion(platform: string): Promise<
+    | { version: string; downloadPath: string }
+    | undefined
+  >;
+}
+```
+
+**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
+
+---
+
+## SmtpClientService
+
+SMTP email sending service. No authentication required.
+
+```typescript
+import { SmtpClientService, type SmtpClientServiceType } from "@simplysm/service-server";
+```
+
+### Definition
+
+```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],
+});
+```

package/docs/transport.md

@@ -0,0 +1,152 @@
+# Transport
+
+## WebSocket Transport
+
+### `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`
+
+```typescript
+function createWebSocketHandler(
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+  }) => Promise<unknown>,
+  jwtSecret: string | undefined,
+): 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.
+
+```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", handler: (err: Error) => void): void;
+  on(event: "close", handler: (code: number) => void): void;
+  on(event: "message", handler: (data: { uuid: string; msg: ServiceClientMessage }) => void): void;
+}
+```
+
+### `createServiceSocket`
+
+```typescript
+function createServiceSocket(
+  socket: WebSocket,
+  clientId: string,
+  clientName: string,
+  connReq: FastifyRequest,
+): 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`.
+
+```typescript
+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>;
+```
+
+**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`.
+
+```typescript
+async function handleUpload(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  jwtSecret: string | undefined,
+): 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.
+
+```typescript
+async function handleStaticFile(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  urlPath: string,
+): 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.96",
+  "version": "13.0.98",
   "description": "Simplysm package - service module (server)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -30,17 +30,17 @@
     "bufferutil": "^4.1.0",
     "consola": "^3.4.2",
     "fastify": "^5.8.2",
-    "jose": "^6.2.1",
+    "jose": "^6.2.2",
     "mime": "^4.1.0",
-    "nodemailer": "^8.0.2",
+    "nodemailer": "^8.0.3",
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.19.0",
-    "@simplysm/core-node": "13.0.96",
-    "@simplysm/core-common": "13.0.96",
-    "@simplysm/orm-node": "13.0.96",
-    "@simplysm/orm-common": "13.0.96",
-    "@simplysm/service-common": "13.0.96"
+    "@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"
   },
   "devDependencies": {
     "@types/nodemailer": "^7.0.11",