code-analysis-client-dev 1.6.341__py3-none-any.whl

code_analysis_client/commands_proxy.py

@@ -0,0 +1,63 @@
+"""
+Dynamic command wrappers: schema from server ``help``, then local shallow validation.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional, cast
+
+if TYPE_CHECKING:
+    from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+class ValidatedCommandsProxy:
+    """``client.commands.<name>(**params)`` — fetch schema via ``help``, validate, ``execute_command``."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: CodeAnalysisAsyncClient) -> None:
+        """Store the client used for schema lookup and validated command calls."""
+        object.__setattr__(self, "_client", client)
+
+    def clear_schema_cache(self) -> None:
+        """Forget cached schemas (e.g. after server ``reload``)."""
+        self._client.clear_command_schema_cache()
+
+    async def fetch_schema(
+        self, command: str, *, refresh: bool = False
+    ) -> Dict[str, Any]:
+        """Return input JSON schema for ``command`` (from server ``help``)."""
+        return cast(
+            Dict[str, Any],
+            await self._client.get_command_schema(command, refresh=refresh),
+        )
+
+    async def invoke(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Merge ``params`` and ``kwargs``, validate against server schema, execute."""
+        merged: Dict[str, Any] = dict(params or {})
+        if kwargs:
+            merged.update(kwargs)
+        return cast(Dict[str, Any], await self._client.call_validated(command, merged))
+
+    def __getattr__(self, name: str) -> Any:
+        """Return an async validated-call wrapper for an arbitrary command name."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        async def _bound(**kw: Any) -> Dict[str, Any]:
+            """Execute the dynamically selected command with validated keyword params."""
+            return cast(Dict[str, Any], await self._client.call_validated(name, kw))
+
+        _bound.__name__ = name
+        _bound.__doc__ = (
+            f"Validated call for command {name!r} (schema from server help)."
+        )
+        return _bound

code_analysis_client/config.py

@@ -0,0 +1,198 @@
+"""
+Map server / adapter-style settings dicts to JsonRpcClient constructor kwargs.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+from pathlib import Path
+from typing import Any, Mapping
+
+CANONICAL_CONFIG_PATH = Path("/etc/casmgr/config.json")
+
+#: Explicit adapter wait/timeout configuration of the client (owner decision 2026-10-24, item M5).
+#: The client hands it to ``JsonRpcClient(ws_config=...)``; the adapter resolves every wait timeout
+#: per call -> this config -> its own constants (60 s ``job_wait_timeout`` and ``cancel`` policy),
+#: so nothing here is left to the adapter's defaults. ``job_wait_timeout`` 0 means no total bound
+#: (a long queued command is never cut off); ``on_timeout`` ``detach`` means a caller timeout
+#: leaves the job running. ``job_push`` mirrors the server section of the same name.
+#: Keep equal to ``code_analysis.core.adapter_timeout_config`` (the server copy, same values).
+DEFAULT_CLIENT_ADAPTER_CONFIG: dict[str, dict[str, Any]] = {
+    "websocket": {
+        "job_wait_timeout": 0,
+        "on_timeout": "detach",
+        "receive_timeout": 60,
+        "receive_timeout_buffer": 5,
+        "heartbeat_interval": 30,
+        "terminal_poll_interval": 2,
+        "close_timeout": 5,
+        "subscribe_settle_delay": 0.5,
+        "cancel_grace_seconds": 0.5,
+    },
+    "job_push": {
+        "on_caller_loss": "detach",
+        "poll_interval": 0.1,
+    },
+}
+
+
+def merged_client_ws_config(user_config: Any = None) -> dict[str, Any]:
+    """Return ``ws_config`` for ``JsonRpcClient``: the defaults with ``user_config`` merged over them.
+
+    ``user_config`` is a mapping (or ``None``); each section is merged key by key so a partial
+    override keeps every other explicit default. Sections other than the defaults' are kept as given.
+    """
+    merged: dict[str, Any] = copy.deepcopy(DEFAULT_CLIENT_ADAPTER_CONFIG)
+    if user_config is None:
+        return merged
+    raw = getattr(user_config, "raw_content", None) if not isinstance(user_config, Mapping) else user_config
+    if not isinstance(raw, Mapping):
+        return merged
+    for name, value in raw.items():
+        if isinstance(value, Mapping) and isinstance(merged.get(name), dict):
+            merged[name].update(value)
+        else:
+            merged[name] = copy.deepcopy(value)
+    return merged
+
+
+def resolve_config_path(explicit: str | Path | None = None) -> Path:
+    """Return the server config path: explicit, then ``CASMGR_CONFIG``, then ``/etc/casmgr/config.json``.
+
+    Never falls back to the current working directory.
+
+    Raises:
+        FileNotFoundError: when no explicit path, no ``CASMGR_CONFIG`` and no ``/etc/casmgr/config.json``.
+    """
+    if explicit is not None and str(explicit).strip():
+        return Path(str(explicit)).expanduser().resolve()
+    env_value = os.environ.get("CASMGR_CONFIG", "").strip()
+    if env_value:
+        return Path(env_value).expanduser().resolve()
+    if CANONICAL_CONFIG_PATH.is_file():
+        return CANONICAL_CONFIG_PATH
+    raise FileNotFoundError(
+        "no server config found: pass a path, set CASMGR_CONFIG, or install /etc/casmgr/config.json"
+    )
+
+
+def _expand_path(value: Any) -> str | None:
+    """Expand a non-empty filesystem path value to an absolute string."""
+    if value is None or value == "":
+        return None
+    return str(Path(str(value)).expanduser().resolve())
+
+
+def _ssl_paths_from_section(ssl_section: Any) -> dict[str, str]:
+    """Extract and normalize TLS path fields from a config SSL section."""
+    if not isinstance(ssl_section, dict):
+        return {}
+    out: dict[str, str] = {}
+    for key in ("cert", "key", "ca", "cert_path", "key_path", "ca_path"):
+        raw = ssl_section.get(key)
+        expanded = _expand_path(raw) if raw else None
+        if expanded:
+            out[key] = expanded
+    # Normalize aliases to cert/key/ca for downstream comparison / JsonRpcClient
+    if "cert" not in out and out.get("cert_path"):
+        out["cert"] = out["cert_path"]
+    if "key" not in out and out.get("key_path"):
+        out["key"] = out["key_path"]
+    if "ca" not in out and out.get("ca_path"):
+        out["ca"] = out["ca_path"]
+    return out
+
+
+def _network_from_server_config(config: Mapping[str, Any]) -> dict[str, Any]:
+    """Return host, port, and protocol settings from a server config dict."""
+    server = config.get("server", {})
+    if not isinstance(server, dict):
+        server = {}
+    host = server.get("host", "127.0.0.1")
+    if host in ("0.0.0.0", "::", "[::]"):
+        host = "127.0.0.1"
+    return {
+        "host": host,
+        "port": int(server.get("port", 15001)),
+        "protocol": server.get("protocol", "http"),
+    }
+
+
+def _client_mtls_paths_from_server_config(config: Mapping[str, Any]) -> dict[str, str]:
+    """Prefer client.ssl; fall back to server.ssl (same rules as pipeline)."""
+    client_section = config.get("client", {})
+    if isinstance(client_section, dict):
+        ssl_section = client_section.get("ssl", {})
+        if isinstance(ssl_section, dict) and any(
+            ssl_section.get(k) for k in ("cert", "cert_path", "key", "key_path")
+        ):
+            return _ssl_paths_from_section(ssl_section)
+    server = config.get("server", {})
+    if not isinstance(server, dict):
+        return {}
+    return _ssl_paths_from_section(server.get("ssl", {}))
+
+
+def adapter_settings_from_server_config(config: Mapping[str, Any]) -> dict[str, Any]:
+    """Build adapter-style settings from a code-analysis server config dict."""
+    settings = dict(_network_from_server_config(config))
+    proto = str(settings.get("protocol", "")).lower()
+    if proto == "mtls":
+        settings["ssl"] = _client_mtls_paths_from_server_config(config)
+    elif proto == "https":
+        ssl_paths = _client_mtls_paths_from_server_config(config)
+        if ssl_paths.get("cert") and ssl_paths.get("key"):
+            settings["ssl"] = ssl_paths
+    return settings
+
+
+def adapter_settings_to_jsonrpc_kwargs(
+    settings: Mapping[str, Any],
+    *,
+    timeout: float | None = 60.0,
+    check_hostname: bool = False,
+    token_header: str | None = None,
+    token: str | None = None,
+) -> dict[str, Any]:
+    """Turn adapter-style settings into keyword args for JsonRpcClient."""
+    ssl_section = settings.get("ssl")
+    cert = key = ca = None
+    if isinstance(ssl_section, dict):
+        cert = ssl_section.get("cert") or ssl_section.get("cert_path")
+        key = ssl_section.get("key") or ssl_section.get("key_path")
+        ca = ssl_section.get("ca") or ssl_section.get("ca_path")
+        cert = _expand_path(cert) if cert else None
+        key = _expand_path(key) if key else None
+        ca = _expand_path(ca) if ca else None
+
+    th = token_header if token_header is not None else settings.get("token_header")
+    tok = token if token is not None else settings.get("token")
+
+    return {
+        "protocol": str(settings.get("protocol", "http")),
+        "host": str(settings.get("host", "127.0.0.1")),
+        "port": int(settings.get("port", 8080)),
+        "token_header": str(th) if th else None,
+        "token": str(tok) if tok else None,
+        "cert": cert,
+        "key": key,
+        "ca": ca,
+        "check_hostname": check_hostname,
+        "timeout": timeout,
+    }
+
+
+def load_server_config(path: str | Path) -> dict[str, Any]:
+    """Load server config.json into a dict."""
+    p = Path(path).expanduser()
+    with p.open("r", encoding="utf-8") as f:
+        data: Any = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError("Server config must be a JSON object")
+    # py3.10: return plain dict for mutability
+    return dict(data)

code_analysis_client/exceptions.py

@@ -0,0 +1,188 @@
+"""
+Client-side errors: parameter-validation failures and queued-job runtime errors.
+
+No dependency on the code_analysis server package.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class ClientValidationError(ValueError):
+    """Parameters do not match the command JSON schema, or the server refused a command.
+
+    ``code`` is ``VALIDATION_ERROR`` for a client-side parameter failure; when the server
+    answered with a refusal, ``code`` is the exact server error code (for example
+    ``SESSION_OPEN_IN_EDITOR``) and ``details`` is the server's error details object.
+    """
+
+    code: str | int = "VALIDATION_ERROR"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        code: str | int | None = None,
+    ) -> None:
+        """Initialize with optional field, details payload and the server error code."""
+        super().__init__(message)
+        self.field = field
+        self.details = details or {}
+        if code:
+            self.code = code
+
+
+class QueueJobError(RuntimeError):
+    """Base for queued-job runtime errors (job failure, timeout, command failure).
+
+    Deliberately does **not** inherit :class:`ClientValidationError`. That class
+    represents bad input caught before a call is even sent, and an
+    ``except ClientValidationError:`` handler written for that purpose must not
+    silently swallow a runtime failure that happened server-side after a valid
+    call was queued and polled. Catch ``QueueJobError`` (or its subclasses)
+    separately from parameter-validation errors.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        job_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize with message, the job id involved, and a details payload."""
+        super().__init__(message)
+        self.job_id = job_id
+        self.details = details or {}
+
+
+class JobFailedError(QueueJobError):
+    """A queued job was stopped or cancelled, or reported a queue-level error status.
+
+    A queued job that ended ``failed`` with the command's own error raises
+    :class:`CommandFailedError` instead (owner decision 2026-11-07, bug e58c5982).
+    """
+
+    def __init__(
+        self,
+        job_id: Optional[str],
+        error: Any = None,
+        *,
+        status: Optional[str] = None,
+    ) -> None:
+        """Store job id, verbatim error payload, and terminal status."""
+        message = f"Job {job_id!r} failed (status={status!r}): {error!r}"
+        super().__init__(
+            message,
+            job_id=job_id,
+            details={"job_id": job_id, "status": status, "error": error},
+        )
+        self.error = error
+        self.status = status
+
+
+class JobTimeoutError(QueueJobError):
+    """The caller wait exceeded ``timeout``; the call detached and the job keeps running server-side."""
+
+    def __init__(self, job_id: Optional[str], timeout: Optional[float]) -> None:
+        """Store job id and the timeout that was exceeded."""
+        message = (
+            f"Timed out after {timeout}s waiting for job {job_id!r}; "
+            "the job keeps running server-side - wait for it again with "
+            "QueuedJob.wait or retry with a longer timeout."
+        )
+        super().__init__(
+            message,
+            job_id=job_id,
+            details={"job_id": job_id, "timeout": timeout},
+        )
+        self.timeout = timeout
+
+
+class CommandFailedError(QueueJobError):
+    """A command ran but its inner result is an error envelope (``success`` false).
+
+    Raised for immediate and queued commands alike; a failing inner result is never
+    returned as a plain dict.
+    """
+
+    def __init__(
+        self,
+        command: Optional[str],
+        job_id: Optional[str],
+        error: Any,
+        *,
+        result: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Store command name, job id, the verbatim inner error object and the inner envelope."""
+        message = f"Command {command!r} failed (job_id={job_id!r}): {error!r}"
+        super().__init__(
+            message,
+            job_id=job_id,
+            details={"command": command, "job_id": job_id, "error": error},
+        )
+        self.command = command
+        self.error = error
+        self.result = result
+
+
+class VectorizerUnavailableError(RuntimeError):
+    """The vectorizer (embedding or chunker service) is not available.
+
+    Raised by vectorizer-dependent commands (semantic_search, revectorize)
+    when the embedding or chunker service is known unavailable.
+    The pre-V1 contract EMBEDDING_SERVICE_ERROR is reserved for a failure of
+    the call itself, not for unavailability of a known-down service.
+    """
+
+    code = "VECTORIZER_UNAVAILABLE"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        service: Optional[str] = None,
+        services: Optional[list[str]] = None,
+        reason: Optional[str] = None,
+        since: Optional[str] = None,
+        last_probe_at: Optional[str] = None,
+        retry_after_seconds: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize with message and vectorizer availability details.
+
+        Args:
+            message: Human-readable error message
+            service: The first unavailable required service (embedding or chunker)
+            services: List of all unavailable required services
+            reason: Reason for unavailability (e.g., timeout, connection_refused)
+            since: ISO-8601 UTC timestamp of when the service became unavailable
+            last_probe_at: ISO-8601 UTC timestamp of the last probe attempt
+            retry_after_seconds: Suggested wait time before retrying
+            details: Additional details dict (overrides individual fields if provided)
+        """
+        super().__init__(message)
+        if details is None:
+            details = {}
+        self.service = service or details.get("service")
+        self.services = services or details.get("services", [])
+        self.reason = reason or details.get("reason")
+        self.since = since or details.get("since")
+        self.last_probe_at = last_probe_at or details.get("last_probe_at")
+        self.retry_after_seconds = retry_after_seconds or details.get(
+            "retry_after_seconds"
+        )
+        self.details = {
+            "service": self.service,
+            "services": self.services,
+            "reason": self.reason,
+            "since": self.since,
+            "last_probe_at": self.last_probe_at,
+            "retry_after_seconds": self.retry_after_seconds,
+        }