roster-server 2.4.0 → 2.4.2

package/README.md

@@ -350,61 +350,70 @@ console.log(customRoster.getUrl('api.example.com'));
 // → https://api.example.com:8443
 ```
 
-## 🔀 External Clusters / Sticky Runtimes
+## 🔌 Cluster-Friendly API (init / attach)
 
-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()`.
+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.
 
-### Ownership Model
+### How It Works
 
-- `roster.start()` = Roster-owned HTTP/HTTPS lifecycle (Greenlock, listeners, ports)
-- `roster.buildRuntimeRouter()` = externally-owned server lifecycle (you call `listen`)
+`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`.
 
-### Minimal Worker Example
+### Quick Example: Sticky-Session Worker
 
 ```javascript
-import http from 'http';
+import https from 'https';
 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');
-    };
+const roster = new Roster({
+    email: 'admin@example.com',
+    wwwPath: '/srv/www',
+    greenlockStorePath: '/srv/greenlock.d'
 });
 
-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');
-    };
-});
+await roster.init();
 
-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
+// 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);
+    }
 });
+```
 
-router.attach(server);
+### API Reference
 
-// External runtime controls binding/lifecycle:
-server.listen(3000);
-```
+#### `roster.init()` → `Promise<Roster>`
 
-### API Notes
+Loads sites, generates SSL config (production), creates VirtualServers and initializes handlers. Idempotent — calling it twice is safe. Returns `this` for chaining.
 
-- `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
+#### `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
 

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()
+```