From 18da1df71e538cd98032937c542154f0efcb6fbb Mon Sep 17 00:00:00 2001 From: jwijenbergh Date: Mon, 1 May 2023 15:18:40 +0200 Subject: Docs: Move state machine to API --- docs/src/SUMMARY.md | 4 +- docs/src/api/README.md | 2 +- docs/src/api/statemachine.md | 111 ++++++++++++++++++++++ docs/src/gettingstarted/building.md | 0 docs/src/gettingstarted/debugging/README.md | 6 -- docs/src/gettingstarted/debugging/fsm.md | 21 ---- docs/src/gettingstarted/debugging/fsm_example.svg | 1 - docs/src/gettingstarted/debugging/logging.md | 8 -- 8 files changed, 113 insertions(+), 40 deletions(-) create mode 100644 docs/src/api/statemachine.md delete mode 100644 docs/src/gettingstarted/building.md delete mode 100644 docs/src/gettingstarted/debugging/README.md delete mode 100644 docs/src/gettingstarted/debugging/fsm.md delete mode 100644 docs/src/gettingstarted/debugging/fsm_example.svg delete mode 100644 docs/src/gettingstarted/debugging/logging.md (limited to 'docs/src') diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index deac26b..1754d60 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -9,13 +9,11 @@ - [Package Formats](./gettingstarted/building/packageformats.md) - [Building for release](./gettingstarted/building/release.md) - [Testing](./gettingstarted/testing.md) - - [Debugging](./gettingstarted/debugging/README.md) - - [Logging](./gettingstarted/debugging/logging.md) - - [Finite State Machine](./gettingstarted/debugging/fsm.md) - [API](./api/README.md) - [Language Interop](./api/languageinterop.md) - [Architecture](./api/architecture.md) - [Typical flow](./api/typicalflow.md) - [Where to find docs](./api/wheretofinddocs.md) + - [State Machine](./api/statemachine.md) - [Let's build a client](./api/letsbuildaclient.md) - [Code examples](./api/codeexamples.md) diff --git a/docs/src/api/README.md b/docs/src/api/README.md index 8684c9c..64e7ee7 100644 --- a/docs/src/api/README.md +++ b/docs/src/api/README.md @@ -1,2 +1,2 @@ # API -This chapter is an introduction to the eduvpn-common API. It is meant as a high-level overview on how to use API and build your own eduVPN/Let's Connect! client. In this chapter, we *go* over the basics of how the interop between Go and language x works, say something about the architecture, explain where to find detailed API documentation, give a typical flow for a client and give a follow along tutorial on building an eduVPN client using Python code. +This chapter is an introduction to the eduvpn-common API. It is meant as a high-level overview on how to use API and build your own eduVPN/Let's Connect! client. In this chapter, we *go* over the basics of how the interop between Go and language x works, say something about the architecture, explain where to find detailed API documentation, explain the state machine, give a typical flow for a client and give a follow along tutorial on building an eduVPN client using Python code. At last, we will also have a few code examples that can be used as a short reference. diff --git a/docs/src/api/statemachine.md b/docs/src/api/statemachine.md new file mode 100644 index 0000000..260266c --- /dev/null +++ b/docs/src/api/statemachine.md @@ -0,0 +1,111 @@ +# 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 + +```mermaid +graph TD + +style Deregistered fill:white +Deregistered(Deregistered) -->|Client registers| No_Server + +style No_Server fill:white +No_Server(No_Server) -->|User clicks a server in the UI| Loading_Server + +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 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 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 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 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 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) -->|Client wants to go back to the main screen| No_Server + +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) -->|Cancel or Error| No_Server + +style Request_Config fill:white +Request_Config(Request_Config) -->|Re-authorize| OAuth_Started + +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 Chosen_Profile fill:white +Chosen_Profile(Chosen_Profile) -->|Cancel or Error| No_Server + +style Chosen_Profile fill:white +Chosen_Profile(Chosen_Profile) -->|Config has been obtained| Got_Config + +style Got_Config fill:cyan +Got_Config(Got_Config) -->|Choose a new server| No_Server + +style Got_Config fill:cyan +Got_Config(Got_Config) -->|Get a new configuration| Loading_Server +``` + +The current state is highlighted in the cyan 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 debuggin purposes. diff --git a/docs/src/gettingstarted/building.md b/docs/src/gettingstarted/building.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/src/gettingstarted/debugging/README.md b/docs/src/gettingstarted/debugging/README.md deleted file mode 100644 index 0b402a9..0000000 --- a/docs/src/gettingstarted/debugging/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Debugging - -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) `.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 deleted file mode 100644 index 45ed281..0000000 --- a/docs/src/gettingstarted/debugging/fsm.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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, 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 - -![](./fsm_example.svg) - -The current state is highlighted in the cyan color. - -## State explanation - -For the explanation of what all the different states mean, see the [API documentation](/api/overview/index.md#states) diff --git a/docs/src/gettingstarted/debugging/fsm_example.svg b/docs/src/gettingstarted/debugging/fsm_example.svg deleted file mode 100644 index eed1532..0000000 --- a/docs/src/gettingstarted/debugging/fsm_example.svg +++ /dev/null @@ -1 +0,0 @@ -
Client registers
Reload list
User clicks a server in the UI
Location chosen
Go back or Error
Server has been chosen
Go back 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
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
Cancel or Error
Profile has been chosen
Cancel or Error
Config has been obtained
Choose a new server
Get a new configuration
Deregistered
No_Server
Loading_Server
Ask_Location
Chosen_Location
Chosen_Server
Authorized
OAuth_Started
Request_Config
Ask_Profile
Chosen_Profile
Got_Config
 \ No newline at end of file diff --git a/docs/src/gettingstarted/debugging/logging.md b/docs/src/gettingstarted/debugging/logging.md deleted file mode 100644 index 9a7eae2..0000000 --- a/docs/src/gettingstarted/debugging/logging.md +++ /dev/null @@ -1,8 +0,0 @@ -# Logging -As said, logging is used. The logging gets saved in a client-specified directory (see [API](../../api/index.html)). Logging has the following levels: - -- `INFO`: Messages purely for info, these do not indicate any errors. They are merely there for debugging purposes -- `WARNING`: These messages indicate a warning, e.g. non-fatal errors -- `ERROR`: Fatal errors which refuses the app from working correctly - -By default only messages below or equal to `WARNING` are logged (`WARNING`, `ERROR`). However, if the debug variable is set to `True`, all messages will be logged into the log file. -- cgit v1.2.3