ptth/docs/explanation/protocol.md

2.2 KiB

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
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:

GET /7ZSFUKGV/http_listen/aliens_wildland http/1.1
Host: example.com

Step 2, client to relay:

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.)

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:

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:

{
	"status_code": "200",
	"headers": {
		"Content-Length": 2400,
		"SomeServerHeader": "hello back"
	}
}

Step 6, relay to client:

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.