coda-node 0.1.0__py3-none-any.whl

coda_node/server/daemon.py

@@ -0,0 +1,261 @@
+"""Daemon management for the Coda node server.
+
+Provides functionality to run the server as a background daemon process
+with PID file tracking, log file redirection, and signal-based shutdown.
+
+The daemon process spawns uvicorn in the background, writes its PID to
+``/tmp/coda-node.pid``, and redirects output to
+``/tmp/coda-node.log``.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+__all__ = [
+    "DAEMON_LOG_PATH",
+    "DAEMON_PID_PATH",
+    "daemon_status",
+    "is_daemon_running",
+    "read_daemon_pid",
+    "start_daemon",
+    "stop_daemon",
+]
+
+_RUNTIME_DIR = Path(tempfile.gettempdir())
+DAEMON_PID_PATH = _RUNTIME_DIR / "coda-node.pid"
+DAEMON_LOG_PATH = _RUNTIME_DIR / "coda-node.log"
+
+
+def read_daemon_pid() -> int | None:
+    """Read the daemon PID from the PID file.
+
+    Returns:
+        The PID as an integer, or ``None`` if the file does not exist
+        or contains invalid content.
+    """
+    if not DAEMON_PID_PATH.exists():
+        return None
+    try:
+        return int(DAEMON_PID_PATH.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def _process_exists(pid: int) -> bool:
+    """Check if a process with the given PID exists."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError, OSError):
+        # OSError covers Windows-specific errors like WinError 87
+        return False
+
+
+def is_daemon_running() -> bool:
+    """Check if the daemon process is currently running.
+
+    Returns:
+        ``True`` if the PID file exists and the process is alive,
+        ``False`` otherwise.
+    """
+    pid = read_daemon_pid()
+    if pid is None:
+        return False
+    return _process_exists(pid)
+
+
+def daemon_status() -> dict[str, object]:
+    """Get detailed status information about the daemon.
+
+    Returns:
+        A dictionary containing:
+        - ``running``: Whether the daemon is running.
+        - ``pid``: The daemon PID (or ``None``).
+        - ``pid_file``: Path to the PID file.
+        - ``log_file``: Path to the log file.
+        - ``log_exists``: Whether the log file exists.
+    """
+    pid = read_daemon_pid()
+    running = pid is not None and _process_exists(pid)
+    return {
+        "running": running,
+        "pid": pid if running else None,
+        "pid_file": str(DAEMON_PID_PATH),
+        "log_file": str(DAEMON_LOG_PATH),
+        "log_exists": DAEMON_LOG_PATH.exists(),
+    }
+
+
+def start_daemon(
+    host: str = "0.0.0.0",
+    port: int = 8080,
+    token: str | None = None,
+) -> int:
+    """Start the server as a background daemon process.
+
+    Spawns a new Python process running uvicorn with the FastAPI app,
+    detached from the current terminal. The process PID is written to
+    :data:`DAEMON_PID_PATH` and output is redirected to
+    :data:`DAEMON_LOG_PATH`.
+
+    Args:
+        host: Bind address for the server.
+        port: Bind port for the server.
+        token: Optional node token for first-run provisioning.
+
+    Returns:
+        The PID of the spawned daemon process.
+
+    Raises:
+        RuntimeError: If the daemon is already running.
+    """
+    if is_daemon_running():
+        pid = read_daemon_pid()
+        raise RuntimeError(f"Daemon already running (PID {pid})")
+
+    # Clean up stale PID file if process is gone
+    if DAEMON_PID_PATH.exists():
+        DAEMON_PID_PATH.unlink()
+
+    # Build environment with optional token
+    env = os.environ.copy()
+    env["CODA_HOST"] = host
+    env["CODA_PORT"] = str(port)
+    if token:
+        env["CODA_NODE_TOKEN"] = token
+
+    # Build the command to run uvicorn directly
+    cmd = [
+        sys.executable,
+        "-m",
+        "uvicorn",
+        "coda_node.server.app:app",
+        "--host",
+        host,
+        "--port",
+        str(port),
+        "--log-level",
+        "warning",
+    ]
+
+    # Open log file for output redirection
+    log_handle = DAEMON_LOG_PATH.open("a", encoding="utf-8")
+
+    try:
+        if os.name == "nt":
+            # Windows: use creation flags to detach
+            creationflags = 0
+            creationflags |= getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+            creationflags |= getattr(subprocess, "DETACHED_PROCESS", 0)
+            creationflags |= getattr(subprocess, "CREATE_NO_WINDOW", 0)
+            process = subprocess.Popen(
+                cmd,
+                stdout=log_handle,
+                stderr=subprocess.STDOUT,
+                stdin=subprocess.DEVNULL,
+                env=env,
+                creationflags=creationflags,
+            )
+        else:
+            # POSIX: use start_new_session to detach from terminal
+            process = subprocess.Popen(
+                cmd,
+                stdout=log_handle,
+                stderr=subprocess.STDOUT,
+                stdin=subprocess.DEVNULL,
+                env=env,
+                start_new_session=True,
+            )
+    finally:
+        log_handle.close()
+
+    # Write PID file
+    DAEMON_PID_PATH.write_text(f"{process.pid}\n")
+    if os.name != "nt":
+        DAEMON_PID_PATH.chmod(0o644)
+
+    return process.pid
+
+
+def stop_daemon(timeout: float = 10.0) -> bool:
+    """Stop the running daemon process.
+
+    Sends ``SIGTERM`` (or uses ``taskkill`` on Windows) to the daemon
+    and waits for it to exit. If the process does not exit within
+    *timeout* seconds, sends ``SIGKILL``.
+
+    Args:
+        timeout: Seconds to wait for graceful shutdown before force-killing.
+
+    Returns:
+        ``True`` if a daemon was found and stopped, ``False`` if no
+        daemon was running.
+    """
+    pid = read_daemon_pid()
+    if pid is None:
+        return False
+
+    if not _process_exists(pid):
+        # Stale PID file, clean up
+        DAEMON_PID_PATH.unlink(missing_ok=True)
+        return False
+
+    try:
+        if os.name == "nt":
+            # Windows: use taskkill
+            subprocess.run(
+                ["taskkill", "/PID", str(pid), "/T", "/F"],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        else:
+            # POSIX: send SIGTERM first
+            os.kill(pid, signal.SIGTERM)
+
+            # Wait for process to exit
+            deadline = time.monotonic() + timeout
+            while time.monotonic() < deadline:
+                if not _process_exists(pid):
+                    break
+                time.sleep(0.1)
+            else:
+                # Process didn't exit, force kill
+                # Use getattr for SIGKILL since it doesn't exist on Windows
+                sigkill = getattr(signal, "SIGKILL", signal.SIGTERM)
+                os.kill(pid, sigkill)
+                time.sleep(0.5)
+
+        DAEMON_PID_PATH.unlink(missing_ok=True)
+        return True
+
+    except (PermissionError, ProcessLookupError, subprocess.TimeoutExpired):
+        DAEMON_PID_PATH.unlink(missing_ok=True)
+        return False
+
+
+def tail_daemon_log(lines: int = 50) -> str:
+    """Return the last *lines* of the daemon log file.
+
+    Args:
+        lines: Maximum number of lines to return.
+
+    Returns:
+        The log tail as a string, or an empty string if the log
+        file does not exist.
+    """
+    if not DAEMON_LOG_PATH.exists():
+        return ""
+    try:
+        all_lines = DAEMON_LOG_PATH.read_text().splitlines()
+        return "\n".join(all_lines[-lines:])
+    except OSError:
+        return ""

coda_node/server/executor.py

@@ -0,0 +1,200 @@
+"""Pluggable execution backend for quantum job processing.
+
+The :class:`JobExecutor` protocol defines the single ``run`` method that
+backends must implement.  A backend can be anything from a hardware QPU
+driver to a simulator -- the consumer doesn't care.
+
+Executor resolution order (in :func:`load_executor`):
+
+1. If ``CODA_EXECUTOR_FACTORY`` is set, import the dotted path and use
+   it as either a pre-built executor instance (has ``.run``) or a
+   factory callable.
+2. If ``settings.device_config`` provides an ``executor_factory`` value,
+   use that.
+3. Scan installed packages for the convention
+   ``<pkg>.executor_factory:create_executor``.  If exactly one match is
+   found, use it automatically.  If multiple match, warn and fall back.
+4. Fall back to :class:`NoopExecutor`, which returns a deterministic
+   all-zeros bitstring for every job.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, cast, runtime_checkable
+
+from coda_node.errors import ExecutorError
+from coda_node.server.ir import NativeGateIR
+
+if TYPE_CHECKING:
+    from coda_node.server.config import Settings
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ExecutionResult", "JobExecutor", "NoopExecutor", "load_executor"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionResult:
+    """Measurement outcome returned by an executor.
+
+    Attributes:
+        counts: Mapping from bitstring (e.g. ``"010"``) to the number of
+            times that outcome was observed.
+        execution_time_ms: Wall-clock execution time in milliseconds.
+        shots_completed: Total shots actually executed (may differ from
+            the requested count if the backend applies shot budgeting).
+    """
+
+    counts: dict[str, int]
+    execution_time_ms: float
+    shots_completed: int
+
+
+@runtime_checkable
+class JobExecutor(Protocol):
+    """Protocol that all execution backends must satisfy.
+
+    Implement a single async ``run`` method that accepts a validated IR
+    program and returns an :class:`ExecutionResult`.
+    """
+
+    async def run(self, ir: NativeGateIR, shots: int) -> ExecutionResult:
+        """Execute a quantum circuit and return measurement counts.
+
+        Args:
+            ir: A validated native-gate intermediate representation.
+            shots: Number of measurement shots to perform.
+
+        Returns:
+            An :class:`ExecutionResult` with bitstring counts.
+        """
+
+
+class NoopExecutor:
+    """Deterministic executor used for scaffolding and integration smoke tests."""
+
+    async def run(self, ir: NativeGateIR, shots: int) -> ExecutionResult:
+        """Return an all-zeros result for every circuit."""
+        bitstring = "0" * len(ir.measurements)
+        return ExecutionResult(
+            counts={bitstring: shots},
+            execution_time_ms=0.0,
+            shots_completed=shots,
+        )
+
+
+def _load_attr(import_path: str) -> Any:
+    """Import and return the attribute at *import_path* (``module:attr`` format)."""
+    module_name, sep, attr_name = import_path.partition(":")
+    if not sep or not module_name or not attr_name:
+        raise ExecutorError(
+            "CODA_EXECUTOR_FACTORY must look like 'package.module:factory_name'"
+        )
+    module = importlib.import_module(module_name)
+    return getattr(module, attr_name)
+
+
+def _instantiate_factory(import_path: str, settings: Settings) -> JobExecutor:
+    """Import and instantiate the executor at *import_path*."""
+    target = _load_attr(import_path)
+    if hasattr(target, "run"):
+        return cast(JobExecutor, target)
+
+    if not callable(target):
+        raise ExecutorError(f"Executor target {import_path!r} is not callable")
+
+    parameters = inspect.signature(target).parameters
+    executor = target(settings) if parameters else target()
+    if not hasattr(executor, "run"):
+        raise ExecutorError(f"Executor factory {import_path!r} did not return a runner")
+    return cast(JobExecutor, executor)
+
+
+def _discover_executor_factories() -> list[str]:
+    """Scan installed packages for the ``create_executor`` convention.
+
+    Iterates over importable top-level packages and checks whether
+    ``<pkg>.executor_factory`` exists with a callable ``create_executor``.
+    Returns a list of ``module:attr`` import paths.
+    """
+    try:
+        from importlib.metadata import packages_distributions
+    except ImportError:
+        return []
+
+    candidates: list[str] = []
+    for pkg in packages_distributions():
+        if "." in pkg or pkg.startswith("_") or pkg == "coda_node":
+            continue
+        module_name = f"{pkg}.executor_factory"
+        try:
+            spec = importlib.util.find_spec(module_name)
+        except (ModuleNotFoundError, ValueError):
+            continue
+        if spec is None:
+            continue
+        try:
+            mod = importlib.import_module(module_name)
+        except Exception:
+            logger.warning(
+                "Failed to import executor_factory module %r, skipping",
+                module_name,
+                exc_info=True,
+            )
+            continue
+        factory = getattr(mod, "create_executor", None)
+        if factory is not None and callable(factory):
+            candidates.append(f"{module_name}:create_executor")
+
+    return candidates
+
+
+def load_executor(settings: Settings) -> JobExecutor:
+    """Resolve and instantiate the configured execution backend.
+
+    Resolution order:
+
+    1. If ``settings.executor_factory`` is set, import and use it
+       (pre-built executor or factory callable).
+    2. If ``settings.device_config`` provides an ``executor_factory``
+       value, import and use it.
+    3. Scan installed packages for a conventional
+       ``<pkg>.executor_factory:create_executor`` factory.  Use it if
+       exactly one match is found; warn and skip if multiple match.
+    4. Fall back to :class:`NoopExecutor` with a warning.
+
+    Args:
+        settings: Runtime settings.
+
+    Returns:
+        An object satisfying the :class:`JobExecutor` protocol.
+
+    Raises:
+        ExecutorError: If the configured executor cannot be loaded.
+    """
+    if settings.executor_factory:
+        return _instantiate_factory(settings.executor_factory, settings)
+
+    discovered = _discover_executor_factories()
+
+    if len(discovered) == 1:
+        logger.info("Auto-discovered executor factory: %s", discovered[0])
+        return _instantiate_factory(discovered[0], settings)
+
+    if len(discovered) > 1:
+        logger.warning(
+            "Multiple executor factories discovered (%s); "
+            "set CODA_EXECUTOR_FACTORY to choose one. Using NoopExecutor.",
+            ", ".join(discovered),
+        )
+        return NoopExecutor()
+
+    logger.warning(
+        "No executor configured (set CODA_EXECUTOR_FACTORY); using NoopExecutor"
+    )
+    return NoopExecutor()

coda_node/server/heartbeat.py

@@ -0,0 +1,113 @@
+"""Periodic heartbeat reporter that keeps the QPU status "online".
+
+The :class:`HeartbeatClient` runs a background loop that POSTs
+authenticated status updates to the Coda cloud heartbeat endpoint
+every *interval* seconds.  If the QPU misses several consecutive
+heartbeats the cloud marks it offline, so this loop is essential for
+maintaining QPU visibility.
+
+The heartbeat payload mirrors the node's readiness state: current job,
+last job timestamp, and Redis health.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+import httpx
+
+from coda_node.server.auth import sign_token
+
+if TYPE_CHECKING:
+    from coda_node.server.consumer import RedisConsumer
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["HeartbeatClient"]
+
+_DEFAULT_INTERVAL = 30
+_HTTP_TIMEOUT = 10.0
+
+
+class HeartbeatClient:
+    """Send periodic authenticated heartbeats to the Coda cloud.
+
+    Args:
+        heartbeat_url: Full URL of the heartbeat endpoint.
+        qpu_id: QPU identifier used as the JWT ``sub`` claim.
+        jwt_private_key: PEM-encoded RSA private key for signing.
+        jwt_key_id: ``kid`` header value for the JWT.
+        consumer: The Redis consumer whose readiness state is reported.
+        interval: Seconds between heartbeat POSTs.
+        connectivity: Qubit-topology edge list (e.g. ``[[1, 0], [2, 1]]``).
+            For directed gate sets (CNOT) the order is ``[ctrl, tgt]``; for
+            symmetric gate sets (CZ, iSWAP, pCZ) the order is ignored by the
+            cloud compiler.  Sent with every heartbeat so the cloud
+            compiler can perform topology-aware routing.
+        extra_headers: Additional HTTP headers merged into every
+            heartbeat request (e.g. deployment-protection bypass).
+    """
+
+    def __init__(
+        self,
+        heartbeat_url: str,
+        qpu_id: str,
+        jwt_private_key: str,
+        jwt_key_id: str,
+        consumer: RedisConsumer,
+        interval: int = _DEFAULT_INTERVAL,
+        connectivity: list[list[int]] | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        """Initialise the heartbeat client with endpoint, credentials, and consumer."""
+        self._url = heartbeat_url
+        self._qpu_id = qpu_id
+        self._jwt_private_key = jwt_private_key
+        self._jwt_key_id = jwt_key_id
+        self._consumer = consumer
+        self._interval = interval
+        self._connectivity = connectivity
+        self._extra_headers = extra_headers or {}
+        self._running = False
+        self._client = httpx.AsyncClient(timeout=_HTTP_TIMEOUT)
+
+    async def _send(self) -> None:
+        """POST a single heartbeat with current node status."""
+        token = sign_token(self._qpu_id, self._jwt_private_key, key_id=self._jwt_key_id)
+        body: dict[str, object] = {
+            "current_job": self._consumer.current_job_id,
+            "last_job_at": self._consumer.last_job_at,
+            "redis_healthy": self._consumer.redis_healthy,
+            "connectivity": self._connectivity,
+        }
+        response = await self._client.post(
+            self._url,
+            json=body,
+            headers={"Authorization": f"Bearer {token}", **self._extra_headers},
+        )
+        response.raise_for_status()
+
+    async def run(self) -> None:
+        """Run the heartbeat loop until :meth:`stop` is called."""
+        self._running = True
+        logger.info(
+            "Heartbeat loop started (every %ds → %s)", self._interval, self._url
+        )
+        while self._running:
+            try:
+                await self._send()
+                logger.debug("Heartbeat sent to %s", self._url)
+            except Exception:
+                logger.warning("Heartbeat to %s failed", self._url, exc_info=True)
+            await asyncio.sleep(self._interval)
+
+    def stop(self) -> None:
+        """Signal the heartbeat loop to exit after the current iteration."""
+        self._running = False
+
+    async def close(self) -> None:
+        """Shut down the underlying HTTP connection pool."""
+        self.stop()
+        await self._client.aclose()