fadenstack 0.4.2__py3-none-any.whl

faden_cli/core/dev_modules.py

@@ -0,0 +1,149 @@
+"""The optional modules -- PII, MCP, skills -- in the dev environment.
+
+``faden dev up`` runs the backend and gateway on the host. The modules were
+only ever wired for the container stack: each was addressed by its Docker
+name (``http://faden-pii:8000``) and published no port, so a gateway on
+the host could not reach one even when it was started by hand, and
+``dev up`` had no way to start one at all. The backend's own defaults already
+expected them on the host (``http://127.0.0.1:8003/api`` for PII), on the
+ports the CLI reserves for them.
+
+So they run the way the backend does: from their service directory, bound to
+127.0.0.1 (only the gateway and backend call them), each on its reserved
+port. This module works out what that takes -- which modules, their own
+settings, and what the gateway and backend need to reach them -- as plain
+dicts, so it can be tested without starting anything.
+"""
+
+from __future__ import annotations
+
+from faden_cli.core.registry import MODULES, ModuleInfo
+
+#: Where the host-run modules listen and where the shared infra is reached.
+#: Never "localhost": see ``registry.INFRA_LOOPBACK``.
+_HOST = "127.0.0.1"
+
+
+class UnknownModuleError(ValueError):
+    """A module name ``dev up`` does not know how to run."""
+
+
+def dev_modules() -> list[ModuleInfo]:
+    """Every module dev mode can run, in registry order."""
+    return [m for m in MODULES.values() if m.dev_dir]
+
+
+def select_modules(requested: str | None, profiles: list[str] | None) -> list[ModuleInfo]:
+    """The modules to run.
+
+    *requested* is ``--modules``: a comma-separated list, or ``none``. Without
+    it, the modules switched on with ``faden module enable`` (the config's
+    profiles) are the ones that run.
+    """
+    runnable = {m.name: m for m in dev_modules()}
+    if requested is None:
+        wanted = [m.name for m in runnable.values() if m.profile in set(profiles or [])]
+    else:
+        names = [n.strip().lower() for n in requested.split(",") if n.strip()]
+        if names in ([], ["none"]):
+            return []
+        unknown = [n for n in names if n not in runnable]
+        if unknown:
+            raise UnknownModuleError(
+                f"Unknown module(s): {', '.join(unknown)}. "
+                f"Available: {', '.join(runnable)}.",
+            )
+        wanted = names
+    return [m for m in runnable.values() if m.name in wanted]
+
+
+def dev_url(module: ModuleInfo) -> str:
+    """The root URL a host-run module answers on."""
+    return f"http://{_HOST}:{module.port}"
+
+
+def service_token(module: ModuleInfo, shared: dict[str, str]) -> str:
+    """The token the gateway and backend present to *module*.
+
+    One value for all three sides, or the calls are refused. The shared
+    ``.env`` wins, so a workspace that set its own keeps it.
+    """
+    return shared.get(f"FADEN_{module.name.upper()}_SERVICE_TOKEN") or module.dev_service_token
+
+
+def module_env(
+    module: ModuleInfo,
+    *,
+    shared: dict[str, str],
+    running: list[ModuleInfo],
+) -> dict[str, str]:
+    """The settings *module* runs with, for its own ``.env``."""
+    p = f"FADEN_{module.name.upper()}_"
+    env = {
+        p + "HOST": _HOST,
+        p + "PORT": str(module.port),
+        p + "ENVIRONMENT": "dev",
+        # One worker: PII loads its spaCy model per worker (~1 GB each), and
+        # MCP keeps its stdio connections per worker.
+        p + "WORKERS_COUNT": "1",
+        # Not reloaded: in this environment they are what the backend and
+        # gateway call, not the code being edited, and a reload of PII reloads
+        # its model.
+        p + "RELOAD": "false",
+    }
+    if module.database:
+        env.update({
+            p + "DB_HOST": _HOST,
+            p + "DB_PORT": "5432",
+            p + "DB_USER": shared.get("POSTGRES_USER", "postgres"),
+            p + "DB_PASS": shared.get("POSTGRES_PASSWORD", "postgres"),
+            p + "DB_BASE": module.database,
+        })
+    if module.redis_base is not None:
+        env.update({
+            p + "REDIS_HOST": _HOST,
+            p + "REDIS_PORT": "6379",
+            p + "REDIS_BASE": str(module.redis_base),
+        })
+        redis_pass = shared.get("REDIS_AUTH") or shared.get("REDIS_PASSWORD")
+        if redis_pass:
+            env[p + "REDIS_PASS"] = redis_pass
+    if module.dev_service_token:
+        env[p + "SERVICE_TOKEN"] = service_token(module, shared)
+    for key, value in module.dev_settings:
+        env[p + key] = shared.get(p + key) or value
+    by_name = {m.name: m for m in running}
+    for key, other in module.dev_links:
+        # Empty when the other one is not running: a URL to nothing would
+        # make every call wait out a connect timeout instead of skipping.
+        env[p + key] = dev_url(by_name[other]) if other in by_name else ""
+    return env
+
+
+def caller_env(
+    service: str,
+    *,
+    shared: dict[str, str],
+    running: list[ModuleInfo],
+) -> dict[str, str]:
+    """What the gateway (``GATEWAY``) or backend (``BACKEND``) needs to reach them.
+
+    Every module dev mode knows about gets its switch: on with its URL (and
+    token) when it runs, off when it does not. Left on while nothing listens,
+    the gateway sends each request to it anyway -- and under a PII policy
+    that blocks when the service is down, every chat then fails with 502.
+    """
+    on = {m.name for m in running}
+    env: dict[str, str] = {}
+    for module in dev_modules():
+        p = f"FADEN_{service}_{module.name.upper()}_"
+        env[p + "ENABLED"] = "true" if module.name in on else "false"
+        if module.name not in on:
+            continue
+        url = dev_url(module)
+        if service == "BACKEND":
+            url += module.backend_url_suffix
+        env[p + "SERVICE_URL"] = url
+        if module.dev_service_token:
+            env[p + "SERVICE_TOKEN"] = service_token(module, shared)
+    return env

faden_cli/core/docker_env.py

@@ -0,0 +1,147 @@
+"""Docker endpoint selection — Docker Desktop / Rancher Desktop fallback.
+
+On Windows the docker CLI talks to a container runtime over a named pipe.
+Docker Desktop and Rancher Desktop install their own endpoints and often
+point the default docker context (or ``DOCKER_HOST``) at the *other*
+runtime's pipe.  When that pipe is down — e.g. Docker Desktop is not
+running but Rancher Desktop is — every docker call fails with::
+
+    failed to connect to the docker API at
+    npipe:////./pipe/dockerDesktopLinuxEngine: The system cannot find
+    the file specified.
+
+This module centralises the resolution logic:
+
+* :func:`rancher_endpoints` — known Rancher Desktop daemon endpoints per
+  platform.  On Windows Rancher Desktop's ``wsl-helper`` proxy listens
+  on the classic ``//./pipe/docker_engine`` pipe (see
+  ``serve_windows.go`` in the rancher-desktop source:
+  ``DefaultEndpoint = "npipe:////./pipe/docker_engine"``).
+* :func:`resolve_docker_host` — probe the current endpoint first, then
+  each Rancher Desktop fallback; return the first ``docker info`` that
+  answers, or ``None``.
+* :func:`ensure_docker_host` — one-shot guard: if the current endpoint
+  is dead and a Rancher Desktop endpoint answers, export
+  ``DOCKER_HOST`` (cached in a module global) so *every* docker
+  subprocess the CLI spawns (detect, compose, logs, …) reaches the live
+  daemon.  No side effects when the active endpoint already works.
+
+Only ``os`` and ``subprocess`` are used — no Docker SDK, consistent with
+the rest of the CLI.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def is_windows() -> bool:
+    """True when the daemon endpoints are Windows named pipes."""
+    return platform.system() == "Windows"
+
+
+def rancher_endpoints() -> list[str]:
+    """Known rancher-desktop daemon endpoints for this platform.
+
+    * Windows — the WSL2/Hyper-V backend's host-side proxy pipe
+      (``rancher-desktop/run/docker.sock`` inside the VM).
+    * macOS / Linux — the socket the app publishes on the host,
+      optionally forwarded to the conventional ``/var/run/docker.sock``
+      location when ``application.adminAccess`` is enabled.
+    """
+    if is_windows():
+        return ["npipe:////./pipe/docker_engine"]
+    app_dir = Path.home() / "Library" / "Application Support" / "rancher-desktop"
+    return [
+        f"unix://{app_dir / 'docker.sock'}",
+        "unix:///var/run/docker.sock",
+    ]
+
+
+def _probe(endpoint: str, timeout: int = 10) -> bool:
+    """Return True if ``docker info`` answers at *endpoint*.
+
+    ``endpoint`` may be the docker CLI's special value ``"default"``
+    (leave the configuration untouched and let the CLI use its current
+    docker context).
+    """
+    docker_bin = shutil.which("docker")
+    if not docker_bin:
+        return False
+    env = dict(os.environ)
+    if endpoint == "default":
+        env.pop("DOCKER_HOST", None)
+    else:
+        env["DOCKER_HOST"] = endpoint
+    try:
+        return (
+            subprocess.run(  # noqa: S603
+                [docker_bin, "info"],
+                env=env,
+                capture_output=True,
+                check=False,
+                timeout=timeout,
+            ).returncode
+            == 0
+        )
+    except Exception:  # a probe must never raise
+        return False
+
+
+def resolve_docker_host() -> str | None:
+    """Return the first reachable docker endpoint, or ``None``.
+
+    Order: the endpoint the docker CLI is currently configured for
+    (``"default"`` when ``DOCKER_HOST`` is unset, i.e. its active
+    docker context, or the ``DOCKER_HOST`` value itself), then the
+    Rancher Desktop fallback endpoints.
+    """
+    current = os.environ.get("DOCKER_HOST") or "default"
+    if _probe(current):
+        return current
+    for candidate in rancher_endpoints():
+        if candidate != current and _probe(candidate):
+            return candidate
+    return None
+
+
+def ensure_docker_host(verbose: bool = False, quiet: bool = False) -> str | None:
+    """Make every docker subprocess talk to a *running* daemon.
+
+    Called once from the CLI root callback, before any command runs:
+
+    * current endpoint already works  → no-op;
+    * current endpoint dead but a Rancher Desktop endpoint answers →
+      export ``DOCKER_HOST`` and print a short notice, so detect /
+      compose / logs all hit the live daemon;
+    * nothing answers → no change (the usual "Docker daemon is not
+      running" errors from ``detect_docker`` stay in effect).
+
+    Safe on every platform: on a Linux host without any container
+    daemon the probes simply fail fast.  Returns the selected endpoint
+    or ``None``.
+    """
+    if shutil.which("docker") is None:
+        return None
+
+    current = os.environ.get("DOCKER_HOST") or "default"
+    host = resolve_docker_host()
+    if host is None:
+        if verbose:
+            from faden_cli.core.console import warning  # noqa: PLC0415 — late import avoids cycle
+            warning("No reachable Docker endpoint (Docker Desktop or Rancher Desktop).")
+        return None
+
+    if host != current:
+        os.environ["DOCKER_HOST"] = host
+        if not quiet:
+            from faden_cli.core.console import info  # noqa: PLC0415 — late import avoids cycle
+            if is_windows() and host == "npipe:////./pipe/docker_engine":
+                info("Docker Desktop endpoint not found — using Rancher Desktop.")
+            else:
+                info(f"Docker endpoint → {host}")
+    return host

faden_cli/core/edge.py

@@ -0,0 +1,94 @@
+"""The install's front door: its ports, and whether it answers over HTTPS.
+
+nginx serves HTTPS whenever ``<install>/tls`` holds ``edge.crt`` and
+``edge.key``, and sends plain HTTP there (shared/nginx/select-config.sh).
+Everything the CLI does against the console after ``docker compose up`` --
+the health gate, the first-admin bootstrap, a login for an enrollment token
+-- has to follow, or it talks to a redirect.
+
+The two host ports nginx is published on are ``FADEN_HTTP_PORT`` and
+``FADEN_HTTPS_PORT`` in the install's ``.env``; docker-compose.yaml
+publishes both, the HTTPS one even while nothing listens on it.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from collections.abc import Mapping
+from pathlib import Path
+from urllib.parse import urlsplit
+
+HTTP_PORT_KEY = "FADEN_HTTP_PORT"
+HTTPS_PORT_KEY = "FADEN_HTTPS_PORT"
+DEFAULT_HTTP_PORT = 80
+DEFAULT_HTTPS_PORT = 443
+
+
+def edge_material_present(install_dir: Path) -> bool:
+    """Whether the install holds the certificate and key nginx serves HTTPS with."""
+    tls = Path(install_dir) / "tls"
+    return (tls / "edge.crt").is_file() and (tls / "edge.key").is_file()
+
+
+def _port(env: Mapping[str, str], key: str, default: int) -> int:
+    raw = (env.get(key) or "").strip().strip('"').strip("'")
+    try:
+        return int(raw) if raw else default
+    except ValueError:
+        return default
+
+
+def ports(env: Mapping[str, str]) -> tuple[int, int]:
+    """``(http, https)``: the host ports nginx is published on, from the install's ``.env``."""
+    return _port(env, HTTP_PORT_KEY, DEFAULT_HTTP_PORT), _port(env, HTTPS_PORT_KEY, DEFAULT_HTTPS_PORT)
+
+
+def check_ports(http: int, https: int) -> str | None:
+    """Why this pair of ports cannot be used, or ``None`` when it can."""
+    for label, value in (("HTTP", http), ("HTTPS", https)):
+        if not 1 <= value <= 65535:  # noqa: PLR2004
+            return f"The {label} port must be between 1 and 65535, not {value}."
+    if http == https:
+        return f"HTTP and HTTPS cannot share port {http}."
+    return None
+
+
+def url_for(host: str, *, https: bool, env: Mapping[str, str]) -> str:
+    """``http[s]://host[:port]`` for *host*, leaving out the scheme's default port."""
+    http_port, https_port = ports(env)
+    scheme, port, default = ("https", https_port, 443) if https else ("http", http_port, 80)
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"  # an IPv6 address
+    return f"{scheme}://{host}" if port == default else f"{scheme}://{host}:{port}"
+
+
+def console_url(install_dir: Path, env: Mapping[str, str]) -> str:
+    """``https://localhost[:port]`` with edge material in place, else ``http://localhost[:port]``.
+
+    *env* is the install's ``.env``; the ports follow ``FADEN_HTTPS_PORT``
+    and ``FADEN_HTTP_PORT`` the way docker-compose.yaml publishes them.
+    """
+    return url_for("localhost", https=edge_material_present(install_dir), env=env)
+
+
+def _is_this_machine(host: str) -> bool:
+    if host.lower() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def verify_for(url: str) -> bool:
+    """TLS verification for a console URL: off only when it is HTTPS to this machine.
+
+    That certificate is usually made here, or issued for a name this machine
+    does not call itself by; what the CLI needs to know is whether the
+    services came up, and the box it runs on answers that. Any other host
+    is verified: a password may be about to go to it.
+    """
+    parts = urlsplit(url)
+    if parts.scheme != "https":
+        return True
+    return not _is_this_machine(parts.hostname or "")