Commit 58531d8e authored by Roman Haefeli's avatar Roman Haefeli
Browse files

update README to reflect current state

parent 47013b3b
# tpf-switchboard
tpf-switchboard is a service with a JSON API to manage different types
of UDP proxies. UDP proxies are way to establish UDP connections for clients
behind NAT firewalls.
of UDP proxies. UDP proxies are way to establish UDP connections between
clients from behind NAT firewalls. The UDP proxies support several
connection topologies.
## JSON API description
### Start a new proxy
tpf-switchboard is developed in the research project "Spatial Dis-/
Continuities in Telematic Performances". It's one element of our toolset to
enable remote locations to create overlapping spaces on physical and virtual
stages.
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:
## UDP proxy types
```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.
A working curl example for starting a new proxy:
```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/`
Information about running proxies is gathered with HTTP `GET` requests. For an overview
of all running proxies, a requet to `<base>/proxies/` is sent. For details of a specific
proxy, a request to `<base>/proxies/<port>` is sent.
curl examples:
```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.
Curl examples:
```bash
curl \
--requeset GET \
http://localhost:3591/rooms/
```
```bash
curl \
--requeset GET \
http://localhost:3591/rooms/rehearsal
```
Those scripts are intended to be run on a server with a public IP address. They
relay incoming UDP packets between connected clients. We use them to establish
UDP connections between endpoints behind NAT firewalls.
### Stop a running proxy
A running proxy is stopped with a HTTP `DELETE` request to the proxy's path.
curl example:
```bash
curl \
--request DELETE
http://localhost:3591/proxies/11000
```
**NOTE**:
Since `DELETE` request should be treated in an idem-potent way, stopping
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
{
"status": <Either 'Error' or 'OK'>,
"msg": <Some message describing the status>
}
```
Depending on type of request and on status, different HTTP status codes are
returned. HTTP status may be one of `200`, '201`, `404`, `422`.
## UDP proxy types
### mirror
**udp_mirror** mirrors incoming packets. This is useful for testing, for instance
**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.
### one2oneBi
**udp_one2oneBi** establishes a connection between two endpoints. As soon as both endpoints
**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 connetion with two endpoints.
### one2manyMo
**udp_dyn_proxy** handles many endpoint-to-endpoint connections simultaneously. For
that to work, each client sends a token message with a key word to the server. After
having received the same token message from two different clients, the sever starts
relaying packets between the two clients.
**one2manyMo** opens two listening socket, a source and a sink. 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 signal their active connection. Packets from
sink clients are discarded.
### one2manyBi
**udp_multi_proxy** relays an incoming stream of UDP packets from a source client to
one or many receiving clients. The script opens two listening sockets, one for the
source client and one with an offset for the receiving clients. Receiving clients
need to send a dummy packet in regular intervals to keep their connection alive.
**one2manyBi** establishes 1-to-N connections like **one2manyMo**, but additionally allows
sink clients send packets to the source. Packets from source are forwarded to all active
sink clients, packets from sink clients are forwarded to the source client. For keeping
connections alive without forwarding any data, **one2manyBi** discards OSC packets with an
address `/hb` and no payload.
### many2manyBi
**many2manyBi** relays incoming packets to all active clients but to to itself. Clients
are considered active as long as they send at least one packet per second. OSC packets
with an address `/hb` and no payload are discarded and may be used by clients to keep
their connection alive without sending data.
## About
tpf-switchboard is developed in the research project "Spatial Dis-/
Continuities in Telematic Performances". It's one element of our toolset to
enable remote locations to create overlapping spaces on physical and virtual
stages.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment