docs: add docstrings to all API endpoints and daemon handlers

Add comprehensive docstrings to firewall, DHCP, proxy, wireguard, certs,
and logs API endpoints. Document parameters, return values, and error cases
for the documentation system.

daemon/handlers/nginx.py

@@ -50,12 +50,18 @@ DEFAULT_CONFIG: dict[str, Any] = {
 
 
 def _get_state() -> dict[str, Any] | None:
+    """Retrieve cached nginx state from the state store."""
     from lib.state import state as state_store
 
     return state_store.get("nginx")
 
 
 def _get_config() -> dict[str, Any]:
+    """Load the nginx config JSON, applying defaults for missing fields.
+
+    Returns:
+        The parsed config dict with ssl defaults filled in.
+    """
     ensure_dirs(CONFIG_DIR, SITES_DIR)
     raw = load_json(CONFIG_FILE)
     if not raw:
@@ -66,10 +72,23 @@ def _get_config() -> dict[str, Any]:
 
 
 def _save_config(cfg: dict[str, Any]) -> None:
+    """Persist the nginx config dict to disk.
+
+    Args:
+        cfg: The config dictionary to save.
+    """
     save_json(CONFIG_FILE, cfg)
 
 
 def _generate_server_conf(domain_cfg: dict[str, Any]) -> str:
+    """Render an nginx server block config from a domain entry via Jinja.
+
+    Args:
+        domain_cfg: Domain config dict containing domain name, backend, headers, etc.
+
+    Returns:
+        Rendered server block as a string.
+    """
     tmpl = ENV.get_template("nginx/server_block.conf")
     return tmpl.render(
         domain=domain_cfg["domain"],
@@ -86,6 +105,12 @@ def _generate_server_conf(domain_cfg: dict[str, Any]) -> str:
 
 
 def _write_site(domain: str, conf_text: str) -> None:
+    """Atomically write a single site config file into sites-enabled.
+
+    Args:
+        domain: Site name used as the filename.
+        conf_text: Rendered nginx server block content.
+    """
     ensure_dirs(SITES_DIR)
     path = SITES_DIR / f"{domain}.conf"
     tmp = path.with_suffix(".tmp")
@@ -97,6 +122,7 @@ def _write_site(domain: str, conf_text: str) -> None:
 
 
 def _write_include_file() -> None:
+    """Write the system include file that references all per-site configs."""
     tmpl = ENV.get_template("nginx/include.conf")
     content = tmpl.render(sites_glob=str(SITES_DIR / "*.conf"))
     tmp = INCLUDE_FILE.with_suffix(".tmp")
@@ -109,6 +135,7 @@ def _write_include_file() -> None:
 
 
 def _write_ssl_snippet() -> None:
+    """Render and install the shared SSL snippet to /etc/nginx/snippets/."""
     cfg = _get_config()
     ssl_cfg = cfg.get("ssl", {})
     ssl_cfg.setdefault("prefer_server_ciphers", DEFAULT_SSL["prefer_server_ciphers"])
@@ -126,6 +153,11 @@ def _write_ssl_snippet() -> None:
 
 
 def _test_config() -> tuple[bool, str]:
+    """Run `nginx -t` to validate the current config.
+
+    Returns:
+        Tuple of (passed, message).
+    """
     result = run_proc(["nginx", "-t"], sudo=True, check=False)
     ok = result.returncode == 0
     output = (result.stderr or result.stdout or "").strip()
@@ -135,6 +167,10 @@ def _test_config() -> tuple[bool, str]:
 
 
 def _reload_nginx() -> None:
+    """Send SIGHUP to nginx to reload its configuration.
+
+    Logs an error if the reload fails.
+    """
     result = run_proc(["nginx", "-s", "reload"], sudo=True, check=False)
     if result.returncode != 0:
         logger.error("nginx reload failed: %s", result.stderr.strip())
@@ -143,6 +179,10 @@ def _reload_nginx() -> None:
 
 
 def _write_all_sites() -> None:
+    """Regenerate all site configs, management proxy, and ACME challenge site.
+
+    Removes stale .conf files that are no longer in config.
+    """
     ensure_dirs(SITES_DIR)
     cfg = _get_config()
     existing = set(SITES_DIR.iterdir()) if SITES_DIR.exists() else set()
@@ -186,6 +226,12 @@ def _write_all_sites() -> None:
 
 
 def _write_htpasswd(user: str, password: str) -> None:
+    """Add or update a user entry in the .htpasswd file using SHA-256 hashing.
+
+    Args:
+        user: The username to add or update.
+        password: Plain-text password to hash.
+    """
     ensure_dirs(DATA_DIR)
     import crypt
 
@@ -211,6 +257,7 @@ def _write_htpasswd(user: str, password: str) -> None:
 
 
 def _get_nginx_state() -> dict[str, Any]:
+    """Return a shallow copy of the cached nginx state, or empty dict if unset."""
     ng = _get_state()
     if ng is None:
         return {}
@@ -223,6 +270,11 @@ def _get_nginx_state() -> dict[str, Any]:
 
 @registry.register("GET", "/nginx/config")
 def get_config(_request: Any, _body: Any) -> dict[str, Any]:
+    """GET /nginx/config — return current nginx config.
+
+    Returns:
+        Full config dict from state cache, or fallback to file.
+    """
     ng = _get_nginx_state()
     if ng:
         return ng.get("config", {})
@@ -231,6 +283,11 @@ def get_config(_request: Any, _body: Any) -> dict[str, Any]:
 
 @registry.register("POST", "/nginx/config")
 def save_config_handler(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
+    """POST /nginx/config — replace the entire nginx config and refresh state.
+
+    Raises:
+        ValueError: When request body is missing.
+    """
     if not body:
         raise ValueError("Request body required")
     _save_config(body)
@@ -240,6 +297,11 @@ def save_config_handler(_request: Any, body: dict[str, Any] | None) -> dict[str,
 
 @registry.register("PATCH", "/nginx/config")
 def patch_config(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
+    """PATCH /nginx/config — deep-merge partial updates into current config.
+
+    Raises:
+        ValueError: When request body is missing.
+    """
     if not body:
         raise ValueError("Request body required")
     from lib.common import deep_merge
@@ -253,6 +315,11 @@ def patch_config(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
 
 @registry.register("GET", "/nginx/domains")
 def get_domains(_request: Any, _body: Any) -> list[dict[str, Any]]:
+    """GET /nginx/domains — return the list of configured proxy domains.
+
+    Returns:
+        Domains list from state cache, or empty list.
+    """
     ng = _get_nginx_state()
     if ng:
         return ng.get("domains", [])
@@ -261,6 +328,12 @@ def get_domains(_request: Any, _body: Any) -> list[dict[str, Any]]:
 
 @registry.register("POST", "/nginx/domains/add")
 def add_domain(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
+    """POST /nginx/domains/add — add a new reverse-proxy domain entry.
+
+    Raises:
+        ValueError: When required fields (domain, backend_host, backend_port) are missing.
+        ValueError: When the domain already exists.
+    """
     if not body:
         raise ValueError("Request body required")
     domain = body.get("domain", "").strip()
@@ -298,6 +371,12 @@ def add_domain(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
 
 @registry.register("DELETE", "/nginx/domains/remove")
 def remove_domain(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
+    """DELETE /nginx/domains/remove — remove a domain from the proxy config.
+
+    Raises:
+        ValueError: When request body or domain field is missing.
+        NotFoundError: When the domain is not configured.
+    """
     if not body:
         raise ValueError("Request body required")
     domain = body.get("domain", "").strip()
@@ -317,6 +396,12 @@ def remove_domain(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
 
 @registry.register("POST", "/nginx/domains/update")
 def update_domain(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
+    """POST /nginx/domains/update — patch fields of an existing domain entry.
+
+    Raises:
+        ValueError: When request body or domain field is missing.
+        NotFoundError: When the domain is not configured.
+    """
     if not body:
         raise ValueError("Request body required")
     domain = body.get("domain", "").strip()
@@ -339,6 +424,11 @@ def update_domain(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
 
 @registry.register("POST", "/nginx/apply")
 def apply(_request: Any, _body: Any) -> dict[str, Any]:
+    """POST /nginx/apply — render all configs, test, and reload nginx.
+
+    Raises:
+        RuntimeError: When the nginx config test fails.
+    """
     _write_ssl_snippet()
     _write_all_sites()
     _write_include_file()
@@ -352,12 +442,18 @@ def apply(_request: Any, _body: Any) -> dict[str, Any]:
 
 @registry.register("POST", "/nginx/test")
 def test(_request: Any, _body: Any) -> dict[str, Any]:
+    """POST /nginx/test — dry-run validate the live nginx config without applying.
+
+    Returns:
+        Dict with valid (bool) and output (str) from `nginx -t`.
+    """
     valid, output = _test_config()
     return {"valid": valid, "output": output}
 
 
 @registry.register("POST", "/nginx/ssl-apply")
 def ssl_apply(_request: Any, _body: Any) -> dict[str, Any]:
+    """POST /nginx/ssl-apply — re-render and install only the SSL snippet."""
     _write_ssl_snippet()
     refresh_state(["nginx"])
     return {"applied": True}
@@ -365,6 +461,11 @@ def ssl_apply(_request: Any, _body: Any) -> dict[str, Any]:
 
 @registry.register("POST", "/nginx/management")
 def set_management_proxy(_request: Any, body: dict[str, Any] | None) -> dict[str, Any]:
+    """POST /nginx/management — configure the management UI reverse proxy.
+
+    Raises:
+        ValueError: When request body or domain field is missing.
+    """
     if not body:
         raise ValueError("Request body required")
     domain = body.get("domain", "").strip()
@@ -391,5 +492,6 @@ def set_management_proxy(_request: Any, body: dict[str, Any] | None) -> dict[str
 
 @registry.register("POST", "/nginx/reload")
 def reload_nginx(_request: Any, _body: Any) -> dict[str, Any]:
+    """POST /nginx/reload — trigger an nginx reload (SIGHUP)."""
     _reload_nginx()
     return {"reloaded": True}