From 2ea4910e4281507e5304bbd6ddafc2bea8c5fbdd Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Wed, 10 Jan 2007 16:33:56 +0000
Subject: [PATCH]  r11915@dhcp-18-188-69-59:  nickm | 2007-01-10 11:24:40 -0500
  Notes about deprecation and status events in control-spec

svn:r9320
---
 doc/control-spec-v0.txt |  3 ++-
 doc/control-spec.txt    | 49 ++++++++++++++++++++++++++++-------------
 2 files changed, 36 insertions(+), 16 deletions(-)

diff --git a/doc/control-spec-v0.txt b/doc/control-spec-v0.txt
index 4c64040acb..faf75a64a4 100644
--- a/doc/control-spec-v0.txt
+++ b/doc/control-spec-v0.txt
@@ -6,7 +6,8 @@ $Id$
 
 THIS PROTOCOL IS DEPRECATED.  It is still documented here because Tor
 0.1.1.x happens to support much of it; but the support for v0 is not
-maintained, so you should expect it to rot in unpredictable ways.
+maintained, so you should expect it to rot in unpredictable ways.  Support
+for v0 will be removed some time after Tor 0.1.2.
 
 0. Scope
 
diff --git a/doc/control-spec.txt b/doc/control-spec.txt
index 106564c225..1904a0fa32 100644
--- a/doc/control-spec.txt
+++ b/doc/control-spec.txt
@@ -489,16 +489,11 @@ $Id$
 
     "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.-RD]
-        [notice, warn, and errs need to be separated here, though.
-        Otherwise, when we add a new status event type in the future,
-        controllers won't know whether it's good or bad. -NM]
+    "status/general"
+      These provide a (possibly empty) newline-separated 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.
 
       [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,
@@ -794,8 +789,8 @@ $Id$
      S: 650 CIRC 1000 EXTENDED moria1,moria2
      S: 250 ORPORT=0
 
-  Clients SHOULD tolerate more arguments in an asynchonous reply than
-  expected, and SHOULD tolerate more lines in an asynchronous reply than
+  Clients MUST tolerate more arguments in an asynchonous reply than
+  expected, and MUST tolerate more lines in an asynchronous reply than
   expected.  For instance, a client that expects a CIRC message like:
       650 CIRC 1000 EXTENDED moria1,moria2
   should tolerate:
@@ -954,12 +949,25 @@ $Id$
 
 4.1.10. Status events
 
+  Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent
+  based on occurrences in the Tor process pertaining to the general state of
+  the program.  Generally, they correspond to log messages of severity Notice
+  or higher.  They differ from log messages in that their format is a
+  specified interface.
+
   [Don't rely on any of these until we work out more of the details. -RD]
 
   Syntax:
-     "650" SP Type SP Severity SP Action SP Arguments
-     Type = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
-     Severity = "NOTICE" / "WARN" / "ERR"
+     "650" SP StatusType SP StatusSeverity SP StatusAction
+                                         [SP StatusArguments] CRLF
+
+     StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
+     StatusSeverity = "NOTICE" / "WARN" / "ERR"
+     StatusAction = 1*ALPHA
+     StatusArguments = StatusArgument *(SP StatusArgument)
+     StatusArgument = StatusKeyword '=' StatusValue
+     StatusKeyword = 1*(ALNUM / "_")
+     StatusValue = 1*(ALNUM / '_')  / QuotedString
 
      Action is a string, and Arguments is a series of keyword=value
      pairs on the same line.  Values may be space-terminated strings,
@@ -969,6 +977,10 @@ $Id$
      VERBOSE_NAMES; see the explanations in the USEFEATURE section
      for details.
 
+     Controllers MUST tolerate unrecognized actions and arguments, MUST
+     tolerate missing arguments, and MUST tolerate arguments that arrive
+     in any order.
+
   Actions for STATUS_GENERAL events can be as follows:
 
      CLOCK_JUMPED
@@ -999,6 +1011,13 @@ do for each. -RD]
      "CURRENT=version"
      "REASON=NEW/OLD/UNRECOMMENDED"
      "RECOMMENDED=\"version, version, ...\""
+       Tor has found that directory servers don't recommend its version of
+       the Tor software.  RECOMMENDED is a comma-and-space-separated string
+       of Tor versions that are recommended.  REASON is NEW if this version
+       of Tor is newer than any recommended version, OLD if this version of
+       Tor is older than any recommended version, and UNRECOMMENDED if
+       some recommended versions of Tor are newer and some are old than this
+       version.
 
      TOO_MANY_CONNECTIONS
      "CURRENT=NUM"