fix(dev): warn on invalid --host and explain failed binds

Author: danielroe

packages/nuxt-cli/src/dev/listen.ts

@@ -65,6 +65,24 @@ export interface Listener {
 
 const ANY_HOSTS = new Set(['', '0.0.0.0', '::'])
 
+const HOSTNAME_RE = /^(?!-)[\d.:a-z-]{1,253}(?<!-)$/i
+
+/**
+ * Check `hostname` is a plausible host or IP address, falling back to a
+ * bindable default (with a warning) when it is not.
+ */
+export function validateHostname(hostname: string | undefined, isPublic?: boolean): string | undefined {
+  const isValid = !!hostname
+    && HOSTNAME_RE.test(hostname)
+    && hostname.split('.').every(label => label.length <= 63)
+  if (!hostname || isValid) {
+    return hostname
+  }
+  const fallback = isPublic ? '' : 'localhost'
+  logger.warn(`Invalid host \`${hostname}\`, using \`${fallback || '0.0.0.0'}\` instead.`)
+  return fallback
+}
+
 /**
  * External IPv4 addresses other devices can reach. IPv4 link-local addresses
  * (169.254.0.0/16, from a macOS Thunderbolt Bridge or an unconfigured adapter)
@@ -105,7 +123,7 @@ function createSecureServer(certificate: ResolvedCertificate, handler: RequestLi
 }
 
 export async function listen(handler: RequestListener, options: ListenOptions = {}): Promise<Listener> {
-  const hostname = options.hostname ?? (options.public ? '' : 'localhost')
+  const hostname = validateHostname(options.hostname, options.public) ?? (options.public ? '' : 'localhost')
 
   const requestedPort = options.port === undefined || options.port === '' ? undefined : Number(options.port)
   const port = await resolvePort(requestedPort, hostname, options.strictPort)
@@ -264,6 +282,8 @@ function describeBindError(error: NodeJS.ErrnoException, port: number, hostname:
       return new Error(`Port ${port} requires elevated privileges. Pass \`--port\` with a port above 1023.`, { cause: error })
     case 'EADDRNOTAVAIL':
       return new Error(`\`${hostname}\` is not an address of this machine. Pass \`--host\` with a local address, or omit it to listen on localhost.`, { cause: error })
+    case 'ENOTFOUND':
+      return new Error(`\`${hostname}\` could not be resolved. Pass \`--host\` with a local address, or omit it to listen on localhost.`, { cause: error })
   }
   return error
 }

packages/nuxt-cli/test/unit/listen.spec.ts

@@ -4,7 +4,7 @@ import { networkInterfaces } from 'node:os'
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { copyURL, getNetworkAddresses, listen, openBrowser, resolveOpenCommand } from '../../src/dev/listen'
+import { copyURL, getNetworkAddresses, listen, openBrowser, resolveOpenCommand, validateHostname } from '../../src/dev/listen'
 
 const writeText = vi.hoisted(() => vi.fn())
 
@@ -62,6 +62,28 @@ describe('getNetworkAddresses', () => {
   })
 })
 
+describe('validateHostname', () => {
+  it('should pass through valid hosts', () => {
+    expect(validateHostname('localhost')).toBe('localhost')
+    expect(validateHostname('127.0.0.1')).toBe('127.0.0.1')
+    expect(validateHostname('::1')).toBe('::1')
+    expect(validateHostname('my-app.example.com')).toBe('my-app.example.com')
+    expect(validateHostname('')).toBe('')
+    expect(validateHostname(undefined)).toBeUndefined()
+  })
+
+  it('should fall back to `localhost` for an invalid host', () => {
+    expect(validateHostname('local host')).toBe('localhost')
+    expect(validateHostname('http://localhost')).toBe('localhost')
+    expect(validateHostname('-nope')).toBe('localhost')
+    expect(validateHostname(`${'a'.repeat(64)}.com`)).toBe('localhost')
+  })
+
+  it('should fall back to all interfaces when public', () => {
+    expect(validateHostname('local host', true)).toBe('')
+  })
+})
+
 describe('resolveOpenCommand', () => {
   const url = 'http://localhost:3000/'
 
@@ -139,6 +161,12 @@ describe('listen', () => {
     expect(spawn.mock.lastCall?.[1]).toContain('https://example.com/foo')
   })
 
+  it('should bind a fallback host for an invalid `hostname`', async () => {
+    const listener = await start({ port: 0, hostname: 'not a host' })
+
+    expect(listener.url).toBe(`http://localhost:${listener.address.port}/`)
+  })
+
   it('should use the requested port with `strictPort`', async () => {
     const { address } = await start({ port: 0 })
     const port = address.port