| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862 |
- """Async LSP client over stdin/stdout — one per ``(server, workspace_root)``.
- Freshness is tracked with **document versions**, not timestamps: every didChange
- bumps ``version`` and each stored push/pull result is tagged with the version it
- describes, so a slow server's leftovers never masquerade as a verdict on the
- current content ("ghost diagnostics"). Whole-document sync is always sent, every
- ``open_file`` also fires ``didChangeWatchedFiles`` (clangd/eslint only re-scan on
- it), and ``ContentModified`` (-32801) errors are retried with exponential backoff.
- """
- from __future__ import annotations
- import asyncio
- import contextlib
- import logging
- import os
- import sys
- from dataclasses import dataclass, field
- from pathlib import Path
- from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
- from urllib.parse import quote, unquote
- from hermes_cli._subprocess_compat import windows_hide_flags
- from hermes_cli.process_identity import own_process_groups, register_child, release_process_group_once_empty
- from agent.lsp.protocol import (
- ERROR_CONTENT_MODIFIED, ERROR_METHOD_NOT_FOUND, LSPProtocolError, LSPRequestError, classify_message,
- encode_message, make_error_response, make_notification, make_request, make_response, read_message,
- )
- logger = logging.getLogger("agent.lsp.client")
- # asyncio's 64 KiB StreamReader default makes readline() raise on one long LSP
- # stderr line (#31417); 16 MiB covers realistic output while staying bounded.
- _STREAM_LIMIT = 16 * 1024 * 1024
- # Timeouts (seconds).
- INITIALIZE_TIMEOUT = 45.0
- DIAGNOSTICS_DOCUMENT_WAIT = 5.0
- DIAGNOSTICS_FULL_WAIT = 10.0
- DIAGNOSTICS_REQUEST_TIMEOUT = 3.0
- PUSH_DEBOUNCE = 0.15
- SHUTDOWN_GRACE = 1.0 # seconds after `exit` before SIGTERM, and between SIGTERM and SIGKILL
- # Retry policy for transient ContentModified errors: 0.5, 1.0, 2.0s.
- MAX_CONTENT_MODIFIED_RETRIES = 3
- RETRY_BASE_DELAY = 0.5
- # Last server stderr lines kept for failure reports; the V8 heap-abort trace that explains a
- # tsserver SIGABRT is otherwise only visible at DEBUG, so the WARNING a user actually reads
- # cannot distinguish "binary missing" from "server ran out of memory".
- STDERR_TAIL_LINES = 30
- # Cap on tracked documents: each _DocState pins the file's full text here AND the server mirrors
- # every open document, so an uncapped dict pins everything a long session ever touched on both
- # sides of the pipe until the idle reaper kills the whole client (#62950). 64 covers an active
- # edit loop's working set; evicted files are didClose'd and re-didOpen'ed on their next touch.
- MAX_TRACKED_FILES = 64
- _WRITE_ERRORS = (BrokenPipeError, ConnectionResetError, OSError)
- _LIVE_STATES = {"starting", "running"}
- _CLIENT_CAPABILITIES: dict[str, Any] = {
- "window": {"workDoneProgress": True},
- "workspace": {"configuration": True, "workspaceFolders": True,
- "didChangeWatchedFiles": {"dynamicRegistration": True}, "diagnostics": {"refreshSupport": False}},
- "textDocument": {
- "synchronization": {"dynamicRegistration": False, "didOpen": True, "didChange": True,
- "didSave": True, "willSave": False, "willSaveWaitUntil": False},
- "diagnostic": {"dynamicRegistration": True, "relatedDocumentSupport": True},
- "publishDiagnostics": {"relatedInformation": True, "tagSupport": {"valueSet": [1, 2]},
- "versionSupport": True, "codeDescriptionSupport": True, "dataSupport": False},
- "hover": {"contentFormat": ["markdown", "plaintext"]},
- "definition": {"linkSupport": True},
- "references": {},
- "documentSymbol": {"hierarchicalDocumentSymbolSupport": True},
- },
- "general": {"positionEncodings": ["utf-16"]},
- }
- def file_uri(path: str) -> str:
- """Return a ``file://`` URI for a path (handles spaces, unicode, Windows drive letters)."""
- abs_path = os.path.abspath(path)
- if os.name == "nt":
- # ``C:\foo`` → ``file:///C:/foo``: the drive letter must be a path component.
- abs_path = abs_path.replace("\\", "/")
- abs_path = abs_path if abs_path.startswith("/") else "/" + abs_path
- return "file://" + quote(abs_path, safe="/:")
- def _folder(root: str) -> dict[str, str]:
- """Build an LSP ``WorkspaceFolder`` for ``root``."""
- return {"name": os.path.basename(root.rstrip(os.sep)) or root, "uri": file_uri(root)}
- def uri_to_path(uri: str) -> str:
- """Inverse of :func:`file_uri`."""
- if not uri.startswith("file://"):
- return uri
- raw = uri[len("file://"):]
- if os.name == "nt" and raw.startswith("/") and len(raw) > 2 and raw[2] == ":":
- raw = raw[1:] # strip leading slash before drive letter
- return os.path.normpath(unquote(raw))
- def _end_position(text: str) -> dict[str, int]:
- """LSP Position at the end of ``text`` (for a whole-document replace range)."""
- if not text:
- return {"line": 0, "character": 0}
- lines = text.splitlines(keepends=False)
- # splitlines drops a trailing newline: the end is then the start of the next (empty) line.
- if text.endswith(("\n", "\r")):
- return {"line": len(lines), "character": 0}
- # Positions use UTF-16 code units, matching our advertised positionEncodings.
- return {"line": len(lines) - 1, "character": len(lines[-1].encode("utf-16-le")) // 2}
- @dataclass
- class _DocState:
- """Per-document state. ``version`` is the LSP document version last sent (didOpen=0, +1 per
- didChange) and doubles as the freshness token: ``push_version`` / ``pull_version`` tag stored
- results, fresh iff tag >= version; -1 means "no data yet". Servers that echo a version in
- publishDiagnostics get exact tagging; others are credited with the current version at receipt."""
- version: int = 0
- text: str = ""
- push: list[dict[str, Any]] = field(default_factory=list)
- pull: list[dict[str, Any]] = field(default_factory=list)
- push_version: int = -1
- pull_version: int = -1
- seed_seen: bool = False
- def fresh_push(self, version: Optional[int] = None) -> bool:
- return self.push_version >= (self.version if version is None else version)
- def fresh_pull(self, version: Optional[int] = None) -> bool:
- return self.pull_version >= (self.version if version is None else version)
- def fresh(self, version: Optional[int] = None) -> bool:
- return self.fresh_push(version) or self.fresh_pull(version)
- def as_disk_read(text: str) -> str:
- """``text`` as ``Path.read_text(encoding="utf-8-sig", errors="replace")`` returns the file holding it."""
- try:
- text = text.encode("utf-8", "surrogateescape").decode("utf-8-sig", "replace")
- except UnicodeEncodeError: # lone surrogate outside the escape range: keep the text, drop the BOM
- text = text.removeprefix("\ufeff")
- return text.replace("\r\n", "\n").replace("\r", "\n")
- class LSPClient:
- """One server process + one workspace root. ``start()`` → ``open_file()`` → ``wait_for_diagnostics()`` →
- ``diagnostics_for()`` → ``shutdown()``."""
- def __init__(self, *, server_id: str, workspace_root: str, command: list[str],
- env: Optional[dict[str, str]] = None, cwd: Optional[str] = None,
- initialization_options: Optional[dict[str, Any]] = None,
- seed_diagnostics_on_first_push: bool = False) -> None:
- self.server_id = server_id
- self.workspace_root = workspace_root
- # Roots this server serves. Single-root servers only ever hold ``workspace_root``;
- # multi-root servers (pyright) grow this via ``add_workspace_folder`` instead of a second process.
- self.workspace_folders: list[str] = [workspace_root]
- self._command = list(command)
- self._env = env
- self._cwd = cwd or workspace_root
- self._init_options = initialization_options or {}
- self._seed_first_push = seed_diagnostics_on_first_push
- self._proc: Optional[asyncio.subprocess.Process] = None
- self._stderr_task: Optional[asyncio.Task] = None
- # Ring buffer of the most recent server stderr lines, surfaced when spawn/initialize fails.
- self._stderr_tail: list[str] = []
- self._exit_code: Optional[int] = None
- self._reader_task: Optional[asyncio.Task] = None
- self._cleanup_lock = asyncio.Lock()
- self._next_id: int = 0
- self._pending: dict[int, asyncio.Future] = {}
- # Server → client requests; anything else gets method-not-found. Capability (un)registration
- # and diagnostic refresh are acknowledged but not acted on: we re-pull on every touch anyway.
- self._request_handlers: dict[str, Callable[[Any], Awaitable[Any]]] = {
- "window/workDoneProgress/create": self._handle_null,
- "workspace/configuration": self._handle_workspace_configuration,
- "client/registerCapability": self._handle_null,
- "client/unregisterCapability": self._handle_null,
- "workspace/workspaceFolders": self._handle_workspace_folders,
- "workspace/diagnostic/refresh": self._handle_null,
- }
- # Server → client notifications; others (showMessage, $/progress) are dropped.
- self._notification_handlers: dict[str, Callable[[Any], None]] = {
- "textDocument/publishDiagnostics": self._handle_publish_diagnostics,
- }
- self._docs: dict[str, _DocState] = {} # keyed by absolute path (NOT URI)
- self._state: str = "stopped"
- self._sync_kind: int = 1 # 1=Full, 2=Incremental
- # Cleared when the server rejects textDocument/diagnostic as unknown: no further pulls.
- self._pull_supported: bool = True
- self._stopping: bool = False
- # Waiters snapshot ``_push_counter`` and treat any increase as "recheck the
- # predicate" — avoids the asyncio.Event sticky-state trap.
- self._push_event = asyncio.Event()
- self._push_counter = 0
- @property
- def state(self) -> str:
- return self._state
- @property
- def is_running(self) -> bool:
- return self._state == "running" and self._connection_is_open()
- def _connection_is_open(self) -> bool:
- proc, reader = self._proc, self._reader_task
- return (
- self._state in _LIVE_STATES
- and proc is not None and proc.returncode is None
- and proc.stdin is not None and not proc.stdin.is_closing()
- and reader is not None and not reader.done()
- )
- # ---- lifecycle ----
- async def start(self) -> None:
- """Spawn + initialize handshake. On failure the process is killed and state is ``"error"``; re-call to retry."""
- if self._state in _LIVE_STATES:
- return
- self._state = "starting"
- try:
- await self._spawn()
- await self._initialize()
- if not self._connection_is_open():
- raise LSPProtocolError("server connection closed during initialization")
- self._state = "running"
- except BaseException as e:
- self._state = "error"
- # Reap the server now so the failure report can name the exit status (a Node heap
- # abort dies on SIGABRT; without this the caller logs an opaque JSON-RPC error).
- # The reader loop may have run ``_cleanup_process`` first — it records the code
- # too, so both orderings leave ``failure_details`` populated.
- proc = self._proc
- if proc is not None:
- with contextlib.suppress(Exception):
- await asyncio.wait_for(proc.wait(), timeout=1.0)
- if proc.returncode is not None:
- self._exit_code = proc.returncode
- stderr_task = self._stderr_task
- if stderr_task is not None: # brief window to collect the abort trace
- with contextlib.suppress(Exception):
- await asyncio.wait_for(asyncio.shield(stderr_task), timeout=0.5)
- # ``_BackgroundLoop.run`` cancels this task when its outer budget expires.
- # CancelledError is a BaseException on supported Python versions, and cleanup
- # must outlive that cancellation or the spawned server escapes all tracking.
- await asyncio.shield(self._cleanup_process())
- # Attach the details to the ORIGINAL exception rather than re-instantiating its
- # type: LSPRequestError's ctor is (code, message, data), so ``type(e)(text)``
- # would surface as a TypeError instead of the LSP error the caller logs.
- details = self.failure_details()
- if details and isinstance(e, Exception):
- e.args = (f"{e} ({details})",)
- raise
- async def _spawn(self) -> None:
- from agent.delegation_context import delegated_child_subprocess_env
- from tools.environments.local import hermes_subprocess_env
- cmd = self._command
- if sys.platform == "win32" and cmd[0].lower().endswith((".cmd", ".bat")):
- cmd = ["cmd.exe", "/c", *cmd] # CreateProcess can't run .cmd/.bat shims directly
- try:
- # start_new_session=True gives the server its own process group; otherwise it inherits
- # the gateway's pgid and mcp_tool's orphan sweeper can killpg() the TUI parent with it.
- # windows_hide_flags() suppresses the console window a .cmd shim would flash from a
- # console-less host (CREATE_NO_WINDOW; 0 on POSIX).
- # Language servers are third-party binaries a write_file can start: they get the
- # scrubbed env (no gateway tokens, no provider keys), plus their own configured env.
- self._proc = await asyncio.create_subprocess_exec(
- cmd[0], *cmd[1:], limit=_STREAM_LIMIT,
- stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
- env=delegated_child_subprocess_env({**hermes_subprocess_env(), **(self._env or {})}), cwd=self._cwd,
- start_new_session=True, # detached-spawn: ok — the group goes to own_process_groups below
- creationflags=windows_hide_flags(),
- )
- except FileNotFoundError as e:
- raise LSPProtocolError(f"LSP server binary not found: {cmd[0]} ({e})") from e
- # The server itself exits on stdin EOF when we die, but a descendant that does not hold or
- # watch that pipe (a wrapper's background child, a SIGTERM-ignoring worker) outlived a
- # SIGKILLed / OOM-killed Hermes forever. The owner-death supervisor kills the whole group
- # the moment this process dies, by any cause. No-op on Windows (job object instead).
- own_process_groups([self._proc.pid])
- # Off the event loop: the ledger write takes a cross-process lock (up to 2 s).
- await asyncio.to_thread(register_child, self._proc.pid, "lsp-server")
- # stderr must be drained or the pipe buffer fills and the server hangs.
- self._stderr_task = asyncio.create_task(self._drain_stderr())
- self._reader_task = asyncio.create_task(self._reader_loop())
- async def _drain_stderr(self) -> None:
- if self._proc is None or self._proc.stderr is None:
- return
- stderr = self._proc.stderr
- try:
- while True:
- try:
- line = await stderr.readline()
- except ValueError:
- # StreamReader.readline() translates LimitOverrunError to
- # ValueError after discarding the oversized buffer. Continue
- # draining so a pathological stderr line cannot leave the
- # pipe unread and block the server.
- logger.warning(
- "[%s] stderr: line exceeded stream limit, discarding",
- self.server_id,
- )
- continue
- if not line:
- break
- if text := line.decode("utf-8", errors="replace").rstrip():
- logger.debug("[%s] stderr: %s", self.server_id, text[:1000])
- self._stderr_tail.append(text[:1000])
- del self._stderr_tail[:-STDERR_TAIL_LINES]
- except (asyncio.CancelledError, OSError):
- pass
- def _describe_exit(self) -> str:
- """Human rendering of the server exit status; empty when the process is still live."""
- proc = self._proc
- if self._exit_code is not None:
- code = self._exit_code
- elif proc is not None and proc.returncode is not None:
- code = proc.returncode
- else:
- return ""
- if code < 0:
- return f"server exited on signal {-code}"
- return f"server exited with code {code}"
- def failure_details(self) -> str:
- """Exit status + last stderr lines for a failed spawn/initialize; empty for a live server."""
- parts: list[str] = []
- if exit_desc := self._describe_exit():
- parts.append(exit_desc)
- if self._stderr_tail:
- parts.append("last stderr lines: " + " | ".join(self._stderr_tail))
- return "; ".join(parts)
- def _dispatch(self, msg: dict) -> None:
- kind, key = classify_message(msg)
- if kind == "response":
- self._dispatch_response(key, msg)
- elif kind == "request":
- asyncio.create_task(self._dispatch_request(key, msg))
- elif kind == "notification":
- self._dispatch_notification(key, msg)
- else:
- logger.warning("[%s] dropping invalid message: %r", self.server_id, msg)
- async def _reader_loop(self) -> None:
- if self._proc is None or self._proc.stdout is None:
- return
- try:
- while (msg := await read_message(self._proc.stdout)) is not None:
- self._dispatch(msg)
- logger.debug("[%s] server closed stdout cleanly", self.server_id)
- except LSPProtocolError as e:
- logger.warning("[%s] protocol error in reader loop: %s", self.server_id, e)
- except (asyncio.CancelledError, OSError):
- pass
- finally:
- unexpected_close = not self._stopping and self._state in _LIVE_STATES
- if unexpected_close:
- self._state = "error"
- for fut in list(self._pending.values()): # fail pending requests fast
- if not fut.done():
- fut.set_exception(LSPProtocolError("server connection closed"))
- self._pending.clear()
- if unexpected_close:
- await self._cleanup_process()
- def _workspace_folders(self) -> list[dict[str, str]]:
- return [_folder(r) for r in self.workspace_folders]
- async def add_workspace_folder(self, root: str) -> None:
- """Attach another root to a running multi-root server. Idempotent; the folder is recorded
- before the notification is sent so concurrent callers for the same root only announce once."""
- if root in self.workspace_folders:
- return
- self.workspace_folders.append(root)
- await self._send_notification(
- "workspace/didChangeWorkspaceFolders", {"event": {"added": [_folder(root)], "removed": []}},
- )
- async def remove_workspace_folder(self, root: str) -> None:
- """Detach ``root`` from a running multi-root server (a removed worktree) so the process keeps
- serving its sibling roots instead of being torn down with them. Idempotent."""
- if root not in self.workspace_folders:
- return
- self.workspace_folders.remove(root)
- await self._send_notification(
- "workspace/didChangeWorkspaceFolders", {"event": {"added": [], "removed": [_folder(root)]}},
- )
- async def _initialize(self) -> None:
- params = {
- "rootUri": file_uri(self.workspace_root), "rootPath": self.workspace_root, "processId": os.getpid(),
- "workspaceFolders": self._workspace_folders(),
- "initializationOptions": self._init_options, "capabilities": _CLIENT_CAPABILITIES,
- }
- result = await asyncio.wait_for(self._send_request("initialize", params), timeout=INITIALIZE_TIMEOUT)
- sync = (result.get("capabilities") or {}).get("textDocumentSync")
- if isinstance(sync, dict):
- sync = sync.get("change")
- self._sync_kind = sync if isinstance(sync, int) else 1 # default to Full
- await self._send_notification("initialized", {})
- if self._init_options: # vtsls/eslint only pick config up via didChangeConfiguration
- await self._send_notification("workspace/didChangeConfiguration", {"settings": self._init_options})
- async def shutdown(self) -> None:
- """Best-effort graceful shutdown: ``shutdown`` + ``exit``, wait ``SHUTDOWN_GRACE`` for the
- server to honour ``exit``, then SIGTERM/SIGKILL. Idempotent."""
- if self._stopping:
- return
- self._stopping = True
- try:
- if self.is_running:
- try:
- await asyncio.wait_for(self._send_request("shutdown", None), timeout=2.0)
- except (TimeoutError, LSPRequestError, LSPProtocolError):
- pass
- try:
- await self._send_notification("exit", None)
- except Exception:
- pass
- # Signalling right after ``exit`` races the server's own exit: needless SIGTERM
- # noise for well-behaved servers and, on Darwin, a reaped-and-reused PID target.
- if (proc := self._proc) is not None and proc.returncode is None:
- with contextlib.suppress(asyncio.TimeoutError):
- await asyncio.wait_for(proc.wait(), timeout=SHUTDOWN_GRACE)
- finally:
- self._state = "stopped"
- await self._cleanup_process()
- async def _cleanup_process(self) -> None:
- async with self._cleanup_lock:
- tasks = [self._reader_task, self._stderr_task]
- self._reader_task = self._stderr_task = None
- proc, self._proc = self._proc, None
- live = [t for t in tasks if t is not None and not t.done() and t is not asyncio.current_task()]
- for t in live:
- t.cancel()
- await asyncio.gather(*live, return_exceptions=True)
- if proc is None:
- return
- if proc.returncode is not None:
- if self._exit_code is None:
- self._exit_code = proc.returncode
- release_process_group_once_empty(proc.pid, timeout=0)
- return
- try:
- # ``shutdown`` has already given the protocol a grace period. Hard-kill
- # the tree while its ancestry is still observable: waiting for the launcher
- # after SIGTERM can let an ignoring descendant become reparented and escape.
- # Windows maps this to a synchronous taskkill /T /F (up to 15s), so the
- # kill runs off the event loop.
- from agent.deadline import kill_process_tree
- if not await asyncio.to_thread(kill_process_tree, proc.pid):
- proc.kill()
- with contextlib.suppress(asyncio.TimeoutError):
- await asyncio.wait_for(proc.wait(), timeout=SHUTDOWN_GRACE)
- except ProcessLookupError:
- pass
- if self._exit_code is None and proc.returncode is not None:
- self._exit_code = proc.returncode
- release_process_group_once_empty(proc.pid, timeout=0)
- # ---- request / notification plumbing ----
- async def _write(self, msg: dict) -> None:
- assert self._proc is not None and self._proc.stdin is not None
- self._proc.stdin.write(encode_message(msg))
- await self._proc.stdin.drain()
- def _require_open(self, method: str) -> None:
- if not self._connection_is_open():
- raise LSPProtocolError(f"cannot send {method!r}: server connection closed")
- async def _send_request(self, method: str, params: Any) -> Any:
- self._require_open(method)
- req_id, self._next_id = self._next_id, self._next_id + 1
- fut: asyncio.Future = asyncio.get_running_loop().create_future()
- self._pending[req_id] = fut
- try:
- await self._write(make_request(req_id, method, params))
- except _WRITE_ERRORS as e:
- self._pending.pop(req_id, None)
- raise LSPProtocolError(f"send failed for {method!r}: {e}") from e
- try:
- return await fut
- except asyncio.CancelledError:
- # The caller abandoned the request (wait_for timeout, or the pull/push race in
- # wait_for_diagnostics cancelling the loser). Without $/cancelRequest the server
- # keeps computing it and blocks the requests queued behind it. Written without
- # drain: awaiting inside a cancelled task is unreliable.
- self._notify_cancel_nowait(req_id)
- raise
- finally:
- self._pending.pop(req_id, None)
- def _notify_cancel_nowait(self, req_id: int) -> None:
- """Best-effort ``$/cancelRequest``; a late answer to ``req_id`` is dropped by
- ``_dispatch_response`` because the id is no longer pending."""
- # LSP allows no notification but ``exit`` after ``shutdown``, and none before InitializeResult.
- if self._stopping or self._state != "running":
- return
- if self._proc is None or self._proc.stdin is None or self._proc.stdin.is_closing():
- return
- try:
- self._proc.stdin.write(encode_message(make_notification("$/cancelRequest", {"id": req_id})))
- except _WRITE_ERRORS:
- pass
- async def _send_request_with_retry(self, method: str, params: Any, *, timeout: float) -> Any:
- """Send a request, retrying ``ContentModified`` (-32801) with backoff; other errors propagate."""
- for attempt in range(MAX_CONTENT_MODIFIED_RETRIES + 1):
- try:
- return await asyncio.wait_for(self._send_request(method, params), timeout=timeout)
- except LSPRequestError as e:
- if e.code != ERROR_CONTENT_MODIFIED or attempt >= MAX_CONTENT_MODIFIED_RETRIES:
- raise
- await asyncio.sleep(RETRY_BASE_DELAY * (2 ** attempt))
- async def _send_notification(self, method: str, params: Any) -> None:
- self._require_open(method)
- try:
- await self._write(make_notification(method, params))
- except _WRITE_ERRORS as e:
- logger.debug("[%s] notify %s failed: %s", self.server_id, method, e)
- async def _send_reply(self, msg: dict) -> None:
- """Send a response to a server→client request; silently no-ops when the pipe is gone."""
- if self._proc is not None and self._proc.stdin is not None and not self._proc.stdin.is_closing():
- try:
- await self._write(msg)
- except _WRITE_ERRORS:
- pass
- def _dispatch_response(self, req_id: int, msg: dict) -> None:
- fut = self._pending.get(req_id)
- if fut is None or fut.done():
- return
- if "error" not in msg:
- fut.set_result(msg.get("result"))
- return
- err = msg["error"] or {}
- fut.set_exception(LSPRequestError(int(err.get("code", -32000)), str(err.get("message", "unknown")), err.get("data")))
- async def _dispatch_request(self, req_id: Any, msg: dict) -> None:
- method = msg.get("method", "")
- handler = self._request_handlers.get(method)
- if handler is None:
- reply = make_error_response(req_id, ERROR_METHOD_NOT_FOUND, f"method not found: {method}")
- else:
- try:
- reply = make_response(req_id, await handler(msg.get("params")))
- except Exception as e:
- logger.warning("[%s] request handler %s failed: %s", self.server_id, method, e)
- reply = make_error_response(req_id, -32000, f"handler failed: {e}")
- await self._send_reply(reply)
- def _dispatch_notification(self, method: str, msg: dict) -> None:
- handler = self._notification_handlers.get(method)
- if handler is None:
- return
- try:
- handler(msg.get("params"))
- except Exception as e:
- logger.debug("[%s] notification handler %s failed: %s", self.server_id, method, e)
- # ---- built-in server-→-client request handlers ----
- async def _handle_null(self, params: Any) -> Any:
- return None
- async def _handle_workspace_folders(self, params: Any) -> Any:
- return self._workspace_folders()
- async def _handle_workspace_configuration(self, params: Any) -> Any:
- """Walk dotted ``section`` paths through initializationOptions; null when missing."""
- if not isinstance(params, dict):
- return [None]
- return [self._config_section(item) for item in params.get("items") or []]
- def _config_section(self, item: Any) -> Any:
- if not isinstance(item, dict):
- return None
- section = item.get("section")
- if not section or not self._init_options:
- return self._init_options or None
- cur: Any = self._init_options
- for part in str(section).split("."):
- if not (isinstance(cur, dict) and part in cur):
- return None
- cur = cur[part]
- return cur
- def _handle_publish_diagnostics(self, params: Any) -> None:
- if not isinstance(params, dict) or not isinstance(params.get("uri"), str):
- return
- diagnostics = params.get("diagnostics") or []
- version = params.get("version")
- doc = self._docs.setdefault(uri_to_path(params["uri"]), _DocState(version=-1))
- is_seed = self._seed_first_push and not doc.seed_seen
- doc.seed_seen = True
- doc.push = diagnostics if isinstance(diagnostics, list) else []
- if is_seed:
- # First push is baseline data only: it predates any didChange we sent,
- # so it's stored WITHOUT a freshness tag and never satisfies a waiter.
- return
- # Tag with the echoed version when provided; otherwise credit the current
- # version (a push observed after our change describes it or newer). doc.version
- # is -1 for never-opened paths (relatedDocuments spillover), keeping them unfresh.
- doc.push_version = version if isinstance(version, int) else doc.version
- # Keep the Event sticky-set so in-progress waits resolve; waiters
- # compare ``_push_counter`` to detect a genuinely new push.
- self._push_counter += 1
- self._push_event.set()
- # ---- public file-sync API ----
- async def open_file(self, path: str, *, language_id: str = "plaintext", text: Optional[str] = None) -> int:
- """Send didOpen (first time) or didChange (subsequent); return the new document version.
- ``text`` is the document content to sync (default: the file on disk) — the deferred write check
- syncs the exact pre-/post-edit snapshots of the edit it checks, whatever the disk holds by then.
- A supplied text is normalized as the disk read would decode it (BOM, newlines, undecodable bytes),
- so a snapshot and the file it was written to sync identically."""
- if not self.is_running:
- raise LSPProtocolError("client not running")
- abs_path = os.path.abspath(path)
- if text is None:
- try:
- text = Path(abs_path).read_text(encoding="utf-8-sig", errors="replace")
- except OSError as e:
- raise LSPProtocolError(f"cannot read {abs_path}: {e}") from e
- else:
- text = as_disk_read(text)
- uri = file_uri(abs_path)
- doc = self._docs.get(abs_path)
- if doc is not None and doc.version < 0:
- doc = None # never opened (relatedDocuments spillover): treat as new
- # FileChangeType: 1 = CREATED, 2 = CHANGED.
- await self._send_notification(
- "workspace/didChangeWatchedFiles", {"changes": [{"uri": uri, "type": 1 if doc is None else 2}]}
- )
- if doc is None:
- # Fresh state: anything a pre-open push stashed under this path (relatedDocuments spillover) is discarded.
- self._docs.pop(abs_path, None)
- self._docs[abs_path] = _DocState(version=0, text=text)
- await self._send_notification(
- "textDocument/didOpen",
- {"textDocument": {"uri": uri, "languageId": language_id, "version": 0, "text": text}},
- )
- await self._evict_lru_docs()
- return 0
- # pop + reinsert refreshes LRU recency (dicts are insertion-ordered).
- self._docs[abs_path] = self._docs.pop(abs_path)
- change: dict[str, Any] = {"text": text}
- if self._sync_kind == 2:
- change["range"] = {"start": {"line": 0, "character": 0}, "end": _end_position(doc.text)}
- new_version = doc.version + 1
- # Bumping the version is the whole invalidation story (see _DocState). It happens
- # BEFORE the send: the write awaits, and a versionless publishDiagnostics read during
- # that await is credited with doc.version -- tagged with the old number it would be
- # judged stale the moment the send resumes. A failed send is swallowed by
- # _send_notification, leaving a version nothing ever satisfies (= "no verdict").
- doc.version, doc.text = new_version, text
- await self._send_notification(
- "textDocument/didChange",
- {"textDocument": {"uri": uri, "version": new_version}, "contentChanges": [change]},
- )
- return new_version
- async def _evict_lru_docs(self) -> None:
- """Drop least-recently-touched documents beyond MAX_TRACKED_FILES; didClose the ones the server
- has open so it releases its mirror too (version -1 entries were never opened)."""
- while len(self._docs) > MAX_TRACKED_FILES:
- old_path, old = next(iter(self._docs.items()))
- del self._docs[old_path]
- if old.version >= 0:
- await self._send_notification("textDocument/didClose", {"textDocument": {"uri": file_uri(old_path)}})
- async def save_file(self, path: str) -> None:
- """Send didSave for ``path``. Some linters re-scan only on save."""
- if self.is_running:
- await self._send_notification(
- "textDocument/didSave", {"textDocument": {"uri": file_uri(os.path.abspath(path))}}
- )
- # ---- diagnostics: pull + wait ----
- async def _pull_document_diagnostics(self, path: str) -> None:
- """Send ``textDocument/diagnostic`` for one file into the pull store. Results are tagged with the
- version captured at send time, so a didChange racing past the request makes them stale
- automatically. Silently no-ops on errors (server may not support pull)."""
- abs_path = os.path.abspath(path)
- doc = self._docs.get(abs_path)
- sent_version = doc.version if doc else -1
- try:
- result = await self._send_request_with_retry(
- "textDocument/diagnostic", {"textDocument": {"uri": file_uri(abs_path)}},
- timeout=DIAGNOSTICS_REQUEST_TIMEOUT,
- )
- except (TimeoutError, LSPRequestError, LSPProtocolError) as e:
- if isinstance(e, LSPRequestError) and e.code == ERROR_METHOD_NOT_FOUND:
- self._pull_supported = False
- logger.debug("[%s] document diagnostic pull failed: %s", self.server_id, e)
- return
- if not isinstance(result, dict):
- return
- related = result.get("relatedDocuments")
- reports = [(abs_path, result, sent_version)]
- if isinstance(related, dict):
- # Related docs get the same send-anchored tagging: fresh only if unchanged since.
- reports += [(uri_to_path(uri), sub, None) for uri, sub in related.items()]
- for doc_path, report, tag in reports:
- items = report.get("items") if isinstance(report, dict) else None
- if isinstance(items, list):
- d = self._docs.setdefault(doc_path, _DocState(version=-1))
- d.pull = items
- d.pull_version = d.version if tag is None else tag
- async def wait_for_diagnostics(self, path: str, version: int, *, mode: str = "document",
- timeout: Optional[float] = None) -> bool:
- """Wait for fresh diagnostics for ``path`` at ``version``; True iff fresh data arrived in budget.
- ``mode`` is ``"document"`` (5s) or ``"full"`` (10s); ``timeout`` overrides the budget (how
- ``lsp.wait_timeout`` reaches the loop). Callers must treat False as "no data", NOT "no errors" —
- the stores may still hold stale entries. Never throws for servers lacking pull support.
- """
- if not (timeout is not None and timeout > 0):
- timeout = DIAGNOSTICS_FULL_WAIT if mode == "full" else DIAGNOSTICS_DOCUMENT_WAIT
- now = asyncio.get_event_loop().time
- deadline = now() + timeout
- abs_path = os.path.abspath(path)
- # Document pull + push wait run concurrently. A pull that settles without a fresh verdict
- # (push-only servers such as typescript-language-server reject it at once) is NOT re-sent:
- # re-sending it spun this loop hundreds of thousands of times per wait. The push wait alone
- # then runs to the deadline.
- pull = asyncio.create_task(self._pull_document_diagnostics(abs_path)) if self._pull_supported else None
- push = asyncio.create_task(self._wait_for_fresh_push(abs_path, version, timeout))
- try:
- while True:
- if not self._connection_is_open():
- raise LSPProtocolError("server connection closed while waiting for diagnostics")
- doc = self._docs.get(abs_path)
- if doc and doc.fresh(version):
- return True
- remaining = deadline - now()
- live = {t for t in (pull, push) if t is not None and not t.done()}
- if remaining <= 0 or not live:
- return False
- await asyncio.wait(live, timeout=remaining, return_when=asyncio.FIRST_COMPLETED)
- finally:
- pending = [t for t in (pull, push) if t is not None and not t.done()]
- for t in pending:
- t.cancel()
- await asyncio.gather(*pending, return_exceptions=True)
- async def _await_push(self, timeout: float) -> bool:
- """Block until the next publishDiagnostics or ``timeout``; True iff a push woke us."""
- self._push_event.clear()
- try:
- await asyncio.wait_for(self._push_event.wait(), timeout=timeout)
- except TimeoutError:
- return False
- return True
- async def _wait_for_fresh_push(self, path: str, version: int, timeout: float) -> None:
- """Wait until a fresh publishDiagnostics arrives for ``path`` at ``version``+."""
- now = asyncio.get_event_loop().time
- deadline = now() + timeout
- baseline = self._push_counter
- while True:
- doc = self._docs.get(path)
- if doc and doc.fresh_push(version):
- # Debounce: TS often emits in pairs. Snapshot the counter so
- # we wake on a *new* push, not the one that just satisfied us.
- debounce_baseline = self._push_counter
- debounce_deadline = now() + PUSH_DEBOUNCE
- while self._push_counter == debounce_baseline:
- remaining = debounce_deadline - now()
- if remaining <= 0 or not await self._await_push(remaining):
- break
- return
- remaining = deadline - now()
- if remaining <= 0:
- return
- if self._push_counter > baseline:
- # New push but predicate still false — re-check without waiting.
- baseline = self._push_counter
- continue
- await self._await_push(min(remaining, 0.5))
- async def wait_for_seed(self, path: str, timeout: float) -> Optional[list[dict[str, Any]]]:
- """For a server whose first push per document is a seed (never fresh): wait up to ``timeout``
- for that push and return what it carried (the verdict on the text sent with didOpen), or None.
- ``path`` must be absolute (the key ``open_file`` stored it under)."""
- abs_path = path
- now = asyncio.get_running_loop().time
- deadline = now() + timeout
- while True:
- doc = self._docs.get(abs_path)
- if doc is not None and doc.seed_seen:
- return list(doc.push)
- remaining = deadline - now()
- if remaining <= 0 or not self._connection_is_open():
- return None
- await self._await_push(min(remaining, 0.5))
- @property
- def seeds_first_push(self) -> bool:
- return self._seed_first_push
- def document_text(self, path: str) -> Optional[str]:
- """The text last synced to the server for ``path`` (None when never opened)."""
- doc = self._docs.get(os.path.abspath(path))
- return doc.text if doc is not None and doc.version >= 0 else None
- def diagnostics_for(self, path: str, *, fresh_only: bool = False) -> list[dict[str, Any]]:
- """Merged + deduped push/pull diagnostics for one file. With ``fresh_only=True`` a store only
- contributes once its version tag has caught up to the document's — report paths must use this
- so "stale" and "clean" aren't conflated."""
- doc = self._docs.get(os.path.abspath(path))
- if doc is None:
- return []
- push = doc.push if not fresh_only or doc.fresh_push() else []
- pull = doc.pull if not fresh_only or doc.fresh_pull() else []
- return _dedupe(push, pull)
- def _dedupe(*lists: list[dict[str, Any]]) -> list[dict[str, Any]]:
- seen: set[str] = set()
- out: list[dict[str, Any]] = []
- for d in (d for lst in lists for d in lst if isinstance(d, dict)):
- if (key := _diagnostic_key(d)) not in seen:
- seen.add(key)
- out.append(d)
- return out
- def _diagnostic_key(d: dict[str, Any]) -> str:
- """Content-equality key: severity + code + source + message + range. Shared with the manager's
- cross-edit delta filter (``_diag_key``) so both layers agree on identity. Range is included so an
- identical error at a second site still surfaces as new (the manager line-shifts its baseline first)."""
- rng = d.get("range") or {}
- start = rng.get("start") or {}
- end = rng.get("end") or {}
- code = d.get("code")
- return "\x00".join([
- str(d.get("severity") or 1), "" if code is None else str(code), str(d.get("source") or ""),
- str(d.get("message") or "").strip(),
- f"{start.get('line', 0)}:{start.get('character', 0)}-{end.get('line', 0)}:{end.get('character', 0)}",
- ])
- __all__ = ["DIAGNOSTICS_DOCUMENT_WAIT", "DIAGNOSTICS_FULL_WAIT", "INITIALIZE_TIMEOUT", "LSPClient", "file_uri", "uri_to_path"]
|