You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/internal/GeneralArchitectureGuide.md
+36Lines changed: 36 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -101,6 +101,24 @@ are coordinated.
101
101
> does not hold, in those cases you can locate the transport action for a REST action by looking at the `NodeClient` invocation in the
102
102
> `Rest*Action`'s `prepareRequest` implementation, it should specify the `ActionType` being invoked which can then be used to locate
103
103
> the `Transport*Action` class that handles it.
104
+
>
105
+
> A netty [EventLoop] thread handles the initial steps of a `Rest*Action` request lifecycle such as decoding, validation and routing.
106
+
> Upon entry into the "transport layer", [NodeClient] delegates the decision of execution to individual `TransportAction`. Each action
107
+
> determines whether to execute synchronously on invoking thread-an approach reserved for lightweight processing-or to dispatch execution to an appropriate
108
+
> thread pool, which is recommended practice for heavy workloads. Comprehensive mechanisms are available for propagating [ThreadContext] when tasks
109
+
> are dispatched to alternate thread pools.
110
+
>
111
+
> `TransportAction` can also be initiated through peer-to-peer communication between nodes. In such cases, the [InboundHandler]
112
+
> locates the appropriate `TransportAction` by consulting the [NamedRegistry], then invokes the `TransportAction`'s handleExecution() method. When a `TransportAction`
113
+
> is registered, it can specify an executor to control how the action is run. One option is the `DIRECT_EXECUTOR_SERVICE`, which executes the
114
+
> action on the calling thread. However, this should be used with caution—it's only appropriate when the action is lightweight.
115
+
> Otherwise, it risks blocking the peer-to-peer I/O thread, potentially degrading responsiveness and causing the node to become unresponsive.
116
+
> If `TransportAction` elects a separate executor, `InboundHandler` performs message deserialization before delegating execution to the executor,
117
+
> refer to [TransportResponseHandler] method executor() for more details.
118
+
>
119
+
> `TransportAction` requests received from remote nodes are always deserialized on the Netty `EventLoop`. In contrast, `TransportAction` responses are
120
+
> deserialized only after being dispatched to the designated executor. Outbound messages, including both requests and responses, are serialized
121
+
> synchronously on the calling thread.
104
122
105
123
### Action registration
106
124
Elasticsearch contains many [TransportAction]s, configured statically in [ActionModule#setupActions]. [ActionPlugin]s can
@@ -115,6 +133,17 @@ The actions themselves sometimes dispatch downstream actions to other nodes in t
115
133
[TransportService#registerRequestHandler]. [HandledTransportAction] is a common parent class that registers an action with the
116
134
`TransportService`.
117
135
136
+
> [!NOTE]
137
+
> `TransportAction``ActionType` naming conventions encode semantic information about the role, scope, plugins, modules and behaviours.
138
+
> [ActionType] instances are mapped to permission privileges via the [ClusterPrivilegeResolver]. Security interceptors enforce access
139
+
> control by invoking RBACEngine.checkPrivileges().
140
+
> Indices-level [ActionType] strings generally follows the pattern: `indices:[data|admin|monitor]/[read|write|get]/[index|bulk|update]`.
141
+
> Cluster-level [ActionType] strings are prefixed by `cluster:` are often followed by a domain-specific such as `autoscaling`, `logstash`, `ingest`,
142
+
> `xpack`.
143
+
> -`internal:` is meant to executed by `_system` user.
144
+
> -`cluster:internal/xpack/..`[ActionType] strings are plugin specific.
145
+
> -`internal:transport/proxy/indices:`[ActionType] strings are automatically wrapped actions when requests for CCR/CCS in proxy mode.
146
+
118
147
> [!NOTE]
119
148
> The name [TransportAction] can be misleading, as it suggests they are all invoke-able and invoked via the TCP transport. In fact,
120
149
> a majority of transport actions are only ever invoked locally via the [NodeClient]. The two key features of a `TransportAction` are:
0 commit comments