@simplysm/service-server 13.0.69 → 13.0.70

package/docs/server.md

@@ -1,374 +0,0 @@
-# ServiceServer
-
-## ServiceServer
-
-`ServiceServer<TAuthInfo>` extends `EventEmitter` and is the main entry point for creating a server.
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|------|
-| `options` | `ServiceServerOptions` | Server configuration (read-only, passed via constructor) |
-| `isOpen` | `boolean` | Whether the server is currently listening |
-| `fastify` | `FastifyInstance` | Underlying Fastify instance (read-only, for advanced use) |
-
-**Methods:**
-
-| Method | Returns | Description |
-|--------|---------|------|
-| `listen()` | `Promise<void>` | Register all plugins/routes and start listening |
-| `close()` | `Promise<void>` | Close all WebSocket connections and shut down the server |
-| `generateAuthToken(payload)` | `Promise<string>` | Generate a JWT token (HS256, 12-hour expiration) |
-| `verifyAuthToken(token)` | `Promise<AuthTokenPayload<TAuthInfo>>` | Verify and decode a JWT token |
-| `emitEvent(eventDef, infoSelector, data)` | `Promise<void>` | Publish an event to matching WebSocket clients |
-| `broadcastReload(clientName, changedFileSet)` | `Promise<void>` | Send a reload command to all connected clients |
-
-**Events:**
-
-| Event | Payload | Description |
-|-------|---------|------|
-| `ready` | `void` | Emitted when the server starts listening |
-| `close` | `void` | Emitted when the server is closed |
-
-## createServiceServer
-
-Factory function for creating a `ServiceServer` instance:
-
-```typescript
-import { createServiceServer } from "@simplysm/service-server";
-
-const server = createServiceServer({
-  port: 8080,
-  rootPath: "/app/data",
-  auth: { jwtSecret: "my-secret-key" },
-  services: [MyService],
-});
-```
-
-## Server Options (`ServiceServerOptions`)
-
-```typescript
-import type { ServiceServerOptions } from "@simplysm/service-server";
-
-interface ServiceServerOptions {
-  /** Server root path (base directory for static files and config files) */
-  rootPath: string;
-  /** Listen port */
-  port: number;
-  /** SSL/TLS config (enables HTTPS) */
-  ssl?: {
-    pfxBytes: Uint8Array;
-    passphrase: string;
-  };
-  /** JWT authentication config */
-  auth?: {
-    jwtSecret: string;
-  };
-  /** List of service definitions to register */
-  services: ServiceDefinition[];
-}
-```
-
-The following structure is expected under `rootPath`:
-
-```
-rootPath/
-  .config.json        # Root config file
-  www/                # Static file root
-    uploads/          # Upload file storage directory
-    {clientName}/     # Per-client directory
-      .config.json    # Per-client config file
-      index.html
-```
-
-## SSL/HTTPS Server
-
-```typescript
-import { createServiceServer } from "@simplysm/service-server";
-import { fsReadFile } from "@simplysm/core-node";
-
-const pfxBytes = await fsReadFile("/path/to/cert.pfx");
-
-const server = createServiceServer({
-  port: 443,
-  rootPath: "/app/data",
-  ssl: {
-    pfxBytes,
-    passphrase: "certificate-password",
-  },
-  auth: { jwtSecret: "my-secret-key" },
-  services: [],
-});
-
-await server.listen();
-```
-
-## Custom Service Definition
-
-Define services using the `defineService` function. Service methods are called via RPC from the client.
-
-```typescript
-import { defineService } from "@simplysm/service-server";
-
-export const MyService = defineService("My", (ctx) => ({
-  hello: async (name: string): Promise<string> => {
-    return `Hello, ${name}!`;
-  },
-
-  getServerTime: async (): Promise<Date> => {
-    return new Date();
-  },
-}));
-
-// Export type for client-side type sharing
-export type MyServiceMethods = import("@simplysm/service-server").ServiceMethods<typeof MyService>;
-```
-
-### ServiceContext
-
-The `ctx` parameter provides access to server resources within service methods.
-
-| Property | Type | Description |
-|----------|------|------|
-| `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}`) |
-
-### ServiceContext Methods
-
-| Method | Returns | Description |
-|--------|---------|------|
-| `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);
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `server` | `ServiceServer<TAuthInfo>` | The server instance |
-| `socket` | `ServiceSocket \| undefined` | WebSocket connection, or `undefined` for HTTP/legacy |
-| `http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> } \| undefined` | HTTP request context |
-| `legacy` | `{ clientName?: string } \| undefined` | V1 legacy context (auto-update only) |
-
-## ServiceDefinition
-
-Type describing a registered service. Created by `defineService()`.
-
-```typescript
-import type { ServiceDefinition } from "@simplysm/service-server";
-
-interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
-  /** Service name (used as RPC route prefix, e.g., "User" → "User.getProfile") */
-  name: string;
-  /** Factory function that returns the service's method object */
-  factory: (ctx: ServiceContext) => TMethods;
-  /** Auth permissions required at service level (set by wrapping factory with auth()) */
-  authPermissions?: string[];
-}
-```
-
-Pass `ServiceDefinition[]` to `ServiceServerOptions.services` when creating the server.
-
-## ServiceMethods
-
-Type utility that extracts method signatures from a `ServiceDefinition`. Use this to share method types with the client without exposing implementation details.
-
-```typescript
-import type { ServiceMethods } from "@simplysm/service-server";
-
-export const MyService = defineService("My", (ctx) => ({
-  hello: async (name: string): Promise<string> => `Hello, ${name}!`,
-}));
-
-// Export type for client-side type sharing
-export type MyServiceType = ServiceMethods<typeof MyService>;
-// Equivalent to: { hello: (name: string) => Promise<string> }
-
-// Client usage:
-// const service = client.getService<MyServiceType>("My");
-// const result = await service.hello("World");
-```
-
-## runServiceMethod
-
-Dispatches a single service method call. Performs auth checks and executes the method. Used internally by `ServiceServer` for both WebSocket and HTTP transports, but exported for advanced use cases such as custom transports or testing.
-
-```typescript
-import { runServiceMethod } from "@simplysm/service-server";
-
-const result = await runServiceMethod(server, {
-  serviceName: "My",
-  methodName: "hello",
-  params: ["World"],
-  socket: serviceSocket, // or undefined for HTTP
-  http: undefined,       // or { clientName, authTokenPayload } for HTTP
-});
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `server` | `ServiceServer` | The server instance |
-| `def.serviceName` | `string` | Name of the service to dispatch to |
-| `def.methodName` | `string` | Name of the method to invoke |
-| `def.params` | `unknown[]` | Positional arguments for the method |
-| `def.socket` | `ServiceSocket \| undefined` | WebSocket context (for WebSocket requests) |
-| `def.http` | `{ clientName: string; authTokenPayload?: AuthTokenPayload } \| undefined` | HTTP context (for HTTP requests) |
-
-Returns: `Promise<unknown>` — the method's return value.
-
-Throws if the service or method is not found, or if the caller lacks required auth permissions.
-
-## Config File Reference
-
-Read sections from `.config.json` files using `ctx.getConfig()`. Root and per-client configs are automatically merged.
-
-```typescript
-import { defineService } from "@simplysm/service-server";
-
-export const MyService = defineService("My", (ctx) => ({
-  getDbHost: async (): Promise<string> => {
-    // Read "mySection" key from rootPath/.config.json or clientPath/.config.json
-    const config = await ctx.getConfig<{ host: string }>("mySection");
-    return config.host;
-  },
-}));
-```
-
-`.config.json` example:
-
-```json
-{
-  "mySection": {
-    "host": "localhost"
-  },
-  "orm": {
-    "default": {
-      "dialect": "mysql",
-      "host": "localhost",
-      "port": 3306,
-      "database": "mydb",
-      "user": "root",
-      "password": "password"
-    }
-  }
-}
-```
-
-Config files are cached and automatically refreshed on file changes (LazyGcMap-based, auto expires after 1 hour).
-
-## getConfig
-
-A standalone function that loads, caches, and watches JSON config files. Used internally by `ctx.getConfig()`.
-
-```typescript
-import { getConfig } from "@simplysm/service-server";
-
-// Returns undefined if the file does not exist
-const config = await getConfig<MyConfig>("/path/to/.config.json");
-```
-
-| Signature | Returns | Description |
-|-----------|---------|------|
-| `getConfig<T>(filePath: string)` | `Promise<T \| undefined>` | Load and cache a JSON config file. Returns `undefined` if file not found |
-
-Behavior:
-- Caches file in `LazyGcMap` on first load.
-- Registers file change watch (`FsWatcher`) to auto-refresh cache on changes.
-- Cache auto-expires after 1 hour of no access, and associated watcher is released.
-- GC runs every 10 minutes to check for expired entries.
-
-## Server Route Structure
-
-The following routes are automatically registered when `ServiceServer.listen()` is called:
-
-| Route | Method | Description |
-|--------|--------|------|
-| `/api/:service/:method` | GET, POST | Service method call via HTTP |
-| `/upload` | POST | Multipart file upload (auth required) |
-| `/` | WebSocket | WebSocket connection endpoint |
-| `/ws` | WebSocket | WebSocket connection endpoint (alias) |
-| `/*` | GET, etc. | Static file serving (based on `rootPath/www/`) |
-
-## Full Server Example
-
-```typescript
-import { createServiceServer, defineService, auth, OrmService } from "@simplysm/service-server";
-import { defineEvent } from "@simplysm/service-common";
-
-// Define a custom service with auth
-export const UserService = defineService("User", auth((ctx) => ({
-  getProfile: async (): Promise<{ name: string }> => {
-    const userId = (ctx.authInfo as { userId: number; role: string })?.userId;
-    // Use ctx.getConfig(), ctx.socket, ctx.server, etc.
-    return { name: "John" };
-  },
-
-  deleteUser: auth(["admin"], async (targetId: number): Promise<void> => {
-    // Admin-only operation
-  }),
-})));
-
-export const PublicService = defineService("Public", (ctx) => ({
-  healthCheck: async (): Promise<string> => {
-    return "OK";
-  },
-}));
-
-// Create and start server
-const server = createServiceServer({
-  port: 8080,
-  rootPath: "/app/data",
-  auth: { jwtSecret: "my-secret-key" },
-  services: [UserService, PublicService, OrmService],
-});
-
-server.on("ready", () => {
-  console.log("Server is ready on port 8080");
-});
-
-await server.listen();
-
-// Generate auth token for a user
-const token = await server.generateAuthToken({
-  roles: ["admin"],
-  data: { userId: 1, role: "admin" },
-});
-
-// Emit events to connected clients
-const UserUpdatedEvent = defineEvent<
-  { userId: number },
-  { action: string }
->("UserUpdatedEvent");
-
-await server.emitEvent(
-  UserUpdatedEvent,
-  (info) => info.userId === 1,
-  { action: "profile-updated" },
-);
-```
-
-## Security
-
-- **Helmet**: `@fastify/helmet` plugin automatically sets security headers like CSP, HSTS.
-- **CORS**: `@fastify/cors` plugin configures CORS.
-- **Path Traversal Prevention**: Static file handler and client name validation block `..`, `/`, `\` characters.
-- **Hidden File Blocking**: Files starting with `.` return a 403 response.
-- **Graceful Shutdown**: Detects `SIGINT`/`SIGTERM` signals to safely close open WebSocket connections and server (10-second timeout).
-
-## Caveats
-
-- `OrmService` is WebSocket-only. Cannot be used via HTTP requests.
-- Config files (`.config.json`) contain sensitive information (DB passwords, JWT secrets, etc.), so hidden files (starting with `.`) are automatically blocked by the static file handler.
-- WebSocket connection requires query parameters `ver=2`, `clientId`, `clientName`. Without these parameters, it operates in V1 legacy mode.
-- If SSL is not configured, the `upgrade-insecure-requests` CSP directive is disabled.

package/docs/transport.md

@@ -1,273 +0,0 @@
-# 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`).
-
-### createWebSocketHandler
-
-Factory function that creates a `WebSocketHandler` instance.
-
-```typescript
-import { createWebSocketHandler } from "@simplysm/service-server";
-
-const handler = createWebSocketHandler(runMethod, jwtSecret);
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `runMethod` | `(def: { serviceName: string; methodName: string; params: unknown[]; socket?: ServiceSocket }) => Promise<unknown>` | Function to execute service method calls |
-| `jwtSecret` | `string \| undefined` | JWT secret for authentication (`undefined` disables auth) |
-
-**Returns:** `WebSocketHandler`
-
-## ServiceSocket
-
-`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:**
-
-| Property | Type | Description |
-|----------|------|------|
-| `clientName` | `string` | Client app name (from WebSocket query parameter) |
-| `connectedAtDateTime` | `DateTime` | Connection timestamp |
-| `authTokenPayload` | `AuthTokenPayload \| undefined` | Authenticated token payload (set after `auth` message) |
-| `connReq` | `FastifyRequest` | Original Fastify request that initiated the WebSocket upgrade |
-
-**Methods:**
-
-| Method | Returns | Description |
-|--------|---------|------|
-| `send(uuid, msg)` | `Promise<number>` | Send a message to this client. Returns total bytes sent |
-| `close()` | `void` | Terminate the WebSocket connection |
-| `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:**
-
-| Event | Payload | Description |
-|-------|---------|------|
-| `error` | `Error` | WebSocket error occurred |
-| `close` | `number` | Connection closed (payload is the close code) |
-| `message` | `{ uuid: string; msg: ServiceClientMessage }` | Decoded message received from client |
-
-### createServiceSocket
-
-Factory function that creates a `ServiceSocket` instance wrapping a raw WebSocket.
-
-```typescript
-import { createServiceSocket } from "@simplysm/service-server";
-
-const serviceSocket = createServiceSocket(socket, clientId, clientName, connReq);
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `socket` | `WebSocket` | Raw WebSocket connection |
-| `clientId` | `string` | Unique client identifier |
-| `clientName` | `string` | Client app name |
-| `connReq` | `FastifyRequest` | Original Fastify request that initiated the WebSocket upgrade |
-
-**Returns:** `ServiceSocket`
-
-## HTTP API Call
-
-Service methods can also be called via HTTP through the `/api/:service/:method` path.
-
-**GET Request:**
-
-```
-GET /api/MyService/hello?json=["World"]
-Header: x-sd-client-name: my-app
-Header: Authorization: Bearer <token>  (optional)
-```
-
-**POST Request:**
-
-```
-POST /api/MyService/hello
-Header: Content-Type: application/json
-Header: x-sd-client-name: my-app
-Header: Authorization: Bearer <token>  (optional)
-Body: ["World"]
-```
-
-- The `x-sd-client-name` header is required.
-- 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);
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `req` | `FastifyRequest` | Fastify request object |
-| `reply` | `FastifyReply` | Fastify reply object |
-| `jwtSecret` | `string \| undefined` | JWT secret for authentication |
-| `runMethod` | `(def: { serviceName: string; methodName: string; params: unknown[]; http: { clientName: string; authTokenPayload?: AuthTokenPayload } }) => Promise<unknown>` | Function to execute service method calls |
-
-## File Upload
-
-Upload files via multipart request to the `/upload` endpoint. Auth token is required.
-
-```typescript
-// Client-side example
-const formData = new FormData();
-formData.append("file", file);
-
-const response = await fetch("/upload", {
-  method: "POST",
-  headers: {
-    Authorization: `Bearer ${token}`,
-  },
-  body: formData,
-});
-
-// Response: ServiceUploadResult[]
-const results = await response.json();
-// [{ path: "uploads/uuid.ext", filename: "original-filename.ext", size: 12345 }]
-```
-
-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);
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `req` | `FastifyRequest` | Fastify request object (must be multipart) |
-| `reply` | `FastifyReply` | Fastify reply object |
-| `rootPath` | `string` | Server root path (files stored under `rootPath/www/uploads/`) |
-| `jwtSecret` | `string \| undefined` | JWT secret for authentication |
-
-### 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);
-```
-
-| Parameter | Type | Description |
-|-----------|------|------|
-| `req` | `FastifyRequest` | Fastify request object |
-| `reply` | `FastifyReply` | Fastify reply object |
-| `rootPath` | `string` | Server root path (serves files from `rootPath/www/`) |
-| `urlPath` | `string` | URL path relative to the root |
-
-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`.
-
-```typescript
-import { createServiceServer } from "@simplysm/service-server";
-import { defineEvent } from "@simplysm/service-common";
-
-// Event definition
-const OrderUpdatedEvent = defineEvent<
-  { orderId: number },
-  { status: string }
->("OrderUpdatedEvent");
-
-// Publish event from server
-await server.emitEvent(
-  OrderUpdatedEvent,
-  (info) => info.orderId === 123,    // Target filter
-  { status: "completed" },           // Data to send
-);
-
-// Send reload command to all clients
-await server.broadcastReload("my-app", new Set(["main.js"]));
-```
-
-## ProtocolWrapper
-
-`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. Uses a shared worker singleton internally.
-
-### createProtocolWrapper
-
-Factory function that creates a `ProtocolWrapper` instance.
-
-**Returns:** `ProtocolWrapper` (no parameters)
-
-```typescript
-import { createProtocolWrapper } from "@simplysm/service-server";
-
-const protocol = createProtocolWrapper();
-
-// Encode a message into chunks
-const { chunks, totalSize } = await protocol.encode(uuid, message);
-
-// Decode received bytes
-const result = await protocol.decode(bytes);
-
-// Clean up
-protocol.dispose();
-```
-
-| Method | Returns | Description |
-|--------|---------|------|
-| `encode(uuid, message)` | `Promise<{ chunks: Uint8Array[]; totalSize: number }>` | Encode a message into transmittable chunks |
-| `decode(bytes)` | `Promise<ServiceMessageDecodeResult>` | Decode received bytes into a message |
-| `dispose()` | `void` | Clean up internal protocol resources |
-
-Worker thread branching:
-
-| Condition | Processing Method |
-|------|-----------|
-| 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 regardless of size.
-
-## Legacy: handleV1Connection
-
-Handles V1 protocol WebSocket clients. Only supports the `SdAutoUpdateService.getLastVersion` command. All other requests return an upgrade-required error.
-
-```typescript
-import { handleV1Connection, AutoUpdateService } from "@simplysm/service-server";
-
-// Used internally by ServiceServer for WebSocket connections without ver=2 query parameter
-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 |