roster-server 2.3.16 → 2.4.0

package/README.md

@@ -350,6 +350,62 @@ console.log(customRoster.getUrl('api.example.com'));
 // → https://api.example.com:8443
 ```
 
+## 🔀 External Clusters / Sticky Runtimes
+
+If your runtime already owns `server.listen(...)` (for example sticky-session workers in Node cluster, PM2, or custom LB workers), you can still use Roster's domain routing, virtual servers, and Socket.IO-compatible upgrade flow without calling `roster.start()`.
+
+### Ownership Model
+
+- `roster.start()` = Roster-owned HTTP/HTTPS lifecycle (Greenlock, listeners, ports)
+- `roster.buildRuntimeRouter()` = externally-owned server lifecycle (you call `listen`)
+
+### Minimal Worker Example
+
+```javascript
+import http from 'http';
+import Roster from 'roster-server';
+
+const roster = new Roster({ local: false, port: 443 });
+
+roster.register('example.com', (virtualServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('hello from example.com');
+    };
+});
+
+roster.register('*.example.com', (virtualServer) => {
+    // Socket.IO (or raw WS) can bind to virtualServer "upgrade" listeners here.
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('hello from wildcard');
+    };
+});
+
+const server = http.createServer();
+const router = roster.buildRuntimeRouter({
+    targetPort: 443, // optional, defaults to roster.defaultPort
+    hostAliases: {
+        localhost: 'example.com'
+    }, // optional map, or callback: (host) => mappedHost
+    allowWwwRedirect: true // optional, defaults to true
+});
+
+router.attach(server);
+
+// External runtime controls binding/lifecycle:
+server.listen(3000);
+```
+
+### API Notes
+
+- `roster.prepareSites(options?)`: builds virtual servers + app handlers without listening.
+- `roster.buildRuntimeRouter(options?)` returns:
+  - `attach(server)` to bind `request` + `upgrade`
+  - `dispatchRequest(req, res)` for manual request dispatch
+  - `dispatchUpgrade(req, socket, head)` for manual upgrade dispatch
+  - `portData` + `diagnostics` snapshots for debugging
+
 ## 🧂 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/docs/decisions/external-runtime-router-api.md

@@ -0,0 +1,12 @@
+---
+id: zezv04723c
+type: decision
+title: 'Decision: External runtime router API'
+created: '2026-03-20 16:17:36'
+---
+# Decision: External runtime router API
+
+**What**: Added `buildRuntimeRouter(options)` and `prepareSites(options)` so cluster/sticky runtimes can use Roster host dispatch + VirtualServer + upgrade routing without calling `start()`.
+**Where**: `index.js` (`prepareSites`, `buildRuntimeRouter`, extracted request/upgrade dispatcher helpers).
+**Why**: Existing consumers had to duplicate internal `start()` dispatcher logic to integrate with externally-managed `listen()` lifecycles.
+**Alternatives rejected**: Auto-starting hidden servers from `buildRuntimeRouter` (rejected to keep ownership explicit and avoid side effects).

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/docs/patterns/roster-dispatch-reuse.md

@@ -0,0 +1,12 @@
+---
+id: jgoo52m5h0
+type: pattern
+title: 'Pattern: Reusable host dispatch internals'
+created: '2026-03-20 16:17:36'
+---
+# Pattern: Reusable host dispatch internals
+
+**What**: Extracted shared host routing pieces from `start()` into reusable methods (`resolveRoutedHost`, `createPortRequestDispatcher`, `createPortUpgradeDispatcher`, `prepareSites`).
+**Where used**: `start()` production path and new `buildRuntimeRouter()` path.
+**When to apply**: Any future feature needing Roster host routing in non-Greenlock server lifecycles or custom server ownership.
+**Notes**: `register()` now supports `{ silent, skipDomainBookkeeping }` for worker-safe registration and reduced duplicate log noise.

package/index.js

@@ -109,6 +109,19 @@ function parseBooleanFlag(value, fallback = false) {
     return fallback;
 }
 
+function 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 '';
+}
+
+function hostWithoutPort(value) {
+    return normalizeHostInput(value).split(':')[0].trim().toLowerCase();
+}
+
 function normalizeDomainForLocalHost(domain) {
     return (domain || '').trim().toLowerCase().replace(/^www\./, '');
 }
@@ -549,13 +562,21 @@ class Roster {
         }
     }
 
-    register(domainString, requestHandler) {
+    /**
+     * Register a domain handler.
+     * @param {string} domainString Domain, optionally with :port.
+     * @param {(virtualServer: VirtualServer) => Function} requestHandler Site app factory.
+     * @param {{ silent?: boolean, skipDomainBookkeeping?: boolean }} [options]
+     * @returns {Roster}
+     */
+    register(domainString, requestHandler, options = {}) {
         if (!domainString) {
             throw new Error('Domain is required');
         }
         if (typeof requestHandler !== 'function') {
             throw new Error('requestHandler must be a function');
         }
+        const { silent = false, skipDomainBookkeeping = false } = options || {};
 
         const { domain, port } = this.parseDomainWithPort(domainString);
 
@@ -565,11 +586,13 @@ class Roster {
                 return this;
             }
             const domainKey = port === this.defaultPort ? domain : `${domain}:${port}`;
-            this.domains.push(domain);
+            if (!skipDomainBookkeeping) this.domains.push(domain);
             this.sites[domainKey] = requestHandler;
             const root = wildcardRoot(domain);
             if (root) this.wildcardZones.add(root);
-            log.info(`(✔) Registered wildcard site: ${domain}${port !== this.defaultPort ? ':' + port : ''}`);
+            if (!silent) {
+                log.info(`(✔) Registered wildcard site: ${domain}${port !== this.defaultPort ? ':' + port : ''}`);
+            }
             return this;
         }
 
@@ -578,13 +601,17 @@ class Roster {
             domainEntries.push(`www.${domain}`);
         }
 
-        this.domains.push(...domainEntries);
+        if (!skipDomainBookkeeping) {
+            this.domains.push(...domainEntries);
+        }
         domainEntries.forEach(d => {
             const domainKey = port === this.defaultPort ? d : `${d}:${port}`;
             this.sites[domainKey] = requestHandler;
         });
 
-        log.info(`(✔) Registered site: ${domain}${port !== this.defaultPort ? ':' + port : ''}`);
+        if (!silent) {
+            log.info(`(✔) Registered site: ${domain}${port !== this.defaultPort ? ':' + port : ''}`);
+        }
         return this;
     }
 
@@ -628,6 +655,151 @@ class Roster {
         return new VirtualServer(domain);
     }
 
+    resolveRoutedHost(rawHost, hostAliases) {
+        const normalizedHost = hostWithoutPort(rawHost);
+        if (!normalizedHost) {
+            return {
+                normalizedHost: '',
+                routedHost: '',
+                isWww: false
+            };
+        }
+
+        let aliasedHost = normalizedHost;
+        if (typeof hostAliases === 'function') {
+            const mapped = hostAliases(normalizedHost);
+            if (mapped) aliasedHost = hostWithoutPort(mapped);
+        } else if (hostAliases && typeof hostAliases === 'object') {
+            const mapped = hostAliases[normalizedHost];
+            if (mapped) aliasedHost = hostWithoutPort(mapped);
+        }
+
+        const isWww = aliasedHost.startsWith('www.');
+        return {
+            normalizedHost: aliasedHost,
+            routedHost: isWww ? aliasedHost.slice(4) : aliasedHost,
+            isWww
+        };
+    }
+
+    createPortRequestDispatcher(portData, options = {}) {
+        const {
+            hostAliases,
+            allowWwwRedirect = true
+        } = options;
+
+        return (req, res) => {
+            const { normalizedHost, routedHost, isWww } = this.resolveRoutedHost(req.headers.host || '', hostAliases);
+
+            if (allowWwwRedirect && isWww) {
+                res.writeHead(301, { Location: `https://${routedHost}${req.url}` });
+                res.end();
+                return;
+            }
+
+            const resolved = this.getHandlerForPortData(routedHost, 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');
+            }
+        };
+    }
+
+    createPortUpgradeDispatcher(portData, options = {}) {
+        const { hostAliases } = options;
+        return (req, socket, head) => {
+            const { routedHost } = this.resolveRoutedHost(req.headers.host || '', hostAliases);
+            const resolved = this.getHandlerForPortData(routedHost, portData);
+            if (resolved && resolved.virtualServer) {
+                resolved.virtualServer.processUpgrade(req, socket, head);
+            } else {
+                socket.destroy();
+            }
+        };
+    }
+
+    /**
+     * Prepare port-based virtual server/app handler data without listening.
+     * @param {{ targetPort?: number }} [options]
+     * @returns {{ sitesByPort: Record<number, { virtualServers: Record<string, VirtualServer>, appHandlers: Record<string, Function> }> }}
+     */
+    prepareSites(options = {}) {
+        const { targetPort } = options;
+        const sitesByPort = {};
+
+        for (const [hostKey, siteApp] of Object.entries(this.sites)) {
+            if (hostKey.startsWith('www.')) continue;
+
+            const { domain, port } = this.parseDomainWithPort(hostKey);
+            if (targetPort !== undefined && port !== targetPort) continue;
+
+            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;
+            }
+        }
+
+        return { sitesByPort };
+    }
+
+    /**
+     * Build a router that can be attached to externally managed servers (e.g. sticky-session workers).
+     * This does not call listen() and does not boot Greenlock.
+     * @param {{ targetPort?: number, hostAliases?: Record<string, string>|((host: string) => string|undefined), allowWwwRedirect?: boolean }} [options]
+     * @returns {{ attach: (server: import('http').Server) => import('http').Server, dispatchRequest: Function, dispatchUpgrade: Function, portData: { virtualServers: Record<string, VirtualServer>, appHandlers: Record<string, Function> }, diagnostics: { targetPort: number, hosts: string[], virtualServers: string[] } }}
+     */
+    buildRuntimeRouter(options = {}) {
+        const {
+            targetPort = this.defaultPort,
+            hostAliases,
+            allowWwwRedirect = true
+        } = options;
+        const { sitesByPort } = this.prepareSites({ targetPort });
+        const portData = sitesByPort[targetPort] || { virtualServers: {}, appHandlers: {} };
+        const dispatchRequest = this.createPortRequestDispatcher(portData, { hostAliases, allowWwwRedirect });
+        const dispatchUpgrade = this.createPortUpgradeDispatcher(portData, { hostAliases });
+
+        return {
+            attach: (server) => {
+                server.on('request', dispatchRequest);
+                server.on('upgrade', dispatchUpgrade);
+                return server;
+            },
+            dispatchRequest,
+            dispatchUpgrade,
+            portData,
+            diagnostics: {
+                targetPort,
+                hosts: Object.keys(portData.appHandlers),
+                virtualServers: Object.keys(portData.virtualServers)
+            }
+        };
+    }
+
     // Assign port to domain, detecting collisions with already assigned ports
     assignPortToDomain(domain) {
         let port = domainToPort(domain, this.minLocalPort, this.maxLocalPort);
@@ -814,100 +986,20 @@ 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 { sitesByPort } = this.prepareSites();
 
             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)) {
                 const portNum = parseInt(port);
-                const dispatcher = createDispatcher(portData);
-                const upgradeHandler = createUpgradeHandler(portData);
+                const dispatcher = this.createPortRequestDispatcher(portData);
+                const upgradeHandler = this.createPortUpgradeDispatcher(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;

package/package.json

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

package/skills/roster-server/SKILL.md

@@ -13,7 +13,7 @@ const roster = new Roster({
     email: 'admin@example.com',
     wwwPath: '/srv/www',
     greenlockStorePath: '/srv/greenlock.d',
-    local: true
+    local: false
 });
 
 roster.start();
@@ -155,9 +155,37 @@ new Roster({
 ### `roster.start()`
 Loads sites, generates SSL config, starts servers. Returns `Promise<void>`.
 
-### `roster.register(domain, handler)`
+### `roster.register(domain, handler, options?)`
 Manually register a domain handler. Domain can include port: `'api.com:8443'`. For wildcards use `'*.example.com'` or `'*.example.com:8080'`.
 
+Optional registration options:
+- `silent: true` suppresses registration logs (useful in clustered workers)
+- `skipDomainBookkeeping: true` avoids `domains[]` side effects when external runtime owns registration/state
+
+### `roster.prepareSites(options?)`
+Builds VirtualServer + app handler wiring without listening. Useful when you need Roster routing internals but your runtime owns `server.listen(...)`.
+
+Options:
+- `targetPort` (optional): only prepare one port, defaults to all registered ports
+
+Returns:
+- `{ sitesByPort }` with `virtualServers` and `appHandlers` per port
+
+### `roster.buildRuntimeRouter(options?)`
+Build a cluster/sticky-runtime-compatible router for externally managed HTTP servers. This API does **not** call `listen()` and does **not** boot Greenlock.
+
+Options:
+- `targetPort` (optional): defaults to `roster.defaultPort`
+- `hostAliases` (optional): object map or callback `(host) => mappedHost`
+- `allowWwwRedirect` (optional, default `true`)
+
+Returns:
+- `attach(server)` binds request + upgrade handlers to an existing server
+- `dispatchRequest(req, res)` pure request dispatcher
+- `dispatchUpgrade(req, socket, head)` pure upgrade dispatcher
+- `portData` routing snapshot
+- `diagnostics` metadata (`targetPort`, hosts, virtual servers)
+
 ### `roster.getUrl(domain)`
 Get environment-aware URL:
 - Local mode: `http://localhost:{port}`
@@ -172,6 +200,12 @@ Get environment-aware URL:
 3. Looks up domain → Gets `VirtualServer` instance
 4. Routes to handler via `virtualServer.processRequest(req, res)`
 
+### External Runtime Flow (cluster/sticky workers)
+1. Register handlers with `roster.register(...)`
+2. Build router via `roster.buildRuntimeRouter(...)`
+3. Attach to externally created server: `router.attach(server)`
+4. External runtime calls `server.listen(...)`
+
 ### VirtualServer Architecture
 Each domain gets isolated server instance that simulates `http.Server`:
 - Captures `request` and `upgrade` event listeners
@@ -242,6 +276,30 @@ roster.register('test.local', (server) => {
 roster.start();
 ```
 
+### External Cluster/Sticky Worker
+```javascript
+const http = require('http');
+const Roster = require('roster-server');
+
+const roster = new Roster({ local: false, port: 443 });
+
+roster.register('example.com', (virtualServer) => {
+    return (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('worker response');
+    };
+}, { silent: true });
+
+const server = http.createServer();
+const router = roster.buildRuntimeRouter({
+    targetPort: 443,
+    hostAliases: { localhost: 'example.com' }
+});
+
+router.attach(server);
+server.listen(3000); // owned by external runtime
+```
+
 ### Environment-Aware Configuration
 ```javascript
 const isProduction = process.env.NODE_ENV === 'production';
@@ -274,3 +332,4 @@ When implementing RosterServer:
 - [ ] Use `roster.getUrl(domain)` for environment-aware URLs
 - [ ] Handle Socket.IO paths correctly in returned handler
 - [ ] Implement error handling in handlers
+- [ ] For sticky/cluster runtimes, use `buildRuntimeRouter().attach(server)` instead of `start()`

package/test/roster-server.test.js

@@ -6,6 +6,7 @@ const path = require('path');
 const fs = require('fs');
 const http = require('http');
 const os = require('os');
+const rosterLog = require('lemonlog')('roster');
 const Roster = require('../index.js');
 const {
     wildcardRoot,
@@ -39,6 +40,20 @@ function httpGet(host, port, pathname = '/') {
     });
 }
 
+async function withPatchedInfoLogger(fn) {
+    const originalInfo = rosterLog.info;
+    const messages = [];
+    rosterLog.info = (...args) => {
+        messages.push(args.map((value) => String(value)).join(' '));
+    };
+    try {
+        await fn();
+    } finally {
+        rosterLog.info = originalInfo;
+    }
+    return messages;
+}
+
 describe('wildcardRoot', () => {
     it('returns root domain for *.example.com', () => {
         assert.strictEqual(wildcardRoot('*.example.com'), 'example.com');
@@ -335,6 +350,21 @@ describe('Roster', () => {
             assert.strictEqual(roster.sites['api.example.com'], handler);
             assert.strictEqual(roster.sites['www.api.example.com'], undefined);
         });
+        it('skipDomainBookkeeping avoids domain list side effects', () => {
+            const roster = new Roster({ local: true });
+            const handler = () => {};
+            roster.register('bookkeep.example', handler, { skipDomainBookkeeping: true });
+            assert.strictEqual(roster.sites['bookkeep.example'], handler);
+            assert.strictEqual(roster.sites['www.bookkeep.example'], handler);
+            assert.deepStrictEqual(roster.domains, []);
+        });
+        it('silent register suppresses registration logs', async () => {
+            const roster = new Roster({ local: true });
+            const messages = await withPatchedInfoLogger(async () => {
+                roster.register('silent.example', () => {}, { silent: true });
+            });
+            assert.strictEqual(messages.some((line) => line.includes('Registered site: silent.example')), false);
+        });
     });
 
     describe('getUrl (exact domain)', () => {
@@ -415,6 +445,111 @@ describe('Roster', () => {
     });
 });
 
+describe('Roster buildRuntimeRouter', () => {
+    it('attaches to external HTTP server and dispatches exact + wildcard hosts', async () => {
+        const roster = new Roster({ local: true, hostname: 'localhost' });
+        roster.register('example.com', () => (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('exact');
+        });
+        roster.register('*.wild.example', () => (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('wild');
+        });
+
+        const server = http.createServer();
+        const router = roster.buildRuntimeRouter({ targetPort: roster.defaultPort });
+        router.attach(server);
+
+        await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+        const { port } = server.address();
+        try {
+            const exact = await new Promise((resolve, reject) => {
+                const req = http.request({
+                    host: '127.0.0.1',
+                    port,
+                    path: '/',
+                    method: 'GET',
+                    headers: { host: 'example.com' }
+                }, (res) => {
+                    let body = '';
+                    res.on('data', (chunk) => { body += chunk; });
+                    res.on('end', () => resolve({ statusCode: res.statusCode, body }));
+                });
+                req.on('error', reject);
+                req.end();
+            });
+            assert.strictEqual(exact.statusCode, 200);
+            assert.strictEqual(exact.body, 'exact');
+
+            const wildcard = await new Promise((resolve, reject) => {
+                const req = http.request({
+                    host: '127.0.0.1',
+                    port,
+                    path: '/',
+                    method: 'GET',
+                    headers: { host: 'api.wild.example' }
+                }, (res) => {
+                    let body = '';
+                    res.on('data', (chunk) => { body += chunk; });
+                    res.on('end', () => resolve({ statusCode: res.statusCode, body }));
+                });
+                req.on('error', reject);
+                req.end();
+            });
+            assert.strictEqual(wildcard.statusCode, 200);
+            assert.strictEqual(wildcard.body, 'wild');
+        } finally {
+            await new Promise((resolve) => server.close(resolve));
+        }
+    });
+
+    it('dispatchUpgrade reaches virtual server upgrade listeners', () => {
+        const roster = new Roster({ local: true });
+        let upgraded = false;
+        roster.register('sio.example.com', (virtualServer) => {
+            virtualServer.on('upgrade', () => {
+                upgraded = true;
+            });
+            return () => {};
+        });
+
+        const router = roster.buildRuntimeRouter();
+        const socket = {
+            destroyed: false,
+            destroy() {
+                this.destroyed = true;
+            }
+        };
+        router.dispatchUpgrade(
+            { headers: { host: 'sio.example.com' }, url: '/socket.io/' },
+            socket,
+            Buffer.alloc(0)
+        );
+
+        assert.strictEqual(upgraded, true);
+        assert.strictEqual(socket.destroyed, false);
+    });
+
+    it('buildRuntimeRouter itself does not call listen', () => {
+        const roster = new Roster({ local: true });
+        roster.register('nolisten.example', () => () => {});
+
+        let listenCalled = false;
+        const originalListen = http.Server.prototype.listen;
+        http.Server.prototype.listen = function (...args) {
+            listenCalled = true;
+            return originalListen.apply(this, args);
+        };
+        try {
+            roster.buildRuntimeRouter();
+        } finally {
+            http.Server.prototype.listen = originalListen;
+        }
+        assert.strictEqual(listenCalled, false);
+    });
+});
+
 describe('Roster local mode (local: true)', () => {
     it('starts HTTP server and responds for registered domain', async () => {
         const roster = new Roster({
@@ -459,6 +594,21 @@ describe('Roster local mode (local: true)', () => {
             closePortServers(roster);
         }
     });
+    it('start local mode keeps subdomain localhost mapping', async () => {
+        const roster = new Roster({
+            local: true,
+            minLocalPort: 19110,
+            maxLocalPort: 19119
+        });
+        roster.register('api.logtest.example', () => () => {});
+        await roster.start();
+        try {
+            const localUrl = roster.getUrl('api.logtest.example');
+            assert.ok(localUrl && localUrl.startsWith('http://api.localhost:'));
+        } finally {
+            closePortServers(roster);
+        }
+    });
 });
 
 describe('Roster loadSites', () => {