@avelor/mesh 0.2.1 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 Local dev proxy. Named services instead of ports. Failure injection without mocks.
 
+![demo](demo.gif)
+
 ```
 app.test   → :3000
 api.test   → :4000
@@ -26,10 +28,10 @@ Requires Node.js 18+. For HTTPS, install [mkcert](https://github.com/FiloSottile
 
 ```bash
 mesh init         # create mesh.yml in current directory
-sudo mesh start   # start proxy in background
+mesh start        # start proxy in background (will prompt for sudo)
 mesh status       # show running services
-sudo mesh stop    # stop the proxy
-sudo mesh route   # start in foreground (useful for debugging)
+mesh stop         # stop the proxy
+mesh route        # start in foreground (useful for debugging)
 ```
 
 `mesh start` runs on `:80` and `:443` (if mkcert is available), writes the hostname entries to `/etc/hosts`, and cleans them up automatically on stop.
@@ -136,7 +138,7 @@ cd examples/basic
 node app.js
 
 # terminal 3 (from examples/basic)
-sudo mesh route
+mesh route
 ```
 
 Then open `https://app.test`.

package/bin/mesh.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { watch, existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs'
-import { spawn }                           from 'child_process'
+import { spawn, spawnSync }                from 'child_process'
 import { dirname, resolve }                from 'path'
 import { createRequire }                   from 'module'
 import { loadConfig }              from '../src/config.js'
@@ -8,9 +8,18 @@ import { writeHosts, removeHosts } from '../src/hosts.js'
 import { startProxy }              from '../src/proxy.js'
 import { ensureCerts }             from '../src/certs.js'
 import { init }                    from '../src/init.js'
+import { findFreePort, startServices } from '../src/services.js'
 
 const STATE_FILE = '/tmp/.mesh.json'
 
+// Re-exec the current command under sudo if not already root.
+// Uses sudo -E to preserve PATH so mkcert and other tools remain findable.
+function autoSudo() {
+  if (process.getuid?.() === 0) return
+  const result = spawnSync('sudo', ['-E', process.execPath, ...process.argv.slice(1)], { stdio: 'inherit' })
+  process.exit(result.status ?? 1)
+}
+
 const RESET  = '\x1b[0m'
 const DIM    = '\x1b[2m'
 const GREEN  = '\x1b[32m'
@@ -42,16 +51,12 @@ if (cmd === 'start') {
     let alive = false
     try { process.kill(state.pid, 0); alive = true } catch (e) { if (e.code === 'EPERM') alive = true }
     if (alive) {
-      console.error(`mesh: already running (pid ${state.pid}) — run sudo mesh stop first`)
+      console.error(`mesh: already running (pid ${state.pid}) — run mesh stop first`)
       process.exit(1)
     }
   } catch { /* not running */ }
 
-  if (process.getuid?.() !== 0) {
-    console.error('mesh: requires sudo to bind ports 80/443')
-    console.error('      sudo mesh start')
-    process.exit(1)
-  }
+  autoSudo()
 
   const forwardArgs = args.filter(a => a !== 'start')
   const child = spawn(process.execPath, [process.argv[1], 'route', ...forwardArgs], {
@@ -103,8 +108,7 @@ if (cmd === 'stop') {
     console.log(`mesh: stopped (pid ${state.pid})`)
   } catch (err) {
     if (err.code === 'EPERM') {
-      console.error(`mesh: permission denied — try: sudo mesh stop`)
-      process.exit(1)
+      autoSudo()
     }
     if (err.code === 'ESRCH') {
       try { unlinkSync(STATE_FILE) } catch {}
@@ -165,97 +169,116 @@ if (cmd === 'status') {
 
 if (cmd !== 'route') {
   console.error('Usage:')
-  console.error('  mesh init                        create mesh.yml in current directory')
-  console.error('  sudo mesh start                  start proxy in background')
-  console.error('  sudo mesh start --config <path>  use a specific config file')
-  console.error('  sudo mesh stop                   stop the background proxy')
-  console.error('  mesh status                      show running services')
-  console.error('  sudo mesh route                  start proxy in foreground (debug)')
+  console.error('  mesh init                       create mesh.yml in current directory')
+  console.error('  mesh start                      start proxy in background')
+  console.error('  mesh start --config <path>      use a specific config file')
+  console.error('  mesh stop                       stop the background proxy')
+  console.error('  mesh status                     show running services')
+  console.error('  mesh route                      start proxy in foreground (debug)')
   process.exit(1)
 }
 
-if (process.getuid?.() !== 0) {
-  console.error('mesh: requires sudo to write /etc/hosts and bind ports 80/443')
-  console.error('      both are cleaned up automatically on exit')
-  console.error('      sudo mesh route')
-  process.exit(1)
-}
+autoSudo()
 
-// ── Load config ───────────────────────────────────────────────────────────────
+// ── Load config + start managed services ─────────────────────────────────────
 
-let config
-try {
-  config = loadConfig(configArg ?? process.cwd())
-} catch (err) {
-  console.error('mesh:', err.message)
-  process.exit(1)
-}
+;(async () => {
+  let config
+  try {
+    config = loadConfig(configArg ?? process.cwd())
+  } catch (err) {
+    console.error('mesh:', err.message)
+    process.exit(1)
+  }
 
-const { services, rules, configPath } = config
+  const { services: rawServices, rules, configPath } = config
 
-writeHosts(services)
+  // Split into managed (command string) and static (port number) services.
+  // For managed services, find a guaranteed-free port and inject it via PORT env.
+  const managed  = {} // { [name]: { command, port } }
+  const services = {} // { [name]: port } — always numbers from here on
 
-const configDir = dirname(resolve(configPath))
-const certs     = ensureCerts(services, configDir)
-const servers   = startProxy(services, rules, certs)
+  for (const [name, value] of Object.entries(rawServices)) {
+    if (typeof value === 'string') {
+      const port     = await findFreePort()
+      managed[name]  = { command: value, port }
+      services[name] = port
+    } else {
+      services[name] = value
+    }
+  }
 
-writeFileSync(STATE_FILE, JSON.stringify({ pid: process.pid, configPath, services, rules, https: !!certs }))
+  const serviceManager = startServices(managed)
 
-// ── Crash safety — clean /etc/hosts even on unexpected exit ───────────────────
+  writeHosts(services)
 
-function shutdown(code = 0) {
-  removeHosts()
-  try { unlinkSync(STATE_FILE) } catch {}
-  servers.http.close()
-  servers.https?.close()
-  process.exit(code)
-}
+  const configDir = dirname(resolve(configPath))
+  const certs     = ensureCerts(services, configDir)
+  const servers   = startProxy(services, rules, certs)
 
-process.on('SIGINT',  () => { console.log('\n  mesh  cleaning up...'); shutdown(0) })
-process.on('SIGTERM', () => shutdown(0))
+  writeFileSync(STATE_FILE, JSON.stringify({ pid: process.pid, configPath, services, rules, https: !!certs }))
 
-process.on('uncaughtException', err => {
-  console.error('\n  mesh  uncaught exception:', err.message)
-  shutdown(1)
-})
+  // ── Crash safety — clean /etc/hosts even on unexpected exit ─────────────────
 
-process.on('unhandledRejection', err => {
-  console.error('\n  mesh  unhandled rejection:', err?.message ?? err)
-  shutdown(1)
-})
+  function shutdown(code = 0) {
+    serviceManager.stop()
+    removeHosts()
+    try { unlinkSync(STATE_FILE) } catch {}
+    servers.http.close()
+    servers.https?.close()
+    process.exit(code)
+  }
 
-// ── Hot-reload ────────────────────────────────────────────────────────────────
+  process.on('SIGINT',  () => { console.log('\n  mesh  cleaning up...'); shutdown(0) })
+  process.on('SIGTERM', () => shutdown(0))
 
-let reloadTimer
-watch(configPath, () => {
-  clearTimeout(reloadTimer)
-  reloadTimer = setTimeout(() => {
-    try {
-      const next = loadConfig(configPath)
+  process.on('uncaughtException', err => {
+    console.error('\n  mesh  uncaught exception:', err.message)
+    shutdown(1)
+  })
 
-      const hasNewServices = Object.keys(next.services).some(k => !services[k])
+  process.on('unhandledRejection', err => {
+    console.error('\n  mesh  unhandled rejection:', err?.message ?? err)
+    shutdown(1)
+  })
+
+  // ── Hot-reload ───────────────────────────────────────────────────────────────
+  // Managed service ports are fixed at startup — only static ports and rules reload.
 
-      Object.keys(services).forEach(k => delete services[k])
-      Object.assign(services, next.services)
-      Object.keys(rules).forEach(k => delete rules[k])
-      Object.assign(rules, next.rules)
+  let reloadTimer
+  watch(configPath, () => {
+    clearTimeout(reloadTimer)
+    reloadTimer = setTimeout(() => {
+      try {
+        const next = loadConfig(configPath)
 
-      writeHosts(services)
-      writeFileSync(STATE_FILE, JSON.stringify({ pid: process.pid, configPath, services, rules, https: !!certs }))
+        const hasNewServices = Object.keys(next.services).some(k => !services[k])
 
-      if (certs && hasNewServices) {
-        const newCerts = ensureCerts(services, configDir)
-        if (newCerts && servers.https) {
-          servers.https.setSecureContext({
-            cert: readFileSync(newCerts.certFile),
-            key:  readFileSync(newCerts.keyFile),
-          })
+        Object.keys(services).forEach(k => delete services[k])
+        for (const [name, value] of Object.entries(next.services)) {
+          // Preserve the already-assigned port for managed services
+          services[name] = managed[name]?.port ?? (typeof value === 'number' ? value : services[name])
+        }
+        Object.keys(rules).forEach(k => delete rules[k])
+        Object.assign(rules, next.rules)
+
+        writeHosts(services)
+        writeFileSync(STATE_FILE, JSON.stringify({ pid: process.pid, configPath, services, rules, https: !!certs }))
+
+        if (certs && hasNewServices) {
+          const newCerts = ensureCerts(services, configDir)
+          if (newCerts && servers.https) {
+            servers.https.setSecureContext({
+              cert: readFileSync(newCerts.certFile),
+              key:  readFileSync(newCerts.keyFile),
+            })
+          }
         }
-      }
 
-      console.log('\n  mesh  config reloaded\n')
-    } catch (err) {
-      console.error('\n  mesh  config reload failed:', err.message, '\n')
-    }
-  }, 100)
-})
+        console.log('\n  mesh  config reloaded\n')
+      } catch (err) {
+        console.error('\n  mesh  config reload failed:', err.message, '\n')
+      }
+    }, 100)
+  })
+})()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avelor/mesh",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Local dev proxy. Named services, failure rules, no ports.",
   "keywords": [
     "proxy",

package/src/certs.js

@@ -1,7 +1,18 @@
 import { execFileSync, spawnSync } from 'child_process'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { chownSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { resolve } from 'path'
 
+// When running under sudo, restore file ownership to the invoking user
+// so that .mesh/ doesn't end up owned by root.
+function fixOwnership(...paths) {
+  const uid = parseInt(process.env.SUDO_UID ?? '')
+  const gid = parseInt(process.env.SUDO_GID ?? '')
+  if (!uid || !gid) return
+  for (const p of paths) {
+    try { chownSync(p, uid, gid) } catch {}
+  }
+}
+
 function mkcertInstalled() {
   return spawnSync('which', ['mkcert']).status === 0
 }
@@ -37,13 +48,15 @@ export function ensureCerts(services, cwd = process.cwd()) {
   const keyFile  = resolve(dir, 'key.pem')
 
   mkdirSync(dir, { recursive: true })
+  fixOwnership(dir)
 
   if (!caInstalled()) {
     execFileSync('mkcert', ['-install'], { stdio: 'ignore' })
   }
 
-  const domains = Object.keys(services).map(n => `${n}.test`).sort()
-  const cached  = cachedDomains(dir).sort()
+  const domains     = Object.keys(services).map(n => `${n}.test`).sort()
+  const cached      = cachedDomains(dir).sort()
+  const domainsFile = resolve(dir, 'domains.json')
 
   const needsRegen = JSON.stringify(domains) !== JSON.stringify(cached)
     || !existsSync(certFile)
@@ -51,7 +64,8 @@ export function ensureCerts(services, cwd = process.cwd()) {
 
   if (needsRegen) {
     execFileSync('mkcert', ['-cert-file', certFile, '-key-file', keyFile, ...domains], { stdio: 'ignore' })
-    writeFileSync(resolve(dir, 'domains.json'), JSON.stringify(domains))
+    writeFileSync(domainsFile, JSON.stringify(domains))
+    fixOwnership(certFile, keyFile, domainsFile)
   }
 
   return { certFile, keyFile }

package/src/config.js

@@ -33,11 +33,17 @@ export function loadConfig(cwdOrFile = process.cwd()) {
     if (!NAME_RE.test(name)) {
       throw new Error(`invalid service name "${name}" — only a-z, 0-9, hyphens and dots allowed`)
     }
-    const port = Number(raw)
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    if (typeof raw === 'string') {
+      if (!raw.trim()) throw new Error(`service "${name}" command cannot be empty`)
+      services[name] = raw.trim()
+    } else if (typeof raw === 'number') {
+      if (!Number.isInteger(raw) || raw < 1 || raw > 65535) {
+        throw new Error(`invalid port for service "${name}": ${raw}`)
+      }
+      services[name] = raw
+    } else {
       throw new Error(`invalid port for service "${name}": ${raw}`)
     }
-    services[name] = port
   }
 
   const rules = {}

package/src/init.js

@@ -39,5 +39,5 @@ export function init(cwd = process.cwd()) {
     }
   }
 
-  console.log('      edit your services and run: sudo mesh route')
+  console.log('      edit your services and run: mesh route')
 }

package/src/proxy.js

@@ -6,20 +6,36 @@ import httpProxy        from 'http-proxy'
 import { matchRule, applyRule } from './rules.js'
 import { wantsHtml, errorPage } from './error-page.js'
 
-const hostCache = new Map()
+// Maps configuredPort → { host, port } — cleared on ECONNREFUSED so next
+// request re-discovers if the service moved to a different port.
+const endpointCache = new Map()
+const SCAN_RANGE = 10
 
-function probeHost(port) {
-  if (hostCache.has(port)) return Promise.resolve(hostCache.get(port))
+function probePort(port) {
   const probe = addr => new Promise((resolve, reject) => {
     const s = net.connect(port, addr)
-    s.setTimeout(200)
+    s.setTimeout(100)
     s.on('connect', () => { s.destroy(); resolve(addr) })
-    s.on('timeout',  () => { s.destroy(); reject(new Error('timeout')) })
+    s.on('timeout',  () => { s.destroy(); reject() })
     s.on('error', reject)
   })
-  return Promise.any([probe('127.0.0.1'), probe('::1')])
-    .then(host => { hostCache.set(port, host); return host })
-    .catch(() => '127.0.0.1')
+  return Promise.any([probe('127.0.0.1'), probe('::1')]).catch(() => null)
+}
+
+async function resolveEndpoint(configuredPort) {
+  const cached = endpointCache.get(configuredPort)
+  if (cached) return cached
+
+  // Probe configured port and the next SCAN_RANGE ports concurrently.
+  // results preserves order so .find() returns the closest open port.
+  const candidates = Array.from({ length: SCAN_RANGE + 1 }, (_, i) => configuredPort + i)
+  const results    = await Promise.all(
+    candidates.map(port => probePort(port).then(host => host ? { host, port } : null))
+  )
+
+  const found = results.find(r => r !== null) ?? { host: '127.0.0.1', port: configuredPort }
+  endpointCache.set(configuredPort, found)
+  return found
 }
 
 function fmtHost(host) {
@@ -38,6 +54,9 @@ export function startProxy(services, rules, certs = null) {
 
   proxy.on('error', (err, req, res) => {
     const { name, target } = resolveService(req.headers.host)
+    if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET') {
+      endpointCache.delete(target)
+    }
     log(RED, 'ERR', name, req.url, `→ ${err.code ?? err.message}`)
     if (!res.headersSent) {
       const protocol = certs ? 'https' : 'http'
@@ -86,19 +105,24 @@ export function startProxy(services, rules, certs = null) {
       log(YELLOW, `${rule.delay}ms`, name, pathname, `→ :${target} (delayed)`)
     }
 
-    const host = await probeHost(target)
-    proxy.web(req, res, { target: `http://${fmtHost(host)}:${target}` })
-    if (!rule) log(DIM, '→', name, pathname, `→ :${target}`)
+    const endpoint = await resolveEndpoint(target)
+    proxy.web(req, res, { target: `http://${fmtHost(endpoint.host)}:${endpoint.port}` })
+    if (!rule) {
+      const portLabel = endpoint.port !== target
+        ? `:${endpoint.port} ${DIM}(shifted from :${target})${RESET}`
+        : `:${target}`
+      log(DIM, '→', name, pathname, `→ ${portLabel}`)
+    }
   }
 
   async function handleUpgrade(req, socket, head) {
     const { name, target } = resolveService(req.headers.host)
     if (!target) { socket.destroy(); return }
-    const host = await probeHost(target)
-    proxy.ws(req, socket, head, { target: `ws://${fmtHost(host)}:${target}` }, err => {
+    const endpoint = await resolveEndpoint(target)
+    proxy.ws(req, socket, head, { target: `ws://${fmtHost(endpoint.host)}:${endpoint.port}` }, err => {
       if (err) log(RED, 'WSE', name, req.url, `→ ${err.code ?? err.message}`)
     })
-    log(DIM, 'WS', name, req.url, `→ :${target}`)
+    log(DIM, 'WS', name, req.url, `→ :${endpoint.port}`)
   }
 
   const httpServer = http.createServer((req, res) => {

package/src/services.js

@@ -0,0 +1,91 @@
+import { spawn } from 'child_process'
+import net       from 'net'
+
+const RESET  = '\x1b[0m'
+const DIM    = '\x1b[2m'
+const CYAN   = '\x1b[36m'
+const YELLOW = '\x1b[33m'
+const RED    = '\x1b[31m'
+
+export function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address()
+      server.close(() => resolve(port))
+    })
+    server.on('error', reject)
+  })
+}
+
+export function startServices(managed) {
+  // managed: { [name]: { command: string, port: number } }
+  if (!Object.keys(managed).length) return { stop() {} }
+
+  let stopping = false
+  const children = new Map()
+
+  function logLine(name, line) {
+    if (!line.trim()) return
+    const time = new Date().toTimeString().slice(0, 8)
+    process.stdout.write(`  ${DIM}${time}${RESET}  ${CYAN}${name}${RESET}  ${DIM}│${RESET} ${line}\n`)
+  }
+
+  function launch(name, command, port, restartCount = 0, startedAt = Date.now()) {
+    const child = spawn(command, [], {
+      env:   { ...process.env, PORT: String(port), HOST: '127.0.0.1' },
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    children.set(name, child)
+
+    let buffer = ''
+    function flush(chunk) {
+      buffer += String(chunk)
+      const lines = buffer.split('\n')
+      buffer = lines.pop()
+      for (const line of lines) logLine(name, line)
+    }
+
+    child.stdout.on('data', flush)
+    child.stderr.on('data', flush)
+
+    child.on('exit', (code, signal) => {
+      if (buffer.trim()) logLine(name, buffer)
+      buffer = ''
+      if (stopping) return
+
+      const uptime    = Date.now() - startedAt
+      const nextCount = uptime > 10_000 ? 0 : restartCount + 1
+      const delay     = Math.min(1000 * 2 ** nextCount, 10_000)
+      const time      = new Date().toTimeString().slice(0, 8)
+
+      console.log(
+        `  ${DIM}${time}${RESET}  ${RED}${name}${RESET}  ` +
+        `${DIM}exited (${code ?? signal}) — restarting in ${delay / 1000}s${RESET}`
+      )
+
+      setTimeout(() => {
+        if (!stopping) launch(name, command, port, nextCount, Date.now())
+      }, delay)
+    })
+
+    const time = new Date().toTimeString().slice(0, 8)
+    const label = restartCount === 0 ? CYAN : YELLOW
+    console.log(`  ${DIM}${time}${RESET}  ${label}${name}${RESET}  ${DIM}→ :${port}  $ ${command}${RESET}`)
+  }
+
+  for (const [name, { command, port }] of Object.entries(managed)) {
+    launch(name, command, port)
+  }
+
+  return {
+    stop() {
+      stopping = true
+      for (const child of children.values()) {
+        try { child.kill('SIGTERM') } catch {}
+      }
+    },
+  }
+}