jsgui3-server 0.0.140 → 0.0.141

package/port-utils.js

@@ -0,0 +1,112 @@
+/**
+ * Port utilities for jsgui3-server
+ * Provides automatic free port detection and port management
+ */
+
+const net = require('net');
+
+/**
+ * Find a free port on the specified host
+ * @param {Object} options - Options for port selection
+ * @param {string} [options.host='127.0.0.1'] - Host to check
+ * @param {number} [options.startPort=8080] - Starting port to try (0 = let OS choose)
+ * @param {number} [options.endPort=65535] - Maximum port to try
+ * @returns {Promise<number>} - A free port number
+ */
+function get_free_port(options = {}) {
+    const host = options.host || '127.0.0.1';
+    const start_port = options.startPort || options.start_port || 0;
+    
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE' && start_port > 0) {
+                // Try next port if specific port was requested
+                get_free_port({ ...options, startPort: start_port + 1 })
+                    .then(resolve)
+                    .catch(reject);
+            } else {
+                reject(err);
+            }
+        });
+        
+        server.listen(start_port, host, () => {
+            const { port } = server.address();
+            server.close((err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(port);
+                }
+            });
+        });
+    });
+}
+
+/**
+ * Check if a specific port is available
+ * @param {number} port - Port to check
+ * @param {string} [host='127.0.0.1'] - Host to check
+ * @returns {Promise<boolean>} - True if port is available
+ */
+function is_port_available(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        
+        server.on('error', () => {
+            resolve(false);
+        });
+        
+        server.listen(port, host, () => {
+            server.close(() => {
+                resolve(true);
+            });
+        });
+    });
+}
+
+/**
+ * Find multiple free ports
+ * @param {number} count - Number of ports to find
+ * @param {Object} options - Options for port selection
+ * @returns {Promise<number[]>} - Array of free port numbers
+ */
+async function get_free_ports(count, options = {}) {
+    const ports = [];
+    for (let i = 0; i < count; i++) {
+        const port = await get_free_port(options);
+        ports.push(port);
+    }
+    return ports;
+}
+
+/**
+ * Get a free port, preferring a specific port if available
+ * @param {number} preferred_port - Preferred port (0 = auto-select)
+ * @param {string} [host='127.0.0.1'] - Host to check
+ * @returns {Promise<number>} - The preferred port if available, or a free port
+ */
+async function get_port_or_free(preferred_port, host = '127.0.0.1') {
+    // If 0 or undefined, always auto-select
+    if (!preferred_port || preferred_port === 0) {
+        return get_free_port({ host });
+    }
+    
+    // Check if preferred port is available
+    const available = await is_port_available(preferred_port, host);
+    if (available) {
+        return preferred_port;
+    }
+    
+    // Fall back to auto-select
+    console.log(`Port ${preferred_port} is in use, selecting a free port...`);
+    return get_free_port({ host });
+}
+
+module.exports = {
+    get_free_port,
+    is_port_available,
+    get_free_ports,
+    get_port_or_free
+};

package/serve-factory.js

@@ -9,6 +9,7 @@ const lib_path = require('path');
 const Webpage = require('./website/webpage');
 const HTTP_Webpage_Publisher = require('./publishers/http-webpage-publisher');
 const Static_Route_HTTP_Responder = require('./http/responders/static/Static_Route_HTTP_Responder');
+const { get_port_or_free } = require('./port-utils');
 
 
 const prepare_webpage_route = (server, route, page_options = {}, defaults = {}) => {
@@ -130,8 +131,10 @@ module.exports = (Server) => {
             throw new Error('`pages` option requires at least one control constructor.');
         }
     
-        const port = Number.isFinite(serve_options.port) ? Number(serve_options.port) : (process.env.PORT ? Number(process.env.PORT) : 8080);
-        if (!Number.isFinite(port)) {
+        const port = Number.isFinite(serve_options.port) ? Number(serve_options.port) : (serve_options.port === 'auto' ? 0 : (process.env.PORT ? Number(process.env.PORT) : 8080));
+        const auto_port = serve_options.autoPort !== false && (port === 0 || serve_options.port === 'auto' || serve_options.autoPort === true);
+        
+        if (!Number.isFinite(port) && serve_options.port !== 'auto') {
             throw new Error('Invalid port specified for Server.serve');
         }
     
@@ -193,17 +196,36 @@ module.exports = (Server) => {
         }
 
         return new Promise((resolve, reject) => {
-            const start_server = () => {
+            const start_server = async () => {
                 if (has_started) return;
                 has_started = true;
+                
+                // Determine the actual port to use
+                let actual_port = port;
+                if (auto_port) {
+                    try {
+                        const check_host = host || '127.0.0.1';
+                        actual_port = await get_port_or_free(port, Array.isArray(check_host) ? check_host[0] : check_host);
+                        if (actual_port !== port && port !== 0) {
+                            console.log(`Port ${port} was in use, using port ${actual_port} instead`);
+                        }
+                    } catch (err) {
+                        console.error('Failed to find free port:', err);
+                        return settle(reject, err);
+                    }
+                }
+                
+                // Store the actual port on the server instance for reference
+                server_instance.port = actual_port;
+                
                 console.log('🔍 DEBUG: Calling server_instance.start()');
-                server_instance.start(port, (err) => {
+                server_instance.start(actual_port, (err) => {
                     if (err) {
                         console.log('🔍 DEBUG: server_instance.start() failed:', err);
                         return settle(reject, err);
                     }
                     console.log('🔍 DEBUG: server_instance.start() succeeded');
-                    const message = host ? `Serving on http://${Array.isArray(host) ? host[0] : host}:${port || 0}/` : `Serving on port ${port || 0} (all IPv4 interfaces)`;
+                    const message = host ? `Serving on http://${Array.isArray(host) ? host[0] : host}:${actual_port}/` : `Serving on port ${actual_port} (all IPv4 interfaces)`;
                     console.log(message);
                     console.log('Server ready');
                     settle(resolve, server_instance);

package/tests/README.md

@@ -22,12 +22,13 @@ tests/
 ├── publishers.test.js            # Component isolation tests for publishers
 ├── configuration-validation.test.js  # Configuration validation tests
 ├── end-to-end.test.js            # Full integration tests
-├── content-analysis.test.js      # Content analysis and verification
-├── performance.test.js           # Performance benchmarks
-├── error-handling.test.js        # Error handling and edge cases
-├── test-runner.js                # Custom test runner with reporting
-└── README.md                     # This file
-```
+├── content-analysis.test.js      # Content analysis and verification
+├── performance.test.js           # Performance benchmarks
+├── error-handling.test.js        # Error handling and edge cases
+├── examples-controls.e2e.test.js # Example apps regression (controls)
+├── test-runner.js                # Custom test runner with reporting
+└── README.md                     # This file
+```
 
 ## Running Tests
 
@@ -36,19 +37,24 @@ tests/
 npm test
 ```
 
-### Run Specific Test Suite
-```bash
-# Using the custom test runner
-node tests/test-runner.js --test=bundlers.test.js
-
-# Using mocha directly
-npx mocha tests/bundlers.test.js
-```
-
-### Run Tests with Options
-```bash
-# Debug mode (enables sourcemaps)
-node tests/test-runner.js --debug
+### Run Specific Test Suite
+```bash
+# Using the custom test runner
+node tests/test-runner.js --test=bundlers.test.js
+
+# Using mocha directly
+npx mocha tests/bundlers.test.js
+```
+
+### Run Example Apps Regression Suite
+```bash
+npm run test:examples:controls
+```
+
+### Run Tests with Options
+```bash
+# Debug mode (enables sourcemaps)
+node tests/test-runner.js --debug
 
 # Verbose output
 node tests/test-runner.js --verbose
@@ -113,12 +119,20 @@ Comprehensive error scenario testing:
 
 - Invalid JavaScript syntax
 - File system errors (permissions, missing files)
-- Configuration validation errors
-- Network and HTTP errors
-- Memory and performance limits
-- Encoding issues
-
-## Configuration Examples
+- Configuration validation errors
+- Network and HTTP errors
+- Memory and performance limits
+- Encoding issues
+
+### 7. Examples/Controls E2E Tests (`examples-controls.e2e.test.js`)
+
+Regression coverage for a representative set of `examples/controls/*` apps:
+
+- Boots a server per example control
+- Verifies `/`, `/js/js.js`, and `/css/css.css` routes
+- Ensures HTML rendering works without `Accept-Encoding`
+
+## Configuration Examples
 
 ### Basic Minification
 ```javascript
@@ -247,4 +261,4 @@ The test suite is designed to work with continuous integration:
     path: test-report.json
 ```
 
-This ensures the minification, compression, and sourcemap features maintain their functionality across code changes.
+This ensures the minification, compression, and sourcemap features maintain their functionality across code changes.

package/tests/examples-controls.e2e.test.js

@@ -0,0 +1,164 @@
+/**
+ * E2E regression tests for example control apps under examples/controls/.
+ *
+ * These tests boot a server for a selected set of examples and validate:
+ * - The HTML route renders successfully (even without Accept-Encoding)
+ * - Bundled JS and CSS routes are served
+ * - The server-rendered HTML includes the expected number of Window controls
+ */
+
+const assert = require('assert');
+const http = require('http');
+const path = require('path');
+const { describe, it } = require('mocha');
+
+const Server = require('../server');
+const { get_free_port } = require('../port-utils');
+
+const repo_root_path = path.join(__dirname, '..');
+const examples_controls_root_path = path.join(repo_root_path, 'examples', 'controls');
+
+const examples = [
+    { dir_name: '1) window', ctrl_name: 'Demo_UI', expected_window_count: 1 },
+    { dir_name: '2) two windows', ctrl_name: 'Demo_UI', expected_window_count: 2 },
+    { dir_name: '3) five windows', ctrl_name: 'Demo_UI', expected_window_count: 5 },
+    { dir_name: '4) window, tabbed panel', ctrl_name: 'Demo_UI', expected_window_count: 1 },
+    { dir_name: '5) window, grid', ctrl_name: 'Demo_UI', expected_window_count: 1 },
+    { dir_name: '8) window, checkbox/a)', ctrl_name: 'Demo_UI', expected_window_count: 1 },
+    { dir_name: '9) window, date picker', ctrl_name: 'Demo_UI', expected_window_count: 1 },
+    { dir_name: '12) window, Select_Options control', ctrl_name: 'Demo_UI', expected_window_count: 1 },
+    { dir_name: '13) window, Dropdown_Menu control', ctrl_name: 'Demo_UI', expected_window_count: 1 }
+];
+
+function make_request(url, { headers = {} } = {}) {
+    return new Promise((resolve, reject) => {
+        const parsed_url = new URL(url);
+        const options = {
+            hostname: parsed_url.hostname,
+            port: parsed_url.port,
+            path: parsed_url.pathname,
+            method: 'GET',
+            headers: {
+                'User-Agent': 'JSGUI3-Examples-E2E/1.0',
+                ...headers
+            }
+        };
+
+        const req = http.request(options, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                resolve({
+                    status_code: res.statusCode,
+                    headers: res.headers,
+                    body: Buffer.concat(chunks).toString('utf8')
+                });
+            });
+        });
+
+        req.on('error', reject);
+        req.setTimeout(15000, () => {
+            req.destroy();
+            reject(new Error('Request timeout'));
+        });
+        req.end();
+    });
+}
+
+function count_occurrences(haystack, needle) {
+    let idx = 0;
+    let count = 0;
+    while (true) {
+        idx = haystack.indexOf(needle, idx);
+        if (idx === -1) return count;
+        count++;
+        idx += needle.length;
+    }
+}
+
+async function start_example_server({ dir_name, ctrl_name }) {
+    const example_dir_path = path.join(examples_controls_root_path, dir_name);
+    const example_client_path = path.join(example_dir_path, 'client.js');
+
+    const jsgui = require(example_client_path);
+    const ctrl = jsgui.controls && jsgui.controls[ctrl_name];
+    assert(ctrl, `Missing exported control jsgui.controls.${ctrl_name} in ${example_client_path}`);
+
+    const server = new Server({
+        Ctrl: ctrl,
+        src_path_client_js: example_client_path,
+        name: `examples/controls/${dir_name}`
+    });
+
+    server.allowed_addresses = ['127.0.0.1'];
+
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error('Publisher ready timeout')), 60000);
+        server.on('ready', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+
+    const port = await get_free_port();
+
+    await new Promise((resolve, reject) => {
+        server.start(port, (err) => (err ? reject(err) : resolve()));
+    });
+
+    return { server, port };
+}
+
+async function close_server(server) {
+    await new Promise((resolve) => server.close(resolve));
+}
+
+describe('Examples/Controls E2E Regression Tests', function() {
+    this.timeout(180000);
+
+    for (const example of examples) {
+        it(`should render and serve bundles for "${example.dir_name}"`, async function() {
+            const { server, port } = await start_example_server(example);
+
+            try {
+                const base_url = `http://127.0.0.1:${port}`;
+
+                const html_response = await make_request(`${base_url}/`, {
+                    headers: {
+                        // Deliberately omit Accept-Encoding to ensure identity works.
+                    }
+                });
+
+                assert.strictEqual(html_response.status_code, 200);
+                assert(
+                    (html_response.headers['content-type'] || '').includes('text/html'),
+                    'Expected HTML content-type'
+                );
+
+                const window_count = count_occurrences(html_response.body, 'data-jsgui-type="window"');
+                assert.strictEqual(
+                    window_count,
+                    example.expected_window_count,
+                    `Expected ${example.expected_window_count} windows, got ${window_count}`
+                );
+
+                const js_response = await make_request(`${base_url}/js/js.js`);
+                assert.strictEqual(js_response.status_code, 200);
+                assert(
+                    (js_response.headers['content-type'] || '').includes('javascript'),
+                    'Expected JavaScript content-type'
+                );
+                assert(js_response.body.length > 1000, 'Expected non-trivial JS bundle');
+
+                const css_response = await make_request(`${base_url}/css/css.css`);
+                assert.strictEqual(css_response.status_code, 200);
+                assert(
+                    (css_response.headers['content-type'] || '').includes('css'),
+                    'Expected CSS content-type'
+                );
+            } finally {
+                await close_server(server);
+            }
+        });
+    }
+});