refactor(exception): unify exception hierarchy and introduce specific error types

observerw · observerw · commit a3256346ff6c · 2025-12-22T15:05:39.000+08:00
diff --git a/src/lsp_client/client/__init__.py b/src/lsp_client/client/__init__.py
@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from .abc import Client
+from .exception import ClientError, ClientRuntimeError
+
+__all__ = [
+    "Client",
+    "ClientError",
+    "ClientRuntimeError",
+]
diff --git a/src/lsp_client/client/exception.py b/src/lsp_client/client/exception.py
@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from lsp_client.exception import LSPError
+
+if TYPE_CHECKING:
+    from .abc import Client
+
+
+class ClientError(LSPError):
+    """Base exception for client-related errors."""
+
+
+class ClientRuntimeError(ClientError):
+    """Raised when a client encounters a runtime error."""
+
+    def __init__(self, client: Client, *args: object):
+        super().__init__(*args)
+        self.client = client
diff --git a/src/lsp_client/clients/deno/client.py b/src/lsp_client/clients/deno/client.py
@@ -24,7 +24,7 @@
 )
 from lsp_client.capability.server_notification.log_message import WithReceiveLogMessage
 from lsp_client.client.abc import Client
-from lsp_client.server import DefaultServers
+from lsp_client.server import DefaultServers, ServerInstallationError
 from lsp_client.server.container import ContainerServer
 from lsp_client.server.local import LocalServer
 from lsp_client.utils.types import lsp_type
@@ -62,7 +62,7 @@ async def ensure_deno_installed() -> None:
         logger.info("Successfully installed deno via shell script")
         return
     except CalledProcessError as e:
-        raise RuntimeError(
+        raise ServerInstallationError(
             "Could not install deno. Please install it manually with:\n"
             "curl -fsSL https://deno.land/install.sh | sh\n\n"
             "See https://deno.land/ for more information."
diff --git a/src/lsp_client/clients/pyrefly.py b/src/lsp_client/clients/pyrefly.py
@@ -36,7 +36,7 @@
     WithRespondWorkspaceFoldersRequest,
 )
 from lsp_client.client.abc import Client
-from lsp_client.server import DefaultServers
+from lsp_client.server import DefaultServers, ServerInstallationError
 from lsp_client.server.container import ContainerServer
 from lsp_client.server.local import LocalServer
 from lsp_client.utils.types import lsp_type
@@ -60,7 +60,7 @@ async def ensure_pyrefly_installed() -> None:
             await anyio.run_process(["pip", "install", "pyrefly"])
         logger.info("Successfully installed pyrefly via uv tool")
     except CalledProcessError as e:
-        raise RuntimeError(
+        raise ServerInstallationError(
             "Could not install pyrefly. Please install it manually with 'pip install pyrefly'. "
             "See https://pyrefly.org/ for more information."
         ) from e
diff --git a/src/lsp_client/clients/pyright.py b/src/lsp_client/clients/pyright.py
@@ -35,7 +35,7 @@
     WithRespondWorkspaceFoldersRequest,
 )
 from lsp_client.client.abc import Client
-from lsp_client.server import DefaultServers
+from lsp_client.server import DefaultServers, ServerInstallationError
 from lsp_client.server.container import ContainerServer
 from lsp_client.server.local import LocalServer
 from lsp_client.utils.types import lsp_type
@@ -56,7 +56,7 @@ async def ensure_pyright_installed() -> None:
         logger.info("Successfully installed pyright-langserver via npm")
         return
     except CalledProcessError as e:
-        raise RuntimeError(
+        raise ServerInstallationError(
             "Could not install pyright-langserver. Please install it manually with 'npm install -g pyright'. "
             "See https://microsoft.github.io/pyright/ for more information."
         ) from e
diff --git a/src/lsp_client/clients/rust_analyzer.py b/src/lsp_client/clients/rust_analyzer.py
@@ -36,7 +36,7 @@
     WithRespondWorkspaceFoldersRequest,
 )
 from lsp_client.client.abc import Client
-from lsp_client.server import DefaultServers
+from lsp_client.server import DefaultServers, ServerInstallationError
 from lsp_client.server.container import ContainerServer
 from lsp_client.server.local import LocalServer
 from lsp_client.utils.types import lsp_type
@@ -56,7 +56,7 @@ async def ensure_rust_analyzer_installed() -> None:
         await anyio.run_process(["rustup", "component", "add", "rust-analyzer"])
         logger.info("Successfully installed rust-analyzer via rustup")
     except CalledProcessError as e:
-        raise RuntimeError(
+        raise ServerInstallationError(
             "Could not install rust-analyzer. Please install it manually with 'rustup component add rust-analyzer'. "
             "See https://rust-analyzer.github.io/ for more information."
         ) from e
diff --git a/src/lsp_client/clients/ty.py b/src/lsp_client/clients/ty.py
@@ -35,7 +35,7 @@
     WithRespondWorkspaceFoldersRequest,
 )
 from lsp_client.client.abc import Client
-from lsp_client.server import DefaultServers
+from lsp_client.server import DefaultServers, ServerInstallationError
 from lsp_client.server.container import ContainerServer
 from lsp_client.server.local import LocalServer
 from lsp_client.utils.types import lsp_type
@@ -54,7 +54,7 @@ async def ensure_ty_installed() -> None:
         logger.info("Successfully installed ty via pip")
         return
     except CalledProcessError as e:
-        raise RuntimeError(
+        raise ServerInstallationError(
             "Could not install ty. Please install it manually with 'pip install ty' or 'uv tool install ty'. "
             "See https://docs.astral.sh/ty/installation/ for more information."
         ) from e
diff --git a/src/lsp_client/clients/typescript.py b/src/lsp_client/clients/typescript.py
@@ -34,7 +34,7 @@
     WithRespondWorkspaceFoldersRequest,
 )
 from lsp_client.client.abc import Client
-from lsp_client.server import DefaultServers
+from lsp_client.server import DefaultServers, ServerInstallationError
 from lsp_client.server.container import ContainerServer
 from lsp_client.server.local import LocalServer
 from lsp_client.utils.types import lsp_type
@@ -61,7 +61,7 @@ async def ensure_typescript_installed() -> None:
         logger.info("Successfully installed typescript-language-server via npm")
         return
     except CalledProcessError as e:
-        raise RuntimeError(
+        raise ServerInstallationError(
             "Could not install typescript-language-server and typescript. Please install them manually with 'npm install -g typescript-language-server typescript'. "
             "See https://github.com/typescript-language-server/typescript-language-server for more information."
         ) from e
diff --git a/src/lsp_client/exception.py b/src/lsp_client/exception.py
@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class LSPError(Exception):
+    """Base exception for all lsp-client errors."""
diff --git a/src/lsp_client/jsonrpc/__init__.py b/src/lsp_client/jsonrpc/__init__.py
@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from .exception import (
+    JsonRpcError,
+    JsonRpcParseError,
+    JsonRpcResponseError,
+    JsonRpcTransportError,
+)
+
+__all__ = [
+    "JsonRpcError",
+    "JsonRpcParseError",
+    "JsonRpcResponseError",
+    "JsonRpcTransportError",
+]
diff --git a/src/lsp_client/jsonrpc/convert.py b/src/lsp_client/jsonrpc/convert.py
@@ -7,6 +7,7 @@
 
 from lsp_client.utils.types import Notification, Request, Response, lsp_type
 
+from .exception import JsonRpcParseError, JsonRpcResponseError
 from .types import (
     RawNotification,
     RawPackage,
@@ -74,16 +75,15 @@ def response_deserialize[R](
     match raw_resp:
         case {"error": _} as raw_err_resp:
             err_resp = converter.structure(raw_err_resp, lsp_type.ResponseErrorMessage)
-            raise (
-                ValueError(f"JSON-RPC Error {err.code}: {err.message}")
-                if (err := err_resp.error)
-                else ValueError(f"JSON-RPC Error: {err_resp}")
-            )
+            if err := err_resp.error:
+                raise JsonRpcResponseError(err.code, err.message, err.data)
+            else:
+                raise JsonRpcParseError(f"Invalid Error Response: {err_resp}")
         case {"result": _} as raw_resp:
             resp = converter.structure(raw_resp, schema)
             return resp.result
         case unexpected:
-            raise ValueError(f"Unexpected response: {unexpected}")
+            raise JsonRpcParseError(f"Unexpected response: {unexpected}")
 
 
 def response_serialize(response: Response[Any]) -> RawResponsePackage:
diff --git a/src/lsp_client/jsonrpc/exception.py b/src/lsp_client/jsonrpc/exception.py
@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from lsp_client.exception import LSPError
+
+
+class JsonRpcError(LSPError):
+    """Base exception for JSON-RPC related errors."""
+
+
+class JsonRpcParseError(JsonRpcError):
+    """Raised when parsing a JSON-RPC message fails."""
+
+
+class JsonRpcTransportError(JsonRpcError):
+    """Raised when the transport connection fails (e.g. unexpected EOF)."""
+
+
+class JsonRpcResponseError(JsonRpcError):
+    """Raised when the JSON-RPC response indicates an error."""
+
+    def __init__(self, code: int, message: str, data: object = None):
+        super().__init__(f"JSON-RPC Error {code}: {message}")
+        self.code = code
+        self.message = message
+        self.data = data
diff --git a/src/lsp_client/jsonrpc/parse.py b/src/lsp_client/jsonrpc/parse.py
@@ -7,6 +7,7 @@
 from anyio.streams.buffered import BufferedByteReceiveStream
 
 from .convert import package_serialize
+from .exception import JsonRpcParseError, JsonRpcTransportError
 from .types import RawPackage
 
 HEADER_RE = re.compile(r"Content-Length:\s*(?P<length>\d+)")
@@ -17,12 +18,12 @@ async def read_raw_package(receiver: BufferedByteReceiveStream) -> RawPackage:
     # when process is closed, the reader will always return b''
     header_bytes = await receiver.receive_until(b"\r\n", max_bytes=65536)
     if not header_bytes:
-        raise EOFError("LSP server process closed")
+        raise JsonRpcTransportError("LSP server process closed")
 
     header = header_bytes.decode("utf-8")
     header_match = HEADER_RE.match(header)
     if not header_match or not (length := int(header_match.group("length"))):
-        raise ValueError("Invalid LSP response header")
+        raise JsonRpcParseError("Invalid LSP response header")
 
     await receiver.receive_until(b"\r\n", max_bytes=65536)  # consume '\r\n'
 
diff --git a/src/lsp_client/server/__init__.py b/src/lsp_client/server/__init__.py
@@ -4,7 +4,7 @@
 
 from .abc import Server
 from .container import ContainerServer
-from .exception import ServerRuntimeError
+from .exception import ServerError, ServerInstallationError, ServerRuntimeError
 from .local import LocalServer
 
 
@@ -17,8 +17,9 @@ class DefaultServers:
 __all__ = [
     "ContainerServer",
     "DefaultServers",
-    "LSPServer",
     "LocalServer",
     "Server",
+    "ServerError",
+    "ServerInstallationError",
     "ServerRuntimeError",
 ]
diff --git a/src/lsp_client/server/exception.py b/src/lsp_client/server/exception.py
@@ -1,9 +1,24 @@
 from __future__ import annotations
 
-from .abc import Server
+from typing import TYPE_CHECKING
 
+from lsp_client.exception import LSPError
+
+if TYPE_CHECKING:
+    from .abc import Server
+
+
+class ServerError(LSPError):
+    """Base exception for server-related errors."""
+
+
+class ServerRuntimeError(ServerError):
+    """Raised when a server fails to start or crashes during execution."""
 
-class ServerRuntimeError(RuntimeError):
     def __init__(self, server: Server, *args: object):
         super().__init__(*args)
         self.server = server
+
+
+class ServerInstallationError(ServerError):
+    """Raised when a server executable cannot be found or installed."""
