unplugin-https-reverse-proxy 4.1.0-beta.2 → 4.1.0-beta.4

package/src/index.ts

@@ -7,6 +7,8 @@ import c from 'picocolors'
 import { createUnplugin } from 'unplugin'
 import { CaddyInstant } from './caddy'
 import { hmrSseBridgeClientScript, setupHmrSseBridge } from './hmr-sse-bridge'
+import { isPrivilegeDenied, markPrivilegeDenied } from './privilege-state'
+import { PrivilegeDeniedError } from './privileged/launch'
 import { consola, generateQrcode, getIpv4List, once } from './utils'
 
 let config: ResolvedConfig
@@ -62,10 +64,15 @@ export const vitePrintUrls = once((
 ) => {
   _printUrls?.()
 
+  // Declined earlier in this process; a hot restart must not ask again.
+  if (isPrivilegeDenied())
+    return
+
   if (caddy)
     return
-  caddy = new CaddyInstant()
-  caddy.run(source, target, {
+  const instance = new CaddyInstant()
+  caddy = instance
+  instance.run(source, target, {
     base,
     ...options,
   }).then(async () => {
@@ -73,6 +80,16 @@ export const vitePrintUrls = once((
 
     consola.success(`  ${c.green('➜')}  ${c.bold('run caddy reverse proxy success')}: ${colorUrl(`${options.https ? 'https' : 'http'}://${target}${base}`)}`)
   }).catch((e) => {
+    // Declining the password is a choice, not a crash: drop the half-started
+    // instance so a later attempt can prompt again.
+    if (caddy === instance)
+      caddy = undefined as unknown as CaddyInstant
+    if (e instanceof PrivilegeDeniedError) {
+      markPrivilegeDenied()
+      consola.warn('reverse proxy skipped: administrator permission was not granted.')
+      consola.info('Restart the dev server to enable it again.')
+      return
+    }
     throw e
   })
 })
@@ -168,6 +185,9 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
     }
     const source = `${devServer.host}:${devServer.port}`
 
+    if (isPrivilegeDenied())
+      return
+
     if (caddy)
       return
 
@@ -195,9 +215,10 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
       options.https = false
     }
 
-    caddy = new CaddyInstant()
+    const instance = new CaddyInstant()
+    caddy = instance
 
-    caddy.run(source, target, {
+    instance.run(source, target, {
       base,
       ...options,
     }).then(() => {
@@ -207,6 +228,14 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
         consola.success(`  ${c.green('➜')}  ${c.bold('run caddy reverse proxy success')}: ${colorUrl(`${options.https ? 'https' : 'http'}://${target}${base}`)}`)
       })
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = undefined as unknown as CaddyInstant
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied()
+        consola.warn('reverse proxy skipped: administrator permission was not granted.')
+        consola.info('Restart the dev server to enable it again.')
+        return
+      }
       throw e
     })
   },
@@ -243,10 +272,11 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
 
     const source = `${devServer.host}:${devServer.port}`
 
-    if (caddy)
+    if (isPrivilegeDenied())
       return
 
-    caddy = new CaddyInstant()
+    if (caddy)
+      return
 
     let base = '/'
     const publicPath = compiler.options.output?.publicPath as unknown
@@ -258,7 +288,10 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
     if (base !== '/' && !base.endsWith('/'))
       base = `${base}/`
 
-    caddy.run(source, target, {
+    const instance = new CaddyInstant()
+    caddy = instance
+
+    instance.run(source, target, {
       base,
       ...options,
     }).then(async () => {
@@ -266,6 +299,14 @@ export const unpluginFactory: UnpluginFactory<Options> = options => ({
 
       consola.success(`  ${c.green('➜')}  ${c.bold('run caddy reverse proxy success')}: ${colorUrl(`${options.https ? 'https' : 'http'}://${target}${base}`)}`)
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = undefined as unknown as CaddyInstant
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied()
+        consola.warn('reverse proxy skipped: administrator permission was not granted.')
+        consola.info('Restart the dev server to enable it again.')
+        return
+      }
       throw e
     })
   },

package/src/privilege-state.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether the user dismissed the password prompt in this process.
+ *
+ * Kept in its own module so the flag outlives a hot restart. Vite rebuilds the
+ * dev server in place (`Object.assign(server, newServer)`) rather than starting
+ * a new process, so module scope is the only place that distinguishes "saved
+ * the config again" from "started the dev server again".
+ */
+let denied = false
+
+/** Records that the user declined; every entry point checks this first. */
+export function markPrivilegeDenied(): void {
+  denied = true
+}
+
+export function isPrivilegeDenied(): boolean {
+  return denied
+}
+
+/** Test hook: restores the initial state between cases. */
+export function resetPrivilegeDenied(): void {
+  denied = false
+}

package/src/privileged/bootstrap.ts

@@ -2,8 +2,9 @@ import type { Socket } from 'node:net'
 import type { ClientHandshake } from './protocol'
 import type { HelperDeps, HelperRuntime } from './server'
 import { Buffer } from 'node:buffer'
-import { chmodSync, chownSync, rmSync } from 'node:fs'
+import { chmodSync, chownSync, existsSync, readFileSync, rmSync } from 'node:fs'
 import { createServer } from 'node:net'
+import { dirname, join } from 'node:path'
 import process from 'node:process'
 import { attachSocket, createHelperRuntime, createNodeHelperDeps } from './server'
 
@@ -26,6 +27,14 @@ export interface HelperBootstrapOptions {
   ownerGid?: number
   /** Caddy storage directory, handed back to the owner when Caddy stops. */
   caddyStoragePath?: string
+  /**
+   * How long the helper lingers with no clients before exiting.
+   *
+   * Kept short so a helper nobody is using does not stay on the machine as an
+   * idle root process. Within the same terminal a restart usually happens
+   * sooner than this and still reuses the running helper.
+   */
+  idleTimeoutMs?: number
   deps?: HelperDeps
   log?: (message: string) => void
 }
@@ -37,6 +46,9 @@ export interface RunningHelper {
 
 const HANDSHAKE_TIMEOUT_MS = 120_000
 
+/** Default idle lifetime after the last client leaves. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 30_000
+
 /**
  * Runs the privileged side of the plugin: listens on a local socket, accepts
  * only a client presenting the shared token, then serves until that client
@@ -70,12 +82,26 @@ export async function startHelper(options: HelperBootstrapOptions): Promise<Runn
   catch {}
 
   const connections = new Set<Socket>()
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
+  let idleTimer: ReturnType<typeof setTimeout> | undefined
+
+  const stopIdleTimer = (): void => {
+    if (idleTimer) {
+      clearTimeout(idleTimer)
+      idleTimer = undefined
+    }
+  }
 
   const server = createServer((socket) => {
     let buffer = ''
     let authenticated = false
+    stopIdleTimer()
     connections.add(socket)
-    socket.on('close', () => connections.delete(socket))
+    socket.on('close', () => {
+      connections.delete(socket)
+      if (connections.size === 0)
+        scheduleIdleExit()
+    })
 
     const timer = setTimeout(() => {
       if (!authenticated)
@@ -127,11 +153,41 @@ export async function startHelper(options: HelperBootstrapOptions): Promise<Runn
     socket.on('error', () => {})
   })
 
+  /**
+   * Exits once nobody needs the helper.
+   *
+   * Without this, every dev server that ever ran leaves a root process behind.
+   * The socket and token are removed too, but only while they still carry this
+   * process's identity: a newer helper may already own them.
+   */
+  function scheduleIdleExit(): void {
+    if (idleTimer || connections.size > 0)
+      return
+
+    idleTimer = setTimeout(() => {
+      idleTimer = undefined
+      if (connections.size > 0)
+        return
+
+      log('no clients left; shutting down')
+      removeOwnSocket(socketPath, token)
+      server.close(() => process.exit(0))
+      // A listener with no clients closes synchronously, but keep a backstop so
+      // the process cannot linger if a close callback never arrives.
+      setTimeout(() => process.exit(0), 1000).unref?.()
+    }, idleTimeoutMs)
+    idleTimer.unref?.()
+  }
+
   await new Promise<void>((resolve, reject) => {
     server.once('error', reject)
     server.listen(socketPath, () => resolve())
   })
 
+  // A helper nobody ever connects to is as useless as one whose clients left:
+  // start the timer now so a failed handshake does not strand it.
+  scheduleIdleExit()
+
   try {
     // The client is not root: hand the socket back to the developer and keep it
     // private to them. Without the chown, `connect()` fails with EACCES and the
@@ -163,6 +219,31 @@ export async function startHelper(options: HelperBootstrapOptions): Promise<Runn
   }
 }
 
+/**
+ * Removes this helper's socket and token, but only if they are still its own.
+ *
+ * A newer helper may have taken both over; deleting them then would break a
+ * session this process never served.
+ */
+function removeOwnSocket(socketPath: string, token: string): void {
+  if (process.platform === 'win32')
+    return
+
+  try {
+    const tokensDir = dirname(socketPath)
+    const tokenFile = join(tokensDir, 'helper.token')
+    const current = existsSync(tokenFile) ? readFileSync(tokenFile, 'utf8').trim() : undefined
+    if (current === token)
+      rmSync(tokenFile, { force: true })
+  }
+  catch {}
+
+  try {
+    rmSync(socketPath, { force: true })
+  }
+  catch {}
+}
+
 /** Sockets left behind by a killed helper cannot be reused; remove them first. */
 export function removeStaleSocket(socketPath: string): void {
   if (process.platform === 'win32')

package/src/privileged/entry.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import process from 'node:process'
 
 export interface HelperEntry {
@@ -26,20 +26,48 @@ export interface ResolveHelperEntryOptions {
  * Published builds ship a compiled `privileged-helper.js` and start it with
  * node; running from the repository uses `tsx` so the TypeScript source works
  * without a build step.
+ *
+ * The running module sits in a subdirectory (`src/caddy`, `src/privileged`),
+ * while the helper lives one level up in `src`, so both lookups walk up instead
+ * of assuming a fixed depth.
  */
 export function resolveHelperEntry(options: ResolveHelperEntryOptions): HelperEntry {
   const { moduleDir, nodeBin = process.execPath, exists = existsSync } = options
 
   for (const name of ['privileged-helper.js', 'privileged-helper.cjs', 'privileged-helper.mjs']) {
-    const candidate = join(moduleDir, name)
-    if (exists(candidate))
+    const candidate = findUp(moduleDir, name, exists)
+    if (candidate)
       return { entry: nodeBin, args: [candidate] }
   }
 
-  const source = join(moduleDir, 'privileged-helper.ts')
-  const tsxCli = join(moduleDir, '../node_modules/tsx/dist/cli.mjs')
-  if (exists(source) && exists(tsxCli))
+  const source = findUp(moduleDir, 'privileged-helper.ts', exists)
+  const tsxCli = findUp(moduleDir, 'node_modules/tsx/dist/cli.mjs', exists)
+  if (source && tsxCli)
     return { entry: nodeBin, args: [tsxCli, source] }
 
   throw new Error(`privileged helper entry not found in ${moduleDir}. Build the package first.`)
 }
+
+/**
+ * Walks up from `from` looking for a relative path.
+ *
+ * Stops at the filesystem root so a helper outside the project is never picked
+ * up by accident.
+ */
+function findUp(
+  from: string,
+  relative: string,
+  exists: (path: string) => boolean,
+): string | undefined {
+  let current = from
+  while (true) {
+    const candidate = join(current, relative)
+    if (exists(candidate))
+      return candidate
+
+    const parent = dirname(current)
+    if (parent === current)
+      return undefined
+    current = parent
+  }
+}

package/src/privileged/launch.ts

@@ -39,6 +39,25 @@ export interface LaunchOptions {
   caddyBin: string
   /** Caddyfile the helper is allowed to load. */
   caddyConfigPath: string
+  /** Shown before the password prompt so the request is not a surprise. */
+  reason?: { target: string, https: boolean }
+}
+
+/**
+ * Explains why a password is about to be requested. Without this the prompt
+ * appears out of nowhere in the middle of `npm run dev` and looks like something
+ * went wrong.
+ */
+export function describePasswordReason(target: string, https: boolean): string[] {
+  const port = https ? '443' : '80'
+  return [
+    `reverse proxy needs administrator permission for ${target}`,
+    `  · bind port ${port}${https ? ` for https://${target}` : ''}`,
+    `  · add ${target} to the hosts file`,
+    '',
+    'This is the only prompt; the rest of the dev server keeps running as you.',
+    'Press Ctrl+C at the prompt to skip the proxy and keep the dev server.',
+  ]
 }
 
 /**
@@ -47,23 +66,44 @@ export interface LaunchOptions {
  * The credential cache is keyed by terminal, so a later `sudo -n` only finds
  * this entry when the child stays in the same session. That is why the helper
  * is spawned without `detached`.
+ *
+ * Returns `denied` when the user dismissed the prompt, so the caller can keep
+ * the dev server running instead of treating it as a crash.
  */
-export function authenticateSudo(sudoCommand = 'sudo'): { ok: boolean, message?: string } {
+export function authenticateSudo(
+  sudoCommand = 'sudo',
+  options: { target?: string, https?: boolean } = {},
+): { ok: boolean, denied?: boolean, message?: string } {
   if (platform() === 'win32')
     return { ok: true }
 
   if (spawnSync(sudoCommand, ['-n', 'true'], { stdio: 'ignore' }).status === 0)
     return { ok: true }
 
+  if (options.target) {
+    for (const line of describePasswordReason(options.target, options.https ?? false))
+      process.stderr.write(`${line}\n`)
+    process.stderr.write('\n')
+  }
+
   if (spawnSync(sudoCommand, ['-v'], { stdio: 'inherit' }).status === 0)
     return { ok: true }
 
   return {
     ok: false,
+    denied: true,
     message: 'administrator permission is required to edit the hosts file and bind ports 80/443',
   }
 }
 
+/** The user dismissed the password prompt; this is a choice, not a failure. */
+export class PrivilegeDeniedError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PrivilegeDeniedError'
+  }
+}
+
 export interface PrivilegedHelperHandle {
   client: PrivilegedClient
   close: () => Promise<void>
@@ -92,9 +132,11 @@ export async function startPrivilegedHelper(options: LaunchOptions): Promise<Pri
   } = options
 
   if (!skipAuth && !direct) {
-    const auth = authenticateSudo(sudoCommand)
-    if (!auth.ok)
-      throw new Error(auth.message)
+    const auth = authenticateSudo(sudoCommand, options.reason)
+    if (!auth.ok) {
+      const message = auth.message ?? 'administrator permission is required'
+      throw auth.denied ? new PrivilegeDeniedError(message) : new Error(message)
+    }
   }
 
   const forwarded = collectForwardedEnv(env)

package/src/privileged/server.ts

@@ -46,6 +46,8 @@ const FLUSH_FALLBACK = [{ file: 'killall', args: ['-HUP', 'mDNSResponder'] }] as
 export interface CaddyChild {
   pid?: number
   kill: (signal?: NodeJS.Signals) => boolean
+  /** False once the process has exited; undefined when unknown. */
+  running?: boolean
 }
 
 /**
@@ -60,7 +62,8 @@ export interface HelperDeps {
   readHosts: () => string
   writeHosts: (content: string) => void
   flushDns: () => Promise<void>
-  freePort: (port: number) => Promise<number[]>
+  /** Releases a port; never kills the pid in `keepPid`. */
+  freePort: (port: number, keepPid?: number) => Promise<number[]>
   /** Caddy binary and the Caddyfile it must load, both fixed at start-up. */
   caddyBin: string
   caddyConfigPath: string
@@ -91,7 +94,8 @@ async function flushDnsBestEffort(deps: HelperDeps): Promise<void> {
 }
 
 export interface HelperRuntime {
-  handle: (request: HelperRequest) => Promise<HelperResponse>
+  /** `client` identifies the caller so shared host mappings are reference-counted. */
+  handle: (request: HelperRequest, client?: object) => Promise<HelperResponse>
   /** Registers a connected client so Caddy output reaches it. */
   attach: (client: object) => void
   /** Last client gone: stop Caddy and drop the hosts entries this plugin wrote. */
@@ -114,6 +118,37 @@ export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
   let generation = 0
   let caddy: CaddyChild | undefined
 
+  // Which client asked for which host. Two projects may map the same domain, so
+  // a mapping is only removed once its last holder is gone.
+  const hostOwners = new Map<string, Set<object>>()
+
+  const hostId = (ip: string, host: string): string => `${ip} ${host.toLowerCase()}`
+
+  function addHostOwner(client: object | undefined, ip: string, host: string): void {
+    const id = hostId(ip, host)
+    let owners = hostOwners.get(id)
+    if (!owners) {
+      owners = new Set()
+      hostOwners.set(id, owners)
+    }
+    owners.add(client ?? deps)
+  }
+
+  /** True when no other client still needs this mapping. */
+  function releaseHostOwner(client: object | undefined, ip: string, host: string): boolean {
+    const id = hostId(ip, host)
+    const owners = hostOwners.get(id)
+    if (!owners)
+      return true
+
+    owners.delete(client ?? deps)
+    if (owners.size > 0)
+      return false
+
+    hostOwners.delete(id)
+    return true
+  }
+
   const broadcast = (event: HelperEvent): void => {
     const line = serializeMessage(event)
     for (const client of clients) {
@@ -183,7 +218,7 @@ export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
     }
   }
 
-  async function handle(request: HelperRequest): Promise<HelperResponse> {
+  async function handle(request: HelperRequest, client?: object): Promise<HelperResponse> {
     try {
       switch (request.method) {
         case 'ping':
@@ -197,6 +232,7 @@ export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
           const edited = addHost(deps.readHosts(), ip, host)
           if (edited.changed)
             deps.writeHosts(edited.content)
+          addHostOwner(client, ip, host)
           await flushDnsBestEffort(deps)
           return { id: request.id, ok: true }
         }
@@ -206,6 +242,12 @@ export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
           if (!isSafeIp(ip) || !isSafeHost(host))
             return { id: request.id, ok: false, error: { message: 'invalid hosts entry' } }
 
+          // Another project may still need this domain; only the last holder
+          // removes the mapping.
+          const last = releaseHostOwner(client, ip, host)
+          if (!last)
+            return { id: request.id, ok: true, result: { kept: true } }
+
           const edited = removeHost(deps.readHosts(), ip, host)
           if (edited.changed)
             deps.writeHosts(edited.content)
@@ -218,16 +260,20 @@ export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
           if (!isAllowedFreePort(port))
             return { id: request.id, ok: false, error: { message: `port ${port} is not releasable` } }
 
-          const killed = await deps.freePort(port)
+          // Caddy belongs to this helper, so a port sweep must never kill it:
+          // the pid is the one serving every other project's domains.
+          const killed = await deps.freePort(port, caddy?.pid)
           return { id: request.id, ok: true, result: { killed } }
         }
 
         case 'caddy.start': {
-          if (caddy)
-            await stopCaddy()
+          // Idempotent: several dev servers share one Caddy, so a second start
+          // must attach to the running process instead of restarting it.
+          if (caddy && caddy.running !== false)
+            return { id: request.id, ok: true, result: { pid: caddy.pid, started: false } }
 
           caddy = deps.startCaddy(broadcast)
-          return { id: request.id, ok: true, result: { pid: caddy.pid } }
+          return { id: request.id, ok: true, result: { pid: caddy.pid, started: true } }
         }
 
         case 'caddy.stop': {
@@ -260,6 +306,27 @@ export function createHelperRuntime(deps: HelperDeps): HelperRuntime {
     },
     async detach(client) {
       clients.delete(client)
+
+      // Drop only the mappings this client was the last holder of, so a project
+      // that exits leaves the domains another project still serves alone.
+      for (const [id, owners] of [...hostOwners]) {
+        if (!owners.delete(client) || owners.size > 0)
+          continue
+
+        hostOwners.delete(id)
+        const [ip, host] = id.split(' ')
+        try {
+          const edited = removeHost(deps.readHosts(), ip, host)
+          if (edited.changed) {
+            deps.writeHosts(edited.content)
+            await flushDnsBestEffort(deps)
+          }
+        }
+        catch (error) {
+          deps.log(`hosts cleanup failed: ${(error as Error).message}`)
+        }
+      }
+
       if (clients.size === 0)
         await dispose()
     },
@@ -367,7 +434,7 @@ export function createNodeHelperDeps(options: NodeHelperDepsOptions): HelperDeps
 
       throw lastError ?? new Error('no DNS cache flush command for this platform')
     },
-    freePort: async (port) => {
+    freePort: async (port, keepPid) => {
       // `lsof` exits with 1 when nothing matches, which is the normal case for
       // a free port; only its stdout carries the answer.
       const pids = platform() === 'win32'
@@ -376,7 +443,9 @@ export function createNodeHelperDeps(options: NodeHelperDepsOptions): HelperDeps
 
       const killed: number[] = []
       for (const pid of pids) {
-        if (pid === process.pid)
+        // Never kill the helper itself or the Caddy it owns: that Caddy serves
+        // every project sharing this helper, not just the caller's.
+        if (pid === process.pid || (keepPid !== undefined && pid === keepPid))
           continue
         try {
           process.kill(pid, 'SIGTERM')
@@ -394,16 +463,28 @@ export function createNodeHelperDeps(options: NodeHelperDepsOptions): HelperDeps
     caddyStoragePath: options.caddyStoragePath,
     storageOwner: options.storageOwner,
     startCaddy: (emit) => {
-      const child = spawn(options.caddyBin, ['run', '--adapter', 'caddyfile', '--config', options.caddyConfigPath], {
+      // `--watch` makes Caddy reload when another project rewrites the shared
+      // Caddyfile. Without it the second project's route never takes effect.
+      const child = spawn(options.caddyBin, ['run', '--adapter', 'caddyfile', '--config', options.caddyConfigPath, '--watch'], {
         cwd: options.caddyCwd ?? process.cwd(),
         env: { ...process.env, ...options.caddyEnv },
         stdio: ['ignore', 'pipe', 'pipe'],
       })
+      const handle: CaddyChild & { running?: boolean } = {
+        pid: child.pid,
+        kill: signal => child.kill(signal),
+        running: true,
+      }
       child.stdout?.on('data', (data: Buffer) => emit({ type: 'event', kind: 'caddy.stdout', data: data.toString() }))
       child.stderr?.on('data', (data: Buffer) => emit({ type: 'event', kind: 'caddy.stderr', data: data.toString() }))
-      child.on('exit', (code, signal) => emit({ type: 'event', kind: 'caddy.exit', code, signal }))
-      caddy = child as unknown as CaddyChild
-      return caddy
+      child.on('exit', (code, signal) => {
+        // Recorded before broadcasting so a later `caddy.start` knows it has to
+        // spawn again rather than reuse a dead process.
+        handle.running = false
+        emit({ type: 'event', kind: 'caddy.exit', code, signal })
+      })
+      caddy = handle
+      return handle
     },
     stopCaddy: async () => {
       const current = caddy
@@ -448,7 +529,7 @@ export function attachSocket(socket: Socket, runtime: HelperRuntime, log: (messa
         continue
       }
 
-      void runtime.handle(request).then((response) => {
+      void runtime.handle(request, socket).then((response) => {
         if (!socket.destroyed)
           socket.write(serializeMessage(response))
       })