@simplysm/service-server 13.0.100 → 14.0.4

package/docs/core.md

@@ -1,10 +1,12 @@
 # Core
 
-## `ServiceContext`
+Service definition, context, authentication wrapper, and method execution.
 
-Context object passed to service factory functions. Provides access to server, socket, auth info, and configuration.
+## ServiceContext\<TAuthInfo\>
 
-```typescript
+Context object passed to service factory functions. Provides access to the server, socket, HTTP info, and authentication state.
+
+```ts
 interface ServiceContext<TAuthInfo = unknown> {
   server: ServiceServer<TAuthInfo>;
   socket?: ServiceSocket;
@@ -15,7 +17,6 @@ interface ServiceContext<TAuthInfo = unknown> {
   legacy?: {
     clientName?: string;
   };
-
   get authInfo(): TAuthInfo | undefined;
   get clientName(): string | undefined;
   get clientPath(): string | undefined;
@@ -23,22 +24,24 @@ interface ServiceContext<TAuthInfo = unknown> {
 }
 ```
 
-| 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 |
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `server` | property | `ServiceServer<TAuthInfo>` | Reference to the server instance |
+| `socket` | property | `ServiceSocket?` | WebSocket connection (present for WS calls) |
+| `http` | property | `{ clientName; authTokenPayload? }?` | HTTP request info (present for HTTP calls) |
+| `http.clientName` | field | `string` | Client identifier from HTTP header |
+| `http.authTokenPayload` | field | `AuthTokenPayload<TAuthInfo>?` | Decoded auth token from HTTP request |
+| `legacy` | property | `{ clientName? }?` | Legacy V1 connection info |
+| `authInfo` | getter | `TAuthInfo \| undefined` | Authenticated user data (from socket or HTTP token) |
+| `clientName` | getter | `string \| undefined` | Client name (from socket, HTTP, or legacy) |
+| `clientPath` | getter | `string \| undefined` | Client path identifier |
+| `getConfig` | method | `<T>(section: string) => Promise<T>` | Read a configuration section |
 
-## `createServiceContext`
+## createServiceContext
 
-Create a service context instance.
+Create a `ServiceContext` instance.
 
-```typescript
+```ts
 function createServiceContext<TAuthInfo = unknown>(
   server: ServiceServer<TAuthInfo>,
   socket?: ServiceSocket,
@@ -47,11 +50,59 @@ function createServiceContext<TAuthInfo = unknown>(
 ): ServiceContext<TAuthInfo>;
 ```
 
-## `ServiceDefinition`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `ServiceServer<TAuthInfo>` | Server instance |
+| `socket` | `ServiceSocket?` | WebSocket connection |
+| `http` | `{ clientName; authTokenPayload? }?` | HTTP request context |
+| `legacy` | `{ clientName? }?` | Legacy V1 context |
+
+## auth
 
-Service definition object. Contains name, factory function, and optional auth permissions.
+Authentication wrapper for service factories and methods. Marks a function as requiring authentication. Optionally restricts access to specific roles.
 
-```typescript
+```ts
+// No role restriction -- just requires authentication
+function auth<TFunction extends (...args: any[]) => any>(fn: TFunction): TFunction;
+
+// With role restriction
+function auth<TFunction extends (...args: any[]) => any>(permissions: string[], fn: TFunction): TFunction;
+```
+
+Can be applied at the service level (wrapping the factory) or at individual method level.
+
+```ts
+const MyService = defineService("My", (ctx) => ({
+  // Public method -- no auth required
+  publicMethod() { return "open"; },
+
+  // Requires authentication (any role)
+  protectedMethod: auth(() => "protected"),
+
+  // Requires "admin" role
+  adminMethod: auth(["admin"], () => "admin only"),
+}));
+```
+
+## getServiceAuthPermissions
+
+Read the authentication permissions from a function wrapped with `auth()`. Returns `undefined` if the function is not wrapped.
+
+```ts
+function getServiceAuthPermissions(fn: Function): string[] | undefined;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fn` | `Function` | A potentially auth-wrapped function |
+
+Returns `string[]` (role list, possibly empty for auth-only) or `undefined` (not wrapped).
+
+## ServiceDefinition\<TMethods\>
+
+A named service with a factory function and optional auth permissions.
+
+```ts
 interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
   name: string;
   factory: (ctx: ServiceContext) => TMethods;
@@ -61,15 +112,15 @@ interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>>
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `name` | `string` | Service name |
-| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function that creates method object |
-| `authPermissions` | `string[]` | Required permissions (from `auth()` wrapper) |
+| `name` | `string` | Service name used for RPC routing |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function that creates service methods |
+| `authPermissions` | `string[]?` | Service-level auth permissions (from `auth()` wrapper) |
 
-## `defineService`
+## defineService
 
-Define a service with a name and factory function.
+Define a named service from a factory function.
 
-```typescript
+```ts
 function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
   name: string,
   factory: (ctx: ServiceContext) => TMethods,
@@ -79,47 +130,44 @@ function defineService<TMethods extends Record<string, (...args: any[]) => any>>
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `name` | `string` | Service name |
-| `factory` | `(ctx: ServiceContext) => TMethods` | Factory function |
+| `factory` | `(ctx: ServiceContext) => TMethods` | Factory that receives context and returns methods |
 
-## `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;
+```ts
+const UserService = defineService("User", (ctx) => ({
+  async getUser(id: number) {
+    // ctx.authInfo, ctx.server, ctx.getConfig, etc.
+    return { id, name: "Alice" };
+  },
+}));
 ```
 
-| Overload | Description |
-|----------|-------------|
-| `auth(fn)` | Require login (any authenticated user) |
-| `auth(["admin"], fn)` | Require specific roles |
-
-## `getServiceAuthPermissions`
+## ServiceMethods\<TDefinition\>
 
-Read auth permissions from an `auth()`-wrapped function. Returns `undefined` if not wrapped.
+Utility type that extracts method signatures from a `ServiceDefinition`. Useful for sharing types with the client.
 
-```typescript
-function getServiceAuthPermissions(fn: Function): string[] | undefined;
+```ts
+type ServiceMethods<TDefinition> = TDefinition extends ServiceDefinition<infer M> ? M : never;
 ```
 
-## `ServiceMethods`
+```ts
+// Server
+const UserService = defineService("User", (ctx) => ({
+  getUser(id: number) { return { id, name: "Alice" }; },
+}));
 
-Extract method signatures from a `ServiceDefinition` for client-side type sharing.
+// Shared type for client
+type UserServiceType = ServiceMethods<typeof UserService>;
 
-```typescript
-type ServiceMethods<TDefinition> =
-  TDefinition extends ServiceDefinition<infer M> ? M : never;
+// Client
+const userSvc = client.getService<UserServiceType>("User");
+const user = await userSvc.getUser(1); // typed as { id: number; name: string }
 ```
 
-## `executeServiceMethod`
+## executeServiceMethod
 
-Execute a service method with authentication and authorization checks.
+Execute a service method by name. Used internally by the transport layer; can also be called directly for testing or custom routing.
 
-```typescript
+```ts
 async function executeServiceMethod(
   server: ServiceServer,
   def: {
@@ -131,3 +179,14 @@ async function executeServiceMethod(
   },
 ): Promise<unknown>;
 ```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `ServiceServer` | Server instance containing registered services |
+| `def.serviceName` | `string` | Name of the service to invoke |
+| `def.methodName` | `string` | Method name within the service |
+| `def.params` | `unknown[]` | Method arguments |
+| `def.socket` | `ServiceSocket?` | WebSocket context (for WS calls) |
+| `def.http` | `{ clientName; authTokenPayload? }?` | HTTP context (for HTTP calls) |
+
+Returns the method return value.

package/docs/legacy.md

@@ -0,0 +1,21 @@
+# Legacy
+
+## handleV1Connection
+
+V1 legacy client handler. Only supports auto-update requests; all other requests receive an upgrade-required error.
+
+```ts
+function handleV1Connection(
+  socket: WebSocket,
+  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
+  clientNameSetter?: (clientName: string | undefined) => void,
+): void;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `WebSocket` | Raw WebSocket connection from the V1 client |
+| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update method implementation |
+| `clientNameSetter` | `((clientName: string \| undefined) => void)?` | Optional callback invoked with the client name when connected (or `undefined` on disconnect) |
+
+This handler is provided for backward compatibility with V1 protocol clients. New clients should use the V2 binary protocol.

package/docs/main.md

@@ -0,0 +1,81 @@
+# Main
+
+## ServiceServer\<TAuthInfo\>
+
+Main server class. Extends `EventEmitter` with `ready` and `close` events. Manages Fastify, WebSocket connections, service routing, and event broadcasting.
+
+```ts
+class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
+  ready: void;
+  close: void;
+}> {
+  constructor(options: ServiceServerOptions);
+}
+```
+
+### Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `ready` | `void` | Emitted when the server is listening and ready |
+| `close` | `void` | Emitted when the server has shut down |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isOpen` | `boolean` | Whether the server is currently listening |
+| `fastify` | `FastifyInstance` | Underlying Fastify instance for advanced configuration |
+| `options` | `ServiceServerOptions` | Server configuration options |
+
+### Methods
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `listen` | -- | `Promise<void>` | Start the server and begin accepting connections |
+| `close` | -- | `Promise<void>` | Gracefully shut down the server |
+| `emitEvent` | `eventDef: ServiceEventDef<TInfo, TData>`, `infoSelector: (item: TInfo) => boolean`, `data: TData` | `Promise<void>` | Broadcast an event to matching listeners across all connected sockets |
+| `signAuthToken` | `payload: AuthTokenPayload<TAuthInfo>` | `Promise<string>` | Sign a JWT token using the server's configured secret |
+| `verifyAuthToken` | `token: string` | `Promise<AuthTokenPayload<TAuthInfo>>` | Verify and decode a JWT token |
+
+### Usage
+
+```ts
+import { createServiceServer, defineService } from "@simplysm/service-server";
+
+const server = createServiceServer({
+  rootPath: process.cwd(),
+  port: 3000,
+  auth: { jwtSecret: "secret" },
+  services: [
+    defineService("Hello", () => ({
+      greet(name: string) { return `Hello, ${name}!`; },
+    })),
+  ],
+});
+
+server.on("ready", () => {
+  // server is listening
+});
+
+await server.listen();
+
+// Later: shut down
+await server.close();
+```
+
+## createServiceServer
+
+Factory function to create a `ServiceServer` instance.
+
+```ts
+function createServiceServer<TAuthInfo = unknown>(
+  options: ServiceServerOptions,
+): ServiceServer<TAuthInfo>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `ServiceServerOptions` | Server configuration |
+
+Returns a new `ServiceServer` instance. Call `listen()` to start accepting connections.

package/docs/protocol.md

@@ -0,0 +1,31 @@
+# Protocol
+
+Server-side protocol wrapper that automatically delegates heavy message encoding/decoding to worker threads.
+
+## ServerProtocolWrapper
+
+Protocol wrapper interface. Heavy messages are encoded/decoded in a worker thread; lightweight messages are processed on the main thread.
+
+```ts
+interface ServerProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `encode` | `uuid: string`, `message: ServiceMessage` | `Promise<{ chunks: Bytes[]; totalSize: number }>` | Encode a message into binary chunks |
+| `decode` | `bytes: Bytes` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | Decode received binary data |
+| `dispose` | -- | `void` | Dispose the wrapper and terminate worker threads |
+
+## createServerProtocolWrapper
+
+Create a `ServerProtocolWrapper` instance.
+
+```ts
+function createServerProtocolWrapper(): ServerProtocolWrapper;
+```
+
+Returns a new protocol wrapper with automatic worker thread delegation for heavy payloads.

package/docs/services.md

@@ -1,58 +1,63 @@
-# Built-in Services
+# Services
+
+Built-in service definitions that can be included in `ServiceServerOptions.services`.
+
+## OrmService
+
+Built-in ORM service definition. Provides database connection management, transaction control, and query execution over the RPC layer. Supports MySQL, MSSQL, and PostgreSQL.
+
+```ts
+const OrmService: ServiceDefinition<{
+  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>;
+}>;
+```
 
-Pre-defined service definitions ready to use with `ServiceServer`.
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getInfo` | `opt` | `Promise<{ dialect; database?; schema? }>` | Get database dialect and schema info |
+| `connect` | `opt` | `Promise<number>` | Open a connection; returns connection ID |
+| `close` | `connId` | `Promise<void>` | Close a connection |
+| `beginTransaction` | `connId`, `isolationLevel?` | `Promise<void>` | Begin a transaction |
+| `commitTransaction` | `connId` | `Promise<void>` | Commit the current transaction |
+| `rollbackTransaction` | `connId` | `Promise<void>` | Rollback the current transaction |
+| `executeParametrized` | `connId`, `query`, `params?` | `Promise<unknown[][]>` | Execute a parameterized SQL query |
+| `executeDefs` | `connId`, `defs`, `options?` | `Promise<unknown[][]>` | Execute query definitions |
+| `bulkInsert` | `connId`, `tableName`, `columnDefs`, `records` | `Promise<void>` | Bulk insert records into a table |
 
-## `OrmService`
+### OrmServiceType
 
-Server-side ORM service implementation. Requires authentication. Manages database connections per WebSocket socket (using `WeakMap`). Supports MySQL, MSSQL, and PostgreSQL via `@simplysm/orm-node`.
+Utility type for extracting ORM service method signatures.
 
-```typescript
-const OrmService: ServiceDefinition;
+```ts
+type OrmServiceType = ServiceMethods<typeof OrmService>;
 ```
 
-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`
+## AutoUpdateService
 
-Server-side auto-update service implementation. Scans the client's platform-specific `updates/` directory for version files.
+Built-in auto-update service definition. Retrieves the latest version information for client applications by platform.
 
-```typescript
-const AutoUpdateService: ServiceDefinition;
+```ts
+const AutoUpdateService: ServiceDefinition<{
+  getLastVersion(platform: string): Promise<{ version: string; downloadPath: string } | undefined>;
+}>;
 ```
 
-Implements the `AutoUpdateService` interface from `@simplysm/service-common`:
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getLastVersion` | `platform: string` | `Promise<{ version; downloadPath } \| undefined>` | Get latest version info for a platform |
 
-| Method | Description |
-|--------|-------------|
-| `getLastVersion(platform)` | Find latest version file for platform (win32, android, etc.) |
+### AutoUpdateServiceType
 
-Supported platforms and file extensions:
-- `android`: `.apk` files
-- Other platforms: `.exe` files
+Utility type for extracting auto-update service method signatures.
 
-## `SmtpClientService`
-
-Server-side SMTP email sending service. Uses `nodemailer` under the hood.
-
-```typescript
-const SmtpClientService: ServiceDefinition;
+```ts
+type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
 ```
-
-| Method | Description |
-|--------|-------------|
-| `send(options)` | Send email with full SMTP options |
-| `sendByDefault(options)` | Send email using server's default SMTP config |