@simplysm/service-server 14.0.4 → 14.0.5

package/docs/main.md

@@ -1,81 +0,0 @@
-# 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

@@ -1,31 +0,0 @@
-# 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,63 +0,0 @@
-# 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>;
-}>;
-```
-
-| 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 |
-
-### OrmServiceType
-
-Utility type for extracting ORM service method signatures.
-
-```ts
-type OrmServiceType = ServiceMethods<typeof OrmService>;
-```
-
-## AutoUpdateService
-
-Built-in auto-update service definition. Retrieves the latest version information for client applications by platform.
-
-```ts
-const AutoUpdateService: ServiceDefinition<{
-  getLastVersion(platform: string): Promise<{ version: string; downloadPath: string } | undefined>;
-}>;
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getLastVersion` | `platform: string` | `Promise<{ version; downloadPath } \| undefined>` | Get latest version info for a platform |
-
-### AutoUpdateServiceType
-
-Utility type for extracting auto-update service method signatures.
-
-```ts
-type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
-```

package/docs/transport.md

@@ -1,169 +0,0 @@
-# Transport
-
-WebSocket and HTTP transport handlers for routing client messages to services.
-
-## WebSocket Transport
-
-### WebSocketHandler
-
-Manages multiple WebSocket connections, routes messages to services, and handles event broadcasting.
-
-```ts
-interface WebSocketHandler {
-  addSocket(socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest): void;
-  closeAll(): void;
-  emit<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `addSocket` | `socket: WebSocket`, `clientId: string`, `clientName: string`, `connReq: FastifyRequest` | `void` | Register a new WebSocket connection |
-| `closeAll` | -- | `void` | Close all managed connections |
-| `emit` | `eventDef`, `infoSelector`, `data` | `Promise<void>` | Broadcast an event to matching listeners across all sockets |
-
-### createWebSocketHandler
-
-Create a `WebSocketHandler` instance.
-
-```ts
-function createWebSocketHandler(
-  runMethod: (def: {
-    serviceName: string;
-    methodName: string;
-    params: unknown[];
-    socket?: ServiceSocket;
-  }) => Promise<unknown>,
-  jwtSecret: string | undefined,
-): WebSocketHandler;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runMethod` | `(def) => Promise<unknown>` | Callback to execute a service method |
-| `jwtSecret` | `string \| undefined` | JWT secret for authenticating socket connections. `undefined` disables auth. |
-
-### ServiceSocket
-
-Represents a single WebSocket connection with protocol encoding/decoding, ping/pong keep-alive, and event listener tracking.
-
-```ts
-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;
-}
-```
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `connectedAtDateTime` | property | `DateTime` | Connection timestamp |
-| `clientName` | property | `string` | Client identifier |
-| `connReq` | property | `FastifyRequest` | Original Fastify request |
-| `authTokenPayload` | property | `AuthTokenPayload?` | Authenticated token payload (set after auth message) |
-| `close` | method | `() => void` | Close the socket |
-| `send` | method | `(uuid, msg) => Promise<number>` | Send a server message; returns number of bytes sent |
-| `addListener` | method | `(key, eventName, info) => void` | Register an event listener on this socket |
-| `removeListener` | method | `(key) => void` | Remove an event listener by key |
-| `getEventListeners` | method | `(eventName) => Array<{ key; info }>` | Get all listeners for an event name |
-| `filterEventTargetKeys` | method | `(targetKeys) => string[]` | Filter target keys to only those on this socket |
-| `on("error")` | method | `(handler) => void` | Subscribe to error events |
-| `on("close")` | method | `(handler) => void` | Subscribe to close events (with close code) |
-| `on("message")` | method | `(handler) => void` | Subscribe to decoded message events |
-
-### createServiceSocket
-
-Create a `ServiceSocket` instance wrapping a raw WebSocket.
-
-```ts
-function createServiceSocket(
-  socket: WebSocket,
-  clientId: string,
-  clientName: string,
-  connReq: FastifyRequest,
-): ServiceSocket;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `WebSocket` | Raw WebSocket instance |
-| `clientId` | `string` | Unique connection identifier |
-| `clientName` | `string` | Client name |
-| `connReq` | `FastifyRequest` | Fastify request that initiated the upgrade |
-
-## HTTP Transport
-
-### handleHttpRequest
-
-Handle an HTTP RPC request. Parses the request body, verifies authentication, executes the service method, and sends the response.
-
-```ts
-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>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify request |
-| `reply` | `FastifyReply` | Fastify reply |
-| `jwtSecret` | `string \| undefined` | JWT secret. `undefined` disables auth verification. |
-| `runMethod` | `(def) => Promise<unknown>` | Callback to execute the service method |
-
-### handleUpload
-
-Handle a file upload request. Saves uploaded files to the server's root path and returns upload results.
-
-```ts
-async function handleUpload(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  jwtSecret: string | undefined,
-): Promise<void>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify request (multipart) |
-| `reply` | `FastifyReply` | Fastify reply |
-| `rootPath` | `string` | Server root path for file storage |
-| `jwtSecret` | `string \| undefined` | JWT secret for auth verification |
-
-### handleStaticFile
-
-Serve a static file from the server's root path.
-
-```ts
-async function handleStaticFile(
-  req: FastifyRequest,
-  reply: FastifyReply,
-  rootPath: string,
-  urlPath: string,
-): Promise<void>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `req` | `FastifyRequest` | Fastify request |
-| `reply` | `FastifyReply` | Fastify reply |
-| `rootPath` | `string` | Server root directory |
-| `urlPath` | `string` | URL path portion to resolve |

package/docs/types.md

@@ -1,31 +0,0 @@
-# Types
-
-## ServiceServerOptions
-
-Server configuration options passed to `createServiceServer`.
-
-```ts
-interface ServiceServerOptions {
-  rootPath: string;
-  port: number;
-  ssl?: {
-    pfxBytes: Uint8Array;
-    passphrase: string;
-  };
-  auth?: {
-    jwtSecret: string;
-  } | false;
-  services: ServiceDefinition[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `rootPath` | `string` | Root directory path for static files and uploads |
-| `port` | `number` | Server listening port |
-| `ssl` | `{ pfxBytes: Uint8Array; passphrase: string }?` | SSL/TLS configuration using a PFX certificate |
-| `ssl.pfxBytes` | `Uint8Array` | PFX certificate bytes |
-| `ssl.passphrase` | `string` | PFX passphrase |
-| `auth` | `{ jwtSecret: string } \| false` | JWT authentication configuration. Set to `false` to disable authentication. |
-| `auth.jwtSecret` | `string` | Secret key for JWT signing and verification |
-| `services` | `ServiceDefinition[]` | Array of service definitions to register |

package/docs/utilities.md

@@ -1,27 +0,0 @@
-# Utilities
-
-## getConfig
-
-Read a configuration section from a JSON file.
-
-```ts
-async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | `string` | Path to the configuration JSON file |
-
-Returns the parsed configuration object typed as `TConfig`, or `undefined` if the file does not exist.
-
-```ts
-import { getConfig } from "@simplysm/service-server";
-
-interface DbConfig {
-  host: string;
-  port: number;
-  database: string;
-}
-
-const dbConfig = await getConfig<DbConfig>("config/db.json");
-```