jsgui3-server 0.0.150 → 0.0.152

package/docs/api-reference.md

@@ -32,30 +32,30 @@ Server.serve(options?: ServerOptions): Promise<Server>
 - `DiscoveryError`: Cannot find client files or controls
 - `BindingError`: Cannot bind to specified host/port
 
-**Example:**
-```javascript
-const server = await Server.serve({
-    port: 3000,
-    ctrl: MyControl,
-    resources: {
-        worker_direct: {
-            type: 'process',
-            command: process.execPath,
-            args: ['worker.js']
-        },
-        remote_worker: {
-            type: 'remote',
-            host: '127.0.0.1',
-            port: 3400
-        }
-    },
-    events: true
-});
-```
-
-**Serve-specific options:**
-- `resources`: Registers managed resources (in-process resource objects, local process resources, remote HTTP process resources).
-- `events`: Enables built-in SSE publisher for resource lifecycle events (`/events` by default).
+**Example:**
+```javascript
+const server = await Server.serve({
+    port: 3000,
+    ctrl: MyControl,
+    resources: {
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true
+});
+```
+
+**Serve-specific options:**
+- `resources`: Registers managed resources (in-process resource objects, local process resources, remote HTTP process resources).
+- `events`: Enables built-in SSE publisher for resource lifecycle events (`/events` by default).
 
 ### Server Constructor
 
@@ -71,42 +71,56 @@ new Server(options?: ServerOptions)
 
 **Returns:** Server instance
 
-**Events:**
-- `'ready'`: Emitted when bundling is complete
-- `'started'`: Emitted when HTTP server is listening
-- `'error'`: Emitted on server errors
-
-### Module Exports
-
-```javascript
-const jsgui = require('jsgui3-server');
-
-// Top-level exports
-jsgui.Process_Resource;
-jsgui.Remote_Process_Resource;
-jsgui.HTTP_SSE_Publisher;
-
-// Resource namespace aliases
-jsgui.Resource.Process;
-jsgui.Resource.Remote_Process;
-```
-
-## Server Instance Methods
-
-### server.start(port, callback)
+**Events:**
+- `'ready'`: Emitted when bundling is complete
+- `'started'`: Emitted when HTTP server is listening
+- `'error'`: Emitted on server errors
+
+### Module Exports
+
+```javascript
+const jsgui = require('jsgui3-server');
+
+// Top-level exports
+jsgui.Process_Resource;
+jsgui.Remote_Process_Resource;
+jsgui.HTTP_SSE_Publisher;
+
+// Resource namespace aliases
+jsgui.Resource.Process;
+jsgui.Resource.Remote_Process;
+```
+
+## Server Instance Methods
+
+### server.start(port, callback, options)
 
 Starts the HTTP server (legacy API).
 
 **Signature:**
 ```javascript
-server.start(port?: number, callback?: (err?: Error) => void): void
+server.start(
+  port?: number,
+  callback?: (err?: Error) => void,
+  options?: {
+    on_port_conflict?: 'error' | 'auto-loopback'
+  }
+): void
 ```
 
 **Parameters:**
 - `port` (number, optional): Port to listen on (default: 8080)
 - `callback` (function, optional): Called when server starts or fails
+- `options` (object, optional): Startup behavior options
+  - `on_port_conflict: 'error' | 'auto-loopback'`
+    - `error` (default): Return startup error as usual.
+    - `auto-loopback`: If all requested interface binds fail with `EADDRINUSE`,
+      retry once on `127.0.0.1` using a free port.
 
-### server.publish(route, handler)
+When startup fails, the returned error may include `error.startup_diagnostics`
+containing attempted addresses and per-address errors.
+
+### server.publish(route, handler)
 
 Adds an API endpoint (legacy API).
 
@@ -115,53 +129,227 @@ Adds an API endpoint (legacy API).
 server.publish(route: string, handler: Function): void
 ```
 
-**Parameters:**
-- `route` (string): Route path (automatically prefixed with `/api/`)
-- `handler` (Function): Request handler function
-
-### server.publish_observable(route, observable, options)
-
-Adds an observable-backed SSE endpoint.
-
-**Signature:**
-```javascript
-server.publish_observable(route: string, observable: Observable, options?: object): HTTP_Observable_Publisher
-```
-
-**Parameters:**
-- `route` (string): Route path. If it does not start with `/`, it is prefixed with `/api/`.
-- `observable` (Observable): Source observable stream.
-- `options` (object, optional): Publisher options.
-
-**Returns:** `HTTP_Observable_Publisher` instance.
-
-**Alias:** `server.publishObservable(route, observable, options)`
-
-### server.close(callback)
-
-Stops managed resources and closes all bound HTTP servers.
-
-**Signature:**
-```javascript
-server.close(callback?: (err?: Error | null) => void): void
-```
-
-**Behavior:**
-- Calls `resource_pool.stop()` when available
-- Stops `sse_publisher` when present
-- Closes all HTTP listeners
-
-### server.use(middleware)
-
-Adds middleware to the server.
+**Parameters:**
+- `route` (string): Route path (automatically prefixed with `/api/`)
+- `handler` (Function): Request handler function
+
+### server.publish_observable(route, observable, options)
+
+Adds an observable-backed SSE endpoint.
+
+**Signature:**
+```javascript
+server.publish_observable(route: string, observable: Observable, options?: object): HTTP_Observable_Publisher
+```
+
+**Parameters:**
+- `route` (string): Route path. If it does not start with `/`, it is prefixed with `/api/`.
+- `observable` (Observable): Source observable stream.
+- `options` (object, optional): Publisher options.
+
+**Returns:** `HTTP_Observable_Publisher` instance.
+
+**Alias:** `server.publishObservable(route, observable, options)`
+
+### server.close(callback)
+
+Stops managed resources and closes all bound HTTP servers.
+
+**Signature:**
+```javascript
+server.close(callback?: (err?: Error | null) => void): void
+```
+
+**Behavior:**
+- Calls `resource_pool.stop()` when available
+- Stops `sse_publisher` when present
+- Closes all HTTP listeners
+
+### server.get_listening_endpoints()
+
+Returns the active listener endpoints (protocol, host, port, url) for the
+current process. Useful when startup falls back from a requested fixed port to
+an auto-selected loopback port.
+
+**Signature:**
+```javascript
+server.get_listening_endpoints(): Array<{
+  protocol: 'http' | 'https';
+  host: string;
+  port: number;
+  url: string;
+}>
+```
+
+**Example:**
+```javascript
+server.start(52000, (err) => {
+  if (err) throw err;
+  console.log('Listening at', server.get_primary_endpoint());
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
+### server.get_primary_endpoint()
+
+Returns the primary endpoint URL string (first endpoint) or `null` if the
+server is not listening.
+
+**Signature:**
+```javascript
+server.get_primary_endpoint(): string | null
+```
+
+**Example:**
+```javascript
+const url = server.get_primary_endpoint();
+if (url) {
+  console.log('Primary endpoint:', url);
+}
+```
+
+### server.print_endpoints(options)
+
+Prints listening endpoint URLs and returns the printed lines.
+
+**Signature:**
+```javascript
+server.print_endpoints(options?: {
+  logger?: (line: string) => void;
+  include_index?: boolean;
+  prefix?: string;
+}): string[]
+```
+
+**Parameters:**
+- `options.logger` (function, optional): Line logger (default: `console.log`)
+- `options.include_index` (boolean, optional): Include endpoint index in output
+- `options.prefix` (string, optional): Prefix text (default: `"listening endpoint"`)
+
+**Example:**
+```javascript
+server.start(52000, (err) => {
+  if (err) throw err;
+  server.print_endpoints({ include_index: true });
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
+### server.get_startup_diagnostics()
+
+Returns startup diagnostics information or `null` when unavailable.
+
+**Signature:**
+```javascript
+server.get_startup_diagnostics(): {
+  requested_port: number;
+  fallback_port?: number;
+  fallback_host?: string;
+  addresses_attempted: string[];
+  errors_by_address: Record<string, { code?: string; message?: string }>;
+} | null
+```
+
+**Example:**
+```javascript
+server.start(52000, (err) => {
+  if (err) {
+    console.error(server.get_startup_diagnostics());
+    throw err;
+  }
+  console.log(server.get_startup_diagnostics());
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
+### server.use(fn)
+
+Register middleware to run before every request is routed. Middleware is executed
+in registration order. The chain runs to completion before the router processes
+the request.
 
 **Signature:**
 ```javascript
-server.use(middleware: Function): void
+server.use(fn: Function): Server   // returns `this` for chaining
 ```
 
 **Parameters:**
-- `middleware` (Function): Express-style middleware function
+- `fn` (Function): Middleware function with signature `(req, res, next) => void`
+  - `req` — Node.js `http.IncomingMessage`
+  - `res` — Node.js `http.ServerResponse`
+  - `next` — Call `next()` to continue to the next middleware / router.
+    Call `next(err)` to skip remaining middleware and trigger the error handler
+    (500 response).
+
+**Returns:** The server instance (for chaining).
+
+**Throws:** `Error` if `fn` is not a function.
+
+**Example:**
+```javascript
+const { compression } = require('jsgui3-server/middleware');
+
+server
+    .use((req, res, next) => {
+        console.log(`${req.method} ${req.url}`);
+        next();
+    })
+    .use(compression());
+```
+
+**Execution order:**
+```
+HTTP Request → middleware[0] → middleware[1] → … → router
+```
+
+If no middleware is registered, the router is called directly with zero overhead.
+
+**See also:** [Middleware Guide](middleware-guide.md) for response-wrapping
+patterns, custom middleware examples, and the built-in compression reference.
+
+---
+
+### Built-in Middleware
+
+#### `compression([options])`
+
+Response-compression middleware. Transparently compresses response bodies
+(gzip / deflate / brotli) when the client supports it and the content type
+is compressible.
+
+```javascript
+const { compression } = require('jsgui3-server/middleware');
+server.use(compression());                    // defaults
+server.use(compression({ threshold: 512 }));  // lower threshold
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|-----------|--------|---------------------------|-------------------------------------------|
+| `threshold` | number | `1024` | Minimum body size in bytes to compress |
+| `level` | number | `Z_DEFAULT_COMPRESSION` | zlib compression level (1–9, or -1) |
+
+**Encoding priority:** gzip → deflate → brotli
+
+**Compressible types:** `application/json`, `text/html`, `text/plain`,
+`text/css`, `text/xml`, `text/csv`, `text/javascript`,
+`application/javascript`, `application/xml`, `application/xhtml+xml`,
+`application/manifest+json`, `image/svg+xml`.
+
+**Not compressed:** bodies below threshold, binary content types, responses
+with an existing `Content-Encoding`, and streaming responses (`res.write()`
+before `res.end()` — e.g. SSE).
+
+**Access paths:**
+```javascript
+require('jsgui3-server/middleware').compression   // direct
+require('jsgui3-server').middleware.compression    // via module
+Server.middleware.compression                      // via class
+```
 
 ## Port Utilities
 
@@ -507,7 +695,7 @@ Serves CSS files.
 serve(request: IncomingMessage, response: ServerResponse): Promise<void>
 ```
 
-### HTTP_API_Publisher
+### HTTP_API_Publisher
 
 Handles API endpoints.
 
@@ -525,162 +713,162 @@ new HTTP_API_Publisher(spec?: PublisherSpec)
 Handles API requests.
 
 **Signature:**
-```javascript
-serve(request: IncomingMessage, response: ServerResponse): Promise<void>
-```
-
-### HTTP_SSE_Publisher
-
-General-purpose SSE publisher for explicit event fan-out.
-
-**Extends:** `HTTP_Publisher`
-
-**Constructor:**
-```javascript
-new HTTP_SSE_Publisher(spec?: {
-    name?: string,
-    keepaliveIntervalMs?: number,
-    maxClients?: number,
-    eventHistorySize?: number
-})
-```
-
-**Methods:**
-- `handle_http(req, res)`
-- `broadcast(event_name, data_value)`
-- `send(client_id, event_name, data_value)`
-- `stop(callback?)`
-
-**Properties:**
-- `client_count` (number)
-
-## Resource Classes
-
-### Process_Resource
-
-Represents a local process as a resource with a unified lifecycle API.
-
-**Extends:** `Resource`
-
-**Constructor:**
-```javascript
-new Process_Resource(spec?: {
-    name?: string,
-    command?: string,
-    args?: string[],
-    cwd?: string,
-    env?: object,
-    autoRestart?: boolean,
-    maxRestarts?: number,
-    processManager?: 'direct' | {
-        type: 'direct' | 'pm2',
-        pm2Path?: string,
-        ecosystem?: string
-    },
-    healthCheck?: {
-        type: 'http' | 'tcp' | 'custom',
-        url?: string,
-        host?: string,
-        port?: number,
-        fn?: Function,
-        intervalMs?: number,
-        timeoutMs?: number,
-        failuresBeforeUnhealthy?: number
-    }
-})
-```
-
-**Core Methods:**
-- `start(callback?)`
-- `stop(callback?)`
-- `restart(callback?)`
-- `get_abstract()`
-
-**Status:**
-```javascript
-{
-    state: 'stopped' | 'starting' | 'running' | 'stopping' | 'restarting' | 'crashed',
-    pid: number | null,
-    uptime: number,
-    restartCount: number,
-    lastHealthCheck: object | null,
-    memoryUsage: object | null,
-    processManager: { type: 'direct' | 'pm2' }
-}
-```
-
-**Events:**
-- `state_change`
-- `stdout`
-- `stderr`
-- `exit`
-- `health_check`
-- `unhealthy`
-- `crashed`
-
-### Remote_Process_Resource
-
-Represents a remote HTTP-controlled process using the same lifecycle-oriented API style as `Process_Resource`.
-
-**Extends:** `Resource`
-
-**Constructor:**
-```javascript
-new Remote_Process_Resource(spec?: {
-    name?: string,
-    host: string,
-    port: number,
-    protocol?: 'http' | 'https',
-    pollIntervalMs?: number,
-    httpTimeoutMs?: number,
-    historySize?: number,
-    unreachableFailuresBeforeEvent?: number,
-    endpoints?: {
-        status?: string,
-        start?: string,
-        stop?: string,
-        health?: string
-    }
-})
-```
-
-**Core Methods:**
-- `start(callback?)`
-- `stop(callback?)`
-- `restart(callback?)`
-- `get_abstract()`
-
-**Status:** Includes `state`, `pid`, `uptime`, `restartCount`, `lastHealthCheck`, `memoryUsage`, and `processManager: { type: 'remote' }`.
-
-**Events:**
-- `state_change`
-- `unreachable`
-- `recovered`
-
-### Server_Resource_Pool
-
-Server-specific resource pool with lifecycle orchestration and event forwarding.
-
-**Extends:** `Resource_Pool`
-
-**Methods:**
-- `add(resource)`
-- `remove(name, callback?)`
-- `start(callback?)`
-- `stop(callback?)`
-- `get_resources_by_type(type)`
-
-**Properties:**
-- `summary`: Aggregated state summary grouped by resource type.
-
-**Forwarded Events:**
-- `resource_state_change`
-- `crashed`
-- `unhealthy`
-- `unreachable`
-- `recovered`
-
-### File_System_Resource
+```javascript
+serve(request: IncomingMessage, response: ServerResponse): Promise<void>
+```
+
+### HTTP_SSE_Publisher
+
+General-purpose SSE publisher for explicit event fan-out.
+
+**Extends:** `HTTP_Publisher`
+
+**Constructor:**
+```javascript
+new HTTP_SSE_Publisher(spec?: {
+    name?: string,
+    keepaliveIntervalMs?: number,
+    maxClients?: number,
+    eventHistorySize?: number
+})
+```
+
+**Methods:**
+- `handle_http(req, res)`
+- `broadcast(event_name, data_value)`
+- `send(client_id, event_name, data_value)`
+- `stop(callback?)`
+
+**Properties:**
+- `client_count` (number)
+
+## Resource Classes
+
+### Process_Resource
+
+Represents a local process as a resource with a unified lifecycle API.
+
+**Extends:** `Resource`
+
+**Constructor:**
+```javascript
+new Process_Resource(spec?: {
+    name?: string,
+    command?: string,
+    args?: string[],
+    cwd?: string,
+    env?: object,
+    autoRestart?: boolean,
+    maxRestarts?: number,
+    processManager?: 'direct' | {
+        type: 'direct' | 'pm2',
+        pm2Path?: string,
+        ecosystem?: string
+    },
+    healthCheck?: {
+        type: 'http' | 'tcp' | 'custom',
+        url?: string,
+        host?: string,
+        port?: number,
+        fn?: Function,
+        intervalMs?: number,
+        timeoutMs?: number,
+        failuresBeforeUnhealthy?: number
+    }
+})
+```
+
+**Core Methods:**
+- `start(callback?)`
+- `stop(callback?)`
+- `restart(callback?)`
+- `get_abstract()`
+
+**Status:**
+```javascript
+{
+    state: 'stopped' | 'starting' | 'running' | 'stopping' | 'restarting' | 'crashed',
+    pid: number | null,
+    uptime: number,
+    restartCount: number,
+    lastHealthCheck: object | null,
+    memoryUsage: object | null,
+    processManager: { type: 'direct' | 'pm2' }
+}
+```
+
+**Events:**
+- `state_change`
+- `stdout`
+- `stderr`
+- `exit`
+- `health_check`
+- `unhealthy`
+- `crashed`
+
+### Remote_Process_Resource
+
+Represents a remote HTTP-controlled process using the same lifecycle-oriented API style as `Process_Resource`.
+
+**Extends:** `Resource`
+
+**Constructor:**
+```javascript
+new Remote_Process_Resource(spec?: {
+    name?: string,
+    host: string,
+    port: number,
+    protocol?: 'http' | 'https',
+    pollIntervalMs?: number,
+    httpTimeoutMs?: number,
+    historySize?: number,
+    unreachableFailuresBeforeEvent?: number,
+    endpoints?: {
+        status?: string,
+        start?: string,
+        stop?: string,
+        health?: string
+    }
+})
+```
+
+**Core Methods:**
+- `start(callback?)`
+- `stop(callback?)`
+- `restart(callback?)`
+- `get_abstract()`
+
+**Status:** Includes `state`, `pid`, `uptime`, `restartCount`, `lastHealthCheck`, `memoryUsage`, and `processManager: { type: 'remote' }`.
+
+**Events:**
+- `state_change`
+- `unreachable`
+- `recovered`
+
+### Server_Resource_Pool
+
+Server-specific resource pool with lifecycle orchestration and event forwarding.
+
+**Extends:** `Resource_Pool`
+
+**Methods:**
+- `add(resource)`
+- `remove(name, callback?)`
+- `start(callback?)`
+- `stop(callback?)`
+- `get_resources_by_type(type)`
+
+**Properties:**
+- `summary`: Aggregated state summary grouped by resource type.
+
+**Forwarded Events:**
+- `resource_state_change`
+- `crashed`
+- `unhealthy`
+- `unreachable`
+- `recovered`
+
+### File_System_Resource
 
 Provides access to local file system.
 
@@ -912,12 +1100,16 @@ ensure_route_leading_slash(route: string): string
 ### ServerOptions
 
 ```typescript
-interface ServerOptions {
-  ctrl?: Function;
-  Ctrl?: Function;
-  src_path_client_js?: string;
+interface ServerOptions {
+  ctrl?: Function;
+  Ctrl?: Function;
+  src_path_client_js?: string;
   port?: number;
   host?: string;
+  on_port_conflict?: 'error' | 'auto-loopback';
+  start?: {
+    on_port_conflict?: 'error' | 'auto-loopback';
+  };
   debug?: boolean;
   name?: string;
   root?: string;
@@ -928,60 +1120,66 @@ interface ServerOptions {
   api?: Record<string, Function>;
   static?: Record<string, string>;
 
-  // Advanced options
-  cors?: CorsConfig;
-  https?: HttpsConfig;
-  middleware?: Function[];
-  publishers?: Record<string, Publisher>;
-  resources?: ResourceEntries;
-  events?: boolean | EventsOptions;
-  bundler?: BundlerConfig;
-}
-```
-
-```typescript
-type ResourceEntries = Record<string, ResourceEntry> | ResourceEntry[];
-
-type ResourceEntry =
-  | Resource
-  | {
-      type?: 'process' | 'local';
-      command?: string;
-      args?: string[];
-      processManager?: 'direct' | {
-        type?: 'direct' | 'pm2';
-        pm2Path?: string;
-        ecosystem?: string;
-      };
-      [key: string]: any;
-    }
-  | {
-      type?: 'remote' | 'http';
-      host?: string;
-      port?: number;
-      protocol?: 'http' | 'https';
-      endpoints?: Record<string, string>;
-      [key: string]: any;
-    }
-  | {
-      type?: 'resource' | 'in_process' | 'in-process';
-      instance?: Resource;
-      resource?: Resource;
-      class?: new (spec?: any) => Resource;
-      Ctor?: new (spec?: any) => Resource;
-      constructor_fn?: new (spec?: any) => Resource;
-      spec?: Record<string, any>;
-      [key: string]: any;
-    };
-
-interface EventsOptions {
-  route?: string;
-  name?: string;
-  keepaliveIntervalMs?: number;
-  maxClients?: number;
-  eventHistorySize?: number;
-}
-```
+  // Middleware & compression
+  middleware?: Function | Function[];   // (req, res, next) middleware functions
+  compression?: boolean | {             // Enable built-in compression middleware
+      threshold?: number;               //   Min body size to compress (default 1024)
+      level?: number;                   //   zlib level (default Z_DEFAULT_COMPRESSION)
+  };
+
+  // Advanced options
+  cors?: CorsConfig;
+  https?: HttpsConfig;
+  publishers?: Record<string, Publisher>;
+  resources?: ResourceEntries;
+  events?: boolean | EventsOptions;
+  bundler?: BundlerConfig;
+}
+```
+
+```typescript
+type ResourceEntries = Record<string, ResourceEntry> | ResourceEntry[];
+
+type ResourceEntry =
+  | Resource
+  | {
+      type?: 'process' | 'local';
+      command?: string;
+      args?: string[];
+      processManager?: 'direct' | {
+        type?: 'direct' | 'pm2';
+        pm2Path?: string;
+        ecosystem?: string;
+      };
+      [key: string]: any;
+    }
+  | {
+      type?: 'remote' | 'http';
+      host?: string;
+      port?: number;
+      protocol?: 'http' | 'https';
+      endpoints?: Record<string, string>;
+      [key: string]: any;
+    }
+  | {
+      type?: 'resource' | 'in_process' | 'in-process';
+      instance?: Resource;
+      resource?: Resource;
+      class?: new (spec?: any) => Resource;
+      Ctor?: new (spec?: any) => Resource;
+      constructor_fn?: new (spec?: any) => Resource;
+      spec?: Record<string, any>;
+      [key: string]: any;
+    };
+
+interface EventsOptions {
+  route?: string;
+  name?: string;
+  keepaliveIntervalMs?: number;
+  maxClients?: number;
+  eventHistorySize?: number;
+}
+```
 
 ### PageConfig
 
@@ -1287,4 +1485,4 @@ const server = await Server.serve({
 
 ---
 
-This API reference provides comprehensive technical documentation for JSGUI3 Server internals. For practical usage examples and tutorials, refer to the user-facing documentation.
+This API reference provides comprehensive technical documentation for JSGUI3 Server internals. For practical usage examples and tutorials, refer to the user-facing documentation.