roster-server 1.9.2 → 1.9.6

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,82 @@ 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 based on a CRC32 hash of the domain name (range 4000-9999):
+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: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 URLs
+
+RosterServer provides a method to get the URL for a domain that adapts automatically to your environment:
+
+**Instance Method: `roster.getUrl(domain)`**
+
+```javascript
+const roster = new Roster({ local: true });
+roster.register('example.com', handler);
+
+await roster.start();
+
+// Get the URL - automatically adapts to environment
+const url = roster.getUrl('example.com');
+console.log(url); 
+// Local mode: http://localhost:9465
+// Production mode: https://example.com
+```
+
+This method:
+- Returns the correct URL based on your environment (`local: true/false`)
+- In **local mode**: Returns `http://localhost:{port}` with the assigned port
+- In **production mode**: Returns `https://{domain}` (or with custom port if configured)
+- Handles `www.` prefix automatically (returns same URL)
+- Returns `null` for domains that aren't registered
+
+**Example Usage:**
+
+```javascript
+// Local development
+const localRoster = new Roster({ local: true });
+localRoster.register('example.com', handler);
+await localRoster.start();
+console.log(localRoster.getUrl('example.com')); 
+// → http://localhost:9465
+
+// Production
+const prodRoster = new Roster({ local: false });
+prodRoster.register('example.com', handler);
+await prodRoster.start();
+console.log(prodRoster.getUrl('example.com')); 
+// → https://example.com
+
+// Production with custom port
+const customRoster = new Roster({ local: false, port: 8443 });
+customRoster.register('api.example.com', handler);
+await customRoster.start();
+console.log(customRoster.getUrl('api.example.com')); 
+// → https://api.example.com:8443
+```
+
 ## 🧂 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,32 @@
+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🔧 Creating server with custom port range (5000-5100)...\n');
+
+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('🚀 Server Started with custom port range:');
+    console.log('example.com →', roster.getUrl('example.com'));
+    console.log('api.example.com →', roster.getUrl('api.example.com'));
+    
+    console.log('\n✅ Both domains running in custom port range (5000-5100)!');
+});

package/demo/environment-aware-url.js

@@ -0,0 +1,55 @@
+const Roster = require('../index.js');
+
+// Example 1: Local mode
+console.log('\n📍 EXAMPLE 1: Local Development Mode\n');
+const localRoster = new Roster({ local: true });
+
+localRoster.register('example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('Hello from local!');
+    };
+});
+
+localRoster.start().then(() => {
+    console.log('Local URL:', localRoster.getUrl('example.com'));
+    console.log('→ Returns: http://localhost:{port}\n');
+});
+
+// Example 2: Production mode (simulated, without actually starting)
+console.log('📍 EXAMPLE 2: Production Mode (simulated)\n');
+const prodRoster = new Roster({ 
+    local: false,
+    email: 'admin@example.com'
+});
+
+prodRoster.register('example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200);
+        res.end('Hello from production!');
+    };
+});
+
+// Don't actually start (would need real SSL), just show what URL would be
+console.log('Production URL (without starting):', 'https://example.com');
+console.log('→ Would return: https://example.com\n');
+
+// Example 3: Production with custom port
+console.log('📍 EXAMPLE 3: Production with Custom Port (simulated)\n');
+const customPortRoster = new Roster({ 
+    local: false,
+    port: 8443,
+    email: 'admin@example.com'
+});
+
+customPortRoster.register('api.example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200);
+        res.end('API');
+    };
+});
+
+console.log('Custom port URL (without starting):', 'https://api.example.com:8443');
+console.log('→ Would return: https://api.example.com:8443\n');
+
+console.log('✅ getUrl() adapts to the environment automatically!');

package/demo/local-url-example.js

@@ -0,0 +1,36 @@
+const Roster = require('../index.js');
+
+// Example: Get URL after registration (adapts to environment)
+console.log('\n🔧 Creating local development server...\n');
+
+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('🚀 Server Started - URLs (based on environment):');
+    console.log('example.com →', roster.getUrl('example.com'));
+    console.log('api.example.com →', roster.getUrl('api.example.com'));
+    
+    // Test with www prefix (should return same URL)
+    console.log('\n🔄 Testing www prefix handling:');
+    console.log('www.example.com →', roster.getUrl('www.example.com'));
+    
+    // Test non-existent domain
+    console.log('\n❌ Testing non-existent domain:');
+    console.log('nonexistent.com →', roster.getUrl('nonexistent.com') || 'null (domain not registered)');
+    
+    console.log('\n✅ All domains running!');
+});

package/demo/socketio.js

@@ -26,4 +26,8 @@ roster.register('example.com', (httpsServer) => {
     };
 });
 
-roster.start();
+roster.start().then(() => {
+    // Get URL for registered domain (adapts to environment)
+    const url = roster.getUrl('example.com');
+    console.log(`✅ Socket.IO server available at: ${url}`);
+});

package/demo/test-geturl.js

@@ -0,0 +1,64 @@
+const Roster = require('../index.js');
+
+console.log('\n🧪 Testing getUrl() method in different scenarios\n');
+
+// Test 1: Local mode with default port
+console.log('TEST 1: Local mode (default port)');
+const local1 = new Roster({ local: true });
+local1.register('example.com', () => (req, res) => res.end('OK'));
+local1.start().then(() => {
+    const url = local1.getUrl('example.com');
+    console.log(`✓ example.com → ${url}`);
+    console.assert(url.startsWith('http://localhost:'), 'Should be localhost HTTP');
+});
+
+// Test 2: Local mode with custom port range
+console.log('\nTEST 2: Local mode (custom port range)');
+const local2 = new Roster({ local: true, minLocalPort: 6000, maxLocalPort: 6100 });
+local2.register('test.com', () => (req, res) => res.end('OK'));
+local2.start().then(() => {
+    const url = local2.getUrl('test.com');
+    console.log(`✓ test.com → ${url}`);
+    const port = parseInt(url.split(':')[2]);
+    console.assert(port >= 6000 && port <= 6100, 'Port should be in custom range');
+});
+
+// Test 3: Production mode (default HTTPS port)
+console.log('\nTEST 3: Production mode (default HTTPS)');
+const prod1 = new Roster({ local: false, email: 'admin@example.com' });
+prod1.register('example.com', () => (req, res) => res.end('OK'));
+const prodUrl1 = prod1.getUrl('example.com');
+console.log(`✓ example.com → ${prodUrl1}`);
+console.assert(prodUrl1 === 'https://example.com', 'Should be HTTPS without port');
+
+// Test 4: Production mode (custom port)
+console.log('\nTEST 4: Production mode (custom port)');
+const prod2 = new Roster({ local: false, port: 8443, email: 'admin@example.com' });
+prod2.register('api.example.com', () => (req, res) => res.end('OK'));
+const prodUrl2 = prod2.getUrl('api.example.com');
+console.log(`✓ api.example.com → ${prodUrl2}`);
+console.assert(prodUrl2 === 'https://api.example.com:8443', 'Should include custom port');
+
+// Test 5: www prefix handling
+console.log('\nTEST 5: www prefix handling');
+const local3 = new Roster({ local: true });
+local3.register('example.com', () => (req, res) => res.end('OK'));
+local3.start().then(() => {
+    const url1 = local3.getUrl('example.com');
+    const url2 = local3.getUrl('www.example.com');
+    console.log(`✓ example.com → ${url1}`);
+    console.log(`✓ www.example.com → ${url2}`);
+    console.assert(url1 === url2, 'www should return same URL');
+});
+
+// Test 6: Non-existent domain
+console.log('\nTEST 6: Non-existent domain');
+const local4 = new Roster({ local: true });
+local4.register('example.com', () => (req, res) => res.end('OK'));
+local4.start().then(() => {
+    const url = local4.getUrl('nonexistent.com');
+    console.log(`✓ nonexistent.com → ${url}`);
+    console.assert(url === null, 'Should return null for unregistered domain');
+    
+    console.log('\n✅ All tests passed!\n');
+});

package/index.js

@@ -160,9 +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) {
@@ -363,19 +366,48 @@ class Roster {
         return { domain: domainString, port: this.defaultPort };
     }
 
+    /**
+     * Get the URL for a domain based on the current environment
+     * @param {string} domain - The domain name
+     * @returns {string|null} The URL if domain is registered, null otherwise
+     */
+    getUrl(domain) {
+        // Remove www prefix if present
+        const cleanDomain = domain.startsWith('www.') ? domain.slice(4) : domain;
+        
+        // Check if domain is registered
+        const isRegistered = this.sites[cleanDomain] || this.sites[`www.${cleanDomain}`];
+        if (!isRegistered) {
+            return null;
+        }
+        
+        // Return URL based on environment
+        if (this.local) {
+            // Local mode: return localhost URL with assigned port
+            if (this.domainPorts && this.domainPorts[cleanDomain]) {
+                return `http://localhost:${this.domainPorts[cleanDomain]}`;
+            }
+            return null;
+        } else {
+            // Production mode: return HTTPS URL
+            const port = this.defaultPort === 443 ? '' : `:${this.defaultPort}`;
+            return `https://${cleanDomain}${port}`;
+        }
+    }
+
     createVirtualServer(domain) {
         return new VirtualServer(domain);
     }
 
     // Assign port to domain, detecting collisions with already assigned ports
-    assignPortToDomain(domain, minPort = 4000, maxPort = 9999) {
-        let port = domainToPort(domain, minPort, maxPort);
+    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 > maxPort) {
-                port = minPort; // Wrap around if we exceed max port
+            if (port > this.maxLocalPort) {
+                port = this.minLocalPort; // Wrap around if we exceed max port
             }
         }
 
@@ -403,6 +435,9 @@ class Roster {
 
     // Start server in local mode with HTTP - simplified version
     startLocalMode() {
+        // Store mapping of domain to port for later retrieval
+        this.domainPorts = {};
+        
         // 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
@@ -413,7 +448,10 @@ class Roster {
             }
 
             // Calculate deterministic port based on domain CRC32, with collision detection
-            const port = this.assignPortToDomain(domain, 4000, 9999);
+            const port = this.assignPortToDomain(domain);
+            
+            // Store domain → port mapping
+            this.domainPorts[domain] = port;
 
             // Create virtual server for the domain
             const virtualServer = this.createVirtualServer(domain);

package/package.json

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