hammer farther on the status events. still a lot of questions.

svn:r8745

1 files changed, 97 insertions, 40 deletions

diff --git a/doc/control-spec.txt b/doc/control-spec.txt
index 375e3eab7..47e0de2cf 100644
--- a/doc/control-spec.txt
+++ b/doc/control-spec.txt
@@ -194,7 +194,7 @@ $Id$
      EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
          "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /
          "AUTHDIR_NEWDESCS" / "DESCCHANGED" / "STATUS_GENERAL" /
-         "STATUS_CLIENT" / "STATUS_SERVER"
+         "STATUS_CLIENT" / "STATUS_SERVER" / "GUARDS"
 
   Any events *not* listed in the SETEVENTS line are turned off; thus, sending
   SETEVENTS with an empty body turns off all event reporting.
@@ -458,6 +458,21 @@ $Id$
       status events are available as getinfo's currently. Let us know if
       you want more exposed.)
 
+    "status/client"
+    "status/server"
+      These two special cases of internal Tor values return a (possibly
+      empty) list of status events from Section 4.1.10 that Tor believes
+      are still accurate. Controllers can use them to get a summary of
+      any current problems with Tor's operation.
+      [The answers should include notice events, not just warns and
+      errs, for example so Tor can learn whether any circuits have been
+      established yet.]
+      [Does this mean that Tor must keep state on its side of all the
+      statuses it's sent, and recognize when they're cancelled out,
+      and so on? It's a shame that Tor needs to do this and also Vidalia
+      needs to do this.]
+
+
   Examples:
      C: GETINFO version desc/name/moria1
      S: 250+desc/name/moria=
@@ -873,43 +888,24 @@ $Id$
   [Don't rely on any of these until we work out more of the details. -RD]
 
   Syntax:
-     "650" SP Type SP Action SP Arguments
-     Type = "STATUS_NOTICE" / "STATUS_WARN"
+     "650" SP Type SP Severity SP Action SP Arguments
+     Type = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
+     Severity = "NOTICE" / "WARN" / "ERR"
+
      Action is a string, and Arguments is a series of key=value
      pairs on the same line.
 
-  Actions for STATUS_NOTICE events can be as follows:
+     The reserved keyword "message" can optionally be used to provide a
+     string describing the nature of the action. Message strings MUST
+     NOT include items that a controller might be tempted to parse,
+     such as numbers.
 
-client notices:
-     CIRCUIT_ESTABLISHED
-       Tor is able to establish circuits for client use. This event will
-       only be sent if we just built a circuit that changed our mind --
-       that is, prior to this event we didn't know whether we could
-       establish circuits.
+  Actions for STATUS_GENERAL severity NOTICE events can be as follows:
 
-     DIR_ALL_UNREACHABLE
-       Tor believes that none of the known directory servers are
-       reachable -- this is most likely because the local network is
-       down or otherwise not working, and might help to explain for the
-       user why Tor appears to be broken.
+     [none yet]
 
-     GUARD_NODES_CHANGED
-
-server notices:
-     EXTERNAL_ADDRESS
-     "address=IP"
-     "method=guessed/resolved/..."
-
-     // hibernating
+  Actions for STATUS_GENERAL severity WARN events can be as follows:
 
-     CHECKING_REACHABILITY
-     "oraddress=IP:port"
-     "diraddress=IP:port"
-     "timeout=NUM"
-
-  Actions for STATUS_WARN events can be as follows:
-
-general warns:
      DANGEROUS_VERSION
      "current=version"
      "recommended=version,version,..."
@@ -923,6 +919,8 @@ general warns:
        also happens when the system is swapping so heavily that Tor is
        starving. The "time" argument includes the number of seconds Tor
        thinks it was unconscious for.
+       [This status event can generally be ignored by the controller,
+       since we don't really know what the user should do anyway. Hm.]
 
      TOO_MANY_CONNECTIONS
      "limit=NUM"
@@ -938,15 +936,41 @@ general warns:
        the controller can explain this to the user and encourage her to
        file a bug report?
 
-     // unexpected dir response. behind a hotel/airport firewall?
+     [The following two are sent as WARNs if CIRCUIT_ESTABLISHED and
+     not DIR_ALL_UNREACHABLE, else as ERRs:]
 
-     // bad http or https proxy?
+     BAD_DIR_RESPONSE
+     // unexpected dir response. behind a hotel/airport firewall?
 
-     // clock is skewed
+     CLOCK_SKEWED
      // (either from talking to a dir authority, or from perusing a
      //  network-status timestamp)
 
-client warns:
+  Actions for STATUS_GENERAL severity ERR events can be as follows:
+
+     BAD_PROXY
+     // bad http or https proxy?
+
+     DIR_ALL_UNREACHABLE
+       Tor believes that none of the known directory servers are
+       reachable -- this is most likely because the local network is
+       down or otherwise not working, and might help to explain for the
+       user why Tor appears to be broken.
+
+  Actions for STATUS_CLIENT severity NOTICE events can be as follows:
+
+     CIRCUIT_ESTABLISHED
+       Tor is able to establish circuits for client use. This event will
+       only be sent if we just built a circuit that changed our mind --
+       that is, prior to this event we didn't know whether we could
+       establish circuits.
+
+     ENOUGH_DIR_INFO
+       Tor now knows enough network-status documents and enough server
+       descriptors that it's going to start trying to build circuits now.
+
+  Actions for STATUS_CLIENT severity WARN events can be as follows:
+
      DANGEROUS_SOCKS
      "protocol=socks4/socks4a/socks5"
      "address=IP:port"
@@ -961,7 +985,29 @@ client warns:
      // a nickname we asked for is unavailable. no need for this
      // quite yet, since no end-user controllers let you configure that.
 
-server warns:
+  Actions for STATUS_CLIENT severity ERR events can be as follows:
+
+     [none yet]
+
+  Actions for STATUS_SERVER severity NOTICE events can be as follows:
+
+     EXTERNAL_ADDRESS
+     "address=IP"
+     "method=guessed/resolved/..."
+
+     // hibernating
+
+     CHECKING_REACHABILITY
+     "oraddress=IP:port"
+     "diraddress=IP:port"
+     "timeout=NUM"
+
+     GOOD_SERVER_DESCRIPTOR
+       We successfully uploaded our server descriptor to each of the
+       directory authorities, with no complaints.
+
+  Actions for STATUS_SERVER severity WARN events can be as follows:
+
      // something about failing to parse our address?
      // from resolve_my_address() in config.c
 
@@ -969,18 +1015,29 @@ server warns:
 
      // too many onions queued. threading problem or slow cpu?
 
-     REACHABILITY_FAILED
-     "oraddress=IP:port"
-     "diraddress=IP:port"
+     // eventdns statements. like, hijacked dns.
 
+     BAD_SERVER_DESCRIPTOR
+     "dirauth=nickname"
      // dir authorities didn't like my descriptor
 
-     // eventdns statements. like, hijacked dns.
+  Actions for STATUS_SERVER severity ERR events can be as follows:
 
+     REACHABILITY_FAILED
+     "oraddress=IP:port"
+     "diraddress=IP:port"
 
   Controllers must tolerate hearing about actions that they don't
   recognize.
 
+4.1.11. Our set of guard nodes has changed
+
+  Syntax:
+     "650" SP "GUARDS" SP Type SP ...
+     Type = "ENTRY"
+     ...
+  [needs to be fleshed out; not implemented yet]
+
 5. Implementation notes
 
 5.1. Authentication