fix: bound JDTLS startup waits

Author: TyceHerrman

CHANGELOG.md

@@ -34,6 +34,8 @@ Status of the `main` branch. Changes prior to the next official version change w
   - Allow language server priorities to be configured in `serena_config.yml` (for auto-detection during 
     project creation) 
   - Add `python_basedpyright` as an alternative Python language server
+  - Java/JDTLS: bound required startup waits and report the current phase and latest language status
+    on timeout instead of blocking until an outer task or CI limit is reached #1789
   - Nix/nixd: support custom `ls_path` launchers and external JSON settings through `config_path` #1737
   - Fix: `get_diagnostics_for_file` crashed with `SolidLSPException` for any Ansible file with at least
     one lint finding, because `ansible-language-server` doesn't implement `textDocument/documentSymbol`

docs/02-usage/050_configuration.md

@@ -706,6 +706,7 @@ The following settings are supported for the Java language server:
 | `lombok_show_generated` | `true` | Show Lombok-generated methods (`getX/setX`, `builder()`, `equals/hashCode/toString`, `withX`, fluent accessors) in `find_symbol`, `get_symbols_overview` and the symbol-edit tools. Set to `false` to restore the previous JDTLS default and hide the synthetic methods (e.g. when `@Data` classes pollute the outline with too many getters/setters). Requires JDTLS commit `b2d8952` / `vscode-java >= 1.53.0`; the bundled default already meets this. |
 | `jdtls_xmx` | `3G` | Maximum heap size for the JDTLS server JVM. |
 | `jdtls_xms` | `100m` | Initial heap size for the JDTLS server JVM. |
+| `startup_timeout` | `600` | Maximum seconds to wait for each required JDTLS startup signal. Applied separately to IntelliCode command registration (vscode-java mode only) and `ServiceReady`; on timeout Serena stops JDTLS and reports the current phase and latest language status. |
 | `intellicode_xmx` | `1G` | (vscode-java mode only) Maximum heap size for the IntelliCode embedded JVM. |
 | `intellicode_xms` | `100m` | (vscode-java mode only) Initial heap size for the IntelliCode embedded JVM. |
 

src/solidlsp/language_servers/eclipse_jdtls.py

@@ -6,6 +6,7 @@
 import hashlib
 import json
 import logging
+import math
 import os
 import pathlib
 import platform
@@ -145,6 +146,8 @@ class EclipseJDTLS(SolidLanguageServer):
         - jdtls_xms: Initial heap size for the JDTLS server JVM (default: "100m")
         - intellicode_xmx: Maximum heap size for the IntelliCode embedded JVM (default: "1G")
         - intellicode_xms: Initial heap size for the IntelliCode embedded JVM (default: "100m")
+        - startup_timeout: Maximum seconds to wait for each required JDTLS startup signal
+              (IntelliCode command registration and ServiceReady; default: 600)
         - lombok_show_generated: Show Lombok-generated methods (getX/setX/builder()/...) in document
               symbols by sending java.symbols.includeGeneratedCode=true to JDTLS (default: true).
               Set to false for @Data-heavy projects where the extra getters/setters are noise.
@@ -192,6 +195,7 @@ class EclipseJDTLS(SolidLanguageServer):
         jdtls_xms: "100m"  # initial heap size for the JDTLS server JVM
         intellicode_xmx: "1G"  # maximum heap size for the IntelliCode embedded JVM
         intellicode_xms: "100m"  # initial heap size for the IntelliCode embedded JVM
+        startup_timeout: 600  # maximum wait for each required startup signal
         lombok_show_generated: true  # show Lombok-generated methods in document symbols (default true)
         gradle_version: "8.14.2"
         vscode_java_version: "1.54.0-923"  # also accepts pinned legacy "1.42.0-561"
@@ -203,6 +207,9 @@ class EclipseJDTLS(SolidLanguageServer):
     ```
     """
 
+    STARTUP_TIMEOUT = 600.0
+    STARTUP_SHUTDOWN_TIMEOUT = 5.0
+
     @classmethod
     def supports_implementation_request(cls) -> bool:
         return True
@@ -221,6 +228,60 @@ def __init__(self, config: LanguageServerConfig, repository_root_path: str, soli
         self._service_ready_event = threading.Event()
         self._project_ready_event = threading.Event()
         self._intellicode_enable_command_available = threading.Event()
+        self._startup_phase = "not_started"
+        self._last_language_status: tuple[str | None, str | None] | None = None
+        self._get_startup_timeout()  # validate before a server process can be started
+
+    def _get_startup_timeout(self) -> float:
+        """Return the maximum seconds to wait for each required JDTLS startup signal."""
+        configured_timeout = self._custom_settings.get("startup_timeout", self.STARTUP_TIMEOUT)
+        try:
+            timeout = float(configured_timeout)
+        except (TypeError, ValueError) as exc:
+            raise SolidLSPException("java.startup_timeout must be a positive finite number") from exc
+
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise SolidLSPException("java.startup_timeout must be a positive finite number")
+        return timeout
+
+    def _set_startup_phase(self, phase: str) -> None:
+        self._startup_phase = phase
+        log.info("JDTLS startup phase: %s", phase)
+
+    def _handle_language_status(self, params: dict) -> None:
+        log.info("Language status update: %s", params)
+        status_type = params.get("type")
+        status_message = params.get("message")
+        self._last_language_status = (status_type, status_message)
+
+        if status_type == "ServiceReady" and status_message == "ServiceReady":
+            self._service_ready_event.set()
+        if status_type == "ProjectStatus" and status_message == "OK":
+            self._project_ready_event.set()
+
+    def _describe_last_language_status(self) -> str:
+        if self._last_language_status is None:
+            return "none received"
+        status_type, status_message = self._last_language_status
+        return f"type={status_type!r}, message={status_message!r}"
+
+    def _wait_for_startup_signal(self, event: threading.Event, signal_name: str) -> None:
+        timeout = self._get_startup_timeout()
+        phase = f"waiting_for_{signal_name}"
+        self._set_startup_phase(phase)
+        log.info("Waiting up to %g seconds for JDTLS %s", timeout, signal_name)
+
+        if event.wait(timeout=timeout):
+            self._set_startup_phase(f"{signal_name}_received")
+            return
+
+        message = (
+            f"JDTLS startup timed out after {timeout:g} seconds while waiting for {signal_name} "
+            f"(phase={phase}, last_language_status={self._describe_last_language_status()})"
+        )
+        log.error(message)
+        self.stop(shutdown_timeout=self.STARTUP_SHUTDOWN_TIMEOUT)
+        raise SolidLSPException(message)
 
     def _create_dependency_provider(self) -> LanguageServerDependencyProvider:
         ls_resources_dir = self.ls_resources_dir(self._solidlsp_settings)
@@ -1383,14 +1444,6 @@ def register_capability_handler(params: dict) -> None:
                         self._intellicode_enable_command_available.set()
             return
 
-        def lang_status_handler(params: dict) -> None:
-            log.info("Language status update: %s", params)
-            if params["type"] == "ServiceReady" and params["message"] == "ServiceReady":
-                self._service_ready_event.set()
-            if params["type"] == "ProjectStatus":
-                if params["message"] == "OK":
-                    self._project_ready_event.set()
-
         def execute_client_command_handler(params: dict) -> list:
             assert params["command"] == "_java.reloadBundles.command"
             assert params["arguments"] == []
@@ -1403,18 +1456,18 @@ def do_nothing(params: dict) -> None:
             return
 
         self.server.on_request("client/registerCapability", register_capability_handler)
-        self.server.on_notification("language/status", lang_status_handler)
+        self.server.on_notification("language/status", self._handle_language_status)
         self.server.on_notification("window/logMessage", window_log_message)
         self.server.on_request("workspace/executeClientCommand", execute_client_command_handler)
         self.server.on_notification("$/progress", do_nothing)
         self.server.on_notification("textDocument/publishDiagnostics", do_nothing)
         self.server.on_notification("language/actionableNotification", do_nothing)
 
-        log.info("Starting EclipseJDTLS server process")
+        self._set_startup_phase("starting_process")
         self.server.start()
         initialize_params = self._create_initialize_params()
 
-        log.info("Sending initialize request from LSP client to LSP server and awaiting response")
+        self._set_startup_phase("waiting_for_initialize_response")
         init_response = self.server.send.initialize(initialize_params)
         assert init_response["capabilities"]["textDocumentSync"]["change"] == 2  # type: ignore
         assert "completionProvider" not in init_response["capabilities"]
@@ -1428,7 +1481,10 @@ def do_nothing(params: dict) -> None:
         # IntelliCode bundle is shipped. In upstream-jdtls mode it's absent and the
         # 'java.intellicode.enable' command will never be registered, so we skip the wait/call.
         if self.runtime_dependency_paths.intellicode_jar_path is not None:
-            self._intellicode_enable_command_available.wait()
+            self._wait_for_startup_signal(
+                self._intellicode_enable_command_available,
+                "intellicode_command_registration",
+            )
 
             java_intellisense_members_path = self.runtime_dependency_paths.intellisense_members_path
             assert java_intellisense_members_path is not None
@@ -1440,13 +1496,12 @@ def do_nothing(params: dict) -> None:
                 }
             )
             assert intellicode_enable_result
+            self._set_startup_phase("intellicode_enabled")
 
-        if not self._service_ready_event.is_set():
-            log.info("Waiting for service to be ready ...")
-            self._service_ready_event.wait()
-        log.info("Service is ready")
+        self._wait_for_startup_signal(self._service_ready_event, "service_ready")
 
         if not self._project_ready_event.is_set():
+            self._set_startup_phase("waiting_for_project_status")
             log.info("Waiting for project to be ready ...")
             project_ready_timeout = 20  # Hotfix: Using timeout until we figure out why sometimes we don't get the project ready event
             if self._project_ready_event.wait(timeout=project_ready_timeout):
@@ -1456,7 +1511,7 @@ def do_nothing(params: dict) -> None:
         else:
             log.info("Project is ready")
 
-        log.info("Startup complete")
+        self._set_startup_phase("complete")
 
     @override
     def _request_hover(self, file_buffer: LSPFileBuffer, line: int, column: int) -> ls_types.Hover | None:

test/solidlsp/java/test_jdtls_startup_timeout.py

@@ -0,0 +1,110 @@
+"""Unit tests for bounded Eclipse JDTLS startup waits."""
+
+import threading
+from typing import Any, cast
+
+import pytest
+
+from solidlsp.language_servers.eclipse_jdtls import EclipseJDTLS
+from solidlsp.ls_exceptions import SolidLSPException
+from solidlsp.settings import SolidLSPSettings
+
+
+class _FakeProtocolServer:
+    def __init__(self, stop_error: Exception | None = None) -> None:
+        self.stop_calls: list[float] = []
+        self.stop_error = stop_error
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self.stop_calls.append(timeout)
+        if self.stop_error is not None:
+            raise self.stop_error
+
+
+def _bare_jdtls(
+    custom_settings: dict | None = None,
+    *,
+    stop_error: Exception | None = None,
+) -> tuple[EclipseJDTLS, _FakeProtocolServer]:
+    """Build only the state touched by the startup timeout helpers."""
+    server = object.__new__(EclipseJDTLS)
+    server._custom_settings = SolidLSPSettings.CustomLSSettings(custom_settings)
+    server._service_ready_event = threading.Event()
+    server._project_ready_event = threading.Event()
+    server._intellicode_enable_command_available = threading.Event()
+    server._startup_phase = "not_started"
+    server._last_language_status = None
+    protocol_server = _FakeProtocolServer(stop_error)
+    server.server = cast(Any, protocol_server)
+    server.server_started = True
+    return server, protocol_server
+
+
+def test_startup_timeout_default_and_override() -> None:
+    server, _ = _bare_jdtls()
+    assert server._get_startup_timeout() == 600.0
+
+    server, _ = _bare_jdtls({"startup_timeout": 12.5})
+    assert server._get_startup_timeout() == 12.5
+
+
+@pytest.mark.parametrize("configured_timeout", [0, -1, "invalid", float("inf"), float("nan")])
+def test_startup_timeout_must_be_positive_and_finite(configured_timeout: object) -> None:
+    server, _ = _bare_jdtls({"startup_timeout": configured_timeout})
+
+    with pytest.raises(SolidLSPException, match="positive finite number"):
+        server._get_startup_timeout()
+
+
+def test_language_status_handler_tracks_latest_status_and_sets_events() -> None:
+    server, _ = _bare_jdtls()
+
+    server._handle_language_status({"type": "ProjectStatus", "message": "OK"})
+    assert server._project_ready_event.is_set()
+    assert not server._service_ready_event.is_set()
+    assert server._describe_last_language_status() == "type='ProjectStatus', message='OK'"
+
+    server._handle_language_status({"type": "ServiceReady", "message": "ServiceReady"})
+    assert server._service_ready_event.is_set()
+    assert server._describe_last_language_status() == "type='ServiceReady', message='ServiceReady'"
+
+
+def test_received_startup_signal_does_not_stop_server() -> None:
+    server, protocol_server = _bare_jdtls({"startup_timeout": 1})
+    event = threading.Event()
+    event.set()
+
+    server._wait_for_startup_signal(event, "service_ready")
+
+    assert server._startup_phase == "service_ready_received"
+    assert protocol_server.stop_calls == []
+    assert server.server_started
+
+
+def test_startup_timeout_reports_phase_and_last_status_then_stops_server() -> None:
+    server, protocol_server = _bare_jdtls({"startup_timeout": 0.001})
+    server._handle_language_status({"type": "ProjectStatus", "message": "Starting"})
+
+    with pytest.raises(SolidLSPException) as exc_info:
+        server._wait_for_startup_signal(threading.Event(), "service_ready")
+
+    message = str(exc_info.value)
+    assert "after 0.001 seconds" in message
+    assert "waiting for service_ready" in message
+    assert "phase=waiting_for_service_ready" in message
+    assert "last_language_status=type='ProjectStatus', message='Starting'" in message
+    assert protocol_server.stop_calls == [5.0]
+    assert not server.server_started
+
+
+def test_shutdown_error_does_not_hide_startup_timeout() -> None:
+    server, protocol_server = _bare_jdtls(
+        {"startup_timeout": 0.001},
+        stop_error=RuntimeError("shutdown failed"),
+    )
+
+    with pytest.raises(SolidLSPException, match="waiting for intellicode_command_registration"):
+        server._wait_for_startup_signal(threading.Event(), "intellicode_command_registration")
+
+    assert protocol_server.stop_calls == [5.0]
+    assert not server.server_started