java-codebase-rag 0.9.6__py3-none-any.whl → 0.10.0__py3-none-any.whl

java_codebase_rag/watch/client.py

@@ -0,0 +1,230 @@
+"""IPC client for the ``jrag watch`` daemon: try-the-daemon, cold-fall-back.
+
+The cold read path is BYTE-IDENTICAL to today: when no daemon is alive (the
+common case — including every ``jrag`` subprocess invocation that is not a
+``jrag watch`` process), :func:`get_payload` falls back to the same
+``<cmd>_payload`` core the handler already calls, loading the graph via
+``_load_graph(cfg)`` (a cache hit on the already-loaded singleton). The daemon
+is a pure accelerator: it never changes observable output, only latency.
+
+Contract (pinned by task-8 brief):
+
+* :func:`is_daemon_alive` -> ``socket_path`` exists AND
+  :meth:`ProjectLock.read_holder` returns a live pid.
+* :func:`request` -> ``response.result`` dict; raises :class:`DaemonUnavailable`
+  (no daemon / version mismatch / hung) or :class:`DaemonError` (``ok=False``).
+* :func:`get_payload` -> the single seam each read handler calls. Tries the
+  daemon; on :class:`DaemonUnavailable`/:class:`DaemonError` runs the cold
+  ``cold_core(argparse.Namespace(**args), cfg, _load_graph(cfg))``. On success it
+  RECONSTRUCTS the payload object from the daemon's serialized dict so the
+  handler's downstream project+render runs unchanged.
+
+Reconstruction is the lossless inverse of :func:`watch.server.serialize`:
+pydantic ``*Output`` models round-trip via ``model_dump(mode="json")`` /
+``model_validate``; the traversal payloads (callers/callees/flow) are plain
+dicts and pass through. The one non-pydantic case is ``find`` query mode, whose
+``rows`` are :class:`SymbolHit` dataclasses accessed by attribute in the renderer
+(``row.id``); those are rebuilt via ``SymbolHit(**row)`` so the renderer is
+untouched. (The task-8 brief literal said "pass-through" for query mode; that
+would break the renderer's attribute access on the hot path, so the rows are
+rebuilt instead — see task-8 report.)
+"""
+from __future__ import annotations
+
+import socket
+from typing import TYPE_CHECKING, Any, Callable
+
+from java_codebase_rag.jrag import _load_graph
+from java_codebase_rag.watch.lock import ProjectLock
+from java_codebase_rag.watch.paths import socket_path
+from java_codebase_rag.watch.protocol import (
+    PROTOCOL_VERSION,
+    ProtocolMismatch,
+    Request,
+    decode_response,
+    encode_request,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# Connect/read budget so a hung daemon falls back to cold rather than blocking
+# the read command. 2s is generous for a local AF_UNIX round trip (the daemon
+# answers inline; a healthy response is sub-millisecond).
+_DAEMON_TIMEOUT = 2.0
+
+
+class DaemonUnavailable(Exception):
+    """No live daemon, an unreachable/hung daemon, or a protocol-version mismatch.
+
+    Always triggers the cold fallback in :func:`get_payload`.
+    """
+
+
+class DaemonError(Exception):
+    """The daemon answered ``ok=False`` (e.g. ``backend_error`` / ``stale_index``).
+
+    Attributes:
+        kind: the ``Response.error.kind`` string (``"backend_error"`` etc.).
+        message: the ``Response.error.message`` string.
+    """
+
+    def __init__(self, kind: str, message: str) -> None:
+        self.kind = kind
+        self.message = message
+        super().__init__(f"{kind}: {message}")
+
+
+def is_daemon_alive(index_dir: "Path") -> bool:
+    """True iff the daemon's socket exists AND a live holder pid is recorded.
+
+    The pid check (:meth:`ProjectLock.read_holder`) returns ``None`` for a
+    missing/empty pid file or a dead/stale pid, so a leftover socket alone does
+    not count as "alive" — a crashed daemon's socket is ignored and the read
+    falls back to cold.
+    """
+    if not socket_path(index_dir).exists():
+        return False
+    return ProjectLock.read_holder(index_dir) is not None
+
+
+def request(index_dir: "Path", cmd: str, args: dict) -> dict:
+    """Send one command to the daemon and return its ``result`` payload dict.
+
+    Raises:
+        DaemonUnavailable: not alive, unreachable/hung (timeout), closed
+            mid-response, or speaking a different protocol version (an older
+            daemon). All of these trigger the cold fallback.
+        DaemonError: the daemon responded ``ok=False``.
+    """
+    if not is_daemon_alive(index_dir):
+        raise DaemonUnavailable(f"no live daemon for {index_dir}")
+
+    sock_path = socket_path(index_dir)
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+            sock.settimeout(_DAEMON_TIMEOUT)
+            sock.connect(str(sock_path))
+            sock.sendall(encode_request(Request(v=PROTOCOL_VERSION, cmd=cmd, args=args)))
+            line = _readline(sock)
+    except OSError as exc:
+        # Timeout, connection refused, etc. -> cold fallback (never block).
+        raise DaemonUnavailable(f"daemon unreachable at {sock_path}: {exc}") from exc
+
+    try:
+        response = decode_response(line)
+    except (ProtocolMismatch, ValueError) as exc:
+        # Version mismatch (older daemon) or a blank/partial line (daemon gone)
+        # -> cold fallback rather than crashing the read command.
+        raise DaemonUnavailable(f"daemon response undecodable: {exc}") from exc
+
+    if not response.ok:
+        err = response.error
+        raise DaemonError(
+            err.kind if err is not None else "unknown",
+            err.message if err is not None else "",
+        )
+    return response.result
+
+
+def get_payload(cmd: str, args: dict, cfg, *, cold_core: Callable[..., Any]) -> Any:
+    """Return the payload for ``cmd``, trying the daemon first then cold-falling-back.
+
+    ``args`` is the command's full parsed-namespace dict (``vars(args)``);
+    ``cold_core`` is the matching ``<cmd>_payload(args, cfg, graph)`` core.
+
+    * Daemon success: the serialized payload dict is RECONSTRUCTED into the same
+      object the cold core returns, so the handler's render path is unchanged.
+    * DaemonUnavailable / DaemonError: the cold core runs against
+      ``_load_graph(cfg)`` — byte-identical to today (the daemon is absent in
+      every non-``watch`` invocation, and an ``ok=False`` frame re-surfaces as
+      the cold core's own ``PayloadError`` → identical error envelope + rc).
+    """
+    try:
+        result = request(cfg.index_dir, cmd, args)
+    except (DaemonUnavailable, DaemonError):
+        return cold_core(argparse_namespace(args), cfg, _load_graph(cfg))
+    return _reconstruct(cmd, result)
+
+
+# ---------------------------------------------------------------------------
+# internals
+# ---------------------------------------------------------------------------
+
+
+def _readline(sock: socket.socket) -> bytes:
+    """Read until newline (the response is one NDJSON line). Returns whatever was
+    received before newline/EOF; the caller decodes (and maps blanks to
+    ``DaemonUnavailable``)."""
+    buf = b""
+    while b"\n" not in buf:
+        chunk = sock.recv(4096)
+        if not chunk:
+            break
+        buf += chunk
+    return buf
+
+
+def _reconstruct(cmd: str, result: Any) -> Any:
+    """Rebuild the payload object the cold core returns from the daemon's JSON dict.
+
+    Inverse of :func:`watch.server.serialize`. See module docstring for the
+    find query-mode ``SymbolHit`` rebuild rationale.
+    """
+    if cmd == "search":
+        from java_codebase_rag.mcp.mcp_v2 import SearchOutput
+
+        return SearchOutput.model_validate(result)
+
+    if cmd == "inspect":
+        from java_codebase_rag.mcp.mcp_v2 import DescribeOutput
+
+        return {
+            "describe": DescribeOutput.model_validate(result["describe"]),
+            "node_id": result["node_id"],
+            "node_fqn": result["node_fqn"],
+            "file_location": result["file_location"],
+        }
+
+    if cmd == "find":
+        # The find payload is always a {"mode": "query"|"filter", ...} dict.
+        mode = result.get("mode")
+        if mode == "filter":
+            from java_codebase_rag.mcp.mcp_v2 import FindOutput
+
+            return {
+                "mode": "filter",
+                "kind": result["kind"],
+                "out": FindOutput.model_validate(result["out"]),
+                "limit": result["limit"],
+            }
+        # query mode: rows are SymbolHit dataclasses (attribute access in the
+        # renderer), rebuilt here so rendering is byte-identical.
+        from java_codebase_rag.graph.ladybug_queries import SymbolHit
+
+        return {
+            "mode": "query",
+            "rows": [SymbolHit(**row) for row in result["rows"]],
+            "raw_truncated": result["raw_truncated"],
+            "post_filter_active": result["post_filter_active"],
+            "limit": result["limit"],
+            "query": result["query"],
+            "kinds": result["kinds"],
+            "matched_mode": result["matched_mode"],
+            "identifier_matched": result["identifier_matched"],
+        }
+
+    # callers / callees / flow: plain dicts already (node/edge values are dicts
+    # of JSON-native scalars); pass through unchanged.
+    return result
+
+
+def argparse_namespace(args: dict):
+    """Build an ``argparse.Namespace`` from the args dict (deferred import).
+
+    Imported lazily so this module's top level stays free of the ``argparse``
+    dependency needed only on the cold path; also a single seam for the cold
+    core's ``args`` reconstruction."""
+    import argparse
+
+    return argparse.Namespace(**args)

java_codebase_rag/watch/daemon.py

@@ -0,0 +1,368 @@
+"""The ``jrag watch`` daemon process: assemble the watch components and run them.
+
+``WatchDaemon`` is the capstone that wires together the building blocks built in
+Tasks 2-10:
+
+  * :class:`watch.lock.ProjectLock` — single-writer mutual exclusion per project.
+  * :class:`watch.warm.WarmResources` — the warm embedding model + the read-only
+    graph reader (and the graph copy-on-write snapshot lifecycle).
+  * :class:`watch.server.WatchServer` — the AF_UNIX socket server that dispatches
+    read commands to the payload cores and ships the serialized payload.
+  * :class:`watch.watcher.SourceWatcher` — the file watcher + debounced per-type
+    reindex dispatcher.
+
+Lifecycle (``run_foreground``):
+
+  1. Acquire the project lock. Held elsewhere -> stderr line + ``return 2``.
+     Unsupported platform -> stderr line + ``return 2``.
+  2. EAGERLY warm the embedding model so a load failure fails fast (stderr +
+     ``on_event("error", …)`` + lock release + ``return 2``).
+  3. Install SIGINT/SIGTERM handlers that set a stop flag.
+  4. ``server.start()`` then ``watcher.start()``.
+  5. Write the state file (``paths.state_path``) so ``--status``/``--stop`` from
+     another process can see current truth.
+  6. Render a ``rich`` Live status panel (watcher state, last reindex) and
+     block on a wait loop until the stop flag is set.
+  7. Tear down in order — ``watcher.stop()`` → ``server.shutdown()`` →
+     ``lock.release()`` → unlink socket + state file — and terminate with
+     ``os._exit(0)``. The explicit ``os._exit`` (mirroring
+     ``jrag._console_script_main``) skips interpreter finalization, which dodges
+     a racy pyarrow/lance worker-thread SIGABRT once the daemon has served a
+     ``search`` (the read path loads lancedb in-process). ``run_foreground``
+     therefore NEVER returns normally on the serving path.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import signal
+import sys
+import threading
+import time
+from typing import TYPE_CHECKING, Any
+
+from java_codebase_rag.watch import paths
+from java_codebase_rag.watch.lock import (
+    LockHeldError,
+    ProjectLock,
+    WatchUnsupportedPlatform,
+)
+from java_codebase_rag.watch.server import WatchServer
+from java_codebase_rag.watch.warm import WarmResources
+from java_codebase_rag.watch.watcher import SourceWatcher
+
+if TYPE_CHECKING:
+    from java_codebase_rag.config import ResolvedOperatorConfig
+
+# State-file rewrites are throttled so a busy reindex burst does not hammer disk.
+# The initial write (``force=True``) and the last reindex both go through
+# immediately; ``--status`` readers tolerate a slightly-stale ``last_reindex``.
+_STATE_WRITE_MIN_INTERVAL_S = 1.0
+# The blocking loop's tick: how often the Live panel refreshes and how quickly a
+# stop signal is observed. 0.5 s is responsive without burning CPU.
+_LOOP_TICK_S = 0.5
+
+log = logging.getLogger(__name__)
+
+
+class WatchDaemon:
+    """Assemble the watch components and serve until interrupted.
+
+    The daemon process holds the project lock for its entire lifetime; the state
+    file is the cross-process truth that ``--status``/``--stop`` read.
+    """
+
+    def __init__(self, cfg: "ResolvedOperatorConfig") -> None:
+        self.cfg = cfg
+        self.lock = ProjectLock(cfg.index_dir)
+        self.warm = WarmResources(cfg)
+        self.server = WatchServer(self.warm, cfg)
+        self.watcher = SourceWatcher(
+            cfg,
+            self.warm,
+            debounce_ms=cfg.watch_debounce_ms,
+            backend=cfg.watch_backend,
+            poll_interval_ms=cfg.watch_poll_interval_ms,
+            on_event=self._record,
+        )
+
+        self._stop = threading.Event()
+        self._state_lock = threading.Lock()
+        self._last_state_write = 0.0
+        self._state: dict[str, Any] = {
+            "started_at": None,
+            "pid": None,
+            "socket": str(paths.socket_path(cfg.index_dir)),
+            "last_reindex_at": None,
+            "last_reindex_kind": None,
+            "reindex_count": 0,
+            # ``queries_served`` is left at 0 for v1: wiring a query-count
+            # callback out of ``WatchServer`` (Task 7, approved) is out of scope
+            # for this task's commit surface and the brief marks it optional.
+            "queries_served": 0,
+        }
+
+    # ------------------------------------------------------------------
+    # public lifecycle
+    # ------------------------------------------------------------------
+
+    def run_foreground(self) -> int:
+        """Serve until SIGINT/SIGTERM, then tear down and ``os._exit(0)``.
+
+        Early failure paths (lock held, unsupported platform, model-load error)
+        return ``2`` normally — they occur before the server accepts connections,
+        so no lance worker threads exist and interpreter finalization is safe.
+
+        The serving path (after ``server.start()``) terminates ONLY via
+        ``os._exit(0)`` in :meth:`_shutdown`; the trailing ``return 0`` is
+        unreachable and exists to satisfy the ``-> int`` contract.
+        """
+        # 1. Acquire the project lock (single writer per project).
+        try:
+            self.lock.acquire()
+        except LockHeldError as exc:
+            print(f"jrag watch: index in use by PID {exc.pid}", file=sys.stderr)
+            return 2
+        except WatchUnsupportedPlatform:
+            print("jrag watch: watch mode requires macOS/Linux", file=sys.stderr)
+            return 2
+
+        # 2. Eagerly warm the model so a load failure fails fast (before the
+        #    server accepts a single query). The model is the only heavy,
+        #    failure-prone resource that is not lazy on the read path.
+        try:
+            self.warm.model()
+        except Exception as exc:  # noqa: BLE001 — report any load failure, then bail
+            print(f"jrag watch: failed to load embedding model: {exc}", file=sys.stderr)
+            self._record("error", {"phase": "model_load", "error": repr(exc)})
+            self.lock.release()
+            return 2
+
+        # 3. Install stop-signal handlers (main thread only).
+        signal.signal(signal.SIGINT, self._on_signal)
+        signal.signal(signal.SIGTERM, self._on_signal)
+
+        # 4a. Server start: bind the socket before starting the watcher so a
+        #     query the moment the panel renders is already servable.
+        #
+        # We hold the EXCLUSIVE project lock, so we are the unique legitimate
+        # owner of this socket path: any pre-existing socket file is a corpse
+        # from a crashed prior daemon and MUST be cleared before bind, else
+        # AF_UNIX bind() fails with EADDRINUSE. ``server.start`` also defends
+        # against a stale socket for callers that do NOT hold the lock, but its
+        # guard (``read_holder is None``) is inert here precisely because we
+        # hold the lock — so the daemon clears its own stale socket itself.
+        stale_sock = paths.socket_path(self.cfg.index_dir)
+        try:
+            stale_sock.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError:
+            log.warning("could not unlink stale socket %s", stale_sock, exc_info=True)
+        try:
+            self.server.start()
+        except Exception as exc:  # noqa: BLE001 — socket bind failure is fatal-but-reported
+            print(f"jrag watch: failed to start server: {exc}", file=sys.stderr)
+            self.lock.release()
+            self._cleanup_runtime_files()
+            return 2
+        # 4b. Watcher start.
+        try:
+            self.watcher.start()
+        except Exception as exc:  # noqa: BLE001 — reported; server already up so shut it down
+            print(f"jrag watch: failed to start watcher: {exc}", file=sys.stderr)
+            self.server.shutdown()
+            self._cleanup_runtime_files()
+            self.lock.release()
+            return 2
+
+        # 5. Write the initial state file (force, so --status sees truth at once).
+        self._state["started_at"] = time.time()
+        self._state["pid"] = os.getpid()
+        self._write_state()
+
+        # 6 + 7. Serve, then tear down. _shutdown ends with os._exit(0) so the
+        #        finally never falls through; the return is unreachable.
+        try:
+            self._serve_until_stopped()
+        finally:
+            self._shutdown()
+        return 0  # pragma: no cover — os._exit in _shutdown
+
+    # ------------------------------------------------------------------
+    # event recording (called from the watcher debounce thread + the UI loop)
+    # ------------------------------------------------------------------
+
+    def _record(self, kind: str, detail: dict[str, Any]) -> None:
+        """Update in-memory state from a watcher event; throttle state rewrites.
+
+        Called on the watcher's debounce worker thread, so all state mutation is
+        under ``_state_lock``. The state file is rewritten at most once per
+        ``_STATE_WRITE_MIN_INTERVAL_S`` so ``--status`` readers see recent truth
+        without disk churn during a reindex burst.
+        """
+        with self._state_lock:
+            if kind == "indexing_done":
+                self._state["last_reindex_at"] = time.time()
+                self._state["last_reindex_kind"] = "+".join(detail.get("kinds", []))
+                self._state["reindex_count"] += 1
+            elif kind == "indexing_started":
+                self._state["last_reindex_kind"] = (
+                    "indexing:" + "+".join(detail.get("kinds", []))
+                )
+            elif kind == "error":
+                self._state["last_error"] = {
+                    "phase": detail.get("phase"),
+                    "at": time.time(),
+                    "detail": detail,
+                }
+            self._maybe_write_state_locked()
+
+    # ------------------------------------------------------------------
+    # serve loop + status panel
+    # ------------------------------------------------------------------
+
+    def _serve_until_stopped(self) -> None:
+        """Render the status panel and block until the stop flag is set.
+
+        On a non-TTY stdio (detached, piped, tests) the Live region is skipped in
+        favor of a single startup line — ``rich.Live`` on a pipe reprints the
+        whole panel on every update and would flood the redirect log.
+        """
+        from rich.console import Console
+
+        console = Console()
+        live = None
+        if console.is_terminal:
+            try:
+                from rich.live import Live
+
+                live = Live(
+                    self._render_panel(),
+                    console=console,
+                    refresh_per_second=4,
+                    transient=False,
+                )
+                live.start()
+            except Exception:  # noqa: BLE001 — Live is cosmetic; never block serving
+                live = None
+        if live is None:
+            print(
+                f"jrag watch: serving on {self._state['socket']} "
+                f"(pid {os.getpid()})",
+                flush=True,
+            )
+
+        try:
+            while not self._stop.is_set():
+                if live is not None:
+                    try:
+                        live.update(self._render_panel())
+                    except Exception:  # noqa: BLE001 — cosmetic
+                        pass
+                # Event.wait returns True as soon as the flag is set, so a stop
+                # signal is observed within one tick rather than the full window.
+                self._stop.wait(_LOOP_TICK_S)
+        finally:
+            if live is not None:
+                try:
+                    live.stop()
+                except Exception:  # noqa: BLE001 — cosmetic
+                    pass
+
+    def _render_panel(self):
+        """Build the ``rich`` status table from the current in-memory state."""
+        from rich.table import Table
+
+        with self._state_lock:
+            state = dict(self._state)
+        table = Table(title=f"jrag watch (pid {os.getpid()})", show_header=False, box=None)
+        table.add_row("socket", str(state.get("socket")))
+        table.add_row("reindex count", str(state.get("reindex_count", 0)))
+        last_kind = state.get("last_reindex_kind")
+        last_at = state.get("last_reindex_at")
+        if last_kind:
+            when = time.strftime("%H:%M:%S", time.localtime(last_at)) if last_at else "—"
+            table.add_row("last reindex", f"{last_kind} ({when})")
+        else:
+            table.add_row("last reindex", "—")
+        return table
+
+    # ------------------------------------------------------------------
+    # shutdown
+    # ------------------------------------------------------------------
+
+    def _shutdown(self) -> None:
+        """Tear down watcher → server → lock, remove runtime files, ``os._exit(0)``.
+
+        Each step is best-effort: a failure in one must not skip the rest, and
+        the process MUST terminate via ``os._exit(0)`` (never a normal return)
+        to avoid the lance worker-thread SIGABRT at finalization once the server
+        has served a ``search`` query.
+        """
+        try:
+            self.watcher.stop()
+        except Exception:  # noqa: BLE001 — teardown must continue
+            log.warning("watcher.stop raised during shutdown", exc_info=True)
+        try:
+            self.server.shutdown()
+        except Exception:  # noqa: BLE001
+            log.warning("server.shutdown raised during shutdown", exc_info=True)
+        try:
+            self.lock.release()
+        except Exception:  # noqa: BLE001
+            log.warning("lock.release raised during shutdown", exc_info=True)
+        self._cleanup_runtime_files()
+        sys.stdout.flush()
+        sys.stderr.flush()
+        os._exit(0)
+
+    # ------------------------------------------------------------------
+    # helpers
+    # ------------------------------------------------------------------
+
+    def _on_signal(self, signum, frame) -> None:  # noqa: ARG002 — signal API
+        """SIGINT/SIGTERM handler: flag the serve loop to stop (main thread)."""
+        self._stop.set()
+
+    def _cleanup_runtime_files(self) -> None:
+        """Remove the socket and state file (idempotent, best-effort)."""
+        for path in (
+            paths.socket_path(self.cfg.index_dir),
+            paths.state_path(self.cfg.index_dir),
+        ):
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                pass
+            except OSError:
+                log.warning("could not unlink %s", path, exc_info=True)
+
+    def _write_state(self) -> None:
+        """Unconditionally write the state JSON now (initial write).
+
+        Acquires ``_state_lock``; the throttled re-write path is
+        :meth:`_maybe_write_state_locked`, called by :meth:`_record` which
+        already holds the lock.
+        """
+        with self._state_lock:
+            self._write_state_locked()
+
+    def _maybe_write_state_locked(self) -> None:
+        """Throttled state write; caller MUST hold ``_state_lock``."""
+        now = time.monotonic()
+        if now - self._last_state_write >= _STATE_WRITE_MIN_INTERVAL_S:
+            self._write_state_locked()
+
+    def _write_state_locked(self) -> None:
+        """Write the JSON state file (best-effort); caller MUST hold ``_state_lock``."""
+        path = paths.state_path(self.cfg.index_dir)
+        data = dict(self._state)
+        try:
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_text(json.dumps(data))
+            os.replace(tmp, path)
+            self._last_state_write = time.monotonic()
+        except OSError:
+            log.warning("could not write state file %s", path, exc_info=True)