jsgui3-server 0.0.142 → 0.0.143

package/docs/publishers-guide.md

@@ -104,16 +104,18 @@ const publisher = new HTTP_Function_Publisher({
 
 **Purpose:** Streams observable data to clients using Server-Sent Events (SSE).
 
-**Key Features:**
-- Real-time streaming of observable events
-- SSE protocol support (`text/event-stream`)
-- Chunked transfer encoding for long-running connections
-- Integration with `fnl` observables
-
-**Usage:**
-```javascript
-const { observable } = require('fnl');
-const Observable_Publisher = require('jsgui3-server/publishers/http-observable-publisher');
+**Key Features:**
+- Real-time streaming of observable events
+- SSE protocol support (`text/event-stream`)
+- Chunked transfer encoding for long-running connections
+- Integration with `fnl` observables
+- Connection cleanup on client disconnect
+- Optional `pause()`, `resume()`, `stop()` controls
+
+**Usage:**
+```javascript
+const { observable } = require('fnl');
+const Observable_Publisher = require('jsgui3-server/publishers/http-observable-publisher');
 
 // Create a hot observable that emits continuously
 let tick_count = 0;
@@ -136,13 +138,28 @@ const publisher = new Observable_Publisher({
     obs: tick_stream
 });
 
-// Register with server router
-server.server_router.set_route('/api/stream', publisher, publisher.handle_http);
-```
-
-**Client-Side Consumption:**
-```javascript
-// In browser, use EventSource API
+// Register with server router
+server.server_router.set_route('/api/stream', publisher, publisher.handle_http);
+
+// Optional: control the stream from server-side code
+publisher.pause();
+publisher.resume();
+publisher.stop();
+```
+
+**Optional Control (HTTP):**
+```javascript
+// From browser or any HTTP client:
+await fetch('/api/stream', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'pause' })   // 'resume' | 'stop' | 'status'
+});
+```
+
+**Client-Side Consumption:**
+```javascript
+// In browser, use EventSource API
 const eventSource = new EventSource('/api/stream');
 
 eventSource.onmessage = (event) => {
@@ -159,20 +176,19 @@ eventSource.onerror = () => {
 };
 ```
 
-**SSE Protocol:**
-The publisher sends events in SSE format:
-```
-HTTP/1.1 200 OK
-Content-Type: text/event-stream
-Transfer-Encoding: chunked
-
-OK
-event: message
-data:{"tick":1,"timestamp":1234567890,"message":"Server tick #1"}
-
-event: message
-data:{"tick":2,"timestamp":1234567891,"message":"Server tick #2"}
-```
+**SSE Protocol:**
+The publisher sends events in SSE format:
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Transfer-Encoding: chunked
+
+data: OK
+
+data: {"tick":1,"timestamp":1234567890,"message":"Server tick #1"}
+
+data: {"tick":2,"timestamp":1234567891,"message":"Server tick #2"}
+```
 
 **See Also:** [Observable SSE Demo](../examples/controls/15)%20window,%20observable%20SSE/) for a complete working example.
 
@@ -386,4 +402,4 @@ Publishers provide comprehensive logging:
 
 ---
 
-This guide provides the foundation for understanding and extending the publisher system. For specific publisher implementations, refer to their individual source files in the `publishers/` directory.
+This guide provides the foundation for understanding and extending the publisher system. For specific publisher implementations, refer to their individual source files in the `publishers/` directory.

package/examples/controls/15) window, observable SSE/README.md

@@ -52,23 +52,35 @@ node server.js
 
 2. **Reactive UI Updates**: The `Observable_Demo_UI` control updates progress bars, status text, and log entries in real-time as events arrive.
 
-## The SSE Protocol
-
-Server-Sent Events use HTTP chunked transfer encoding:
-
-```
-HTTP/1.1 200 OK
-Content-Type: text/event-stream
-Transfer-Encoding: chunked
-
-event: message
-data: {"progress": 10, "stage": "Loading..."}
-
-event: message
-data: {"progress": 20, "stage": "Processing..."}
-
-...
-```
+## The SSE Protocol
+
+Server-Sent Events use HTTP chunked transfer encoding:
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Transfer-Encoding: chunked
+
+data: OK
+
+data: {"progress": 10, "stage": "Loading..."}
+
+data: {"progress": 20, "stage": "Processing..."}
+
+...
+```
+
+## Optional Pause/Resume/Stop Control
+
+`HTTP_Observable_Publisher` also supports controlling the published observable:
+
+```javascript
+await fetch('/api/tick-stream', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ action: 'pause' })   // 'resume' | 'stop' | 'status'
+});
+```
 
 ## Observable Pattern Benefits
 

package/package.json

@@ -14,7 +14,7 @@
     "jsgui3-html": "^0.0.175",
     "jsgui3-webpage": "^0.0.8",
     "jsgui3-website": "^0.0.8",
-    "lang-tools": "^0.0.43",
+    "lang-tools": "^0.0.44",
     "mocha": "^11.7.5",
     "multiparty": "^4.2.3",
     "ncp": "^2.0.0",
@@ -39,7 +39,7 @@
     "type": "git",
     "url": "https://github.com/metabench/jsgui3-server.git"
   },
-  "version": "0.0.142",
+  "version": "0.0.143",
   "scripts": {
     "cli": "node cli.js",
     "serve": "node cli.js serve",

package/publishers/http-observable-publisher.js

@@ -1,125 +1,318 @@
-const jsgui = require('jsgui3-html');
-
-const {
-    Evented_Class
-} = jsgui;
-
-const {
-    observable
-} = require('fnl');
-
-const HTTP_Publisher = require('./http-publisher');
-
-// Evented_Class_Publisher?
-//  Evented_Publisher
-
-// Want to do this over websockets too.
-//  Should be a single ws point.
-//   Could give out conntection keys alongside the HTTP request.
-//    All the security needed - give out a 256 bit key in the HTML doc, require it to open the websocket connection.
-//     Seems simple, would work with a single process auth provider, then could have centralised auth and token issuance and checking.
-
-
-class Observable_Publisher extends HTTP_Publisher {
-    constructor(spec) {
-        super(spec);
-        let obs, schema;
-        // needs to hook into the server though...
-        if (spec.next && spec.complete && spec.error) {
-            obs = spec;
-        } else {
-
-            if (spec.obs) {
-                obs = spec.obs;
-            } else {
-                throw 'No observable found.';
-            }
-
-            //let {schema} = spec;
-            
-            schema = spec.schema;
-
-            //console.trace();
-            //throw 'NYI';
-        }
-        // need to be able to process (http) requests.
-        // reobserve that observable to prevent too many events being attached.
-
-        // reobserve
-        //  code here could be written as resobserve function.
-        //   or just obs on an existing obs?
-
-        let obs2 = observable((next, complete, error) => {
-            obs.on('next', data => {
-                next(data);
-            })
-            return [];
-        })
-        this.type = 'observable';
-
-        // Also should publish when it's over.
-
-        /*
-
-        => Request
-        GET /stream HTTP/1.1 
-        Host: example.com
-        Accept: text/event-stream
-
-        <= Response
-        HTTP/1.1 200 OK 
-        Connection: keep-alive
-        Content-Type: text/event-stream
-        Transfer-Encoding: chunked
-
-        retry: 15000 
-
-        data: First message is a simple string. 
-
-        data: {"message": "JSON payload"} 
-
-        event: foo 
-        data: Message of type "foo"
-
-        id: 42 
-        event: bar
-        data: Multi-line message of
-        data: type "bar" and id "42"
-
-        id: 43 
-        data: Last message, id "43"
-        
-1
-2
-3
-4
-event: message\n
-data: this is an important message\n
-data: that has two lines\n
-\n
-
-        */
-
-        
-        this.handle_http = (req, res) => {
-            // need to handle observable http request.
-            // Begin sending to that connection...
-            // Following SSE would be nice.
-            res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Transfer-Encoding': 'chunked',
-                //'Trailer': 'Content-MD5'
-            });
-            res.write('OK\n');
-            let obs2_handler = data => {
-                //console.log('data', data);
-                let s_data = JSON.stringify(data);
-                //res.write(s_data + '\n');
-                res.write('event: message\ndata:' + s_data + '\n\n');
-            }
-            obs2.on('next', obs2_handler);
-        }
-    }
-}
-
-module.exports = Observable_Publisher;
+const HTTP_Publisher = require('./http-publisher');
+
+const default_keep_alive_interval_ms = 15000;
+
+// Want to do this over websockets too.
+//  Should be a single ws point.
+//   Could give out connection keys alongside the HTTP request.
+//    All the security needed - give out a 256 bit key in the HTML doc, require it to open the websocket connection.
+//     Seems simple, would work with a single process auth provider, then could have centralised auth and token issuance and checking.
+
+class Observable_Publisher extends HTTP_Publisher {
+    constructor(spec = {}) {
+        super(spec);
+
+        let obs;
+        if (spec && spec.obs) {
+            obs = spec.obs;
+            if (spec.schema) this.schema = spec.schema;
+        } else {
+            obs = spec;
+        }
+
+        if (!obs || typeof obs.on !== 'function') {
+            throw new Error('No observable found.');
+        }
+
+        this.type = 'observable';
+        this.obs = obs;
+
+        this.keep_alive_interval_ms = (spec && spec.keep_alive_interval_ms !== undefined)
+            ? spec.keep_alive_interval_ms
+            : default_keep_alive_interval_ms;
+
+        this.is_paused = (typeof obs.status === 'string' && obs.status === 'paused');
+
+        this.active_sse_connections = new Set();
+        this._keep_alive_timer = null;
+
+        this._source_handlers_bound = false;
+        this._bind_source_handlers();
+    }
+
+    _bind_source_handlers() {
+        if (this._source_handlers_bound) return;
+        this._source_handlers_bound = true;
+
+        const { obs } = this;
+
+        this._source_next_handler = (data) => {
+            if (this.is_paused) return;
+            this._broadcast_sse_data(data);
+        };
+
+        this._source_complete_handler = (data) => {
+            this._broadcast_sse_event('complete', data);
+            this._close_all_sse_connections();
+        };
+
+        this._source_error_handler = (err) => {
+            this._broadcast_sse_event('error', this._normalize_error(err));
+            this._close_all_sse_connections();
+        };
+
+        this._source_paused_handler = () => {
+            this.is_paused = true;
+            this._broadcast_sse_event('paused', { status: 'paused' });
+        };
+
+        this._source_resumed_handler = () => {
+            this.is_paused = false;
+            this._broadcast_sse_event('resumed', { status: 'ok' });
+        };
+
+        obs.on('next', this._source_next_handler);
+        obs.on('complete', this._source_complete_handler);
+        obs.on('error', this._source_error_handler);
+        obs.on('paused', this._source_paused_handler);
+        obs.on('resumed', this._source_resumed_handler);
+    }
+
+    _unbind_source_handlers() {
+        if (!this._source_handlers_bound) return;
+        this._source_handlers_bound = false;
+
+        const { obs } = this;
+        const safe_off = (event_name, handler) => {
+            if (typeof obs.off === 'function' && handler) {
+                obs.off(event_name, handler);
+            }
+        };
+
+        safe_off('next', this._source_next_handler);
+        safe_off('complete', this._source_complete_handler);
+        safe_off('error', this._source_error_handler);
+        safe_off('paused', this._source_paused_handler);
+        safe_off('resumed', this._source_resumed_handler);
+
+        this._source_next_handler = null;
+        this._source_complete_handler = null;
+        this._source_error_handler = null;
+        this._source_paused_handler = null;
+        this._source_resumed_handler = null;
+    }
+
+    _normalize_error(err) {
+        if (!err) return { message: 'Unknown error' };
+        if (typeof err === 'string') return { message: err };
+        if (err instanceof Error) return { name: err.name, message: err.message, stack: err.stack };
+        return { message: String(err) };
+    }
+
+    _stringify_sse_data(data) {
+        if (data === undefined) return '';
+        if (typeof data === 'string') return data;
+        try {
+            return JSON.stringify(data);
+        } catch (err) {
+            return JSON.stringify({
+                error: 'non_serializable',
+                message: this._normalize_error(err).message
+            });
+        }
+    }
+
+    _write_sse(res, s) {
+        try {
+            res.write(s);
+            return true;
+        } catch (e) {
+            return false;
+        }
+    }
+
+    _broadcast_raw_sse(s) {
+        const arr_connections = Array.from(this.active_sse_connections);
+        for (const res of arr_connections) {
+            if (res.destroyed || res.writableEnded) {
+                this.active_sse_connections.delete(res);
+                continue;
+            }
+            const ok = this._write_sse(res, s);
+            if (!ok || res.destroyed || res.writableEnded) {
+                this.active_sse_connections.delete(res);
+            }
+        }
+        this._maybe_stop_keep_alive_timer();
+    }
+
+    _broadcast_sse_data(data) {
+        const s_data = this._stringify_sse_data(data);
+        this._broadcast_raw_sse(`data: ${s_data}\n\n`);
+    }
+
+    _broadcast_sse_event(event_name, data) {
+        const s_data = this._stringify_sse_data(data);
+        this._broadcast_raw_sse(`event: ${event_name}\ndata: ${s_data}\n\n`);
+    }
+
+    _close_all_sse_connections() {
+        const arr_connections = Array.from(this.active_sse_connections);
+        this.active_sse_connections.clear();
+        for (const res of arr_connections) {
+            try {
+                if (!res.writableEnded) res.end();
+            } catch (e) { }
+        }
+        this._maybe_stop_keep_alive_timer();
+    }
+
+    _ensure_keep_alive_timer() {
+        if (!this.keep_alive_interval_ms) return;
+        if (this._keep_alive_timer) return;
+
+        this._keep_alive_timer = setInterval(() => {
+            this._broadcast_raw_sse(`: keep-alive ${Date.now()}\n\n`);
+        }, this.keep_alive_interval_ms);
+
+        if (typeof this._keep_alive_timer.unref === 'function') {
+            this._keep_alive_timer.unref();
+        }
+    }
+
+    _maybe_stop_keep_alive_timer() {
+        if (this._keep_alive_timer && this.active_sse_connections.size === 0) {
+            clearInterval(this._keep_alive_timer);
+            this._keep_alive_timer = null;
+        }
+    }
+
+    pause() {
+        this.is_paused = true;
+        if (this.obs && typeof this.obs.pause === 'function') {
+            this.obs.pause();
+        } else {
+            this._broadcast_sse_event('paused', { status: 'paused' });
+        }
+    }
+
+    resume() {
+        this.is_paused = false;
+        if (this.obs && typeof this.obs.resume === 'function') {
+            this.obs.resume();
+        } else {
+            this._broadcast_sse_event('resumed', { status: 'ok' });
+        }
+    }
+
+    stop() {
+        if (this.obs && typeof this.obs.stop === 'function') {
+            this.obs.stop();
+        }
+        this._broadcast_sse_event('stopped', { status: 'stopped' });
+        this._close_all_sse_connections();
+        this._unbind_source_handlers();
+    }
+
+    _handle_http_control(req, res) {
+        const chunks = [];
+
+        req.on('data', chunk => {
+            chunks.push(chunk);
+        });
+
+        req.on('end', () => {
+            const content_type = (req.headers['content-type'] || '').toLowerCase();
+            const body = Buffer.concat(chunks).toString();
+
+            let action = '';
+            if (content_type.includes('application/json')) {
+                try {
+                    const parsed = body ? JSON.parse(body) : {};
+                    action = parsed.action || parsed.command || parsed.cmd || '';
+                } catch (e) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'Invalid JSON body' }));
+                    return;
+                }
+            } else {
+                action = body.trim();
+            }
+
+            const action_lc = String(action || 'status').toLowerCase();
+
+            if (action_lc === 'pause') this.pause();
+            else if (action_lc === 'resume') this.resume();
+            else if (action_lc === 'stop') this.stop();
+            else if (action_lc !== 'status') {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: 'Unknown action', action: action_lc }));
+                return;
+            }
+
+            const obs_status = (this.obs && typeof this.obs.status === 'string')
+                ? this.obs.status
+                : (this.is_paused ? 'paused' : 'ok');
+
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                ok: true,
+                action: action_lc,
+                status: obs_status,
+                connections: this.active_sse_connections.size
+            }));
+        });
+
+        req.on('error', (err) => {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: this._normalize_error(err) }));
+        });
+    }
+
+    handle_http(req, res) {
+        const method = String(req.method || 'GET').toUpperCase();
+
+        if (method === 'POST') {
+            this._handle_http_control(req, res);
+            return;
+        }
+
+        if (method !== 'GET') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+            return;
+        }
+
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'Transfer-Encoding': 'chunked',
+            'X-Accel-Buffering': 'no'
+        });
+
+        // SSE handshake (consumed by client demo; ignored by tests).
+        this._write_sse(res, 'data: OK\n\n');
+
+        this.active_sse_connections.add(res);
+        this._ensure_keep_alive_timer();
+
+        if (this.is_paused) {
+            this._write_sse(res, `event: paused\ndata: ${this._stringify_sse_data({ status: 'paused' })}\n\n`);
+        }
+
+        let removed = false;
+        const remove_connection = () => {
+            if (removed) return;
+            removed = true;
+            this.active_sse_connections.delete(res);
+            this._maybe_stop_keep_alive_timer();
+        };
+
+        req.on('close', remove_connection);
+        res.on('close', remove_connection);
+        res.on('finish', remove_connection);
+    }
+}
+
+module.exports = Observable_Publisher;

package/tests/observable-sse.test.js

@@ -9,8 +9,8 @@ const http = require('http');
 const path = require('path');
 const { get_free_port } = require('../port-utils');
 
-describe('Observable SSE Demo E2E Tests', function() {
-    this.timeout(30000); // Allow time for server startup and SSE streaming
+describe('Observable SSE Demo E2E Tests', function() {
+    this.timeout(90000); // Allow time for bundling + server startup + SSE streaming
 
     let server_process;
     let server_port;
@@ -140,9 +140,9 @@ describe('Observable SSE Demo E2E Tests', function() {
         // Wait for server to be ready
         await new Promise((resolve, reject) => {
             let output = '';
-            const timeout = setTimeout(() => {
-                reject(new Error('Server startup timeout'));
-            }, 15000);
+            const timeout = setTimeout(() => {
+                reject(new Error('Server startup timeout'));
+            }, 45000);
 
             server_process.stdout.on('data', (data) => {
                 output += data.toString();