roster-server 1.9.4 → 1.9.8

package/README.md

@@ -18,6 +18,14 @@ Welcome to **RosterServer**, the ultimate domain host router with automatic HTTP
 npm install roster-server
 ```
 
+## 🤖 AI Skill
+
+You can also add RosterServer as a skill for AI agentic development:
+
+```bash
+npx skills add https://github.com/clasen/RosterServer --skill roster-server
+```
+
 ## 🛠️ Usage
 
 ### Directory Structure
@@ -205,27 +213,11 @@ const roster = new Roster({
 });
 ```
 
-### 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 
-});
-```
+### Getting URLs
 
-This static method calculates the port deterministically using CRC32, so you can predict the URL before even creating a Roster instance.
+RosterServer provides a method to get the URL for a domain that adapts automatically to your environment:
 
-**2. Instance Method (After Registration):**
+**Instance Method: `roster.getUrl(domain)`**
 
 ```javascript
 const roster = new Roster({ local: true });
@@ -233,29 +225,43 @@ 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
+// 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 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.
+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
-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}`);
-});
+// 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

package/demo/custom-port-range.js

@@ -7,15 +7,7 @@ const roster = new Roster({
     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 
-}));
+console.log('\n🔧 Creating server with custom port range (5000-5100)...\n');
 
 roster.register('example.com', (httpsServer) => {
     return (req, res) => {
@@ -32,9 +24,9 @@ roster.register('api.example.com', (httpsServer) => {
 });
 
 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('🚀 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

@@ -1,12 +1,8 @@
 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: Get URL after registration (adapts to environment)
+console.log('\n🔧 Creating local development server...\n');
 
-// Example 2: Get URL after registration (instance method)
 const roster = new Roster({ local: true });
 
 roster.register('example.com', (httpsServer) => {
@@ -24,17 +20,17 @@ roster.register('api.example.com', (httpsServer) => {
 });
 
 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'));
+    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.getLocalUrl('www.example.com'));
+    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.getLocalUrl('nonexistent.com') || 'null (domain not registered)');
+    console.log('nonexistent.com →', roster.getUrl('nonexistent.com') || 'null (domain not registered)');
     
     console.log('\n✅ All domains running!');
 });

package/demo/socketio.js

@@ -27,11 +27,7 @@ roster.register('example.com', (httpsServer) => {
 });
 
 roster.start().then(() => {
-    // Get local URL for registered domain (requires instance)
-    const url = roster.getLocalUrl('example.com');
+    // Get URL for registered domain (adapts to environment)
+    const url = roster.getUrl('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/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

@@ -367,41 +367,32 @@ class Roster {
     }
 
     /**
-     * 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
+     * Get the URL for a domain based on the current environment
      * @param {string} domain - The domain name
-     * @returns {string|null} The local URL if found, null otherwise
+     * @returns {string|null} The URL if domain is registered, null otherwise
      */
-    getLocalUrl(domain) {
+    getUrl(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]}`;
+        // Check if domain is registered
+        const isRegistered = this.sites[cleanDomain] || this.sites[`www.${cleanDomain}`];
+        if (!isRegistered) {
+            return null;
         }
         
-        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) {

package/package.json

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

package/skills/roster-server/SKILL.md

@@ -0,0 +1,260 @@
+# RosterServer Skill
+
+## Overview
+
+RosterServer is a virtual hosting platform for multiple HTTPS sites with automatic SSL via Let's Encrypt. Each domain gets an isolated `VirtualServer` instance to prevent configuration conflicts between different application types (Express, Socket.IO, etc).
+
+## Quick Setup
+
+### Production
+```javascript
+const Roster = require('roster-server');
+
+const roster = new Roster({
+    email: 'admin@example.com',
+    wwwPath: '/srv/www',
+    greenlockStorePath: '/srv/greenlock.d',
+    staging: false  // Use true for testing
+});
+
+roster.start();
+```
+
+### Local Development
+```javascript
+const roster = new Roster({
+    local: true,  // HTTP mode, no SSL
+    wwwPath: './www',
+    minLocalPort: 4000,  // Optional
+    maxLocalPort: 9999   // Optional
+});
+
+roster.start().then(() => {
+    console.log('example.com:', roster.getUrl('example.com'));
+    // → http://localhost:9465 (deterministic CRC32-based port)
+});
+```
+
+## Directory Structure
+
+```
+project/
+├── greenlock.d/        # SSL certificates (auto-generated)
+├── www/
+│   ├── example.com/
+│   │   └── index.js   # Handler for example.com
+│   └── api.example.com/
+│       └── index.js   # Handler for subdomain
+└── server.js          # Your setup
+```
+
+## Handler Patterns
+
+Each `www/{domain}/index.js` must export a function that receives `httpsServer` and returns a request handler.
+
+### Pattern 1: Basic HTTP Handler
+```javascript
+module.exports = (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('Hello World');
+    };
+};
+```
+
+### Pattern 2: Express App
+```javascript
+const express = require('express');
+
+module.exports = (httpsServer) => {
+    const app = express();
+    
+    app.get('/', (req, res) => res.send('Hello'));
+    app.post('/api/data', (req, res) => res.json({ ok: true }));
+    
+    return app;
+};
+```
+
+### Pattern 3: Socket.IO
+```javascript
+const { Server } = require('socket.io');
+
+module.exports = (httpsServer) => {
+    const io = new Server(httpsServer);
+    
+    io.on('connection', (socket) => {
+        socket.on('message', (data) => io.emit('message', data));
+    });
+    
+    return (req, res) => {
+        if (req.url && req.url.startsWith(io.opts.path)) return;
+        res.writeHead(200);
+        res.end('Socket.IO running');
+    };
+};
+```
+
+### Pattern 4: Manual Registration
+```javascript
+// In server.js, before roster.start()
+roster.register('example.com', (httpsServer) => {
+    return (req, res) => {
+        res.writeHead(200);
+        res.end('Manual handler');
+    };
+});
+
+// With custom port
+roster.register('api.example.com:8443', handler);
+```
+
+## Key Configuration Options
+
+```javascript
+new Roster({
+    email: 'admin@example.com',      // Required for SSL
+    wwwPath: '/srv/www',             // Site handlers directory
+    greenlockStorePath: '/srv/greenlock.d',  // SSL storage
+    
+    // Environment
+    local: false,                    // true = HTTP, false = HTTPS
+    staging: false,                  // true = Let's Encrypt staging
+    
+    // Server
+    hostname: '0.0.0.0',
+    port: 443,                       // Default HTTPS port (NOT 80!)
+    
+    // Local mode
+    minLocalPort: 4000,
+    maxLocalPort: 9999,
+    
+    // Advanced
+    filename: 'index',               // Handler filename (no extension)
+    basePath: '/srv'                 // Base for relative paths
+})
+```
+
+## Core API
+
+### `roster.start()`
+Loads sites, generates SSL config, starts servers. Returns `Promise<void>`.
+
+### `roster.register(domain, handler)`
+Manually register a domain handler. Domain can include port: `'api.com:8443'`.
+
+### `roster.getUrl(domain)`
+Get environment-aware URL:
+- Local mode: `http://localhost:{port}`
+- Production: `https://{domain}` or `https://{domain}:{port}`
+- Returns `null` if domain not registered
+
+## How It Works
+
+### Request Flow
+1. Request arrives → Dispatcher extracts `Host` header
+2. Strips `www.` prefix (301 redirect if present)
+3. Looks up domain → Gets `VirtualServer` instance
+4. Routes to handler via `virtualServer.processRequest(req, res)`
+
+### VirtualServer Architecture
+Each domain gets isolated server instance that simulates `http.Server`:
+- Captures `request` and `upgrade` event listeners
+- Complete separation between domains
+- No configuration conflicts between apps
+
+### Port Assignment
+**Production**: Default 443, custom via `domain:port` syntax  
+**Local**: CRC32 hash of domain → deterministic port in range 4000-9999  
+**Reserved**: Port 80 for ACME challenges only
+
+### SSL Management
+- Automatic Let's Encrypt certificate generation
+- Auto-renewal 45 days before expiration
+- SNI support for multiple domains
+- Custom ports reuse certificates via SNI callback
+
+## Common Issues & Solutions
+
+**Port 443 in use**: Use different port `{ port: 8443 }`  
+**Certificate failed**: Check firewall (ports 80, 443), verify DNS, try `staging: true`  
+**Site not found**: Verify directory name matches domain, check `index.js` exports function  
+**Local port conflict**: Adjust `minLocalPort`/`maxLocalPort` range  
+**Socket.IO not working**: Ensure handler checks `io.opts.path` and returns properly
+
+## Best Practices
+
+1. **Test with staging first**: `staging: true` to avoid Let's Encrypt rate limits
+2. **Use local mode for dev**: `local: true` for faster iteration
+3. **Environment variables**: Configure via `process.env` for portability
+4. **Error handling**: Wrap handlers with try/catch, don't expose internals
+5. **Socket.IO paths**: Always check `req.url.startsWith(io.opts.path)` in returned handler
+6. **Port 80**: Never use as HTTPS port (reserved for ACME)
+
+## Quick Examples
+
+### Full Production Setup
+```javascript
+const Roster = require('roster-server');
+
+const roster = new Roster({
+    email: process.env.ADMIN_EMAIL,
+    wwwPath: '/srv/www',
+    greenlockStorePath: '/srv/greenlock.d',
+    staging: process.env.NODE_ENV !== 'production'
+});
+
+roster.start().then(() => {
+    console.log('RosterServer running');
+}).catch(err => {
+    console.error('Startup failed:', err);
+    process.exit(1);
+});
+```
+
+### Local Dev with Manual Registration
+```javascript
+const roster = new Roster({ local: true, wwwPath: './www' });
+
+roster.register('test.local', (server) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok', url: roster.getUrl('test.local') }));
+    };
+});
+
+roster.start();
+```
+
+### Environment-Aware Configuration
+```javascript
+const isProduction = process.env.NODE_ENV === 'production';
+
+const roster = new Roster({
+    email: process.env.ADMIN_EMAIL || 'admin@example.com',
+    wwwPath: process.env.WWW_PATH || './www',
+    greenlockStorePath: process.env.SSL_PATH || './greenlock.d',
+    local: !isProduction,
+    staging: !isProduction,
+    minLocalPort: parseInt(process.env.MIN_PORT) || 4000,
+    maxLocalPort: parseInt(process.env.MAX_PORT) || 9999
+});
+
+roster.start();
+```
+
+## Implementation Checklist
+
+When implementing RosterServer:
+
+- [ ] Create `www/` directory structure with domain folders
+- [ ] Each domain has `index.js` exporting `(httpsServer) => handler`
+- [ ] Configure email for Let's Encrypt notifications
+- [ ] Test with `local: true` first
+- [ ] Test with `staging: true` before production
+- [ ] Ensure ports 80 and 443 are open (production)
+- [ ] Verify DNS points to server
+- [ ] Never use port 80 as HTTPS port
+- [ ] Use `roster.getUrl(domain)` for environment-aware URLs
+- [ ] Handle Socket.IO paths correctly in returned handler
+- [ ] Implement error handling in handlers