Documentation : Rest and Transport Action Threading Model

Author: zhubotang-wq

docs/internal/GeneralArchitectureGuide.md

@@ -42,9 +42,6 @@ were left unconsumed.
 6. The response is written to the `RestChannel`, either as a [single payload][RestToXContentListener] or a
 [stream of chunks][RestChunkedToXContentListener].
 
-A Netty channel eventLoop thread executes step 1 to 3. The [RestChannelConsumer] delegates execution to a task manager thread, which processes
-the request and eventually returns control to the original event loop thread to write the response back to the Netty channel.
-
 ### Request interceptor
 
 The [RestController] accepts a [RestInterceptor] that can intercept [RestRequest]s and add additional pre-handling. A single
@@ -104,6 +101,16 @@ are coordinated.
 > does not hold, in those cases you can locate the transport action for a REST action by looking at the `NodeClient` invocation in the
 > `Rest*Action`'s `prepareRequest` implementation, it should specify the `ActionType` being invoked which can then be used to locate
 > the `Transport*Action` class that handles it.
+>
+> A netty [EventLoop] thread handles the initial steps of a Rest*Action request lifecycle such as decoding, validation and routing.
+> Upon entry into the "transport layer", [NodeClient] delegates the remaining processing to its [TaskManager] thread. The [TaskManager]
+> thread eventually returns control to the original [EventLoop] thread to write the response back to the Netty channel.
+>
+> [TransportAction] can also be initiated through peer-to-peer communication between nodes. In such cases, the [InboundHandler]
+> locates the appropriate [TransportAction] by consulting the [NamedRegistry], then invokes its handleExecution() method. When a [TransportAction]
+> is registered, it can specify an executor to control how the action is run. One option is the DIRECT_EXECUTOR_SERVICE, which executes the
+> action on the calling thread. However, this should be used with caution—it's only appropriate when the action is lightweight.
+> Otherwise, it risks blocking the peer-to-peer I/O thread, potentially degrading responsiveness and causing the node to become unresponsive.
 
 ### Action registration
 Elasticsearch contains many [TransportAction]s, configured statically in [ActionModule#setupActions]. [ActionPlugin]s can
@@ -182,6 +189,10 @@ capabilities.
 [TransportService]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/TransportService.java
 [TransportSingleShardAction]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/action/support/single/shard/TransportSingleShardAction.java
 [Transport]:https://github.com/elastic/elasticsearch/blob/v9.0.1/server/src/main/java/org/elasticsearch/transport/Transport.java
+[EventLoop]:https://github.com/netty/netty/blob/4.2/transport/src/main/java/io/netty/channel/EventLoop.java
+[TaskManager]:https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/tasks/TaskManager.java
+[InboundHandler]:https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/transport/InboundHandler.java
+[NamedRegistry]:https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/common/NamedRegistry.java
 
 ## Serializations