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/README.md | 4 +-- docs/src/gettingstarted/building/README.md | 2 +- docs/src/gettingstarted/building/go.md | 8 ++--- docs/src/gettingstarted/building/packageformats.md | 1 + docs/src/gettingstarted/debugging/README.md | 2 +- docs/src/gettingstarted/debugging/fsm.md | 36 ++++++++++++---------- docs/src/gettingstarted/debugging/fsm_example.svg | 2 +- docs/src/gettingstarted/testing.md | 6 ++-- 8 files changed, 32 insertions(+), 29 deletions(-) (limited to 'docs/src/gettingstarted') diff --git a/docs/src/gettingstarted/README.md b/docs/src/gettingstarted/README.md index f73a736..252c8b1 100644 --- a/docs/src/gettingstarted/README.md +++ b/docs/src/gettingstarted/README.md @@ -1,6 +1,6 @@ # Getting started This chapter contains the steps to get started with the Go library and the Python wrapper. You will learn how to build the library/wrapper, how to run the test suite and how to debug possible errors. -Note that the Python wrapper is the most up to date wrapper. For now, we only document the Python wrapper in this documentation and in the future document the other wrappers as well. +Note that the Python wrapper is currently the only wrapper. So for now, we only document the Python wrapper in this documentation and in the future document the other wrappers as well. -The documentation on how to use this library will be given in the next chapter: [API](../api/index.html). +The documentation on how to use this library in your own code will be given in the next chapter: [API](../api/index.html). diff --git a/docs/src/gettingstarted/building/README.md b/docs/src/gettingstarted/building/README.md index 70df2b7..00295bf 100644 --- a/docs/src/gettingstarted/building/README.md +++ b/docs/src/gettingstarted/building/README.md @@ -1,2 +1,2 @@ # Building -This section contains the instruction on how to build the library and associated wrappers. We first explain how to build the Go library and then further explain the wrapper specific building process. As the Python wrapper is the only stable wrapper at the moment, this only consists of this wrapper language for now. +This section contains the instruction on how to build the library and associated wrappers. We first explain how to build the Go library and then further explain the wrapper specific building process. As the Python wrapper is the only wrapper at the moment, this only consists of this wrapper language for now. diff --git a/docs/src/gettingstarted/building/go.md b/docs/src/gettingstarted/building/go.md index 65f62a5..84c39fd 100644 --- a/docs/src/gettingstarted/building/go.md +++ b/docs/src/gettingstarted/building/go.md @@ -5,17 +5,17 @@ To build the Go library, you need the dependencies for your system installed. We ### Linux To build the Go shared library using Linux you need the following dependencies: -- [Go](https://go.dev/doc/install) 1.15 or later +- [Go](https://go.dev/doc/install) 1.18 or later - [Gcc](https://gcc.gnu.org/) - [GNU Make](https://www.gnu.org/software/make/) -- Dependencies for each wrapper you are interested in +- Dependencies for each wrapper you are interested in (read next sections) ### Windows On Windows, you can install gcc and make (or even Go) via MinGW or Cygwin or use WSL. For MinGW: 1. [Install MinGW](https://www.msys2.org/#installation) (you don't need to install any extra packages yet) and open some MSYS2 terminal (e.g. from the start menu or one of the installed binaries) -2. Install the [`make`](https://packages.msys2.org/package/make?repo=msys) package (`pacman -S make`) (or +2. Install the [`make`](https://packages.msys2.org/package/make?repo=msys) package (or e.g. [`mingw-w64-x86_64-make`](https://packages.msys2.org/package/mingw-w64-x86_64-make?repo=mingw64) and use `mingw32-make` in the command line) 3. To compile for x86_64: @@ -57,7 +57,7 @@ make GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc For example, you can cross compile for Windows from Linux using [MinGW-w64](https://www.mingw-w64.org/downloads/). -This shared library gets loaded by the different wrappers. To build the actual wrapper code, you need other build commands. This will be explained now +This shared library gets loaded by the different wrappers. To build the actual wrapper code, you need other build commands. This will be explained now. ### Cleaning To clean build the library and wrapper, issue the following command in the root directory: diff --git a/docs/src/gettingstarted/building/packageformats.md b/docs/src/gettingstarted/building/packageformats.md index 70516d9..02c9be9 100644 --- a/docs/src/gettingstarted/building/packageformats.md +++ b/docs/src/gettingstarted/building/packageformats.md @@ -39,3 +39,4 @@ make rpm-mock MOCK_TARGET=centos-stream-8-aarch64 A list of targets can be found in ```/etc/mock/*.cfg```. The default target is `fedora-36-x86_64` # Linux: Deb +The debian files can be found on a different [GitHub repository](https://github.com/jwijenbergh/python-eduvpn-common.deb). The debian packages for this repository are then build with [nbuilder.deb](https://git.sr.ht/~fkooman/nbuilder.deb). 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 diff --git a/docs/src/gettingstarted/testing.md b/docs/src/gettingstarted/testing.md index 62abfaf..079c052 100644 --- a/docs/src/gettingstarted/testing.md +++ b/docs/src/gettingstarted/testing.md @@ -1,5 +1,5 @@ # Testing -The Go library right now has tests defined for server interaction and signature verification tests. +The Go library right now has various tests defined. E.g. server interaction, oauth, discovery and signature verification tests. To run the test suite, issue the following command in a shell @@ -13,7 +13,7 @@ Note that this runs the tests without any server interaction (so for now only th SERVER_URI="eduvpn.example.com" PORTAL_USER="example" PORTAL_PASS="example" make test-go ``` -This needs [python3-selenium](https://selenium-python.readthedocs.io/) and [geckodriver](https://github.com/mozilla/geckodriver/releases) (extract and put in your `$PATH`). +This needs [python3-selenium](https://selenium-python.readthedocs.io/) and [geckodriver](https://github.com/mozilla/geckodriver/releases) (extract and put in your `$PATH`). Note that testing with a server assumes it uses a default portal, due to it needing to click on buttons on the web page. You can add your own portal by customizing the [called Selenium script](https://github.com/eduvpn/eduvpn-common/blob/main/selenium_eduvpn.py). If you have [Docker](https://www.docker.com/get-started/) installed and [Docker-compose](https://docs.docker.com/compose/install/) you can use a convenient helper script which starts up two containers - An eduVPN server for testing @@ -47,4 +47,4 @@ make test This accepts the same environment variables as we have explained before. -[^1]: For now, this is only the Python wrapper as the other wrappers do not implement the newest API just yet. +[^1]: For now, this is only the Python wrapper. -- cgit v1.2.3