[or-cvs] [tor/maint-0.2.2 3/5] Correct grammars to reflect that VERBOSE_NAMES is part of the protocol.

[nickm at torproject.org]

Author: Poet (Tim Sally) <poet at stack.io>
Date: Wed, 1 Dec 2010 05:25:17 -0600
Subject: Correct grammars to reflect that VERBOSE_NAMES is part of the protocol.
Commit: 87158368dc02350d7eda43cbadc00a3cfc4d8815

Several updates to grammars for events and GETINFO results.  All relate
to the fact that LongName has replaced ServerID since 0.2.2.1-alpha. See
documentation of VERBOSE_NAMES for more information. The following
grammars were changed:
  * orconn-status GETINFO result
  * entry-guards GETINFO result
  * Path general token
  * OR Connection status changed event
  * New descriptors available event
In all cases a note was added about when the old grammar applies.
---
 doc/spec/control-spec.txt |   48 ++++++++++++++++++++++++++++++++------------
 1 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt
index 1b9a692..14b5903 100644
--- a/doc/spec/control-spec.txt
+++ b/doc/spec/control-spec.txt
@@ -480,21 +480,28 @@
          StreamID SP StreamStatus SP CircID SP Target CRLF
 
     "orconn-status"
-      A series of lines as for an OR connection status event.  Each is of the
-      form:
+      A series of lines as for an OR connection status event.  In Tor
+      0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
+      0.2.2.1-alpha and later by default, each line is of the form:
+         LongName SP ORStatus CRLF
+
+     Before 0.1.2.2-alpha, each line is of the form:
          ServerID SP ORStatus CRLF
 
     "entry-guards"
       A series of lines listing the currently chosen entry guards, if any.
-      Each is of the form:
-         ServerID2 SP Status [SP ISOTime] CRLF
-
-         Status-with-time = ("unlisted") SP ISOTime
-         Status = ("up" / "never-connected" / "down" /
-                      "unusable" / "unlisted" )
+      In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
+      0.2.2.1-alpha and later by default, each line is of the form:
+         LongName SP Status [SP ISOTime] CRLF
 
+      Before 0.1.2.2-alpha, each line is of the form:
+         ServerID2 SP Status [SP ISOTime] CRLF
          ServerID2 = Nickname / 40*HEXDIG
 
+      The definition of Status is the same for both:
+         Status = "up" / "never-connected" / "down" /
+                  "unusable" / "unlisted"
+
       [From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes".
        Tor still supports calling it that for now, but support will be
        removed in 0.1.3.x.]
@@ -1004,7 +1011,11 @@
                "FAILED"   / ; circuit closed (was not built)
                "CLOSED"     ; circuit closed (was built)
 
-      Path = ServerID *("," ServerID)
+      Path = LongName *("," LongName)
+        ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
+        ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path
+        ; is as follows:
+        Path = ServerID *("," ServerID)
 
       Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
                "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
@@ -1093,19 +1104,26 @@
 4.1.3. OR Connection status changed
 
   The syntax is:
-    "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
+
+    "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
              Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
 
     ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
 
+        ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
+        ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR
+        ; Connection is as follows:
+        "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
+                 Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
+
   NEW is for incoming connections, and LAUNCHED is for outgoing
   connections. CONNECTED means the TLS handshake has finished (in
   either direction). FAILED means a connection is being closed that
   hasn't finished its handshake, and CLOSED is for connections that
   have handshaked.
 
-  A ServerID is specified unless it's a NEW connection, in which
-  case we don't know what server it is yet, so we use Address:Port.
+  A LongName or ServerID is specified unless it's a NEW connection, in
+  which case we don't know what server it is yet, so we use Address:Port.
 
   If extended events are enabled (see 3.19), optional reason and
   circuit counting information is provided for CLOSED and FAILED
@@ -1142,7 +1160,11 @@
 4.1.6. New descriptors available
 
   Syntax:
-     "650" SP "NEWDESC" 1*(SP ServerID) CRLF
+     "650" SP "NEWDESC" 1*(SP LongName) CRLF
+        ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
+        ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it
+        ; is as follows:
+        "650" SP "NEWDESC" 1*(SP ServerID) CRLF
 
 4.1.7. New Address mapping
 
-- 
1.7.1