blob: 29c05492a285e6c1550f1392c4caa8cef37ccc86 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
# Finite state machine
The eduvpn-common library uses a finite state machine internally to keep track of which state the client is in and to communicate data callbacks (e.g. to communicate the Authorization URL in the OAuth process to the client).
## Viewing the FSM
To view the FSM in an image, register to the library with in debug mode. This
outputs the graph with a `.graph` extension in the client-specified
config directory. The format of this
graph is from [Mermaid](https://mermaid-js.github.io/mermaid/#/). You
can convert this to an image using the [Mermaid command-line client](https://github.com/mermaid-js/mermaid-cli) installed or from the Mermaid web site, the [Mermaid Live Editor](https://mermaid.live)
## FSM example
The following is an example of the FSM when the client has obtained a Wireguard/OpenVPN configuration from an eduVPN server
<div class="statemachine">
```mermaid
graph TD
style Deregistered fill:cyan
Deregistered(Deregistered) -->|Client registers| No_Server
style No_Server fill:white
No_Server(No_Server) -->|Reload list| No_Server
style No_Server fill:white
No_Server(No_Server) -->|The client wants to ask for a location on the main screen| Ask_Location
style No_Server fill:white
No_Server(No_Server) -->|User clicks a server in the UI| Loading_Server
style No_Server fill:white
No_Server(No_Server) -->|The VPN is still active| Connected
style Ask_Location fill:white
Ask_Location(Ask_Location) -->|Location chosen| Chosen_Location
style Ask_Location fill:white
Ask_Location(Ask_Location) -->|Go back or Error| No_Server
style Ask_Location fill:white
Ask_Location(Ask_Location) -->|Go back or Error| Got_Config
style Chosen_Location fill:white
Chosen_Location(Chosen_Location) -->|Server has been chosen| Chosen_Server
style Chosen_Location fill:white
Chosen_Location(Chosen_Location) -->|Go back or Error| No_Server
style Chosen_Location fill:white
Chosen_Location(Chosen_Location) -->|Go back or Error| Got_Config
style Loading_Server fill:white
Loading_Server(Loading_Server) -->|Server info loaded| Chosen_Server
style Loading_Server fill:white
Loading_Server(Loading_Server) -->|User chooses a Secure Internet server but no location is configured| Ask_Location
style Loading_Server fill:white
Loading_Server(Loading_Server) -->|Go back or Error| No_Server
style Loading_Server fill:white
Loading_Server(Loading_Server) -->|Go back or Error| Got_Config
style Chosen_Server fill:white
Chosen_Server(Chosen_Server) -->|Found tokens in config| Authorized
style Chosen_Server fill:white
Chosen_Server(Chosen_Server) -->|No tokens found in config| OAuth_Started
style Chosen_Server fill:white
Chosen_Server(Chosen_Server) -->|Go back or Error| No_Server
style Chosen_Server fill:white
Chosen_Server(Chosen_Server) -->|Go back or Error| Got_Config
style OAuth_Started fill:white
OAuth_Started(OAuth_Started) -->|User authorizes with browser| Authorized
style OAuth_Started fill:white
OAuth_Started(OAuth_Started) -->|Go back or Error| No_Server
style OAuth_Started fill:white
OAuth_Started(OAuth_Started) -->|Go back or Error| Got_Config
style Authorized fill:white
Authorized(Authorized) -->|Re-authorize with OAuth| OAuth_Started
style Authorized fill:white
Authorized(Authorized) -->|Client requests a config| Request_Config
style Authorized fill:white
Authorized(Authorized) -->|Load the server again| Loading_Server
style Authorized fill:white
Authorized(Authorized) -->|Go back or Error| No_Server
style Authorized fill:white
Authorized(Authorized) -->|Go back or Error| Got_Config
style Request_Config fill:white
Request_Config(Request_Config) -->|Multiple profiles found and no profile chosen| Ask_Profile
style Request_Config fill:white
Request_Config(Request_Config) -->|Only one profile or profile already chosen| Chosen_Profile
style Request_Config fill:white
Request_Config(Request_Config) -->|Re-authorize| OAuth_Started
style Request_Config fill:white
Request_Config(Request_Config) -->|Go back or Error| No_Server
style Request_Config fill:white
Request_Config(Request_Config) -->|Go back or Error| Got_Config
style Ask_Profile fill:white
Ask_Profile(Ask_Profile) -->|Cancel or Error| No_Server
style Ask_Profile fill:white
Ask_Profile(Ask_Profile) -->|Profile has been chosen| Chosen_Profile
style Ask_Profile fill:white
Ask_Profile(Ask_Profile) -->|Go back or Error| No_Server
style Ask_Profile fill:white
Ask_Profile(Ask_Profile) -->|Go back or Error| Got_Config
style Chosen_Profile fill:white
Chosen_Profile(Chosen_Profile) -->|Config has been obtained| Got_Config
style Chosen_Profile fill:white
Chosen_Profile(Chosen_Profile) -->|Go back or Error| No_Server
style Chosen_Profile fill:white
Chosen_Profile(Chosen_Profile) -->|Go back or Error| Got_Config
style Got_Config fill:white
Got_Config(Got_Config) -->|Choose a new server| No_Server
style Got_Config fill:white
Got_Config(Got_Config) -->|Get a new configuration| Loading_Server
style Got_Config fill:white
Got_Config(Got_Config) -->|VPN is connecting| Connecting
style Connecting fill:white
Connecting(Connecting) -->|Go back or Error| Got_Config
style Connecting fill:white
Connecting(Connecting) -->|Done connecting| Connected
style Disconnecting fill:white
Disconnecting(Disconnecting) -->|Done disconnecting| Got_Config
style Disconnecting fill:white
Disconnecting(Disconnecting) -->|Go back or Error| Connected
style Connected fill:white
Connected(Connected) -->|The VPN is disconnecting| Disconnecting
```
</div>
The current state is highlighted in the <span style="color:cyan">cyan</span> color.
## State explanation
For the explanation of what all the different states mean, see the [client documentation](https://github.com/eduvpn/eduvpn-common/blob/v2/client/fsm.go#L14-L50)
## States that ask data
In eduvpn-common, there are certain states that require attention from the client.
- OAuth Started: A state that must be handled by the client. How a client can 'handle' this state, we will see in the next section. In this state, the client must open the webbrowser with the authorization URL to complete to OAuth process
- Ask Profile: The state that asks for a profile selection to the client. Reply to this state by using a "cookie" and the CookieReply function. What this means will be discussed in the Python client example too
- Ask Location: Same for ask profile but for selecting a secure internet location. Only called if one must be chosen, e.g. due to a selection that is no longer valid
The rest of the states are miscellaneous states, meaning that the client can handle them however it wants to. However, it can be useful to handle most state transitions to e.g. show loading screens or for logging and debugging purposes.
|
