fix(dev): do not report or restart on broken pipes

Author: danielroe

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

@@ -5,6 +5,8 @@ import type { NuxtDevContext, NuxtDevIPCMessage, NuxtParentIPCMessage } from './
 import process from 'node:process'
 import defu from 'defu'
 import { overrideEnv } from '../utils/env.ts'
+import { isBrokenPipe } from '../utils/errors'
+import { debug } from '../utils/logger'
 import { startCpuProfile, stopCpuProfile } from '../utils/profile.ts'
 import { NuxtDevServer } from './utils'
 
@@ -165,12 +167,21 @@ export async function initialize(devContext: NuxtDevContext, ctx: InitializeOpti
       function restart() {
         if (!restarted) {
           restarted = true
+          process.off('uncaughtException', restartOnError)
+          process.off('unhandledRejection', restartOnError)
           callback(devServer)
         }
       }
+      function restartOnError(error: unknown) {
+        if (isBrokenPipe(error)) {
+          debug('Ignoring broken pipe:', error)
+          return
+        }
+        restart()
+      }
       devServer.once('restart', restart)
-      process.once('uncaughtException', restart)
-      process.once('unhandledRejection', restart)
+      process.on('uncaughtException', restartOnError)
+      process.on('unhandledRejection', restartOnError)
     },
   }
 }

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

@@ -257,6 +257,10 @@ export async function printQRCode(url: string): Promise<void> {
 }
 
 export async function copyURL(url: string): Promise<void> {
+  if (!isClipboardAvailable()) {
+    logger.warn('No clipboard is available in this environment.')
+    return
+  }
   try {
     const { writeText } = await import('tinyclip')
     await writeText(url)
@@ -268,6 +272,20 @@ export async function copyURL(url: string): Promise<void> {
   }
 }
 
+const DISPLAY_REQUIRED_PLATFORMS = new Set<NodeJS.Platform>(['linux', 'freebsd', 'openbsd'])
+
+/**
+ * Clipboard tools on Linux and BSD (`wl-copy`, `xsel`, `xclip`) need a display
+ * server. Without one they exit before receiving any input, and the resulting
+ * `EPIPE` escapes as an uncaught exception from inside the writing library.
+ */
+function isClipboardAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (!DISPLAY_REQUIRED_PLATFORMS.has(process.platform)) {
+    return true
+  }
+  return !!(env.WSL_DISTRO_NAME || env.WAYLAND_DISPLAY || env.DISPLAY)
+}
+
 function centerBlock(block: string): string {
   const lines = block.split('\n')
   const width = Math.max(...lines.map(line => line.length))

packages/nuxt-cli/src/utils/console.ts

@@ -4,6 +4,9 @@ import process from 'node:process'
 
 import { consola } from 'consola'
 
+import { isBrokenPipe } from './errors'
+import { debug } from './logger'
+
 // Filter out unwanted logs
 // TODO: Use better API from consola for intercepting logs
 function wrapReporter(reporter: ConsolaReporter) {
@@ -37,9 +40,15 @@ export function setupGlobalConsole(opts: { dev?: boolean } = {}) {
     consola.wrapConsole()
   }
 
-  process.on('unhandledRejection', err =>
-    consola.error('[unhandledRejection]', err))
+  process.on('unhandledRejection', err => report('[unhandledRejection]', err))
+
+  process.on('uncaughtException', err => report('[uncaughtException]', err))
+}
 
-  process.on('uncaughtException', err =>
-    consola.error('[uncaughtException]', err))
+function report(label: string, error: unknown) {
+  if (isBrokenPipe(error)) {
+    debug(`${label} ignoring broken pipe:`, error)
+    return
+  }
+  consola.error(label, error)
 }

packages/nuxt-cli/src/utils/errors.ts

@@ -0,0 +1,10 @@
+/**
+ * A pipe closing early is a property of the other end of the pipe, not a fault
+ * in the dev server: a clipboard tool that exited before we wrote to it, or
+ * `nuxt dev | head` closing stdout. Such errors should never be reported as
+ * crashes or trigger a restart.
+ */
+export function isBrokenPipe(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code
+  return code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED'
+}

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+
+import { isBrokenPipe } from '../../src/utils/errors'
+
+describe('isBrokenPipe', () => {
+  it('should detect closed pipes', () => {
+    expect(isBrokenPipe(Object.assign(new Error('write EPIPE'), { code: 'EPIPE' }))).toBe(true)
+    expect(isBrokenPipe(Object.assign(new Error('destroyed'), { code: 'ERR_STREAM_DESTROYED' }))).toBe(true)
+  })
+
+  it('should ignore other errors', () => {
+    expect(isBrokenPipe(new Error('boom'))).toBe(false)
+    expect(isBrokenPipe(Object.assign(new Error('nope'), { code: 'ENOENT' }))).toBe(false)
+    expect(isBrokenPipe(undefined)).toBe(false)
+  })
+})

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

@@ -4,7 +4,11 @@ import { networkInterfaces } from 'node:os'
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import { getNetworkAddresses, listen, resolveOpenCommand } from '../../src/dev/listen'
+import { copyURL, getNetworkAddresses, listen, resolveOpenCommand } from '../../src/dev/listen'
+
+const writeText = vi.hoisted(() => vi.fn())
+
+vi.mock('tinyclip', () => ({ writeText }))
 
 const spawn = vi.hoisted(() => vi.fn((_command: string, _args: string[]) => ({ on: () => ({ unref: () => {} }) })))
 
@@ -118,3 +122,50 @@ describe('listen', () => {
     expect(listener.address.port).toBe(port)
   })
 })
+
+describe('copyURL', () => {
+  const platform = process.platform
+  const env = { ...process.env }
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+    process.env = { ...env }
+    vi.clearAllMocks()
+  })
+
+  function stubPlatform(value: NodeJS.Platform, overrides: NodeJS.ProcessEnv = {}) {
+    Object.defineProperty(process, 'platform', { value, configurable: true })
+    process.env = { ...env, DISPLAY: undefined, WAYLAND_DISPLAY: undefined, WSL_DISTRO_NAME: undefined, ...overrides }
+  }
+
+  it('should skip copying without a display server on linux', async () => {
+    stubPlatform('linux')
+
+    await copyURL('http://localhost:3000/')
+
+    expect(writeText).not.toHaveBeenCalled()
+  })
+
+  it('should copy when a display server is available', async () => {
+    stubPlatform('linux', { DISPLAY: ':0' })
+
+    await copyURL('http://localhost:3000/')
+
+    expect(writeText).toHaveBeenCalledWith('http://localhost:3000/')
+  })
+
+  it('should copy on platforms that do not need a display server', async () => {
+    stubPlatform('darwin')
+
+    await copyURL('http://localhost:3000/')
+
+    expect(writeText).toHaveBeenCalledWith('http://localhost:3000/')
+  })
+
+  it('should warn rather than throw when copying fails', async () => {
+    stubPlatform('darwin')
+    writeText.mockRejectedValueOnce(new Error('no clipboard tool found'))
+
+    await expect(copyURL('http://localhost:3000/')).resolves.toBeUndefined()
+  })
+})