README.md 5.25 KB
Newer Older
1
# Telemersive Switchboard
Roman Haefeli's avatar
Roman Haefeli committed
2

3
*Telemersive Switchboard* is a service with a JSON API to manage different types of UDP proxies. UDP proxies are way to establish UDP connections between clients from behind NAT firewalls. The UDP proxies support several
4
connection topologies.
5

6
7
8
It is written in [Python](https://www.python.org/) and uses the
[flask](https://flask.palletsprojects.com/) framework.

9
## JSON API description
10

11
### Start a new proxy
12

13
14
15
A new proxy process is launched by sending a HTTP `POST` request with POST data
containing the description of the new proxy in JSON format to the path `<base>/proxies/`.
An example of POST data:
16

17
18
19
20
21
22
23
24
25
26
27
28
```json
{
    "port": 11000,
    "type", "one2oneBi",
    "room": "rehearsal",
    "description": "UltraGrid stage"
}
```

All four parameters `port`, `type`, `room`, and `description` are mandatory and must
be specified. Omitting any of them causes an error.

Roman Haefeli's avatar
Roman Haefeli committed
29
cURL example for starting a new proxy:
30
31
32
33
34
35
36
37
38
39
40
41
42

```bash
curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"port": 11000, "type": "one2oneBi", "description": "UltraGrid stage", "room": "rehearsal"}' \
  http://localhost:3591/proxies/
```

### Inspect running proxies

#### path `<base>/proxies/`

Roman Haefeli's avatar
Roman Haefeli committed
43
44
Information about running proxies is gathered with a HTTP `GET` request to `<base>/proxies/`. For
a specific proxy, use the proxy's specific path `<base>/proxies/<port>`.
45

Roman Haefeli's avatar
Roman Haefeli committed
46
cURL examples:
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

```bash
curl \
  --requeset GET \
  http://localhost:3591/proxies/
```

```bash
curl \
  --requeset GET \
  http://localhost:3591/proxies/11000
```

#### path `<base>/rooms/`

You can also request running proxies grouped by room through `<base>/rooms/`. Also, all
proxies running in a specific room can be listed.

Roman Haefeli's avatar
Roman Haefeli committed
65
cURL examples:
66
67
68

```bash
curl \
Roman Haefeli's avatar
Roman Haefeli committed
69
  --request GET \
70
71
72
73
74
  http://localhost:3591/rooms/
```

```bash
curl \
Roman Haefeli's avatar
Roman Haefeli committed
75
  --request GET \
76
77
  http://localhost:3591/rooms/rehearsal
```
78

79
80
81
82
### Stop a running proxy

A running proxy is stopped with a HTTP `DELETE` request to the proxy's path.

Roman Haefeli's avatar
Roman Haefeli committed
83
cURL example:
84
85
86

```bash
curl \
Roman Haefeli's avatar
Roman Haefeli committed
87
  --request DELETE \
88
89
90
91
   http://localhost:3591/proxies/11000
```

**NOTE**:  
92
Since `DELETE` requests should be treated in an idem-potent way, stopping
93
94
95
96
97
98
99
100
101
an already stopped proxy is considered not an error.

### Return values

For requests to semantically valid paths, the return value is a JSON object
of the format:

```json
{
102
103
  "status": "<Either 'Error' or 'OK'>",
  "msg": "<Some message describing the status>"
104
105
106
107
}
```

Depending on type of request and on status, different HTTP status codes are
108
returned. HTTP status may be one of `200`, `201`, `404`, `422`.
109
110
111


## UDP proxy types
112

maybites's avatar
maybites committed
113
**mirror** mirrors incoming packets. This is useful for testing, for instance to test if the server port is reachable. Also, it can be used to test applications like UltraGrid when no second peer is available.
114

maybites's avatar
maybites committed
115
**one2oneBi** establishes a connection between two endpoints. As soon as both endpoints have sent at least one packet, the script starts relaying incoming between clients. This script handles exactly one connection with two endpoints.
116

maybites's avatar
maybites committed
117
118
**one2manyMo** establishes 1-to-N connections and opens two listening socket, a source and a sink. The sink port uses an offset of
+1. It relays all incoming traffic from the source to all clients connected to the sink. Sink clients are requested to send at least one packet per second to indicate their active connection.
119
Packets from sink clients are discarded.
120

121
**one2manyBi** establishes 1-to-N connections like **one2manyMo**, but additionally allows
maybites's avatar
maybites committed
122
123
124
125
sink clients to send packets to the source. The sink port uses an offset of +1. Packets from
source client are forwarded to all active sink clients, packets from sink clients are forwarded
to the source client. Source AND Sink
clients are requested to send at least one packet per second to indicate their active connection.
126

127
**many2manyBi** relays incoming packets to all active clients but to to itself. Clients
maybites's avatar
maybites committed
128
are considered active as long as they send at least one packet per second.
129

maybites's avatar
maybites committed
130
131
**one2manyMo**, **one2manyBi** and **many2manyBi**
On ports that require packets to indicate an active connection, these scripts also accept an OSC packet without a payload and the address `/hb` without forwarding this packet.
132

133
134
## Deployment

135
The recommended way of running *Telemersive Switchboard* is to execute it under [gunicorn](https://gunicorn.org/). The included script `setup.sh` automates the process of setting up Telemersive Switchboard* as a system service. The script is tested on *Debian* and *Ubuntu*. Run it as root:
136
137
138
139
140

```bash
./setup.sh
```

maybites's avatar
maybites committed
141
142
143
144
145
### Stopping

This works best if no proxies are open.

```bash
146
systemctl stop telemersive-switchboard.service
maybites's avatar
maybites committed
147
148
```

Roman Haefeli's avatar
Roman Haefeli committed
149
### Logging
150
The service logs accesses to `/var/log/telemersive-swtichboard/access.log` and other messages to `/var/log/telemersive-switchboard/error.log`.
Roman Haefeli's avatar
Roman Haefeli committed
151
152


153
154
## About

155
*Telemersive Switchboard* is developed in the research project **Spatial Dis-/Continuities in Telematic Performances**. It is one element of our tool set to enable remote locations to create overlapping spaces on physical and virtualstages.
156

Roman Haefeli's avatar
Roman Haefeli committed
157
158
## Authors

maybites's avatar
maybites committed
159
160
161
162
163
164
165
166
167
Main contribution:
* Roman Haefeli <roman.haefeli@zhdk.ch>

Programming:
* Martin Froehlich <martin.froehlich@zhdk.ch>
* Florian Bruggisser <florian.bruggisser@zhdk.ch>

Bug Fixing:
* Joel Gähwiler <joel.gaehwiler@gmail.com>
Roman Haefeli's avatar
Roman Haefeli committed
168
169
170
171

## License

**GPL 3.0** (see [LICENSE.txt](LICENSE.txt))