fix(dev): pin cloudflared version and shut tunnels down gracefully

Author: danielroe

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

@@ -26,13 +26,17 @@ interface ConsentOptions {
 /**
  * Resolve a third-party tool binary: from `PATH`, then the download cache,
  * then (with the user's consent) by downloading it.
+ *
+ * `cacheName` overrides the cached filename, so version-pinned tools can key
+ * their cache entry by version without affecting the `PATH` lookup.
  */
-exportasyncfunctionresolveTool(name: string,options: {url?: string,archive?: boolean,consent: ConsentOptions}): Promise<string|undefined>{
+exportasyncfunctionresolveTool(name: string,options: {url?: string,archive?: boolean,cacheName?: string,consent: ConsentOptions}): Promise<string|undefined>{
 constexisting=findInPath(name)
 if(existing){
 returnexisting
 }
-constdestination=join(getCacheDir('bin'),process.platform==='win32' ? `${name}.exe` : name)
+constcacheName=options.cacheName||name
+constdestination=join(getCacheDir('bin'),process.platform==='win32' ? `${cacheName}.exe` : cacheName)
 if(existsSync(destination)){
 returndestination
 }
@@ -129,6 +133,11 @@ async function downloadBinary(url: string, destination: string, options: { archi
 writeFileSync(archivePath,data)
 execFileSync('tar',['-xzf',archivePath,'-C',stagingDir],{stdio: 'ignore'})
 rmSync(archivePath)
+// Archives are named after the tool, not the cache entry.
+constextracted=join(stagingDir,options.name||basename(destination))
+if(extracted!==staged&&existsSync(extracted)){
+renameSync(extracted,staged)
+}
 }
 else{
 writeFileSync(staged,data)

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

@@ -197,8 +197,8 @@ export async function listen(handler: RequestListener, options: ListenOptions =
  server,
 https: certificate,
  getURLs,
-close: ()=>{
-tunnel?.close()
+close: async()=>{
+awaittunnel?.close()
 returnnewPromise<void>((resolve,reject)=>{
 server.close(error=>(error ? reject(error) : resolve()))
 server.closeAllConnections?.()

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

@@ -1,16 +1,26 @@
 importtype{Buffer}from'node:buffer'
 
 import{spawn}from'node:child_process'
+import{once}from'node:events'
 importprocessfrom'node:process'
 
 import{debug,logger}from'../utils/logger'
 import{resolveTool}from'./binaries'
 
 constTUNNEL_URL_RE=/https:\/\/(?!api\.)[\w-]+\.trycloudflare\.com/
 
+/**
+ * Pinned so a bad Cloudflare release cannot break `--tunnel` for everyone.
+ * Set `CLOUDFLARED_VERSION` (or `latest`) to override.
+ */
+constCLOUDFLARED_VERSION=process.env.CLOUDFLARED_VERSION||'2026.7.3'
+
+/** How long to wait for `cloudflared` to exit on `SIGINT` before `SIGKILL`. */
+constSHUTDOWN_TIMEOUT_MS=5000
+
 exportinterfaceTunnel{
 url: string
-close: ()=>void
+close: ()=>Promise<void>
 }
 
 exportasyncfunctionstartTunnel(localURL: string,insecure?: boolean): Promise<Tunnel|undefined>{
@@ -27,10 +37,20 @@ export async function startTunnel(localURL: string, insecure?: boolean): Promise
 constchild=spawn(binary,args,{stdio: ['ignore','pipe','pipe']})
 
 letoutput=''
+constrecentOutput: string[]=[]
 consturl=awaitnewPromise<string|undefined>((resolve)=>{
 consttimeout=setTimeout(resolve,20_000,undefined)
 constonData=(chunk: Buffer)=>{
-output+=chunk.toString()
+consttext=chunk.toString()
+output+=text
+for(constlineoftext.split('\n')){
+if(line.trim()){
+recentOutput.push(line.trim())
+}
+}
+if(recentOutput.length>10){
+recentOutput.splice(0,recentOutput.length-10)
+}
 constmatch=output.match(TUNNEL_URL_RE)
 if(match){
 clearTimeout(timeout)
@@ -55,7 +75,10 @@ export async function startTunnel(localURL: string, insecure?: boolean): Promise
 if(!url){
 child.kill()
 debug('cloudflared output:',output)
-logger.warn('Could not establish a Cloudflare quick tunnel. Run with `DEBUG=nuxi` for details.')
+logger.warn([
+'Could not establish a Cloudflare quick tunnel.',
+ ...recentOutput.map(line=>` ${line}`),
+].join('\n'))
 returnundefined
 }
 
@@ -72,7 +95,7 @@ export async function startTunnel(localURL: string, insecure?: boolean): Promise
 
 constkill=()=>{
 try{
-child.kill()
+child.kill('SIGKILL')
 }
 catch{
 // process may have already exited
@@ -82,24 +105,55 @@ export async function startTunnel(localURL: string, insecure?: boolean): Promise
 
 return{
  url,
-close: ()=>{
+close: async()=>{
 process.removeListener('exit',kill)
-kill()
+if(child.exitCode!==null||child.signalCode!==null){
+return
+}
+// `SIGINT` lets cloudflared drain its connections and deregister the
+// quick tunnel; escalate if it does not exit promptly.
+constexited=once(child,'exit')
+child.kill('SIGINT')
+constescalation=setTimeout(kill,SHUTDOWN_TIMEOUT_MS)
+try{
+awaitexited
+}
+catch(error){
+debug('Failed to stop `cloudflared`:',error)
+}
+finally{
+clearTimeout(escalation)
+}
 },
 }
 }
 
+constCLOUDFLARED_ASSETS: Record<string,Partial<Record<typeofprocess.arch,string>>>={
+darwin: {
+arm64: 'cloudflared-darwin-arm64.tgz',
+x64: 'cloudflared-darwin-amd64.tgz',
+},
+linux: {
+arm: 'cloudflared-linux-arm',
+arm64: 'cloudflared-linux-arm64',
+ia32: 'cloudflared-linux-386',
+x64: 'cloudflared-linux-amd64',
+},
+win32: {
+ia32: 'cloudflared-windows-386.exe',
+x64: 'cloudflared-windows-amd64.exe',
+},
+}
+
 asyncfunctionresolveCloudflared(): Promise<string|undefined>{
-constarch=process.arch==='arm64' ? 'arm64' : 'amd64'
-constbase='https://github.com/cloudflare/cloudflared/releases/latest/download'
-constasset=({
-darwin: `cloudflared-darwin-${arch}.tgz`,
-linux: `cloudflared-linux-${arch}`,
-win32: `cloudflared-windows-amd64.exe`,
-}asRecord<string,string>)[process.platform]
+constbase=CLOUDFLARED_VERSION==='latest'
+ ? 'https://github.com/cloudflare/cloudflared/releases/latest/download'
+ : `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}`
+constasset=CLOUDFLARED_ASSETS[process.platform]?.[process.arch]
 returnresolveTool('cloudflared',{
 url: asset&&`${base}/${asset}`,
 archive: asset?.endsWith('.tgz'),
+cacheName: `cloudflared-${CLOUDFLARED_VERSION}`,
 consent: {
 key: 'cloudflared',
 notice: [