roster-server 2.3.16 → 2.4.2

package/README.md

@@ -350,6 +350,71 @@ console.log(customRoster.getUrl('api.example.com'));
 // → https://api.example.com:8443
 ```
 
+## 🔌 Cluster-Friendly API (init / attach)
+
+RosterServer can coexist with external cluster managers (sticky-session libraries, PM2 cluster, custom master/worker architectures) that already own the TCP socket and distribute connections. Instead of letting Roster create and bind servers, you initialize routing separately and wire it into your own server.
+
+### How It Works
+
+`roster.init()` loads sites, creates VirtualServers, and prepares dispatchers — but creates **no servers** and calls **no `.listen()`**. You then get handler functions to wire into any `http.Server` or `https.Server`.
+
+### Quick Example: Sticky-Session Worker
+
+```javascript
+import https from 'https';
+import Roster from 'roster-server';
+
+const roster = new Roster({
+    email: 'admin@example.com',
+    wwwPath: '/srv/www',
+    greenlockStorePath: '/srv/greenlock.d'
+});
+
+await roster.init();
+
+// Create your own HTTPS server with Roster's SNI + routing
+const server = https.createServer({ SNICallback: roster.sniCallback() });
+roster.attach(server);
+
+// Master passes connections via IPC — worker never calls listen()
+process.on('message', (msg, connection) => {
+    if (msg === 'sticky-session:connection') {
+        server.emit('connection', connection);
+    }
+});
+```
+
+### API Reference
+
+#### `roster.init()` → `Promise<Roster>`
+
+Loads sites, generates SSL config (production), creates VirtualServers and initializes handlers. Idempotent — calling it twice is safe. Returns `this` for chaining.
+
+#### `roster.requestHandler(port?)` → `(req, res) => void`
+
+Returns the Host-header dispatch function for a given port (defaults to `defaultPort`). Handles www→non-www redirects, wildcard matching, and VirtualServer dispatch.
+
+#### `roster.upgradeHandler(port?)` → `(req, socket, head) => void`
+
+Returns the WebSocket upgrade dispatcher for a given port. Routes upgrades to the correct VirtualServer.
+
+#### `roster.sniCallback()` → `(servername, callback) => void`
+
+Returns a TLS SNI callback that resolves certificates from `greenlockStorePath` on disk. Not available in local mode.
+
+#### `roster.attach(server, { port }?)` → `Roster`
+
+Convenience method. Wires `requestHandler` and `upgradeHandler` onto `server.on('request', ...)` and `server.on('upgrade', ...)`. Returns `this` for chaining.
+
+### Standalone Mode (unchanged)
+
+`roster.start()` still works exactly as before — it calls `init()` internally, then creates and binds servers:
+
+```javascript
+const roster = new Roster({ ... });
+await roster.start(); // full standalone mode, no changes needed
+```
+
 ## 🧂 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/cluster-sticky-https-sni.js

@@ -0,0 +1,90 @@
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const Roster = require('../index.js');
+
+function hasCertificateFor(storePath, subject) {
+    const base = path.join(storePath, 'live', subject);
+    return (
+        fs.existsSync(path.join(base, 'privkey.pem')) &&
+        fs.existsSync(path.join(base, 'cert.pem')) &&
+        fs.existsSync(path.join(base, 'chain.pem'))
+    );
+}
+
+async function main() {
+    // In this demo, certs are expected to already exist in greenlock.d/live/<subject>.
+    // init()+attach() do routing only; no ACME issuance/listen lifecycle is started.
+    const greenlockStorePath = process.env.GREENLOCK_STORE_PATH || path.join(__dirname, '..', 'greenlock.d');
+    const listenPort = Number(process.env.DEMO_HTTPS_PORT || 19643);
+
+    const roster = new Roster({
+        local: false,
+        email: process.env.ADMIN_EMAIL || 'admin@example.com',
+        greenlockStorePath
+    });
+
+    roster.register('example.com', () => {
+        return (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('hello from external HTTPS worker (default port routes)');
+        };
+    });
+
+    roster.register('api.example.com:9443', () => {
+        return (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, source: 'api.example.com:9443 route table' }));
+        };
+    });
+
+    await roster.init();
+
+    const missing = ['example.com', '*.example.com'].filter((subject) => !hasCertificateFor(greenlockStorePath, subject));
+    if (missing.length > 0) {
+        console.log('\n⚠️  Missing certificate files for:');
+        missing.forEach((subject) => console.log(`  - ${subject}`));
+        console.log('\nExpected files:');
+        console.log('  greenlock.d/live/<subject>/privkey.pem');
+        console.log('  greenlock.d/live/<subject>/cert.pem');
+        console.log('  greenlock.d/live/<subject>/chain.pem');
+        console.log('\nTip: run regular roster.start() once (or your cert manager) to issue certs first.\n');
+    }
+
+    const server = https.createServer({
+        SNICallback: roster.sniCallback(),
+        minVersion: 'TLSv1.2',
+        maxVersion: 'TLSv1.3'
+    });
+
+    // Attach default routing table (defaultPort = 443 routes)
+    roster.attach(server);
+
+    await new Promise((resolve, reject) => {
+        server.listen(listenPort, '0.0.0.0', resolve);
+        server.on('error', reject);
+    });
+
+    console.log('\n✅ HTTPS cluster-friendly demo running');
+    console.log(`Listening on :${listenPort} with external server ownership`);
+    console.log('Roster only provides SNI + vhost routing (no internal listen/bootstrap).\n');
+
+    console.log('Try:');
+    console.log(`curl -k --resolve example.com:${listenPort}:127.0.0.1 https://example.com:${listenPort}/`);
+    console.log(`curl -k --resolve www.example.com:${listenPort}:127.0.0.1 https://www.example.com:${listenPort}/foo`);
+    console.log('\nFor custom route table port=9443, attach another server:');
+    console.log('  const srv9443 = https.createServer({ SNICallback: roster.sniCallback() });');
+    console.log('  roster.attach(srv9443, { port: 9443 });');
+    console.log('  srv9443.listen(19644);');
+    console.log(`  curl -k --resolve api.example.com:19644:127.0.0.1 https://api.example.com:19644/`);
+
+    // Sticky-session runtime pattern:
+    // process.on('message', (msg, socket) => {
+    //   if (msg === 'sticky-session:connection') server.emit('connection', socket);
+    // });
+}
+
+main().catch((err) => {
+    console.error('Demo failed:', err);
+    process.exit(1);
+});

package/demo/cluster-sticky-worker.js

@@ -0,0 +1,60 @@
+const http = require('http');
+const Roster = require('../index.js');
+
+async function main() {
+    const roster = new Roster({
+        local: true,
+        minLocalPort: 19500,
+        maxLocalPort: 19550
+    });
+
+    roster.register('example.com', () => {
+        return (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('[example.com] hello from external worker wiring');
+        };
+    });
+
+    roster.register('api.example.com:9000', () => {
+        return (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, source: 'api.example.com:9000' }));
+        };
+    });
+
+    // init() prepares virtual-host routing, but does not create/listen sockets.
+    await roster.init();
+
+    // This server represents your external runtime-owned worker server.
+    const server443 = http.createServer();
+    roster.attach(server443); // defaultPort routes (443)
+
+    const server9000 = http.createServer();
+    roster.attach(server9000, { port: 9000 }); // custom port routes
+
+    await new Promise((resolve, reject) => {
+        server443.listen(19501, 'localhost', resolve);
+        server443.on('error', reject);
+    });
+
+    await new Promise((resolve, reject) => {
+        server9000.listen(19502, 'localhost', resolve);
+        server9000.on('error', reject);
+    });
+
+    console.log('\n✅ Cluster-friendly worker demo running');
+    console.log('Roster did not bind ports itself. External servers own listen().\n');
+    console.log('Try requests with Host headers:');
+    console.log('curl -H "Host: example.com" http://localhost:19501/');
+    console.log('curl -H "Host: api.example.com" http://localhost:19502/\n');
+
+    // Sticky-session runtimes normally pass accepted sockets into the worker:
+    // process.on('message', (msg, socket) => {
+    //     if (msg === 'sticky-session:connection') server443.emit('connection', socket);
+    // });
+}
+
+main().catch((err) => {
+    console.error('Demo failed:', err);
+    process.exit(1);
+});

package/docs/architecture/decision-roster-cluster-friendly-api.md

@@ -0,0 +1,30 @@
+---
+id: n5edmg25e9
+type: architecture
+title: 'Architecture: Cluster-friendly init/attach API for RosterServer'
+created: '2026-03-20 20:38:03'
+---
+# Architecture: Cluster-Friendly init/attach API
+
+**What**: Split Roster's monolithic `start()` into `init()` (routing preparation) + optional `start()` (server lifecycle). New public methods: `init()`, `requestHandler(port?)`, `upgradeHandler(port?)`, `sniCallback()`, `attach(server, opts?)`.
+
+**Where**: `index.js` — Roster class. Private methods: `_initSiteHandlers()`, `_createDispatcher()`, `_createUpgradeHandler()`, `_normalizeHostInput()`, `_loadCert()`, `_resolvePemsForServername()`, `_initSniResolver()`.
+
+**Why**: `start()` assumed full ownership of bootstrap (listen, lifecycle, dispatch), conflicting with external cluster managers (sticky-session, PM2 cluster) that already own the TCP socket and distribute connections.
+
+**Design decisions**:
+- `init()` is idempotent (guarded by `_initialized` flag)
+- `start()` calls `init()` internally — zero breaking changes for existing users
+- SNI callback in `init()` path uses disk-based cert resolution only (no Greenlock runtime) — safe for workers
+- Greenlock-backed issuance only happens in `start()` production path — reserved for the process managing certs
+- `_createDispatcher` uses `this.local` to choose http/https protocol for www redirects
+- `startLocalMode()` was refactored to consume pre-initialized `_sitesByPort` from `init()`
+- 14 new tests added covering init/handlers/attach/sni contracts
+
+**Key pattern for users**:
+```javascript
+await roster.init();
+const server = https.createServer({ SNICallback: roster.sniCallback() });
+roster.attach(server);
+// Master passes connections — worker never calls listen()
+```

package/docs/decisions/git-master-acme-init-retry.md

@@ -0,0 +1,7 @@
+---
+id: 47bowe7gen
+type: decision
+title: Pushed ACME retry commit
+created: '2026-03-17 11:47:46'
+---
+Committed and pushed master commit ecb2723. Changes: added retry loop (3 attempts with incremental backoff) around ACME directory init in vendor/greenlock/greenlock.js and updated package-lock.json version from 2.2.10 to 2.2.12.

package/index.js

@@ -252,6 +252,9 @@ class Roster {
         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._sitesByPort = {};
+        this._initialized = false;
+        this._sniCallback = null;
         this.hostname = options.hostname ?? '::';
         this.filename = options.filename || 'index';
         this.minLocalPort = options.minLocalPort || 4000;
@@ -662,65 +665,219 @@ class Roster {
         return null;
     }
 
-    // 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
+    _normalizeHostInput(value) {
+        if (typeof value === 'string') return value;
+        if (!value || typeof value !== 'object') return '';
+        if (typeof value.servername === 'string') return value.servername;
+        if (typeof value.hostname === 'string') return value.hostname;
+        if (typeof value.subject === 'string') return value.subject;
+        return '';
+    }
 
-            // Skip www domains in local mode
-            if (domain.startsWith('www.')) {
-                continue;
-            }
+    _loadCert(subjectDir) {
+        const normalizedSubject = this._normalizeHostInput(subjectDir).trim().toLowerCase();
+        if (!normalizedSubject) return null;
+        const certPath = path.join(this.greenlockStorePath, 'live', normalizedSubject);
+        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)) {
+            return {
+                key: fs.readFileSync(keyPath, 'utf8'),
+                cert: fs.readFileSync(certFilePath, 'utf8') + fs.readFileSync(chainPath, 'utf8')
+            };
+        }
+        return null;
+    }
 
-            // Calculate deterministic port based on domain CRC32, with collision detection
-            const port = this.assignPortToDomain(domain);
+    _resolvePemsForServername(servername) {
+        const host = this._normalizeHostInput(servername).trim().toLowerCase();
+        if (!host) return null;
+        const candidates = buildCertLookupCandidates(host);
+        for (const candidate of candidates) {
+            const pems = this._loadCert(candidate);
+            if (pems) return pems;
+        }
+        return null;
+    }
 
-            // Store domain → port mapping
-            this.domainPorts[domain] = port;
+    _initSiteHandlers() {
+        this._sitesByPort = {};
+        for (const [hostKey, siteApp] of Object.entries(this.sites)) {
+            if (hostKey.startsWith('www.')) continue;
+            const { domain, port } = this.parseDomainWithPort(hostKey);
+            if (!this._sitesByPort[port]) {
+                this._sitesByPort[port] = {
+                    virtualServers: {},
+                    appHandlers: {}
+                };
+            }
 
-            // Create virtual server for the domain
             const virtualServer = this.createVirtualServer(domain);
+            this._sitesByPort[port].virtualServers[domain] = virtualServer;
             this.domainServers[domain] = virtualServer;
 
-            // Initialize app with virtual server
             const appHandler = siteApp(virtualServer);
+            this._sitesByPort[port].appHandlers[domain] = appHandler;
+            if (!domain.startsWith('*.')) {
+                this._sitesByPort[port].appHandlers[`www.${domain}`] = appHandler;
+            }
+        }
+    }
 
-            // Create simple dispatcher for this domain
-            const dispatcher = (req, res) => {
-                // Set fallback handler on virtual server for non-Socket.IO requests
+    _createDispatcher(portData) {
+        return (req, res) => {
+            const host = req.headers.host || '';
+            const hostWithoutPort = host.split(':')[0].toLowerCase();
+            const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
+
+            if (hostWithoutPort.startsWith('www.')) {
+                const protocol = this.local ? 'http' : 'https';
+                res.writeHead(301, { Location: `${protocol}://${domain}${req.url}` });
+                res.end();
+                return;
+            }
+
+            const resolved = this.getHandlerForPortData(domain, portData);
+            if (!resolved) {
+                res.writeHead(404);
+                res.end('Site not found');
+                return;
+            }
+            const { virtualServer, appHandler } = resolved;
+
+            if (virtualServer && virtualServer.requestListeners.length > 0) {
                 virtualServer.fallbackHandler = appHandler;
+                virtualServer.processRequest(req, res);
+            } else if (appHandler) {
+                appHandler(req, res);
+            } else {
+                res.writeHead(404);
+                res.end('Site not found');
+            }
+        };
+    }
+
+    _createUpgradeHandler(portData) {
+        return (req, socket, head) => {
+            const host = req.headers.host || '';
+            const hostWithoutPort = host.split(':')[0].toLowerCase();
+            const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
+
+            const resolved = this.getHandlerForPortData(domain, portData);
+            if (resolved && resolved.virtualServer) {
+                resolved.virtualServer.processUpgrade(req, socket, head);
+            } else {
+                socket.destroy();
+            }
+        };
+    }
 
-                if (virtualServer.requestListeners.length > 0) {
-                    virtualServer.processRequest(req, res);
-                } else if (appHandler) {
-                    appHandler(req, res);
+    _initSniResolver() {
+        this._sniCallback = (servername, callback) => {
+            try {
+                const pems = this._resolvePemsForServername(servername);
+                if (pems) {
+                    callback(null, tls.createSecureContext({ key: pems.key, cert: pems.cert }));
                 } else {
-                    res.writeHead(404);
-                    res.end('Site not found');
+                    callback(new Error(`No certificate files available for ${servername}`));
                 }
+            } catch (error) {
+                callback(error);
+            }
+        };
+    }
+
+    async init() {
+        if (this._initialized) return this;
+        await this.loadSites();
+        if (!this.local) {
+            this.generateConfigJson();
+        }
+        this._initSiteHandlers();
+        if (!this.local) {
+            this._initSniResolver();
+        }
+        this._initialized = true;
+        return this;
+    }
+
+    requestHandler(port) {
+        if (!this._initialized) throw new Error('Call init() before requestHandler()');
+        const targetPort = port || this.defaultPort;
+        const portData = this._sitesByPort[targetPort];
+        if (!portData) {
+            return (req, res) => {
+                res.writeHead(404);
+                res.end('Site not found');
             };
+        }
+        return this._createDispatcher(portData);
+    }
 
-            // Create HTTP server for this domain
-            const httpServer = http.createServer(dispatcher);
-            this.portServers[port] = httpServer;
+    upgradeHandler(port) {
+        if (!this._initialized) throw new Error('Call init() before upgradeHandler()');
+        const targetPort = port || this.defaultPort;
+        const portData = this._sitesByPort[targetPort];
+        if (!portData) {
+            return (req, socket, head) => { socket.destroy(); };
+        }
+        return this._createUpgradeHandler(portData);
+    }
 
-            // Handle WebSocket upgrade events
-            httpServer.on('upgrade', (req, socket, head) => {
-                virtualServer.processUpgrade(req, socket, head);
-            });
+    sniCallback() {
+        if (!this._initialized) throw new Error('Call init() before sniCallback()');
+        if (!this._sniCallback) throw new Error('SNI callback not available in local mode');
+        return this._sniCallback;
+    }
 
-            httpServer.listen(port, 'localhost', () => {
-                const cleanDomain = normalizeDomainForLocalHost(domain);
-                log.info(`🌐 ${domain} → http://${localHostForDomain(cleanDomain)}:${port}`);
-            });
+    attach(server, { port } = {}) {
+        if (!this._initialized) throw new Error('Call init() before attach()');
+        server.on('request', this.requestHandler(port));
+        server.on('upgrade', this.upgradeHandler(port));
+        return this;
+    }
 
-            httpServer.on('error', (error) => {
-                log.error(`❌ Error on port ${port} for ${domain}:`, error.message);
-            });
+    startLocalMode() {
+        this.domainPorts = {};
+
+        for (const portData of Object.values(this._sitesByPort)) {
+            for (const [domain, virtualServer] of Object.entries(portData.virtualServers)) {
+                if (domain.startsWith('www.')) continue;
+
+                const port = this.assignPortToDomain(domain);
+                this.domainPorts[domain] = port;
+
+                const appHandler = portData.appHandlers[domain];
+
+                const dispatcher = (req, res) => {
+                    virtualServer.fallbackHandler = appHandler;
+                    if (virtualServer.requestListeners.length > 0) {
+                        virtualServer.processRequest(req, res);
+                    } else if (appHandler) {
+                        appHandler(req, res);
+                    } else {
+                        res.writeHead(404);
+                        res.end('Site not found');
+                    }
+                };
+
+                const httpServer = http.createServer(dispatcher);
+                this.portServers[port] = httpServer;
+
+                httpServer.on('upgrade', (req, socket, head) => {
+                    virtualServer.processUpgrade(req, socket, head);
+                });
+
+                httpServer.listen(port, 'localhost', () => {
+                    const cleanDomain = normalizeDomainForLocalHost(domain);
+                    log.info(`🌐 ${domain} → http://${localHostForDomain(cleanDomain)}:${port}`);
+                });
+
+                httpServer.on('error', (error) => {
+                    log.error(`❌ Error on port ${port} for ${domain}:`, error.message);
+                });
+            }
         }
 
         log.info(`(✔) Started ${Object.keys(this.portServers).length} sites in local mode`);
@@ -728,14 +885,8 @@ class Roster {
     }
 
     async start() {
-        await this.loadSites();
+        await this.init();
 
-        // Skip Greenlock configuration generation in local mode
-        if (!this.local) {
-            this.generateConfigJson();
-        }
-
-        // Handle local mode with simple HTTP server
         if (this.local) {
             return this.startLocalMode();
         }
@@ -794,7 +945,6 @@ class Roster {
                 if (eventDomain && !msg.includes(`[${eventDomain}]`)) {
                     msg = `[${eventDomain}] ${msg}`;
                 }
-                // Suppress known benign warnings from ACME when using acme-dns-01-cli
                 if (event === 'warning' && typeof msg === 'string') {
                     if (/acme-dns-01-cli.*(incorrect function signatures|deprecated use of callbacks)/i.test(msg)) return;
                     if (/dns-01 challenge plugin should have zones/i.test(msg)) return;
@@ -804,8 +954,6 @@ class Roster {
                 else log.info(msg);
             }
         };
-        // Keep a direct greenlock runtime handle so we can call get() explicitly under Bun
-        // before binding :443, avoiding invalid non-TLS responses on startup.
         const greenlockRuntime = GreenlockShim.create(greenlockOptions);
         const greenlock = Greenlock.init({
             ...greenlockOptions,
@@ -814,130 +962,22 @@ class Roster {
 
         return greenlock.ready(async glx => {
             const httpServer = glx.httpServer();
-
-            // Group sites by port
-            const sitesByPort = {};
-            for (const [hostKey, siteApp] of Object.entries(this.sites)) {
-                if (!hostKey.startsWith('www.')) {
-                    const { domain, port } = this.parseDomainWithPort(hostKey);
-                    if (!sitesByPort[port]) {
-                        sitesByPort[port] = {
-                            virtualServers: {},
-                            appHandlers: {}
-                        };
-                    }
-
-                    const virtualServer = this.createVirtualServer(domain);
-                    sitesByPort[port].virtualServers[domain] = virtualServer;
-                    this.domainServers[domain] = virtualServer;
-
-                    const appHandler = siteApp(virtualServer);
-                    sitesByPort[port].appHandlers[domain] = appHandler;
-                    if (!domain.startsWith('*.')) {
-                        sitesByPort[port].appHandlers[`www.${domain}`] = appHandler;
-                    }
-                }
-            }
-
             const bunTlsHotReloadHandlers = [];
 
-            // Create dispatcher for each port
-            const createDispatcher = (portData) => {
-                return (req, res) => {
-                    const host = req.headers.host || '';
-
-                    const hostWithoutPort = host.split(':')[0].toLowerCase();
-                    const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
-
-                    if (hostWithoutPort.startsWith('www.')) {
-                        res.writeHead(301, { Location: `https://${domain}${req.url}` });
-                        res.end();
-                        return;
-                    }
-
-                    const resolved = this.getHandlerForPortData(domain, portData);
-                    if (!resolved) {
-                        res.writeHead(404);
-                        res.end('Site not found');
-                        return;
-                    }
-                    const { virtualServer, appHandler } = resolved;
-
-                    if (virtualServer && virtualServer.requestListeners.length > 0) {
-                        virtualServer.fallbackHandler = appHandler;
-                        virtualServer.processRequest(req, res);
-                    } else if (appHandler) {
-                        appHandler(req, res);
-                    } else {
-                        res.writeHead(404);
-                        res.end('Site not found');
-                    }
-                };
-            };
-
             httpServer.listen(80, this.hostname, () => {
                 log.info('HTTP server listening on port 80');
             });
 
-            const createUpgradeHandler = (portData) => {
-                return (req, socket, head) => {
-                    const host = req.headers.host || '';
-                    const hostWithoutPort = host.split(':')[0].toLowerCase();
-                    const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
-
-                    const resolved = this.getHandlerForPortData(domain, portData);
-                    if (resolved && resolved.virtualServer) {
-                        resolved.virtualServer.processUpgrade(req, socket, head);
-                    } else {
-                        socket.destroy();
-                    }
-                };
-            };
-
-            // Handle different port types
-            for (const [port, portData] of Object.entries(sitesByPort)) {
+            for (const [port, portData] of Object.entries(this._sitesByPort)) {
                 const portNum = parseInt(port);
-                const dispatcher = createDispatcher(portData);
-                const upgradeHandler = createUpgradeHandler(portData);
-                const greenlockStorePath = this.greenlockStorePath;
-                const normalizeHostInput = (value) => {
-                    if (typeof value === 'string') return value;
-                    if (!value || typeof value !== 'object') return '';
-                    if (typeof value.servername === 'string') return value.servername;
-                    if (typeof value.hostname === 'string') return value.hostname;
-                    if (typeof value.subject === 'string') return value.subject;
-                    return '';
-                };
-                const loadCert = (subjectDir) => {
-                    const normalizedSubject = normalizeHostInput(subjectDir).trim().toLowerCase();
-                    if (!normalizedSubject) return null;
-                    const certPath = path.join(greenlockStorePath, 'live', normalizedSubject);
-                    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)) {
-                        return {
-                            key: fs.readFileSync(keyPath, 'utf8'),
-                            cert: fs.readFileSync(certFilePath, 'utf8') + fs.readFileSync(chainPath, 'utf8')
-                        };
-                    }
-                    return null;
-                };
-                const resolvePemsForServername = (servername) => {
-                    const host = normalizeHostInput(servername).trim().toLowerCase();
-                    if (!host) return null;
-                    const candidates = buildCertLookupCandidates(host);
-                    for (const candidate of candidates) {
-                        const pems = loadCert(candidate);
-                        if (pems) return pems;
-                    }
-                    return null;
-                };
+                const dispatcher = this._createDispatcher(portData);
+                const upgradeHandler = this._createUpgradeHandler(portData);
+
                 const issueAndReloadPemsForServername = async (servername) => {
-                    const host = normalizeHostInput(servername).trim().toLowerCase();
+                    const host = this._normalizeHostInput(servername).trim().toLowerCase();
                     if (!host) return null;
 
-                    let pems = resolvePemsForServername(host);
+                    let pems = this._resolvePemsForServername(host);
                     if (pems) return pems;
 
                     try {
@@ -946,11 +986,9 @@ class Roster {
                         log.warn(`⚠️  Greenlock issuance failed for ${host}: ${error?.message || error}`);
                     }
 
-                    pems = resolvePemsForServername(host);
+                    pems = this._resolvePemsForServername(host);
                     if (pems) return pems;
 
-                    // For wildcard zones, try a valid subdomain bootstrap host so Greenlock can
-                    // resolve the wildcard site without relying on invalid "*.domain" servername input.
                     const wildcardSubject = wildcardSubjectForHost(host);
                     const zone = wildcardSubject ? wildcardRoot(wildcardSubject) : null;
                     if (zone) {
@@ -960,11 +998,12 @@ class Roster {
                         } catch (error) {
                             log.warn(`⚠️  Greenlock wildcard bootstrap failed for ${bootstrapHost}: ${error?.message || error}`);
                         }
-                        pems = resolvePemsForServername(host);
+                        pems = this._resolvePemsForServername(host);
                     }
 
                     return pems;
                 };
+
                 const ensureBunDefaultPems = async (primaryDomain) => {
                     let pems = await issueAndReloadPemsForServername(primaryDomain);
 
@@ -974,7 +1013,7 @@ class Roster {
 
                     if (pems && needsWildcard && !certCoversName(pems.cert, `*.${primaryDomain}`)) {
                         log.warn(`⚠️  Existing cert for ${primaryDomain} lacks *.${primaryDomain} SAN — clearing stale cert for combined re-issuance`);
-                        const certDir = path.join(greenlockStorePath, 'live', primaryDomain);
+                        const certDir = path.join(this.greenlockStorePath, 'live', primaryDomain);
                         try { fs.rmSync(certDir, { recursive: true, force: true }); } catch {}
                         pems = null;
                     }
@@ -989,7 +1028,7 @@ class Roster {
                         log.error(`❌ Failed to obtain certificate for ${certSubject} under Bun:`, error?.message || error);
                     }
 
-                    pems = resolvePemsForServername(primaryDomain);
+                    pems = this._resolvePemsForServername(primaryDomain);
                     if (pems) return pems;
 
                     throw new Error(
@@ -999,15 +1038,11 @@ class Roster {
                 };
 
                 if (portNum === this.defaultPort) {
-                    // Bun has known gaps around SNICallback compatibility.
-                    // Fallback to static cert loading for the primary domain on default HTTPS port.
                     const tlsOpts = { minVersion: this.tlsMinVersion, maxVersion: this.tlsMaxVersion };
                     let httpsServer;
 
                     if (isBunRuntime) {
                         const primaryDomain = Object.keys(portData.virtualServers)[0];
-                        // Under Bun, avoid glx.httpsServer fallback (may serve invalid TLS on :443).
-                        // Require concrete PEM files and create native https server directly.
                         let defaultPems = await ensureBunDefaultPems(primaryDomain);
                         httpsServer = https.createServer({
                             ...tlsOpts,
@@ -1043,21 +1078,18 @@ class Roster {
                     }
 
                     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}`);
                     });
                 } else {
-                    // Create HTTPS server for custom ports using Greenlock certificates
                     const httpsOptions = {
                         minVersion: this.tlsMinVersion,
                         maxVersion: this.tlsMaxVersion,
                         SNICallback: (servername, callback) => {
                             try {
-                                const pems = resolvePemsForServername(servername);
+                                const pems = this._resolvePemsForServername(servername);
                                 if (pems) {
                                     callback(null, tls.createSecureContext({ key: pems.key, cert: pems.cert }));
                                 } else {
@@ -1070,8 +1102,6 @@ class Roster {
                     };
 
                     const httpsServer = https.createServer(httpsOptions, dispatcher);
-
-                    // Handle WebSocket upgrade events
                     httpsServer.on('upgrade', upgradeHandler);
 
                     httpsServer.on('error', (error) => {
@@ -1079,7 +1109,6 @@ class Roster {
                     });
 
                     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);
                         }
@@ -1103,7 +1132,7 @@ class Roster {
                     : 30000;
                 const maxAttempts = Number.isFinite(Number(process.env.ROSTER_BUN_WILDCARD_PREWARM_MAX_ATTEMPTS))
                     ? Math.max(0, Number(process.env.ROSTER_BUN_WILDCARD_PREWARM_MAX_ATTEMPTS))
-                    : 0; // 0 = retry forever
+                    : 0;
 
                 for (const zone of this.wildcardZones) {
                     const bootstrapHost = `bun-bootstrap.${zone}`;
@@ -1112,7 +1141,6 @@ class Roster {
                             log.warn(`⚠️  Bun runtime detected: prewarming wildcard certificate via ${bootstrapHost} (attempt ${attempt})`);
                             let reloaded = false;
                             for (const reloadTls of bunTlsHotReloadHandlers) {
-                                // Trigger issuance + immediately hot-reload default TLS context when ready.
                                 reloaded = (await reloadTls(bootstrapHost, `prewarm ${bootstrapHost} attempt ${attempt}`)) || reloaded;
                             }
                             if (!reloaded) {
@@ -1131,7 +1159,6 @@ class Roster {
                         }
                     };
 
-                    // Background prewarm + retries so HTTPS startup is not blocked by DNS propagation timing.
                     attemptPrewarm().catch(() => {});
                 }
             }

package/package.json

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

package/skills/roster-server/SKILL.md

@@ -123,6 +123,30 @@ roster.register('*.example.com:8080', handler);
 ### Pattern 5: Static Site (no code)
 Place only `index.html` (and assets) in `www/example.com/`. No `index.js` needed. RosterServer serves files with path-traversal protection; `/` → `index.html`, other paths → file or 404. Implemented in `lib/static-site-handler.js` and `lib/resolve-site-app.js`.
 
+### Pattern 6: Cluster-Friendly (external server)
+```javascript
+const https = require('https');
+const Roster = require('roster-server');
+
+const roster = new Roster({
+    email: 'admin@example.com',
+    wwwPath: '/srv/www',
+    greenlockStorePath: '/srv/greenlock.d'
+});
+
+await roster.init();
+
+const server = https.createServer({ SNICallback: roster.sniCallback() });
+roster.attach(server);
+
+// Master passes connections — worker never calls listen()
+process.on('message', (msg, connection) => {
+    if (msg === 'sticky-session:connection') {
+        server.emit('connection', connection);
+    }
+});
+```
+
 ## Key Configuration Options
 
 ```javascript
@@ -137,7 +161,7 @@ new Roster({
     staging: false,                  // true = Let's Encrypt staging
     
     // Server
-    hostname: '0.0.0.0',
+    hostname: '::',
     port: 443,                       // Default HTTPS port (NOT 80!)
     
     // Local mode
@@ -153,7 +177,22 @@ new Roster({
 ## Core API
 
 ### `roster.start()`
-Loads sites, generates SSL config, starts servers. Returns `Promise<void>`.
+Loads sites, generates SSL config, starts servers. Returns `Promise<void>`. Calls `init()` internally.
+
+### `roster.init()`
+Loads sites, creates VirtualServers, prepares dispatchers — but creates **no servers** and calls **no `.listen()`**. Returns `Promise<Roster>`. Idempotent. Use this for cluster-friendly integration where an external manager owns the socket.
+
+### `roster.requestHandler(port?)`
+Returns `(req, res) => void` dispatcher for a port (defaults to `defaultPort`). Requires `init()` first. Handles Host-header routing, www→non-www redirects, wildcard matching.
+
+### `roster.upgradeHandler(port?)`
+Returns `(req, socket, head) => void` for WebSocket upgrade routing. Requires `init()` first.
+
+### `roster.sniCallback()`
+Returns `(servername, callback) => void` TLS SNI callback that resolves certs from `greenlockStorePath`. Production mode only. Requires `init()` first.
+
+### `roster.attach(server, { port }?)`
+Convenience: wires `requestHandler` + `upgradeHandler` onto an external `http.Server` or `https.Server`. Returns `this`. Requires `init()` first.
 
 ### `roster.register(domain, handler)`
 Manually register a domain handler. Domain can include port: `'api.com:8443'`. For wildcards use `'*.example.com'` or `'*.example.com:8080'`.

package/test/roster-server.test.js

@@ -718,3 +718,276 @@ describe('Roster generateConfigJson', () => {
         }
     });
 });
+
+describe('Roster init() (cluster-friendly API)', () => {
+    it('initializes without creating or listening on any server', async () => {
+        const roster = new Roster({
+            local: true,
+            minLocalPort: 19300,
+            maxLocalPort: 19309
+        });
+        roster.register('init-test.example', (server) => {
+            return (req, res) => { res.writeHead(200); res.end('ok'); };
+        });
+        await roster.init();
+        assert.strictEqual(roster._initialized, true);
+        assert.strictEqual(Object.keys(roster.portServers).length, 0);
+        assert.ok(roster._sitesByPort[443]);
+        assert.ok(roster.domainServers['init-test.example']);
+    });
+
+    it('is idempotent (calling init twice does not reinitialize)', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('idem.example', () => () => {});
+        await roster.init();
+        const firstSitesByPort = roster._sitesByPort;
+        await roster.init();
+        assert.strictEqual(roster._sitesByPort, firstSitesByPort);
+    });
+
+    it('start() still works after manual init()', async () => {
+        const roster = new Roster({
+            local: true,
+            minLocalPort: 19310,
+            maxLocalPort: 19319
+        });
+        roster.register('after-init.example', (server) => {
+            return (req, res) => { res.writeHead(200); res.end('after-init'); };
+        });
+        await roster.init();
+        await roster.start();
+        try {
+            const port = roster.domainPorts['after-init.example'];
+            assert.ok(typeof port === 'number');
+            await new Promise((r) => setTimeout(r, 50));
+            const result = await httpGet('localhost', port, '/');
+            assert.strictEqual(result.statusCode, 200);
+            assert.strictEqual(result.body, 'after-init');
+        } finally {
+            closePortServers(roster);
+        }
+    });
+});
+
+describe('Roster requestHandler() / upgradeHandler()', () => {
+    it('throws if called before init()', () => {
+        const roster = new Roster({ local: true });
+        assert.throws(() => roster.requestHandler(), /Call init\(\) before/);
+        assert.throws(() => roster.upgradeHandler(), /Call init\(\) before/);
+    });
+
+    it('returns a working request dispatcher after init()', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('handler-test.example', (server) => {
+            return (req, res) => { res.writeHead(200); res.end('dispatched'); };
+        });
+        await roster.init();
+
+        const handler = roster.requestHandler();
+        assert.strictEqual(typeof handler, 'function');
+
+        let statusCode, body;
+        const fakeRes = {
+            writeHead: (s) => { statusCode = s; },
+            end: (b) => { body = b; }
+        };
+        handler({ headers: { host: 'handler-test.example' }, url: '/' }, fakeRes);
+        assert.strictEqual(statusCode, 200);
+        assert.strictEqual(body, 'dispatched');
+    });
+
+    it('returns 404 dispatcher for unregistered port', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('port-test.example', () => () => {});
+        await roster.init();
+
+        const handler = roster.requestHandler(9999);
+        let statusCode;
+        const fakeRes = {
+            writeHead: (s) => { statusCode = s; },
+            end: () => {}
+        };
+        handler({ headers: { host: 'port-test.example' }, url: '/' }, fakeRes);
+        assert.strictEqual(statusCode, 404);
+    });
+
+    it('upgrade handler destroys socket for unknown host', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('upgrade-test.example', () => () => {});
+        await roster.init();
+
+        const handler = roster.upgradeHandler();
+        let destroyed = false;
+        const fakeSocket = { destroy: () => { destroyed = true; } };
+        handler({ headers: { host: 'unknown.example' }, url: '/' }, fakeSocket, Buffer.alloc(0));
+        assert.strictEqual(destroyed, true);
+    });
+
+    it('www redirect uses http:// protocol in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('redirect.example', (server) => {
+            return (req, res) => { res.writeHead(200); res.end('ok'); };
+        });
+        await roster.init();
+
+        const handler = roster.requestHandler();
+        let location;
+        const fakeRes = {
+            writeHead: (s, headers) => { location = headers?.Location; },
+            end: () => {}
+        };
+        handler({ headers: { host: 'www.redirect.example' }, url: '/path' }, fakeRes);
+        assert.ok(location);
+        assert.ok(location.startsWith('http://'), `Expected http:// redirect, got: ${location}`);
+    });
+
+    it('dispatches correctly for custom registered port via requestHandler(port)', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('api.ported.example:8443', () => {
+            return (req, res) => { res.writeHead(200); res.end('port-8443'); };
+        });
+        await roster.init();
+
+        const handler = roster.requestHandler(8443);
+        let statusCode;
+        let body;
+        const fakeRes = {
+            writeHead: (s) => { statusCode = s; },
+            end: (b) => { body = b; }
+        };
+        handler({ headers: { host: 'api.ported.example' }, url: '/' }, fakeRes);
+        assert.strictEqual(statusCode, 200);
+        assert.strictEqual(body, 'port-8443');
+    });
+
+    it('www redirect uses https:// protocol in production mode', async () => {
+        const roster = new Roster({ local: false });
+        roster.register('redirect-prod.example', () => {
+            return (req, res) => { res.writeHead(200); res.end('ok'); };
+        });
+        await roster.init();
+
+        const handler = roster.requestHandler();
+        let location;
+        const fakeRes = {
+            writeHead: (s, headers) => { location = headers?.Location; },
+            end: () => {}
+        };
+        handler({ headers: { host: 'www.redirect-prod.example' }, url: '/secure' }, fakeRes);
+        assert.ok(location);
+        assert.ok(location.startsWith('https://'), `Expected https:// redirect, got: ${location}`);
+    });
+});
+
+describe('Roster sniCallback()', () => {
+    it('throws if called before init()', () => {
+        const roster = new Roster({ local: false });
+        assert.throws(() => roster.sniCallback(), /Call init\(\) before/);
+    });
+
+    it('throws in local mode (no SNI in HTTP)', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('sni-local.example', () => () => {});
+        await roster.init();
+        assert.throws(() => roster.sniCallback(), /not available in local mode/);
+    });
+
+    it('returns a function after init() in production mode', async () => {
+        const roster = new Roster({ local: false });
+        roster.register('sni-prod.example', () => () => {});
+        await roster.init();
+        const cb = roster.sniCallback();
+        assert.strictEqual(typeof cb, 'function');
+    });
+});
+
+describe('Roster attach()', () => {
+    it('throws if called before init()', () => {
+        const roster = new Roster({ local: true });
+        const fakeServer = { on: () => {} };
+        assert.throws(() => roster.attach(fakeServer), /Call init\(\) before/);
+    });
+
+    it('wires request and upgrade listeners onto external server', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('attach-test.example', (server) => {
+            return (req, res) => { res.writeHead(200); res.end('attached'); };
+        });
+        await roster.init();
+
+        const listeners = {};
+        const fakeServer = {
+            on: (event, fn) => { listeners[event] = fn; }
+        };
+        const result = roster.attach(fakeServer);
+        assert.strictEqual(result, roster);
+        assert.strictEqual(typeof listeners['request'], 'function');
+        assert.strictEqual(typeof listeners['upgrade'], 'function');
+    });
+
+    it('uses provided port option when attaching', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('attach-443.example', () => (req, res) => { res.writeHead(200); res.end('on-443'); });
+        roster.register('attach-9443.example:9443', () => (req, res) => { res.writeHead(200); res.end('on-9443'); });
+        await roster.init();
+
+        const listeners = {};
+        const fakeServer = {
+            on: (event, fn) => { listeners[event] = fn; }
+        };
+        roster.attach(fakeServer, { port: 9443 });
+
+        let statusCode;
+        let body;
+        const fakeRes = {
+            writeHead: (s) => { statusCode = s; },
+            end: (b) => { body = b; }
+        };
+        listeners.request({ headers: { host: 'attach-9443.example' }, url: '/' }, fakeRes);
+        assert.strictEqual(statusCode, 200);
+        assert.strictEqual(body, 'on-9443');
+    });
+
+    it('attached handler dispatches requests correctly', async () => {
+        const roster = new Roster({
+            local: true,
+            minLocalPort: 19400,
+            maxLocalPort: 19409
+        });
+        roster.register('attach-http.example', (server) => {
+            return (req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('from-attach');
+            };
+        });
+        await roster.init();
+
+        const server = http.createServer();
+        roster.attach(server);
+
+        const port = 19400;
+        await new Promise((resolve, reject) => {
+            server.listen(port, 'localhost', resolve);
+            server.on('error', reject);
+        });
+        try {
+            await new Promise((r) => setTimeout(r, 50));
+            const result = await new Promise((resolve, reject) => {
+                const req = http.get(
+                    { host: 'localhost', port, path: '/', headers: { host: 'attach-http.example' } },
+                    (res) => {
+                        let body = '';
+                        res.on('data', (chunk) => { body += chunk; });
+                        res.on('end', () => resolve({ statusCode: res.statusCode, body }));
+                    }
+                );
+                req.on('error', reject);
+                req.setTimeout(2000, () => { req.destroy(); reject(new Error('timeout')); });
+            });
+            assert.strictEqual(result.statusCode, 200);
+            assert.strictEqual(result.body, 'from-attach');
+        } finally {
+            server.close();
+        }
+    });
+});