Merge branch 'tunnel-state-machine-doc'

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/architecture.md b/docs/architecture.md
index 3d670a772c..212c571f06 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -32,6 +32,113 @@ See [this document](relay-selector.md).
 
 ### Tunnel state machine
 
+The tunnel state machine is the part of Talpid that coordinates the events for establishing a VPN
+connection. It acts upon requests for establishing a secure VPN connection or for disconnecting an
+already established connection and returning the system to its initial state. This involves also
+using other parts of Talpid to configure the system so that the security policies are applied and
+so that the connection works correctly without any further manual configuration necessary.
+
+The tunnel state machine starts in an initial `Disconnected` state. In this state, no changes are
+made to the operating system and no security policies are applied. When a request is sent to the
+state machine to establish a connection, the state machine will progress first into a `Connecting`
+state that will configure the operating system and setup a tunnel with a connection to a VPN server.
+Once the configuration is complete and the connection is verified to be working, the state machine
+then proceeds to a `Connected` state.
+
+A request can be made to close the VPN connection. Such request will lead the state machine into
+a `Disconnecting` state, which will close the connection to the VPN server and restore the operating
+system to its original configuration. After the process is complete, the state machine returns to
+the `Disconnected` state.
+
+If an error occurs in the `Connecting` or `Connected` states, the state machine may proceed to an
+`Error` state. It might reach this state either immediately (when an error occurs in the
+`Connecting` state) or after passing through another state to tear down the tunnel (when an error
+occurs in the `Connected` state). Either way, in this state the operating system is configured to
+block all connections to avoid leaking any data. The objective is to ensure no data leaks from the
+tunnel while the user has requested a secure connection, as defined in the [security document].
+
+A high-level overview of the tunnel state machine can be seen in the diagram below:
+
+
+                    +--------------+   Request to connect    +------------+
+      Start ------->| Disconnected +------------------------>| Connecting |
+                    +--------------+                         +----+--+--+-+
+                        ^                                      ^  |  ^  |
+                        |           Will attempt to reconnect  |  |  |  |
+                        |   .----------------------------------'  |  |  |
+                        |   |                                     |  |  |
+                        |   |                   .-----------------'  |  |
+                        |   |                   | Unrecoverable      |  |
+                        |   |                   |     error          |  |
+                        |   |    Request to     V                    |  |
+     System is restored |   |    disconnect +-------+                |  | Connection is configured
+       to its initial   |   |   .-----------+ Error +----------------'  |       and working
+        configuration   |   |   |           +-------+  Request to       |
+                        |   |   |               ^       connect         |
+                        |   |   |               |                       |
+                        |   |   |  .------------'                       |
+                        |   |   |  | Unrecoverable                      |
+                        |   |   |  |  error while                       |
+                        |   |   |  |  in connected                      |
+                        |   |   V  |     state                          V
+                     +--+---+------+-+                         +-----------+
+                     | Disconnecting |<------------------------+ Connected |
+                     +---------------+  Request to disconnect  +-----------+
+                                          or unrecoverable
+                                               error
+
+[security document]: security.md
+
+#### 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.
+
+##### Tunnel commands
+
+Besides the two main commands `Connect` and `Disconnect`, there are a few other commands that can be
+sent to the tunnel state machine. The following list includes all the commands the tunnel state
+machine can receive.
+
+- *Connect*: establish a secure VPN connection
+- *Disconnect*: tear down the active VPN connection and return the operating system to its initial
+  configuration
+- *Allow LAN*: enable or disable local network sharing, changing the security policies for some of
+  the states
+- *Block when disconnected*: configures whether the state machine should apply the security policy
+  for blocking all connections when it's in the `Disconnected` state, effectively requesting the
+  system to never allow connections outside the tunnel
+
+##### External events
+
+Depending on the state of the machine, it will also listen for specific external events and act
+on them possibly by changing states. All of these events can be considered as tunnel events, but
+they happen on different scenarios and because of different causes.
+
+- *Tunnel is Up*: the tunnel monitor notifies that the tunnel is working correctly
+- *Tunnel is Down*: the tunnel monitor notifies that the tunnel has disconnected
+- *Tunnel monitor stopped*: communication to the tunnel monitor was lost
+- *Is offline*: notify the tunnel state machine if the operating system is connected or not to the
+  network, so that it can safely wait for connectivity to be restored without endlessly retrying to
+  establish the VPN connection
+
+#### State machine outputs
+
+Every time the state machine changes state, it will output a `TunnelStateTransition`. This is an
+`enum` type representing which state the tunnel state machine has entered and any associated
+metadata that might be useful.
+
+- *Disconnected*
+- *Connecting*: includes the information of the endpoint it is trying to connect to
+- *Connected*: includes the information of the endpoint it is connected to
+- *Disconnecting*: includes the state it will transition to once successfully disconnected, which
+  is represented as the action it will take after disconnected, listed below:
+  - *Nothing*: proceed to the `Disconnected` state
+  - *Block*: proceed to the `Error` state
+  - *Reconnect*: proceed to the `Connecting` state
+- *Error*: includes the cause of the error and the information if the operating system was
+  successfully configured to block all connections
+
 ### System DNS management
 
 ### Firewall integration