correct the spec for the stream_bw event.

"neonomad" pointed out on or-talk that the order is opposite from the
intuitive order. explain why. we chose to fix the spec rather than the
code because there are controllers like torflow that already expect
the current behavior.

diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt
index f968fa851fef46f1a84d1127ed1bdeacbc6dc432..eb01641109aba17c3903186e9a9155e3575911cc 100644 (file)
--- a/doc/spec/control-spec.txt
+++ b/doc/spec/control-spec.txt
@@ -1597,17 +1597,21 @@
 4.1.13. Bandwidth used on an application stream
 
   The syntax is:
-     "650" SP "STREAM_BW" SP StreamID SP BytesRead SP BytesWritten CRLF
-     BytesRead = 1*DIGIT
+     "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead CRLF
      BytesWritten = 1*DIGIT
+     BytesRead = 1*DIGIT
+
+  BytesWritten and BytesRead are the number of bytes written and read
+  by the application since the last STREAM_BW event on this stream.
 
-  BytesRead and BytesWritten are the number of bytes read and written since
-  the last STREAM_BW event on this stream.  These events are generated about
-  once per second per stream; no events are generated for streams that have
-  not read or written.
+  Note that from Tor's perspective, *reading* a byte on a stream means
+  that the application *wrote* the byte. That's why the order of "written"
+  vs "read" is opposite for stream_bw events compared to bw events.
 
-  These events apply only to streams entering Tor (such as on a SOCKSPort,
-  TransPort, or so on).  They are not generated for exiting streams.
+  These events are generated about once per second per stream; no events
+  are generated for streams that have not written or read. These events
+  apply only to streams entering Tor (such as on a SOCKSPort, TransPort,
+  or so on). They are not generated for exiting streams.
 
 4.1.14. Per-country client stats