roster-server 2.0.4 → 2.1.0

package/README.md

@@ -11,6 +11,7 @@ Welcome to **RosterServer**, the ultimate domain host router with automatic HTTP
 - **Virtual Hosting**: Serve multiple domains from a single server.
 - **Automatic Redirects**: Redirect `www` subdomains to the root domain.
 - **Zero Configuration**: Well, almost zero. Just a tiny bit of setup.
+- **Bun compatible**: Works with both Node.js and [Bun](https://bun.sh).
 
 ## 📦 Installation
 
@@ -18,6 +19,12 @@ Welcome to **RosterServer**, the ultimate domain host router with automatic HTTP
 npm install roster-server
 ```
 
+Or with [Bun](https://bun.sh):
+
+```bash
+bun add roster-server
+```
+
 ## 🤖 AI Skill
 
 You can also add RosterServer as a skill for AI agentic development:
@@ -39,17 +46,42 @@ Your project should look something like this:
 └── www/
     ├── example.com/
     │   └── index.js
-    └── subdomain.example.com/
+    ├── subdomain.example.com/
+    │   └── index.js
+    ├── other-domain.com/
     │   └── index.js
-    └── other-domain.com/
-        └── index.js        
+    └── *.example.com/          # Wildcard: one handler for all subdomains (api.example.com, app.example.com, etc.)
+        └── index.js
 ```
 
+### Wildcard DNS (*.example.com)
+
+You can serve all subdomains of a domain with a single handler in three ways:
+
+1. **Folder**: Create a directory named literally `*.example.com` under `www` (e.g. `www/*.example.com/index.js`). Any request to `api.example.com`, `app.example.com`, etc. will use that handler.
+2. **Register (default port)**: `roster.register('*.example.com', handler)` for the default HTTPS port.
+3. **Register (custom port)**: `roster.register('*.example.com:8080', handler)` for a specific port.
+
+Wildcard SSL certificates require **DNS-01** validation (Let's Encrypt does not support HTTP-01 for wildcards). By default Roster uses `acme-dns-01-cli` through an internal wrapper (adds `propagationDelay` and modern plugin signatures). Override with a custom plugin:
+
+```javascript
+import Roster from 'roster-server';
+
+const roster = new Roster({
+    email: 'admin@example.com',
+    wwwPath: '/srv/www',
+    greenlockStorePath: '/srv/greenlock.d',
+    dnsChallenge: { module: 'acme-dns-01-route53', /* provider options */ }  // optional override
+});
+```
+
+Set `dnsChallenge: false` to disable. For other DNS providers install the plugin in your app and pass it. See [Greenlock DNS plugins](https://git.rootprojects.org/root/greenlock-express.js#dns-01-challenge-plugins).
+
 ### Setting Up Your Server
 
 ```javascript
 // /srv/roster/server.js
-const Roster = require('roster-server');
+import Roster from 'roster-server';
 
 const options = {
     email: 'admin@example.com',
@@ -71,7 +103,7 @@ I'll help analyze the example files shown. You have 3 different implementations
 
 1. **Basic HTTP Handler**:
 ```javascript:demo/www/example.com/index.js
-module.exports = (httpsServer) => {
+export default (httpsServer) => {
     return (req, res) => {
         res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
         res.end('"Loco de pensar, queriendo entrar en razón, y el corazón tiene razones que la propia razón nunca entenderá."');
@@ -81,9 +113,9 @@ module.exports = (httpsServer) => {
 
 2. **Express App**:
 ```javascript:demo/www/express.example.com/index.js
-const express = require('express');
+import express from 'express';
 
-module.exports = (httpsServer) => {
+export default (httpsServer) => {
     const app = express();
     app.get('/', (req, res) => {
         res.setHeader('Content-Type', 'text/plain; charset=utf-8');
@@ -96,9 +128,9 @@ module.exports = (httpsServer) => {
 
 3. **Socket.IO Server**:
 ```javascript:demo/www/sio.example.com/index.js
-const { Server } = require('socket.io');
+import { Server } from 'socket.io';
 
-module.exports = (httpsServer) => {
+export default (httpsServer) => {
     const io = new Server(httpsServer);
 
     io.on('connection', (socket) => {
@@ -145,10 +177,16 @@ roster.register('example.com:8080', (httpsServer) => {
 ### Running the Server
 
 ```bash
-# /srv/roster/server.js
+# With Node.js
 node server.js
 ```
 
+Or with Bun:
+
+```bash
+bun server.js
+```
+
 And that's it! Your server is now hosting multiple HTTPS-enabled sites. 🎉
 
 ## 🤯 But Wait, There's More!
@@ -172,122 +210,11 @@ When creating a new `RosterServer` instance, you can pass the following options:
 - `email` (string): Your email for Let's Encrypt notifications.
 - `wwwPath` (string): Path to your `www` directory containing your sites.
 - `greenlockStorePath` (string): Directory for Greenlock configuration.
+- `dnsChallenge` (object|false): Optional override for wildcard DNS-01 challenge config. Default is local/manual `acme-dns-01-cli` wrapper with `propagationDelay: 120000`, `autoContinue: false`, and `dryRunDelay: 120000`. This is safer for manual DNS providers (Linode/Cloudflare UI) because Roster waits longer and does not auto-advance in interactive terminals. Set `false` to disable. You can pass `{ module: '...', propagationDelay: 180000 }` to tune DNS wait time (ms). Set `autoContinue: true` (or env `ROSTER_DNS_AUTO_CONTINUE=1`) to continue automatically after delay. 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`).
 - `staging` (boolean): Set to `true` to use Let's Encrypt's staging environment (for testing).
 - `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).
-- `tlsMode` (string): TLS backend to use — `'auto'` (default), `'greenlock'`, or `'static'`. See [TLS Configuration](#-tls-configuration) below.
-- `tlsDomain` (string): Domain whose cert files are pre-loaded as the server default in static mode (optional).
-- `tls` (object): Additional TLS options passed to `https.createServer` (e.g. `minVersion`, `maxVersion`, `ciphers`).
-
-## 🔒 TLS Configuration
-
-RosterServer supports three TLS backends, selectable with the `tlsMode` option.
-
-### Behavior matrix
-
-| `tlsMode` | Runtime | HTTPS server |
-|-----------|---------|-------------|
-| `'auto'` (default) | Node.js | Greenlock SNI — certs managed and auto-renewed automatically |
-| `'auto'` (default) | Bun | Static file certs from `greenlockStorePath/live/<domain>/` |
-| `'greenlock'` | any | Always Greenlock SNI |
-| `'static'` | any | Always static file certs |
-
-Bun's TLS stack does not support Greenlock's async SNICallback, causing a `tlsv1 alert protocol version` error. `'auto'` mode detects the runtime and picks the correct backend transparently.
-
-### Static mode cert layout
-
-In `'auto'` (Bun) or `'static'` mode, certs are read per-domain from:
-
-```
-greenlockStorePath/
-  live/
-    example.com/
-      privkey.pem
-      cert.pem
-      chain.pem
-    api.example.com/
-      privkey.pem
-      cert.pem
-      chain.pem
-```
-
-Greenlock populates this layout automatically when it renews certificates, so no extra tooling is required.
-
-### Default TLS options
-
-The static-cert path enforces secure defaults that can be overridden with the `tls` option:
-
-```javascript
-{ minVersion: 'TLSv1.2', maxVersion: 'TLSv1.3' }
-```
-
-### Examples
-
-**Default — works on both Node and Bun without changes:**
-
-```javascript
-const roster = new Roster({
-    email: 'admin@example.com',
-    wwwPath: '/srv/www'
-    // tlsMode defaults to 'auto'
-});
-roster.start();
-```
-
-**Force Greenlock on all runtimes:**
-
-```javascript
-const roster = new Roster({
-    email: 'admin@example.com',
-    wwwPath: '/srv/www',
-    tlsMode: 'greenlock'
-});
-roster.start();
-```
-
-**Force static certs with a pre-loaded default cert (avoids SNI-less connection failures):**
-
-```javascript
-const roster = new Roster({
-    email: 'admin@example.com',
-    wwwPath: '/srv/www',
-    tlsMode: 'static',
-    tlsDomain: 'example.com'  // loaded as the server's fallback cert
-});
-roster.start();
-```
-
-**Custom TLS options (e.g. restrict ciphers):**
-
-```javascript
-const roster = new Roster({
-    email: 'admin@example.com',
-    wwwPath: '/srv/www',
-    tls: {
-        minVersion: 'TLSv1.2',
-        ciphers: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256'
-    }
-});
-roster.start();
-```
-
-### Smoke test
-
-After deploying, verify TLS is working:
-
-```bash
-curl -v https://example.com
-# Should show TLSv1.2 or TLSv1.3 in the handshake — no "alert protocol version" errors
-```
-
-Server logs will display the active mode on startup:
-
-```
-Runtime: bun | TLS mode: static
-HTTPS port 443: using static certs from /srv/greenlock.d/live [static]
-HTTPS server listening on port 443
-```
 
 ## 🏠 Local Development Mode
 
@@ -298,6 +225,8 @@ When `{ local: true }` is enabled, RosterServer **Skips SSL/HTTPS**: Runs pure H
 ### Setting Up Local Mode
 
 ```javascript
+import Roster from 'roster-server';
+
 const server = new Roster({
     wwwPath: '/srv/www',
     local: true,  // Enable local development mode
@@ -318,6 +247,8 @@ In local mode, domains are automatically assigned ports based on a CRC32 hash of
 You can customize the port range:
 
 ```javascript
+import Roster from 'roster-server';
+
 const roster = new Roster({ 
     local: true,
     minLocalPort: 5000,  // Start from port 5000
@@ -332,6 +263,8 @@ RosterServer provides a method to get the URL for a domain that adapts automatic
 **Instance Method: `roster.getUrl(domain)`**
 
 ```javascript
+import Roster from 'roster-server';
+
 const roster = new Roster({ local: true });
 roster.register('example.com', handler);
 
@@ -354,6 +287,8 @@ This method:
 **Example Usage:**
 
 ```javascript
+import Roster from 'roster-server';
+
 // Local development
 const localRoster = new Roster({ local: true });
 localRoster.register('example.com', handler);

package/demo/wildcard-example.js

@@ -0,0 +1,31 @@
+/**
+ * Wildcard DNS demo: one handler for all subdomains (*.example.com)
+ *
+ * Run from repo root: node demo/wildcard-example.js
+ * Then open the printed URL (or use curl with Host header) to see the wildcard response.
+ * Any subdomain (api.example.com, app.example.com, foo.example.com) uses the same handler.
+ */
+const Roster = require('../index.js');
+const path = require('path');
+const { wildcardRoot } = require('../index.js');
+
+const roster = new Roster({
+    local: true,
+    wwwPath: path.join(__dirname, 'www'),
+});
+
+roster.start().then(() => {
+    const wildcardPattern = roster.domains.find((d) => d.startsWith('*.'));
+    const subdomain = wildcardPattern ? 'api.' + wildcardRoot(wildcardPattern) : 'api.example.com';
+    const wildcardUrl = roster.getUrl(subdomain);
+
+    console.log('\n🌐 Wildcard demo');
+    console.log('   Loaded:', wildcardPattern ? `https://${wildcardPattern}` : '(none)');
+    console.log('   Any subdomain uses the same handler.\n');
+    console.log('   Try:', wildcardUrl || '(no wildcard site in www path)');
+    if (wildcardUrl) {
+        const host = wildcardPattern ? 'api.' + wildcardRoot(wildcardPattern) : 'api.example.com';
+        console.log('   Or:  curl -H "Host: ' + host + '"', wildcardUrl);
+    }
+    console.log('');
+});