roster-server 2.4.14 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # 👾 RosterServer
 
-Host multiple domains from one Node.js process, with HTTPS certificates managed through Greenlock, Express and Socket.IO integration, static file serving, and local HTTP development. Each site receives a virtual server for request and upgrade listeners; applications share the process.
+Host multiple domains behind one Node.js entry point, with HTTPS certificates managed through Greenlock, Express and Socket.IO integration, static file serving, and local HTTP development. Each site receives a virtual server for request and upgrade listeners. By default every site directory runs in its own process, so a busy, blocked, or crashed site does not take the others down; see [site isolation](#site-isolation).
 
 ## Installation
 
@@ -85,7 +85,7 @@ module.exports = () => {
 };
 ```
 
-The virtual server supports request/upgrade listener integration; it is not a separately listening TCP server or a process isolation boundary. Request listeners own their requests, including asynchronous responses. Roster does not invoke the returned handler just because a listener has not finished. Wrappers can capture the site's HTTP fallback through `server.listeners('request')`.
+The virtual server supports request/upgrade listener integration; it is not a separately listening TCP server. Process isolation comes from [site isolation](#site-isolation), not from the virtual server. Request listeners own their requests, including asynchronous responses. Roster does not invoke the returned handler just because a listener has not finished. Wrappers can capture the site's HTTP fallback through `server.listeners('request')`.
 
 Thrown or rejected request-handler errors produce a `500`, or destroy the response if headers were already sent.
 
@@ -120,6 +120,12 @@ roster.register('api.example.com:8443', site);
 roster.register('*.example.com:8443', site);
 ```
 
+Instead of a factory, `register()` also accepts a site directory, loaded like a discovered site. A directory registration can run in an isolated process, and every domain registered with the same directory, including the discovered one, shares that process:
+
+```javascript
+roster.register('en.example.com', path.join(wwwPath, 'example.com'));
+```
+
 A registration without an explicit port uses the instance's `port`. Exact hosts take precedence over wildcard matches. `*.example.com` does not match the apex `example.com`; register the apex separately if needed. Wildcard certificates require [DNS-01 configuration](#certificates-and-dns).
 
 Requests to `www` hosts redirect to the host without `www`, preserving the explicit port in the Host header. `getUrl(domain)` normalizes `www` and supports wildcard lookups. In local mode it returns `localhost` or a subdomain such as `api.localhost`, with the assigned port. In production it uses the instance's default port; it is not a per-port URL lookup for registrations made only on non-default ports, which can return `null`.
@@ -135,6 +141,49 @@ A directory with `index.html` and no entry script needs no JavaScript factory:
 
 Filesystem operations are asynchronous, and disconnected downloads close their file handles.
 
+## Site isolation
+
+`start()` runs each site directory in its own Node.js process. This applies to discovered `www/` sites and to directories passed to `register()`. One process serves every domain and port registered with that directory, so a site with SQLite, files written by lowdb, cron jobs, or internal servers never runs twice. Disable isolation with `isolation: false`.
+
+The main process keeps the listeners, certificate issuance and renewal (ACME, SNI, wildcard), port 80, and shutdown. For each HTTPS connection it reads only the TLS ClientHello and passes the raw socket to the process serving that SNI host. That process terminates TLS and handles requests, WebSocket upgrades, request plugins, and `onClose` hooks. The socket is the client's own connection, so `req.socket.remoteAddress` and all headers arrive unchanged. A TLS handshake does not use the main process's CPU or event loop. In local mode, each isolated process listens on its own assigned port.
+
+These sites stay in the main process:
+
+- A factory function passed to `register()`, because a function cannot move to another process. Register the site directory instead to isolate it.
+- A site whose entry module the main process already loaded with `require()`. Isolating it would create a second instance. This check cannot see ESM modules imported by the application; do not import an isolated site's module from the server script.
+- Connections without SNI, or for a host no isolated site serves.
+
+Roster logs the sites that are not isolated at startup.
+
+A crashed isolated process is restarted after `isolation.restartDelayMs`, and the other sites keep serving. While it is down, its connections are refused. If its startup fails, `start()` rejects, as it does for an in-process factory error. Once more than `isolation.backlog` connections are waiting for a site process, new connections to that site are dropped. A client that sends no ClientHello within `isolation.helloTimeoutMs` is disconnected.
+
+```javascript
+const roster = new Roster({
+    isolation: { restartDelayMs: 1000, backlog: 511, helloTimeoutMs: 10000 }
+});
+```
+
+When at least one site is isolated, request plugins added with `use()` before `start()` are recreated in every isolated process. Plugin state, such as scanner-blocker bans, is therefore per site. A plugin can be recreated only if it carries a `Roster.pluginSource` descriptor whose options are JSON-serializable; otherwise `start()` rejects. `createScannerBlocker()` provides one unless its options include functions such as `onBlock`. For a custom plugin:
+
+```javascript
+// my-plugin.cjs
+const Roster = require('roster-server');
+
+function createMyPlugin(options) {
+    const plugin = (req, res, context) => false;
+    plugin[Roster.pluginSource] = { module: __filename, export: 'createMyPlugin', options };
+    return plugin;
+}
+
+module.exports = { createMyPlugin };
+```
+
+On `close()`, or a handled signal, each isolated process drains its requests, runs its `onClose` hooks, and exits. Hook errors from those processes appear in the same `AggregateError`. When `closeTimeoutMs` expires, Roster kills the remaining isolated processes. Isolated processes ignore `SIGINT` and `SIGTERM` and wait for the main process, so a signal sent to the whole process group by a terminal or process manager does not cut their drain short. If the main process exits without closing, each isolated process closes itself.
+
+Isolation needs a Roster-owned listener, so it applies only when `start()` initializes the instance. Calling `init()` yourself keeps every site in the current process for `attach()` and the other external-server helpers. Isolation is not available on Bun, whose HTTPS server cannot adopt a passed socket; there, Roster logs a warning and serves every site in the main process. Isolation cannot be combined with the legacy `cluster: true` launcher, which disables it by default.
+
+Each isolated process loads Node.js and its site, so memory use grows with the number of site directories. Code that runs when a site's module loads runs in that site's process, not in the main process.
+
 ## Startup and shutdown
 
 Concurrent `init()` calls share initialization, so each factory runs once per registered domain/port. Concurrent `start()` calls share startup. In standalone and local modes, `await roster.start()` waits for listeners to bind. Initialization or bind failures reject and clean up resources already initialized by the instance.
@@ -203,7 +252,7 @@ During shutdown, `roster.close()` drains its routed requests, closes its routed
 
 For multiple workers, keep certificate issuance in one manager process and use `autoCertificates: false` with `init()` in serving workers. The manager can use `start()` to provide ACME HTTP and `ensureCertificate()` before starting workers. Keep domain/certificate configuration consistent: `init()` still writes configuration even in serving-only mode. `start()` retains the standalone ACME lifecycle even if `autoCertificates` is false.
 
-The legacy `cluster: true` launcher delegates process management to Greenlock. `close()` applies to the current Roster instance; it does not stop worker processes. External cluster managers should coordinate shutdown in each worker.
+The legacy `cluster: true` launcher delegates process management to Greenlock and turns off [site isolation](#site-isolation). `close()` applies to the current Roster instance; it does not stop worker processes. External cluster managers should coordinate shutdown in each worker.
 
 ## Certificates and DNS
 
@@ -245,6 +294,7 @@ Pass operational settings through the constructor, using the consuming applicati
 | `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. |
+| `isolation` | `true` (`false` with `cluster`) | One process per site directory under `start()`; `false` or `{ restartDelayMs, backlog, helloTimeoutMs }` (defaults `1000`, `511`, `10000`). See [site isolation](#site-isolation). |
 | `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). |
@@ -255,7 +305,7 @@ Pass operational settings through the constructor, using the consuming applicati
 
 | Method | Contract |
 | --- | --- |
-| `register(domain, factory)` | Register before initialization; accepts `domain:port` and wildcard domains. Returns `Roster`. |
+| `register(domain, factory \| siteDirectory)` | Register before initialization; accepts `domain:port` and wildcard domains. A site directory can be isolated; a factory runs in the main process. Returns `Roster`. |
 | `use(plugin)` | Add a synchronous request plugin. Returns `Roster`. |
 | `init()` | `Promise<Roster>`; prepare routing and factories without listening. |
 | `start()` | Start standalone/local listeners; await readiness. |
@@ -270,6 +320,7 @@ Pass operational settings through the constructor, using the consuming applicati
 | `createManagedHttpsServer({ servername, port?, ensureCertificate?, tlsOptions? })` | `Promise<https.Server>` with certificates and dispatchers; does not listen. Certificate assurance defaults to `true`. Requires production-mode `init()`. |
 | `createServingHttpsServer({ servername, port?, tlsOptions? })` | Same helper with `ensureCertificate: false`; set `autoCertificates: false` for a serving-only instance. |
 | `virtualServer.onClose(fn)` | Register a cleanup hook; returns the virtual server. See [shutdown](#startup-and-shutdown). |
+| `Roster.pluginSource` | Symbol for a request plugin's `{ module, export, options }` descriptor. See [site isolation](#site-isolation). |
 
 ## Request plugins
 
@@ -283,7 +334,7 @@ import { createScannerBlocker } from 'roster-server/plugins/scanner-blocker.js';
 roster.use(createScannerBlocker());
 ```
 
-The blocker rejects common PHP, WordPress, repository, and sensitive-file probes with `404`. Defaults: a `60000` ms strike window, `3` strikes, a `900000` ms ban, `10000` tracked clients, and `trustProxy: false`. Configure `windowMs`, `strikeThreshold`, `banDurationMs`, and `maxTrackedClients` on the plugin. State is bounded, in memory, and per process.
+The blocker rejects common PHP, WordPress, repository, and sensitive-file probes with `404`. Defaults: a `60000` ms strike window, `3` strikes, a `900000` ms ban, `10000` tracked clients, and `trustProxy: false`. Configure `windowMs`, `strikeThreshold`, `banDurationMs`, and `maxTrackedClients` on the plugin. State is bounded, in memory, and per process, so each isolated site keeps its own bans.
 
 Enable `trustProxy` only behind a trusted proxy that overwrites `X-Forwarded-For`. The optional synchronous `onBlock(event)` callback can integrate the application's logging or enforcement; it does not itself provide shared or persistent bans.
 

package/index.js

@@ -2,14 +2,37 @@ const fs = require('fs');
 const path = require('path');
 const http = require('http');
 const https = require('https');
+const net = require('net');
 const tls = require('tls');
 const crypto = require('crypto');
 const { EventEmitter } = require('events');
 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 { locateSiteEntry, resolveSiteApp } = require('./lib/resolve-site-app.js');
+const { IsolatedSite } = require('./lib/isolated-site.js');
+const { parseClientHello } = require('./lib/client-hello.js');
 const log = require('lemonlog')('roster');
 const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
+// A request plugin carrying { module, export, options } under this key can be recreated in isolated site processes.
+const PLUGIN_SOURCE = Symbol.for('roster-server.plugin-source');
+
+function isJsonValue(value) {
+    if (value === null || ['string', 'number', 'boolean', 'undefined'].includes(typeof value)) return true;
+    if (Array.isArray(value)) return value.every(isJsonValue);
+    if (Object.getPrototypeOf(value) !== Object.prototype) return false;
+    return Object.values(value).every(isJsonValue);
+}
+
+function isolatedPluginSource(plugin) {
+    const source = plugin[PLUGIN_SOURCE];
+    if (!source || typeof source.module !== 'string' || typeof source.export !== 'string' || !isJsonValue(source.options)) {
+        throw new Error(
+            `Request plugin ${plugin.name || '(anonymous)'} cannot be recreated in isolated site processes. ` +
+            'Attach a Roster.pluginSource descriptor with JSON-serializable options, or set isolation: false'
+        );
+    }
+    return { module: source.module, export: source.export, options: source.options };
+}
 
 function requestError(error, res) {
     log.error('Request handler failed:', error?.message || error);
@@ -272,6 +295,27 @@ class Roster {
         this.greenlockStorePath = options.greenlockStorePath || path.join(basePath, 'greenlock.d');
         this.staging = options.staging || false;
         this.cluster = options.cluster || false;
+        const isolation = options.isolation ?? !this.cluster;
+        if (typeof isolation !== 'boolean' && (typeof isolation !== 'object' || isolation === null)) {
+            throw new TypeError('isolation must be a boolean or an options object');
+        }
+        if (isolation && this.cluster) {
+            throw new Error('isolation cannot be combined with cluster: true');
+        }
+        this.isolation = isolation ? {
+            restartDelayMs: 1000,
+            backlog: 511,
+            helloTimeoutMs: 10000,
+            ...(isolation === true ? {} : isolation)
+        } : null;
+        for (const [name, value] of Object.entries(this.isolation || {})) {
+            if (!Number.isFinite(value) || value <= 0) {
+                throw new TypeError(`isolation.${name} must be a positive finite number`);
+            }
+        }
+        this._isolate = false;
+        this._isolatedSites = [];
+        this._isolatedRoutes = {};
         this.local = options.local || false;
         this.domains = [];
         this.sites = {};
@@ -382,7 +426,9 @@ class Roster {
 
             let resolved;
             try {
-                resolved = await resolveSiteApp(domainPath, { filename: this.filename });
+                resolved = this._isolate
+                    ? this._locateSite(domainPath)
+                    : await resolveSiteApp(domainPath, { filename: this.filename });
             } catch (err) {
                 log.warn(`⚠️  Error loading site in ${domainPath}:`, err);
                 continue;
@@ -418,6 +464,42 @@ class Roster {
         }
     }
 
+    // An isolated site is recorded by its directory and loaded only by its own process.
+    _locateSite(domainPath) {
+        const entry = locateSiteEntry(domainPath, { filename: this.filename });
+        return entry ? { siteApp: domainPath, type: entry.type } : null;
+    }
+
+    _isLoadedInProcess(sitePath) {
+        const entry = locateSiteEntry(sitePath, { filename: this.filename });
+        if (!entry || entry.type !== 'js') return false;
+        return Boolean(require.cache[entry.path] || require.cache[fs.realpathSync(entry.path)]);
+    }
+
+    // Load site directories that stay in this process; the rest keep their path for an isolated process.
+    async _resolveSiteSources() {
+        const sitePaths = new Set(Object.values(this.sites).filter(source => typeof source === 'string'));
+        for (const sitePath of sitePaths) {
+            this._assertOpen();
+            if (this._isolate) {
+                if (!this._isLoadedInProcess(sitePath)) continue;
+                log.warn(`⚠️  ${sitePath} is already loaded by the main process; serving it there so it never runs twice`);
+            }
+            let resolved = null;
+            try {
+                resolved = await resolveSiteApp(sitePath, { filename: this.filename });
+            } catch (err) {
+                log.warn(`⚠️  Error loading site in ${sitePath}:`, err);
+            }
+            this._assertOpen();
+            for (const [key, source] of Object.entries(this.sites)) {
+                if (source !== sitePath) continue;
+                if (resolved) this.sites[key] = resolved.siteApp;
+                else delete this.sites[key];
+            }
+        }
+    }
+
     generateConfigJson() {
         const configDir = this.greenlockStorePath;
         const configPath = path.join(configDir, 'config.json');
@@ -622,8 +704,13 @@ class Roster {
         if (!domainString) {
             throw new Error('Domain is required');
         }
-        if (typeof requestHandler !== 'function') {
-            throw new Error('requestHandler must be a function');
+        if (typeof requestHandler === 'string') {
+            requestHandler = path.resolve(requestHandler);
+            if (!locateSiteEntry(requestHandler, { filename: this.filename })) {
+                throw new Error(`No index file (js/mjs/cjs or index.html) found in ${requestHandler}`);
+            }
+        } else if (typeof requestHandler !== 'function') {
+            throw new Error('requestHandler must be a function or a site directory path');
         }
 
         const { domain, port } = this.parseDomainWithPort(domainString);
@@ -800,7 +887,7 @@ class Roster {
         this._sitesByPort = {};
         for (const [hostKey, siteApp] of Object.entries(this.sites)) {
             this._assertOpen();
-            if (hostKey.startsWith('www.')) continue;
+            if (hostKey.startsWith('www.') || typeof siteApp !== 'function') continue;
             const { domain, port } = this.parseDomainWithPort(hostKey);
             if (!this._sitesByPort[port]) {
                 this._sitesByPort[port] = {
@@ -827,6 +914,104 @@ class Roster {
         }
     }
 
+    // Sites left with a directory source after _resolveSiteSources get one process per directory.
+    _planIsolatedSites() {
+        if (!this._isolate) return;
+        const keysBySitePath = new Map();
+        for (const [key, source] of Object.entries(this.sites)) {
+            if (typeof source !== 'string') continue;
+            if (!keysBySitePath.has(source)) keysBySitePath.set(source, []);
+            keysBySitePath.get(source).push(key);
+        }
+        const shared = Object.keys(this.sites).filter(key => !key.startsWith('www.') && typeof this.sites[key] === 'function');
+        if (shared.length > 0) {
+            log.warn(`⚠️  Not isolated, served by the main process: ${shared.join(', ')}`);
+        }
+        if (keysBySitePath.size === 0) return;
+
+        const plugins = this.plugins.map(isolatedPluginSource);
+        const options = {
+            local: this.local,
+            port: this.defaultPort,
+            filename: this.filename,
+            greenlockStorePath: this.greenlockStorePath,
+            tlsMinVersion: this.tlsMinVersion,
+            tlsMaxVersion: this.tlsMaxVersion,
+            closeTimeoutMs: this.closeTimeoutMs
+        };
+        const sitesByPath = new Map();
+        for (const [sitePath, keys] of keysBySitePath) {
+            const site = new IsolatedSite({
+                name: path.basename(sitePath),
+                config: { path: sitePath, keys, options, plugins },
+                isolation: this.isolation,
+                issueCertificate: servername => this._checkCertificate(servername)
+            });
+            sitesByPath.set(sitePath, site);
+            this._isolatedSites.push(site);
+        }
+
+        const isolatedPorts = new Set([...keysBySitePath.values()].flat().map(key => this.parseDomainWithPort(key).port));
+        for (const [key, source] of Object.entries(this.sites)) {
+            if (key.startsWith('www.')) continue;
+            const { domain, port } = this.parseDomainWithPort(key);
+            if (!isolatedPorts.has(port)) continue;
+            const routes = this._isolatedRoutes[port] ??= { exact: new Map(), wildcards: [] };
+            const site = sitesByPath.get(source) || null;
+            if (domain.startsWith('*.')) routes.wildcards.push([domain, site]);
+            else routes.exact.set(domain, site);
+        }
+    }
+
+    // Same precedence as getHandlerForPortData: exact host, then wildcards in registration order.
+    _isolatedSiteFor(routes, servername) {
+        const domain = servername.startsWith('www.') ? servername.slice(4) : servername;
+        if (routes.exact.has(domain)) return routes.exact.get(domain);
+        const wildcard = routes.wildcards.find(([pattern]) => hostMatchesWildcard(domain, pattern));
+        return wildcard ? wildcard[1] : null;
+    }
+
+    // Read the TLS ClientHello and hand the raw socket to the process serving its SNI host.
+    _route(socket, port, routes, server) {
+        let head = Buffer.alloc(0);
+        socket.setTimeout(this.isolation.helloTimeoutMs, () => socket.destroy());
+        socket.on('error', () => socket.destroy());
+        const read = chunk => {
+            head = Buffer.concat([head, chunk]);
+            const servername = parseClientHello(head);
+            if (servername === undefined) return;
+            socket.removeListener('data', read);
+            socket.pause();
+            socket.setTimeout(0);
+            const site = servername && this._isolatedSiteFor(routes, servername);
+            if (site) {
+                site.handoff(port, head, socket);
+                return;
+            }
+            socket.unshift(head);
+            server.emit('connection', socket);
+        };
+        socket.on('data', read);
+    }
+
+    _listenSite(server, port) {
+        const routes = this._isolatedRoutes[port];
+        if (!routes) {
+            this.portServers[port] = server;
+            return this._listen(server, port, this.hostname);
+        }
+        this._ownedServers.add(server);
+        const router = net.createServer(socket => this._route(socket, port, routes, server));
+        this.portServers[port] = router;
+        return this._listen(router, port, this.hostname);
+    }
+
+    async _startIsolatedSites() {
+        this._assertOpen();
+        await Promise.all(this._isolatedSites.map(site => site.start()));
+        this._assertOpen();
+    }
+
     _createDispatcher(portData) {
         return (req, res) => {
             if (!this._beginRequest(res)) return;
@@ -1125,6 +1310,7 @@ class Roster {
     async _initialize() {
         await this.loadSites();
         this._assertOpen();
+        await this._resolveSiteSources();
         if (!this.local) {
             this.generateConfigJson();
             if (this.autoCertificates) {
@@ -1132,6 +1318,7 @@ class Roster {
             }
         }
         this._initSiteHandlers();
+        this._planIsolatedSites();
         this._assertOpen();
         if (!this.local) {
             this._initSniResolver();
@@ -1208,7 +1395,9 @@ class Roster {
             timer = setTimeout(() => {
                 for (const res of this._responses) res.destroy();
                 for (const socket of this._sockets) socket.destroy();
-                for (const server of this._ownedServers) server.closeAllConnections();
+                // Isolation routers are plain TCP servers; their sockets are in _sockets.
+                for (const server of this._ownedServers) server.closeAllConnections?.();
+                for (const site of this._isolatedSites) site.kill();
                 reject(timeoutError);
             }, this.closeTimeoutMs);
         });
@@ -1240,7 +1429,7 @@ class Roster {
                         if (error && error.code !== 'ERR_SERVER_NOT_RUNNING') errors.push(error);
                         resolve();
                     });
-                    server.closeIdleConnections();
+                    server.closeIdleConnections?.();
                 } catch (error) {
                     errors.push(error);
                     resolve();
@@ -1254,8 +1443,11 @@ class Roster {
                 try { server.close(); } catch (error) { errors.push(error); }
             }
             for (const socket of this._upgradedSockets) socket.destroy();
+            const isolated = this._isolatedSites.map(site => site.close().then(siteErrors => {
+                errors.push(...siteErrors);
+            }));
             await wait(Promise.all([
-                ...closing, ...draining,
+                ...closing, ...draining, ...isolated,
                 Promise.allSettled([...this._certificateChecks.values(), ...this._contextLoads.values()])
             ]));
             if (isBunRuntime) {
@@ -1376,11 +1568,11 @@ class Roster {
     async startLocalMode() {
         this.domainPorts = {};
 
-        for (const portData of Object.values(this._sitesByPort)) {
+        for (const [sitePort, portData] of Object.entries(this._sitesByPort)) {
             for (const [domain, virtualServer] of Object.entries(portData.virtualServers)) {
                 if (domain.startsWith('www.')) continue;
 
-                const port = this.assignPortToDomain(domain);
+                const port = this.assignPortToDomain(domain, Number(sitePort));
                 this.domainPorts[domain] = port;
 
                 const appHandler = portData.appHandlers[domain];
@@ -1414,13 +1606,32 @@ class Roster {
             }
         }
 
-        log.info(`(✔) Started ${Object.keys(this.portServers).length} sites in local mode`);
+        for (const site of this._isolatedSites) {
+            for (const key of site.config.keys) {
+                if (key.startsWith('www.')) continue;
+                const { domain, port: sitePort } = this.parseDomainWithPort(key);
+                const port = this.assignPortToDomain(domain, sitePort);
+                site.localPorts[`${domain}:${sitePort}`] = port;
+                this.domainPorts[domain] = port;
+            }
+        }
+        await this._startIsolatedSites();
+
+        log.info(`(✔) Started ${Object.keys(this.domainPorts).length} sites in local mode`);
         return Promise.resolve();
     }
 
     start() {
         if (this._closing) return Promise.reject(new Error('Roster is closing or closed'));
         if (!this._startPromise) {
+            // Isolation requires Roster to own the listeners, so only start() initializes for it.
+            if (this.isolation && !this._initPromise) {
+                if (isBunRuntime) {
+                    log.warn('⚠️  Bun runtime detected: site isolation is not supported; all sites run in the main process');
+                } else {
+                    this._isolate = true;
+                }
+            }
             this._startPromise = this._start().catch(async error => {
                 if (!this._closing) {
                     try { await this.close(); } catch (cleanupError) {
@@ -1462,9 +1673,12 @@ class Roster {
 
             await this._listen(httpServer, 80, this.hostname);
             log.info('HTTP server listening on port 80');
+            await this._startIsolatedSites();
 
-            for (const [port, portData] of Object.entries(this._sitesByPort)) {
+            const ports = new Set([...Object.keys(this._sitesByPort), ...Object.keys(this._isolatedRoutes)]);
+            for (const port of ports) {
                 const portNum = parseInt(port);
+                const portData = this._sitesByPort[port] || { virtualServers: {}, appHandlers: {} };
                 const dispatcher = this._createDispatcher(portData);
                 const upgradeHandler = this._createUpgradeHandler(portData);
 
@@ -1577,10 +1791,9 @@ class Roster {
                         httpsServer = glx.httpsServer(tlsOpts, dispatcher);
                     }
 
-                    this.portServers[portNum] = httpsServer;
                     httpsServer.on('upgrade', upgradeHandler);
 
-                    await this._listen(httpsServer, portNum, this.hostname);
+                    await this._listenSite(httpsServer, portNum);
                     log.info(`HTTPS server listening on port ${portNum}`);
                 } else {
                     const httpsOptions = {
@@ -1600,9 +1813,7 @@ class Roster {
                         }
                     });
 
-                    this.portServers[portNum] = httpsServer;
-
-                    await this._listen(httpsServer, portNum, this.hostname);
+                    await this._listenSite(httpsServer, portNum);
                     log.info(`HTTPS server listening on port ${portNum}`);
                 }
             }
@@ -1654,6 +1865,7 @@ class Roster {
 
 module.exports = Roster;
 module.exports.isBunRuntime = isBunRuntime;
+module.exports.pluginSource = PLUGIN_SOURCE;
 module.exports.wildcardRoot = wildcardRoot;
 module.exports.hostMatchesWildcard = hostMatchesWildcard;
 module.exports.wildcardSubjectForHost = wildcardSubjectForHost;

package/lib/client-hello.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const RECORD_HEADER_BYTES = 5;
+const HANDSHAKE_RECORD = 0x16;
+const CLIENT_HELLO = 0x01;
+const SERVER_NAME_EXTENSION = 0x0000;
+const HOST_NAME = 0x00;
+// TLS limits a record to 16 KiB; a ClientHello spanning more than four records is not a browser handshake.
+const MAX_CLIENT_HELLO_BYTES = 4 * (RECORD_HEADER_BYTES + 16384);
+
+function readServerName(hello) {
+    let offset = 4 + 2 + 32;
+    offset += 1 + hello[offset];
+    offset += 2 + hello.readUInt16BE(offset);
+    offset += 1 + hello[offset];
+    const extensionsEnd = offset + 2 + hello.readUInt16BE(offset);
+    offset += 2;
+    while (offset + 4 <= extensionsEnd) {
+        const type = hello.readUInt16BE(offset);
+        const length = hello.readUInt16BE(offset + 2);
+        offset += 4;
+        if (type === SERVER_NAME_EXTENSION) {
+            const listEnd = offset + 2 + hello.readUInt16BE(offset);
+            let entry = offset + 2;
+            while (entry + 3 <= listEnd) {
+                const nameLength = hello.readUInt16BE(entry + 1);
+                if (hello[entry] === HOST_NAME) {
+                    return hello.toString('ascii', entry + 3, entry + 3 + nameLength).toLowerCase().replace(/\.$/, '') || null;
+                }
+                entry += 3 + nameLength;
+            }
+            return null;
+        }
+        offset += length;
+    }
+    return null;
+}
+
+/**
+ * Extract the SNI host name from the first bytes a TLS client sends.
+ * @param {Buffer} buffer - Bytes received so far on the connection.
+ * @returns {string|null|undefined} The lowercase server name, `null` when the bytes are not a
+ * ClientHello carrying one, or `undefined` when more bytes are needed to decide.
+ */
+function parseClientHello(buffer) {
+    const fragments = [];
+    let offset = 0;
+    while (true) {
+        if (buffer.length >= MAX_CLIENT_HELLO_BYTES) return null;
+        if (buffer.length < offset + RECORD_HEADER_BYTES) return undefined;
+        if (buffer[offset] !== HANDSHAKE_RECORD) return null;
+        const recordEnd = offset + RECORD_HEADER_BYTES + buffer.readUInt16BE(offset + 3);
+        if (buffer.length < recordEnd) return undefined;
+        fragments.push(buffer.subarray(offset + RECORD_HEADER_BYTES, recordEnd));
+        offset = recordEnd;
+        const hello = Buffer.concat(fragments);
+        if (hello.length < 4) continue;
+        if (hello[0] !== CLIENT_HELLO) return null;
+        if (hello.length < 4 + hello.readUIntBE(1, 3)) continue;
+        try {
+            return readServerName(hello);
+        } catch {
+            return null;
+        }
+    }
+}
+
+module.exports = { parseClientHello };