From b9b62c59dc99b63c5128f10a22774e3722b8b140 Mon Sep 17 00:00:00 2001 From: jwijenbergh Date: Wed, 4 Jan 2023 22:00:41 +0100 Subject: Docs: Update to be closer in line with the latest API --- docs/src/gettingstarted/debugging/README.md | 2 +- docs/src/gettingstarted/debugging/fsm.md | 36 ++++++++++++----------- docs/src/gettingstarted/debugging/fsm_example.svg | 2 +- 3 files changed, 21 insertions(+), 19 deletions(-) (limited to 'docs/src/gettingstarted/debugging') diff --git a/docs/src/gettingstarted/debugging/README.md b/docs/src/gettingstarted/debugging/README.md index e3a1ecd..0b402a9 100644 --- a/docs/src/gettingstarted/debugging/README.md +++ b/docs/src/gettingstarted/debugging/README.md @@ -3,4 +3,4 @@ To debug this library, e.g. to discover bugs or to see how it works internally, the library comes with a few nice additions. ## The debug variable -To enable debugging, set debugging to True in the method that registers the code with the library (see [API](../api/index.html)). This sets the logging level to `INFO` (meaning show all messages), and generates a Finite State Machine (FSM) PNG file. We explain in more detail what these two components (logging and FSM) exactly are and how they can be used. +To enable debugging, set debugging to True in the method that registers the code with the library (see [API](../api/index.html)). This sets the logging level to `INFO` (meaning show all messages), and generates a Finite State Machine (FSM) `.graph` file. We explain in more detail what these two components (logging and FSM) exactly are and how they can be used. diff --git a/docs/src/gettingstarted/debugging/fsm.md b/docs/src/gettingstarted/debugging/fsm.md index 8479a92..15b1a12 100644 --- a/docs/src/gettingstarted/debugging/fsm.md +++ b/docs/src/gettingstarted/debugging/fsm.md @@ -3,11 +3,11 @@ 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, set the debug variable to `True`. This outputs the graph with a `.graph` extension in the client-specified config directory (See [API](../../api/index.html)). The format of this graph is from [Mermaid](https://mermaid-js.github.io/mermaid/#/). - -If you have the [Mermaid command line client](https://github.com/mermaid-js/mermaid-cli) installed, the Go library will automatically provide a PNG file in the same directory of the `.graph` file. We recommend to use an image viewer that has auto-reload capabilities, such as [feh](https://feh.finalrewind.org/)[^1] for Linux. - -If you do not want to install additional tools to view the graph, you can submit the contents of the `.graph` file to the [Mermaid Live Editor](https://mermaid.live/) to see the image. +To view the FSM in an image, set the debug variable to `True`. This +outputs the graph with a `.graph` extension in the client-specified +config directory (See [API](../../api/index.html)). 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 @@ -18,15 +18,17 @@ The current state is highlighted in the cyan col ## State explanation The states mean the following: - -- `Deregistered`: The client has not registered with the library yet, the state variables are not initialized -- `No_Server`: The client is registered, but has not chosen a server yet -- `Chosen_Server`: The client has chosen a server to connect to -- `OAuth_Started`: The OAuth process has been started. This means that the client needs to redirect to the browser so that the user can login and approve the application -- `Authorized`: The OAuth process has finished. The client now has tokens and is thus authorized -- `Request_Config`: The client is in the process of requesting an OpenVPN/Wireguard configuration from the server -- `Ask_Profile`: The server has multiple profiles for which a config can be obtained, the client must show an UI of the profiles. The user then selects one of these profiles to exit this state -- `Has_Config`: The client now has a configuration that it can use to connect using OpenVPN/Wireguard -- `Connected`: The client is connected to the VPN - -[^1]: We recommend the following arguments for feh: `feh --auto-reload --keep-zoom-vp directory/example.png`. This auto reloads the feh image viewer and keeps the zoom level when reloading +- `Deregistered`: the app is not registered with the wrapper +- `No_Server`: means the user has not chosen a server yet +- `Ask_Location`: the user selected a Secure Internet server but needs to choose a location +- `Search_Server`: the user is currently selecting a server in the UI +- `Loading_Server`: means we are loading the server details +- `Chosen_Server`: means the user has chosen a server to connect to +- `OAuth_Started`: means the OAuth process has started +- `Authorized`: means the OAuth process has finished and the user is now authorized with the server +- `Request_Config`: the user has requested a config for connecting +- `Ask_Profile`: the go code is asking for a profile selection from the UI +- `Disconnected`: the user has gotten a config for a server but is not connected yet +- `Disconnecting`: the OS is disconnecting and the Go code is doing the /disconnect +- `Connecting`: the OS is establishing a connection to the server +- `Connected`: the user has been connected to the server. diff --git a/docs/src/gettingstarted/debugging/fsm_example.svg b/docs/src/gettingstarted/debugging/fsm_example.svg index cc0e33a..8e20808 100644 --- a/docs/src/gettingstarted/debugging/fsm_example.svg +++ b/docs/src/gettingstarted/debugging/fsm_example.svg @@ -1 +1 @@ -
Client registers
User chooses a server
The user is trying to choose a Server in the UI
User clicks a server in the UI
Cancel or Error
Found tokens in config
No tokens found in config
User authorizes with browser
Cancel or Error
Re-authorize with OAuth
Client requests a config
Multiple profiles found and no profile chosen
Only one profile or profile already chosen
Cancel or Error
Re-authorize
OS reports connected
User chooses a new profile
User wants to choose a new server
User chooses profile
Done but no profile selected
OS reports disconnected
Deregistered
No_Server
Chosen_Server
Search_Server
Authorized
OAuth_Started
Request_Config
Ask_Profile
Has_Config
Connected
 \ No newline at end of file +
Client registers
Reload list
User clicks a server in the UI
The server has been chosen
The user is trying to choose a new server in the UI
The user is already connected
Change the location in the main screen
Location chosen
Go back or Error
Cancel or Error
User clicks a server in the UI
Cancel or Error
Server info loaded
User chooses a Secure Internet server but no location is configured
Go back or Error
Found tokens in config
No tokens found in config
User authorizes with browser
Go back or Error
Cancel or Error
Re-authorize with OAuth
Client requests a config
Client wants to go back to the main screen
Multiple profiles found and no profile chosen
Only one profile or profile already chosen
Cancel or Error
Re-authorize
User chooses profile
Cancel or Error
Cancel or Error
OS reports it is trying to connect
User reconnects
User wants to choose a new server
Re-authorize with OAuth
Cancel or Error
Done disconnecting
Cancel or Error
Done connecting
App wants to disconnect
Deregistered
No_Server
Loading_Server
Chosen_Server
Search_Server
Connected
Ask_Location
Authorized
OAuth_Started
Request_Config
Ask_Profile
Disconnected
Connecting
Disconnecting
 \ No newline at end of file -- cgit v1.2.3