jsgui3-server 0.0.150 → 0.0.152

package/docs/configuration-reference.md

@@ -61,6 +61,37 @@ Configuration values are resolved in this order (later sources override earlier
   Server.serve({ port: 3000 });
   ```
 
+#### `on_port_conflict`
+- **Type:** `'error' | 'auto-loopback'`
+- **Description:** Startup behavior when the requested port is already in use.
+- **Default:** `'error'`
+
+```javascript
+// If the configured port is busy on all selected interfaces,
+// retry on 127.0.0.1 using a free ephemeral port.
+Server.serve({
+    port: 52000,
+    on_port_conflict: 'auto-loopback'
+});
+```
+
+#### `start`
+- **Type:** `object`
+- **Description:** Advanced startup options passed to `server.start(...)`.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `on_port_conflict` | `'error' \| 'auto-loopback'` | Same as top-level `on_port_conflict` |
+
+```javascript
+Server.serve({
+    port: 52000,
+    start: {
+        on_port_conflict: 'auto-loopback'
+    }
+});
+```
+
 #### `host`
 - **Type:** `string`
 - **Description:** Host interface to bind to
@@ -129,7 +160,7 @@ Configuration values are resolved in this order (later sources override earlier
   });
   ```
 
-### API Configuration
+### API Configuration
 
 #### `api`
 - **Type:** `object`
@@ -154,81 +185,81 @@ Configuration values are resolved in this order (later sources override earlier
           'echo': (data) => data
       }
   });
-  ```
-
-### Resource and Event Options
-
-#### `resources`
-- **Type:** `object | array`
-- **Description:** Resource definitions to register in the server resource pool and start after server startup.
-- **Lifecycle:** Resources are started automatically after the HTTP server is listening and stopped automatically during `server.close()`.
-- **Supported forms:**
-  - In-process resource instance
-  - In-process resource constructor/class config
-  - Process resource config (`type: 'process'` or inferred from `command`)
-  - Remote process resource config (`type: 'remote'` or inferred from `host`/`endpoints`)
-- **Example:**
-  ```javascript
-  Server.serve({
-      resources: {
-          // In-process resource instance
-          cache: new In_Process_Cache_Resource({ name: 'cache' }),
-
-          // Process_Resource in direct mode (default)
-          worker_direct: {
-              type: 'process',
-              command: process.execPath,
-              args: ['worker.js'],
-              autoRestart: true
-          },
-
-          // Process_Resource in PM2 mode (pm2Path optional)
-          worker_pm2: {
-              type: 'process',
-              processManager: { type: 'pm2' },
-              command: process.execPath,
-              args: ['worker.js']
-          },
-
-          // Remote_Process_Resource
-          remote_worker: {
-              type: 'remote',
-              host: '127.0.0.1',
-              port: 3400,
-              pollIntervalMs: 30000
-          }
-      }
-  });
-  ```
-
-**Process resource notes:**
-- `processManager` defaults to `direct`.
-- PM2 works without explicitly setting `pm2Path`:
-  - `processManager.pm2Path` (if provided)
-  - `PM2_PATH` env var (if provided)
-  - local `node_modules/.bin/pm2` (if present)
-  - `pm2` from `PATH`
-
-#### `events`
-- **Type:** `boolean | object`
-- **Description:** Enables a built-in SSE endpoint for resource lifecycle events.
-- **Default:** `false`
-- **When `true`:**
-  - Registers `HTTP_SSE_Publisher` at `/events`
-  - Forwards resource pool lifecycle events (`resource_state_change`, `crashed`, `unhealthy`, `unreachable`, `recovered`)
-- **When object:** Supports publisher options such as `route`, `name`, `keepaliveIntervalMs`, `maxClients`.
-- **Example:**
-  ```javascript
-  Server.serve({
-      events: {
-          route: '/events',
-          keepaliveIntervalMs: 15000,
-          maxClients: 200
-      }
-  });
-  ```
-
-### Static File Serving
+  ```
+
+### Resource and Event Options
+
+#### `resources`
+- **Type:** `object | array`
+- **Description:** Resource definitions to register in the server resource pool and start after server startup.
+- **Lifecycle:** Resources are started automatically after the HTTP server is listening and stopped automatically during `server.close()`.
+- **Supported forms:**
+  - In-process resource instance
+  - In-process resource constructor/class config
+  - Process resource config (`type: 'process'` or inferred from `command`)
+  - Remote process resource config (`type: 'remote'` or inferred from `host`/`endpoints`)
+- **Example:**
+  ```javascript
+  Server.serve({
+      resources: {
+          // In-process resource instance
+          cache: new In_Process_Cache_Resource({ name: 'cache' }),
+
+          // Process_Resource in direct mode (default)
+          worker_direct: {
+              type: 'process',
+              command: process.execPath,
+              args: ['worker.js'],
+              autoRestart: true
+          },
+
+          // Process_Resource in PM2 mode (pm2Path optional)
+          worker_pm2: {
+              type: 'process',
+              processManager: { type: 'pm2' },
+              command: process.execPath,
+              args: ['worker.js']
+          },
+
+          // Remote_Process_Resource
+          remote_worker: {
+              type: 'remote',
+              host: '127.0.0.1',
+              port: 3400,
+              pollIntervalMs: 30000
+          }
+      }
+  });
+  ```
+
+**Process resource notes:**
+- `processManager` defaults to `direct`.
+- PM2 works without explicitly setting `pm2Path`:
+  - `processManager.pm2Path` (if provided)
+  - `PM2_PATH` env var (if provided)
+  - local `node_modules/.bin/pm2` (if present)
+  - `pm2` from `PATH`
+
+#### `events`
+- **Type:** `boolean | object`
+- **Description:** Enables a built-in SSE endpoint for resource lifecycle events.
+- **Default:** `false`
+- **When `true`:**
+  - Registers `HTTP_SSE_Publisher` at `/events`
+  - Forwards resource pool lifecycle events (`resource_state_change`, `crashed`, `unhealthy`, `unreachable`, `recovered`)
+- **When object:** Supports publisher options such as `route`, `name`, `keepaliveIntervalMs`, `maxClients`.
+- **Example:**
+  ```javascript
+  Server.serve({
+      events: {
+          route: '/events',
+          keepaliveIntervalMs: 15000,
+          maxClients: 200
+      }
+  });
+  ```
+
+### Static File Serving
 
 #### `static`
 - **Type:** `object`
@@ -270,51 +301,51 @@ Configuration values are resolved in this order (later sources override earlier
   });
   ```
 
-#### `config`
-- **Type:** `string`
-- **Description:** Path to configuration file
-- **Default:** `'jsgui.config.js'` (if exists)
-- **Example:**
-  ```javascript
-  Server.serve({
-      config: './my-config.js'
-  });
-  ```
-
-#### `style`
-- **Type:** `object`
-- **Description:** Style pipeline options for CSS/SCSS/Sass extraction and compilation.
-- **Default:** `{}` (inherits debug behavior for sourcemaps)
-- **Example:**
-  ```javascript
-  Server.serve({
-      ctrl: MyControl,
-      debug: true,
-      style: {
-          sourcemaps: {
-              enabled: true,
-              inline: true,
-              include_sources: true
-          },
-          load_paths: ['styles', 'controls'],
-          output_style: 'expanded',
-          quiet_dependencies: true,
-          compile_css_with_sass: true
-      }
-  });
-  ```
-
-**Style options:**
-- `sourcemaps.enabled` (`boolean`): Enable CSS sourcemaps. Defaults to `true` when `debug` is enabled.
-- `sourcemaps.inline` (`boolean`): Inline sourcemaps into compiled CSS (default `true`).
-- `sourcemaps.include_sources` (`boolean`): Embed sources content in the sourcemap (default `true`).
-- `load_paths` (`string[]`): Sass load paths for `@use`/`@import`.
-- `output_style` (`string`): Sass output style (e.g., `expanded`, `compressed`).
-- `quiet_dependencies` (`boolean`): Suppress dependency warnings during Sass compilation.
-- `compile_css_with_sass` (`boolean`): Compile `.css` blocks through Sass when mixing with SCSS (default `true`).
-- `scss_sources` / `sass_sources` (`string[]`): Extra Sass/SCSS sources appended during compilation.
-
-Inline CSS sourcemaps are emitted only when a single compilation pass is possible. Mixed `.sass` plus `.scss`/`.css` inputs skip inline maps to avoid inaccurate mappings.
+#### `config`
+- **Type:** `string`
+- **Description:** Path to configuration file
+- **Default:** `'jsgui.config.js'` (if exists)
+- **Example:**
+  ```javascript
+  Server.serve({
+      config: './my-config.js'
+  });
+  ```
+
+#### `style`
+- **Type:** `object`
+- **Description:** Style pipeline options for CSS/SCSS/Sass extraction and compilation.
+- **Default:** `{}` (inherits debug behavior for sourcemaps)
+- **Example:**
+  ```javascript
+  Server.serve({
+      ctrl: MyControl,
+      debug: true,
+      style: {
+          sourcemaps: {
+              enabled: true,
+              inline: true,
+              include_sources: true
+          },
+          load_paths: ['styles', 'controls'],
+          output_style: 'expanded',
+          quiet_dependencies: true,
+          compile_css_with_sass: true
+      }
+  });
+  ```
+
+**Style options:**
+- `sourcemaps.enabled` (`boolean`): Enable CSS sourcemaps. Defaults to `true` when `debug` is enabled.
+- `sourcemaps.inline` (`boolean`): Inline sourcemaps into compiled CSS (default `true`).
+- `sourcemaps.include_sources` (`boolean`): Embed sources content in the sourcemap (default `true`).
+- `load_paths` (`string[]`): Sass load paths for `@use`/`@import`.
+- `output_style` (`string`): Sass output style (e.g., `expanded`, `compressed`).
+- `quiet_dependencies` (`boolean`): Suppress dependency warnings during Sass compilation.
+- `compile_css_with_sass` (`boolean`): Compile `.css` blocks through Sass when mixing with SCSS (default `true`).
+- `scss_sources` / `sass_sources` (`string[]`): Extra Sass/SCSS sources appended during compilation.
+
+Inline CSS sourcemaps are emitted only when a single compilation pass is possible. Mixed `.sass` plus `.scss`/`.css` inputs skip inline maps to avoid inaccurate mappings.
 
 ## Environment Variables
 
@@ -421,81 +452,81 @@ Server.serve({
 });
 ```
 
-### Resource Pools
-
-```javascript
-let server;
-server = await Server.serve({
-    resources: {
-        cache: new In_Process_Cache_Resource({
-            name: 'cache'
-        }),
-        worker_direct: {
-            type: 'process',
-            command: process.execPath,
-            args: ['worker.js']
-        },
-        remote_worker: {
-            type: 'remote',
-            host: '127.0.0.1',
-            port: 3400
-        }
-    },
-    events: true,
-    api: {
-        'resources/summary': () => server.resource_pool.summary,
-        'resources/restart': async ({ name }) => {
-            const resource = server.resource_pool.get_resource(name);
-            if (!resource || typeof resource.restart !== 'function') {
-                return { ok: false, error: 'Resource restart not supported' };
-            }
-            await resource.restart();
-            return { ok: true, status: resource.status };
-        }
-    }
-});
-```
-
-For strongly typed in-process resources you can also provide constructor-based entries:
-
-```javascript
-Server.serve({
-    resources: {
-        in_process_metrics: {
-            type: 'resource',
-            class: In_Process_Metrics_Resource,
-            spec: {
-                sampleIntervalMs: 1000
-            }
-        },
-        in_process_events: {
-            constructor_fn: In_Process_Event_Bus_Resource,
-            spec: {
-                maxHistory: 500
-            }
-        },
-        in_process_cache: {
-            resource: new In_Process_Cache_Resource({
-                name: 'in_process_cache'
-            })
-        },
-        in_process_singleton: new In_Process_Registry_Resource({
-            name: 'in_process_singleton'
-        })
-    }
-});
-```
-
-### Middleware
+### Resource Pools
 
 ```javascript
-const express = require('express');
-const compression = require('compression');
+let server;
+server = await Server.serve({
+    resources: {
+        cache: new In_Process_Cache_Resource({
+            name: 'cache'
+        }),
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true,
+    api: {
+        'resources/summary': () => server.resource_pool.summary,
+        'resources/restart': async ({ name }) => {
+            const resource = server.resource_pool.get_resource(name);
+            if (!resource || typeof resource.restart !== 'function') {
+                return { ok: false, error: 'Resource restart not supported' };
+            }
+            await resource.restart();
+            return { ok: true, status: resource.status };
+        }
+    }
+});
+```
+
+For strongly typed in-process resources you can also provide constructor-based entries:
+
+```javascript
+Server.serve({
+    resources: {
+        in_process_metrics: {
+            type: 'resource',
+            class: In_Process_Metrics_Resource,
+            spec: {
+                sampleIntervalMs: 1000
+            }
+        },
+        in_process_events: {
+            constructor_fn: In_Process_Event_Bus_Resource,
+            spec: {
+                maxHistory: 500
+            }
+        },
+        in_process_cache: {
+            resource: new In_Process_Cache_Resource({
+                name: 'in_process_cache'
+            })
+        },
+        in_process_singleton: new In_Process_Registry_Resource({
+            name: 'in_process_singleton'
+        })
+    }
+});
+```
+
+### `middleware`
+- **Type:** `Function | Function[]`
+- **Description:** One or more Express-style middleware functions `(req, res, next)` to run before every request reaches the router. Middleware is executed in array order.
+
+```javascript
+const { compression } = require('jsgui3-server/middleware');
 
 Server.serve({
     middleware: [
-        compression(),
-        express.json({ limit: '10mb' }),
+        compression({ threshold: 512 }),
         (req, res, next) => {
             console.log(`${req.method} ${req.url}`);
             next();
@@ -504,6 +535,52 @@ Server.serve({
 });
 ```
 
+### `compression`
+- **Type:** `boolean | Object`
+- **Description:** Convenience shorthand that enables the built-in response-compression middleware. Pass `true` for defaults or an options object.
+- **Default:** Disabled (no compression)
+
+| Sub-option | Type | Default | Description |
+|------------|--------|---------------------------|--------------------------------------------|
+| `threshold` | number | `1024` | Minimum body size (bytes) to compress |
+| `level` | number | `Z_DEFAULT_COMPRESSION` | zlib compression level (1–9, or -1 for default) |
+
+```javascript
+// Enable with defaults (1024 byte threshold, gzip preferred)
+Server.serve({ compression: true });
+
+// Enable with custom options
+Server.serve({ compression: { threshold: 256, level: 6 } });
+```
+
+> **Note:** `compression` and `middleware` can be used together. The `middleware` array runs first (in order), then the compression middleware is appended.
+
+See [Middleware Guide](middleware-guide.md) for the full API, response-wrapping patterns, and custom middleware examples.
+
+### Runtime Introspection Helpers
+
+After startup, these server instance methods are useful for runtime endpoint
+inspection and diagnostics:
+
+- `server.get_listening_endpoints()`
+- `server.get_primary_endpoint()`
+- `server.print_endpoints(options)`
+- `server.get_startup_diagnostics()`
+
+```javascript
+const server = await Server.serve({
+    Ctrl: MyControl,
+    port: 52000,
+    on_port_conflict: 'auto-loopback'
+});
+
+console.log('Primary endpoint:', server.get_primary_endpoint());
+server.print_endpoints({ include_index: true });
+console.log('Startup diagnostics:', server.get_startup_diagnostics());
+```
+
+See [API Reference](api-reference.md) for full method signatures.
+
 ## Configuration Validation
 
 ### Type Checking
@@ -523,18 +600,18 @@ Server.serve({ port: 'not-a-number' });
 - **Required:** None (auto-discovery provides defaults)
 - **Optional:** All options have sensible defaults
 
-### Validation Rules
-
-- `port`: Must be number between 1-65535 or 0 (ephemeral)
-- `host`: Must be valid IPv4 address or hostname
-- `debug`: Converted to boolean using truthy() function
-- `pages`: Each page must have `content` property
-- `api`: Values must be functions
-- `static`: Values must be strings (directory paths)
-- `resources`: Must be an object map or array of supported resource entries
-- `resources.<name>.type`: Supported values include `process`, `remote`, `resource`, `in_process`, `in-process`
-- `resources.<name>.processManager.type`: Supported values include `direct`, `pm2`
-- `events`: Must be boolean or object
+### Validation Rules
+
+- `port`: Must be number between 1-65535 or 0 (ephemeral)
+- `host`: Must be valid IPv4 address or hostname
+- `debug`: Converted to boolean using truthy() function
+- `pages`: Each page must have `content` property
+- `api`: Values must be functions
+- `static`: Values must be strings (directory paths)
+- `resources`: Must be an object map or array of supported resource entries
+- `resources.<name>.type`: Supported values include `process`, `remote`, `resource`, `in_process`, `in-process`
+- `resources.<name>.processManager.type`: Supported values include `direct`, `pm2`
+- `events`: Must be boolean or object
 
 ## Configuration Patterns
 
@@ -965,4 +1042,4 @@ Solution: port: 3000 instead of port: "3000"
 
 ---
 
-This configuration reference provides comprehensive coverage of all JSGUI3 Server configuration options. Remember that most options have sensible defaults, so you only need to specify what differs from the defaults for your use case.
+This configuration reference provides comprehensive coverage of all JSGUI3 Server configuration options. Remember that most options have sensible defaults, so you only need to specify what differs from the defaults for your use case.