Commit 0eb423be by PLN (Algolia)

devname: stable local names for dev servers

parents
__pycache__/
*.pyc
This diff is collapsed. Click to expand it.
# devname
Stable local names for dev servers, so nobody — human or agent — remembers ports.
Every dev server on the machine answers at a stable `*.localhost` name:
`hindsight.localhost`, `bench.sre.localhost`, `devname.localhost`. One Caddy
proxies names to ports; a tiny registry keeps the truth; a CLI makes the whole
thing boring.
```
devname ensure [project] [--service S] [--branch auto]
```
`ensure` is the only verb an agent ever needs: it prints the URL if the name
exists, otherwise it allocates a port (17000–17999), registers the name and
reloads Caddy. Idempotent, safe to run concurrently (the registry is
`flock`ed), safe to forget.
## Why `.localhost`
`*.localhost` resolves to loopback on any modern OS (RFC 6761) with zero DNS
setup — no `/etc/hosts`, no resolver config, no mDNS (`.local` collides with
Bonjour). Names are local-program-only **by construction**: the generated
Caddyfile aborts every connection whose source is not loopback, so nothing
leaks onto the LAN even though the proxy binds the wildcard (the only way an
unprivileged process can bind a low port on macOS).
## Install
Requirements: macOS (launchd agent), [Caddy](https://caddyserver.com), Python 3.
For https: [mkcert](https://github.com/FiloSottile/mkcert) with a trusted root
(`mkcert -install`).
```bash
git clone <this repo> && cd devname
sudo cp bin/devname /usr/local/bin/devname && sudo chmod +x /usr/local/bin/devname
devname agent install # one launchd agent (label DEVNAME_LABEL, default: devname)
devname ensure myapp # myapp.localhost — allocated or adopted, Caddy reloaded
devname doctor # check the whole chain
```
## Commands
```
devname ensure [project] [--service S] [--branch B|auto] [--port N] [--keep-host] [--format url|port|json]
devname ls [--json] devname rm <host> devname check <host>
devname render devname serve devname doctor
devname agent install|status
```
- `<project>.localhost` — the project's main site
- `<service>.<project>.localhost` — a sub-service (`tests.leboard.localhost`)
- `<name>--<branch>[.<project>].localhost` — a branch variant; a worktree never
collides with the main checkout
The agent also serves the **index page** (`devname.localhost`): every
registered name with live up/down status, probed per request, plus `/json`.
## For agents
The design target was agents starting servers: never hard-code a port, never
parse `lsof`.
```bash
PORT=$(devname ensure myapp --format port)
./myapp --port "$PORT" # now at myapp.localhost
```
The registry is a flat `names.json` (`$DEVNAME_HOME`, default
`~/.config/devnames`); the Caddyfile is generated from it, never hand-edited.
`mkcert` issues one SAN certificate covering every registered name.
## Tests
```bash
python3 -m unittest discover tests
```
## License
GPL-3.0-only — see [LICENSE](LICENSE).
This diff is collapsed. Click to expand it.
import importlib.machinery
import importlib.util
import io
import json
import os
import pathlib
import tempfile
import unittest
from contextlib import redirect_stderr, redirect_stdout
ROOT = pathlib.Path(__file__).resolve().parent.parent
def load_module(conf):
os.environ["DEVNAME_HOME"] = conf
loader = importlib.machinery.SourceFileLoader("devname_under_test", str(ROOT / "bin" / "devname"))
spec = importlib.util.spec_from_loader("devname_under_test", loader)
mod = importlib.util.module_from_spec(spec)
loader.exec_module(mod)
return mod
class DevnameTests(unittest.TestCase):
def setUp(self):
self._tmp = tempfile.TemporaryDirectory()
self.addCleanup(self._tmp.cleanup)
self.dn = load_module(self._tmp.name)
def run_cli(self, *argv):
out, err = io.StringIO(), io.StringIO()
with redirect_stdout(out), redirect_stderr(err):
rc = self.dn.main(list(argv))
return rc, out.getvalue().strip(), err.getvalue()
# naming
def test_names_follow_the_convention(self):
h = self.dn.hostname
self.assertEqual(h("leboard"), "leboard.localhost")
self.assertEqual(h("leboard", "tests"), "tests.leboard.localhost")
self.assertEqual(h("leboard", None, "feat/x y"), "leboard--feat-x-y.localhost")
self.assertEqual(h("leboard", "tests", "Fix_1"), "tests--fix-1.leboard.localhost")
def test_slug_is_dns_safe_and_bounded(self):
s = self.dn.slug("Feature/Ünï cøde!!" + "z" * 80)
self.assertLessEqual(len(s), 40)
self.assertRegex(s, r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
self.assertNotEqual(self.dn.slug("a" * 60), self.dn.slug("a" * 61))
def test_bad_names_are_refused(self):
for bad in ("Foo", "a--b", "a-", "a_b", "x" * 41):
rc, _, err = self.run_cli("ensure", bad)
self.assertEqual(rc, 2, bad)
self.assertIn("must be lowercase", err)
# ensure
def test_ensure_is_idempotent_and_prints_the_url(self):
rc, out, err = self.run_cli("ensure", "demo")
self.assertEqual((rc, out), (0, "http://demo.localhost"))
self.assertIn("created", err)
port = json.loads(self.run_cli("ensure", "demo", "--format", "json")[1])
rc, out, err = self.run_cli("ensure", "demo", "--format", "port")
self.assertEqual(out, str(port["port"]))
self.assertFalse(port["created"])
self.assertIn("exists", err)
self.assertIn(self.dn.POOL.start, range(17000, 18000))
self.assertIn(port["port"], self.dn.POOL)
def test_allocated_ports_never_collide(self):
ports = {int(self.run_cli("ensure", "p", "--service", f"s{i}", "--format", "port")[1]) for i in range(5)}
self.assertEqual(len(ports), 5)
def test_adopting_an_existing_port_and_conflicts(self):
self.assertEqual(self.run_cli("ensure", "sre", "--service", "bench", "--port", "8895")[0], 0)
rc, _, err = self.run_cli("ensure", "sre", "--service", "bench", "--port", "9000")
self.assertEqual(rc, 2)
self.assertIn("already maps to port 8895", err)
rc, _, err = self.run_cli("ensure", "other", "--port", "8895")
self.assertEqual(rc, 2)
self.assertIn("already registered as bench.sre.localhost", err)
self.assertEqual(self.run_cli("ensure", "sre", "--service", "bench", "--port", "9000", "--force")[0], 0)
self.assertEqual(self.dn.load()["entries"]["bench.sre.localhost"]["port"], 9000)
def test_branch_variant_is_a_separate_name(self):
self.run_cli("ensure", "sre", "--service", "bench", "--port", "8895")
rc, out, _ = self.run_cli("ensure", "sre", "--service", "bench", "--branch", "feat/a")
self.assertEqual(out, "http://bench--feat-a.sre.localhost")
self.assertEqual(len(self.dn.load()["entries"]), 2)
# a main/master branch means no suffix
rc, out, _ = self.run_cli("ensure", "sre", "--service", "bench", "--branch", "main")
self.assertEqual(out, "http://bench.sre.localhost")
# rendering
def test_caddyfile_drops_non_loopback_and_rewrites_host(self):
self.run_cli("ensure", "sre", "--service", "bench", "--port", "8895")
self.run_cli("ensure", "app", "--port", "8123", "--keep-host")
text = (pathlib.Path(self._tmp.name) / "Caddyfile").read_text()
self.assertIn("abort @notlocal", text)
self.assertIn("not remote_ip 127.0.0.0/8 ::1", text)
self.assertIn("auto_https off", text)
self.assertNotIn("default_bind", text) # a specific-address bind of :80 needs root on macOS
self.assertIn("http://bench.sre.localhost {", text)
self.assertIn("reverse_proxy 127.0.0.1:8895", text)
self.assertIn("header_up Host 127.0.0.1:8895", text)
app_block = text.split("http://app.localhost {")[1].split("}\n}")[0]
self.assertNotIn("header_up", app_block)
self.assertEqual(text.count("abort @notlocal"), text.count("reverse_proxy")) # every site is guarded
def test_index_site_is_always_rendered_and_guarded(self):
self.run_cli("ensure", "app", "--port", "8123")
text = (pathlib.Path(self._tmp.name) / "Caddyfile").read_text()
self.assertIn("http://devname.localhost {", text)
self.assertIn("reverse_proxy 127.0.0.1:16999", text)
self.assertEqual(text.count("abort @notlocal"), text.count("reverse_proxy")) # the index site too
def test_index_page_lists_names_with_live_status(self):
self.run_cli("ensure", "app", "--port", "8123", "--note", "demo app")
page = self.dn.index_page()
self.assertIn("app.localhost", page)
self.assertIn("demo app", page)
rows = self.dn.index_rows()
self.assertEqual(len(rows), 1)
host, entry, up = rows[0]
self.assertEqual(host, "app.localhost")
self.assertFalse(up) # nothing listens on 8123 in the test
self.dn.save({"version": 1, "entries": {}}) # empty registry renders an empty page, not a crash
self.assertIn("0 names · 0 up", self.dn.index_page())
def test_https_blocks_only_when_a_cert_exists(self):
reg = {"entries": {"a.localhost": {"port": 1, "rewrite": True}}}
self.assertNotIn("https://", self.dn.render_caddyfile(reg, False))
with_tls = self.dn.render_caddyfile(reg, True)
self.assertIn("https://a.localhost {", with_tls)
self.assertIn("tls ", with_tls)
def test_mkcert_skips_the_java_trust_store(self):
self.assertEqual(self.dn.MKCERT_ENV["TRUST_STORES"], "system,nss")
def test_rm_and_ls(self):
self.run_cli("ensure", "gone")
self.assertEqual(self.run_cli("rm", "gone")[0], 0)
self.assertEqual(self.run_cli("rm", "gone")[0], 2)
self.assertEqual(json.loads(self.run_cli("ls", "--json")[1]), [])
def test_registry_file_is_atomic_and_private(self):
self.run_cli("ensure", "demo")
conf = pathlib.Path(self._tmp.name)
self.assertFalse((conf / "names.json.tmp").exists())
self.assertFalse((conf / "Caddyfile.tmp").exists())
self.assertEqual(oct(conf.stat().st_mode & 0o777), "0o700")
if __name__ == "__main__":
unittest.main()
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment