diff options
Diffstat (limited to 'docs/architecture.md')
| -rw-r--r-- | docs/architecture.md | 58 |
1 files changed, 51 insertions, 7 deletions
diff --git a/docs/architecture.md b/docs/architecture.md index c0186f76c9..3c61dcfba1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,3 +1,6 @@ + + + # Mullvad VPN app architecture This document describes the code architecture and how everything fits together. @@ -15,12 +18,48 @@ My thought was that after this section every aspect of the app is explained under either the Mullvad or the Talpid header. So it's clear which part they belong to. I yet don't know if this makes sense though. +## The daemon +The client consists of two main parts - the daemon and the GUI, but there's also a CLI. The daemon +is the process that's responsible for upholding the security guarantees of the client, it consists +of an actor system so that it can drive many processes asynchronously, allowing for a multiplicity +of clients. + +<img src="diagrams/daemon-components.png"> + +The daemon receives commands from the [front-ends](#frontends) (GUI and CLI) via the management +interface and these are serviced asynchronously via the daemon, often interacting via various other +components during and after the RPC has been finished. There are various dependencies between the +different components and it's important to ensure no deadlocks occur, and some executions flows that +provide essential behavior can be hard to trace. + +<img src="diagrams/update-relay-constraints.png"> + ## Mullvad part of daemon ### Frontend <-> system service communication +This is done via GRPC ([here's](../mullvad-management-interface/proto/management_interface.proto) +the relevant proto file) over a Unix domain socket on desktop platforms and via a JNI on Android. In +both cases, the frontends end up sending a message to the daemon that it then services. The +servicing of any message must never block any other message. Frontends can also subscribe to +messages from the daemon, to receive updates about the tunnel state, new settings, new relay lists, +version information and device events. + -### Talking to api.mullvad.net +### Talking to api.mullvad.net. +Reaching the API is done via a direct TLS connection to the API host or via a shadowsocks bridge, to +increase censorship resistance. There are multiple components that interact with the API in an +asynchronous fashion, so to manage them all, there's an actor that specifically deals with sending +REST requests to the API. + +The API must be reachable in secured states even if a tunnel is not up, so the API runtime interacts +with the [tunnel state machine](#tunnel-state-machine) to send over the currently used API endpoint. +This can be a source of deadlocks, so no actor should ever be blocked by an API request if the TSM +relies on it to change states. + +All API requests can be dropped in flight to allow for resetting the connection whenever a tunnel is +established. The API requests can also be blocked when in the offline state or when it's assumed +that the user hasn't used our client for a period of time. ### Selecting relay and bridge servers See [this document](relay-selector.md). @@ -92,7 +131,14 @@ A high-level overview of the tunnel state machine can be seen in the diagram bel #### State machine inputs There are two types of inputs that the tunnel state machine react to. The first one is commands sent -to the state machine, and the second is external events that the state machine listens to. +to the state machine, and the second is external events that the state machine listens to. Reacting +to any event can result in the state machine transitioning away to a different state. + +<img src="diagrams/tsm-connecting-enter.png"> + + + + ##### Tunnel commands @@ -176,11 +222,9 @@ Linux. #### macOS -On macOS, the offline monitor uses [`SCNetworkReachability`] callbacks to detect changes in -connectivity and then enumerates network interfaces via [`SCDynamicStore`] and assumes connectivity -if an active physical interface exists. The interfaces are enumerated because sometimes -`SCNetworkReachability` can trigger a callback signalling full connectivity even when there exists -no default route. +On macOS, the offline monitor uses `route -n monitor -` to listen for changes in the routing table, +reasserting that a default route exists any time a change is detected. It's only assumed that the +host is offline if a default route doesn't exist. ##### Issues |