path: root/docs/src/api/letsbuildaclient.md

# Let's build a client using Python
To begin, let's follow the flow and see if we can figure out how it works.

## Registering

> The client starts up. It calls the Register function that communicates with the library that it has initialized

In Python, this works like the following:
- First import the library
```python
import eduvpn_common.main as edu

# we will come back to this later
def handler(common: edu.EduVPN, old: int, old: int, data: str):
	return False

# These arguments can be found in the docstring
# But also in the exports.go file
# For Python it's a bit different, we have split the arguments into the constructor and register
# Here we pass the client ID for OAuth, the version of the client and the directory where config files should be found
common=edu.EduVPN("org.eduvpn.app.linux", "0.0.1", "/tmp/test")

# Here we create a state handler with the class passed to it
state_handler = lambda old, new, data: handler(common, old, new, data)

common.register(handler=state_handler, debug=True)
```

Now after registering, we know that we have no servers configured (unless you're following this tutorial again with an existing `/tmp/test`). So we continue with step 4

## Discovery

>  If the client has no servers, or it wants to add a new server, the client calls `DiscoOrganizations` and `DiscoServers` to get the discovery files from the library.

```python
# Let's get them and print them
print(common.get_disco_organizations())
print(common.get_disco_servers())
```

We get a big JSON blob, so which format is this? From the Go documentation:

> DiscoOrganizations gets the organizations from discovery, returned as types/discovery/discovery.go Organizations marshalled as JSON

> DiscoServers gets the servers from discovery, returned as types/discovery/discovery.go Servers marshalled as JSON

If you follow these files, you see two structs, Servers and Organizations. These structs have json tags associated with them. You can use this structure to figure out how to parse the returned data. In case of discovery, it's very similar to the [JSON files from the discovery server](https://disco.eduvpn.org/v2)

## Adding a server

The next bullet point that we implement is the following:

> From this discovery list, it calls AddServer to add the server to the internal server list of eduvpn-common. This also calls necessary state transitions, e.g. for authorizing the server. The next call to ServerList then has this server included

The discovery servers contains a server called the demo server. Let's try to add it. To add it we need to pass the type of server we're adding. From discovery we can deduce that this is an institute access server as the JSON looks like the following:

```json
{
    "authentication_url_template": "",
    "base_url": "https://demo.eduvpn.nl/",
    "display_name": {
        "en": "Demo"
    },
    "server_type": "institute_access", # this is why we know it is Institute Access
    "support_contact": [
        "mailto:eduvpn@surf.nl"
    ]
},
```

From the Go documentation, we know that the identifier must be the Base URL:

> id is the identifier of the string
> - In case of secure internet: The organization ID
> - In case of custom server: The base URL
> - In case of institute access: The base URL


```python
# Compare this to the Go version, the non-interactive field is optional here as it is default False
common.add_server(edu.ServerType.INSTITUTE_ACCESS, "https://demo.eduvpn.nl/")
```

But we get an error!
```bash
eduvpn_common.main.WrappedError: fsm failed transition from 'Chosen_Server' to 'OAuth_Started', is this required transition handled?
```

This is the state machine we briefly mentioned before. Some functions require that you handle certain transitions. From the Go documentation, we can find this in the documentation as well that you must handle this transition. Let's handle it in Python to open the webbrowser for the OAuth process.

In the registering code, we previously defined a handler that does nothing. Let's extend it to handle the OAuth state transition:
```python
import webbrowser

def handler(common: edu.EduVPN, old: int, new: int, data: str):
	# you would define an enumeration with all the states so that you can also extend them
	# it's 6 because https://github.com/eduvpn/eduvpn-common/blob/b660911b5db000b43970f3754b5767bb50741360/client/fsm.go#L33
	if new == 6:
		webbrowser.open(data)
		return True
	return False
```

Now if you re-rerun the whole code with this handler added, your webbrowser should open.

After you have authorized the application through the portal using the webbrowser, the server should have been added:

```python
print(common.get_servers())
```

Returns:

```json
{
  "institute_access_servers": [
    {
      "display_name": {
        "en": "Demo"
      },
      "identifier": "https://demo.eduvpn.nl/",
      "profiles": {
        "current": ""
      },
      "delisted": false
    }
  ]
}
```

The format of this JSON is specified in the Go documentation:

`(in exports/exports.go)`
> It returns the server list as a JSON string defined in types/server/server.go List

## Obtaining a VPN configuration from the server

The next part of the flow is:

> When the user selects a server to connect to in the UI, it calls the GetConfig to get a VPN configuration for this server. This function transitions the state machine multiple times. The client uses these state transitions for logging or even updating the UI. The client then connects

Let's try it, the required arguments are the same for adding a config in the Python wrapper:

```python
print(common.get_config(edu.ServerType.INSTITUTE_ACCESS, "https://demo.eduvpn.nl"))
```

However, this gives an exception:

```bash
eduvpn_common.main.WrappedError: fsm failed transition from 'Request_Config' to 'Ask_Profile', is this required transition handled?
```

A similar error to the OAuth error we had before. This `Ask_Profile` transition is there for the client/user to choose a profile as this server has multiple profiles defined.

To handle this transition and thus choose a profile to continue, we must do multiple steps:
- Add the condition to the handler to return true
- Parse the data that we get back
- Reply with a choice for the profile 

If we add the condition and print the data:

```python
if new == 9:
    print(f"profiles received: {data}")
    return True
```

we get back the following JSON (from the Go docs: `The data for this transition is defined in types/server/server.go RequiredAskTransition with embedded data Profiles in types/server/server.go`):

```python
{
  "cookie": 4,
  "data": {
    "map": {
      "internet": {
        "display_name": {
          "en": "Internet"
        },
        "supported_protocols": [
          1,
          2
        ]
      },
      "internet-split": {
        "display_name": {
          "en": "No rfc1918 routes"
        },
        "supported_protocols": [
          1,
          2
        ]
      }
    },
    "current": ""
  }
}
```

This thus gives you the list of profiles with a so-called "cookie". This *cookie* is used to confirm the choice to the Go library. To do so we must do the following in the handler:

```python
if new == 9:
    json_dict = json.loads(data)
    common.cookie_reply(json_dict["cookie"], "internet")
    return True
```

If we then re-run the code, we get back the following JSON (from the Go docs: `The return data is the configuration, marshalled as JSON and defined in types/server/server.go Configuration`)

```python
{
  "config": "the WireGuard config",
  "protocol": 2, # 2 specifies WireGuard
  "default_gateway": true
}
```

## Cleanup
The flow also mentioned:

> When the client is done, it calls `Deregister` such that the most up to date internal state is saved to disk. Note that eduvpn-common also saves the internal state .e.g. after obtaining a VPN configuration

Let's be a nice client and do this:

```python
common.deregister()
```

If we then call any function, we get an error, so it is important that you do this on exit:

```python
print(common.get_servers())
>>> eduvpn_common.main.WrappedError: No state available, did you register the client?
```

But when we register again and then get the list of servers, the servers are retrieved from disk:

```python
common=edu.EduVPN("org.eduvpn.app.linux", "0.0.1", "/tmp/test")
common.register(handler=state_handler, debug=True)
print(common.get_servers())
```

gives

```json
{
  "institute_access_servers": [
    {
      "display_name": {
        "en": "Demo"
      },
      "identifier": "https://demo.eduvpn.nl/",
      "profiles": {
        "map": {
          "internet": {
            "display_name": {
              "en": "Internet"
            },
            "supported_protocols": [
              1,
              2
            ]
          },
          "internet-split": {
            "display_name": {
              "en": "No rfc1918 routes"
            },
            "supported_protocols": [
              1,
              2
            ]
          }
        },
        "current": "internet"
      },
      "delisted": false
    }
  ]
}
```

Note the difference with the previous JSON, the profiles are now initialized because we have gotten a configuration before.

If the `/tmp/test` directory is removed (the argument that was passed to register), we get no servers again:

```python
import shutil
shutil.rmtree("/tmp/test")
common=edu.EduVPN("org.eduvpn.app.linux", "0.0.1", "/tmp/test")
common.register(handler=state_handler, debug=True)
print(common.get_servers())
```

gives `"{}"`, an empty JSON object string