From 7bae7f45ff83cbbdddd43c2efe0a730c31afb7de Mon Sep 17 00:00:00 2001
From: _ <_@_>
Date: Tue, 27 Apr 2021 19:45:58 -0500
Subject: [PATCH] :pencil: docs: add explanation of protocol with made-up HTTP
text
---
README.md | 2 +-
docs/explanation/protocol.md | 125 +++++++++++++++++++++++++++++++++++
2 files changed, 126 insertions(+), 1 deletion(-)
create mode 100644 docs/explanation/protocol.md
diff --git a/README.md b/README.md
index 400a29c..ebbd3fe 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,7 @@ We'll call these steps "H1", "H2", and "H3" in the next section.
PTTH:
-```
+```text
Client Relay Server
P1
diff --git a/docs/explanation/protocol.md b/docs/explanation/protocol.md
new file mode 100644
index 0000000..bba9bfd
--- /dev/null
+++ b/docs/explanation/protocol.md
@@ -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
+
+
+
+
+...
+```
+
+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.