roster-server 2.4.13 → 2.4.14

package/README.md

@@ -149,7 +149,18 @@ Register `virtualServer.onClose(fn)` in a factory for timers, databases, queues,
 
 `closeTimeoutMs` (default `30000`) bounds the whole operation. At the deadline Roster destroys remaining owned connections and active routed responses, attempts cleanup hooks, and rejects with a timeout. It cannot forcibly interrupt an application Promise or an ACME operation already in progress.
 
-Closing is **idempotent and terminal**: repeated calls return the same Promise. Create a new instance after closure or failed initialization/startup. Roster does not install process signal handlers; connect shutdown to the application's lifecycle:
+Closing is **idempotent and terminal**: repeated calls return the same Promise. Create a new instance after closure or failed initialization/startup.
+
+For automatic shutdown on `SIGINT` or `SIGTERM`, explicitly enable `handleSignals`:
+
+```javascript
+const roster = new Roster({ handleSignals: true });
+await roster.start();
+```
+
+The option defaults to `false`. Listeners are installed once when `init()` or `start()` begins and removed when closure completes, including failed startup or cleanup. Signals call `roster.close()`; repeated signals during closure do not repeat cleanup. Existing application signal listeners remain installed. Shutdown failures are logged and set `process.exitCode = 1`.
+
+Roster does not force process termination or close caller-owned servers. The process exits naturally when its remaining work finishes; other resources or cluster workers still require application coordination. If the application already coordinates shutdown, leave `handleSignals` disabled and connect Roster to that flow:
 
 ```javascript
 async function shutdown() {
@@ -233,6 +244,7 @@ Pass operational settings through the constructor, using the consuming applicati
 | `autoCertificates` | `true` | Certificate runtime during `init()`; disable for serving-only workers. |
 | `certificateRenewIntervalMs` | `43200000` (12h) | Roster renewal check interval; minimum `60000`. |
 | `closeTimeoutMs` | `30000` | Positive finite total shutdown deadline. |
+| `handleSignals` | `false` | Close this instance on `SIGINT`/`SIGTERM`; does not force process exit. |
 | `tlsMinVersion`, `tlsMaxVersion` | `TLSv1.2`, `TLSv1.3` | Protocol limits for created HTTPS servers. |
 | `skipLocalCheck` | `true` | Skips Greenlock dry-run/local challenge checks. |
 | `dnsChallenge` | CLI wrapper | DNS-01 options or `false`; see [certificates](#certificates-and-dns). |

package/index.js

@@ -9,6 +9,7 @@ const Greenlock = require('./vendor/greenlock-express/greenlock-express.js');
 const GreenlockShim = require('./vendor/greenlock-express/greenlock-shim.js');
 const { resolveSiteApp } = require('./lib/resolve-site-app.js');
 const log = require('lemonlog')('roster');
+const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
 
 function requestError(error, res) {
     log.error('Request handler failed:', error?.message || error);
@@ -287,6 +288,8 @@ class Roster {
         this._initPromise = null;
         this._startPromise = null;
         this._closePromise = null;
+        this.handleSignals = parseBooleanFlag(options.handleSignals, false);
+        this._signalHandler = null;
         this._ownedServers = new Set();
         this._sockets = new Set();
         this._upgradedSockets = new Set();
@@ -1097,6 +1100,16 @@ class Roster {
     init() {
         if (this._closing) return Promise.reject(new Error('Roster is closing or closed'));
         if (this._initPromise) return this._initPromise;
+        if (this.handleSignals) {
+            this._signalHandler = () => {
+                if (this._closing) return;
+                this.close().catch(error => {
+                    log.error('Signal shutdown failed:', error.message);
+                    process.exitCode = 1;
+                });
+            };
+            for (const signal of SHUTDOWN_SIGNALS) process.on(signal, this._signalHandler);
+        }
         this._initTask = this._initialize();
         this._initPromise = this._initTask.catch(async error => {
             if (!this._closing) {
@@ -1260,6 +1273,10 @@ class Roster {
             }));
         } finally {
             clearTimeout(timer);
+            if (this._signalHandler) {
+                for (const signal of SHUTDOWN_SIGNALS) process.removeListener(signal, this._signalHandler);
+                this._signalHandler = null;
+            }
             for (const [server, handlers] of this._attachments) {
                 server.removeListener('request', handlers.request);
                 server.removeListener('upgrade', handlers.upgrade);

package/package.json

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

package/skills/roster-server/SKILL.md

@@ -56,7 +56,7 @@ A virtual request listener owns its request even before it ends the response. Ro
 
 ## Shutdown
 
-- Connect `await roster.close()` to the application's existing shutdown flow. Roster does not install signal handlers or terminate processes.
+- Connect `await roster.close()` to the application's existing shutdown flow, or explicitly set `handleSignals: true` for automatic `SIGINT`/`SIGTERM` cleanup. It defaults to `false`; listeners are installed during `init()`/`start()` and removed after closure, including failure. Repeated signals during closure do not repeat hooks. Existing signal listeners are preserved; shutdown errors are logged and set `process.exitCode = 1`. Roster never forces process termination.
 - Register `virtualServer.onClose(fn)` for each site's timers, databases, and other resources. Return/await its cleanup Promise; wrap callback APIs when needed.
 - Roster signals virtual `close` at shutdown start to release integrations such as long polling, closes routed WebSockets, drains HTTP, then runs cleanup hooks concurrently. Put dependent cleanup steps in one hook.
 - Hooks run once. Failures are aggregated after other hooks are attempted. `closeTimeoutMs` bounds the complete operation; timeout cannot cancel arbitrary user Promises or in-flight ACME work.

package/test/signals.test.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const { it } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const { once } = require('node:events');
+
+async function runChild(t, body, onMessage = () => {}) {
+    const script = `
+        const assert = require('node:assert/strict');
+        const http = require('node:http');
+        const Roster = require(${JSON.stringify(require.resolve('../index.js'))});
+        const options = { local: true, wwwPath: '/tmp/roster-signals-' + process.pid };
+        const signals = ['SIGINT', 'SIGTERM'];
+        (async () => { ${body} })().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        }).finally(() => process.disconnect());
+    `;
+    const child = spawn(process.execPath, ['-e', script], { stdio: ['ignore', 'ignore', 'pipe', 'ipc'] });
+    const messages = [];
+    let stderr = '';
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('message', message => {
+        messages.push(message);
+        onMessage(message, child);
+    });
+    t.after(() => {
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+    });
+    const [code, signal] = await once(child, 'close');
+    return { code, signal, messages, stderr };
+}
+
+function assertSuccess(result) {
+    assert.equal(result.signal, null, result.stderr);
+    assert.equal(result.code, 0, result.stderr);
+}
+
+it('does not install signal listeners unless explicitly enabled', { timeout: 10000 }, async t => {
+    assertSuccess(await runChild(t, `
+        const before = signals.map(signal => process.listeners(signal));
+        for (const handleSignals of [undefined, false]) {
+            const roster = new Roster({ ...options, handleSignals });
+            await roster.init();
+            signals.forEach((signal, i) => assert.deepEqual(process.listeners(signal), before[i]));
+            await roster.close();
+            signals.forEach((signal, i) => assert.deepEqual(process.listeners(signal), before[i]));
+        }
+    `));
+});
+
+it('installs listeners once at initialization and removes only the closing instance listeners', { timeout: 10000 }, async t => {
+    assertSuccess(await runChild(t, `
+        const existing = () => {};
+        signals.forEach(signal => process.on(signal, existing));
+        const before = signals.map(signal => process.listeners(signal));
+        const first = new Roster({ ...options, handleSignals: true });
+        const second = new Roster({ ...options, handleSignals: true });
+        signals.forEach((signal, i) => assert.deepEqual(process.listeners(signal), before[i]));
+        await Promise.all([first.init(), first.init(), second.init()]);
+        signals.forEach((signal, i) => assert.equal(process.listenerCount(signal), before[i].length + 2));
+        await Promise.all([first.close(), first.close()]);
+        signals.forEach((signal, i) => {
+            assert.equal(process.listenerCount(signal), before[i].length + 1);
+            assert.ok(process.listeners(signal).includes(existing));
+        });
+        await second.close();
+        signals.forEach((signal, i) => assert.deepEqual(process.listeners(signal), before[i]));
+    `));
+});
+
+it('removes signal listeners after initialization and cleanup both fail', { timeout: 10000 }, async t => {
+    assertSuccess(await runChild(t, `
+        const before = signals.map(signal => process.listeners(signal));
+        const roster = new Roster({ ...options, handleSignals: true });
+        roster.register('example.com', virtual => {
+            virtual.onClose(() => { throw new Error('cleanup failed'); });
+            throw new Error('factory failed');
+        });
+        await assert.rejects(roster.init(), AggregateError);
+        signals.forEach((signal, i) => assert.deepEqual(process.listeners(signal), before[i]));
+    `));
+});
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    it(`drains HTTP and runs hooks once on real ${signal}, including repeated signals`, { timeout: 10000 }, async t => {
+        const result = await runChild(t, `
+            const roster = new Roster({ ...options, handleSignals: true });
+            roster.assignPortToDomain = () => 0;
+            let cleaned = 0;
+            let finished = false;
+            let response;
+            const repeated = new Promise(resolve => process.once(${JSON.stringify(signal === 'SIGINT' ? 'SIGTERM' : 'SIGINT')}, resolve));
+            roster.register('example.com', virtual => {
+                virtual.on('close', () => {
+                    process.send('closing');
+                    setImmediate(() => { finished = true; response.end(' drained'); });
+                });
+                virtual.onClose(async () => {
+                    assert.equal(finished, true);
+                    await repeated;
+                    cleaned++;
+                });
+                return (req, res) => {
+                    response = res;
+                    res.write('active');
+                };
+            });
+            await Promise.all([roster.start(), roster.start()]);
+            const server = roster.portServers[0];
+            const body = await new Promise((resolve, reject) => {
+                http.get({ hostname: 'localhost', port: server.address().port, agent: false }, res => {
+                    let body = '';
+                    res.once('data', () => process.send('ready'));
+                    res.on('data', chunk => { body += chunk; });
+                    res.on('end', () => resolve(body));
+                    res.on('error', reject);
+                }).on('error', reject);
+            });
+            await roster.close();
+            assert.equal(body, 'active drained');
+            assert.equal(cleaned, 1);
+            assert.equal(server.listening, false);
+            signals.forEach(signal => assert.equal(process.listenerCount(signal), 0));
+            process.send('complete');
+        `, (message, child) => {
+            if (message === 'ready') child.kill(signal);
+            if (message === 'closing') child.kill(signal === 'SIGINT' ? 'SIGTERM' : 'SIGINT');
+        });
+        assertSuccess(result);
+        assert.deepEqual(result.messages, ['ready', 'closing', 'complete']);
+    });
+}
+
+it('reports signal-triggered cleanup failure with exit code 1 and removes listeners', { timeout: 10000 }, async t => {
+    const result = await runChild(t, `
+        const roster = new Roster({ ...options, handleSignals: true });
+        roster.assignPortToDomain = () => 0;
+        let entered;
+        const closing = new Promise(resolve => { entered = resolve; });
+        roster.register('example.com', virtual => {
+            virtual.on('close', entered);
+            virtual.onClose(() => { throw new Error('cleanup failed'); });
+            return (req, res) => res.end();
+        });
+        await roster.start();
+        process.send('ready');
+        await closing;
+        await assert.rejects(roster.close(), AggregateError);
+        signals.forEach(signal => assert.equal(process.listenerCount(signal), 0));
+        assert.equal(process.exitCode, 1);
+        process.send('complete');
+    `, (message, child) => { if (message === 'ready') child.kill('SIGTERM'); });
+    assert.equal(result.signal, null, result.stderr);
+    assert.equal(result.code, 1, result.stderr);
+    assert.deepEqual(result.messages, ['ready', 'complete']);
+});
+
+it('handles signals during initialization and cleans up its listeners', { timeout: 10000 }, async t => {
+    const result = await runChild(t, `
+        const roster = new Roster({ ...options, handleSignals: true });
+        let release;
+        roster.loadSites = () => new Promise(resolve => { release = resolve; });
+        let called = false;
+        roster.register('example.com', () => { called = true; });
+        const initializing = assert.rejects(roster.init(), /closing or closed/);
+        process.once('message', () => release());
+        const close = roster.close.bind(roster);
+        roster.close = () => { const result = close(); process.send('closing'); return result; };
+        process.send('ready');
+        await initializing;
+        await close();
+        assert.equal(called, false);
+        signals.forEach(signal => assert.equal(process.listenerCount(signal), 0));
+        process.send('complete');
+    `, (message, child) => {
+        if (message === 'ready') child.kill('SIGTERM');
+        if (message === 'closing') child.send('release');
+    });
+    assertSuccess(result);
+    assert.deepEqual(result.messages, ['ready', 'closing', 'complete']);
+});