[tor-commits] [snowflake/main] Document /amp/client in broker-spec.txt.

[dcf at torproject.org]

commit f2dc41d77891816b3f6aec78cf9491fad6999388
Author: David Fifield <david at bamsoftware.com>
Date:   Mon Jul 26 10:23:12 2021 -0600

    Document /amp/client in broker-spec.txt.
---
 doc/broker-spec.txt | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/doc/broker-spec.txt b/doc/broker-spec.txt
index f2cd231..f25be79 100644
--- a/doc/broker-spec.txt
+++ b/doc/broker-spec.txt
@@ -107,6 +107,11 @@ through the exchange of WebRTC SDP information with its endpoints.
 
 2.1. Client interactions with the broker
 
+The broker offers multiple ways for clients to exchange registration
+messages.
+
+2.1.1. HTTPS POST
+
 Clients interact with the broker by making a POST request to `/client` with the
 offer SDP in the request body:
 ```
@@ -130,6 +135,38 @@ If no proxies were available, they receive a 503 status code:
 HTTP 503 Service Unavailable
 ```
 
+2.1.2. AMP
+
+The broker's /amp/client endpoint receives client poll messages encoded
+into the URL path, and sends client poll responses encoded as HTML that
+conforms to the requirements of AMP (Accelerated Mobile Pages). This
+endpoint is intended to be accessed through an AMP cache, using the
+-ampcache option of snowflake-client.
+
+The client encodes its poll message into a GET request as follows:
+```
+GET /amp/client/0[0 or more bytes]/[base64 of client poll message]
+```
+The components of the path are as follows:
+* "/amp/client/", the root of the endpoint.
+* "0", a format version number, which controls the interpretation of the
+  rest of the path. Only the first byte matters as a version indicator
+  (not the whole first path component).
+* Any number of slash or non-slash bytes. These may be used as padding
+  or to prevent cache collisions in the AMP cache.
+* A final slash.
+* base64 encoding of the client poll message, using the URL-safe
+  alphabet (which does not include slash).
+
+The broker returns a client poll response message in the HTTP response.
+The message is encoded using AMP armor, an AMP-compatible HTML encoding.
+The data stream is notionally a "0" byte (a format version indicator)
+followed by the base64 encoding of the message (using the standard
+alphabet, with "=" padding). This stream is broken into
+whitespace-separated chunks, which are then bundled into HTML <pre>
+elements. The <pre> elements are then surrounded by AMP boilerplate. To
+decode, search the HTML for <pre> elements, concatenate their contents
+and join on whitespace, discard the "0" prefix, and base64 decode.
 
 2.2 Proxy interactions with the broker