Connecting to Aeron Archive
A User Application needs to connect to Aeron Archive before it can send any Control Request messages to it. Connecting creates a Control Session. Connecting supports authentication, but a no-op authentication provider is used by default.
In the diagram below, some of the details of Aeron Transport have been simplified for clarity. Also, references to 'Channels' below should really be 'Channel and StreamId's, but again, it's easier to refer to them as Channels.
Use the tabs above to step through the animation.
When Aeron Archive starts, the ArchiveConductor subscribes to two Control Channels, which are used to receive Control Request messages from User Applications. They are identical apart from the communications media - one is accessed locally over IPC, the other over UDP. The UDP control channel can be disabled if not required. Configuring the channels is described below.
When a User Application wants to communicate with Aeron Archive, it starts by creating a Subscription to a Channel and StreamId, which it will tell Aeron Archive to use for returning responses to it. The Archive Client refers to this as the Control Response Channel. If the application is on a different machine to the Archive, this will need to be a UDP channel.
The Archive Client contains a configuration property called the Control Request Channel. The User Application
needs to configure this with one of the Control Channels that the Archive is listening on. This is configured
using System properties or method calls on an AeronArchive.Context object. Let's say it's running on the same
machine, so it configures Control Request Channel to be the Local Control Channel (IPC).
The User Application calls AeronArchive.connect(). This starts by creating a Publication to the Control Request
Channel (which is configured to be the Local Control Channel on Aeron Archive). Given that this is an IPC channel,
when the Publication is created in the Media Driver, it would immediately 'connect' to the Subscription. When
this happens, the Media Driver would send an ImageReady message to the ArchiveConductor, which would cause it to
call an
AvailableImageHandler.
When the AvailableImageHandler is called in the ArchiveConductor, it creates a
ControlSessionDemuxer
for the Image, and adds the demuxer to a list of Sessions. Part of the ArchiveConductor's duty cycle is to call
doWork() on each Session, and the ControlSessionDemuxer's doWork() method is what polls the Image to process
Control Request messages.
Back in the User Application, after AeronArchive.connect() has created the Publication to the Control Request
Channel, it sends an AuthConnectRequest message. The message contains the Control Response Channel URI and
StreamId, so the Archive knows where to return responses to.
When the ControlSessionDemuxer polls the Image for the Control Request Channel, it finds the AuthConnectRequest message. It kicks off the async creation of an ExclusivePublication back to the Control Response Channel. Then it creates a ControlSession, assigns it a controlSessionId and gives it the id of the ExclusivePublication. The ControlSession is added to the list of Sessions in the ArchiveConductor.
The ControlSession contains a state machine that will be in the state of waiting for the ExclusivePublication to be created. Once created, it waits for it to be connected. Once connected, it sends a ControlResponse message on it, which contains the controlSessionId (if authentication was configured, it could send a challenge request back to the client at this point). The User Application is now 'connected' to Aeron Archive and can send Control Request messages.
Configuring the Archive Control Channels
On Aeron Archive, Control Channel is the UDP channel, which needs configuring if enabled (default values below):
aeron.archive.control.channel.enabled=true
aeron.archive.control.channel=
aeron.archive.control.stream.id=10
Local Control Channel is the IPC channel:
aeron.archive.local.control.channel=aeron:ipc
aeron.archive.local.control.stream.id=10
Control Messages
Once a User Application is connected to Aeron Archive, it can send Control Requests to it on the Control Request Channel. Every message sent to the Archive contains the controlSessionId, which identifies the ControlSession. The ControlSession contains the Publication for sending response messages back to the application's Control Response Channel.
The full list of request and response messages is defined here: