roster-server 1.9.0 → 1.9.4

package/README.md

@@ -166,6 +166,8 @@ When creating a new `RosterServer` instance, you can pass the following options:
 - `greenlockStorePath` (string): Directory for Greenlock configuration.
 - `staging` (boolean): Set to `true` to use Let's Encrypt's staging environment (for testing).
 - `local` (boolean): Set to `true` to run in local development mode.
+- `minLocalPort` (number): Minimum port for local mode (default: 4000).
+- `maxLocalPort` (number): Maximum port for local mode (default: 9999).
 
 ## 🏠 Local Development Mode
 
@@ -178,19 +180,84 @@ When `{ local: true }` is enabled, RosterServer **Skips SSL/HTTPS**: Runs pure H
 ```javascript
 const server = new Roster({
     wwwPath: '/srv/www',
-    local: true  // Enable local development mode
+    local: true,  // Enable local development mode
+    minLocalPort: 4000,  // Optional: minimum port (default: 4000)
+    maxLocalPort: 9999   // Optional: maximum port (default: 9999)
 });
 server.start();
 ```
 
 ### Port Assignment
 
-In local mode, domains are automatically assigned ports starting from 3000:
+In local mode, domains are automatically assigned ports based on a CRC32 hash of the domain name (default range 4000-9999, configurable via `minLocalPort` and `maxLocalPort`):
 
-- `example.com` → `http://localhost:3000`
-- `api.example.com` → `http://localhost:3001`  
+- `example.com` → `http://localhost:9465`
+- `api.example.com` → `http://localhost:9388`  
 - And so on...
 
+You can customize the port range:
+
+```javascript
+const roster = new Roster({ 
+    local: true,
+    minLocalPort: 5000,  // Start from port 5000
+    maxLocalPort: 6000   // Up to port 6000
+});
+```
+
+### Getting Local URLs
+
+RosterServer provides two methods to get the local URL for a domain:
+
+**1. Static Method (Predictable, No Instance Required):**
+
+```javascript
+// Get the URL before starting the server (using default range 4000-9999)
+const url = Roster.getLocalUrl('example.com');
+console.log(url); // http://localhost:9465
+
+// Or specify custom port range
+const customUrl = Roster.getLocalUrl('example.com', { 
+    minLocalPort: 5000, 
+    maxLocalPort: 6000 
+});
+```
+
+This static method calculates the port deterministically using CRC32, so you can predict the URL before even creating a Roster instance.
+
+**2. Instance Method (After Registration):**
+
+```javascript
+const roster = new Roster({ local: true });
+roster.register('example.com', handler);
+
+await roster.start();
+
+// Get the actual URL assigned to the domain
+const url = roster.getLocalUrl('example.com');
+console.log(url); // http://localhost:9465
+```
+
+This instance method returns the actual URL assigned to the domain after the server starts. It's useful when you need to confirm the URL or when there might be port collisions.
+
+**Example Usage:**
+
+```javascript
+const roster = new Roster({ local: true });
+
+roster.register('example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200);
+        res.end('Hello World!');
+    };
+});
+
+roster.start().then(() => {
+    const url = roster.getLocalUrl('example.com');
+    console.log(`Server available at: ${url}`);
+});
+```
+
 ## 🧂 A Touch of Magic
 
 You might be thinking, "But setting up HTTPS and virtual hosts is supposed to be complicated and time-consuming!" Well, not anymore. With RosterServer, you can get back to writing code that matters, like defending Earth from alien invaders! 👾👾👾

package/demo/custom-port-range.js

@@ -0,0 +1,40 @@
+const Roster = require('../index.js');
+
+// Example with custom port range
+const roster = new Roster({ 
+    local: true,
+    minLocalPort: 5000,  // Custom minimum port
+    maxLocalPort: 5100   // Custom maximum port
+});
+
+console.log('\n📍 Static URL Prediction with custom range (5000-5100):');
+console.log('example.com →', Roster.getLocalUrl('example.com', { 
+    minLocalPort: 5000, 
+    maxLocalPort: 5100 
+}));
+console.log('api.example.com →', Roster.getLocalUrl('api.example.com', { 
+    minLocalPort: 5000, 
+    maxLocalPort: 5100 
+}));
+
+roster.register('example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('Hello from example.com with custom port range!');
+    };
+});
+
+roster.register('api.example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ message: 'API with custom port range' }));
+    };
+});
+
+roster.start().then(() => {
+    console.log('\n🚀 Server Started with custom port range:');
+    console.log('example.com →', roster.getLocalUrl('example.com'));
+    console.log('api.example.com →', roster.getLocalUrl('api.example.com'));
+    
+    console.log('\n✅ Both domains running in custom port range (5000-5100)!');
+});

package/demo/local-url-example.js

@@ -0,0 +1,40 @@
+const Roster = require('../index.js');
+
+// Example 1: Get URL before creating instance (static method)
+console.log('\n📍 Static URL Prediction (before server starts):');
+console.log('example.com →', Roster.getLocalUrl('example.com'));
+console.log('api.example.com →', Roster.getLocalUrl('api.example.com'));
+console.log('test.example.com →', Roster.getLocalUrl('test.example.com'));
+
+// Example 2: Get URL after registration (instance method)
+const roster = new Roster({ local: true });
+
+roster.register('example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('Hello from example.com!');
+    };
+});
+
+roster.register('api.example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ message: 'API endpoint' }));
+    };
+});
+
+roster.start().then(() => {
+    console.log('\n🚀 Server Started - Actual URLs:');
+    console.log('example.com →', roster.getLocalUrl('example.com'));
+    console.log('api.example.com →', roster.getLocalUrl('api.example.com'));
+    
+    // Test with www prefix (should return same URL)
+    console.log('\n🔄 Testing www prefix handling:');
+    console.log('www.example.com →', roster.getLocalUrl('www.example.com'));
+    
+    // Test non-existent domain
+    console.log('\n❌ Testing non-existent domain:');
+    console.log('nonexistent.com →', roster.getLocalUrl('nonexistent.com') || 'null (domain not registered)');
+    
+    console.log('\n✅ All domains running!');
+});

package/demo/socketio.js

@@ -26,4 +26,12 @@ roster.register('example.com', (httpsServer) => {
     };
 });
 
-roster.start();
+roster.start().then(() => {
+    // Get local URL for registered domain (requires instance)
+    const url = roster.getLocalUrl('example.com');
+    console.log(`✅ Socket.IO server available at: ${url}`);
+    
+    // Get local URL without instance (static method - predictable port)
+    const staticUrl = Roster.getLocalUrl('example.com');
+    console.log(`ℹ️  Static prediction: ${staticUrl}`);
+});

package/index.js

@@ -7,6 +7,32 @@ const { EventEmitter } = require('events');
 const Greenlock = require('greenlock-express');
 const log = require('lemonlog')('roster');
 
+// CRC32 implementation for deterministic port assignment
+function crc32(str) {
+    const crcTable = [];
+    for (let i = 0; i < 256; i++) {
+        let crc = i;
+        for (let j = 0; j < 8; j++) {
+            crc = (crc & 1) ? (0xEDB88320 ^ (crc >>> 1)) : (crc >>> 1);
+        }
+        crcTable[i] = crc;
+    }
+
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < str.length; i++) {
+        const byte = str.charCodeAt(i);
+        crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 0xFF];
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+// Convert CRC32 hash to a port number in available range
+function domainToPort(domain, minPort = 3000, maxPort = 65535) {
+    const hash = crc32(domain);
+    const portRange = maxPort - minPort + 1;
+    return minPort + (hash % portRange);
+}
+
 // Virtual Server that completely isolates applications
 class VirtualServer extends EventEmitter {
     constructor(domain) {
@@ -14,7 +40,7 @@ class VirtualServer extends EventEmitter {
         this.domain = domain;
         this.requestListeners = [];
         this.upgradeListeners = [];
-        
+
         // Simulate http.Server properties
         this.listening = false;
         this.address = () => ({ port: 443, family: 'IPv4', address: '0.0.0.0' });
@@ -23,7 +49,7 @@ class VirtualServer extends EventEmitter {
         this.headersTimeout = 60000;
         this.maxHeadersCount = null;
     }
-    
+
     // Override listener methods to capture them
     on(event, listener) {
         if (event === 'request') {
@@ -33,11 +59,11 @@ class VirtualServer extends EventEmitter {
         }
         return super.on(event, listener);
     }
-    
+
     addListener(event, listener) {
         return this.on(event, listener);
     }
-    
+
     // Socket.IO compatibility methods
     listeners(event) {
         if (event === 'request') {
@@ -47,7 +73,7 @@ class VirtualServer extends EventEmitter {
         }
         return super.listeners(event);
     }
-    
+
     removeListener(event, listener) {
         if (event === 'request') {
             const index = this.requestListeners.indexOf(listener);
@@ -62,7 +88,7 @@ class VirtualServer extends EventEmitter {
         }
         return super.removeListener(event, listener);
     }
-    
+
     removeAllListeners(event) {
         if (event === 'request') {
             this.requestListeners = [];
@@ -71,33 +97,33 @@ class VirtualServer extends EventEmitter {
         }
         return super.removeAllListeners(event);
     }
-    
+
     // Simulate other http.Server methods
     listen() { this.listening = true; return this; }
     close() { this.listening = false; return this; }
     setTimeout() { return this; }
-    
+
     // Process request with this virtual server's listeners
     processRequest(req, res) {
         let handled = false;
-        
+
         // Track if response was handled
         const originalEnd = res.end;
-        res.end = function(...args) {
+        res.end = function (...args) {
             handled = true;
             return originalEnd.apply(this, args);
         };
-        
+
         // Try all listeners
         for (const listener of this.requestListeners) {
             if (!handled) {
                 listener(req, res);
             }
         }
-        
+
         // Restore original end method
         res.end = originalEnd;
-        
+
         // If no listener handled the request, try fallback handler
         if (!handled && this.fallbackHandler) {
             this.fallbackHandler(req, res);
@@ -106,14 +132,14 @@ class VirtualServer extends EventEmitter {
             res.end('No handler found');
         }
     }
-    
+
     // Process upgrade events (WebSocket)
     processUpgrade(req, socket, head) {
         // Emit to all registered upgrade listeners
         for (const listener of this.upgradeListeners) {
             listener(req, socket, head);
         }
-        
+
         // If no listeners, destroy the socket
         if (this.upgradeListeners.length === 0) {
             socket.destroy();
@@ -134,8 +160,12 @@ class Roster {
         this.sites = {};
         this.domainServers = {}; // Store separate servers for each domain
         this.portServers = {}; // Store servers by port
+        this.domainPorts = {}; // Store domain → port mapping for local mode
+        this.assignedPorts = new Set(); // Track ports assigned to domains (not OS availability)
         this.hostname = options.hostname || '0.0.0.0';
         this.filename = options.filename || 'index';
+        this.minLocalPort = options.minLocalPort || 4000;
+        this.maxLocalPort = options.maxLocalPort || 9999;
 
         const port = options.port === undefined ? 443 : options.port;
         if (port === 80 && !this.local) {
@@ -306,7 +336,7 @@ class Roster {
         }
 
         const { domain, port } = this.parseDomainWithPort(domainString);
-        
+
         const domainEntries = [domain];
         if ((domain.match(/\./g) || []).length < 2) {
             domainEntries.push(`www.${domain}`);
@@ -336,10 +366,64 @@ class Roster {
         return { domain: domainString, port: this.defaultPort };
     }
 
+    /**
+     * Get the local URL for a domain when running in local mode
+     * @param {string} domain - The domain name (e.g., 'example.com')
+     * @param {Object} options - Optional configuration
+     * @param {number} options.minLocalPort - Minimum port range (default: 4000)
+     * @param {number} options.maxLocalPort - Maximum port range (default: 9999)
+     * @returns {string} The local URL (e.g., 'http://localhost:4321')
+     */
+    static getLocalUrl(domain, options = {}) {
+        const minPort = options.minLocalPort || 4000;
+        const maxPort = options.maxLocalPort || 9999;
+        
+        // Remove www prefix if present
+        const cleanDomain = domain.startsWith('www.') ? domain.slice(4) : domain;
+        
+        // Calculate deterministic port
+        const port = domainToPort(cleanDomain, minPort, maxPort);
+        
+        return `http://localhost:${port}`;
+    }
+
+    /**
+     * Get the local URL for a domain that was registered on this instance
+     * @param {string} domain - The domain name
+     * @returns {string|null} The local URL if found, null otherwise
+     */
+    getLocalUrl(domain) {
+        // Remove www prefix if present
+        const cleanDomain = domain.startsWith('www.') ? domain.slice(4) : domain;
+        
+        // Check if domain has a port assigned
+        if (this.domainPorts && this.domainPorts[cleanDomain]) {
+            return `http://localhost:${this.domainPorts[cleanDomain]}`;
+        }
+        
+        return null;
+    }
+
     createVirtualServer(domain) {
         return new VirtualServer(domain);
     }
 
+    // Assign port to domain, detecting collisions with already assigned ports
+    assignPortToDomain(domain) {
+        let port = domainToPort(domain, this.minLocalPort, this.maxLocalPort);
+
+        // If port is already assigned to another domain, increment until we find a free one
+        while (this.assignedPorts.has(port)) {
+            port++;
+            if (port > this.maxLocalPort) {
+                port = this.minLocalPort; // Wrap around if we exceed max port
+            }
+        }
+
+        this.assignedPorts.add(port);
+        return port;
+    }
+
     // Get SSL context from Greenlock for custom ports
     async getSSLContext(domain, greenlock) {
         try {
@@ -353,39 +437,43 @@ class Roster {
             }
         } catch (error) {
         }
-        
+
         // Return undefined to let HTTPS server handle SNI callback
         return null;
     }
 
     // Start server in local mode with HTTP - simplified version
     startLocalMode() {
-        const startPort = 3000;
-        let currentPort = startPort;
+        // Store mapping of domain to port for later retrieval
+        this.domainPorts = {};
         
-        // Create a simple HTTP server for each domain with sequential ports
+        // Create a simple HTTP server for each domain with CRC32-based ports
         for (const [hostKey, siteApp] of Object.entries(this.sites)) {
             const domain = hostKey.split(':')[0]; // Remove port if present
-            
+
             // Skip www domains in local mode
             if (domain.startsWith('www.')) {
                 continue;
             }
+
+            // Calculate deterministic port based on domain CRC32, with collision detection
+            const port = this.assignPortToDomain(domain);
             
-            const port = currentPort; // Capture current port value
-            
+            // Store domain → port mapping
+            this.domainPorts[domain] = port;
+
             // Create virtual server for the domain
             const virtualServer = this.createVirtualServer(domain);
             this.domainServers[domain] = virtualServer;
-            
+
             // Initialize app with virtual server
             const appHandler = siteApp(virtualServer);
-            
+
             // Create simple dispatcher for this domain
             const dispatcher = (req, res) => {
                 // Set fallback handler on virtual server for non-Socket.IO requests
                 virtualServer.fallbackHandler = appHandler;
-                
+
                 if (virtualServer.requestListeners.length > 0) {
                     virtualServer.processRequest(req, res);
                 } else if (appHandler) {
@@ -395,34 +483,32 @@ class Roster {
                     res.end('Site not found');
                 }
             };
-            
+
             // Create HTTP server for this domain
             const httpServer = http.createServer(dispatcher);
             this.portServers[port] = httpServer;
-            
+
             // Handle WebSocket upgrade events
             httpServer.on('upgrade', (req, socket, head) => {
                 virtualServer.processUpgrade(req, socket, head);
             });
-            
+
             httpServer.listen(port, 'localhost', () => {
                 log.info(`🌐 ${domain} → http://localhost:${port}`);
             });
-            
+
             httpServer.on('error', (error) => {
                 log.error(`❌ Error on port ${port} for ${domain}:`, error.message);
             });
-            
-            currentPort++;
         }
-        
-        log.info(`(✔) Started ${currentPort - startPort} sites in local mode`);
+
+        log.info(`(✔) Started ${Object.keys(this.portServers).length} sites in local mode`);
         return Promise.resolve();
     }
 
     async start() {
         await this.loadSites();
-        
+
         // Skip Greenlock configuration generation in local mode
         if (!this.local) {
             this.generateConfigJson();
@@ -443,7 +529,7 @@ class Roster {
 
         return greenlock.ready(glx => {
             const httpServer = glx.httpServer();
-            
+
             // Group sites by port
             const sitesByPort = {};
             for (const [hostKey, siteApp] of Object.entries(this.sites)) {
@@ -455,12 +541,12 @@ class Roster {
                             appHandlers: {}
                         };
                     }
-                    
+
                     // Create completely isolated virtual server
                     const virtualServer = this.createVirtualServer(domain);
                     sitesByPort[port].virtualServers[domain] = virtualServer;
                     this.domainServers[domain] = virtualServer;
-                    
+
                     // Initialize app with virtual server
                     const appHandler = siteApp(virtualServer);
                     sitesByPort[port].appHandlers[domain] = appHandler;
@@ -472,11 +558,11 @@ class Roster {
             const createDispatcher = (portData) => {
                 return (req, res) => {
                     const host = req.headers.host || '';
-                    
+
                     // Remove port from host header if present (e.g., "domain.com:8080" -> "domain.com")
                     const hostWithoutPort = host.split(':')[0];
                     const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
-                    
+
                     // Handle www redirects
                     if (hostWithoutPort.startsWith('www.')) {
                         res.writeHead(301, { Location: `https://${domain}${req.url}` });
@@ -486,7 +572,7 @@ class Roster {
 
                     const virtualServer = portData.virtualServers[domain];
                     const appHandler = portData.appHandlers[domain];
-                    
+
                     if (virtualServer && virtualServer.requestListeners.length > 0) {
                         // Set fallback handler on virtual server for non-Socket.IO requests
                         virtualServer.fallbackHandler = appHandler;
@@ -512,9 +598,9 @@ class Roster {
                     const host = req.headers.host || '';
                     const hostWithoutPort = host.split(':')[0];
                     const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
-                    
+
                     const virtualServer = portData.virtualServers[domain];
-                    
+
                     if (virtualServer) {
                         virtualServer.processUpgrade(req, socket, head);
                     } else {
@@ -529,15 +615,15 @@ class Roster {
                 const portNum = parseInt(port);
                 const dispatcher = createDispatcher(portData);
                 const upgradeHandler = createUpgradeHandler(portData);
-                
+
                 if (portNum === this.defaultPort) {
                     // Use Greenlock for default port (443) with SSL
                     const httpsServer = glx.httpsServer(null, dispatcher);
                     this.portServers[portNum] = httpsServer;
-                    
+
                     // Handle WebSocket upgrade events
                     httpsServer.on('upgrade', upgradeHandler);
-                    
+
                     httpsServer.listen(portNum, this.hostname, () => {
                         log.info(`HTTPS server listening on port ${portNum}`);
                     });
@@ -551,12 +637,12 @@ class Roster {
                                 const keyPath = path.join(certPath, 'privkey.pem');
                                 const certFilePath = path.join(certPath, 'cert.pem');
                                 const chainPath = path.join(certPath, 'chain.pem');
-                                
+
                                 if (fs.existsSync(keyPath) && fs.existsSync(certFilePath) && fs.existsSync(chainPath)) {
                                     const key = fs.readFileSync(keyPath, 'utf8');
                                     const cert = fs.readFileSync(certFilePath, 'utf8');
                                     const chain = fs.readFileSync(chainPath, 'utf8');
-                                    
+
                                     callback(null, tls.createSecureContext({
                                         key: key,
                                         cert: cert + chain
@@ -569,25 +655,25 @@ class Roster {
                             }
                         }
                     };
-                    
+
                     const httpsServer = https.createServer(httpsOptions, dispatcher);
-                    
+
                     // Handle WebSocket upgrade events
                     httpsServer.on('upgrade', upgradeHandler);
-                    
+
                     httpsServer.on('error', (error) => {
                         log.error(`HTTPS server error on port ${portNum}:`, error.message);
                     });
-                    
+
                     httpsServer.on('tlsClientError', (error) => {
                         // Suppress HTTP request errors to avoid log spam
                         if (!error.message.includes('http request')) {
                             log.error(`TLS error on port ${portNum}:`, error.message);
                         }
                     });
-                    
+
                     this.portServers[portNum] = httpsServer;
-                    
+
                     httpsServer.listen(portNum, this.hostname, (error) => {
                         if (error) {
                             log.error(`Failed to start HTTPS server on port ${portNum}:`, error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "roster-server",
-    "version": "1.9.0",
+    "version": "1.9.4",
     "description": "👾 RosterServer - A domain host router to host multiple HTTPS.",
     "main": "index.js",
     "scripts": {