From Kolab Wiki
Image #SSA_0a.jpeg shows an exemplary setup for a single-machine setup without persistent cache using a per-user SQLite in-memory cache within Akonadi. Image #SSA_0b.jpeg shows the next stage with a persistent cache that can handle multi-threading in the Akonadi infrastructure & allows distribution of IMAP & SQL over different machines.
All clients running on the same host allows them to access the Akonadi Control Server (ACS) directly through a local socket where the user id is mapped to an Akonadi Server of which there is one per user regardless of the number of clients connected by the user, so the clients share the cache & connections.
The ACS is responsible for executing an Akonadi Server along with all its agents per user. Afterwards it proxies the client connections through to the local socket with the respective Akonadi Servers. All other communication with the Akonadi Servers and the Agents, as well as between the Akonadi Server and its Agents, is limited to command, control & notification messages sent via dbus. This dbus is shared between all Akonadi components on the host, and is also where Akonadi Agents request their passwords from the Akonadi Control Server.
Because dbus itself is not cryptographically secured, the Akonadi Control Server creates public/private key pairs for itself and each Akonadi component it launches. The private and public key of the child process and the public key of the ACS are handed over during launch, the private key of the child process is then forgotten by the ACS, while the public key is stored for future communication with this particular instance of the agent. All messages to the ACS should at least be signed for verification by the ACS, all messages by the ACS to the child processes, especially passwords and other confidential data, should be encrypted.
In order to be able to provide the IMAP password to the agent, the password is stored encrypted to the key of the ACS itself, all password, key and uid to Akonadi instance mapping databases are exclusively kept in memory.
This requires two modifications in the Agents & Akonadi Server Code:
- Password handling: Currently done through kconfig, which will not be available on server, needs to be made to work with dbus + crypto setup.
- Multi-user setup: dbus communication currently assumes single user situation, so must receive additional instance/session information.
These can be done in ways that a single source code repository can be used to compile server side and client side Akonadi server and agents, but for the Akonadi Control Server the situation is a bit more complex because it needs to do various things that are unnecessary on the desktop, such as:
- Map between different client sessions of a single user and the corresponding Akonadi Server and proxy the payload connection based on the Akonadi Server Access Protocol (ASAP) language based on a socket connection;
- Do the same based on a network connection listening on a network port (see picture #SSA_1a.jpeg). In this scenario, like in all others, the ACS is still proxying the ASAP protocol access to the right Akonadi Server over a local socket;
- Listen and respond on an AMQP message bus for requests to provide the right host & Akonadi Agent for multi-server Akonadi setups (see picture #SSA_2a.jpeg);
- Handle key & password storage;
- Handle termination of Akonadi Servers & Agents after a timeout period.
Naturally, once an AMQP message bus is deployed as part of the setup, it might also be used to have true real-time updates & push based upon notifications from the Cyrus IMAP Daemon (see picture #SSA_2b.jpeg).
On the client side, this complexity is abstracted from the client through the libacsclient, which primarily acts as a brokering library for the clients, written in C++ and wrapped in SWIG for various language bindings. This library is configured to (a) connect to a local socket, (b) connect to a remote port, or (c) request existing/new sessions from an AMQP message bus, depending on the scenario and setup. The client does not need to know which is the setup in place, as it is interfacing only with an API that allows it to request a new session or re-open an existing session, providing it with a command interface that will allow it access to the Akonadi Server regardless of where that server is.
Later this brokering library can also be performance tuned to pull data out of IMAP directly instead of going through Akonadi for some requests, e.g. fetching an email with a large attachment, so it does not have to be pulled through the entire Akonadi stack (see picture #SSA_2c.jpeg).