@simplysm/service-server 13.0.97 → 13.0.99

package/README.md

@@ -0,0 +1,163 @@
+# @simplysm/service-server
+
+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
+
+```bash
+npm install @simplysm/service-server
+```
+
+## API Overview
+
+### 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 |
+
+-> 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 } from "@simplysm/service-server";
+import { OrmService, AutoUpdateService } from "@simplysm/service-server";
+
+// Define a custom service
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok", time: new Date().toISOString() }),
+}));
+
+// Define an authenticated service
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+  adminOnly: auth(["admin"], () => "admin-only data"),
+})));
+
+// Create and start server
+const server = createServiceServer({
+  rootPath: "/app",
+  port: 3000,
+  auth: { jwtSecret: "my-secret" },
+  services: [HealthService, UserService, OrmService, AutoUpdateService],
+});
+
+await server.listen();
+```
+
+### JWT Authentication
+
+```typescript
+import { signJwt, verifyJwt } from "@simplysm/service-server";
+
+// 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

@@ -0,0 +1,59 @@
+# Auth
+
+JWT-based authentication utilities using the `jose` library (HS256 algorithm).
+
+## `AuthTokenPayload`
+
+JWT token payload with roles and custom data. Extends `JWTPayload` from `jose`.
+
+```typescript
+interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
+  roles: string[];
+  data: TAuthInfo;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `roles` | `string[]` | User roles for permission checking |
+| `data` | `TAuthInfo` | Custom auth data (user info, etc.) |
+
+## `signJwt`
+
+Sign a JWT token with HS256 algorithm. Token expires in 12 hours.
+
+```typescript
+async function signJwt<TAuthInfo = unknown>(
+  jwtSecret: string,
+  payload: AuthTokenPayload<TAuthInfo>,
+): Promise<string>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `jwtSecret` | `string` | Secret key for signing |
+| `payload` | `AuthTokenPayload<TAuthInfo>` | Token payload |
+
+## `verifyJwt`
+
+Verify and decode a JWT token. Throws on expired or invalid tokens.
+
+```typescript
+async function verifyJwt<TAuthInfo = unknown>(
+  jwtSecret: string,
+  token: string,
+): Promise<AuthTokenPayload<TAuthInfo>>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `jwtSecret` | `string` | Secret key for verification |
+| `token` | `string` | JWT token string |
+
+## `decodeJwt`
+
+Decode a JWT token without verification (for reading payload only).
+
+```typescript
+function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo>;
+```

package/docs/core.md

@@ -0,0 +1,133 @@
+# Core
+
+## `ServiceContext`
+
+Context object passed to service factory functions. Provides access to server, socket, auth info, and configuration.
+
+```typescript
+interface ServiceContext<TAuthInfo = unknown> {
+  server: ServiceServer<TAuthInfo>;
+  socket?: ServiceSocket;
+  http?: {
+    clientName: string;
+    authTokenPayload?: AuthTokenPayload<TAuthInfo>;
+  };
+  legacy?: {
+    clientName?: string;
+  };
+
+  get authInfo(): TAuthInfo | undefined;
+  get clientName(): string | undefined;
+  get clientPath(): string | undefined;
+  getConfig<T>(section: string): Promise<T>;
+}
+```
+
+| 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`
+
+Create a service context instance.
+
+```typescript
+function createServiceContext<TAuthInfo = unknown>(
+  server: ServiceServer<TAuthInfo>,
+  socket?: ServiceSocket,
+  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> },
+  legacy?: { clientName?: string },
+): ServiceContext<TAuthInfo>;
+```
+
+## `ServiceDefinition`
+
+Service definition object. Contains name, factory function, and optional auth permissions.
+
+```typescript
+interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
+  name: string;
+  factory: (ctx: ServiceContext) => TMethods;
+  authPermissions?: string[];
+}
+```
+
+| 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.
+
+```typescript
+function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
+  name: string,
+  factory: (ctx: ServiceContext) => TMethods,
+): ServiceDefinition<TMethods>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Service name |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function |
+
+## `auth`
+
+Auth wrapper for service factories and methods. Can be applied at service-level or method-level with optional role requirements.
+
+```typescript
+function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
+function auth<TFunction extends (...args: any[]) => any>(
+  permissions: string[],
+  fn: TFunction,
+): TFunction;
+```
+
+| 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
+function getServiceAuthPermissions(fn: Function): string[] | undefined;
+```
+
+## `ServiceMethods`
+
+Extract method signatures from a `ServiceDefinition` for client-side type sharing.
+
+```typescript
+type ServiceMethods<TDefinition> =
+  TDefinition extends ServiceDefinition<infer M> ? M : never;
+```
+
+## `executeServiceMethod`
+
+Execute a service method with authentication and authorization checks.
+
+```typescript
+async function executeServiceMethod(
+  server: ServiceServer,
+  def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+    http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
+  },
+): Promise<unknown>;
+```

package/docs/server.md

@@ -0,0 +1,126 @@
+# Server
+
+## `ServiceServerOptions`
+
+Configuration options for `ServiceServer`.
+
+```typescript
+interface ServiceServerOptions {
+  rootPath: string;
+  port: number;
+  ssl?: {
+    pfxBytes: Uint8Array;
+    passphrase: string;
+  };
+  auth?: {
+    jwtSecret: string;
+  };
+  services: ServiceDefinition[];
+}
+```
+
+| 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 |
+
+## `ServiceServer`
+
+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;
+}> {
+  isOpen: boolean;
+  readonly fastify: FastifyInstance;
+  readonly options: ServiceServerOptions;
+
+  constructor(options: ServiceServerOptions);
+
+  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>;
+  signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
+  verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
+}
+```
+
+| 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
+
+## `createServiceServer`
+
+Factory function to create a `ServiceServer` instance.
+
+```typescript
+function createServiceServer<TAuthInfo = unknown>(
+  options: ServiceServerOptions,
+): ServiceServer<TAuthInfo>;
+```
+
+## Utils
+
+### `getConfig`
+
+Read JSON configuration from file with caching and live-reload via file watcher. Cache expires after 1 hour.
+
+```typescript
+async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
+```
+
+## 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;
+```

package/docs/services.md

@@ -0,0 +1,58 @@
+# Built-in Services
+
+Pre-defined service definitions ready to use with `ServiceServer`.
+
+## `OrmService`
+
+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;
+```
+
+Implements the `OrmService` interface from `@simplysm/service-common`:
+
+| 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`
+
+Server-side auto-update service implementation. Scans the client's platform-specific `updates/` directory for version files.
+
+```typescript
+const AutoUpdateService: ServiceDefinition;
+```
+
+Implements the `AutoUpdateService` interface from `@simplysm/service-common`:
+
+| 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`
+
+Server-side SMTP email sending service. Uses `nodemailer` under the hood.
+
+```typescript
+const SmtpClientService: ServiceDefinition;
+```
+
+| Method | Description |
+|--------|-------------|
+| `send(options)` | Send email with full SMTP options |
+| `sendByDefault(options)` | Send email using server's default SMTP config |

package/docs/transport.md

@@ -0,0 +1,164 @@
+# Transport
+
+## WebSocket Transport
+
+### `WebSocketHandler`
+
+WebSocket handler interface. 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>;
+}
+```
+
+| 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;
+  }) => Promise<unknown>,
+  jwtSecret?: string,
+): WebSocketHandler;
+```
+
+### `ServiceSocket`
+
+Service socket interface. 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;
+}
+```
+
+| 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,
+  clientId: string,
+  clientName: string,
+  connReq: FastifyRequest,
+): ServiceSocket;
+```
+
+## HTTP Transport
+
+### `handleHttpRequest`
+
+Handle HTTP API requests. Routes `POST/GET /api/:service/:method` to service methods.
+
+```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>;
+```
+
+### `handleUpload`
+
+Handle file upload requests. Accepts multipart form data with auth token.
+
+```typescript
+async function handleUpload(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  jwtSecret: string | undefined,
+): Promise<void>;
+```
+
+### `handleStaticFile`
+
+Handle static file serving. Serves files from `www/` directory with security checks (path traversal protection, hidden file blocking).
+
+```typescript
+async function handleStaticFile(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  urlPath: string,
+): Promise<void>;
+```
+
+## 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.97",
+  "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-common": "13.0.97",
-    "@simplysm/core-node": "13.0.97",
-    "@simplysm/orm-node": "13.0.97",
-    "@simplysm/orm-common": "13.0.97",
-    "@simplysm/service-common": "13.0.97"
+    "@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",