Commit 250c1f85 by PLN (Algolia)

devname: put OS specifics behind one platform layer; launchd agent behind it

Tool discovery, state and log paths, and the agent live in a Platform
class (MacPlatform for launchd, a base for any other Unix that refuses
agent and points at devname serve). agent gains uninstall, restart,
and install --print to show the plist without writing or loading it.
parent 1c3ff048
......@@ -68,13 +68,8 @@ CADDYFILE = os.path.join(CONF, "Caddyfile")
ADMIN_SOCK = os.path.join(CONF, "admin.sock")
CERT_DIR = os.path.join(CONF, "certs")
CERT, KEY, SANS = (os.path.join(CERT_DIR, n) for n in ("devname.pem", "devname-key.pem", "sans.txt"))
STATE = os.path.join(HOME, ".local", "state", "devname")
LABEL = "pl.nech.devname"
PLIST = os.path.join(HOME, "Library", "LaunchAgents", LABEL + ".plist")
LOGDIR = os.path.join(HOME, "Library", "Logs", "devname")
LABEL = os.environ.get("DEVNAME_LABEL") or "pl.nech.devname" # launchd label (macOS)
POOL = range(17000, 18000)
CADDY = shutil.which("caddy") or "/opt/homebrew/bin/caddy"
MKCERT = shutil.which("mkcert") or ("/opt/homebrew/bin/mkcert" if os.path.exists("/opt/homebrew/bin/mkcert") else None)
# no JDK keystore here: mkcert's optional Java step exits 1 and would block issuing the cert (found 2026-11-03)
MKCERT_ENV = dict(os.environ, TRUST_STORES="system,nss")
SUFFIX = ".localhost"
......@@ -122,6 +117,198 @@ def check_name(kind, value):
return value
# ---- platform layer: everything that differs between macOS, Linux and any other Unix lives here.
# The rest of the script asks PLAT; no other code path may assume an OS.
def run_out(cmd, timeout=10):
"""(returncode, stdout) of a short probe; (None, "") when it cannot run at all (tool missing, hung)."""
try:
r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
return r.returncode, r.stdout.strip()
except (OSError, subprocess.TimeoutExpired):
return None, ""
def read_os_release(path="/etc/os-release"):
"""/etc/os-release as a dict (empty when absent); ID and ID_LIKE pick the install hints."""
out = {}
try:
with open(path) as fh:
for raw in fh:
k, sep, v = raw.strip().partition("=")
if sep and not k.startswith("#"):
out[k] = v.strip().strip("\"'")
except OSError:
pass
return out
class Platform:
"""Any Unix without a supervisor devname knows: everything works except `agent`, and
`devname serve` is a plain foreground process to wrap in your own init (runit, OpenRC, tmux)."""
name = "other"
supervisor = None
running_words = ("running", "not running")
tool_dirs = ("/usr/local/bin", "/usr/bin")
def __init__(self, os_release=None):
self.os_release = os_release if os_release is not None else {}
def describe(self):
return f"{self.name} ({sys.platform}), supervisor: {self.supervisor or 'none, run `devname serve` yourself'}"
def state_dir(self):
"""Caddy's own data and config (the child's XDG_DATA_HOME / XDG_CONFIG_HOME)."""
base = os.environ.get("XDG_STATE_HOME") or os.path.join(HOME, ".local", "state")
return os.path.join(base, "devname")
def find_tool(self, name):
"""$DEVNAME_<NAME> override, then PATH, then the platform's usual install dirs; None when absent."""
env = os.environ.get("DEVNAME_" + name.upper().replace("-", "_"))
if env:
return env
found = shutil.which(name)
if found:
return found
for d in self.tool_dirs:
p = os.path.join(os.path.expanduser(d), name)
if os.path.isfile(p) and os.access(p, os.X_OK):
return p
return None
def agent_python(self):
"""Interpreter baked into the agent definition: a stable system path (survives upgrades),
else the one running now. Supervisors start with a minimal PATH, so never `env python3` there."""
for d in self.tool_dirs:
p = os.path.join(os.path.expanduser(d), "python3")
if os.path.isfile(p) and os.access(p, os.X_OK):
return p
return sys.executable
def agent_argv(self):
return [self.agent_python(), os.path.abspath(__file__), "serve"]
def install_hint(self, tool):
return f"install {tool} with your package manager"
def _no_agent(self):
raise Err(f"no supervisor integration on {sys.platform}: run `devname serve` under your init "
"(runit, OpenRC supervise-daemon, a tmux window)")
def agent_path(self):
return None
def agent_text(self):
self._no_agent()
def agent_running(self):
return None # unknown: no supervisor to ask
def agent_preflight(self):
return [] # problems that would make a freshly installed agent crash-loop
def agent_install(self):
self._no_agent()
def agent_uninstall(self):
self._no_agent()
def agent_restart(self):
self._no_agent()
def log_hint(self):
return "stderr of `devname serve`"
class MacPlatform(Platform):
"""launchd agent, Homebrew tools. macOS lets an unprivileged process bind :80/:443 on the wildcard
address, which is exactly what the generated Caddyfile does."""
name = "macos"
supervisor = "launchd"
running_words = ("loaded", "not loaded")
tool_dirs = ("/opt/homebrew/bin", "/usr/local/bin")
def state_dir(self):
return os.path.join(HOME, ".local", "state", "devname") # historic path: caddy's data stays put
def log_dir(self):
return os.path.join(HOME, "Library", "Logs", "devname")
def log_hint(self):
return os.path.join(self.log_dir(), "caddy.log")
def install_hint(self, tool):
return {"caddy": "brew install caddy",
"mkcert": "brew install mkcert nss (nss: Firefox trust)"}.get(tool, f"brew install {tool}")
def agent_path(self):
return os.path.join(HOME, "Library", "LaunchAgents", LABEL + ".plist")
def agent_text(self):
args = "".join(f"<string>{html.escape(x)}</string>" for x in self.agent_argv())
return f"""<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>{LABEL}</string>
<key>ProgramArguments</key><array>{args}</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>{self.log_dir()}/caddy.log</string>
<key>StandardErrorPath</key><string>{self.log_dir()}/caddy.log</string>
</dict></plist>
"""
def domain(self):
return f"gui/{os.getuid()}"
def agent_running(self):
return run_out(["launchctl", "print", f"{self.domain()}/{LABEL}"])[0] == 0
def agent_install(self):
text = self.agent_text()
os.makedirs(self.log_dir(), exist_ok=True)
os.makedirs(os.path.dirname(self.agent_path()), exist_ok=True)
with open(self.agent_path(), "w") as fh:
fh.write(text)
subprocess.run(["launchctl", "bootout", f"{self.domain()}/{LABEL}"], capture_output=True)
r = subprocess.run(["launchctl", "bootstrap", self.domain(), self.agent_path()], capture_output=True, text=True)
if r.returncode: # error 5 is the known transient: retry once
r = subprocess.run(["launchctl", "bootstrap", self.domain(), self.agent_path()], capture_output=True, text=True)
if r.returncode:
raise Err("launchctl bootstrap failed: " + r.stderr.strip())
return f"agent {LABEL} installed and loaded"
def agent_uninstall(self):
subprocess.run(["launchctl", "bootout", f"{self.domain()}/{LABEL}"], capture_output=True)
with contextlib.suppress(FileNotFoundError):
os.unlink(self.agent_path())
return f"agent {LABEL} unloaded and removed"
def agent_restart(self):
r = subprocess.run(["launchctl", "kickstart", "-k", f"{self.domain()}/{LABEL}"], capture_output=True, text=True)
if r.returncode:
raise Err("launchctl kickstart failed: " + r.stderr.strip())
return f"agent {LABEL} restarted"
def detect_platform(sysplat=None, os_release=None):
sysplat = sysplat or sys.platform
if sysplat == "darwin":
return MacPlatform()
return Platform(os_release if os_release is not None else read_os_release())
PLAT = detect_platform()
STATE = PLAT.state_dir()
CADDY = PLAT.find_tool("caddy")
MKCERT = PLAT.find_tool("mkcert")
def caddy_bin():
if not CADDY:
raise Err("caddy not found: " + PLAT.install_hint("caddy"))
return CADDY
def hostname(project, service=None, branch=None):
def first(name):
return name if not branch else f"{name}--{slug(branch, 20)}"
......@@ -545,7 +732,7 @@ def render(reg, reload=True):
return "written"
if not os.path.exists(ADMIN_SOCK):
return "written (agent not running: nothing reloaded)"
r = subprocess.run([CADDY, "reload", "--config", CADDYFILE, "--adapter", "caddyfile", "--address", f"unix/{ADMIN_SOCK}"],
r = subprocess.run([caddy_bin(), "reload", "--config", CADDYFILE, "--adapter", "caddyfile", "--address", f"unix/{ADMIN_SOCK}"],
capture_output=True, text=True, timeout=20)
if r.returncode:
raise Err("caddy refused the config (the old one stays live): " + r.stderr.strip()[-300:])
......@@ -996,13 +1183,14 @@ def start_index_server():
def cmd_serve(a):
caddy_bin() # fail before touching anything when caddy is absent
with locked():
render(load(), reload=False)
os.makedirs(STATE, exist_ok=True)
with contextlib.suppress(FileNotFoundError):
os.unlink(ADMIN_SOCK)
env = dict(os.environ, XDG_DATA_HOME=STATE, XDG_CONFIG_HOME=STATE, HOME=HOME)
caddy = subprocess.Popen([CADDY, "run", "--config", CADDYFILE, "--adapter", "caddyfile"], env=env)
caddy = subprocess.Popen([caddy_bin(), "run", "--config", CADDYFILE, "--adapter", "caddyfile"], env=env)
start_index_server()
start_status_poller()
start_lan_announcer()
......@@ -1010,10 +1198,6 @@ def cmd_serve(a):
return caddy.wait()
def launchd_loaded():
return subprocess.run(["launchctl", "print", f"gui/{os.getuid()}/{LABEL}"], capture_output=True).returncode == 0
def cmd_doctor(a):
ok = True
......@@ -1021,8 +1205,19 @@ def cmd_doctor(a):
nonlocal ok
ok = ok and good
print(("PASS " if good else "FAIL ") + text)
line(os.path.exists(CADDY), f"caddy at {CADDY}")
line(launchd_loaded(), f"launchd agent {LABEL} loaded")
def note(text):
print(" " + text)
note("platform: " + PLAT.describe())
line(bool(CADDY), f"caddy at {CADDY}" if CADDY else "caddy not found")
if not CADDY:
note("fix: " + PLAT.install_hint("caddy"))
running = PLAT.agent_running()
if running is None:
note("no supervisor integration here: run `devname serve` under your init")
else:
line(running, f"{PLAT.supervisor} agent {PLAT.running_words[0] if running else PLAT.running_words[1]}"
f" ({PLAT.agent_path()}; logs: {PLAT.log_hint()})")
line(os.path.exists(ADMIN_SOCK), "caddy admin socket present")
try:
urllib.request.urlopen(urllib.request.Request("http://127.0.0.1/", headers={"Host": "doctor.invalid"}), timeout=3)
......@@ -1057,31 +1252,30 @@ def cmd_doctor(a):
def cmd_agent(a):
"""One verb set on every platform; PLAT maps it to launchd, systemd --user, or a clear refusal."""
if a.print:
if a.action != "install":
raise Err("--print goes with `agent install`: it shows what install would write")
print(PLAT.agent_text(), end="")
print(f"devname: would write {PLAT.agent_path()} (nothing written, nothing started)", file=sys.stderr)
return 0
if a.action == "status":
print("loaded" if launchd_loaded() else "not loaded")
running = PLAT.agent_running()
if running is None:
PLAT.agent_text() # raises the platform's explanation
print(PLAT.running_words[0] if running else PLAT.running_words[1])
return 0
plist = f"""<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>{LABEL}</string>
<key>ProgramArguments</key><array><string>{os.path.abspath(__file__)}</string><string>serve</string></array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>{LOGDIR}/caddy.log</string>
<key>StandardErrorPath</key><string>{LOGDIR}/caddy.log</string>
</dict></plist>
"""
os.makedirs(LOGDIR, exist_ok=True)
with open(PLIST, "w") as fh:
fh.write(plist)
domain = f"gui/{os.getuid()}"
subprocess.run(["launchctl", "bootout", f"{domain}/{LABEL}"], capture_output=True)
r = subprocess.run(["launchctl", "bootstrap", domain, PLIST], capture_output=True, text=True)
if r.returncode: # error 5 is the known transient: retry once
r = subprocess.run(["launchctl", "bootstrap", domain, PLIST], capture_output=True, text=True)
if r.returncode:
raise Err("launchctl bootstrap failed: " + r.stderr.strip())
print(f"devname: agent {LABEL} installed and loaded", file=sys.stderr)
if a.action == "install":
problems = PLAT.agent_preflight()
if problems and not a.force:
raise Err("not installing an agent that would crash-loop; fix first (or --force):\n "
+ "\n ".join(problems))
msg = PLAT.agent_install()
elif a.action == "uninstall":
msg = PLAT.agent_uninstall()
else:
msg = PLAT.agent_restart()
print(f"devname: {msg}", file=sys.stderr)
return 0
......@@ -1111,7 +1305,11 @@ def main(argv=None):
sub.add_parser("render").set_defaults(fn=cmd_render)
sub.add_parser("serve").set_defaults(fn=cmd_serve)
sub.add_parser("doctor").set_defaults(fn=cmd_doctor)
s = sub.add_parser("agent"); s.add_argument("action", choices=["install", "status"]); s.set_defaults(fn=cmd_agent)
s = sub.add_parser("agent", help="the supervisor integration: launchd (macOS), systemd --user (Linux)")
s.add_argument("action", choices=["install", "uninstall", "status", "restart"])
s.add_argument("--print", action="store_true", help="with install: print the plist/unit, write and start nothing")
s.add_argument("--force", action="store_true", help="with install: skip the preflight checks")
s.set_defaults(fn=cmd_agent)
a = p.parse_args(argv)
try:
return a.fn(a)
......
......@@ -9,6 +9,7 @@ import tempfile
import time
import unittest
from contextlib import redirect_stderr, redirect_stdout
from unittest import mock
ROOT = pathlib.Path(__file__).resolve().parent.parent
......@@ -387,5 +388,125 @@ class DevnameTests(unittest.TestCase):
self.assertIn("http://mac.local/CA", lan)
class FakeRun:
"""Stands in for subprocess.run: records every argv, answers from a {argv-prefix tuple: (rc, stdout)} table."""
def __init__(self, table=None, default=(0, "")):
self.table, self.default, self.calls = table or {}, default, []
def __call__(self, cmd, *args, **kw):
self.calls.append(list(cmd))
rc, out = self.default
best = -1
for prefix, answer in self.table.items():
if tuple(cmd[:len(prefix)]) == prefix and len(prefix) > best:
(rc, out), best = answer, len(prefix)
return mock.Mock(returncode=rc, stdout=out + ("\n" if out else ""), stderr="")
class PlatformTests(unittest.TestCase):
"""Every platform branch, driven by mocks: runs on any OS, no sudo, no caddy, no network."""
def setUp(self):
self._tmp = tempfile.TemporaryDirectory()
self.addCleanup(self._tmp.cleanup)
self.dn = load_module(os.path.join(self._tmp.name, "conf"))
self.home = os.path.join(self._tmp.name, "home")
os.makedirs(self.home)
patcher = mock.patch.object(self.dn, "HOME", self.home) # agent files land in the temp home, never the real one
patcher.start()
self.addCleanup(patcher.stop)
def use(self, plat, run=None):
self.run = run or FakeRun()
for target, value in ((self.dn, {"PLAT": plat}), (self.dn.subprocess, {"run": self.run})):
p = mock.patch.multiple(target, **value)
p.start()
self.addCleanup(p.stop)
return plat
def 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(), err.getvalue()
# detection
def test_detect_platform_by_sys_platform(self):
self.assertIsInstance(self.dn.detect_platform("darwin"), self.dn.MacPlatform)
other = self.dn.detect_platform("freebsd13", os_release={})
self.assertEqual(type(other), self.dn.Platform)
self.assertIsNone(other.supervisor)
def test_os_release_parsing(self):
p = pathlib.Path(self._tmp.name) / "os-release"
p.write_text('NAME="Ubuntu"\nID=ubuntu\nID_LIKE=debian\n# comment\nVERSION_ID="24.04"\n')
rel = self.dn.read_os_release(str(p))
self.assertEqual((rel["ID"], rel["ID_LIKE"], rel["VERSION_ID"]), ("ubuntu", "debian", "24.04"))
self.assertEqual(self.dn.read_os_release(str(p) + ".absent"), {})
def test_find_tool_env_override_then_path_then_dirs(self):
plat = self.dn.Platform({})
with mock.patch.dict(os.environ, {"DEVNAME_CADDY": "/opt/x/caddy"}):
self.assertEqual(plat.find_tool("caddy"), "/opt/x/caddy")
tool_dir = pathlib.Path(self._tmp.name) / "bin"
tool_dir.mkdir()
exe = tool_dir / "caddy"
exe.write_text("#!/bin/sh\n")
exe.chmod(0o755)
plat.tool_dirs = (str(tool_dir),)
with mock.patch.dict(os.environ, {"DEVNAME_CADDY": ""}), mock.patch.object(self.dn.shutil, "which", return_value=None):
self.assertEqual(plat.find_tool("caddy"), str(exe))
self.assertIsNone(plat.find_tool("absent-tool"))
def test_missing_caddy_is_a_clear_error_not_a_crash(self):
self.use(self.dn.Platform({}))
with mock.patch.object(self.dn, "CADDY", None):
rc, _, err = self.cli("serve")
self.assertEqual(rc, 2)
self.assertIn("caddy not found", err)
# macOS: launchd (mocked: launchctl never runs here)
def test_mac_agent_print_writes_nothing(self):
plat = self.use(self.dn.MacPlatform())
rc, out, err = self.cli("agent", "install", "--print")
self.assertEqual(rc, 0)
self.assertIn("<key>Label</key><string>pl.nech.devname</string>", out)
self.assertIn("<string>serve</string>", out)
self.assertIn("Library/Logs/devname/caddy.log", out)
self.assertIn("would write", err)
self.assertFalse(os.path.exists(plat.agent_path()))
self.assertEqual(self.run.calls, [])
def test_mac_agent_install_status_restart_uninstall(self):
plat = self.use(self.dn.MacPlatform())
self.assertEqual(self.cli("agent", "install")[0], 0)
self.assertTrue(os.path.exists(plat.agent_path()))
verbs = [c[1] for c in self.run.calls]
self.assertEqual(verbs, ["bootout", "bootstrap"])
self.assertEqual(self.cli("agent", "status")[1].strip(), "loaded")
self.assertEqual(self.cli("agent", "restart")[0], 0)
self.assertEqual(self.run.calls[-1][:3], ["launchctl", "kickstart", "-k"])
self.assertEqual(self.cli("agent", "uninstall")[0], 0)
self.assertFalse(os.path.exists(plat.agent_path()))
def test_mac_bootstrap_failure_is_reported(self):
self.use(self.dn.MacPlatform(), FakeRun({("launchctl", "bootstrap"): (5, "")}))
rc, _, err = self.cli("agent", "install")
self.assertEqual(rc, 2)
self.assertIn("launchctl bootstrap failed", err)
self.assertEqual(sum(1 for c in self.run.calls if c[1] == "bootstrap"), 2) # the known transient: one retry
# any other Unix: no supervisor, a clear refusal
def test_other_platform_refuses_agent_and_points_at_serve(self):
self.use(self.dn.Platform({}))
for verb in ("install", "status", "restart", "uninstall"):
rc, _, err = self.cli("agent", verb)
self.assertEqual(rc, 2, verb)
self.assertIn("devname serve", err)
self.assertEqual(self.cli("agent", "install", "--print")[0], 2)
self.assertEqual(self.cli("agent", "status", "--print")[0], 2) # --print only goes with install
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