[tor-commits] [torspec/master] bandwidth: Add sbws and Tor versions where required

[nickm at torproject.org]

commit aa8807d3064a88b6b489373bd65ad9310a59beea
Author: teor <teor at torproject.org>
Date:   Mon Jan 14 11:27:38 2019 +1000

    bandwidth: Add sbws and Tor versions where required
---
 bandwidth-file-spec.txt | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt
index 05d1f40..e3a744f 100644
--- a/bandwidth-file-spec.txt
+++ b/bandwidth-file-spec.txt
@@ -59,9 +59,8 @@
 
   All Tor versions can consume format version 1.0.0.
   All Tor versions can consume format version 1.1.0 and later,
-  but they warn on additional header Lines.
-  [TODO: this might be fixed, and if it is fixed should be said which
-  version of Tor]
+  but Tor versions earlier than 0.3.5.1-alpha warn if the header
+  contains any KeyValue lines after the Timestamp.
 
 2. Format details
 
@@ -95,7 +94,8 @@
     KeyValue ::= Keyword "=" Value
     Value ::= ArgumentCharValue+
     ArgumentCharValue ::= any printing ASCII character except NL and SP.
-    Terminator ::= "====="
+    Terminator ::= "=====" or "===="
+      Note: sbws versions 0.1.0 to 1.0.2 used a 4-character terminator.
     Timestamp ::= Int
     Bandwidth ::= Int
     MasterKey ::= a base64-encoded Ed25519 public key, with
@@ -105,12 +105,13 @@
   Note that key_value and value are defined in Tor directory protocol
   with different formats to KeyValue and Value here.
 
-  All Lines in the file MUST be 510 characters or less, to allow for the
-  trailing newline and NULL characters.
-  The previous limit was 254 characters in Tor 0.2.6.2-alpha and
-  earlier.
-  The parser MAY ignore longer Lines.
-  [TODO: Change this restriction in 1.1.0 or later]
+  Tor versions earlier than 0.3.5.1-alpha require all lines in the file
+  to be 510 characters or less. The previous limit was 254 characters in
+  Tor 0.2.6.2-alpha and earlier. Parsers MAY ignore longer Lines.
+
+  Note that directory authorities are only supported on the two most
+  recent stable Tor versions, so we expect that line limits will be
+  removed after Tor 0.4.0 is released in 2019.
 
 2.2. Header List format
 
@@ -305,7 +306,7 @@ It consists of:
 
     In version 1.0.0, Header List ends when the first relay bandwidth
     is found conforming to the next section.
-    Implementations of version 1.1.0 SHOULD include this Line.
+    Implementations of version 1.1.0 and later SHOULD include this Line.
 
 2.3. Relays' Bandwidth List format
 
@@ -325,9 +326,6 @@ If a parser does not recognize any extra material in a RelayLine,
 the extra material MUST be ignored.
 
 Each RelayLine MUST include the following KeyValue pairs:
-In version 1.0.0, node_id MUST NOT be at the end of the Line.
-In version 1.1.0, the KeyValue can be in any arbitrary order.
-[TODO: list of Tor version that support it, when it's done]
 
   "node_id=" hexdigest
 
@@ -335,6 +333,10 @@ In version 1.1.0, the KeyValue can be in any arbitrary order.
 
     The fingerprint for the relay's RSA identity key.
 
+    Note: In bandwidth files read by Tor versions earlier than
+          0.3.4.1-alpha, node_id MUST NOT be at the end of the Line.
+          These authority versions are no longer supported.
+
   "master_key_ed25519=" MasterKey
 
     [Zero or one time.]
@@ -568,8 +570,8 @@ earliest_bandwidth=2018-04-16T15:13:26
 bw=380 error_circ=0 error_misc=0 error_stream=1 master_key_ed25519=YaqV4vbvPYKucElk297eVdNArDz9HtIwUoIeo0+cVIpQ nick=Test node_id=$68A483E05A2ABDCA6DA5A3EF8DB5177638A27F80 rtt=380 success=1 time=2018-05-08T16:13:26
 bw=189 error_circ=0 error_misc=0 error_stream=0 master_key_ed25519=a6a+dZadrQBtfSbmQkP7j2ardCmLnm5NJ4ZzkvDxbo0I nick=Test2 node_id=$96C15995F30895689291F455587BD94CA427B6FC rtt=378 success=1 time=2018-05-08T16:13:36
 
-A.3. Generated by sbws version 1.X.X
-[TODO: change the version of sbws that generates this when it is implemented]
+A.3. Generated by sbws version 1.0.3
+
 1523911758
 version=1.2.0
 latest_bandwidth=2018-04-16T20:49:18
@@ -582,8 +584,7 @@ number_consensus_relays=6436
 number_eligible_relays=6000
 percent_eligible_relays=93
 software=sbws
-software_version=1.X.X
-[TODO: change the version of sbws that generates this when it is implemented]
+software_version=1.0.3
 =====
 bw=38000 bw_mean=1127824 bw_median=1180062 desc_avg_bw=1073741824 desc_obs_bw_last=17230879 desc_obs_bw_mean=14732306 error_circ=0 error_misc=0 error_stream=1 master_key_ed25519=YaqV4vbvPYKucElk297eVdNArDz9HtIwUoIeo0+cVIpQ nick=Test node_id=$68A483E05A2ABDCA6DA5A3EF8DB5177638A27F80 rtt=380 success=1 time=2018-05-08T16:13:26
 bw=1 bw_mean=199162 bw_median=185675 desc_avg_bw=409600 desc_obs_bw_last=836165 desc_obs_bw_mean=858030 error_circ=0 error_misc=0 error_stream=0 master_key_ed25519=a6a+dZadrQBtfSbmQkP7j2ardCmLnm5NJ4ZzkvDxbo0I nick=Test2 node_id=$96C15995F30895689291F455587BD94CA427B6FC rtt=378 success=1 time=2018-05-08T16:13:36
@@ -602,8 +603,7 @@ number_consensus_relays=6436
 number_eligible_relays=2960
 percent_eligible_relays=46
 software=sbws
-software_version=1.X.X
-[TODO: change the version of sbws that generates this when it is implemented]
+software_version=1.0.3
 =====
 
 B. Scaling bandwidths