jsgui3-server 0.0.147 → 0.0.149

package/docs/api-reference.md

@@ -32,13 +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
-});
-```
+**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
 
@@ -54,12 +71,27 @@ 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
-
-## Server Instance Methods
+**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)
 
@@ -74,7 +106,7 @@ server.start(port?: number, callback?: (err?: Error) => void): void
 - `port` (number, optional): Port to listen on (default: 8080)
 - `callback` (function, optional): Called when server starts or fails
 
-### server.publish(route, handler)
+### server.publish(route, handler)
 
 Adds an API endpoint (legacy API).
 
@@ -83,13 +115,45 @@ 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.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.use(middleware)
+
+Adds middleware to the server.
 
 **Signature:**
 ```javascript
@@ -443,7 +507,7 @@ Serves CSS files.
 serve(request: IncomingMessage, response: ServerResponse): Promise<void>
 ```
 
-### HTTP_API_Publisher
+### HTTP_API_Publisher
 
 Handles API endpoints.
 
@@ -461,13 +525,162 @@ new HTTP_API_Publisher(spec?: PublisherSpec)
 Handles API requests.
 
 **Signature:**
-```javascript
-serve(request: IncomingMessage, response: ServerResponse): Promise<void>
-```
-
-## Resource Classes
-
-### 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.
 
@@ -699,10 +912,10 @@ 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;
   debug?: boolean;
@@ -715,15 +928,60 @@ interface ServerOptions {
   api?: Record<string, Function>;
   static?: Record<string, string>;
 
-  // Advanced options
-  cors?: CorsConfig;
-  https?: HttpsConfig;
-  middleware?: Function[];
-  publishers?: Record<string, Publisher>;
-  resources?: Record<string, Resource>;
-  bundler?: BundlerConfig;
-}
-```
+  // 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;
+}
+```
 
 ### PageConfig
 
@@ -1029,4 +1287,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.

package/docs/books/admin-ui/01-introduction.md

@@ -0,0 +1,32 @@
+# Chapter 1: Introduction
+
+## Vision
+
+The Admin UI is the **go-to interface** for developers and operators to administer `jsgui3-server` instances. It should be:
+
+- **Instantaneous**: Zero setup required; just navigate to `/admin`
+- **Insightful**: Surface the internal state of the server in real-time
+- **Actionable**: Allow common admin tasks directly from the UI
+
+## Goals
+
+1. **Visibility into Observables**: If a server publishes an observable (e.g., for crawl progress, metrics), the Admin UI should display it automatically with an appropriate control.
+2. **Resource Browser**: List all registered resources (routes, publishers, static paths) with introspection.
+3. **Configuration Panel**: View and modify server configuration (where safe).
+4. **Performance Metrics**: Display throughput, active connections, memory usage.
+
+## Inspiration
+
+The design is inspired by:
+- Database admin tools (pgAdmin, phpMyAdmin)
+- Monitoring dashboards (Grafana, Kibana)
+- The jsgui3 Window control aesthetic
+
+## Target Experience
+
+A developer starts a jsgui3-server, then navigates to `http://localhost:PORT/admin`. They immediately see:
+- A sidebar listing all resources
+- A main panel showing the selected resource's details
+- Real-time updates for any observables
+
+No extra code required—the Admin UI is built into jsgui3-server and activates automatically.

package/docs/books/admin-ui/02-architecture.md

@@ -0,0 +1,92 @@
+# Chapter 2: Architecture
+
+## High-Level Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     jsgui3-server                            │
+│                                                              │
+│  ┌──────────────────┐   ┌────────────────┐                  │
+│  │ Admin UI Module  │◄──│ Server Router  │                  │
+│  │ (admin-ui/)      │   └───────┬────────┘                  │
+│  └────────┬─────────┘           │                           │
+│           │             ┌───────┴────────┐                  │
+│           ▼             │ Resource Pool  │                  │
+│  ┌─────────────────┐    │ (resources/)   │                  │
+│  │ Admin_Page      │    └───────┬────────┘                  │
+│  │ (client.js)     │            │                           │
+│  └────────┬────────┘    ┌───────┴────────┐                  │
+│           │             │ Publishers     │                  │
+│           ▼             │ (observables)  │                  │
+│  ┌─────────────────┐    └────────────────┘                  │
+│  │ Controls:       │                                        │
+│  │ - Resource_List │                                        │
+│  │ - Observable_   │                                        │
+│  │   Monitor       │                                        │
+│  │ - Config_Panel  │                                        │
+│  └─────────────────┘                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Module Structure
+
+```
+admin-ui/
+├── client.js         # Main client control (Admin_Page)
+├── server.js         # API routes for admin data
+├── controls/         # UI components
+│   ├── Resource_List.js
+│   ├── Observable_Monitor.js
+│   ├── Config_Panel.js
+│   └── Metrics_Dashboard.js
+└── styles/           # CSS modules
+    └── admin.css
+```
+
+## Key Patterns (from Window examples)
+
+1. **`client.js`** exports a jsgui module with controls registered on `jsgui.controls`
+2. **`server.js`** creates a `Server` instance, passes `Ctrl` and `src_path_client_js`
+3. Controls extend `Active_HTML_Document` for full-page apps
+4. CSS is defined as a static `.css` property on the control class
+5. `activate()` sets up client-side interactivity
+
+## Data Flow
+
+1. **Server Start** → Admin module registers `/admin` route
+2. **Client Request** → SSR renders Admin_Page with initial state
+3. **Activation** → Client connects to `/api/admin/resources` (SSE)
+4. **Updates** → Resource changes stream to client in real-time
+
+## Integration with `publish_observable`
+
+The Admin UI leverages the schema-aware observable system:
+- Server exposes `/api/admin/observables` listing all published observables
+- Each observable has a schema describing its data type
+- `Auto_Observable_UI` renders appropriate controls automatically
+
+## Server Lifecycle Events
+
+The server emits two distinct lifecycle events:
+
+| Event | Fired When | Use Case |
+|-------|------------|----------|
+| `ready` | Publishers/bundlers complete | Safe to call `server.start()`, publish routes |
+| `listening` | HTTP server bound to ports | Server accepting connections |
+
+**Example usage:**
+```javascript
+server.on('ready', () => {
+    // Publish observables and set up routes
+    server.publish_observable('/api/data', myObservable);
+    
+    // Now start accepting connections
+    server.start(port, (err) => {
+        console.log('Server running');
+    });
+});
+
+server.on('listening', () => {
+    console.log('Server accepting connections');
+});
+```