Browse Source

Correct grammars to reflect that VERBOSE_NAMES is part of the protocol.

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.
Poet (Tim Sally) 15 years ago
parent
commit
87158368dc
1 changed files with 35 additions and 13 deletions
  1. 35 13
      doc/spec/control-spec.txt

+ 35 - 13
doc/spec/control-spec.txt

@@ -480,21 +480,28 @@
          StreamID SP StreamStatus SP CircID SP Target CRLF
          StreamID SP StreamStatus SP CircID SP Target CRLF
 
 
     "orconn-status"
     "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
          ServerID SP ORStatus CRLF
 
 
     "entry-guards"
     "entry-guards"
       A series of lines listing the currently chosen entry guards, if any.
       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
          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".
       [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
        Tor still supports calling it that for now, but support will be
        removed in 0.1.3.x.]
        removed in 0.1.3.x.]
@@ -1004,7 +1011,11 @@
                "FAILED"   / ; circuit closed (was not built)
                "FAILED"   / ; circuit closed (was not built)
                "CLOSED"     ; circuit closed (was 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" /
       Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
                "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
                "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
@@ -1093,19 +1104,26 @@
 4.1.3. OR Connection status changed
 4.1.3. OR Connection status changed
 
 
   The syntax is:
   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
              Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
 
 
     ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
     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
   NEW is for incoming connections, and LAUNCHED is for outgoing
   connections. CONNECTED means the TLS handshake has finished (in
   connections. CONNECTED means the TLS handshake has finished (in
   either direction). FAILED means a connection is being closed that
   either direction). FAILED means a connection is being closed that
   hasn't finished its handshake, and CLOSED is for connections that
   hasn't finished its handshake, and CLOSED is for connections that
   have handshaked.
   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
   If extended events are enabled (see 3.19), optional reason and
   circuit counting information is provided for CLOSED and FAILED
   circuit counting information is provided for CLOSED and FAILED
@@ -1142,7 +1160,11 @@
 4.1.6. New descriptors available
 4.1.6. New descriptors available
 
 
   Syntax:
   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
 4.1.7. New Address mapping