unplugin-https-reverse-proxy 4.1.0-beta.3 → 4.1.0-beta.5

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/launch.ts

@@ -70,10 +70,10 @@ export function describePasswordReason(target: string, https: boolean): string[]
  * 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(
+export async function authenticateSudo(
   sudoCommand = 'sudo',
   options: { target?: string, https?: boolean } = {},
-): { ok: boolean, denied?: boolean, message?: string } {
+): Promise<{ ok: boolean, denied?: boolean, message?: string }> {
   if (platform() === 'win32')
     return { ok: true }
 
@@ -86,16 +86,53 @@ export function authenticateSudo(
     process.stderr.write('\n')
   }
 
-  if (spawnSync(sudoCommand, ['-v'], { stdio: 'inherit' }).status === 0)
-    return { ok: true }
+  // `sudo -v` inherits the terminal, so Ctrl+C reaches this process too. Without
+  // a handler the default action kills the dev server, which reads as "the
+  // proxy crashed my dev server" when the user only meant to skip it.
+  let interrupted = false
+  const onSigint = (): void => {
+    interrupted = true
+  }
+  process.on('SIGINT', onSigint)
+
+  try {
+    const { status, signal } = await runPrompt(sudoCommand)
+    if (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',
+    // `sudo` exits 1 on a wrong password and dies by the signal on Ctrl+C.
+    // Both are checked: a real Ctrl+C reaches this process and the child
+    // together, while a signal aimed at the child alone only shows up here.
+    const cancelled = interrupted || signal === 'SIGINT'
+    return {
+      ok: false,
+      denied: true,
+      message: cancelled
+        ? 'administrator permission was cancelled'
+        : 'administrator permission is required to edit the hosts file and bind ports 80/443',
+    }
+  }
+  finally {
+    process.off('SIGINT', onSigint)
   }
 }
 
+/**
+ * Runs `sudo -v` with the terminal attached.
+ *
+ * Spawned asynchronously rather than with `spawnSync`: the synchronous form
+ * blocks the event loop, so the SIGINT handler above never runs and the exit
+ * looks like a plain failure instead of a cancellation.
+ */
+function runPrompt(sudoCommand: string): Promise<{ status: number | null, signal: NodeJS.Signals | null }> {
+  return new Promise((resolve) => {
+    const child = spawn(sudoCommand, ['-v'], { stdio: 'inherit' })
+
+    child.on('error', () => resolve({ status: 1, signal: null }))
+    child.on('exit', (status, signal) => resolve({ status, signal }))
+  })
+}
+
 /** The user dismissed the password prompt; this is a choice, not a failure. */
 export class PrivilegeDeniedError extends Error {
   constructor(message: string) {
@@ -132,7 +169,7 @@ export async function startPrivilegedHelper(options: LaunchOptions): Promise<Pri
   } = options
 
   if (!skipAuth && !direct) {
-    const auth = authenticateSudo(sudoCommand, options.reason)
+    const auth = await authenticateSudo(sudoCommand, options.reason)
     if (!auth.ok) {
       const message = auth.message ?? 'administrator permission is required'
       throw auth.denied ? new PrivilegeDeniedError(message) : new Error(message)

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))
       })

package/src/privileged/session.ts

@@ -4,6 +4,7 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { platform } from 'node:os'
 import { join } from 'node:path'
+import * as lockfile from 'proper-lockfile'
 import { connectExistingHelper, createHelperToken, startPrivilegedHelper } from './launch'
 
 export interface SessionScope {
@@ -50,26 +51,50 @@ export function sessionSocketPath(runtimeDir: string): string {
  * Connects to the helper already serving this runtime directory, or starts a
  * new one. Reuse matters for multi-instance dev servers: the second instance
  * attaches to the running Caddy instead of asking for a password again.
+ *
+ * The check-then-start sequence runs under a lock. Two projects starting at the
+ * same moment would otherwise both fail to find a socket, both spawn a helper,
+ * and the second would delete the first one's socket while it was still
+ * serving.
  */
 export async function openHelperSession(scope: SessionScope): Promise<OpenedSession> {
   const socketPath = sessionSocketPath(scope.runtimeDir)
+  const release = await acquireStartLock(scope.runtimeDir)
 
-  if (existsSync(socketPath) || platform() === 'win32') {
-    const token = await readToken(scope.runtimeDir)
-    if (token) {
-      const reused = await connectExistingHelper(socketPath, token)
-      if (reused) {
-        return {
-          client: reused,
-          reused: true,
-          close: async () => {
-            await reused.close()
-          },
-        }
-      }
-    }
+  try {
+    const reused = await tryReuse(socketPath, scope)
+    if (reused)
+      return reused
+
+    return await startNew(socketPath, scope)
   }
+  finally {
+    release()
+  }
+}
+
+async function tryReuse(socketPath: string, scope: SessionScope): Promise<OpenedSession | undefined> {
+  if (!existsSync(socketPath) && platform() !== 'win32')
+    return undefined
+
+  const token = await readToken(scope.runtimeDir)
+  if (!token)
+    return undefined
+
+  const reused = await connectExistingHelper(socketPath, token)
+  if (!reused)
+    return undefined
 
+  return {
+    client: reused,
+    reused: true,
+    close: async () => {
+      await reused.close()
+    },
+  }
+}
+
+async function startNew(socketPath: string, scope: SessionScope): Promise<OpenedSession> {
   const token = createHelperToken()
   const started = await startPrivilegedHelper({
     socketPath,
@@ -98,6 +123,30 @@ export async function openHelperSession(scope: SessionScope): Promise<OpenedSess
   }
 }
 
+/**
+ * Serialises "is a helper running? if not, start one" across processes.
+ *
+ * The lock file is separate from the socket: the socket only exists once a
+ * helper is listening, while this lock guards the window before that.
+ */
+async function acquireStartLock(runtimeDir: string): Promise<() => void> {
+  const lockPath = join(runtimeDir, 'helper.start.lock')
+  try {
+    await writeFile(lockPath, '', { flag: 'a' })
+  }
+  catch {}
+
+  const release = await lockfile.lock(lockPath, {
+    realpath: false,
+    stale: 30_000,
+    retries: { retries: 100, minTimeout: 50, maxTimeout: 200 },
+  })
+
+  return () => {
+    void release().catch(() => {})
+  }
+}
+
 async function readToken(runtimeDir: string): Promise<string | undefined> {
   try {
     const content = await readFile(tokenPath(runtimeDir), 'utf8')