jsgui3-server 0.0.138 → 0.0.140

package/examples/json/simple-api/README.md

@@ -0,0 +1,125 @@
+# Simple JSON API Example
+
+This is the simplest possible JSON API server using JSGUI3 Server. It demonstrates basic CRUD operations with minimal code.
+
+## Features
+
+- ✅ **Minimal code**: ~70 lines total
+- ✅ **4 API endpoints**: GET status, GET messages, POST add message, POST clear messages
+- ✅ **Data validation**: Input checking with error handling
+- ✅ **In-memory storage**: Simple data persistence
+- ✅ **No UI components**: Pure JSON API server
+
+## API Endpoints
+
+### `GET /api/status`
+Returns server status information.
+
+**Response:**
+```json
+{
+  "status": "running",
+  "timestamp": "2025-11-02T01:48:00.000Z",
+  "version": "1.0.0",
+  "uptime": 123.456
+}
+```
+
+### `GET /api/messages`
+Returns all messages with count.
+
+**Response:**
+```json
+{
+  "messages": [
+    {
+      "id": 1,
+      "text": "Hello, World!",
+      "author": "System",
+      "timestamp": "2025-11-02T01:48:00.000Z"
+    }
+  ],
+  "count": 1
+}
+```
+
+### `POST /api/add-message`
+Adds a new message.
+
+**Request Body:**
+```json
+{
+  "text": "Your message here",
+  "author": "Your Name"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": {
+    "id": 3,
+    "text": "Your message here",
+    "author": "Your Name",
+    "timestamp": "2025-11-02T01:48:00.000Z"
+  }
+}
+```
+
+### `POST /api/clear-messages`
+Clears all messages.
+
+**Response:**
+```json
+{
+  "success": true,
+  "clearedCount": 2,
+  "message": "Cleared 2 messages"
+}
+```
+
+## Running
+
+```bash
+cd examples/json/simple-api
+node server.js
+```
+
+## Testing
+
+```bash
+# Get server status
+curl http://localhost:3002/api/status
+
+# Get messages
+curl http://localhost:3002/api/messages
+
+# Add a message
+curl -X POST http://localhost:3002/api/add-message \
+  -H "Content-Type: application/json" \
+  -d '{"text":"Hello from curl!","author":"Tester"}'
+
+# Clear all messages
+curl -X POST http://localhost:3002/api/clear-messages \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Code Structure
+
+The entire server is in `server.js`:
+
+```javascript
+Server.serve({
+  api: {
+    'status': () => ({ /* status data */ }),
+    'messages': () => ({ /* messages data */ }),
+    'add-message': (data) => ({ /* add logic */ }),
+    'clear-messages': () => ({ /* clear logic */ })
+  },
+  port: 3002
+});
+```
+
+This demonstrates the absolute minimum code needed for a working JSON API server.

package/examples/json/simple-api/diagnostic-report.json

@@ -0,0 +1,73 @@
+{
+  "timestamp": "2025-11-02T03:33:18.682Z",
+  "tests": [
+    {
+      "name": "Module Loading - Server",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.335Z"
+    },
+    {
+      "name": "Module Loading - Server.serve",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.336Z"
+    },
+    {
+      "name": "Module Loading - serve-factory",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.336Z"
+    },
+    {
+      "name": "Server Construction - Instance Creation",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.342Z"
+    },
+    {
+      "name": "Server Construction - Resource Pool",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.343Z"
+    },
+    {
+      "name": "Server Construction - Router",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.343Z"
+    },
+    {
+      "name": "Server Construction - Publish Method",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.343Z"
+    },
+    {
+      "name": "API Setup - Publishing Endpoints",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.346Z"
+    },
+    {
+      "name": "API Setup - Router Access",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.346Z"
+    },
+    {
+      "name": "HTTP Serving - Server Start",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:19.370Z"
+    },
+    {
+      "name": "HTTP Serving - API Response",
+      "status": "passed",
+      "timestamp": "2025-11-02T03:33:20.396Z"
+    },
+    {
+      "name": "End-to-End - Server Startup",
+      "status": "failed",
+      "timestamp": "2025-11-02T03:33:35.422Z",
+      "error": "Server startup timeout"
+    }
+  ],
+  "summary": {
+    "total": 12,
+    "passed": 11,
+    "failed": 1,
+    "errors": [],
+    "successRate": "91.7%"
+  }
+}

package/examples/json/simple-api/diagnostic-test.js

@@ -0,0 +1,433 @@
+// Comprehensive Diagnostic Test System for JSON API Server
+// Tests each component individually to pinpoint failures
+
+const { spawn } = require('child_process');
+const http = require('http');
+const path = require('path');
+const fs = require('fs');
+
+class DiagnosticTestSystem {
+    constructor() {
+        this.results = {
+            timestamp: new Date(),
+            tests: [],
+            summary: {
+                total: 0,
+                passed: 0,
+                failed: 0,
+                errors: []
+            }
+        };
+        this.serverProcess = null;
+        this.testPort = 3003; // Different port to avoid conflicts
+    }
+
+    log(message, level = 'info') {
+        const timestamp = new Date().toISOString();
+        const prefix = level === 'error' ? '❌' : level === 'success' ? '✅' : '🔍';
+        console.log(`[${timestamp}] ${prefix} ${message}`);
+    }
+
+    recordTest(name, status, details = {}) {
+        const test = {
+            name,
+            status,
+            timestamp: new Date(),
+            ...details
+        };
+        this.results.tests.push(test);
+        this.results.summary.total++;
+
+        if (status === 'passed') {
+            this.results.summary.passed++;
+            this.log(`${name}: PASSED`, 'success');
+        } else if (status === 'failed') {
+            this.results.summary.failed++;
+            this.log(`${name}: FAILED - ${details.error || 'Unknown error'}`, 'error');
+        } else if (status === 'error') {
+            this.results.summary.errors.push(details.error);
+            this.log(`${name}: ERROR - ${details.error}`, 'error');
+        }
+
+        return test;
+    }
+
+    async testModuleLoading() {
+        this.log('Testing module loading...');
+
+        try {
+            // Test 1: Load Server module
+            const Server = require('../../../server');
+            if (!Server) {
+                throw new Error('Server module not loaded');
+            }
+            this.recordTest('Module Loading - Server', 'passed');
+
+            // Test 2: Check Server.serve method
+            if (typeof Server.serve !== 'function') {
+                throw new Error('Server.serve is not a function');
+            }
+            this.recordTest('Module Loading - Server.serve', 'passed');
+
+            // Test 3: Load serve-factory
+            const serveFactory = require('../../../serve-factory');
+            if (typeof serveFactory !== 'function') {
+                throw new Error('serve-factory module not loaded');
+            }
+            this.recordTest('Module Loading - serve-factory', 'passed');
+
+            return true;
+        } catch (error) {
+            this.recordTest('Module Loading', 'error', { error: error.message, stack: error.stack });
+            return false;
+        }
+    }
+
+    async testServerConstruction() {
+        this.log('Testing server construction...');
+
+        try {
+            const Server = require('../../../server');
+
+            // Test 1: Create server instance
+            const server = new Server({
+                name: 'Diagnostic Test Server',
+                debug: true
+            });
+
+            if (!server) {
+                throw new Error('Server instance not created');
+            }
+            this.recordTest('Server Construction - Instance Creation', 'passed');
+
+            // Test 2: Check required properties
+            if (!server.resource_pool) {
+                throw new Error('Server missing resource_pool');
+            }
+            this.recordTest('Server Construction - Resource Pool', 'passed');
+
+            if (!server.server_router) {
+                throw new Error('Server missing server_router');
+            }
+            this.recordTest('Server Construction - Router', 'passed');
+
+            // Test 3: Check publish method exists
+            if (typeof server.publish !== 'function') {
+                throw new Error('Server missing publish method');
+            }
+            this.recordTest('Server Construction - Publish Method', 'passed');
+
+            return server;
+        } catch (error) {
+            this.recordTest('Server Construction', 'error', { error: error.message, stack: error.stack });
+            return null;
+        }
+    }
+
+    async testAPISetup(server) {
+        this.log('Testing API setup...');
+
+        try {
+            // Test 1: Publish API endpoints
+            const api = {
+                'test-status': () => ({ status: 'test', timestamp: new Date() }),
+                'test-data': () => ({ data: [1, 2, 3], count: 3 })
+            };
+
+            for (const [name, handler] of Object.entries(api)) {
+                server.publish(name, handler);
+            }
+            this.recordTest('API Setup - Publishing Endpoints', 'passed');
+
+            // Test 2: Check router has routes
+            const router = server.router;
+            if (!router) {
+                throw new Error('Router not accessible');
+            }
+            this.recordTest('API Setup - Router Access', 'passed');
+
+            return true;
+        } catch (error) {
+            this.recordTest('API Setup', 'error', { error: error.message, stack: error.stack });
+            return false;
+        }
+    }
+
+    async testHTTPServing(server) {
+        this.log('Testing HTTP serving...');
+
+        return new Promise((resolve) => {
+            try {
+                // Test 1: Start server
+                server.start(this.testPort, (err) => {
+                    if (err) {
+                        this.recordTest('HTTP Serving - Server Start', 'error', { error: err.message });
+                        resolve(false);
+                        return;
+                    }
+
+                    this.recordTest('HTTP Serving - Server Start', 'passed');
+
+                    // Test 2: Make HTTP request
+                    setTimeout(() => {
+                        this.makeTestRequest('/api/test-status')
+                            .then(response => {
+                                if (response && response.status === 'test') {
+                                    this.recordTest('HTTP Serving - API Response', 'passed');
+                                    resolve(true);
+                                } else {
+                                    this.recordTest('HTTP Serving - API Response', 'failed', {
+                                        error: 'Invalid response',
+                                        response
+                                    });
+                                    resolve(false);
+                                }
+                            })
+                            .catch(error => {
+                                this.recordTest('HTTP Serving - API Response', 'error', { error: error.message });
+                                resolve(false);
+                            })
+                            .finally(() => {
+                                // Clean up server
+                                if (server && server.close) {
+                                    server.close(() => {
+                                        this.log('Test server closed');
+                                    });
+                                }
+                            });
+                    }, 1000); // Wait for server to be ready
+                });
+            } catch (error) {
+                this.recordTest('HTTP Serving', 'error', { error: error.message, stack: error.stack });
+                resolve(false);
+            }
+        });
+    }
+
+    async testEndToEndIntegration() {
+        this.log('Testing end-to-end integration...');
+
+        return new Promise((resolve) => {
+            try {
+                // Start the actual server process
+                this.serverProcess = spawn('node', ['server.js'], {
+                    cwd: path.dirname(__filename),
+                    stdio: ['pipe', 'pipe', 'pipe']
+                });
+
+                let serverOutput = '';
+                let serverStarted = false;
+
+                const timeout = setTimeout(() => {
+                    if (!serverStarted) {
+                        this.recordTest('End-to-End - Server Startup', 'failed', {
+                            error: 'Server startup timeout'
+                        });
+                        this.cleanup();
+                        resolve(false);
+                    }
+                }, 15000);
+
+                this.serverProcess.stdout.on('data', (data) => {
+                    serverOutput += data.toString();
+                    if (serverOutput.includes('🚀 Simple JSON API Server started!') && !serverStarted) {
+                        serverStarted = true;
+                        clearTimeout(timeout);
+                        this.recordTest('End-to-End - Server Startup', 'passed');
+
+                        // Now test the API endpoints
+                        setTimeout(async () => {
+                            try {
+                                // Test status endpoint
+                                const statusResponse = await this.makeTestRequest('/api/status', 3002);
+                                if (!statusResponse || statusResponse.status !== 'running') {
+                                    throw new Error('Status endpoint failed');
+                                }
+
+                                // Test messages endpoint
+                                const messagesResponse = await this.makeTestRequest('/api/messages', 3002);
+                                if (!messagesResponse || !Array.isArray(messagesResponse.messages)) {
+                                    throw new Error('Messages endpoint failed');
+                                }
+
+                                // Test add message
+                                const addResponse = await this.makeTestRequest('/api/add-message', 3002, 'POST', {
+                                    text: 'Diagnostic test message',
+                                    author: 'Diagnostic System'
+                                });
+                                if (!addResponse || !addResponse.success) {
+                                    throw new Error('Add message endpoint failed');
+                                }
+
+                                this.recordTest('End-to-End - API Functionality', 'passed');
+                                resolve(true);
+
+                            } catch (error) {
+                                this.recordTest('End-to-End - API Functionality', 'error', { error: error.message });
+                                resolve(false);
+                            } finally {
+                                this.cleanup();
+                            }
+                        }, 1000);
+                    }
+                });
+
+                this.serverProcess.stderr.on('data', (data) => {
+                    console.error('Server stderr:', data.toString());
+                });
+
+                this.serverProcess.on('error', (error) => {
+                    this.recordTest('End-to-End - Server Process', 'error', { error: error.message });
+                    clearTimeout(timeout);
+                    resolve(false);
+                });
+
+            } catch (error) {
+                this.recordTest('End-to-End Integration', 'error', { error: error.message, stack: error.stack });
+                resolve(false);
+            }
+        });
+    }
+
+    async makeTestRequest(path, port = this.testPort, method = 'GET', data = null) {
+        return new Promise((resolve, reject) => {
+            const options = {
+                hostname: 'localhost',
+                port: port,
+                path: path,
+                method: method,
+                headers: {
+                    'Content-Type': 'application/json'
+                }
+            };
+
+            const req = http.request(options, (res) => {
+                let body = '';
+
+                res.on('data', (chunk) => {
+                    body += chunk;
+                });
+
+                res.on('end', () => {
+                    try {
+                        // Handle empty response body
+                        if (body.trim() === '') {
+                            resolve(null);
+                            return;
+                        }
+                        const response = JSON.parse(body);
+                        resolve(response);
+                    } catch (error) {
+                        reject(new Error(`Failed to parse response: ${body}`));
+                    }
+                });
+            });
+
+            req.on('error', (error) => {
+                reject(error);
+            });
+
+            if (data && method === 'POST') {
+                req.write(JSON.stringify(data));
+            }
+
+            req.end();
+        });
+    }
+
+    cleanup() {
+        if (this.serverProcess) {
+            this.serverProcess.kill('SIGTERM');
+            setTimeout(() => {
+                if (!this.serverProcess.killed) {
+                    this.serverProcess.kill('SIGKILL');
+                }
+            }, 2000);
+        }
+    }
+
+    generateReport() {
+        const report = {
+            ...this.results,
+            summary: {
+                ...this.results.summary,
+                successRate: this.results.summary.total > 0 ?
+                    ((this.results.summary.passed / this.results.summary.total) * 100).toFixed(1) + '%' : '0%'
+            }
+        };
+
+        // Write to file
+        const reportPath = path.join(__dirname, 'diagnostic-report.json');
+        fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+
+        return report;
+    }
+
+    async runAllTests() {
+        this.log('🧪 Starting Comprehensive Diagnostic Tests');
+        this.log('==========================================\n');
+
+        try {
+            // Test 1: Module Loading
+            const modulesLoaded = await this.testModuleLoading();
+            if (!modulesLoaded) {
+                this.log('❌ Module loading failed - cannot continue with other tests');
+                return this.generateReport();
+            }
+
+            // Test 2: Server Construction
+            const server = await this.testServerConstruction();
+            if (!server) {
+                this.log('❌ Server construction failed - cannot continue with other tests');
+                return this.generateReport();
+            }
+
+            // Test 3: API Setup
+            const apiSetup = await this.testAPISetup(server);
+            if (!apiSetup) {
+                this.log('❌ API setup failed - cannot continue with HTTP tests');
+            }
+
+            // Test 4: HTTP Serving
+            await this.testHTTPServing(server);
+
+            // Test 5: End-to-End Integration
+            await this.testEndToEndIntegration();
+
+        } catch (error) {
+            this.log(`❌ Unexpected error during testing: ${error.message}`, 'error');
+            this.recordTest('Unexpected Error', 'error', { error: error.message, stack: error.stack });
+        } finally {
+            this.cleanup();
+        }
+
+        const report = this.generateReport();
+
+        this.log('\n📊 Diagnostic Test Summary');
+        this.log('==========================');
+        this.log(`Total Tests: ${report.summary.total}`);
+        this.log(`Passed: ${report.summary.passed}`);
+        this.log(`Failed: ${report.summary.failed}`);
+        this.log(`Success Rate: ${report.summary.successRate}`);
+
+        if (report.summary.errors.length > 0) {
+            this.log('\n❌ Errors Found:');
+            report.summary.errors.forEach((error, index) => {
+                this.log(`  ${index + 1}. ${error}`);
+            });
+        }
+
+        this.log(`\n📄 Detailed report saved to: diagnostic-report.json`);
+
+        return report;
+    }
+}
+
+// Export for use in other files
+module.exports = DiagnosticTestSystem;
+
+// Run if called directly
+if (require.main === module) {
+    const diagnostic = new DiagnosticTestSystem();
+    diagnostic.runAllTests().catch(console.error);
+}

package/examples/json/simple-api/server-debug.md

@@ -0,0 +1,58 @@
+# Server Startup Debug Document
+
+## Expected Server Behavior
+
+1. **Server.serve() call** - Server should initialize with API configuration
+2. **Route setup** - API routes should be registered (we see "pre routing tree set route" messages)
+3. **Server start** - HTTP server should start listening on port 3002
+4. **Ready event** - Server should emit 'ready' event when fully started
+5. **HTTP requests** - Server should accept and respond to HTTP requests
+
+## Actual Server Behavior
+
+1. **Server.serve() call** - ✅ Server initializes successfully (DEBUG: Starting Server.serve() call)
+2. **Route setup** - ✅ Routes are registered (DEBUG: Publishing API route messages/status/add-message/clear-messages)
+3. **Server start** - ❌ Server never calls server_instance.start() - execution stops after route setup
+4. **Ready event** - ❌ Never emitted because server.start() is never called
+5. **HTTP requests** - ❌ ECONNREFUSED because server never binds to port
+
+## Issues Identified
+
+- Server execution stops after API route setup - never reaches the server start phase
+- The Promise returned by Server.serve() never resolves because start_server() is never called
+- No debug messages from server_instance.start() or resource_pool.start()
+- The server hangs indefinitely after route setup, never proceeding to bind to the port
+- Ready event listener is set up but never fires (no "Ready event fired" message)
+- Fallback timeout is set up but doesn't trigger start_server() either
+
+## Root Cause Analysis
+
+The server has a syntax error in the constructor - `Object.defineProperty(this, 'router', { get: () => server_router });` is missing a semicolon before it, causing a syntax error that prevents the module from loading.
+
+The server never emits a 'ready' event because the constructor fails to execute properly. The 'ready' event is only raised in two places:
+
+1. In the Ctrl (control) branch when wp_publisher emits 'ready'
+2. In the else branch when ws_publisher emits 'ready'
+
+Since we're using API-only mode (no Ctrl specified), we should be in the else branch, but the constructor fails before reaching that logic.
+
+## Issues Identified
+
+1. **Syntax Error**: Missing semicolon before `Object.defineProperty` call
+2. **Server Constructor Failure**: Constructor throws before completing initialization
+3. **No Ready Event**: Server never raises 'ready' event due to constructor failure
+4. **Module Load Failure**: Server module cannot be required due to syntax error
+
+## Debug Steps Taken
+
+- Increased wait times from 5s to 50s after route setup
+- Verified route setup messages are being detected
+- Confirmed server process starts without errors
+- Added detailed error logging for HTTP requests
+
+## Next Steps
+
+- Add console.log statements in server startup code to trace execution
+- Check if server.start() is actually being called
+- Verify port binding is successful
+- Look for any async operations that might be blocking startup