feat(vhost): match req.hostname when present for reverse proxy support

Route by the framework-resolved req.hostname (Express 5, respects
trust proxy / X-Forwarded-Host) when present, falling back to the raw
Host header for plain Node.js / connect servers. req.vhost.host is
populated from the same resolved value, so it reflects the host that
routing actually used.

Fixes #20, supersedes #21

Author: sheplu

HISTORY.md

@@ -1,6 +1,9 @@
 4.0.0 / 2026-06-10
 ==================
 
+  * Match against `req.hostname` when present (Express 5), falling back to the
+    `Host` header, so routing works behind reverse proxies with `trust proxy`
+    (#20); `req.vhost.host` reflects the value routing actually used
   * Rewrite in TypeScript; ship ESM only with bundled type declarations
   * Drop support for Node.js below 24; require Node.js 24 or newer
   * **Breaking:** package is now ESM (`import vhost from 'vhost'`); `require()` is

README.md

@@ -31,6 +31,12 @@ contain `*` to match 1 or more characters in that section of the hostname. When
 `hostname` is a RegExp, it will be forced to case-insensitive (since hostnames are)
 and will be forced to match based on the start and end of the hostname.
 
+The host used for matching is `req.hostname` when the framework provides one
+(Express 5 populates it, respecting `trust proxy` so hosts forwarded through a
+reverse proxy via `X-Forwarded-Host` are honored), otherwise the raw
+[`Host` header](https://nodejs.org/dist/latest/docs/api/http.html#messageheaders)
+(plain Node.js / connect servers).
+
 When host is matched and the request is sent down to a vhost handler, the `req.vhost`
 property will be populated with an object. This object will have numeric properties
 corresponding to each wildcard (or capture group if RegExp object provided) and the

src/index.ts

@@ -12,9 +12,12 @@
  * Numeric keys `0..length-1` hold the captured wildcard / RegExp group values.
  */
 export interface VHost {
-  /** The raw `Host` header, including the port if one was present. */
+  /**
+   * The host value the request was routed by: `req.hostname` when the
+   * framework provided one, otherwise the raw `Host` header (port included).
+   */
   host: string
-  /** The `Host` header with any port stripped. */
+  /** The routed host with any port stripped. */
   hostname: string
   /** The number of captured wildcards / RegExp groups. */
   length: number
@@ -29,6 +32,12 @@ export interface VHost {
  */
 export interface VHostRequest {
   headers: { host?: string | undefined }
+  /**
+   * Framework-resolved hostname, e.g. Express 5's `req.hostname`. When present
+   * it takes precedence over the `Host` header, so the middleware works behind
+   * reverse proxies when `trust proxy` resolves `X-Forwarded-Host`.
+   */
+  hostname?: string | undefined
   vhost?: VHost
 }
 
@@ -103,7 +112,7 @@ export default function vhost<Req extends VHostRequest = VHostRequest, Res = unk
       : (name: string): boolean => regexp.test(name)
 
     return function vhost (req, res, next) {
-      const host = req.headers.host
+      const host = hostof(req)
 
       if (!host) {
         return next()
@@ -142,7 +151,7 @@ export default function vhost<Req extends VHostRequest = VHostRequest, Res = unk
     const minLen = hostname.length
 
     return function vhost (req, res, next) {
-      const host = req.headers.host
+      const host = hostof(req)
 
       if (!host) {
         return next()
@@ -167,7 +176,7 @@ export default function vhost<Req extends VHostRequest = VHostRequest, Res = unk
 
   // RegExp hostname: unchanged regex path.
   return function vhost (req, res, next) {
-    const host = req.headers.host
+    const host = hostof(req)
 
     if (!host) {
       return next()
@@ -190,9 +199,20 @@ export default function vhost<Req extends VHostRequest = VHostRequest, Res = unk
   }
 }
 
+/**
+ * Get the host value to route by: the framework-resolved `req.hostname`
+ * (Express 5, respects `trust proxy` / `X-Forwarded-Host`) when present,
+ * otherwise the raw `Host` header.
+ */
+function hostof (req: VHostRequest): string | undefined {
+  return req.hostname || req.headers.host
+}
+
 /**
  * Get the hostname (port stripped) from a raw `Host` header value, handling
- * IPv6 literals such as `[::1]:8080`.
+ * IPv6 literals such as `[::1]:8080`. Values from `req.hostname` are already
+ * port-free (and IPv6 literals stay bracketed), so re-parsing them here is a
+ * no-op.
  */
 function hostnameof (host: string): string | undefined {
   if (!host) {

test/test.mjs

@@ -160,6 +160,127 @@ describe('vhost(hostname, server)', function () {
       .expect(200, 'undefined', done)
   })
 
+  describe('with req.hostname (express 5 / reverse proxy)', function () {
+    it('should route by req.hostname over the Host header', function (_, done) {
+      var vhosts = []
+
+      vhosts.push(vhost('proxied.com', proxied))
+      vhosts.push(vhost('direct.com', direct))
+
+      var app = createServer(vhosts, null, function (req) {
+        // what express 5 provides with `trust proxy` from X-Forwarded-Host
+        req.hostname = 'proxied.com'
+      })
+
+      function proxied (req, res) { res.end('proxied') }
+      function direct (req, res) { res.end('direct') }
+
+      request(app)
+        .get('/')
+        .set('Host', 'direct.com')
+        .expect(200, 'proxied', done)
+    })
+
+    it('should reflect the routed value on req.vhost.host and hostname', function (_, done) {
+      var app = createServer('proxied.com', function (req, res) {
+        res.end(JSON.stringify({ host: req.vhost.host, hostname: req.vhost.hostname }))
+      }, function (req) {
+        req.hostname = 'proxied.com'
+      })
+
+      request(app)
+        .get('/')
+        .set('Host', 'direct.com:8080')
+        .expect(200, '{"host":"proxied.com","hostname":"proxied.com"}', done)
+    })
+
+    it('should match a wildcard against req.hostname and capture from it', function (_, done) {
+      var app = createServer('*.proxied.com', function (req, res) {
+        res.end(JSON.stringify([req.vhost.length, req.vhost[0], req.vhost.hostname]))
+      }, function (req) {
+        req.hostname = 'foo.proxied.com'
+      })
+
+      request(app)
+        .get('/')
+        .set('Host', 'direct.com')
+        .expect(200, '[1,"foo","foo.proxied.com"]', done)
+    })
+
+    it('should match a RegExp against req.hostname', function (_, done) {
+      var app = createServer(/user-(bob|joe)\.proxied\.com/, function (req, res) {
+        res.end(JSON.stringify([req.vhost.length, req.vhost[0]]))
+      }, function (req) {
+        req.hostname = 'user-bob.proxied.com'
+      })
+
+      request(app)
+        .get('/')
+        .set('Host', 'direct.com')
+        .expect(200, '[1,"bob"]', done)
+    })
+
+    it('should 404 when req.hostname does not match', function (_, done) {
+      var app = createServer('proxied.com', function (req, res) {
+        res.end('proxied')
+      }, function (req) {
+        // Host header would match, but the resolved hostname wins
+        req.hostname = 'other.com'
+      })
+
+      request(app)
+        .get('/')
+        .set('Host', 'proxied.com')
+        .expect(404, done)
+    })
+
+    it('should fall back to the Host header when req.hostname is empty', function (_, done) {
+      var app = createServer('direct.com', function (req, res) {
+        res.end('direct')
+      }, function (req) {
+        req.hostname = ''
+      })
+
+      request(app)
+        .get('/')
+        .set('Host', 'direct.com')
+        .expect(200, 'direct', done)
+    })
+
+    it('should not re-strip a portless IPv6 req.hostname', function (_, done) {
+      // req.hostname is already port-free; re-parsing the bracketed literal
+      // must be a no-op, not mangle it to an empty string
+      var app = createServer('[::1]', function (req, res) {
+        res.end(JSON.stringify({ host: req.vhost.host, hostname: req.vhost.hostname }))
+      }, function (req) {
+        req.hostname = '[::1]'
+      })
+
+      request(app)
+        .get('/')
+        .set('Host', 'direct.com:8080')
+        .expect(200, '{"host":"[::1]","hostname":"[::1]"}', done)
+    })
+
+    it('should call next() when neither req.hostname nor Host is present', function (_, done) {
+      var app = http.createServer(function onRequest (req, res) {
+        req.headers.host = undefined
+
+        var mw = vhost('proxied.com', function (req, res) {
+          res.end('handled')
+        })
+
+        mw(req, res, function () {
+          res.end('next:' + String(req.vhost))
+        })
+      })
+
+      request(app)
+        .get('/')
+        .expect(200, 'next:undefined', done)
+    })
+  })
+
   describe('arguments', function () {
     describe('hostname', function () {
       it('should be required', function () {
@@ -699,12 +820,16 @@ describe('vhost(hostname, server)', function () {
   })
 })
 
-function createServer (hostname, server) {
+function createServer (hostname, server, pretest) {
   var vhosts = !Array.isArray(hostname)
     ? [vhost(hostname, server)]
     : hostname
 
   return http.createServer(function onRequest (req, res) {
+    // allows changes to the request/response objects before the middleware,
+    // e.g. simulating the `req.hostname` an Express 5 app would provide
+    if (pretest) pretest(req, res)
+
     var index = 0
 
     function next (err) {