@avelor/mesh 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avelor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# mesh
+
+Local dev proxy. Named services instead of ports. Failure injection without mocks.
+
+```
+app.test   → :3000
+api.test   → :4000
+admin.test → :5000
+```
+
+No more `:3000`, `:4000`, `:5000` open in different tabs. No more mixing them up.
+
+---
+
+## Install
+
+```bash
+npm install -g @avelor/mesh
+```
+
+Requires Node.js 18+. For HTTPS, install [mkcert](https://github.com/FiloSottile/mkcert).
+
+---
+
+## Usage
+
+```bash
+mesh init        # create mesh.yml in current directory
+sudo mesh route  # start proxy (writes /etc/hosts)
+```
+
+`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.yml
+
+```yaml
+services:
+  app: 3000
+  api: 4000
+  admin: 5000
+```
+
+That's enough to get started. Services are available at `app.test`, `api.test`, `admin.test`.
+
+### Failure rules
+
+Test how your app handles errors — no mocks, no code changes.
+
+```yaml
+services:
+  app: 3000
+  api: 4000
+
+rules:
+  api:
+    - path: /payments
+      status: 503
+      rate: 30
+    - path: /auth/login
+      status: 401
+      rate: 20
+    - path: /slow-endpoint
+      delay: 2000
+      rate: 100
+    - path: /flaky
+      status: 500
+      delay: 800
+      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)|
+
+`status` and `delay` can be combined: wait N ms, then fail with that status.
+
+### Subdomains
+
+Multiple names can point to the same port:
+
+```yaml
+services:
+  app: 3000
+  tenant1.app: 3000
+  tenant2.app: 3000
+  api: 4000
+```
+
+Rules apply per name, so `tenant1.app` and `tenant2.app` can have different failure scenarios.
+
+---
+
+## HTTPS
+
+If [mkcert](https://github.com/FiloSottile/mkcert) is installed, `mesh route` automatically generates a locally-trusted certificate for all your `.test` domains and serves them over HTTPS. Port `:80` redirects to `:443`.
+
+```bash
+# macOS
+brew install mkcert
+
+# Linux
+apt install mkcert
+```
+
+If mkcert is not found, mesh falls back to HTTP only.
+
+Generated certificates are stored in `.mesh/` (added to `.gitignore` by `mesh init`).
+
+---
+
+## Examples
+
+See [`examples/basic`](examples/basic) and [`examples/multi`](examples/multi) for working setups with a frontend and API server.
+
+```bash
+# terminal 1
+cd examples/basic
+node api.js
+
+# terminal 2
+cd examples/basic
+node app.js
+
+# terminal 3 (from examples/basic)
+sudo mesh route
+```
+
+Then open `https://app.test`.
+
+---
+
+## How it works
+
+`mesh route` runs a local HTTP/HTTPS proxy on `127.0.0.1`. Incoming requests are matched by hostname, forwarded to the configured port, and optionally intercepted by failure rules before reaching the target service.
+
+`/etc/hosts` entries are written on start and removed on exit (`SIGINT` / `SIGTERM`).
+
+---
+
+## License
+
+MIT

package/bin/mesh.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { watch, existsSync, readFileSync } from 'fs'
+import { dirname, resolve }                from 'path'
+import { createRequire }                   from 'module'
+import { loadConfig }              from '../src/config.js'
+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'
+
+// ── Argument parsing ──────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2)
+const cmd  = args.find(a => !a.startsWith('-'))
+
+const configIdx  = args.indexOf('--config')
+const configArg  = configIdx !== -1 ? args[configIdx + 1] : null
+
+if (args.includes('--version') || args.includes('-v')) {
+  const { version } = createRequire(import.meta.url)('../package.json')
+  console.log(version)
+  process.exit(0)
+}
+
+if (cmd === 'init') {
+  init()
+  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')
+  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)
+}
+
+// ── Load config ───────────────────────────────────────────────────────────────
+
+let config
+try {
+  config = loadConfig(configArg ?? process.cwd())
+} catch (err) {
+  console.error('mesh:', err.message)
+  process.exit(1)
+}
+
+const { services, rules, configPath } = config
+
+writeHosts(services)
+
+const configDir = dirname(resolve(configPath))
+const certs     = ensureCerts(services, configDir)
+const servers   = startProxy(services, rules, certs)
+
+// ── Crash safety — clean /etc/hosts even on unexpected exit ───────────────────
+
+function shutdown(code = 0) {
+  removeHosts()
+  servers.http.close()
+  servers.https?.close()
+  process.exit(code)
+}
+
+process.on('SIGINT',  () => { console.log('\n  mesh  cleaning up...'); shutdown(0) })
+process.on('SIGTERM', () => shutdown(0))
+
+process.on('uncaughtException', err => {
+  console.error('\n  mesh  uncaught exception:', err.message)
+  shutdown(1)
+})
+
+process.on('unhandledRejection', err => {
+  console.error('\n  mesh  unhandled rejection:', err?.message ?? err)
+  shutdown(1)
+})
+
+// ── Hot-reload ────────────────────────────────────────────────────────────────
+
+let reloadTimer
+watch(configPath, () => {
+  clearTimeout(reloadTimer)
+  reloadTimer = setTimeout(() => {
+    try {
+      const next = loadConfig(configPath)
+
+      const hasNewServices = Object.keys(next.services).some(k => !services[k])
+
+      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)
+
+      writeHosts(services)
+
+      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)
+})

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@avelor/mesh",
+  "version": "0.1.0",
+  "description": "Local dev proxy. Named services, failure rules, no ports.",
+  "keywords": [
+    "proxy",
+    "dev",
+    "local",
+    "localhost",
+    "https",
+    "hosts",
+    "dns",
+    "chaos",
+    "fault-injection",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "author": "Avelor <cruz@avelor.es>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/avelor-es/mesh"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "mesh": "./bin/mesh.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "http-proxy": "^1.18.1",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/certs.js

@@ -0,0 +1,58 @@
+import { execFileSync, spawnSync } from 'child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { resolve } from 'path'
+
+function mkcertInstalled() {
+  return spawnSync('which', ['mkcert']).status === 0
+}
+
+function caInstalled() {
+  try {
+    const caRoot = execFileSync('mkcert', ['-CAROOT'], { encoding: 'utf8' }).trim()
+    return existsSync(resolve(caRoot, 'rootCA.pem'))
+  } catch {
+    return false
+  }
+}
+
+function cachedDomains(dir) {
+  try {
+    return JSON.parse(readFileSync(resolve(dir, 'domains.json'), 'utf8'))
+  } catch {
+    return []
+  }
+}
+
+export function ensureCerts(services, cwd = process.cwd()) {
+  if (!mkcertInstalled()) {
+    console.warn('mesh: mkcert not found — running HTTP only')
+    console.warn('      macOS:  brew install mkcert')
+    console.warn('      Linux:  apt install mkcert  /  snap install mkcert')
+    console.warn('')
+    return null
+  }
+
+  const dir      = resolve(cwd, '.mesh')
+  const certFile = resolve(dir, 'cert.pem')
+  const keyFile  = resolve(dir, 'key.pem')
+
+  mkdirSync(dir, { recursive: true })
+
+  if (!caInstalled()) {
+    execFileSync('mkcert', ['-install'], { stdio: 'ignore' })
+  }
+
+  const domains = Object.keys(services).map(n => `${n}.test`).sort()
+  const cached  = cachedDomains(dir).sort()
+
+  const needsRegen = JSON.stringify(domains) !== JSON.stringify(cached)
+    || !existsSync(certFile)
+    || !existsSync(keyFile)
+
+  if (needsRegen) {
+    execFileSync('mkcert', ['-cert-file', certFile, '-key-file', keyFile, ...domains], { stdio: 'ignore' })
+    writeFileSync(resolve(dir, 'domains.json'), JSON.stringify(domains))
+  }
+
+  return { certFile, keyFile }
+}

package/src/config.js

@@ -0,0 +1,66 @@
+import { readFileSync, existsSync } from 'fs'
+import { resolve } from 'path'
+import yaml from 'js-yaml'
+
+const NAME_RE = /^[a-z0-9][a-z0-9.-]*$/
+
+export function findConfigFile(cwd = process.cwd()) {
+  for (const name of ['mesh.yml', 'mesh.yaml']) {
+    const p = resolve(cwd, name)
+    if (existsSync(p)) return p
+  }
+  throw new Error(`mesh.yml not found in ${cwd} — run 'mesh init' to create one`)
+}
+
+export function loadConfig(cwdOrFile = process.cwd()) {
+  let path
+  if (cwdOrFile.endsWith('.yml') || cwdOrFile.endsWith('.yaml')) {
+    path = resolve(cwdOrFile)
+    if (!existsSync(path)) throw new Error(`config file not found: ${path}`)
+  } else {
+    path = findConfigFile(cwdOrFile)
+  }
+
+  const data = yaml.load(readFileSync(path, 'utf8'))
+
+  if (!data?.services || typeof data.services !== 'object') {
+    throw new Error('mesh.yml must define at least one service')
+  }
+
+  const services = {}
+  for (const [name, raw] of Object.entries(data.services)) {
+    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) {
+      throw new Error(`invalid port for service "${name}": ${raw}`)
+    }
+    services[name] = port
+  }
+
+  const rules = {}
+  for (const [name, list] of Object.entries(data.rules ?? {})) {
+    if (!services[name]) throw new Error(`rule references unknown service "${name}"`)
+    rules[name] = (list ?? []).map((r, i) => {
+      const prefix = `rules.${name}[${i}]`
+      if (r.status !== undefined && (typeof r.status !== 'number' || !Number.isInteger(r.status))) {
+        throw new Error(`${prefix}.status must be an integer`)
+      }
+      if (r.rate !== undefined && (typeof r.rate !== 'number' || r.rate < 0 || r.rate > 100)) {
+        throw new Error(`${prefix}.rate must be a number between 0 and 100`)
+      }
+      if (r.delay !== undefined && (typeof r.delay !== 'number' || r.delay < 0)) {
+        throw new Error(`${prefix}.delay must be a positive number`)
+      }
+      return {
+        path:   r.path   ?? '/',
+        status: r.status ?? null,
+        delay:  r.delay  ?? null,
+        rate:   r.rate   ?? 100,
+      }
+    })
+  }
+
+  return { services, rules, configPath: path }
+}

package/src/hosts.js

@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync } from 'fs'
+
+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)
+
+  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')
+}
+
+export function removeHosts() {
+  try {
+    const current = readFileSync(HOSTS_FILE, 'utf8')
+    writeFileSync(HOSTS_FILE, removeMeshBlock(current).trimEnd() + '\n', 'utf8')
+  } catch {
+    // Best-effort cleanup
+  }
+}
+
+function removeMeshBlock(content) {
+  return content.replace(
+    new RegExp(`\\n?${MESH_START}[\\s\\S]*?${MESH_END}\\n?`, 'g'),
+    ''
+  )
+}

package/src/init.js

@@ -0,0 +1,43 @@
+import { existsSync, writeFileSync, readFileSync, appendFileSync } from 'fs'
+import { resolve } from 'path'
+
+const TEMPLATE = `services:
+  app: 3000
+  api: 4000
+
+# rules:
+#   api:
+#     - path: /payments
+#       status: 503
+#       rate: 30
+#     - path: /slow-endpoint
+#       delay: 2000
+#       rate: 100
+#     - path: /flaky
+#       status: 500
+#       delay: 800
+#       rate: 25
+`
+
+export function init(cwd = process.cwd()) {
+  const path = resolve(cwd, 'mesh.yml')
+
+  if (existsSync(path)) {
+    console.error('mesh: mesh.yml already exists')
+    process.exit(1)
+  }
+
+  writeFileSync(path, TEMPLATE, 'utf8')
+  console.log('mesh: created mesh.yml')
+
+  const gitignorePath = resolve(cwd, '.gitignore')
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf8')
+    if (!content.includes('.mesh')) {
+      appendFileSync(gitignorePath, '\n.mesh/\n')
+      console.log('mesh: added .mesh/ to .gitignore')
+    }
+  }
+
+  console.log('      edit your services and run: sudo mesh route')
+}

package/src/proxy.js

@@ -0,0 +1,136 @@
+import http             from 'http'
+import https            from 'https'
+import { readFileSync } from 'fs'
+import httpProxy        from 'http-proxy'
+import { matchRule, applyRule } from './rules.js'
+
+const RESET  = '\x1b[0m'
+const DIM    = '\x1b[2m'
+const GREEN  = '\x1b[32m'
+const YELLOW = '\x1b[33m'
+const RED    = '\x1b[31m'
+const CYAN   = '\x1b[36m'
+
+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}`)
+    if (!res.headersSent) {
+      res.writeHead(502, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Service unavailable', service: host }))
+    }
+  })
+
+  function resolveService(host) {
+    const hostname = (host ?? '').replace(/:\d+$/, '')
+    const name     = hostname.endsWith('.test') ? hostname.slice(0, -5) : hostname
+    return { name, target: services[name] }
+  }
+
+  async function handle(req, res) {
+    const { name, target } = resolveService(req.headers.host)
+
+    if (!target) {
+      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)
+
+    if (rule) {
+      const injected = await applyRule(rule, res)
+      if (injected) {
+        const label = rule.delay ? `${rule.delay}ms+${rule.status}` : `${rule.status}`
+        log(YELLOW, label, name, pathname, `→ injected`)
+        return
+      }
+      log(YELLOW, `${rule.delay}ms`, name, pathname, `→ :${target} (delayed)`)
+    }
+
+    proxy.web(req, res, { target: `http://127.0.0.1:${target}` })
+    if (!rule) log(DIM, '→', name, pathname, `→ :${target}`)
+  }
+
+  function handleUpgrade(req, socket, head) {
+    const { name, target } = resolveService(req.headers.host)
+    if (!target) { socket.destroy(); return }
+    proxy.ws(req, socket, head, { target: `ws://127.0.0.1:${target}` }, err => {
+      if (err) log(RED, 'WSE', name, req.url, `→ ${err.code ?? err.message}`)
+    })
+    log(DIM, 'WS', name, req.url, `→ :${target}`)
+  }
+
+  const httpServer = http.createServer((req, res) => {
+    if (certs) {
+      const host = (req.headers.host ?? '').replace(/:80$/, '')
+      res.writeHead(301, { Location: `https://${host}${req.url}` })
+      res.end()
+      return
+    }
+    handle(req, res)
+  })
+
+  httpServer.on('upgrade', handleUpgrade)
+
+  httpServer.on('error', err => {
+    if (err.code === 'EADDRINUSE') {
+      console.error('mesh: port 80 is already in use — stop whatever is running on it and retry')
+      process.exit(1)
+    }
+    throw err
+  })
+
+  httpServer.listen(80, '127.0.0.1', () => onReady(services, rules, certs))
+
+  let httpsServer = null
+
+  if (certs) {
+    httpsServer = https.createServer(
+      { cert: readFileSync(certs.certFile), key: readFileSync(certs.keyFile) },
+      handle
+    )
+    httpsServer.on('upgrade', handleUpgrade)
+    httpsServer.on('error', err => {
+      if (err.code === 'EADDRINUSE') {
+        console.error('mesh: port 443 is already in use — stop whatever is running on it and retry')
+        process.exit(1)
+      }
+      throw err
+    })
+    httpsServer.listen(443, '127.0.0.1')
+  }
+
+  return { http: httpServer, https: httpsServer }
+}
+
+function onReady(services, rules, certs) {
+  const pad      = Math.max(...Object.keys(services).map(s => s.length))
+  const protocol = certs ? 'https' : 'http'
+
+  console.log('')
+  console.log(`  ${CYAN}mesh${RESET}  ${certs ? 'https + http→https redirect' : 'http only'}`)
+  console.log('')
+  for (const [name, port] of Object.entries(services)) {
+    console.log(`  ${GREEN}${name.padEnd(pad)}.test${RESET}  ${DIM}→ :${port}  ${protocol}://${name}.test${RESET}`)
+  }
+  if (Object.keys(rules).length) {
+    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}`)
+      }
+    }
+  }
+  console.log('')
+}
+
+function log(color, label, service, path, tail) {
+  const time = new Date().toTimeString().slice(0, 8)
+  console.log(`  ${DIM}${time}${RESET}  ${color}${label}${RESET}  ${service}${DIM}${path}${RESET}  ${DIM}${tail}${RESET}`)
+}

package/src/rules.js

@@ -0,0 +1,47 @@
+export function matchRule(rules, serviceName, pathname) {
+  const serviceRules = rules[serviceName]
+  if (!serviceRules) return null
+
+  for (const rule of serviceRules) {
+    if (!pathname.startsWith(rule.path)) continue
+    if (rule.rate === 0) continue
+    if (Math.random() * 100 > rule.rate) continue
+    return rule
+  }
+
+  return null
+}
+
+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 }))
+      }
+      resolve(rule.status != null)
+    }
+
+    if (rule.delay) {
+      setTimeout(respond, rule.delay)
+    } else {
+      respond()
+    }
+  })
+}
+
+function statusText(code) {
+  const map = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    408: 'Request Timeout',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+  }
+  return map[code] ?? 'Error'
+}