Ingress Messages¶
Clients interact with the cluster using an AeronCluster client API object. It sends Ingress messages and handles some of the Egress message responses. Ingress messages are sent from the cluster client to a Consensus Module.
Ingress messages need to be sent to the leader cluster member, except for the first message, a SessionConnectRequest. This can be sent to any cluster member, but followers will return a REDIRECT SessionEvent, redirecting the client to the leader, which is how clients discover the leader. Followers ignore all other Ingress messages. It isn't shown on the diagram above, but when a client connects to a follower, it temporarily creates an Ingress log buffer, and an Egress log buffer to send the redirect, then they are torn down.
The AeronCluster
client API sends a SessionConnectRequest to establish a session with the cluster. A
successful response is an OK SessionEvent, which contains a clusterSessionId
. The
AeronCluster object automatically includes this in all subsequent Ingress messages, to identify the session.
Aeron Cluster can be configured to authenticate client connections (see Authentication). If so configured, it can authenticate credentials in the SessionConnectRequest. It can also return a Challenge Egress message, which the client would respond to with a ChallengeResponse.
SessionMessageHeader is used to wrap application level messages. This is for messages sent in to the cluster on the Ingress, or responses from the Clustered Service on the Egress. When sent on the Ingress, they are appended to the Log, before being processed by the Clustered Services, so SessionMessageHeader messages are used in a number of streams.
The Ingress messages are described below.
- SessionMessageHeader
- SessionConnectRequest
- SessionCloseRequest
- SessionKeepAlive
- ChallengeResponse
- AdminRequest
SessionMessageHeader¶
On the Ingress, SessionMessageHeader is used by clients to send application level messages into the cluster, for delivery to the ClusteredServices. SessionMessageHeader is an envelope for the application message - the Consensus Module does not read the contents, and just appends it to the Log.
SessionMessageHeader {
leadershipTermId long // current leadership term
clusterSessionId long // identifies the session
timestamp long // not set on the Ingress (epoch time in cluster time units)
}
leadershipTermId
identifies which leadership term the client thinks is current
(taken from SessionEvent when connecting to the cluster, or a
NewLeaderEvent after an election). If it doesn't match the current leadership term in
the Consensus Module, the message is dropped.
timestamp
is not set by the client when sending this message on the Ingress. When the Consensus Module appends
this message to the Log, it sets timestamp
to the current cluster time (the time the Ingress message was received).
timestamp
is also set by the ClusteredServiceAgent when sending a SessionMessageHeader response on the Egress.
Sent from AeronCluster.offer() and AeronCluster.tryClaim(), which wrap the caller's message with a SessionMessageHeader.
It is received in the Consensus Module by the IngressAdapter.
SessionConnectRequest¶
Sent when a client calls
AeronCluster.connect()
to establish a session with the Cluster. Before sending the message, the AeronCluster client creates a Subscription
for the Egress. The channel and streamId of the client's Egress are passed in the SessionConnectRequest, so the
Cluster can connect back to the client. The response to this is a SessionEvent.
SessionConnectRequest {
correlationId long // to return in the response
responseStreamId int // egress streamId for the cluster to connect back to the client
version int // of the Aeron Cluster Client
responseChannel String // egress channel for the cluster to connect back to the client
encodedCredentials byte[] // if using authentication, otherwise empty
}
It is received in the Consensus Module by the IngressAdapter. Client session handling is described in Consensus Module Clients.
SessionCloseRequest¶
Sent when the client calls AeronCluster.close()
,
either explicitly, or via its AutoCloseable
interface. This cleanly closes the client's session, cleaning up
resources in the Consensus Modules and Clustered Services.
SessionCloseRequest {
leadershipTermId long // current leadership term
clusterSessionId long // identifies the session
}
It is received in the Consensus Module by the IngressAdapter.
SessionKeepAlive¶
Sent from AeronCluster.sendKeepAlive()
,
which the client needs to call once in a while, if not otherwise sending Ingress messages to the cluster. This
stops the session from timing out (aeron.cluster.session.timeout=10s
).
SessionKeepAlive {
leadershipTermId long // current leadership term
clusterSessionId long // identifies the session
}
It is received in the Consensus Module by the IngressAdapter.
ChallengeResponse¶
Sent automatically from within the AeronCluster client object in response to a Challenge, if authentication is configured.
ChallengeResponse {
correlationId long // to be returned in the SessionEvent response
clusterSessionId long // identifies the session
encodedCredentials byte[] // the response data for the challenge
}
It is received in the Consensus Module by the IngressAdapter.
NOTE: ClusterBackupAgent is another cluster client that connects to the Consensus Module and can be challenged, but it communicates using the Consensus streamId (see Challenge and ChallengeResponse).
AdminRequest¶
A generic admin request, which currently only has one request type: snapshot the cluster. This is sent by AeronCluster.sendAdminRequestToTakeASnapshot().
AdminRequest {
leadershipTermId long // current leadership term
clusterSessionId long // identifies the session
correlationId long // to be returned in the response
requestType AdminRequestType // enum with only one value: SNAPSHOT
payload byte[] // optional, empty for SNAPSHOT
}
It is received in the Consensus Module by the IngressAdapter. The response is an AdminResponse.