Skip to content

Ingress Messages

Clustered Service Consensus Module Archive log Clustered Service Consensus Module Archive log Client B Client A Network cnc.dat cnc.dat cnc.dat cnc.dat cons-module service control-response control-request control-response control-request cons-module service consensus0-1 consensus2-1 consensus1-0 consensus1-2 consensus1-0 consensus2-0 consensus0-1 consensus0-2 log log egressB ingressB egressA ingressA ingressB ingressA egressA egressB Conductor Receiver Sender Conductor Receiver Sender Receiver Conductor Sender Receiver Conductor Sender StreamId: 102 StreamId: 104 StreamId: 105 StreamId: 100 StreamId: 108 StreamId: 101 LEADER FOLLOWER

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

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.