From 5ea59f5bfa77efa1773c5f63a6618568f522ecaa Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Tue, 27 Oct 2026 22:11:36 +0800
Subject: [PATCH] docs(jsonrpc): Notification handlers must not wait for the
 remote side

Claude-Session: https://claude.ai/code/session_01VUYsdXA2nkF5v6zsC93dpn
---
 crates/ide-jsonrpc/src/lib.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/crates/ide-jsonrpc/src/lib.rs b/crates/ide-jsonrpc/src/lib.rs
index 0d628656..78c5d444 100644
--- a/crates/ide-jsonrpc/src/lib.rs
+++ b/crates/ide-jsonrpc/src/lib.rs
@@ -203,7 +203,9 @@ pub mod codes {
 /// Calls run on blocking-capable threads, never on the reader task, so a slow
 /// handler cannot stall response delivery. Notifications are delivered one at
 /// a time in arrival order; requests run concurrently, each once every
-/// notification that arrived before it has been handled.
+/// notification that arrived before it has been handled. So `on_notification`
+/// must not wait for the remote side (a response to our request may depend on
+/// its request to us, which would then never start); hand such work to a task.
 pub trait Handler: Send + Sync + 'static {
     fn on_notification(&self, method: &str, params: Value);
     /// Respond to a server→client request (e.g. `workspace/configuration`).