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'
+importprocessfrom'node:process'
+
+letdockerCache: boolean|undefined
+letwslKernelCache: boolean|undefined
+
+/** Whether this process is running inside a Docker (or compatible) container. */
+exportfunctionisDocker(): boolean{
+dockerCache??=existsSync('/.dockerenv')||readTextFile('/proc/self/cgroup').includes('docker')
+returndockerCache
+}
+
+/**
+ * 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.
+ */
+exportfunctionisWsl(platform: NodeJS.Platform=process.platform,env: NodeJS.ProcessEnv=process.env): boolean{
+if(platform!=='linux'){
+returnfalse
+}
+if(env.WSL_DISTRO_NAME){
+returntrue
+}
+wslKernelCache??=release().toLowerCase().includes('microsoft')
+||readTextFile('/proc/version').toLowerCase().includes('microsoft')
+returnwslKernelCache
+}
+
+/**
+ * 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.
+ */
+exportfunctiondetectIsolatedEnvironment(): string|undefined{
+if(isDocker()){
+return'the container'
+}
+if(isWsl()){
+return'WSL'
+}
+}
+
+functionreadTextFile(path: string): string{
+try{
+returnreadFileSync(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{createServerascreateHttpServer}from'node:http'
 import{createServerascreateHttpsServer}from'node:https'
-import{networkInterfaces,release}from'node:os'
+import{networkInterfaces}from'node:os'
 importprocessfrom'node:process'
 
 import{getPort}from'get-port-please'
 importcolorsfrom'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 {
 }
 
 constANY_HOSTS=newSet(['','0.0.0.0','::'])
+constLOOPBACK_HOSTS=newSet(['localhost','127.0.0.1','::1'])
 
 constHOSTNAME_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))
+constisolated=LOOPBACK_HOSTS.has(hostname) ? detectIsolatedEnvironment() : undefined
+consthint=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`.
-constisWSL=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. */
+asyncfunctionloadEnvironment(){
+vi.resetModules()
+returnimport('../../src/dev/environment')
+}
+
+constrealPlatform=process.platform
+
+functionstubPlatform(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 }=awaitloadEnvironment()
+
+expect(isDocker()).toBe(true)
+})
+
+it('should detect a docker cgroup',async()=>{
+readFileSync.mockReturnValue('0::/docker/abc123')
+const{ isDocker }=awaitloadEnvironment()
+
+expect(isDocker()).toBe(true)
+})
+
+it('should cache the result',async()=>{
+const{ isDocker }=awaitloadEnvironment()
+
+expect(isDocker()).toBe(false)
+existsSync.mockReturnValue(true)
+expect(isDocker()).toBe(false)
+})
+
+it('should not detect docker on a plain host',async()=>{
+const{ isDocker }=awaitloadEnvironment()
+
+expect(isDocker()).toBe(false)
+})
+})
+
+describe('isWsl',()=>{
+it('should detect `WSL_DISTRO_NAME`',async()=>{
+const{ isWsl }=awaitloadEnvironment()
+
+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 }=awaitloadEnvironment()
+
+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 }=awaitloadEnvironment()
+
+expect(isWsl('linux',{})).toBe(true)
+})
+
+it('should be false off linux',async()=>{
+release.mockReturnValue('5.15.0-microsoft-standard-WSL2')
+const{ isWsl }=awaitloadEnvironment()
+
+expect(isWsl('darwin',{WSL_DISTRO_NAME: 'Ubuntu'})).toBe(false)
+expect(isWsl('win32',{})).toBe(false)
+})
+
+it('should be false on plain linux',async()=>{
+const{ isWsl }=awaitloadEnvironment()
+
+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 }=awaitloadEnvironment()
+
+expect(detectIsolatedEnvironment()).toBe('the container')
+})
+
+it('should report WSL',async()=>{
+stubPlatform('linux')
+release.mockReturnValue('5.15.0-microsoft-standard-WSL2')
+const{ detectIsolatedEnvironment }=awaitloadEnvironment()
+
+expect(detectIsolatedEnvironment()).toBe('WSL')
+})
+
+it('should report nothing on a plain host',async()=>{
+const{ detectIsolatedEnvironment }=awaitloadEnvironment()
+
+expect(detectIsolatedEnvironment()).toBeUndefined()
+})
+})