# The PTTH protocol
(As currently implemented)
## Steps:
1. Server makes a request to the relay to listen for client
requests
2. Client makes a request to the relay
3. Relay responds to server's request from step 1 with
the client request from step 2
4. Server processes client request
5. Server makes a request to the relay to respond to the
client.
6. Relay responds to client's request from step 2 with the
server response from step 4
7. Relay responds to server's request from step 5
```text
Client Relay Server
P1
O <----- O
P2/H1 |
O ------> O
| P3
O -----> O
| P4/H2
O <----- O
| P5
O <------ O
P6/H3 | P7
O -----> O
```
## Example HTTP text
The relay is at `https://example.com`.
The server is named `aliens_wildland`. The API key is hidden
for simplicity and to discourage copy-pasting of well-known secrets.
Step 1, server to relay:
```text
GET /7ZSFUKGV/http_listen/aliens_wildland http/1.1
Host: example.com
```
Step 2, client to relay:
```text
GET /frontend/servers/aliens_wildland/files/
Host: example.com
SomeClientHeader: hello
```
Step 3, relay to server
(For readability, the body is written as JSON. PTTH actually uses
Msgpack.)
```text
HTTP/1.1 200 OK
[
{
"id": "JOZC7VRA",
"req": {
"method": "GET",
"uri": "/files",
"headers": {
"SomeClientHeader": "hello"
}
}
}
]
```
Step 4 doesn't involve any HTTP.
Step 5, server to relay:
```text
POST /7ZSFUKGV/http_response/JOZC7VRA http/1.1
Host: example.com
X-PTTH-2LJYXWC4: ZXhhbXBsZSB0ZXh0IGdvZXMgaGVyZQo=
Content-Length: 2400
...
```
The "PTTH magic header" `X-PTTH-2LJYXWC4` contains the server's
response status code and headers, encoded as MsgPack and then
ASCII-armored with Base64. The equivalent JSON would be:
```json
{
"status_code": "200",
"headers": {
"Content-Length": 2400,
"SomeServerHeader": "hello back"
}
}
```
Step 6, relay to client:
```text
HTTP/1.1 200 OK
Content-Length: 2400
SomeServerHeader: hello back
...
```
Step 7 doesn't contain any important data.