roster-server 3.3.0 → 3.4.1

package/README.md

@@ -28,7 +28,7 @@ await roster.start();
 console.log(roster.getUrl('example.com'));
 ```
 
-Local mode binds to `localhost`, skips certificates, and assigns domain ports within `minLocalPort`–`maxLocalPort` (default `4000`–`9999`). Assignments use a domain hash and resolve collisions within the instance; they do not probe for available OS ports. A bind failure rejects startup. Read the assigned URL with `getUrl()` instead of hardcoding a sample port.
+Local mode binds to `hostname` (default `::`, IPv4 and IPv6 on all interfaces), skips certificates, and assigns domain ports within `minLocalPort`–`maxLocalPort` (default `4000`–`9999`). Assignments use a domain hash and resolve collisions within the instance; they do not probe for available OS ports. A bind failure rejects startup. Read the assigned URL with `getUrl()` instead of hardcoding a sample port.
 
 For production HTTPS, use a real contact email, public DNS pointing to the host, and explicit storage paths:
 
@@ -191,6 +191,10 @@ A site directory whose entry exports an object with a `connection(socket, head)`
 ```javascript
 // www/game.example.com/index.js
 export default {
+    async start({ certificate }) {
+        // Runs once before the first connection, e.g. to fork workers.
+        // certificate(servername) resolves { key, cert } PEM strings; cert includes the chain.
+    },
     connection(socket, head) {
         // Terminate TLS here, or pass socket and head to another process.
     },
@@ -202,7 +206,7 @@ export default {
 
 In production, `socket` is the client's TCP connection and `head` holds the TLS ClientHello that Roster already read; put it back with `socket.unshift(head)` before terminating TLS, and do not `resume()` the socket after wrapping it. In local mode, the site's assigned port accepts plain TCP connections, `socket` arrives paused, and `head` is empty. `connection()` runs synchronously; if it throws, Roster destroys the socket.
 
-Roster keeps issuing and renewing the site's certificates under `greenlockStorePath/live/<domain>`, but the site loads them and must pick up renewed files itself. Request plugins, `www.` redirects, and `onClose` hooks do not apply: the site owns every connection it receives. A socket site must run isolated; Roster rejects it when it would be served by the main process.
+`certificate(servername)` returns the certificate Roster would serve for that host, with the same wildcard and zone matching. A missing certificate is issued by the main process first, as for any isolated site. Roster also renews it; call `certificate()` again to pick up a renewal, for example on an interval or when a cached copy gets old. It is not available in local mode. Request plugins, `www.` redirects, and `onClose` hooks do not apply: the site owns every connection it receives. A socket site must run isolated; Roster rejects it when it would be served by the main process.
 
 ## Startup and shutdown
 
@@ -309,7 +313,7 @@ Pass operational settings through the constructor, using the consuming applicati
 | `filename` | `index` | Script entry basename, without extension. |
 | `local` | `false` | Local HTTP mode with assigned ports and no certificates. |
 | `port` | `443` | Default port for manual registrations and routing helpers. |
-| `hostname` | `::` | Production bind address; local mode uses `localhost`. |
+| `hostname` | `::` | Bind address in production and local mode. |
 | `minLocalPort`, `maxLocalPort` | `4000`, `9999` | Inclusive local assignment range. |
 | `staging` | `false` | ACME staging environment. |
 | `autoCertificates` | `true` | Certificate runtime during `init()`; disable for serving-only workers. |

package/index.js

@@ -950,6 +950,7 @@ class Roster {
         const plugins = this.plugins.map(isolatedPluginSource);
         const options = {
             local: this.local,
+            hostname: this.hostname,
             port: this.defaultPort,
             filename: this.filename,
             greenlockStorePath: this.greenlockStorePath,
@@ -1630,7 +1631,7 @@ class Roster {
                     virtualServer.processUpgrade(req, socket, head);
                 });
 
-                await this._listen(httpServer, port, 'localhost');
+                await this._listen(httpServer, port, this.hostname);
                 const cleanDomain = normalizeDomainForLocalHost(domain);
                 log.info(`🌐 ${domain} → http://${localHostForDomain(cleanDomain)}:${port}`);
             }

package/lib/resolve-site-app.js

@@ -42,8 +42,8 @@ async function resolveSiteApp(domainPath, options = {}) {
 }
 
 /**
- * A socket site exports `{ connection(socket, head), close?() }` and serves raw client
- * connections itself, including TLS. Only an isolated site process can hand it sockets.
+ * A socket site exports `{ start?(context), connection(socket, head), close?() }` and serves
+ * raw client connections itself, including TLS. Only an isolated site process can hand it sockets.
  */
 function isSocketSite(siteApp) {
     return typeof siteApp === 'object' && siteApp !== null && typeof siteApp.connection === 'function';

package/lib/site-worker.js

@@ -45,6 +45,11 @@ class SiteWorkerRoster extends Roster {
         return this._socketSite !== null;
     }
 
+    // The site terminates TLS with certificates Roster resolves: read from the store, or issued by the main process.
+    startSocketSite() {
+        return this._socketSite.start?.({ certificate: servername => this.ensureCertificate(servername) });
+    }
+
     // In local mode a socket site gets plain connections on its assigned ports, with no ClientHello.
     async serveLocalSockets() {
         const head = Buffer.alloc(0);
@@ -52,7 +57,7 @@ class SiteWorkerRoster extends Roster {
             if (key.startsWith('www.')) continue;
             const { domain, port } = this.parseDomainWithPort(key);
             const server = net.createServer({ pauseOnConnect: true });
-            const listening = this._listen(server, this._site.localPorts[`${domain}:${port}`], 'localhost');
+            const listening = this._listen(server, this._site.localPorts[`${domain}:${port}`], this.hostname);
             server.on('connection', socket => {
                 // The site owns the connection from here; it may pass it to another process.
                 this._sockets.delete(socket);
@@ -167,6 +172,7 @@ async function start(site) {
         }
         await roster.init();
         if (roster.socketSite) {
+            await roster.startSocketSite();
             if (roster.local) await roster.serveLocalSockets();
         } else if (roster.local) {
             await roster.start();

package/package.json

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

package/skills/roster-server/SKILL.md

@@ -9,7 +9,7 @@ Use this skill to configure a consuming application. Keep its existing configura
 
 ## Choose the lifecycle owner
 
-- **Local development:** `new Roster({ local: true, wwwPath: absolutePath })`, register sites, then `await roster.start()`. Local mode binds to `localhost` and assigns ports; read URLs with `roster.getUrl(domain)` after startup.
+- **Local development:** `new Roster({ local: true, wwwPath: absolutePath })`, register sites, then `await roster.start()`. Local mode binds to `hostname` (default `::`, IPv4 and IPv6) and assigns ports; read URLs with `roster.getUrl(domain)` after startup.
 - **Standalone HTTPS:** set the real `email`, absolute `wwwPath` and `greenlockStorePath`; leave `local` false. `await roster.start()` owns ACME HTTP on port 80 and the configured HTTPS listeners. A different HTTPS port does not eliminate the need for port 80.
 - **External server/worker:** `await roster.init()`, then `roster.attach(server, { port })` or an HTTPS helper. The caller owns listening and closing that server. `port` on `attach()` selects the routing table, not the TCP port.
 - **Serving-only worker:** use `autoCertificates: false` with `init()` and `createServingHttpsServer({ servername })`. A separate manager must provide certificates first. Calling `start()` still enables the standalone ACME lifecycle.

package/test/isolation.test.js

@@ -91,9 +91,9 @@ function get(port, servername, { pathname = '/', headers = {} } = {}) {
     });
 }
 
-function localGet(port, pathname = '/') {
+function localGet(port, pathname = '/', hostname = 'localhost') {
     return new Promise((resolve, reject) => {
-        http.get({ hostname: 'localhost', port, path: pathname, agent: false }, res => {
+        http.get({ hostname, port, path: pathname, agent: false }, res => {
             let body = '';
             res.on('data', chunk => { body += chunk; });
             res.on('end', () => resolve({ status: res.statusCode, body }));
@@ -315,6 +315,9 @@ it('isolates directory sites in local mode, including aliases and request plugin
     assert.equal(alias.pid, site.pid);
     assert.notEqual(other.pid, site.pid);
     assert.deepEqual(await localGet(port('other.example'), '/wp-login.php'), { status: 404, body: 'Not Found' });
+    for (const address of ['127.0.0.1', '::1']) {
+        assert.equal(JSON.parse((await localGet(port('site.example'), '/', address)).body).pid, site.pid);
+    }
 });
 
 it('serves a site module already loaded by the main process from that process', { timeout: 20000 }, async t => {
@@ -405,11 +408,11 @@ it('closes isolated sites when the main process dies without closing', { timeout
     assert.equal(fs.readFileSync(marker, 'utf8'), 'closed');
 });
 
-function socketSite(server, marker) {
+function socketSite(server, marker, start = 'async start() {}') {
     return `const fs = require('fs');
-const server = ${server};
-server.on('request', (req, res) => res.end(JSON.stringify({ pid: process.pid, address: req.socket.remoteAddress })));
+let server = ${server};
 module.exports = {
+    ${start},
     connection(socket, head) {
         fs.writeFileSync(${JSON.stringify(marker)} + '.head', String(head.length));
         // A ClientHello read by Roster goes back on the stream; a local connection arrives paused.
@@ -417,6 +420,9 @@ module.exports = {
         server.emit('connection', socket);
         if (head.length === 0) socket.resume();
     },
+    reply(req, res) {
+        res.end(JSON.stringify({ pid: process.pid, address: req.socket.remoteAddress }));
+    },
     close() {
         fs.writeFileSync(${JSON.stringify(marker)}, 'closed');
     }
@@ -426,14 +432,15 @@ module.exports = {
 it('hands raw client sockets with their ClientHello to a socket site that terminates TLS', { timeout: 20000 }, async t => {
     const marker = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'roster-socket-site-')), 'closed');
     t.after(() => fs.rmSync(path.dirname(marker), { recursive: true, force: true }));
-    const tlsServer = `require('https').createServer({
-        key: fs.readFileSync(${JSON.stringify(path.join(pki, 'key.pem'))}),
-        cert: fs.readFileSync(${JSON.stringify(path.join(pki, 'cert.pem'))})
-    })`;
+    // The site gets its certificate from Roster's store through start(), not from files it reads.
+    const start = `async start({ certificate }) {
+        const pems = await certificate('raw.example.com');
+        server = require('https').createServer(pems, (req, res) => module.exports.reply(req, res));
+    }`;
     const { roster, port } = await startProduction(t, {
-        'raw.example.com': socketSite(tlsServer, marker),
+        'raw.example.com': socketSite('null', marker, start),
         'plain.example.com': REPORT_SITE
-    }, { certificates: ['plain.example.com'] });
+    }, { certificates: ['plain.example.com', 'raw.example.com'] });
     const raw = JSON.parse((await get(port, 'raw.example.com')).body);
     const plain = JSON.parse((await get(port, 'plain.example.com')).body);
     assert.notEqual(raw.pid, process.pid);
@@ -445,15 +452,37 @@ it('hands raw client sockets with their ClientHello to a socket site that termin
     assert.equal(isRunning(raw.pid), false);
 });
 
+it('issues a missing certificate through the main process when a socket site asks for it', { timeout: 20000 }, async t => {
+    const marker = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'roster-socket-site-')), 'closed');
+    t.after(() => fs.rmSync(path.dirname(marker), { recursive: true, force: true }));
+    const store = path.join(path.dirname(marker), 'greenlock.d');
+    const issued = [];
+    const start = `async start({ certificate }) {
+        server = require('https').createServer(await certificate('fresh.example.com'), (req, res) => module.exports.reply(req, res));
+    }`;
+    const { port } = await startProduction(t, { 'fresh.example.com': socketSite('null', marker, start) }, {
+        options: { greenlockStorePath: store },
+        issue: async ({ servername }) => {
+            issued.push(servername);
+            installCertificate(store, servername);
+        }
+    });
+    assert.deepEqual(issued, ['fresh.example.com']);
+    assert.notEqual(JSON.parse((await get(port, 'fresh.example.com')).body).pid, process.pid);
+});
+
 it('gives a socket site plain connections on its local port', { timeout: 20000 }, async t => {
     const marker = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'roster-socket-site-')), 'closed');
     t.after(() => fs.rmSync(path.dirname(marker), { recursive: true, force: true }));
-    const { wwwPath } = createWww(t, { 'raw.example': socketSite(`require('http').createServer()`, marker) });
+    const { wwwPath } = createWww(t, {
+        'raw.example': socketSite(`require('http').createServer((req, res) => module.exports.reply(req, res))`, marker)
+    });
     const roster = new Roster({ local: true, wwwPath, minLocalPort: 19370, maxLocalPort: 19379 });
     t.after(() => roster.close().catch(() => {}));
     await roster.start();
     const { port } = new URL(roster.getUrl('raw.example'));
     assert.notEqual(JSON.parse((await localGet(port)).body).pid, process.pid);
+    for (const address of ['127.0.0.1', '::1']) assert.equal((await localGet(port, '/', address)).status, 200);
     assert.equal(fs.readFileSync(`${marker}.head`, 'utf8'), '0');
     await roster.close();
     assert.equal(fs.readFileSync(marker, 'utf8'), 'closed');

package/test/lifecycle.test.js

@@ -94,7 +94,7 @@ it('waits for listening, shares start, and closes owned servers once', async t =
 
 it('rejects bind failures and rolls back already opened ports', async t => {
     const blocker = http.createServer();
-    await new Promise(resolve => blocker.listen(0, 'localhost', resolve));
+    await new Promise(resolve => blocker.listen(0, '::', resolve));
     t.after(() => new Promise(resolve => blocker.close(resolve)));
     const roster = createRoster(t);
     const ports = [0, blocker.address().port];