feat(dev): hint about --host when bound to loopback in docker or wsl

Author: danielroe

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

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { release } from 'node:os'
+import process from 'node:process'
+
+let dockerCache: boolean | undefined
+let wslKernelCache: boolean | undefined
+
+/** Whether this process is running inside a Docker (or compatible) container. */
+export function isDocker(): boolean {
+  dockerCache ??= existsSync('/.dockerenv') || readTextFile('/proc/self/cgroup').includes('docker')
+  return dockerCache
+}
+
+/**
+ * Whether this process is running under the Windows Subsystem for Linux.
+ *
+ * WSL1 spells the kernel release `Microsoft`, WSL2 `microsoft-standard-WSL2`.
+ * A custom-kernel WSL2 install has neither, so `/proc/version` is checked too.
+ */
+export function isWsl(platform: NodeJS.Platform = process.platform, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (platform !== 'linux') {
+    return false
+  }
+  if (env.WSL_DISTRO_NAME) {
+    return true
+  }
+  wslKernelCache ??= release().toLowerCase().includes('microsoft')
+    || readTextFile('/proc/version').toLowerCase().includes('microsoft')
+  return wslKernelCache
+}
+
+/**
+ * The name of the container-like environment a loopback bind is unreachable
+ * from, or `undefined` when the dev server is running directly on the host.
+ */
+export function detectIsolatedEnvironment(): string | undefined {
+  if (isDocker()) {
+    return 'the container'
+  }
+  if (isWsl()) {
+    return 'WSL'
+  }
+}
+
+function readTextFile(path: string): string {
+  try {
+    return readFileSync(path, 'utf8')
+  }
+  catch {
+    return ''
+  }
+}

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

@@ -6,14 +6,15 @@ import type { Tunnel } from './tunnel'
 import { spawn } from 'node:child_process'
 import { createServer as createHttpServer } from 'node:http'
 import { createServer as createHttpsServer } from 'node:https'
-import { networkInterfaces, release } from 'node:os'
+import { networkInterfaces } from 'node:os'
 import process from 'node:process'
 
 import { getPort } from 'get-port-please'
 import colors from 'picocolors'
 
 import { debug, logger } from '../utils/logger'
 import { resolveCertificate } from './cert'
+import { detectIsolatedEnvironment, isWsl } from './environment'
 import { resolvePortlessURLs } from './portless'
 import { startTunnel } from './tunnel'
 
@@ -64,6 +65,7 @@ export interface Listener {
 }
 
 const ANY_HOSTS = new Set(['', '0.0.0.0', '::'])
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1'])
 
 const HOSTNAME_RE = /^(?!-)[\d.:a-z-]{1,253}(?<!-)$/i
 
@@ -202,7 +204,11 @@ export async function listen(handler: RequestListener, options: ListenOptions =
       lines.push(line(labelColors[type], labels[type], colors.cyan(displayURL), qr && displayURL === qrURL))
     }
     if (!anyHost && !tunnel && !portless.url) {
-      lines.push(line(colors.magenta, 'Network:', colors.gray(`use ${colors.white('--host')} to expose`), false))
+      const isolated = LOOPBACK_HOSTS.has(hostname) ? detectIsolatedEnvironment() : undefined
+      const hint = isolated
+        ? `use ${colors.white('--host')} to reach this server from outside ${isolated}`
+        : `use ${colors.white('--host')} to expose`
+      lines.push(line(colors.magenta, 'Network:', colors.gray(hint), false))
     }
     if (publicURL && publicURL !== url && !urls.some(entry => entry.url === publicURL)) {
       lines.push(line(colors.magenta, 'Public:', colors.cyan(publicURL), qr && publicURL === qrURL))
@@ -365,18 +371,14 @@ export function resolveOpenCommand(
       : [browser, [...browserArgs, url]]
   }
 
-  // WSL reports itself as Linux but has no X server, so `xdg-open` fails there;
-  // `cmd.exe` opens the browser on the Windows side instead. WSL1 spells the
-  // release `Microsoft`, WSL2 `microsoft-standard-WSL2`.
-  const isWSL = platform === 'linux'
-    && (!!env.WSL_DISTRO_NAME || release().toLowerCase().includes('microsoft'))
-
   if (platform === 'darwin') {
     return ['open', [url]]
   }
   // `cmd /c start` owns the arcane quoting rules; `""` is a dummy window title
   // (otherwise `start` treats a quoted URL as one), and `&`/`^` need escaping.
-  if (platform === 'win32' || isWSL) {
+  // WSL reports itself as Linux but has no X server, so `xdg-open` fails there;
+  // `cmd.exe` opens the browser on the Windows side instead.
+  if (platform === 'win32' || isWsl(platform, env)) {
     return ['cmd.exe', ['/c', 'start', '""', url.replace(/[&^]/g, '^$&')]]
   }
   return ['xdg-open', [url]]

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

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { existsSync, readFileSync, release } = vi.hoisted(() => ({
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => ''),
+  release: vi.fn(() => '6.1.0-generic'),
+}))
+
+vi.mock('node:fs', () => ({ existsSync, readFileSync }))
+vi.mock('node:os', () => ({ release }))
+
+/** Re-import so the module-level detection caches start empty. */
+async function loadEnvironment() {
+  vi.resetModules()
+  return import('../../src/dev/environment')
+}
+
+const realPlatform = process.platform
+
+function stubPlatform(platform: NodeJS.Platform) {
+  Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+}
+
+beforeEach(() => {
+  existsSync.mockReturnValue(false)
+  readFileSync.mockReturnValue('')
+  release.mockReturnValue('6.1.0-generic')
+})
+
+afterEach(() => {
+  stubPlatform(realPlatform)
+  vi.clearAllMocks()
+})
+
+describe('isDocker', () => {
+  it('should detect `/.dockerenv`', async () => {
+    existsSync.mockReturnValue(true)
+    const { isDocker } = await loadEnvironment()
+
+    expect(isDocker()).toBe(true)
+  })
+
+  it('should detect a docker cgroup', async () => {
+    readFileSync.mockReturnValue('0::/docker/abc123')
+    const { isDocker } = await loadEnvironment()
+
+    expect(isDocker()).toBe(true)
+  })
+
+  it('should cache the result', async () => {
+    const { isDocker } = await loadEnvironment()
+
+    expect(isDocker()).toBe(false)
+    existsSync.mockReturnValue(true)
+    expect(isDocker()).toBe(false)
+  })
+
+  it('should not detect docker on a plain host', async () => {
+    const { isDocker } = await loadEnvironment()
+
+    expect(isDocker()).toBe(false)
+  })
+})
+
+describe('isWsl', () => {
+  it('should detect `WSL_DISTRO_NAME`', async () => {
+    const { isWsl } = await loadEnvironment()
+
+    expect(isWsl('linux', { WSL_DISTRO_NAME: 'Ubuntu' })).toBe(true)
+  })
+
+  it('should detect a microsoft kernel release', async () => {
+    release.mockReturnValue('5.15.0-microsoft-standard-WSL2')
+    const { isWsl } = await loadEnvironment()
+
+    expect(isWsl('linux', {})).toBe(true)
+  })
+
+  it('should detect microsoft in `/proc/version`', async () => {
+    readFileSync.mockReturnValue('Linux version 5.15.0 (Microsoft@Microsoft.com)')
+    const { isWsl } = await loadEnvironment()
+
+    expect(isWsl('linux', {})).toBe(true)
+  })
+
+  it('should be false off linux', async () => {
+    release.mockReturnValue('5.15.0-microsoft-standard-WSL2')
+    const { isWsl } = await loadEnvironment()
+
+    expect(isWsl('darwin', { WSL_DISTRO_NAME: 'Ubuntu' })).toBe(false)
+    expect(isWsl('win32', {})).toBe(false)
+  })
+
+  it('should be false on plain linux', async () => {
+    const { isWsl } = await loadEnvironment()
+
+    expect(isWsl('linux', {})).toBe(false)
+  })
+})
+
+describe('detectIsolatedEnvironment', () => {
+  it('should prefer the container over WSL', async () => {
+    existsSync.mockReturnValue(true)
+    release.mockReturnValue('5.15.0-microsoft-standard-WSL2')
+    const { detectIsolatedEnvironment } = await loadEnvironment()
+
+    expect(detectIsolatedEnvironment()).toBe('the container')
+  })
+
+  it('should report WSL', async () => {
+    stubPlatform('linux')
+    release.mockReturnValue('5.15.0-microsoft-standard-WSL2')
+    const { detectIsolatedEnvironment } = await loadEnvironment()
+
+    expect(detectIsolatedEnvironment()).toBe('WSL')
+  })
+
+  it('should report nothing on a plain host', async () => {
+    const { detectIsolatedEnvironment } = await loadEnvironment()
+
+    expect(detectIsolatedEnvironment()).toBeUndefined()
+  })
+})