jsgui3-server 0.0.148 → 0.0.150

package/docs/configuration-reference.md

@@ -129,7 +129,7 @@ Configuration values are resolved in this order (later sources override earlier
   });
   ```
 
-### API Configuration
+### API Configuration
 
 #### `api`
 - **Type:** `object`
@@ -154,9 +154,81 @@ Configuration values are resolved in this order (later sources override earlier
           'echo': (data) => data
       }
   });
-  ```
-
-### 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`
@@ -349,21 +421,70 @@ Server.serve({
 });
 ```
 
-### Resource Pools
-
-```javascript
-Server.serve({
-    resources: {
-        database: new DatabaseResource({
-            connectionString: process.env.DATABASE_URL
-        }),
-        cache: new RedisResource({
-            host: 'localhost',
-            port: 6379
-        })
-    }
-});
-```
+### 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
 
@@ -402,14 +523,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)
+### 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
 

package/docs/core/README.md

@@ -0,0 +1,19 @@
+# Core Documentation
+
+This directory contains dense, implementation-first documentation for the active reliability surface of `jsgui3-server`.
+
+Current focus:
+
+- server startup and readiness semantics
+- unified resource model (in-process, direct process, remote process)
+- resource pool lifecycle and event forwarding
+- SSE event transport for resource telemetry
+- end-to-end browser testing methodology for control + resource integration
+
+Primary text:
+
+- `docs/core/jsgui3-server-core-book/00-table-of-contents.md`
+
+Related deep-dive:
+
+- `docs/books/jsgui3-bundling-research-book/README.md`

package/docs/core/jsgui3-server-core-book/00-table-of-contents.md

@@ -0,0 +1,21 @@
+# jsgui3-server Core Book
+
+## Purpose
+
+This book specifies the currently critical execution path: `Server.serve(...)` startup, resource lifecycle control, resource event publication, and browser-level verification of those behaviors.
+
+## Chapter Map
+
+1. `01-startup-readiness-state-machine.md`
+2. `02-resource-abstraction-and-lifecycle.md`
+3. `03-resource-pool-and-event-topology.md`
+4. `04-sse-publisher-semantics.md`
+5. `05-serve-factory-resource-wiring.md`
+6. `06-e2e-testing-methodology.md`
+7. `07-defect-detection-and-hardening-loop.md`
+
+## Reader Contract
+
+- This text is dense by design.
+- It assumes familiarity with Node.js HTTP servers, async control flow, and event-driven architecture.
+- It prioritizes invariants, failure modes, and testability over introductory narrative.

package/docs/core/jsgui3-server-core-book/01-startup-readiness-state-machine.md

@@ -0,0 +1,41 @@
+# 1. Startup Readiness State Machine
+
+## Core Problem
+
+A server that binds a socket before its route graph is installed can return transient `404` responses during cold start. This is a correctness defect, not a cosmetic delay.
+
+## Current Model
+
+`Server.serve(...)` now enforces a strict ordering:
+
+1. construct `Server` instance
+2. install API publishers and optional SSE publisher
+3. wait for server `ready` event (emitted after webpage/website publisher route installation)
+4. resolve additional page route preparations
+5. bind sockets with `server.start(...)`
+6. start configured resources
+7. resolve `serve(...)` promise
+
+## Removed Failure Pattern
+
+Previous behavior had a fallback timer that could start listening before `ready`. This allowed requests to arrive before `/` and bundle routes were present.
+
+That path is removed. Startup now rejects on readiness timeout instead of entering a half-ready listening state.
+
+## Startup Timeout
+
+`readyTimeoutMs` (default `120000`) bounds waiting for readiness. Timeout behavior:
+
+- if readiness is not reached in time, `serve(...)` rejects
+- no forced early listen occurs
+
+This makes startup failure explicit and testable.
+
+## Verification
+
+`tests/serve.test.js` includes a delayed fake webpage publisher and asserts that:
+
+- `serve(...)` does not resolve until delayed readiness arrives
+- post-resolution `/` is immediately routable
+
+This test prevents regression to pre-ready listening.

package/docs/core/jsgui3-server-core-book/02-resource-abstraction-and-lifecycle.md

@@ -0,0 +1,92 @@
+# 2. Resource Abstraction and Lifecycle
+
+## Uniform Contract
+
+`Process_Resource` and `Remote_Process_Resource` expose the same operational surface:
+
+- `start()`
+- `stop()`
+- `restart()`
+- `status` getter
+- `get_abstract()`
+
+The contract allows client/API code to remain management-backend agnostic.
+
+## Process_Resource Modes
+
+`Process_Resource` supports two process managers:
+
+- `direct` (default): local child process (`spawn`)
+- `pm2`: external manager integration (`pm2 start/stop/restart/jlist`)
+
+PM2 path resolution is optional and automatic:
+
+1. `processManager.pm2Path`
+2. `PM2_PATH` env
+3. local `node_modules/.bin/pm2(.cmd)`
+4. `pm2` from `PATH`
+
+Therefore explicit `pm2Path` is not required for default operation.
+
+## State Machine
+
+Nominal states:
+
+- `stopped`
+- `starting`
+- `running`
+- `stopping`
+- `restarting`
+- `crashed`
+
+`Remote_Process_Resource` additionally uses `unreachable` for transport failure.
+
+Each transition emits `state_change` with `{ from, to, timestamp }`.
+
+## Operational Signals
+
+`Process_Resource` emits:
+
+- `stdout` / `stderr` (line-wise)
+- `exit`
+- `health_check`
+- `unhealthy`
+- `crashed`
+
+`Remote_Process_Resource` emits:
+
+- `state_change`
+- `unreachable`
+- `recovered`
+
+## Failure Handling
+
+### Local process
+
+Unexpected non-zero exit with `autoRestart: true` enters exponential backoff restart.
+
+Backoff progression:
+
+- base `restartBackoffBaseMs` (default 1000)
+- doubles per attempt
+- capped at 60000ms
+
+Exceeding `maxRestarts` transitions to `crashed` and halts auto-restart.
+
+### Remote process
+
+Transport failures do not map to `crashed`; they map to `unreachable`. Recovery is explicit via `recovered` event when polling succeeds again.
+
+## Observability Payload
+
+`status` normalizes operational metrics:
+
+- state
+- pid (if meaningful)
+- uptime
+- restartCount
+- lastHealthCheck
+- memoryUsage
+- processManager metadata
+
+The normalized shape is essential for stable API and UI projections.

package/docs/core/jsgui3-server-core-book/03-resource-pool-and-event-topology.md

@@ -0,0 +1,47 @@
+# 3. Resource Pool and Event Topology
+
+## Role
+
+`Server_Resource_Pool` is the system-wide resource coordinator. It extends `Resource_Pool` and adds lifecycle orchestration plus event fan-in.
+
+## Lifecycle Surface
+
+Implemented operations:
+
+- `add(resource)` / `push(resource)`
+- `remove(name)` with stop-on-remove semantics
+- `start(callback)` start-all
+- `stop(callback)` stop-all
+- `get_resources_by_type(type)`
+- `summary` getter
+
+## Event Fan-In
+
+Pool-level forwarded events:
+
+- `resource_state_change`
+- `crashed`
+- `unhealthy`
+- `unreachable`
+- `recovered`
+
+Forwarding payload includes `resourceName` plus original event fields.
+
+This gives a single subscription point for system telemetry.
+
+## Summary as Fleet Snapshot
+
+`summary` aggregates:
+
+- totals by state (`running`, `stopped`, `crashed`, `unreachable`, ...)
+- `byType` entries with `get_abstract()` output per resource
+
+`summary` is designed for status APIs and dashboard views.
+
+## Correctness Invariants
+
+1. removing a resource must detach forwarded listeners
+2. stop-all must tolerate mixed callback/promise resource implementations
+3. no event should lose resource identity when forwarded
+
+`tests/server-resource-pool.test.js` and `tests/serve-resources.test.js` exercise these invariants.

package/docs/core/jsgui3-server-core-book/04-sse-publisher-semantics.md

@@ -0,0 +1,41 @@
+# 4. SSE Publisher Semantics
+
+## Component
+
+`HTTP_SSE_Publisher` is a general-purpose server-sent events publisher, separate from observable-specific transport.
+
+## Responsibilities
+
+- maintain connection registry (`client_id -> response stream`)
+- format protocol-correct SSE frames (`id`, `event`, `data`)
+- provide `broadcast(event, data)`
+- provide `send(client_id, event, data)`
+- issue keepalive comments (`:keepalive`) to prevent idle timeout
+- maintain bounded event history for replay
+- support `Last-Event-ID` replay on reconnect
+
+## Delivery Semantics
+
+- event IDs are monotonic and server-local
+- replay sends events with `id > last_event_id`
+- delivery is best-effort per connected client
+- failed writes trigger client disconnect cleanup
+
+## Operational Constraints
+
+- max client guard (`maxClients`)
+- explicit `stop()` for deterministic shutdown
+- keepalive timer lifecycle tied to active client count
+
+## Integration Contract
+
+When `Server.serve({ events: true })` is used, pool events are bridged into SSE broadcasts. Resource state transitions become browser-consumable without client polling loops.
+
+## Verification
+
+`tests/http-sse-publisher.test.js` validates:
+
+- multi-client broadcast
+- targeted delivery
+- keepalive emission
+- replay via `Last-Event-ID`

package/docs/core/jsgui3-server-core-book/05-serve-factory-resource-wiring.md

@@ -0,0 +1,46 @@
+# 5. Serve Factory Resource Wiring
+
+## Objective
+
+`Server.serve(...)` must be a single-entry composition API that can instantiate and wire:
+
+- pages / controls
+- API handlers
+- resources (process or remote)
+- SSE endpoint for resource events
+
+without requiring the caller to manually compose internals.
+
+## Resource Configuration Forms
+
+Accepted `resources` forms include:
+
+- direct resource instance
+- constructor function / class
+- `{ class | Ctor | constructor_fn, ...spec }`
+- `{ type: 'process' | 'remote', ...spec }`
+
+Type inference fallbacks:
+
+- `command` or `processManager` -> `Process_Resource`
+- `host` or `endpoints` -> `Remote_Process_Resource`
+
+## Event Bridge
+
+With `events: true`:
+
+- `HTTP_SSE_Publisher` mounted on `/events` (or configured route)
+- pool events broadcast onto SSE stream
+
+This creates a default telemetry channel with zero extra server code.
+
+## Startup Ordering
+
+1. configure APIs, events, and resource specs
+2. wait for ready
+3. start listening
+4. start configured resources
+
+## Shutdown Ordering
+
+`server.close()` triggers resource pool stop and SSE stop before closing HTTP servers. This prevents orphan resources and dangling SSE clients.

package/docs/core/jsgui3-server-core-book/06-e2e-testing-methodology.md

@@ -0,0 +1,48 @@
+# 6. E2E Testing Methodology
+
+## Principle
+
+A browser E2E test is valid only if it asserts both:
+
+- user-visible state (DOM/control behavior)
+- server truth (resource/process state, event emission)
+
+UI-only assertions are necessary but insufficient for fullstack correctness.
+
+## Harness
+
+`tests/helpers/puppeteer-e2e-harness.js` provides:
+
+- deterministic step runner (`run_interaction_story`)
+- browser probe capture (`console`, `pageerror`, request failures)
+- shared page/server boot helpers
+- stable interaction primitives (input event dispatch, drag)
+
+This converts long imperative test scripts into explicit state-transition stories.
+
+## Story Pattern
+
+Each step has:
+
+- `name`
+- `run(page)`
+- optional `assert(page)`
+
+Failure is annotated with `[story :: step]` to localize defects quickly.
+
+## Current High-Value Scenarios
+
+1. control interaction precision (`Date_Picker` + `Datetime_Picker`)
+2. client-driven resource lifecycle control (`start/stop/restart`)
+3. SSE propagation to browser and UI projection
+4. parity check between browser-observed state and server-side resource state
+
+Implemented in:
+
+- `tests/window-resource-integration.puppeteer.test.js`
+
+## Stability Guards
+
+- route readiness gate before browser navigation in resource integration tests
+- allowlist-based probe assertions for expected disconnect noise (`/events` abort on close)
+- strict no-unexpected-console-error policy

package/docs/core/jsgui3-server-core-book/07-defect-detection-and-hardening-loop.md

@@ -0,0 +1,47 @@
+# 7. Defect Detection and Hardening Loop
+
+## Goal
+
+Maximize bug discovery rate while minimizing false confidence.
+
+## Loop
+
+1. define invariant
+2. encode invariant as automated test
+3. reproduce failure deterministically
+4. implement smallest correctness-preserving fix
+5. re-run focused suite
+6. run regression suites touching adjacent surfaces
+7. document invariant and fix rationale
+
+## Practical Invariants for Current Surface
+
+### Startup / Routing
+
+- `serve()` must not resolve before root route availability
+- startup timeout must fail explicitly, not partially start
+
+### Resource Management
+
+- `stop()` semantics are idempotent for already-stopped resources
+- crash vs unreachable classification must remain distinct
+- process manager backend must not leak into consumer API shape
+
+### Eventing
+
+- every forwarded resource event must include `resourceName`
+- SSE replay must preserve event ordering by event ID
+
+### Browser Integration
+
+- client action routes must be observable in captured API call log
+- SSE state transitions must drive UI state within bounded time
+
+## Recommended Additional Test Work
+
+1. Add a chaos-style resource test with rapid start/stop/restart bursts and assert no deadlock.
+2. Add remote resource failure flapping test (unreachable/recovered oscillation) with threshold validation.
+3. Add SSE reconnection E2E test in browser with explicit `Last-Event-ID` continuity assertion.
+4. Add matrix tests across process manager modes (`direct`, `pm2` if available) under the same API contract assertions.
+
+These increase confidence in concurrency and degraded-network behavior, where latent bugs usually appear.