roster-server 2.4.0 → 2.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "roster-server",
-    "version": "2.4.0",
+    "version": "2.4.2",
     "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: false
+    local: true
 });
 
 roster.start();
@@ -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,38 +177,25 @@ new Roster({
 ## Core API
 
 ### `roster.start()`
-Loads sites, generates SSL config, starts servers. Returns `Promise<void>`.
-
-### `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'`.
+Loads sites, generates SSL config, starts servers. Returns `Promise<void>`. Calls `init()` internally.
 
-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.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.prepareSites(options?)`
-Builds VirtualServer + app handler wiring without listening. Useful when you need Roster routing internals but your runtime owns `server.listen(...)`.
+### `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.
 
-Options:
-- `targetPort` (optional): only prepare one port, defaults to all registered ports
+### `roster.upgradeHandler(port?)`
+Returns `(req, socket, head) => void` for WebSocket upgrade routing. Requires `init()` first.
 
-Returns:
-- `{ sitesByPort }` with `virtualServers` and `appHandlers` per port
+### `roster.sniCallback()`
+Returns `(servername, callback) => void` TLS SNI callback that resolves certs from `greenlockStorePath`. Production mode only. Requires `init()` first.
 
-### `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.
+### `roster.attach(server, { port }?)`
+Convenience: wires `requestHandler` + `upgradeHandler` onto an external `http.Server` or `https.Server`. Returns `this`. Requires `init()` first.
 
-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.register(domain, handler)`
+Manually register a domain handler. Domain can include port: `'api.com:8443'`. For wildcards use `'*.example.com'` or `'*.example.com:8080'`.
 
 ### `roster.getUrl(domain)`
 Get environment-aware URL:
@@ -200,12 +211,6 @@ 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
@@ -276,30 +281,6 @@ 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';
@@ -332,4 +313,3 @@ 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,7 +6,6 @@ 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,
@@ -40,20 +39,6 @@ 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');
@@ -350,21 +335,6 @@ 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)', () => {
@@ -445,111 +415,6 @@ 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({
@@ -594,21 +459,6 @@ 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', () => {
@@ -868,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();
+        }
+    });
+});

package/docs/decisions/external-runtime-router-api.md

@@ -1,12 +0,0 @@
----
-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/patterns/roster-dispatch-reuse.md

@@ -1,12 +0,0 @@
----
-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.