[tor-commits] [snowflake/master] Begin the Broker sub-README page

[arlo at torproject.org]

commit 4acff9983cca4d3a7778e3a49f073b0e342e5cf4
Author: Serene Han <keroserene+git at gmail.com>
Date:   Thu Feb 11 21:39:20 2016 -0800

    Begin the Broker sub-README page
---
 broker/README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/broker/README.md b/broker/README.md
index e69de29..ab6af99 100644
--- a/broker/README.md
+++ b/broker/README.md
@@ -0,0 +1,39 @@
+This is the Broker component of Snowflake.
+
+### Overview
+
+The Broker handles the rendezvous by matching Snowflake
+Clients with Proxies, and passing their WebRTC Session Descriptions
+(the "signaling" step). This allows Clients and Proxies to establish
+a Peer connection.
+
+It is analogous to Flashproxy's
+[Facilitator](https://trac.torproject.org/projects/tor/wiki/FlashProxyFAQ),
+but bidirectional and domain-fronted.
+
+The Broker expects:
+
+- Clients to send their SDP offer in a POST request, which will then block
+  until the Broker responds with the answer of the matched Proxy.
+- Proxies to announce themselves with a POST request, to which the Broker
+  responds with some Client's SDP offer. The Proxy should then send a second
+  POST request soon after containing its SDP answer, which the Broker passes
+  back to the same Client.
+
+### Running your own
+
+You can run your own Broker on either localhost or appengine.
+(Other CDNs will be supported soon.)
+
+
+To run on localhost, run `dev_appserver.py` or equivalent from this
+directory. (on arch, I use the wrapper script `dev_appserver-go`)
+
+To run on appengine, you can spin up your own instance with an arbitrary
+name, and use `appcfg.py`.
+
+In both cases, you'll need to provide the URL of the custom broker
+to the client plugin using the `--url $URL` flag.
+
+See more detailed appengine instructions
+[here](https://cloud.google.com/appengine/docs/go/).