Add hooks

Author: andre487

.gitignore

@@ -156,6 +156,7 @@ activemq-data/
 /inventory-path
 /.secrets/
 /.generated/
+/.hooks/
 env/
 venv/
 ENV/

README.md

@@ -79,6 +79,12 @@ authorized-key files from every SSH-enabled host.
 Use `--limit HOST` and `--tags common,admin,firewall,ssh,https` with plan, apply, or verify. Always run
 `plan` before applying to an existing server and keep the current administrative SSH session open.
 
+After a successful `apply`, executable `.hooks/post-config-change` and files in
+`.hooks/post-config-change.d/` are run in name order. The ignored `.hooks` directory is intended for
+machine-local integrations and secrets. Hooks receive `MEGAPROXY_INVENTORY`,
+`MEGAPROXY_ANSIBLE_INVENTORY`, `MEGAPROXY_ROOT`, and `MEGAPROXY_EVENT`. Use `--no-hooks` before or
+after the command to skip them, for example `./mega-proxy apply --no-hooks`.
+
 ## HTTPS
 
 HTTPS uses a pinned GOST v3 container, TLS 1.2/1.3, Basic authentication and HTTP/2 CONNECT. Invalid

src/megaproxy_server/cli.py

@@ -11,6 +11,7 @@
 
 from .export import export_profiles, jump_candidates
 from .generate import generate
+from .hooks import run_hooks
 from .inventory import DEFAULT_INVENTORY, ROOT, discover, load, save, write_ansible_inventory
 from .summary import render_summary
 from .users import active_users, remove_users
@@ -20,24 +21,32 @@
 def parser() -> argparse.ArgumentParser:
     result = argparse.ArgumentParser(description="Configure MegaProxy HTTPS and SSH servers")
     result.add_argument("--inventory", "-i", help="Inventory configuration path")
+    result.add_argument("--no-hooks", action="store_true", help="Do not run local hooks")
     sub = result.add_subparsers(dest="command")
-    sub.add_parser("inventory", help="Create a new inventory")
-    sub.add_parser("validate", help="Validate inventory and Ansible syntax")
-    sub.add_parser("check", help="Run the complete local/CI test suite")
+    commands = []
+    commands.append(sub.add_parser("inventory", help="Create a new inventory"))
+    commands.append(sub.add_parser("validate", help="Validate inventory and Ansible syntax"))
+    commands.append(sub.add_parser("check", help="Run the complete local/CI test suite"))
     for name in ("plan", "apply", "verify"):
         command = sub.add_parser(name)
+        commands.append(command)
         command.add_argument("--limit")
         command.add_argument("--tags")
     export = sub.add_parser("export")
+    commands.append(export)
     export.add_argument("--output", default=".generated/megaproxy-profiles.json")
     export.add_argument("--all-jumps", action="store_true")
     configs = sub.add_parser("configs", help="Generate all supported client configuration formats")
+    commands.append(configs)
     configs.add_argument("--output-dir", default=".generated/configs")
     summary = sub.add_parser("summary", help="Print credentials for a password manager")
+    commands.append(summary)
     summary.add_argument("login", nargs="?", help="Show only this login")
-    sub.add_parser("remove-users", help="Remove one or more proxy user accounts")
-    sub.add_parser("vault-secrets", help="Encrypt only secret inventory fields with Ansible Vault")
-    sub.add_parser("jumps", help="List all possible SSH jump chains")
+    commands.append(sub.add_parser("remove-users", help="Remove one or more proxy user accounts"))
+    commands.append(sub.add_parser("vault-secrets", help="Encrypt only secret inventory fields with Ansible Vault"))
+    commands.append(sub.add_parser("jumps", help="List all possible SSH jump chains"))
+    for command in commands:
+        command.add_argument("--no-hooks", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
     return result
 
 
@@ -196,6 +205,10 @@ def main() -> None:
         applied_admin = tags is None or "admin" in {tag.strip() for tag in tags.split(",")}
         if code == 0 and command == "apply" and applied_admin:
             finish_bootstrap(path, inventory, limit)
+        if code == 0 and command == "apply" and not args.no_hooks:
+            inventory = load(path)
+            generated = write_ansible_inventory(path, inventory)
+            code = run_hooks(ROOT, "post-config-change", path, generated)
         raise SystemExit(code)
     except (ValidationError, FileNotFoundError, ValueError) as error:
         print(f"Configuration error: {error}", file=sys.stderr)

src/megaproxy_server/hooks.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+
+def run_hooks(root: Path, event: str, inventory: Path, ansible_inventory: Path) -> int:
+    hooks_dir = root / ".hooks"
+    candidates = [hooks_dir / event]
+    event_dir = hooks_dir / f"{event}.d"
+    if event_dir.is_dir():
+        candidates.extend(sorted(path for path in event_dir.iterdir() if path.is_file()))
+
+    environment = os.environ.copy()
+    environment.update(
+        {
+            "MEGAPROXY_EVENT": event,
+            "MEGAPROXY_INVENTORY": str(inventory.resolve()),
+            "MEGAPROXY_ANSIBLE_INVENTORY": str(ansible_inventory.resolve()),
+            "MEGAPROXY_ROOT": str(root.resolve()),
+        }
+    )
+    for hook in candidates:
+        if not hook.is_file() or not os.access(hook, os.X_OK):
+            continue
+        print(f"Running hook: {hook}", flush=True)
+        result = subprocess.run([str(hook)], cwd=root, env=environment)
+        if result.returncode:
+            return result.returncode
+    return 0

src/megaproxy_server/inventory.py

@@ -161,8 +161,16 @@ def _dns_label(value: str) -> str:
     return re.sub(r"[^a-z0-9-]+", "-", value.lower()).strip("-")
 
 
+def _host_title(name: str) -> str:
+    parts = name.split("_")
+    if parts[-1:] == ["proxy"]:
+        parts.pop()
+    return " ".join([parts[0].upper(), *(part.title() for part in parts[1:])])
+
+
 def ansible_inventory(inventory: Inventory) -> dict[str, Any]:
     hosts: dict[str, Any] = {}
+    public_https_hosts: list[dict[str, Any]] = []
     for name, host in inventory.hosts.items():
         services = host.services.model_dump(mode="json", exclude_none=True)
         routes: list[dict[str, Any]] = []
@@ -178,6 +186,16 @@ def ansible_inventory(inventory: Inventory) -> dict[str, Any]:
                 {"username": https.chain_username, "password": https.chain_password}
                 if inventory.settings.https_chains_enabled and https.chain_exit else None
             )
+            for route in routes:
+                public_https_hosts.append(
+                    {
+                        "name": name if route["name"] == "direct" else f"{name}_{route['name']}",
+                        "host": route["hostname"],
+                        "port": https.port,
+                        "code": name.split("_", 1)[0].upper(),
+                        "title": _host_title(name),
+                    }
+                )
         variables: dict[str, Any] = {
             "ansible_host": host.address,
             "ansible_user": host.admin.bootstrap_user or host.admin.user,
@@ -196,7 +214,15 @@ def ansible_inventory(inventory: Inventory) -> dict[str, Any]:
             except ValueError:
                 variables["megaproxy_https_san_type"] = "DNS"
         hosts[name] = variables
-    return {"all": {"hosts": hosts}}
+    return {
+        "all": {
+            "vars": {
+                "megaproxy_users": inventory.users.model_dump(mode="json"),
+                "megaproxy_public_https_hosts": public_https_hosts,
+            },
+            "hosts": hosts,
+        }
+    }
 
 
 def write_ansible_inventory(source: Path, inventory: Inventory) -> Path:

tests/test_hooks.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from megaproxy_server.hooks import run_hooks
+
+
+def test_runs_executable_hook_with_inventory_environment(tmp_path: Path) -> None:
+    hooks = tmp_path / ".hooks"
+    hooks.mkdir()
+    output = tmp_path / "hook-output"
+    hook = hooks / "post-config-change"
+    hook.write_text(f"#!/bin/sh\nprintf '%s' \"$MEGAPROXY_INVENTORY\" > {output}\n")
+    hook.chmod(0o700)
+    inventory = tmp_path / "inventory.yml"
+    generated = tmp_path / "inventory.ansible.yml"
+
+    assert run_hooks(tmp_path, "post-config-change", inventory, generated) == 0
+    assert output.read_text() == str(inventory.resolve())
+
+
+def test_skips_non_executable_hook(tmp_path: Path) -> None:
+    hooks = tmp_path / ".hooks"
+    hooks.mkdir()
+    hook = hooks / "post-config-change"
+    hook.write_text("#!/bin/sh\nexit 42\n")
+    hook.chmod(0o600)
+
+    assert not os.access(hook, os.X_OK)
+    assert run_hooks(tmp_path, "post-config-change", tmp_path / "one", tmp_path / "two") == 0

tests/test_inventory.py

@@ -95,3 +95,16 @@ def test_https_sni_routes_are_generated_for_every_exit() -> None:
     assert [route["hostname"] for route in routes] == ["ru.example", "proxy-ru-via-proxy-nl.chains.example"]
     projected = ansible_inventory(inventory)["all"]["hosts"]["proxy_ru"]["megaproxy_services"]["https"]
     assert projected["routes"][1]["chain"]["host"] == "nl.example"
+    public_hosts = ansible_inventory(inventory)["all"]["vars"]["megaproxy_public_https_hosts"]
+    assert public_hosts == [
+        {"name": "proxy_ru", "host": "ru.example", "port": 443, "code": "PROXY", "title": "PROXY Ru"},
+        {
+            "name": "proxy_ru_via-proxy_nl",
+            "host": "proxy-ru-via-proxy-nl.chains.example",
+            "port": 443,
+            "code": "PROXY",
+            "title": "PROXY Ru",
+        },
+        {"name": "proxy_nl", "host": "nl.example", "port": 443, "code": "PROXY", "title": "PROXY Nl"},
+    ]
+    assert ansible_inventory(inventory)["all"]["vars"]["megaproxy_users"]["https"][0]["name"] == "alice"