[tor-commits] [meek/master] A few doc comments.

[dcf at torproject.org]

commit 90f4223a329f6791b0cbfc8f65e2dd37f31b976a
Author: David Fifield <david at bamsoftware.com>
Date:   Sat Apr 26 21:15:22 2014 -0700

    A few doc comments.
---
 appengine/reflect.go       |    9 +++++++++
 firefox/components/main.js |    3 +++
 latencytest/README         |    3 +++
 latencytest/latencytest.go |    3 +++
 meek-client/meek-client.go |    1 +
 5 files changed, 19 insertions(+)

diff --git a/appengine/reflect.go b/appengine/reflect.go
index 863a738..27c5941 100644
--- a/appengine/reflect.go
+++ b/appengine/reflect.go
@@ -1,3 +1,5 @@
+// A web app for Google App Engine that proxies HTTP requests and responses to a
+// Tor relay running meek-server.
 package reflect
 
 import (
@@ -18,6 +20,7 @@ const (
 
 var context appengine.Context
 
+// Join two URL paths.
 func pathJoin(a, b string) string {
 	if len(a) > 0 && a[len(a)-1] == '/' {
 		a = a[:len(a)-1]
@@ -37,11 +40,15 @@ var reflectedHeaderFields = []string{
 	"X-Session-Id",
 }
 
+// Make a copy of r, with the URL being changed to be relative to forwardURL,
+// and including only the headers in reflectedHeaderFields.
 func copyRequest(r *http.Request) (*http.Request, error) {
 	u, err := url.Parse(forwardURL)
 	if err != nil {
 		return nil, err
 	}
+	// Append the requested path to the path in forwardURL, so that
+	// forwardURL can be something like "http://example.com/reflect".
 	u.Path = pathJoin(u.Path, r.URL.Path)
 	c, err := http.NewRequest(r.Method, u.String(), r.Body)
 	if err != nil {
@@ -64,6 +71,8 @@ func handler(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
+	// Use urlfetch.Transport directly instead of urlfetch.Client because we
+	// want only a single HTTP transaction, not following redirects.
 	transport := urlfetch.Transport{
 		Context: context,
 		// Despite the name, Transport.Deadline is really a timeout and
diff --git a/firefox/components/main.js b/firefox/components/main.js
index b07ed84..bef833f 100644
--- a/firefox/components/main.js
+++ b/firefox/components/main.js
@@ -229,12 +229,15 @@ MeekHTTPHelper.RequestReader = function(transport, callback) {
         Components.interfaces.nsITransport.OPEN_BLOCKING | Components.interfaces.nsITransport.OPEN_UNBUFFERED, 0, 0);
 
     this.state = this.STATE_READING_LENGTH;
+    // Initially size the buffer to read the 4-byte length.
     this.buf = new Uint8Array(4);
     this.bytesToRead = this.buf.length;
     this.deadline = Date.now() + MeekHTTPHelper.LOCAL_READ_TIMEOUT * 1000;
     this.asyncWait();
 };
 MeekHTTPHelper.RequestReader.prototype = {
+    // The onInputStreamReady callback is called for all read events. These
+    // constants keep track of the state of parsing.
     STATE_READING_LENGTH: 1,
     STATE_READING_OBJECT: 2,
     STATE_DONE: 3,
diff --git a/latencytest/README b/latencytest/README
new file mode 100644
index 0000000..c96e60c
--- /dev/null
+++ b/latencytest/README
@@ -0,0 +1,3 @@
+This is an App Engine web app that measures the latency between the App
+Engine servers and other endpoints. A copy of this app is running at
+http://meek-latency-test.appspot.com/.
diff --git a/latencytest/latencytest.go b/latencytest/latencytest.go
index 0244bd6..4c248a2 100644
--- a/latencytest/latencytest.go
+++ b/latencytest/latencytest.go
@@ -1,3 +1,6 @@
+// This program tests the HTTP round-trip time from App Engine to various
+// endpoints. It does several POSTS to each endpoint and then draws a graph
+// showing the round-trip time.
 package latencytest
 
 import (
diff --git a/meek-client/meek-client.go b/meek-client/meek-client.go
index d6b095f..f293b67 100644
--- a/meek-client/meek-client.go
+++ b/meek-client/meek-client.go
@@ -151,6 +151,7 @@ func handler(conn *pt.SocksConn) error {
 	}()
 
 	defer conn.Close()
+	// Ignore the IP address in the SOCKS request.
 	err := conn.Grant(&net.TCPAddr{IP: net.ParseIP("0.0.0.0"), Port: 0})
 	if err != nil {
 		return err