reactor
/
ptth
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

📝 docs: add explanation of protocol with made-up HTTP text

main
_ 2021-04-27 19:45:58 -05:00
parent 6990be48d6
commit 7bae7f45ff
2 changed files with 126 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -133,7 +133,7 @@ We'll call these steps "H1", "H2", and "H3" in the next section.
PTTH: PTTH:
``` ```text
Client Relay Server Client Relay Server
P1 P1

125
docs/explanation/protocol.md Normal file
View File

@ -0,0 +1,125 @@
# 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
<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.