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

2021-04-27 19:45:58 -05:00 · 2021-04-27 19:45:58 -05:00 · 7bae7f45ff
parent 6990be48d6
commit 7bae7f45ff
2 changed files with 126 additions and 1 deletions
--- 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
--- a/docs/explanation/protocol.md
+++ 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
+
+<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.