Document an overview of action names and how they're used in the transport layer

[DaveCTurner]

As noted at #100162 (comment) we don't really have any great overview docs about how transport actions are registered and used.

The Javadocs for org.elasticsearch.transport.TransportHandshaker describe the message format of transport handshakes which are pretty similar to regular transport message but we should have something similar about regular transport messages too. The key point there is that the action name is included (in plain ASCII) in the header (see org.elasticsearch.transport.Header) and we use that string to pick the handler from the map of registered handlers:

elasticsearch/server/src/main/java/org/elasticsearch/transport/InboundHandler.java

Lines 229 to 231 in 6caf9c1

	final String action = header.getActionName();
	final long requestId = header.getRequestId();
	final RequestHandlerRegistry<T> reg = requestHandlers.getHandler(action);

[elasticsearchmachine]

Pinging @elastic/es-distributed (Team:Distributed)

[DiannaHohensee]

IIUC, each TransportAction has a actionName, like this, and these paths/names/commands are registered someplace via the TransportService (?). Then when a node receives a transport layer request, either from another cluster node or internally, the actionName is looked up in some map that will cause the appropriate TransportAction to be invoked? I'm guessing the Handler naming convention is in reference to Netty and ChannelHandler extensions/implementations?

Not necessary to answer this now, but maybe this will give whomever picks this task up an additional clue as to what would be helpful to document.

[DaveCTurner]

these paths/names/commands are registered someplace

Specifically they're held in org.elasticsearch.transport.Transport.RequestHandlers#requestHandlers

[JeremyDahlgren]

A note for the assignee -- take a look at the recently updated REST and Transport Layers documentation added in #126377. Determine if this documentation is sufficient or if there are any details that could be added.

[elasticsearchmachine]

Pinging @elastic/es-distributed-obsolete (Team:Distributed (Obsolete))

[elasticsearchmachine]

Pinging @elastic/es-distributed-coordination (Team:Distributed Coordination)

[zhubotang-wq]

The REST and Transport Layers is very comprehensive and adequate in explaining the organization and characteristics of TransportActions. It does cover the following

• The namedWriteableRegistry populated by actionModule#setActions is indeed being used by inboundHandler to route request to TransportActions.
• Rest*Actions can occasionally map to TransportActions (in case of cluster administration). However, in most cases TranportActions are not invokable from transport layer.

However, the document didn't mention care needs to taken to ensure TransportActions should not run on network IO thread.

[DaveCTurner]

However, the document didn't mention care needs to taken to ensure TransportActions should #100162 (comment) run on network IO thread.

That's a good point, we should add some more detail about the threading model for both REST and Transport actions (for REST actions it's simple but for Transport actions it's more involved). Are you volunteering to write that up?

Also I think we should consider adding a little more information about the strings used to identify transport actions. They're not just opaque strings, they have some structure that is meaningful to the security layers (mainly just prefix-matching, see e.g. org.elasticsearch.xpack.core.security.authz.privilege.IndexPrivilege and org.elasticsearch.xpack.core.security.authz.privilege.ClusterPrivilegeResolver).

(reopening this as I think there's still a couple of things to do here)