roster-server 2.4.2 → 2.4.6

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).
@@ -384,6 +386,36 @@ process.on('message', (msg, connection) => {
 });
 ```
 
+### Production Pattern: Single Certificate Manager + Workers
+
+For robust ACME behavior with cluster runtimes, run a single certificate manager process (primary) and keep workers in serving-only mode. This avoids challenge race conditions while keeping certificate lifecycle automatic.
+
+```javascript
+// primary
+const certManager = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www'
+});
+certManager.register('example.com', () => (req, res) => res.end('manager'));
+await certManager.start();                    // enables ACME challenge lifecycle
+await certManager.ensureCertificate('example.com');
+
+// worker
+const workerRoster = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www',
+    autoCertificates: false
+});
+workerRoster.register('example.com', () => (req, res) => res.end('worker'));
+await workerRoster.init();
+const server = await workerRoster.createServingHttpsServer({ servername: 'example.com' });
+server.listen(4336);
+```
+
+Reference implementation: `demo/https-cluster-configurable.js`.
+
 ### API Reference
 
 #### `roster.init()` → `Promise<Roster>`
@@ -400,7 +432,23 @@ Returns the WebSocket upgrade dispatcher for a given port. Routes upgrades to th
 
 #### `roster.sniCallback()` → `(servername, callback) => void`
 
-Returns a TLS SNI callback that resolves certificates from `greenlockStorePath` on disk. Not available in local mode.
+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.ensureCertificate(servername)` → `Promise<{ key, cert }>`
+
+Ensures a certificate exists for `servername`. With `autoCertificates` enabled (default), it issues missing certificates automatically and returns PEMs.
+
+#### `roster.loadCertificate(servername)` → `{ key, cert }`
+
+Loads an existing certificate from `greenlockStorePath` without issuing new certificates. Useful for serving-only workers.
+
+#### `roster.createManagedHttpsServer({ servername, port?, ensureCertificate?, tlsOptions? })` → `Promise<https.Server>`
+
+Creates an HTTPS server prewired with default cert, SNI callback, and request/upgrade routing. By default it ensures certificate issuance before returning.
+
+#### `roster.createServingHttpsServer({ servername, port?, tlsOptions? })` → `Promise<https.Server>`
+
+Convenience alias for serving-only workers. Equivalent to `createManagedHttpsServer(..., ensureCertificate: false)`.
 
 #### `roster.attach(server, { port }?)` → `Roster`
 

package/demo/https-cluster-configurable.js

@@ -0,0 +1,95 @@
+const cluster = require('cluster');
+const os = require('os');
+const path = require('path');
+const Roster = require('../index.js');
+
+// Change these values to your target domain and HTTPS port.
+const CONFIG = {
+    domain: 'example.com',
+    httpsPort: 4336,
+    workers: Math.max(1, Math.min(2, os.cpus().length)),
+    certificateManagerHttpsPort: 0, // 0 = ephemeral, manager does not serve public traffic
+    wwwPath: path.join(__dirname, 'www'),
+    greenlockStorePath: path.join(__dirname, '..', 'greenlock.d'),
+    email: 'mclasen@example.com',
+    staging: false
+};
+
+function createRoster({ isCertificateManager }) {
+    const roster = new Roster({
+        local: false,
+        email: CONFIG.email,
+        staging: CONFIG.staging,
+        wwwPath: CONFIG.wwwPath,
+        greenlockStorePath: CONFIG.greenlockStorePath,
+        autoCertificates: isCertificateManager,
+        // Certificate manager can bind an ephemeral HTTPS port; workers serve real traffic.
+        port: isCertificateManager ? CONFIG.certificateManagerHttpsPort : 443
+    });
+    return roster;
+}
+
+async function startWorker() {
+    const roster = createRoster({ isCertificateManager: false });
+
+    // 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();
+    const server = await roster.createServingHttpsServer({
+        servername: CONFIG.domain
+    });
+
+    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\n');
+
+    // Primary is the single certificate manager to avoid ACME race conditions.
+    // It starts Roster standalone lifecycle so ACME http-01 challenge server (:80) is active.
+    const certificateManager = createRoster({ isCertificateManager: true });
+    certificateManager.register(CONFIG.domain, () => {
+        return (req, res) => {
+            res.writeHead(200);
+            res.end('certificate-manager');
+        };
+    });
+    await certificateManager.start();
+    await certificateManager.ensureCertificate(CONFIG.domain);
+    const subject = CONFIG.domain;
+    console.log(`[primary] certificate ready for ${CONFIG.domain} (subject=${subject})\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/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.

package/index.js

@@ -268,6 +268,12 @@ class Roster {
         }
 
         this.skipLocalCheck = parseBooleanFlag(options.skipLocalCheck, true);
+        this.autoCertificates = parseBooleanFlag(options.autoCertificates, true);
+        this.certificateRenewIntervalMs = Number.isFinite(Number(options.certificateRenewIntervalMs))
+            ? Math.max(60000, Number(options.certificateRenewIntervalMs))
+            : 12 * 60 * 60 * 1000;
+        this._greenlockRuntime = null;
+        this._certificateRenewTimer = null;
 
         const port = options.port === undefined ? 443 : options.port;
         if (port === 80 && !this.local) {
@@ -775,28 +781,193 @@ class Roster {
 
     _initSniResolver() {
         this._sniCallback = (servername, callback) => {
+            const normalizedServername = this._normalizeHostInput(servername).trim().toLowerCase();
             try {
-                const pems = this._resolvePemsForServername(servername);
+                const pems = this._resolvePemsForServername(normalizedServername);
                 if (pems) {
                     callback(null, tls.createSecureContext({ key: pems.key, cert: pems.cert }));
-                } else {
-                    callback(new Error(`No certificate files available for ${servername}`));
+                    return;
                 }
             } catch (error) {
                 callback(error);
+                return;
+            }
+
+            // Cluster-friendly automatic issuance path (no internal listen lifecycle).
+            if (!this._greenlockRuntime || !normalizedServername) {
+                callback(new Error(`No certificate files available for ${servername}`));
+                return;
+            }
+
+            this._greenlockRuntime.get({ servername: normalizedServername })
+                .then(() => {
+                    const issued = this._resolvePemsForServername(normalizedServername);
+                    if (issued) {
+                        callback(null, tls.createSecureContext({ key: issued.key, cert: issued.cert }));
+                    } else {
+                        callback(new Error(`No certificate files available for ${servername}`));
+                    }
+                })
+                .catch((error) => {
+                    callback(error);
+                });
+        };
+    }
+
+    _buildGreenlockOptions() {
+        return {
+            packageRoot: __dirname,
+            configDir: this.greenlockStorePath,
+            maintainerEmail: this.email,
+            cluster: this.cluster,
+            staging: this.staging,
+            skipDryRun: this.skipLocalCheck,
+            skipChallengeTest: this.skipLocalCheck,
+            notify: (event, details) => {
+                const eventDomain = (() => {
+                    if (!details || typeof details !== 'object') return null;
+
+                    const directKeys = ['subject', 'servername', 'domain', 'hostname', 'host'];
+                    for (const key of directKeys) {
+                        if (typeof details[key] === 'string' && details[key].trim()) {
+                            return details[key].trim().toLowerCase();
+                        }
+                    }
+
+                    if (Array.isArray(details.altnames) && details.altnames.length > 0) {
+                        const alt = details.altnames.find(name => typeof name === 'string' && name.trim());
+                        if (alt) return alt.trim().toLowerCase();
+                    }
+
+                    if (Array.isArray(details.domains) && details.domains.length > 0) {
+                        const domain = details.domains.find(name => typeof name === 'string' && name.trim());
+                        if (domain) return domain.trim().toLowerCase();
+                    }
+
+                    if (details.identifier && typeof details.identifier.value === 'string' && details.identifier.value.trim()) {
+                        return details.identifier.value.trim().toLowerCase();
+                    }
+
+                    return null;
+                })();
+
+                let msg;
+                if (typeof details === 'string') {
+                    msg = details;
+                } else if (details instanceof Error) {
+                    msg = details.stack || details.message;
+                } else if (details && typeof details === 'object' && typeof details.message === 'string') {
+                    msg = details.message;
+                } else {
+                    try {
+                        msg = JSON.stringify(details);
+                    } catch {
+                        msg = String(details);
+                    }
+                }
+                if (!msg || msg === 'undefined') msg = `[${event}] (no details)`;
+                if (eventDomain && !msg.includes(`[${eventDomain}]`)) {
+                    msg = `[${eventDomain}] ${msg}`;
+                }
+                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;
+                }
+                if (event === 'error') log.error(msg);
+                else if (event === 'warning') log.warn(msg);
+                else log.info(msg);
             }
         };
     }
 
+    _getManagedCertificateSubjects() {
+        const uniqueDomains = new Set();
+        this.domains.forEach((domain) => {
+            const root = domain.startsWith('*.') ? wildcardRoot(domain) : domain.replace(/^www\./, '');
+            if (root) uniqueDomains.add(root);
+        });
+        const subjects = [];
+        uniqueDomains.forEach((domain) => {
+            subjects.push(domain);
+            const includeWildcard = this.wildcardZones.has(domain) && this.dnsChallenge && !this.combineWildcardCerts;
+            if (includeWildcard) subjects.push(`*.${domain}`);
+        });
+        return [...new Set(subjects)];
+    }
+
+    _startCertificateRenewLoop() {
+        if (!this._greenlockRuntime || this._certificateRenewTimer) return;
+        const subjects = this._getManagedCertificateSubjects();
+        if (subjects.length === 0) return;
+        this._certificateRenewTimer = setInterval(() => {
+            subjects.forEach((subject) => {
+                this._greenlockRuntime.get({ servername: subject }).catch((error) => {
+                    log.warn(`⚠️  Certificate renew check failed for ${subject}: ${error?.message || error}`);
+                });
+            });
+        }, this.certificateRenewIntervalMs);
+        if (typeof this._certificateRenewTimer.unref === 'function') {
+            this._certificateRenewTimer.unref();
+        }
+    }
+
+    async ensureCertificate(servername) {
+        if (this.local) {
+            throw new Error('ensureCertificate() is not available in local mode');
+        }
+        if (!this._initialized) {
+            throw new Error('Call init() before ensureCertificate()');
+        }
+        const normalizedServername = this._normalizeHostInput(servername).trim().toLowerCase();
+        if (!normalizedServername) {
+            throw new Error('servername is required');
+        }
+        let pems = this._resolvePemsForServername(normalizedServername);
+        if (pems) return pems;
+        if (!this._greenlockRuntime) {
+            throw new Error('autoCertificates is disabled; enable { autoCertificates: true } to issue certificates automatically');
+        }
+        await this._greenlockRuntime.get({ servername: normalizedServername });
+        pems = this._resolvePemsForServername(normalizedServername);
+        if (!pems) {
+            throw new Error(`Certificate issuance completed but no PEM files were found for ${normalizedServername}`);
+        }
+        return pems;
+    }
+
+    loadCertificate(servername) {
+        if (this.local) {
+            throw new Error('loadCertificate() is not available in local mode');
+        }
+        if (!this._initialized) {
+            throw new Error('Call init() before loadCertificate()');
+        }
+        const normalizedServername = this._normalizeHostInput(servername).trim().toLowerCase();
+        if (!normalizedServername) {
+            throw new Error('servername is required');
+        }
+        const pems = this._resolvePemsForServername(normalizedServername);
+        if (!pems) {
+            throw new Error(`No certificate files available for ${normalizedServername}`);
+        }
+        return pems;
+    }
+
     async init() {
         if (this._initialized) return this;
         await this.loadSites();
         if (!this.local) {
             this.generateConfigJson();
+            if (this.autoCertificates) {
+                this._greenlockRuntime = GreenlockShim.create(this._buildGreenlockOptions());
+            }
         }
         this._initSiteHandlers();
         if (!this.local) {
             this._initSniResolver();
+            if (this.autoCertificates) {
+                this._startCertificateRenewLoop();
+            }
         }
         this._initialized = true;
         return this;
@@ -838,6 +1009,46 @@ class Roster {
         return this;
     }
 
+    async createManagedHttpsServer(options = {}) {
+        if (this.local) throw new Error('createManagedHttpsServer() is not available in local mode');
+        if (!this._initialized) throw new Error('Call init() before createManagedHttpsServer()');
+
+        const {
+            servername,
+            port,
+            ensureCertificate = true,
+            tlsOptions = {}
+        } = options;
+
+        const normalizedServername = this._normalizeHostInput(servername).trim().toLowerCase();
+        if (!normalizedServername) {
+            throw new Error('servername is required');
+        }
+
+        const pems = ensureCertificate
+            ? await this.ensureCertificate(normalizedServername)
+            : this.loadCertificate(normalizedServername);
+
+        const server = https.createServer({
+            minVersion: this.tlsMinVersion,
+            maxVersion: this.tlsMaxVersion,
+            ...tlsOptions,
+            key: pems.key,
+            cert: pems.cert,
+            SNICallback: this.sniCallback()
+        });
+
+        this.attach(server, { port });
+        return server;
+    }
+
+    async createServingHttpsServer(options = {}) {
+        return this.createManagedHttpsServer({
+            ...options,
+            ensureCertificate: false
+        });
+    }
+
     startLocalMode() {
         this.domainPorts = {};
 
@@ -891,69 +1102,7 @@ class Roster {
             return this.startLocalMode();
         }
 
-        const greenlockOptions = {
-            packageRoot: __dirname,
-            configDir: this.greenlockStorePath,
-            maintainerEmail: this.email,
-            cluster: this.cluster,
-            staging: this.staging,
-            skipDryRun: this.skipLocalCheck,
-            skipChallengeTest: this.skipLocalCheck,
-            notify: (event, details) => {
-                const eventDomain = (() => {
-                    if (!details || typeof details !== 'object') return null;
-
-                    const directKeys = ['subject', 'servername', 'domain', 'hostname', 'host'];
-                    for (const key of directKeys) {
-                        if (typeof details[key] === 'string' && details[key].trim()) {
-                            return details[key].trim().toLowerCase();
-                        }
-                    }
-
-                    if (Array.isArray(details.altnames) && details.altnames.length > 0) {
-                        const alt = details.altnames.find(name => typeof name === 'string' && name.trim());
-                        if (alt) return alt.trim().toLowerCase();
-                    }
-
-                    if (Array.isArray(details.domains) && details.domains.length > 0) {
-                        const domain = details.domains.find(name => typeof name === 'string' && name.trim());
-                        if (domain) return domain.trim().toLowerCase();
-                    }
-
-                    if (details.identifier && typeof details.identifier.value === 'string' && details.identifier.value.trim()) {
-                        return details.identifier.value.trim().toLowerCase();
-                    }
-
-                    return null;
-                })();
-
-                let msg;
-                if (typeof details === 'string') {
-                    msg = details;
-                } else if (details instanceof Error) {
-                    msg = details.stack || details.message;
-                } else if (details && typeof details === 'object' && typeof details.message === 'string') {
-                    msg = details.message;
-                } else {
-                    try {
-                        msg = JSON.stringify(details);
-                    } catch {
-                        msg = String(details);
-                    }
-                }
-                if (!msg || msg === 'undefined') msg = `[${event}] (no details)`;
-                if (eventDomain && !msg.includes(`[${eventDomain}]`)) {
-                    msg = `[${eventDomain}] ${msg}`;
-                }
-                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;
-                }
-                if (event === 'error') log.error(msg);
-                else if (event === 'warning') log.warn(msg);
-                else log.info(msg);
-            }
-        };
+        const greenlockOptions = this._buildGreenlockOptions();
         const greenlockRuntime = GreenlockShim.create(greenlockOptions);
         const greenlock = Greenlock.init({
             ...greenlockOptions,

package/package.json

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

package/skills/roster-server/SKILL.md

@@ -147,6 +147,31 @@ process.on('message', (msg, connection) => {
 });
 ```
 
+### Pattern 7: Cluster Production (single cert manager + workers)
+```javascript
+// PRIMARY: certificate manager (single process)
+const manager = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www'
+});
+manager.register('example.com', () => (req, res) => res.end('manager'));
+await manager.start();
+await manager.ensureCertificate('example.com');
+
+// WORKER: serving-only process
+const worker = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www',
+    autoCertificates: false
+});
+worker.register('example.com', () => (req, res) => res.end('worker'));
+await worker.init();
+const httpsServer = await worker.createServingHttpsServer({ servername: 'example.com' });
+httpsServer.listen(4336);
+```
+
 ## Key Configuration Options
 
 ```javascript
@@ -189,7 +214,19 @@ Returns `(req, res) => void` dispatcher for a port (defaults to `defaultPort`).
 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.
+Returns `(servername, callback) => void` TLS SNI callback that resolves certs from `greenlockStorePath`. With `autoCertificates` enabled (default), it can issue missing certs automatically. Production mode only. Requires `init()` first.
+
+### `roster.ensureCertificate(servername)`
+Forces certificate availability for a domain and returns `{ key, cert }`. With `autoCertificates` enabled (default), it issues certs automatically when missing.
+
+### `roster.loadCertificate(servername)`
+Loads existing `{ key, cert }` from `greenlockStorePath` without issuing new certificates.
+
+### `roster.createManagedHttpsServer(options)`
+Creates a pre-wired `https.Server` with default cert, SNI callback, and attached request/upgrade handlers.
+
+### `roster.createServingHttpsServer(options)`
+Serving-only helper for worker processes. Same as `createManagedHttpsServer(..., ensureCertificate: false)`.
 
 ### `roster.attach(server, { port }?)`
 Convenience: wires `requestHandler` + `upgradeHandler` onto an external `http.Server` or `https.Server`. Returns `this`. Requires `init()` first.

package/test/roster-server.test.js

@@ -318,6 +318,14 @@ describe('Roster', () => {
             const roster = new Roster({ local: false, combineWildcardCerts: true });
             assert.strictEqual(roster.combineWildcardCerts, true);
         });
+        it('defaults autoCertificates to true', () => {
+            const roster = new Roster({ local: false });
+            assert.strictEqual(roster.autoCertificates, true);
+        });
+        it('allows disabling autoCertificates explicitly', () => {
+            const roster = new Roster({ local: false, autoCertificates: false });
+            assert.strictEqual(roster.autoCertificates, false);
+        });
     });
 
     describe('register (normal domain)', () => {
@@ -901,6 +909,84 @@ describe('Roster sniCallback()', () => {
     });
 });
 
+describe('Roster ensureCertificate()', () => {
+    it('throws if called before init()', async () => {
+        const roster = new Roster({ local: false, autoCertificates: true });
+        await assert.rejects(() => roster.ensureCertificate('example.com'), /Call init\(\) before ensureCertificate/);
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true, autoCertificates: true });
+        roster.register('local-cert.example', () => () => {});
+        await roster.init();
+        await assert.rejects(() => roster.ensureCertificate('local-cert.example'), /not available in local mode/);
+    });
+
+    it('throws when autoCertificates is disabled and cert is missing', async () => {
+        const roster = new Roster({ local: false, autoCertificates: false });
+        roster.register('missing-cert.example', () => () => {});
+        await roster.init();
+        await assert.rejects(
+            () => roster.ensureCertificate('missing-cert.example'),
+            /autoCertificates is disabled/
+        );
+    });
+});
+
+describe('Roster loadCertificate()', () => {
+    it('throws if called before init()', () => {
+        const roster = new Roster({ local: false });
+        assert.throws(() => roster.loadCertificate('example.com'), /Call init\(\) before loadCertificate/);
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('local-load.example', () => () => {});
+        await roster.init();
+        assert.throws(() => roster.loadCertificate('local-load.example'), /not available in local mode/);
+    });
+});
+
+describe('Roster createManagedHttpsServer()', () => {
+    it('throws if called before init()', async () => {
+        const roster = new Roster({ local: false });
+        await assert.rejects(
+            () => roster.createManagedHttpsServer({ servername: 'example.com' }),
+            /Call init\(\) before createManagedHttpsServer/
+        );
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('local-managed.example', () => () => {});
+        await roster.init();
+        await assert.rejects(
+            () => roster.createManagedHttpsServer({ servername: 'local-managed.example' }),
+            /not available in local mode/
+        );
+    });
+});
+
+describe('Roster createServingHttpsServer()', () => {
+    it('throws if called before init()', async () => {
+        const roster = new Roster({ local: false });
+        await assert.rejects(
+            () => roster.createServingHttpsServer({ servername: 'example.com' }),
+            /Call init\(\) before createManagedHttpsServer/
+        );
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('local-serving.example', () => () => {});
+        await roster.init();
+        await assert.rejects(
+            () => roster.createServingHttpsServer({ servername: 'local-serving.example' }),
+            /not available in local mode/
+        );
+    });
+});
+
 describe('Roster attach()', () => {
     it('throws if called before init()', () => {
         const roster = new Roster({ local: true });

package/demo/cluster-sticky-https-sni.js

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

@@ -1,60 +0,0 @@
-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);
-});