client.py 43 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862
  1. """Async LSP client over stdin/stdout — one per ``(server, workspace_root)``.
  2. Freshness is tracked with **document versions**, not timestamps: every didChange
  3. bumps ``version`` and each stored push/pull result is tagged with the version it
  4. describes, so a slow server's leftovers never masquerade as a verdict on the
  5. current content ("ghost diagnostics"). Whole-document sync is always sent, every
  6. ``open_file`` also fires ``didChangeWatchedFiles`` (clangd/eslint only re-scan on
  7. it), and ``ContentModified`` (-32801) errors are retried with exponential backoff.
  8. """
  9. from __future__ import annotations
  10. import asyncio
  11. import contextlib
  12. import logging
  13. import os
  14. import sys
  15. from dataclasses import dataclass, field
  16. from pathlib import Path
  17. from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
  18. from urllib.parse import quote, unquote
  19. from hermes_cli._subprocess_compat import windows_hide_flags
  20. from hermes_cli.process_identity import own_process_groups, register_child, release_process_group_once_empty
  21. from agent.lsp.protocol import (
  22. ERROR_CONTENT_MODIFIED, ERROR_METHOD_NOT_FOUND, LSPProtocolError, LSPRequestError, classify_message,
  23. encode_message, make_error_response, make_notification, make_request, make_response, read_message,
  24. )
  25. logger = logging.getLogger("agent.lsp.client")
  26. # asyncio's 64 KiB StreamReader default makes readline() raise on one long LSP
  27. # stderr line (#31417); 16 MiB covers realistic output while staying bounded.
  28. _STREAM_LIMIT = 16 * 1024 * 1024
  29. # Timeouts (seconds).
  30. INITIALIZE_TIMEOUT = 45.0
  31. DIAGNOSTICS_DOCUMENT_WAIT = 5.0
  32. DIAGNOSTICS_FULL_WAIT = 10.0
  33. DIAGNOSTICS_REQUEST_TIMEOUT = 3.0
  34. PUSH_DEBOUNCE = 0.15
  35. SHUTDOWN_GRACE = 1.0 # seconds after `exit` before SIGTERM, and between SIGTERM and SIGKILL
  36. # Retry policy for transient ContentModified errors: 0.5, 1.0, 2.0s.
  37. MAX_CONTENT_MODIFIED_RETRIES = 3
  38. RETRY_BASE_DELAY = 0.5
  39. # Last server stderr lines kept for failure reports; the V8 heap-abort trace that explains a
  40. # tsserver SIGABRT is otherwise only visible at DEBUG, so the WARNING a user actually reads
  41. # cannot distinguish "binary missing" from "server ran out of memory".
  42. STDERR_TAIL_LINES = 30
  43. # Cap on tracked documents: each _DocState pins the file's full text here AND the server mirrors
  44. # every open document, so an uncapped dict pins everything a long session ever touched on both
  45. # sides of the pipe until the idle reaper kills the whole client (#62950). 64 covers an active
  46. # edit loop's working set; evicted files are didClose'd and re-didOpen'ed on their next touch.
  47. MAX_TRACKED_FILES = 64
  48. _WRITE_ERRORS = (BrokenPipeError, ConnectionResetError, OSError)
  49. _LIVE_STATES = {"starting", "running"}
  50. _CLIENT_CAPABILITIES: dict[str, Any] = {
  51. "window": {"workDoneProgress": True},
  52. "workspace": {"configuration": True, "workspaceFolders": True,
  53. "didChangeWatchedFiles": {"dynamicRegistration": True}, "diagnostics": {"refreshSupport": False}},
  54. "textDocument": {
  55. "synchronization": {"dynamicRegistration": False, "didOpen": True, "didChange": True,
  56. "didSave": True, "willSave": False, "willSaveWaitUntil": False},
  57. "diagnostic": {"dynamicRegistration": True, "relatedDocumentSupport": True},
  58. "publishDiagnostics": {"relatedInformation": True, "tagSupport": {"valueSet": [1, 2]},
  59. "versionSupport": True, "codeDescriptionSupport": True, "dataSupport": False},
  60. "hover": {"contentFormat": ["markdown", "plaintext"]},
  61. "definition": {"linkSupport": True},
  62. "references": {},
  63. "documentSymbol": {"hierarchicalDocumentSymbolSupport": True},
  64. },
  65. "general": {"positionEncodings": ["utf-16"]},
  66. }
  67. def file_uri(path: str) -> str:
  68. """Return a ``file://`` URI for a path (handles spaces, unicode, Windows drive letters)."""
  69. abs_path = os.path.abspath(path)
  70. if os.name == "nt":
  71. # ``C:\foo`` → ``file:///C:/foo``: the drive letter must be a path component.
  72. abs_path = abs_path.replace("\\", "/")
  73. abs_path = abs_path if abs_path.startswith("/") else "/" + abs_path
  74. return "file://" + quote(abs_path, safe="/:")
  75. def _folder(root: str) -> dict[str, str]:
  76. """Build an LSP ``WorkspaceFolder`` for ``root``."""
  77. return {"name": os.path.basename(root.rstrip(os.sep)) or root, "uri": file_uri(root)}
  78. def uri_to_path(uri: str) -> str:
  79. """Inverse of :func:`file_uri`."""
  80. if not uri.startswith("file://"):
  81. return uri
  82. raw = uri[len("file://"):]
  83. if os.name == "nt" and raw.startswith("/") and len(raw) > 2 and raw[2] == ":":
  84. raw = raw[1:] # strip leading slash before drive letter
  85. return os.path.normpath(unquote(raw))
  86. def _end_position(text: str) -> dict[str, int]:
  87. """LSP Position at the end of ``text`` (for a whole-document replace range)."""
  88. if not text:
  89. return {"line": 0, "character": 0}
  90. lines = text.splitlines(keepends=False)
  91. # splitlines drops a trailing newline: the end is then the start of the next (empty) line.
  92. if text.endswith(("\n", "\r")):
  93. return {"line": len(lines), "character": 0}
  94. # Positions use UTF-16 code units, matching our advertised positionEncodings.
  95. return {"line": len(lines) - 1, "character": len(lines[-1].encode("utf-16-le")) // 2}
  96. @dataclass
  97. class _DocState:
  98. """Per-document state. ``version`` is the LSP document version last sent (didOpen=0, +1 per
  99. didChange) and doubles as the freshness token: ``push_version`` / ``pull_version`` tag stored
  100. results, fresh iff tag >= version; -1 means "no data yet". Servers that echo a version in
  101. publishDiagnostics get exact tagging; others are credited with the current version at receipt."""
  102. version: int = 0
  103. text: str = ""
  104. push: list[dict[str, Any]] = field(default_factory=list)
  105. pull: list[dict[str, Any]] = field(default_factory=list)
  106. push_version: int = -1
  107. pull_version: int = -1
  108. seed_seen: bool = False
  109. def fresh_push(self, version: Optional[int] = None) -> bool:
  110. return self.push_version >= (self.version if version is None else version)
  111. def fresh_pull(self, version: Optional[int] = None) -> bool:
  112. return self.pull_version >= (self.version if version is None else version)
  113. def fresh(self, version: Optional[int] = None) -> bool:
  114. return self.fresh_push(version) or self.fresh_pull(version)
  115. def as_disk_read(text: str) -> str:
  116. """``text`` as ``Path.read_text(encoding="utf-8-sig", errors="replace")`` returns the file holding it."""
  117. try:
  118. text = text.encode("utf-8", "surrogateescape").decode("utf-8-sig", "replace")
  119. except UnicodeEncodeError: # lone surrogate outside the escape range: keep the text, drop the BOM
  120. text = text.removeprefix("\ufeff")
  121. return text.replace("\r\n", "\n").replace("\r", "\n")
  122. class LSPClient:
  123. """One server process + one workspace root. ``start()`` → ``open_file()`` → ``wait_for_diagnostics()`` →
  124. ``diagnostics_for()`` → ``shutdown()``."""
  125. def __init__(self, *, server_id: str, workspace_root: str, command: list[str],
  126. env: Optional[dict[str, str]] = None, cwd: Optional[str] = None,
  127. initialization_options: Optional[dict[str, Any]] = None,
  128. seed_diagnostics_on_first_push: bool = False) -> None:
  129. self.server_id = server_id
  130. self.workspace_root = workspace_root
  131. # Roots this server serves. Single-root servers only ever hold ``workspace_root``;
  132. # multi-root servers (pyright) grow this via ``add_workspace_folder`` instead of a second process.
  133. self.workspace_folders: list[str] = [workspace_root]
  134. self._command = list(command)
  135. self._env = env
  136. self._cwd = cwd or workspace_root
  137. self._init_options = initialization_options or {}
  138. self._seed_first_push = seed_diagnostics_on_first_push
  139. self._proc: Optional[asyncio.subprocess.Process] = None
  140. self._stderr_task: Optional[asyncio.Task] = None
  141. # Ring buffer of the most recent server stderr lines, surfaced when spawn/initialize fails.
  142. self._stderr_tail: list[str] = []
  143. self._exit_code: Optional[int] = None
  144. self._reader_task: Optional[asyncio.Task] = None
  145. self._cleanup_lock = asyncio.Lock()
  146. self._next_id: int = 0
  147. self._pending: dict[int, asyncio.Future] = {}
  148. # Server → client requests; anything else gets method-not-found. Capability (un)registration
  149. # and diagnostic refresh are acknowledged but not acted on: we re-pull on every touch anyway.
  150. self._request_handlers: dict[str, Callable[[Any], Awaitable[Any]]] = {
  151. "window/workDoneProgress/create": self._handle_null,
  152. "workspace/configuration": self._handle_workspace_configuration,
  153. "client/registerCapability": self._handle_null,
  154. "client/unregisterCapability": self._handle_null,
  155. "workspace/workspaceFolders": self._handle_workspace_folders,
  156. "workspace/diagnostic/refresh": self._handle_null,
  157. }
  158. # Server → client notifications; others (showMessage, $/progress) are dropped.
  159. self._notification_handlers: dict[str, Callable[[Any], None]] = {
  160. "textDocument/publishDiagnostics": self._handle_publish_diagnostics,
  161. }
  162. self._docs: dict[str, _DocState] = {} # keyed by absolute path (NOT URI)
  163. self._state: str = "stopped"
  164. self._sync_kind: int = 1 # 1=Full, 2=Incremental
  165. # Cleared when the server rejects textDocument/diagnostic as unknown: no further pulls.
  166. self._pull_supported: bool = True
  167. self._stopping: bool = False
  168. # Waiters snapshot ``_push_counter`` and treat any increase as "recheck the
  169. # predicate" — avoids the asyncio.Event sticky-state trap.
  170. self._push_event = asyncio.Event()
  171. self._push_counter = 0
  172. @property
  173. def state(self) -> str:
  174. return self._state
  175. @property
  176. def is_running(self) -> bool:
  177. return self._state == "running" and self._connection_is_open()
  178. def _connection_is_open(self) -> bool:
  179. proc, reader = self._proc, self._reader_task
  180. return (
  181. self._state in _LIVE_STATES
  182. and proc is not None and proc.returncode is None
  183. and proc.stdin is not None and not proc.stdin.is_closing()
  184. and reader is not None and not reader.done()
  185. )
  186. # ---- lifecycle ----
  187. async def start(self) -> None:
  188. """Spawn + initialize handshake. On failure the process is killed and state is ``"error"``; re-call to retry."""
  189. if self._state in _LIVE_STATES:
  190. return
  191. self._state = "starting"
  192. try:
  193. await self._spawn()
  194. await self._initialize()
  195. if not self._connection_is_open():
  196. raise LSPProtocolError("server connection closed during initialization")
  197. self._state = "running"
  198. except BaseException as e:
  199. self._state = "error"
  200. # Reap the server now so the failure report can name the exit status (a Node heap
  201. # abort dies on SIGABRT; without this the caller logs an opaque JSON-RPC error).
  202. # The reader loop may have run ``_cleanup_process`` first — it records the code
  203. # too, so both orderings leave ``failure_details`` populated.
  204. proc = self._proc
  205. if proc is not None:
  206. with contextlib.suppress(Exception):
  207. await asyncio.wait_for(proc.wait(), timeout=1.0)
  208. if proc.returncode is not None:
  209. self._exit_code = proc.returncode
  210. stderr_task = self._stderr_task
  211. if stderr_task is not None: # brief window to collect the abort trace
  212. with contextlib.suppress(Exception):
  213. await asyncio.wait_for(asyncio.shield(stderr_task), timeout=0.5)
  214. # ``_BackgroundLoop.run`` cancels this task when its outer budget expires.
  215. # CancelledError is a BaseException on supported Python versions, and cleanup
  216. # must outlive that cancellation or the spawned server escapes all tracking.
  217. await asyncio.shield(self._cleanup_process())
  218. # Attach the details to the ORIGINAL exception rather than re-instantiating its
  219. # type: LSPRequestError's ctor is (code, message, data), so ``type(e)(text)``
  220. # would surface as a TypeError instead of the LSP error the caller logs.
  221. details = self.failure_details()
  222. if details and isinstance(e, Exception):
  223. e.args = (f"{e} ({details})",)
  224. raise
  225. async def _spawn(self) -> None:
  226. from agent.delegation_context import delegated_child_subprocess_env
  227. from tools.environments.local import hermes_subprocess_env
  228. cmd = self._command
  229. if sys.platform == "win32" and cmd[0].lower().endswith((".cmd", ".bat")):
  230. cmd = ["cmd.exe", "/c", *cmd] # CreateProcess can't run .cmd/.bat shims directly
  231. try:
  232. # start_new_session=True gives the server its own process group; otherwise it inherits
  233. # the gateway's pgid and mcp_tool's orphan sweeper can killpg() the TUI parent with it.
  234. # windows_hide_flags() suppresses the console window a .cmd shim would flash from a
  235. # console-less host (CREATE_NO_WINDOW; 0 on POSIX).
  236. # Language servers are third-party binaries a write_file can start: they get the
  237. # scrubbed env (no gateway tokens, no provider keys), plus their own configured env.
  238. self._proc = await asyncio.create_subprocess_exec(
  239. cmd[0], *cmd[1:], limit=_STREAM_LIMIT,
  240. stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
  241. env=delegated_child_subprocess_env({**hermes_subprocess_env(), **(self._env or {})}), cwd=self._cwd,
  242. start_new_session=True, # detached-spawn: ok — the group goes to own_process_groups below
  243. creationflags=windows_hide_flags(),
  244. )
  245. except FileNotFoundError as e:
  246. raise LSPProtocolError(f"LSP server binary not found: {cmd[0]} ({e})") from e
  247. # The server itself exits on stdin EOF when we die, but a descendant that does not hold or
  248. # watch that pipe (a wrapper's background child, a SIGTERM-ignoring worker) outlived a
  249. # SIGKILLed / OOM-killed Hermes forever. The owner-death supervisor kills the whole group
  250. # the moment this process dies, by any cause. No-op on Windows (job object instead).
  251. own_process_groups([self._proc.pid])
  252. # Off the event loop: the ledger write takes a cross-process lock (up to 2 s).
  253. await asyncio.to_thread(register_child, self._proc.pid, "lsp-server")
  254. # stderr must be drained or the pipe buffer fills and the server hangs.
  255. self._stderr_task = asyncio.create_task(self._drain_stderr())
  256. self._reader_task = asyncio.create_task(self._reader_loop())
  257. async def _drain_stderr(self) -> None:
  258. if self._proc is None or self._proc.stderr is None:
  259. return
  260. stderr = self._proc.stderr
  261. try:
  262. while True:
  263. try:
  264. line = await stderr.readline()
  265. except ValueError:
  266. # StreamReader.readline() translates LimitOverrunError to
  267. # ValueError after discarding the oversized buffer. Continue
  268. # draining so a pathological stderr line cannot leave the
  269. # pipe unread and block the server.
  270. logger.warning(
  271. "[%s] stderr: line exceeded stream limit, discarding",
  272. self.server_id,
  273. )
  274. continue
  275. if not line:
  276. break
  277. if text := line.decode("utf-8", errors="replace").rstrip():
  278. logger.debug("[%s] stderr: %s", self.server_id, text[:1000])
  279. self._stderr_tail.append(text[:1000])
  280. del self._stderr_tail[:-STDERR_TAIL_LINES]
  281. except (asyncio.CancelledError, OSError):
  282. pass
  283. def _describe_exit(self) -> str:
  284. """Human rendering of the server exit status; empty when the process is still live."""
  285. proc = self._proc
  286. if self._exit_code is not None:
  287. code = self._exit_code
  288. elif proc is not None and proc.returncode is not None:
  289. code = proc.returncode
  290. else:
  291. return ""
  292. if code < 0:
  293. return f"server exited on signal {-code}"
  294. return f"server exited with code {code}"
  295. def failure_details(self) -> str:
  296. """Exit status + last stderr lines for a failed spawn/initialize; empty for a live server."""
  297. parts: list[str] = []
  298. if exit_desc := self._describe_exit():
  299. parts.append(exit_desc)
  300. if self._stderr_tail:
  301. parts.append("last stderr lines: " + " | ".join(self._stderr_tail))
  302. return "; ".join(parts)
  303. def _dispatch(self, msg: dict) -> None:
  304. kind, key = classify_message(msg)
  305. if kind == "response":
  306. self._dispatch_response(key, msg)
  307. elif kind == "request":
  308. asyncio.create_task(self._dispatch_request(key, msg))
  309. elif kind == "notification":
  310. self._dispatch_notification(key, msg)
  311. else:
  312. logger.warning("[%s] dropping invalid message: %r", self.server_id, msg)
  313. async def _reader_loop(self) -> None:
  314. if self._proc is None or self._proc.stdout is None:
  315. return
  316. try:
  317. while (msg := await read_message(self._proc.stdout)) is not None:
  318. self._dispatch(msg)
  319. logger.debug("[%s] server closed stdout cleanly", self.server_id)
  320. except LSPProtocolError as e:
  321. logger.warning("[%s] protocol error in reader loop: %s", self.server_id, e)
  322. except (asyncio.CancelledError, OSError):
  323. pass
  324. finally:
  325. unexpected_close = not self._stopping and self._state in _LIVE_STATES
  326. if unexpected_close:
  327. self._state = "error"
  328. for fut in list(self._pending.values()): # fail pending requests fast
  329. if not fut.done():
  330. fut.set_exception(LSPProtocolError("server connection closed"))
  331. self._pending.clear()
  332. if unexpected_close:
  333. await self._cleanup_process()
  334. def _workspace_folders(self) -> list[dict[str, str]]:
  335. return [_folder(r) for r in self.workspace_folders]
  336. async def add_workspace_folder(self, root: str) -> None:
  337. """Attach another root to a running multi-root server. Idempotent; the folder is recorded
  338. before the notification is sent so concurrent callers for the same root only announce once."""
  339. if root in self.workspace_folders:
  340. return
  341. self.workspace_folders.append(root)
  342. await self._send_notification(
  343. "workspace/didChangeWorkspaceFolders", {"event": {"added": [_folder(root)], "removed": []}},
  344. )
  345. async def remove_workspace_folder(self, root: str) -> None:
  346. """Detach ``root`` from a running multi-root server (a removed worktree) so the process keeps
  347. serving its sibling roots instead of being torn down with them. Idempotent."""
  348. if root not in self.workspace_folders:
  349. return
  350. self.workspace_folders.remove(root)
  351. await self._send_notification(
  352. "workspace/didChangeWorkspaceFolders", {"event": {"added": [], "removed": [_folder(root)]}},
  353. )
  354. async def _initialize(self) -> None:
  355. params = {
  356. "rootUri": file_uri(self.workspace_root), "rootPath": self.workspace_root, "processId": os.getpid(),
  357. "workspaceFolders": self._workspace_folders(),
  358. "initializationOptions": self._init_options, "capabilities": _CLIENT_CAPABILITIES,
  359. }
  360. result = await asyncio.wait_for(self._send_request("initialize", params), timeout=INITIALIZE_TIMEOUT)
  361. sync = (result.get("capabilities") or {}).get("textDocumentSync")
  362. if isinstance(sync, dict):
  363. sync = sync.get("change")
  364. self._sync_kind = sync if isinstance(sync, int) else 1 # default to Full
  365. await self._send_notification("initialized", {})
  366. if self._init_options: # vtsls/eslint only pick config up via didChangeConfiguration
  367. await self._send_notification("workspace/didChangeConfiguration", {"settings": self._init_options})
  368. async def shutdown(self) -> None:
  369. """Best-effort graceful shutdown: ``shutdown`` + ``exit``, wait ``SHUTDOWN_GRACE`` for the
  370. server to honour ``exit``, then SIGTERM/SIGKILL. Idempotent."""
  371. if self._stopping:
  372. return
  373. self._stopping = True
  374. try:
  375. if self.is_running:
  376. try:
  377. await asyncio.wait_for(self._send_request("shutdown", None), timeout=2.0)
  378. except (TimeoutError, LSPRequestError, LSPProtocolError):
  379. pass
  380. try:
  381. await self._send_notification("exit", None)
  382. except Exception:
  383. pass
  384. # Signalling right after ``exit`` races the server's own exit: needless SIGTERM
  385. # noise for well-behaved servers and, on Darwin, a reaped-and-reused PID target.
  386. if (proc := self._proc) is not None and proc.returncode is None:
  387. with contextlib.suppress(asyncio.TimeoutError):
  388. await asyncio.wait_for(proc.wait(), timeout=SHUTDOWN_GRACE)
  389. finally:
  390. self._state = "stopped"
  391. await self._cleanup_process()
  392. async def _cleanup_process(self) -> None:
  393. async with self._cleanup_lock:
  394. tasks = [self._reader_task, self._stderr_task]
  395. self._reader_task = self._stderr_task = None
  396. proc, self._proc = self._proc, None
  397. live = [t for t in tasks if t is not None and not t.done() and t is not asyncio.current_task()]
  398. for t in live:
  399. t.cancel()
  400. await asyncio.gather(*live, return_exceptions=True)
  401. if proc is None:
  402. return
  403. if proc.returncode is not None:
  404. if self._exit_code is None:
  405. self._exit_code = proc.returncode
  406. release_process_group_once_empty(proc.pid, timeout=0)
  407. return
  408. try:
  409. # ``shutdown`` has already given the protocol a grace period. Hard-kill
  410. # the tree while its ancestry is still observable: waiting for the launcher
  411. # after SIGTERM can let an ignoring descendant become reparented and escape.
  412. # Windows maps this to a synchronous taskkill /T /F (up to 15s), so the
  413. # kill runs off the event loop.
  414. from agent.deadline import kill_process_tree
  415. if not await asyncio.to_thread(kill_process_tree, proc.pid):
  416. proc.kill()
  417. with contextlib.suppress(asyncio.TimeoutError):
  418. await asyncio.wait_for(proc.wait(), timeout=SHUTDOWN_GRACE)
  419. except ProcessLookupError:
  420. pass
  421. if self._exit_code is None and proc.returncode is not None:
  422. self._exit_code = proc.returncode
  423. release_process_group_once_empty(proc.pid, timeout=0)
  424. # ---- request / notification plumbing ----
  425. async def _write(self, msg: dict) -> None:
  426. assert self._proc is not None and self._proc.stdin is not None
  427. self._proc.stdin.write(encode_message(msg))
  428. await self._proc.stdin.drain()
  429. def _require_open(self, method: str) -> None:
  430. if not self._connection_is_open():
  431. raise LSPProtocolError(f"cannot send {method!r}: server connection closed")
  432. async def _send_request(self, method: str, params: Any) -> Any:
  433. self._require_open(method)
  434. req_id, self._next_id = self._next_id, self._next_id + 1
  435. fut: asyncio.Future = asyncio.get_running_loop().create_future()
  436. self._pending[req_id] = fut
  437. try:
  438. await self._write(make_request(req_id, method, params))
  439. except _WRITE_ERRORS as e:
  440. self._pending.pop(req_id, None)
  441. raise LSPProtocolError(f"send failed for {method!r}: {e}") from e
  442. try:
  443. return await fut
  444. except asyncio.CancelledError:
  445. # The caller abandoned the request (wait_for timeout, or the pull/push race in
  446. # wait_for_diagnostics cancelling the loser). Without $/cancelRequest the server
  447. # keeps computing it and blocks the requests queued behind it. Written without
  448. # drain: awaiting inside a cancelled task is unreliable.
  449. self._notify_cancel_nowait(req_id)
  450. raise
  451. finally:
  452. self._pending.pop(req_id, None)
  453. def _notify_cancel_nowait(self, req_id: int) -> None:
  454. """Best-effort ``$/cancelRequest``; a late answer to ``req_id`` is dropped by
  455. ``_dispatch_response`` because the id is no longer pending."""
  456. # LSP allows no notification but ``exit`` after ``shutdown``, and none before InitializeResult.
  457. if self._stopping or self._state != "running":
  458. return
  459. if self._proc is None or self._proc.stdin is None or self._proc.stdin.is_closing():
  460. return
  461. try:
  462. self._proc.stdin.write(encode_message(make_notification("$/cancelRequest", {"id": req_id})))
  463. except _WRITE_ERRORS:
  464. pass
  465. async def _send_request_with_retry(self, method: str, params: Any, *, timeout: float) -> Any:
  466. """Send a request, retrying ``ContentModified`` (-32801) with backoff; other errors propagate."""
  467. for attempt in range(MAX_CONTENT_MODIFIED_RETRIES + 1):
  468. try:
  469. return await asyncio.wait_for(self._send_request(method, params), timeout=timeout)
  470. except LSPRequestError as e:
  471. if e.code != ERROR_CONTENT_MODIFIED or attempt >= MAX_CONTENT_MODIFIED_RETRIES:
  472. raise
  473. await asyncio.sleep(RETRY_BASE_DELAY * (2 ** attempt))
  474. async def _send_notification(self, method: str, params: Any) -> None:
  475. self._require_open(method)
  476. try:
  477. await self._write(make_notification(method, params))
  478. except _WRITE_ERRORS as e:
  479. logger.debug("[%s] notify %s failed: %s", self.server_id, method, e)
  480. async def _send_reply(self, msg: dict) -> None:
  481. """Send a response to a server→client request; silently no-ops when the pipe is gone."""
  482. if self._proc is not None and self._proc.stdin is not None and not self._proc.stdin.is_closing():
  483. try:
  484. await self._write(msg)
  485. except _WRITE_ERRORS:
  486. pass
  487. def _dispatch_response(self, req_id: int, msg: dict) -> None:
  488. fut = self._pending.get(req_id)
  489. if fut is None or fut.done():
  490. return
  491. if "error" not in msg:
  492. fut.set_result(msg.get("result"))
  493. return
  494. err = msg["error"] or {}
  495. fut.set_exception(LSPRequestError(int(err.get("code", -32000)), str(err.get("message", "unknown")), err.get("data")))
  496. async def _dispatch_request(self, req_id: Any, msg: dict) -> None:
  497. method = msg.get("method", "")
  498. handler = self._request_handlers.get(method)
  499. if handler is None:
  500. reply = make_error_response(req_id, ERROR_METHOD_NOT_FOUND, f"method not found: {method}")
  501. else:
  502. try:
  503. reply = make_response(req_id, await handler(msg.get("params")))
  504. except Exception as e:
  505. logger.warning("[%s] request handler %s failed: %s", self.server_id, method, e)
  506. reply = make_error_response(req_id, -32000, f"handler failed: {e}")
  507. await self._send_reply(reply)
  508. def _dispatch_notification(self, method: str, msg: dict) -> None:
  509. handler = self._notification_handlers.get(method)
  510. if handler is None:
  511. return
  512. try:
  513. handler(msg.get("params"))
  514. except Exception as e:
  515. logger.debug("[%s] notification handler %s failed: %s", self.server_id, method, e)
  516. # ---- built-in server-→-client request handlers ----
  517. async def _handle_null(self, params: Any) -> Any:
  518. return None
  519. async def _handle_workspace_folders(self, params: Any) -> Any:
  520. return self._workspace_folders()
  521. async def _handle_workspace_configuration(self, params: Any) -> Any:
  522. """Walk dotted ``section`` paths through initializationOptions; null when missing."""
  523. if not isinstance(params, dict):
  524. return [None]
  525. return [self._config_section(item) for item in params.get("items") or []]
  526. def _config_section(self, item: Any) -> Any:
  527. if not isinstance(item, dict):
  528. return None
  529. section = item.get("section")
  530. if not section or not self._init_options:
  531. return self._init_options or None
  532. cur: Any = self._init_options
  533. for part in str(section).split("."):
  534. if not (isinstance(cur, dict) and part in cur):
  535. return None
  536. cur = cur[part]
  537. return cur
  538. def _handle_publish_diagnostics(self, params: Any) -> None:
  539. if not isinstance(params, dict) or not isinstance(params.get("uri"), str):
  540. return
  541. diagnostics = params.get("diagnostics") or []
  542. version = params.get("version")
  543. doc = self._docs.setdefault(uri_to_path(params["uri"]), _DocState(version=-1))
  544. is_seed = self._seed_first_push and not doc.seed_seen
  545. doc.seed_seen = True
  546. doc.push = diagnostics if isinstance(diagnostics, list) else []
  547. if is_seed:
  548. # First push is baseline data only: it predates any didChange we sent,
  549. # so it's stored WITHOUT a freshness tag and never satisfies a waiter.
  550. return
  551. # Tag with the echoed version when provided; otherwise credit the current
  552. # version (a push observed after our change describes it or newer). doc.version
  553. # is -1 for never-opened paths (relatedDocuments spillover), keeping them unfresh.
  554. doc.push_version = version if isinstance(version, int) else doc.version
  555. # Keep the Event sticky-set so in-progress waits resolve; waiters
  556. # compare ``_push_counter`` to detect a genuinely new push.
  557. self._push_counter += 1
  558. self._push_event.set()
  559. # ---- public file-sync API ----
  560. async def open_file(self, path: str, *, language_id: str = "plaintext", text: Optional[str] = None) -> int:
  561. """Send didOpen (first time) or didChange (subsequent); return the new document version.
  562. ``text`` is the document content to sync (default: the file on disk) — the deferred write check
  563. syncs the exact pre-/post-edit snapshots of the edit it checks, whatever the disk holds by then.
  564. A supplied text is normalized as the disk read would decode it (BOM, newlines, undecodable bytes),
  565. so a snapshot and the file it was written to sync identically."""
  566. if not self.is_running:
  567. raise LSPProtocolError("client not running")
  568. abs_path = os.path.abspath(path)
  569. if text is None:
  570. try:
  571. text = Path(abs_path).read_text(encoding="utf-8-sig", errors="replace")
  572. except OSError as e:
  573. raise LSPProtocolError(f"cannot read {abs_path}: {e}") from e
  574. else:
  575. text = as_disk_read(text)
  576. uri = file_uri(abs_path)
  577. doc = self._docs.get(abs_path)
  578. if doc is not None and doc.version < 0:
  579. doc = None # never opened (relatedDocuments spillover): treat as new
  580. # FileChangeType: 1 = CREATED, 2 = CHANGED.
  581. await self._send_notification(
  582. "workspace/didChangeWatchedFiles", {"changes": [{"uri": uri, "type": 1 if doc is None else 2}]}
  583. )
  584. if doc is None:
  585. # Fresh state: anything a pre-open push stashed under this path (relatedDocuments spillover) is discarded.
  586. self._docs.pop(abs_path, None)
  587. self._docs[abs_path] = _DocState(version=0, text=text)
  588. await self._send_notification(
  589. "textDocument/didOpen",
  590. {"textDocument": {"uri": uri, "languageId": language_id, "version": 0, "text": text}},
  591. )
  592. await self._evict_lru_docs()
  593. return 0
  594. # pop + reinsert refreshes LRU recency (dicts are insertion-ordered).
  595. self._docs[abs_path] = self._docs.pop(abs_path)
  596. change: dict[str, Any] = {"text": text}
  597. if self._sync_kind == 2:
  598. change["range"] = {"start": {"line": 0, "character": 0}, "end": _end_position(doc.text)}
  599. new_version = doc.version + 1
  600. # Bumping the version is the whole invalidation story (see _DocState). It happens
  601. # BEFORE the send: the write awaits, and a versionless publishDiagnostics read during
  602. # that await is credited with doc.version -- tagged with the old number it would be
  603. # judged stale the moment the send resumes. A failed send is swallowed by
  604. # _send_notification, leaving a version nothing ever satisfies (= "no verdict").
  605. doc.version, doc.text = new_version, text
  606. await self._send_notification(
  607. "textDocument/didChange",
  608. {"textDocument": {"uri": uri, "version": new_version}, "contentChanges": [change]},
  609. )
  610. return new_version
  611. async def _evict_lru_docs(self) -> None:
  612. """Drop least-recently-touched documents beyond MAX_TRACKED_FILES; didClose the ones the server
  613. has open so it releases its mirror too (version -1 entries were never opened)."""
  614. while len(self._docs) > MAX_TRACKED_FILES:
  615. old_path, old = next(iter(self._docs.items()))
  616. del self._docs[old_path]
  617. if old.version >= 0:
  618. await self._send_notification("textDocument/didClose", {"textDocument": {"uri": file_uri(old_path)}})
  619. async def save_file(self, path: str) -> None:
  620. """Send didSave for ``path``. Some linters re-scan only on save."""
  621. if self.is_running:
  622. await self._send_notification(
  623. "textDocument/didSave", {"textDocument": {"uri": file_uri(os.path.abspath(path))}}
  624. )
  625. # ---- diagnostics: pull + wait ----
  626. async def _pull_document_diagnostics(self, path: str) -> None:
  627. """Send ``textDocument/diagnostic`` for one file into the pull store. Results are tagged with the
  628. version captured at send time, so a didChange racing past the request makes them stale
  629. automatically. Silently no-ops on errors (server may not support pull)."""
  630. abs_path = os.path.abspath(path)
  631. doc = self._docs.get(abs_path)
  632. sent_version = doc.version if doc else -1
  633. try:
  634. result = await self._send_request_with_retry(
  635. "textDocument/diagnostic", {"textDocument": {"uri": file_uri(abs_path)}},
  636. timeout=DIAGNOSTICS_REQUEST_TIMEOUT,
  637. )
  638. except (TimeoutError, LSPRequestError, LSPProtocolError) as e:
  639. if isinstance(e, LSPRequestError) and e.code == ERROR_METHOD_NOT_FOUND:
  640. self._pull_supported = False
  641. logger.debug("[%s] document diagnostic pull failed: %s", self.server_id, e)
  642. return
  643. if not isinstance(result, dict):
  644. return
  645. related = result.get("relatedDocuments")
  646. reports = [(abs_path, result, sent_version)]
  647. if isinstance(related, dict):
  648. # Related docs get the same send-anchored tagging: fresh only if unchanged since.
  649. reports += [(uri_to_path(uri), sub, None) for uri, sub in related.items()]
  650. for doc_path, report, tag in reports:
  651. items = report.get("items") if isinstance(report, dict) else None
  652. if isinstance(items, list):
  653. d = self._docs.setdefault(doc_path, _DocState(version=-1))
  654. d.pull = items
  655. d.pull_version = d.version if tag is None else tag
  656. async def wait_for_diagnostics(self, path: str, version: int, *, mode: str = "document",
  657. timeout: Optional[float] = None) -> bool:
  658. """Wait for fresh diagnostics for ``path`` at ``version``; True iff fresh data arrived in budget.
  659. ``mode`` is ``"document"`` (5s) or ``"full"`` (10s); ``timeout`` overrides the budget (how
  660. ``lsp.wait_timeout`` reaches the loop). Callers must treat False as "no data", NOT "no errors" —
  661. the stores may still hold stale entries. Never throws for servers lacking pull support.
  662. """
  663. if not (timeout is not None and timeout > 0):
  664. timeout = DIAGNOSTICS_FULL_WAIT if mode == "full" else DIAGNOSTICS_DOCUMENT_WAIT
  665. now = asyncio.get_event_loop().time
  666. deadline = now() + timeout
  667. abs_path = os.path.abspath(path)
  668. # Document pull + push wait run concurrently. A pull that settles without a fresh verdict
  669. # (push-only servers such as typescript-language-server reject it at once) is NOT re-sent:
  670. # re-sending it spun this loop hundreds of thousands of times per wait. The push wait alone
  671. # then runs to the deadline.
  672. pull = asyncio.create_task(self._pull_document_diagnostics(abs_path)) if self._pull_supported else None
  673. push = asyncio.create_task(self._wait_for_fresh_push(abs_path, version, timeout))
  674. try:
  675. while True:
  676. if not self._connection_is_open():
  677. raise LSPProtocolError("server connection closed while waiting for diagnostics")
  678. doc = self._docs.get(abs_path)
  679. if doc and doc.fresh(version):
  680. return True
  681. remaining = deadline - now()
  682. live = {t for t in (pull, push) if t is not None and not t.done()}
  683. if remaining <= 0 or not live:
  684. return False
  685. await asyncio.wait(live, timeout=remaining, return_when=asyncio.FIRST_COMPLETED)
  686. finally:
  687. pending = [t for t in (pull, push) if t is not None and not t.done()]
  688. for t in pending:
  689. t.cancel()
  690. await asyncio.gather(*pending, return_exceptions=True)
  691. async def _await_push(self, timeout: float) -> bool:
  692. """Block until the next publishDiagnostics or ``timeout``; True iff a push woke us."""
  693. self._push_event.clear()
  694. try:
  695. await asyncio.wait_for(self._push_event.wait(), timeout=timeout)
  696. except TimeoutError:
  697. return False
  698. return True
  699. async def _wait_for_fresh_push(self, path: str, version: int, timeout: float) -> None:
  700. """Wait until a fresh publishDiagnostics arrives for ``path`` at ``version``+."""
  701. now = asyncio.get_event_loop().time
  702. deadline = now() + timeout
  703. baseline = self._push_counter
  704. while True:
  705. doc = self._docs.get(path)
  706. if doc and doc.fresh_push(version):
  707. # Debounce: TS often emits in pairs. Snapshot the counter so
  708. # we wake on a *new* push, not the one that just satisfied us.
  709. debounce_baseline = self._push_counter
  710. debounce_deadline = now() + PUSH_DEBOUNCE
  711. while self._push_counter == debounce_baseline:
  712. remaining = debounce_deadline - now()
  713. if remaining <= 0 or not await self._await_push(remaining):
  714. break
  715. return
  716. remaining = deadline - now()
  717. if remaining <= 0:
  718. return
  719. if self._push_counter > baseline:
  720. # New push but predicate still false — re-check without waiting.
  721. baseline = self._push_counter
  722. continue
  723. await self._await_push(min(remaining, 0.5))
  724. async def wait_for_seed(self, path: str, timeout: float) -> Optional[list[dict[str, Any]]]:
  725. """For a server whose first push per document is a seed (never fresh): wait up to ``timeout``
  726. for that push and return what it carried (the verdict on the text sent with didOpen), or None.
  727. ``path`` must be absolute (the key ``open_file`` stored it under)."""
  728. abs_path = path
  729. now = asyncio.get_running_loop().time
  730. deadline = now() + timeout
  731. while True:
  732. doc = self._docs.get(abs_path)
  733. if doc is not None and doc.seed_seen:
  734. return list(doc.push)
  735. remaining = deadline - now()
  736. if remaining <= 0 or not self._connection_is_open():
  737. return None
  738. await self._await_push(min(remaining, 0.5))
  739. @property
  740. def seeds_first_push(self) -> bool:
  741. return self._seed_first_push
  742. def document_text(self, path: str) -> Optional[str]:
  743. """The text last synced to the server for ``path`` (None when never opened)."""
  744. doc = self._docs.get(os.path.abspath(path))
  745. return doc.text if doc is not None and doc.version >= 0 else None
  746. def diagnostics_for(self, path: str, *, fresh_only: bool = False) -> list[dict[str, Any]]:
  747. """Merged + deduped push/pull diagnostics for one file. With ``fresh_only=True`` a store only
  748. contributes once its version tag has caught up to the document's — report paths must use this
  749. so "stale" and "clean" aren't conflated."""
  750. doc = self._docs.get(os.path.abspath(path))
  751. if doc is None:
  752. return []
  753. push = doc.push if not fresh_only or doc.fresh_push() else []
  754. pull = doc.pull if not fresh_only or doc.fresh_pull() else []
  755. return _dedupe(push, pull)
  756. def _dedupe(*lists: list[dict[str, Any]]) -> list[dict[str, Any]]:
  757. seen: set[str] = set()
  758. out: list[dict[str, Any]] = []
  759. for d in (d for lst in lists for d in lst if isinstance(d, dict)):
  760. if (key := _diagnostic_key(d)) not in seen:
  761. seen.add(key)
  762. out.append(d)
  763. return out
  764. def _diagnostic_key(d: dict[str, Any]) -> str:
  765. """Content-equality key: severity + code + source + message + range. Shared with the manager's
  766. cross-edit delta filter (``_diag_key``) so both layers agree on identity. Range is included so an
  767. identical error at a second site still surfaces as new (the manager line-shifts its baseline first)."""
  768. rng = d.get("range") or {}
  769. start = rng.get("start") or {}
  770. end = rng.get("end") or {}
  771. code = d.get("code")
  772. return "\x00".join([
  773. str(d.get("severity") or 1), "" if code is None else str(code), str(d.get("source") or ""),
  774. str(d.get("message") or "").strip(),
  775. f"{start.get('line', 0)}:{start.get('character', 0)}-{end.get('line', 0)}:{end.get('character', 0)}",
  776. ])
  777. __all__ = ["DIAGNOSTICS_DOCUMENT_WAIT", "DIAGNOSTICS_FULL_WAIT", "INITIALIZE_TIMEOUT", "LSPClient", "file_uri", "uri_to_path"]