start sending "COUNT=%d RECOMMENDATION=%s" key/values on bootstrap

problem status events, so the controller can hear about problems even
before tor decides they're worth reporting for sure.


svn:r15357

1 files changed, 22 insertions, 17 deletions

diff --git a/proposals/137-bootstrap-phases.txt b/proposals/137-bootstrap-phases.txt
index a77b033..fb949f8 100644
--- a/proposals/137-bootstrap-phases.txt
+++ b/proposals/137-bootstrap-phases.txt
@@ -30,7 +30,8 @@ Status: Open
 
   So in this case we send
   650 STATUS_CLIENT NOTICE/WARN BOOTSTRAP \
-  PROGRESS=num TAG=Keyword SUMMARY=String WARNING=String REASON=Keyword
+  PROGRESS=num TAG=Keyword SUMMARY=String \
+  [WARNING=String REASON=Keyword COUNT=num RECOMMENDATION=Keyword]
 
   The arguments MAY appear in any order. Controllers MUST accept unrecognized
   arguments.
@@ -47,8 +48,10 @@ Status: Open
   (severity notice) or an indication of a bootstrapping problem
   (severity warn). If severity warn, it should also include a "warning"
   argument string with any hints Tor has to offer about why it's having
-  troubles bootstrapping, and a "reason" string that lists of the reasons
-  allowed in the ORConn event.
+  troubles bootstrapping, a "reason" string that lists one of the reasons
+  allowed in the ORConn event, a "count" number that tells how many
+  bootstrap problems there have been so far at this phase, and a
+  "recommendation" keyword to indicate how the controller ought to react.
 
 3. The bootstrap phases.
 
@@ -182,21 +185,23 @@ Status: Open
   When an OR Conn fails, we send a "bootstrap problem" status event, which
   is like the standard bootstrap status event except with severity warn.
   We include the same progress, tag, and summary values as we would for
-  a normal bootstrap event, but we also include 'warning' and 'reason'
-  strings.
+  a normal bootstrap event, but we also include "warning", "reason",
+  "count", and "recommendation" key/value combos.
 
-  The reason strings are long-term-stable controller-facing tags to
+  The "reason" values 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
-  further problems at that phase. Hopefully this is a good balance between
-  tolerating occasional errors and reporting serious problems quickly. (We
-  will want to revisit this approach if there are many different 'reason'
-  values being reported among the first ten problem reports, since in
-  this case the controller will only hear one of them.)
+  strings, on the other hand, are human-readable. Controllers SHOULD
+  NOT rely on the format of any warning string. Currently the possible
+  values for "recommendation" are either "ignore" or "warn" -- if ignore,
+  the controller can accumulate the string in a pile of problems to show
+  the user if the user asks; if warn, the controller should alert the
+  user that Tor is pretty sure there's a bootstrapping problem.
+
+  Currently Tor uses recommendation=ignore for the first nine bootstrap
+  problem reports for a given phase, and then uses recommendation=warn
+  for subsequent problems at that phase. Hopefully this is a good
+  balance between tolerating occasional errors and reporting serious
+  problems quickly.
 
 5. Suggested controller behavior.
 
@@ -217,7 +222,7 @@ Status: Open
   Controllers should also have some mechanism to alert their user when
   bootstrapping problems are reported. Perhaps we should gather a set of
   help texts and the controller can send the user to the right anchor in a
-  "bootstrapping problems" help page?
+  "bootstrapping problems" page in the controller's help subsystem?
 
 6. Getting up to speed when the controller connects.