roster-server 1.9.2 → 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 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 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

@@ -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,57 @@ 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, 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 +444,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 +457,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.4",
     "description": "👾 RosterServer - A domain host router to host multiple HTTPS.",
     "main": "index.js",
     "scripts": {