roster-server 2.4.0 → 2.4.4

package/.greenlockrc

@@ -0,0 +1 @@
+{"configDir":"/Users/martinclasen/Stuff/greenlock.d"}

package/README.md

@@ -247,6 +247,8 @@ When creating a new `RosterServer` instance, you can pass the following options:
 - `greenlockStorePath` (string): Directory for Greenlock configuration.
 - `dnsChallenge` (object|false): Optional override for wildcard DNS-01 challenge config. Default is `acme-dns-01-cli` wrapper with `propagationDelay: 120000`, `autoContinue: false`, and `dryRunDelay: 120000`. Manual mode still works, but you can enable automatic Linode DNS API mode by setting `ROSTER_DNS_PROVIDER=linode` and `LINODE_API_KEY`. In automatic mode, Roster creates/removes TXT records itself and still polls public resolvers every 15s before continuing. Set `false` to disable DNS challenge. You can pass `{ module: '...', propagationDelay: 180000 }` to tune DNS wait time (ms). For Greenlock dry-runs (`_greenlock-dryrun-*`), delay defaults to `dryRunDelay` (same as `propagationDelay` unless overridden with `dnsChallenge.dryRunDelay` or env `ROSTER_DNS_DRYRUN_DELAY_MS`). When wildcard sites are present, Roster creates a separate wildcard certificate (`*.example.com`) that uses `dns-01`, while apex/www stay on the regular certificate flow (typically `http-01`), reducing manual TXT records.
 - `staging` (boolean): Set to `true` to use Let's Encrypt's staging environment (for testing).
+- `autoCertificates` (boolean): Enables automatic certificate issuance and renewal in production lifecycle. **Default: `true`**. Set to `false` only if certificates are managed externally.
+- `certificateRenewIntervalMs` (number): Renewal check interval when `autoCertificates` is enabled (minimum 60s, default 12h).
 - `local` (boolean): Set to `true` to run in local development mode.
 - `minLocalPort` (number): Minimum port for local mode (default: 4000).
 - `maxLocalPort` (number): Maximum port for local mode (default: 9999).
@@ -350,61 +352,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. It resolves certificates from `greenlockStorePath` and, when `autoCertificates` is enabled (default), can issue missing certificates automatically. 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-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/demo/https-cluster-configurable.js

@@ -0,0 +1,84 @@
+const cluster = require('cluster');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+const Roster = require('../index.js');
+
+// Change these values to your target domain and HTTPS port.
+const CONFIG = {
+    domain: 'chinchon.blyts.com',
+    httpsPort: 4336,
+    workers: Math.max(1, Math.min(2, os.cpus().length)),
+    wwwPath: path.join(__dirname, 'www'),
+    greenlockStorePath: path.join(__dirname, '..', 'greenlock.d'),
+    email: 'mclasen@blyts.com',
+    staging: false,
+    autoCertificates: true
+};
+
+async function startWorker() {
+    const roster = new Roster({
+        local: false,
+        email: CONFIG.email,
+        staging: CONFIG.staging,
+        wwwPath: CONFIG.wwwPath,
+        greenlockStorePath: CONFIG.greenlockStorePath,
+        autoCertificates: CONFIG.autoCertificates
+    });
+
+    // Domain is configured from CONFIG (single source of truth).
+    roster.register(CONFIG.domain, () => {
+        return (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end(`HTTPS cluster response from worker ${process.pid} for ${CONFIG.domain}`);
+        };
+    });
+
+    await roster.init();
+    // Automatic cert issuance by roster-server (and renewal loop) in cluster-friendly mode.
+    const defaultPems = await roster.ensureCertificate(CONFIG.domain);
+
+    const server = https.createServer({
+        key: defaultPems.key,
+        cert: defaultPems.cert,
+        SNICallback: roster.sniCallback(),
+        minVersion: 'TLSv1.2',
+        maxVersion: 'TLSv1.3'
+    });
+
+    roster.attach(server);
+
+    server.listen(CONFIG.httpsPort, () => {
+        console.log(`[worker ${process.pid}] listening on https://0.0.0.0:${CONFIG.httpsPort} for domain ${CONFIG.domain}`);
+    });
+}
+
+async function startPrimary() {
+    console.log(`\n[primary ${process.pid}] starting ${CONFIG.workers} workers`);
+    console.log(`domain=${CONFIG.domain} port=${CONFIG.httpsPort}`);
+    console.log(`wwwPath=${CONFIG.wwwPath}`);
+    console.log(`greenlockStorePath=${CONFIG.greenlockStorePath}\n`);
+    console.log(`[primary] cert lifecycle managed by roster-server (autoCertificates=${CONFIG.autoCertificates})\n`);
+
+    for (let i = 0; i < CONFIG.workers; i++) {
+        cluster.fork();
+    }
+
+    cluster.on('exit', (worker) => {
+        console.log(`[primary] worker ${worker.process.pid} exited, restarting...`);
+        cluster.fork();
+    });
+}
+
+if (cluster.isPrimary) {
+    startPrimary().catch((err) => {
+        console.error(`[primary ${process.pid}] startup failed`, err);
+        process.exit(1);
+    });
+} else {
+    startWorker().catch((err) => {
+        console.error(`[worker ${process.pid}] startup 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/roster-autocert-defaults.md

@@ -0,0 +1,20 @@
+---
+id: eyap8usul0
+type: decision
+title: 'Decision update: autoCertificates default true'
+created: '2026-03-20 23:53:16'
+---
+# Decision update: autoCertificates default true
+
+**What changed**: `autoCertificates` now defaults to `true` instead of `false`.
+
+**Why**: User expectation and product value are that SSL lifecycle should be automatic and robust by default in RosterServer.
+
+**Implementation**:
+- Constructor default changed in `index.js` (`parseBooleanFlag(options.autoCertificates, true)`).
+- Added constructor tests for default true and explicit opt-out (`autoCertificates: false`).
+- Updated docs (`README.md`, `skills/roster-server/SKILL.md`) to reflect default-on behavior.
+
+**Guardrails**:
+- Users can still opt out with `autoCertificates: false` when certs are externally managed.
+- `ensureCertificate()` keeps explicit error message when autoCertificates is disabled.