Newer
Older
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
The server has two main responsibilites.
The first is to handle API calls from the client to store, update and delete information, such as competitions or users.
It also needs to make sure that only authorized people can access these.
The other is to sync slides, timer and answers between clients in an active competition.
Both of these will be described in more detail below.
## Receiving API calls
An API call is a way the client can communicates with the server.
When a request is received the server begins by authorizing it (making sure the person sending the request is allowed to access the route).
After that it makes sure that it got all information in the request it needed.
The server will then do the thing the client requested.
And finally it will need to generate repsonse, usually in the form of an object from the database.
All of these steps are described in more detail below.
### Routes
Each route which is possible to call is specified in the files in the `app/apis/` folder.
All available routes can also be seen by navigating to `localhost:5000` after starting the server.
### Authorization
When the server receives an API call the first thing it does is to authorize it.
The authorization is done using JSON Web Tokens (JWT) by comparing the contents of them with what is expected.
Whenever a client logs into an account or joins a competition, it is given a JWT generated by the server, and the client will need to use this token in every subsequent request sent to the server to authenticate itself.
What authorization to be done on the server is specified by the `@protect_route()` decorator.
This decorator specifies who is allowed to access this route, which can either be users with specific roles, or people who have joined competitions with specific views.
If the route is not decorated everyone is allowed to access it, the only routes currently like that is logging in as a user and joining a competition, by necessity.
### Parsing request
After the request is authorized the server will need to parse contents of the request.
The parsing is done with [reqparse](https://flask-restx.readthedocs.io/en/latest/parsing.html) from RestX (this module is deprecated and should be replaced).
Each API call expects different parameters in different places and this is specificied in each of the files in `app/apis/` folder, together with the route.
### Handling request
After the request has been authorized and parsed the server needs to act on the request.
What the server does of course depends on the route and given arguments, but it usually gets, edits or deletes something from the database.
The server uses an SQL database and interfaces to it via SQLAlchemy.
Everything related to the database is located in the `app/database/` folder.
### Responding
When the server is done handling the request it usually responds with an item from the database.
Converting a database object to json is done with [Marsmallow](https://marshmallow.readthedocs.io/en/stable/).
How to do this conversion is specified in two files in in the folder `app/core/`.
The file `schemas.py` just converts a record in the database field by field.
The file `rich_schemas.py` on the other hand converts an `id` in one table to an entire object in the another table, thus the name rich.
In this way, for example, an entire competition with it's teams, codes, slides and the slides' questions and components can be returned in a single API call.
## Active competitions
Slides and timers (and answers) needs to be synced during an active presentation.
This is done using SocketIO together with flask_socketio.
Events sent is also authorized via JWT, basically the same way as the for the API calls.
But for socket events, the decorator that is used to authenticate them is `@authorize_user()`.
Whenever client joins a competition they will connect via sockets.
A single competition cannot be active more than once at the same time.
This means that you will need to make a copy of a competition if you want to run multiple times at the same time.
All of the functionality related to an active competition and sockets can be found in the file `app/core/sockets.py`.
The terms `active competition` and `presentation` means the same thing.
### Starting and joing presentations
Whenever a client types in a code in the client it will be checked via the `api/auth/login/code` API call.
If there is such a code and it was an operator code, the client will receive a JWT it will need to use to authenticate itself.
If there is such a code and the associated competition is active, the client will also receive a JWT, regardless if it was an operator code or not.
Both of these cases will be handled by the default `connect` event, using the JWT received from the API call.
The server can see what is stored in the JWT and do different things depending on it's contents.
### Syncing between clients
The operator will emit the `sync` event and provide either slide or timer to update it on the server.
The server will then send `sync` to all connected clients with the updated values, regardless of what was actually updated.
The server will also store the timer and active slide in order to `sync` clients when they join.
The operator can also emit `end_presentation` to disconnect all clients from it's competitions.
This will also end the presentation.