roster-server 2.3.6 → 2.3.8

package/README.md

@@ -309,12 +309,13 @@ await roster.start();
 const url = roster.getUrl('example.com');
 console.log(url); 
 // Local mode: http://localhost:9465
+// Local subdomain: http://api.localhost:9465
 // Production mode: https://example.com
 ```
 
 This method:
 - Returns the correct URL based on your environment (`local: true/false`)
-- In **local mode**: Returns `http://localhost:{port}` with the assigned port
+- In **local mode**: Returns `http://localhost:{port}` for apex domains and `http://{subdomain}.localhost:{port}` for subdomains
 - In **production mode**: Returns `https://{domain}` (or with custom port if configured)
 - Handles `www.` prefix automatically (returns same URL)
 - Returns `null` for domains that aren't registered
@@ -327,9 +328,12 @@ import Roster from 'roster-server';
 // Local development
 const localRoster = new Roster({ local: true });
 localRoster.register('example.com', handler);
+localRoster.register('api.example.com', handler);
 await localRoster.start();
 console.log(localRoster.getUrl('example.com')); 
 // → http://localhost:9465
+console.log(localRoster.getUrl('api.example.com'));
+// → http://api.localhost:7342
 
 // Production
 const prodRoster = new Roster({ local: false });

package/docs/decisions/local-subdomain-localhost-url.md

@@ -0,0 +1,12 @@
+---
+id: wrxv04lnq9
+type: decision
+title: 'Decision: Local subdomain URL format'
+created: '2026-03-16 17:15:01'
+---
+# Decision: Local subdomain URL format
+
+**What**: In local mode, `getUrl(domain)` now returns `http://<subdomain>.localhost:<port>` for subdomains, while apex domains keep `http://localhost:<port>`.
+**Where**: Implemented in `index.js` (`getUrl` local branch), validated in `test/roster-server.test.js`, and documented in `README.md`.
+**Why**: Local URLs should preserve subdomain semantics so multi-tenant/subdomain routes are explicit and easier to test.
+**Alternatives rejected**: Keeping all local URLs as `http://localhost:<port>` was rejected because it hides host intent for subdomain-based apps.

package/index.js

@@ -606,7 +606,22 @@ class Roster {
         if (this.local) {
             const pattern = resolved.siteKey.split(':')[0];
             if (this.domainPorts && this.domainPorts[pattern] !== undefined) {
-                return `http://localhost:${this.domainPorts[pattern]}`;
+                const labels = cleanDomain.split('.').filter(Boolean);
+                let localHost = 'localhost';
+
+                // For wildcard matches, preserve the full left-side subdomain chain.
+                if (pattern.startsWith('*.')) {
+                    const root = wildcardRoot(pattern);
+                    if (root && hostMatchesWildcard(cleanDomain, pattern)) {
+                        const subdomain = cleanDomain.slice(0, -(root.length + 1));
+                        if (subdomain) localHost = `${subdomain}.localhost`;
+                    }
+                } else if (labels.length > 2) {
+                    // For exact subdomains (e.g. api.example.com), map to api.localhost.
+                    localHost = `${labels.slice(0, -2).join('.')}.localhost`;
+                }
+
+                return `http://${localHost}:${this.domainPorts[pattern]}`;
             }
             return null;
         }
@@ -778,7 +793,7 @@ class Roster {
                     }
                 }
                 if (!msg || msg === 'undefined') msg = `[${event}] (no details)`;
-                if (eventDomain && !msg.includes(`[domain:${eventDomain}]`)) {
+                if (eventDomain && !msg.includes(`[${eventDomain}]`)) {
                     msg = `[domain:${eventDomain}] ${msg}`;
                 }
                 // Suppress known benign warnings from ACME when using acme-dns-01-cli

package/package.json

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

package/test/roster-server.test.js

@@ -218,7 +218,7 @@ describe('Roster', () => {
             roster.register('*.example.com', () => {});
             roster.domainPorts = { '*.example.com': 9999 };
             roster.local = true;
-            assert.strictEqual(roster.getUrl('api.example.com'), 'http://localhost:9999');
+            assert.strictEqual(roster.getUrl('api.example.com'), 'http://api.localhost:9999');
         });
         it('returns https URL for wildcard-matched host in production', () => {
             const roster = new Roster({ local: false });
@@ -359,6 +359,13 @@ describe('Roster', () => {
             roster.local = true;
             assert.strictEqual(roster.getUrl('exact.local'), 'http://localhost:4567');
         });
+        it('returns http://subdomain.localhost:PORT in local mode for exact subdomain', () => {
+            const roster = new Roster({ local: true });
+            roster.register('api.example.com', () => {});
+            roster.domainPorts = { 'api.example.com': 5678 };
+            roster.local = true;
+            assert.strictEqual(roster.getUrl('api.example.com'), 'http://api.localhost:5678');
+        });
         it('returns https URL in production for registered domain', () => {
             const roster = new Roster({ local: false });
             roster.register('example.com', () => {});