@avelor/mesh 0.1.0 → 0.2.0

package/README.md

@@ -25,11 +25,14 @@ Requires Node.js 18+. For HTTPS, install [mkcert](https://github.com/FiloSottile
 ## Usage
 
 ```bash
-mesh init        # create mesh.yml in current directory
-sudo mesh route  # start proxy (writes /etc/hosts)
+mesh init         # create mesh.yml in current directory
+sudo mesh start   # start proxy in background
+mesh status       # show running services
+sudo mesh stop    # stop the proxy
+sudo mesh route   # start in foreground (useful for debugging)
 ```
 
-`mesh route` starts on `:80` and `:443` (if mkcert is available), writes the hostname entries to `/etc/hosts`, and cleans them up on exit.
+`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.
 
 ---
 
@@ -56,7 +59,11 @@ services:
 rules:
   api:
     - path: /payments
+      method: POST
       status: 503
+      body:
+        error: Payment service unavailable
+        retryAfter: 30
       rate: 30
     - path: /auth/login
       status: 401
@@ -70,14 +77,16 @@ rules:
       rate: 25
 ```
 
-| Field    | Description                                      |
-|----------|--------------------------------------------------|
-| `path`   | Request path prefix to match                     |
-| `status` | HTTP status code to return (400, 401, 500, etc.) |
-| `delay`  | Milliseconds to wait before responding           |
-| `rate`   | Percentage of matching requests to affect (1–100)|
+| Field    | Description                                                   |
+|----------|---------------------------------------------------------------|
+| `path`   | Request path prefix to match                                  |
+| `method` | HTTP method to match (GET, POST, PUT, PATCH, DELETE…)         |
+| `status` | HTTP status code to return (400, 401, 500, etc.)              |
+| `body`   | Response body — object (sent as JSON) or string (plain text)  |
+| `delay`  | Milliseconds to wait before responding                        |
+| `rate`   | Percentage of matching requests to affect (1–100)             |
 
-`status` and `delay` can be combined: wait N ms, then fail with that status.
+`status` and `delay` can be combined: wait N ms, then fail with that status. Without `body`, the default is `{ "error": "<status text>", "injected": true }`.
 
 ### Subdomains
 

package/bin/mesh.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { watch, existsSync, readFileSync } from 'fs'
+import { watch, existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { spawn }                           from 'child_process'
 import { dirname, resolve }                from 'path'
 import { createRequire }                   from 'module'
 import { loadConfig }              from '../src/config.js'
@@ -8,6 +9,13 @@ import { startProxy }              from '../src/proxy.js'
 import { ensureCerts }             from '../src/certs.js'
 import { init }                    from '../src/init.js'
 
+const STATE_FILE = '/tmp/.mesh.json'
+
+const RESET  = '\x1b[0m'
+const DIM    = '\x1b[2m'
+const GREEN  = '\x1b[32m'
+const CYAN   = '\x1b[36m'
+
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
 const args = process.argv.slice(2)
@@ -27,11 +35,103 @@ if (cmd === 'init') {
   process.exit(0)
 }
 
+if (cmd === 'start') {
+  try {
+    const state = JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+    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`)
+      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)
+  }
+
+  const forwardArgs = args.filter(a => a !== 'start')
+  const child = spawn(process.execPath, [process.argv[1], 'route', ...forwardArgs], {
+    detached: true,
+    stdio:    'ignore',
+  })
+  child.unref()
+  console.log(`mesh: started (pid ${child.pid})`)
+  process.exit(0)
+}
+
+if (cmd === 'stop') {
+  let state
+  try {
+    state = JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+  } catch {
+    console.error('mesh: not running')
+    process.exit(1)
+  }
+  try {
+    process.kill(state.pid, 'SIGTERM')
+    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)
+    }
+    if (err.code === 'ESRCH') {
+      try { unlinkSync(STATE_FILE) } catch {}
+      console.error('mesh: not running (stale state removed)')
+      process.exit(1)
+    }
+    console.error('mesh:', err.message)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+if (cmd === 'status') {
+  let state
+  try {
+    state = JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+  } catch {
+    console.error('mesh: not running')
+    process.exit(1)
+  }
+
+  let alive = false
+  try {
+    process.kill(state.pid, 0)
+    alive = true
+  } catch (err) {
+    if (err.code === 'EPERM') alive = true
+  }
+
+  if (!alive) {
+    try { unlinkSync(STATE_FILE) } catch {}
+    console.error('mesh: not running (stale state removed)')
+    process.exit(1)
+  }
+
+  const protocol = state.https ? 'https' : 'http'
+  const pad = Math.max(...Object.keys(state.services).map(s => s.length))
+  console.log('')
+  console.log(`  ${CYAN}mesh${RESET}  running  ${DIM}pid ${state.pid}${RESET}`)
+  console.log('')
+  for (const [name, port] of Object.entries(state.services)) {
+    console.log(`  ${GREEN}${name.padEnd(pad)}.test${RESET}  ${DIM}→ :${port}  ${protocol}://${name}.test${RESET}`)
+  }
+  console.log('')
+  process.exit(0)
+}
+
 if (cmd !== 'route') {
   console.error('Usage:')
-  console.error('  mesh init                      create mesh.yml in current directory')
-  console.error('  sudo mesh route                start proxy')
-  console.error('  sudo mesh route --config <path>  use a specific config file')
+  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)')
   process.exit(1)
 }
 
@@ -60,10 +160,13 @@ const configDir = dirname(resolve(configPath))
 const certs     = ensureCerts(services, configDir)
 const servers   = startProxy(services, rules, certs)
 
+writeFileSync(STATE_FILE, JSON.stringify({ pid: process.pid, configPath, services, https: !!certs }))
+
 // ── Crash safety — clean /etc/hosts even on unexpected exit ───────────────────
 
 function shutdown(code = 0) {
   removeHosts()
+  try { unlinkSync(STATE_FILE) } catch {}
   servers.http.close()
   servers.https?.close()
   process.exit(code)
@@ -99,6 +202,7 @@ watch(configPath, () => {
       Object.assign(rules, next.rules)
 
       writeHosts(services)
+      writeFileSync(STATE_FILE, JSON.stringify({ pid: process.pid, configPath, services, https: !!certs }))
 
       if (certs && hasNewServices) {
         const newCerts = ensureCerts(services, configDir)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avelor/mesh",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local dev proxy. Named services, failure rules, no ports.",
   "keywords": [
     "proxy",
@@ -35,6 +35,9 @@
     "http-proxy": "^1.18.1",
     "js-yaml": "^4.1.0"
   },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18"
   }

package/src/config.js

@@ -2,7 +2,8 @@ import { readFileSync, existsSync } from 'fs'
 import { resolve } from 'path'
 import yaml from 'js-yaml'
 
-const NAME_RE = /^[a-z0-9][a-z0-9.-]*$/
+const NAME_RE    = /^[a-z0-9][a-z0-9.-]*$/
+const METHODS    = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'])
 
 export function findConfigFile(cwd = process.cwd()) {
   for (const name of ['mesh.yml', 'mesh.yaml']) {
@@ -53,11 +54,16 @@ export function loadConfig(cwdOrFile = process.cwd()) {
       if (r.delay !== undefined && (typeof r.delay !== 'number' || r.delay < 0)) {
         throw new Error(`${prefix}.delay must be a positive number`)
       }
+      if (r.method !== undefined && !METHODS.has(r.method.toUpperCase())) {
+        throw new Error(`${prefix}.method must be a valid HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)`)
+      }
       return {
         path:   r.path   ?? '/',
+        method: r.method ? r.method.toUpperCase() : null,
         status: r.status ?? null,
         delay:  r.delay  ?? null,
         rate:   r.rate   ?? 100,
+        body:   r.body   ?? null,
       }
     })
   }

package/src/error-page.js

@@ -0,0 +1,68 @@
+export function wantsHtml(req) {
+  return (req.headers.accept ?? '').includes('text/html')
+}
+
+export function errorPage(status, name, { services = null, port = null, protocol = 'http' } = {}) {
+  const is404 = status === 404
+  const heading = is404
+    ? `<span class="hl">${name}.test</span> not found`
+    : `<span class="hl">${name}.test</span> is not responding`
+  const message = is404
+    ? 'No service is configured for this hostname.'
+    : `The service is configured but not reachable on <span class="mono">:${port}</span>. Is it running?`
+
+  const servicesBlock = (is404 && services && Object.keys(services).length)
+    ? `<div class="services">
+        <div class="label">configured services</div>
+        ${Object.entries(services).map(([n, p]) =>
+          `<div class="row">
+            <a class="name" href="${protocol}://${n}.test">${n}.test</a>
+            <span class="port">:${p}</span>
+          </div>`
+        ).join('')}
+      </div>`
+    : ''
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>mesh — ${status}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      background: #0d0d0d;
+      color: #555;
+      font-family: 'SF Mono', ui-monospace, 'Cascadia Code', monospace;
+      font-size: 13px;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 40px 24px;
+    }
+    .wrap { width: 100%; max-width: 440px; }
+    .status { color: #2a2a2a; font-size: 11px; letter-spacing: 0.08em; margin-bottom: 28px; }
+    h1 { color: #ccc; font-size: 16px; font-weight: 500; line-height: 1.5; margin-bottom: 10px; }
+    .hl { color: #e2e2e2; }
+    p { line-height: 1.7; }
+    .mono { font-family: inherit; color: #888; }
+    .services { margin-top: 40px; }
+    .label { font-size: 10px; letter-spacing: 0.1em; text-transform: uppercase; color: #2a2a2a; margin-bottom: 14px; }
+    .row { display: flex; align-items: baseline; gap: 10px; padding: 7px 0; border-top: 1px solid #181818; }
+    .name { color: #4ade80; text-decoration: none; }
+    .name:hover { color: #86efac; }
+    .port { color: #2e2e2e; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="status">mesh / ${status}</div>
+    <h1>${heading}</h1>
+    <p>${message}</p>
+    ${servicesBlock}
+  </div>
+</body>
+</html>`
+}

package/src/hosts.js

@@ -4,31 +4,26 @@ const HOSTS_FILE  = '/etc/hosts'
 const MESH_START  = '# mesh:start'
 const MESH_END    = '# mesh:end'
 
-export function writeHosts(services) {
-  const current = readFileSync(HOSTS_FILE, 'utf8')
-
-  // Remove any previous mesh block
-  const clean = removeMeshBlock(current)
-
+export function writeHosts(services, hostsFile = HOSTS_FILE) {
+  const current = readFileSync(hostsFile, 'utf8')
+  const clean   = removeMeshBlock(current)
   const entries = Object.keys(services)
     .map(name => `127.0.0.1 ${name}.test`)
     .join('\n')
-
   const next = `${clean.trimEnd()}\n\n${MESH_START}\n${entries}\n${MESH_END}\n`
-
-  writeFileSync(HOSTS_FILE, next, 'utf8')
+  writeFileSync(hostsFile, next, 'utf8')
 }
 
-export function removeHosts() {
+export function removeHosts(hostsFile = HOSTS_FILE) {
   try {
-    const current = readFileSync(HOSTS_FILE, 'utf8')
-    writeFileSync(HOSTS_FILE, removeMeshBlock(current).trimEnd() + '\n', 'utf8')
+    const current = readFileSync(hostsFile, 'utf8')
+    writeFileSync(hostsFile, removeMeshBlock(current).trimEnd() + '\n', 'utf8')
   } catch {
     // Best-effort cleanup
   }
 }
 
-function removeMeshBlock(content) {
+export function removeMeshBlock(content) {
   return content.replace(
     new RegExp(`\\n?${MESH_START}[\\s\\S]*?${MESH_END}\\n?`, 'g'),
     ''

package/src/proxy.js

@@ -3,6 +3,7 @@ import https            from 'https'
 import { readFileSync } from 'fs'
 import httpProxy        from 'http-proxy'
 import { matchRule, applyRule } from './rules.js'
+import { wantsHtml, errorPage } from './error-page.js'
 
 const RESET  = '\x1b[0m'
 const DIM    = '\x1b[2m'
@@ -15,11 +16,17 @@ export function startProxy(services, rules, certs = null) {
   const proxy = httpProxy.createProxyServer({ xfwd: true })
 
   proxy.on('error', (err, req, res) => {
-    const host = req.headers.host?.split('.')[0] ?? '?'
-    log(RED, 'ERR', host, req.url, `→ ${err.code ?? err.message}`)
+    const { name, target } = resolveService(req.headers.host)
+    log(RED, 'ERR', name, req.url, `→ ${err.code ?? err.message}`)
     if (!res.headersSent) {
-      res.writeHead(502, { 'Content-Type': 'application/json' })
-      res.end(JSON.stringify({ error: 'Service unavailable', service: host }))
+      const protocol = certs ? 'https' : 'http'
+      if (wantsHtml(req)) {
+        res.writeHead(502, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(errorPage(502, name, { port: target, protocol }))
+      } else {
+        res.writeHead(502, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'Service unavailable', service: name }))
+      }
     }
   })
 
@@ -33,14 +40,20 @@ export function startProxy(services, rules, certs = null) {
     const { name, target } = resolveService(req.headers.host)
 
     if (!target) {
-      res.writeHead(404, { 'Content-Type': 'application/json' })
-      res.end(JSON.stringify({ error: `Unknown service: ${name}` }))
+      const protocol = certs ? 'https' : 'http'
+      if (wantsHtml(req)) {
+        res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(errorPage(404, name, { services, protocol }))
+      } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: `Unknown service: ${name}` }))
+      }
       return
     }
 
     const pathname = new URL(req.url, 'http://x').pathname
 
-    const rule = matchRule(rules, name, pathname)
+    const rule = matchRule(rules, name, pathname, req.method)
 
     if (rule) {
       const injected = await applyRule(rule, res)
@@ -122,8 +135,9 @@ function onReady(services, rules, certs) {
     console.log('')
     for (const [svc, ruleList] of Object.entries(rules)) {
       for (const r of ruleList) {
-        const type = r.status ? `${r.status}` : `${r.delay}ms delay`
-        console.log(`  ${YELLOW}${svc}${r.path}${RESET}  ${DIM}${r.rate}% → ${type}${RESET}`)
+        const type      = r.status ? `${r.status}` : `${r.delay}ms delay`
+        const methodStr = r.method ? `${r.method} ` : ''
+        console.log(`  ${YELLOW}${svc}${r.path}${RESET}  ${DIM}${methodStr}${r.rate}% → ${type}${RESET}`)
       }
     }
   }

package/src/rules.js

@@ -1,9 +1,10 @@
-export function matchRule(rules, serviceName, pathname) {
+export function matchRule(rules, serviceName, pathname, method) {
   const serviceRules = rules[serviceName]
   if (!serviceRules) return null
 
   for (const rule of serviceRules) {
     if (!pathname.startsWith(rule.path)) continue
+    if (rule.method && rule.method !== method.toUpperCase()) continue
     if (rule.rate === 0) continue
     if (Math.random() * 100 > rule.rate) continue
     return rule
@@ -16,8 +17,12 @@ export function applyRule(rule, res) {
   return new Promise(resolve => {
     const respond = () => {
       if (rule.status) {
-        res.writeHead(rule.status, { 'Content-Type': 'application/json' })
-        res.end(JSON.stringify({ error: statusText(rule.status), injected: true }))
+        const body  = rule.body ?? { error: statusText(rule.status), injected: true }
+        const isObj = typeof body !== 'string'
+        const raw   = isObj ? JSON.stringify(body) : body
+        const type  = isObj ? 'application/json' : 'text/plain'
+        res.writeHead(rule.status, { 'Content-Type': type })
+        res.end(raw)
       }
       resolve(rule.status != null)
     }