2021-04-28 00:45:58 +00:00
|
|
|
# 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
|
|
|
|
|
|
|
|
|
|
[
|
|
|
|
|
{
|
2021-04-28 03:36:44 +00:00
|
|
|
"id": "01F4B61CQF1GY39BM5H24SR9H3",
|
2021-04-28 00:45:58 +00:00
|
|
|
"req": {
|
|
|
|
|
"method": "GET",
|
|
|
|
|
"uri": "/files",
|
|
|
|
|
"headers": {
|
|
|
|
|
"SomeClientHeader": "hello"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Step 4 doesn't involve any HTTP.
|
|
|
|
|
|
|
|
|
|
Step 5, server to relay:
|
|
|
|
|
|
|
|
|
|
```text
|
2021-04-28 03:36:44 +00:00
|
|
|
POST /7ZSFUKGV/http_response/01F4B61CQF1GY39BM5H24SR9H3 http/1.1
|
2021-04-28 00:45:58 +00:00
|
|
|
Host: example.com
|
|
|
|
|
X-PTTH-2LJYXWC4: ZXhhbXBsZSB0ZXh0IGdvZXMgaGVyZQo=
|
|
|
|
|
Content-Length: 2400
|
|
|
|
|
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<meta charset="utf-8" />
|
|
|
|
|
...
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<meta charset="utf-8" />
|
|
|
|
|
...
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Step 7 doesn't contain any important data.
|
