dataface 0.1.2__py3-none-any.whl

dataface/core/serve/bootstrap.py

@@ -0,0 +1,39 @@
+"""Serve startup hooks — run once before the server begins handling requests.
+
+Stage: SERVE
+Purpose: Apply environment-driven config overrides at process startup.
+
+Call apply_default_theme_from_env() immediately before create_server() in
+serve.py. Any invalid configuration fails fast with a clear error so the
+process exits before binding the port.
+"""
+
+import os
+
+DFT_DEFAULT_THEME_ENV = "DFT_DEFAULT_THEME"
+
+
+def apply_default_theme_from_env() -> None:
+    """Read DFT_DEFAULT_THEME and patch the in-process default theme.
+
+    When the env var is set:
+      - Empty string → ValueError (explicit misconfiguration)
+      - Unknown theme name → ValueError with list of valid names
+      - Known theme name → get_default_theme_name() returns it for this process
+
+    When the env var is unset → no-op; existing default is unchanged.
+
+    Raises:
+        ValueError: If the env var is set to an empty string or unknown theme.
+    """
+    from dataface.core.compile.config import set_default_theme_name
+
+    raw = os.environ.get(DFT_DEFAULT_THEME_ENV)
+    if raw is None:
+        return
+    if not raw:
+        raise ValueError(
+            f"{DFT_DEFAULT_THEME_ENV} is set to an empty string. "
+            "Provide a valid theme name (e.g. 'carbong100', 'light') or unset the variable."
+        )
+    set_default_theme_name(raw)

dataface/core/serve/embedded.py

@@ -0,0 +1,57 @@
+"""Shared lifecycle for the embedded preview HTTP server.
+
+Both `dft mcp serve` and `dft chat` start a uvicorn-served FastAPI app
+alongside their primary transport so render_dashboard URLs are
+clickable. They differ in how they run the asyncio loop:
+mcp/server.py uses `asyncio.create_task` on the calling loop; the chat
+CLI uses a dedicated background thread + loop because the chat loop
+itself is sync.
+
+This module extracts the parts they share — port resolution, uvicorn
+availability probe, `uvicorn.Config` + `uvicorn.Server` construction —
+so a fix to either side lands once.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataface._install_hint import install_hint
+from dataface.core.serve.port import find_available_port
+from dataface.core.serve.server import create_server
+
+
+def build_embedded_server(
+    port_hint: int = 8765,
+    *,
+    host: str = "localhost",
+    log_level: str = "warning",
+    max_attempts: int = 10,
+) -> tuple[Any, int]:
+    """Resolve a free port and build a configured `uvicorn.Server`.
+
+    Returns ``(server, resolved_port)``. Raises ``ImportError`` (with an
+    install hint) when uvicorn isn't installed, or ``RuntimeError`` from
+    ``find_available_port`` when no free port is available — callers
+    surface those errors with their own context. Callers run the server
+    on whatever asyncio loop fits their lifecycle (one-shot async task,
+    background thread, etc.).
+    """
+    try:
+        import uvicorn  # noqa: PLC0415
+    except ImportError as e:
+        raise ImportError(
+            "Embedded preview server requires uvicorn. "
+            f"Install with: {install_hint('mcp')}"
+        ) from e
+
+    resolved = find_available_port(port_hint, host=host, max_attempts=max_attempts)
+
+    config = uvicorn.Config(
+        create_server(),
+        host=host,
+        port=resolved,
+        log_level=log_level,
+    )
+    server = uvicorn.Server(config)
+    return server, resolved

dataface/core/serve/port.py

@@ -0,0 +1,129 @@
+"""Port resolution for dft serve / dft playground.
+
+Resolution order:
+1. Explicit --port CLI flag (highest priority)
+2. DFT_PORT env var
+3. port field in dataface.yml
+4. Hash-based port from project directory path
+5. Auto-increment fallback if chosen port is occupied
+"""
+
+import hashlib
+import os
+import socket
+from pathlib import Path
+
+# Range for hash-based ports: 9000–9999 (1000 slots).
+_PORT_RANGE_START = 9000
+_PORT_RANGE_SIZE = 1000
+
+
+def port_from_project_dir(project_dir: Path) -> int:
+    """Derive a deterministic port from the project directory path."""
+    resolved = str(project_dir.resolve())
+    digest = hashlib.sha256(resolved.encode()).hexdigest()
+    return _PORT_RANGE_START + int(digest, 16) % _PORT_RANGE_SIZE
+
+
+def _validate_port(port: int, source: str) -> None:
+    """Raise ValueError if *port* is outside the valid TCP range."""
+    if not (1 <= port <= 65535):
+        raise ValueError(f"{source} must be between 1 and 65535, got {port}")
+
+
+def is_port_available(port: int, host: str = "localhost") -> bool:
+    """Return True if *port* on *host* can be bound (IPv4 only)."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def find_available_port(
+    preferred: int,
+    host: str = "localhost",
+    max_attempts: int = 50,
+) -> int:
+    """Return *preferred* if free, otherwise scan upward until a free port is found."""
+    for offset in range(max_attempts):
+        candidate = preferred + offset
+        if candidate > 65535:
+            break
+        if is_port_available(candidate, host):
+            return candidate
+    raise RuntimeError(
+        f"Could not find an available port after {max_attempts} attempts "
+        f"(starting from {preferred})"
+    )
+
+
+def _read_port_from_config(project_dir: Path) -> int | None:
+    """Read a ``port`` field from dataface.yml / dataface.yaml, if present."""
+    import yaml
+
+    for name in ("dataface.yml", "dataface.yaml"):
+        cfg_path = project_dir / name
+        if cfg_path.exists():
+            try:
+                data = yaml.safe_load(cfg_path.read_text()) or {}
+            except yaml.YAMLError as e:
+                raise ValueError(f"Invalid YAML in {cfg_path}: {e}") from e
+            raw = data.get("port")
+            if raw is not None:
+                try:
+                    port = int(raw)
+                except (ValueError, TypeError):
+                    raise ValueError(
+                        f"Invalid port in {cfg_path}: expected integer, got {raw!r}"
+                    ) from None
+                _validate_port(port, f"port in {cfg_path}")
+                return port
+    return None
+
+
+def resolve_port(
+    *,
+    project_dir: Path,
+    explicit_port: int | None = None,
+    host: str = "localhost",
+    default_port: int | None = None,
+) -> int:
+    """Resolve the port to serve on.
+
+    Priority: explicit_port > DFT_PORT env > dataface.yml > hash-based default.
+
+    Explicit ports (--port flag) are returned as-is — if the user asked for a
+    specific port, we respect that even if it's occupied (uvicorn will error).
+
+    For auto-resolved ports, we auto-increment to the next available port if the
+    chosen one is occupied.
+    """
+    # 1. Explicit --port flag
+    if explicit_port is not None:
+        _validate_port(explicit_port, "--port")
+        return explicit_port
+
+    # 2. DFT_PORT env var
+    env_val = os.environ.get("DFT_PORT")
+    if env_val is not None:
+        try:
+            env_port = int(env_val)
+        except ValueError:
+            raise ValueError(f"DFT_PORT must be an integer, got: {env_val!r}") from None
+        _validate_port(env_port, "DFT_PORT")
+        return find_available_port(env_port, host)
+
+    # 3. dataface.yml port field
+    config_port = _read_port_from_config(project_dir)
+    if config_port is not None:
+        return find_available_port(config_port, host)
+
+    # 4. Hash-based default (or caller-supplied default_port)
+    if default_port is not None:
+        _validate_port(default_port, "default_port")
+        base = default_port
+    else:
+        base = port_from_project_dir(project_dir)
+    return find_available_port(base, host)