commit 1448c3885f2bdfde9d7dfc801e730cfe5301a224 Author: Cecylia Bocovich cohosh@torproject.org Date: Tue May 12 16:08:15 2020 -0400

Update documentation to include broker spec

Add broker messaging specification with endpoints for clients and proxies. --- doc/broker-spec.txt | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+)

diff --git a/doc/broker-spec.txt b/doc/broker-spec.txt index eba3347..c3177e0 100644 --- a/doc/broker-spec.txt +++ b/doc/broker-spec.txt @@ -67,3 +67,116 @@ Metrics data from the Snowflake broker can be retrieved by sending an HTTP GET r

A count of the number of times a client successfully received a proxy from the broker, rounded up to the nearest multiple of 8. + +2. Broker messaging specification and endpoints + +The broker facilitates the connection of snowflake clients and snowflake proxies +through the exchange of WebRTC SDP information with its endpoints. + +2.1. Client interactions with the broker + +Clients interact with the broker by making a POST request to `/client` with the +offer SDP in the request body: +``` +POST /client HTTP + +[offer SDP] +``` +If the broker is behind a domain-fronted connection, this request is accompanied +with the necessary HOST information. + +If the client is matched up with a proxy, they receive a 200 OK response with +the proxy's answer SDP in the request body: +``` +HTTP 200 OK + +[answer SDP] +``` + +If no proxies were available, they receive a 503 status code: +``` +HTTP 503 Service Unavailable +``` + + +2.2 Proxy interactions with the broker + +Proxies poll the broker with a proxy poll request to `/proxy`: + +``` +POST /proxy HTTP + +{ + Sid: [generated session id of proxy], + Version: 1.1, + Type: ["badge"|"webext"|"standalone"|"mobile"] +} +``` + +If the request is well-formed, they receive a 200 OK response. + +If a client is matched: +``` +HTTP 200 OK + +{ + Status: "client match", + { + type: offer, + sdp: [WebRTC SDP] + } +} +``` + +If a client is not matched: +``` +HTTP 200 OK + +{ + Status: "no match" +} +``` + +If the request is malformed: +``` +HTTP 400 BadRequest +``` + +If they are matched with a client, they provide their SDP answer with a POST +request to `/answer`: +``` +POST /answer HTTP + +{ + Sid: [generated session id of proxy], + Version: 1.1, + Answer: + { + type: answer, + sdp: [WebRTC SDP] + } +} +``` + +If the request is well-formed, they receive a 200 OK response. + +If the client retrieved the answer: +``` +HTTP 200 OK + +{ + Status: "success" +} +``` + +If the client left: +``` +HTTP 200 OK + +{ + Status: "client gone" +} + +3) If the request is malformed: +HTTP 400 BadRequest +```