[or-cvs] r15352: Spec clarifications on 137. (tor/trunk/doc/spec/proposals)

[nickm at seul.org]

Author: nickm
Date: 2008-06-18 16:00:32 -0400 (Wed, 18 Jun 2008)
New Revision: 15352

Modified:
   tor/trunk/doc/spec/proposals/137-bootstrap-phases.txt
Log:
Spec clarifications on 137.

Modified: tor/trunk/doc/spec/proposals/137-bootstrap-phases.txt
===================================================================
--- tor/trunk/doc/spec/proposals/137-bootstrap-phases.txt	2008-06-18 19:55:41 UTC (rev 15351)
+++ tor/trunk/doc/spec/proposals/137-bootstrap-phases.txt	2008-06-18 20:00:32 UTC (rev 15352)
@@ -30,8 +30,11 @@
 
   So in this case we send
   650 STATUS_CLIENT NOTICE/WARN BOOTSTRAP \
-  PROGRESS=num TAG=string SUMMARY=string WARNING=string REASON=string
+  PROGRESS=num TAG=Keyword SUMMARY=String WARNING=String REASON=Keyword
 
+  The arguments MAY appear in any order. Controllers MUST accept unrecognized
+  arguments.
+
   "Progress" gives a number between 0 and 100 for how far through
   the bootstrapping process we are. "Summary" is a string that can be
   displayed to the user to describe the *next* task that Tor will tackle,
@@ -53,8 +56,13 @@
   Tor. Controllers should not assume that the percentages and tags listed
   here will continue to match up, or even that the tags will stay in
   the same order. Some phases might also be skipped (not reported) if the
-  associated bootstrap step is already complete.
+  associated bootstrap step is already complete, or if the phase no longer
+  is necessary.  Only "starting" and "done" are guaranteed to exist in all
+  future versions.
 
+  Current Tor versions enter these phases in order, monotonically;
+  future Tors MAY revisit earlier stages.
+
   Phase 0:
   tag=starting summary="starting"
 
@@ -76,9 +84,9 @@
   Phase 10
   tag=handshake_dir summary="Finishing handshake with directory mirror"
 
-  This event occurs when Tor establishes a TCP connection with a relay
-  (or its https proxy if it's using one). Tor remains in this phase until
-  the TLS handshake with the relay is finished.
+  This event occurs when Tor establishes a TCP connection with a relay used
+  as a directory mirror (or its https proxy if it's using one). Tor remains
+  in this phase until the TLS handshake with the relay is finished.
 
   Problems in this phase generally happen because Tor's firewall is
   doing more sophisticated MITM attacks on it, or doing packet-level
@@ -177,12 +185,10 @@
   a normal bootstrap event, but we also include 'warning' and 'reason'
   strings.
 
-  The reason string is the same argument as the reason string for ORCONN
-  failure events; the controller can recognize the various reasons
-  and help the user accordingly. The warning string currently tries to
-  provide the equivalent of strerror() -- this isn't very useful if the
-  controller can recognize reason tags and be smarter, but for a very
-  simple controller it should be better than nothing.
+  The reason strings are long-term-stable controller-facing tags to
+  identify particular issues in a bootstrapping step.  The warning
+  strings, on the other hand, are human-readable.  Controllers SHOULD
+  NOT rely on the format of any warning string.
 
   Currently Tor ignores the first nine bootstrap problem reports for
   a given phase, reports the tenth to the controller, and then ignores