bandwidth: edit bandwidth URL dir-spec and proposal

* dir-spec: don't post bandwidth files to other authorities
* dir-spec: add URL for current bandwidth file
* dir-spec: clean up the consensus and vote "current" publication schedule

Closes ticket #21377.

2 files changed, 39 insertions, 28 deletions

diff --git a/dir-spec.txt b/dir-spec.txt
index 388ad04..df74ca8 100644
--- a/dir-spec.txt
+++ b/dir-spec.txt
@@ -2607,19 +2607,19 @@
      http://<hostname>/tor/status-vote/next/bandwidth.z
 
    at the start of each voting period.
+
+   It MUST NOT attempt to send its bandwidth list file in a HTTP POST to
+   other authorities and it SHOULD NOT make bandwidth list files from other
+   authorities available.
+
    If an authority makes this file available, it MUST be the bandwidth file
    used to create the vote document available at
 
      http://<hostname>/tor/status-vote/next/authority.z
 
-   Once the voting period starts, the bandwidth list file SHOULD be available
-   at
+   The bandwidth list format is described in bandwidth-file-spec.txt.
 
-     http://<hostname>/tor/status-vote/next/bandwidth.z
-
-   The bandwidth list file is described in bandwidth-file-spec.txt.
-
-   First-appeared in Tor 0.3.5.
+   The standard URLs for bandwidth list files first-appeared in Tor 0.3.5.
 
 3.5. Downloading missing certificates from other directory authorities
 
@@ -3343,16 +3343,14 @@
 
 3.11. Publishing the signed consensus
 
-   Once there are enough signatures, or once the voting period starts,
-   these documents are available at
+   The voting period ends at the valid-after time. If the consensus has
+   been signed by a majority of authorities, these documents are made
+   available at
       http://<hostname>/tor/status-vote/current/consensus.z
    and
       http://<hostname>/tor/status-vote/current/consensus-signatures.z
    [XXX current/consensus-signatures is not currently implemented, as it
     is not used in the voting protocol.]
-   [XXX It's actually false that the first document is available as soon
-    as there are enough signatures. It's only available as soon as the
-    voting period starts. -KL]
 
    [XXX possible future features include support for downloading old
     consensuses.]
@@ -3361,13 +3359,15 @@
      http://<hostname>/tor/status-vote/current/authority.z
      http://<hostname>/tor/status-vote/current/<fp>.z
      http://<hostname>/tor/status-vote/current/d/<d>.z
-   once the consensus is complete.
+     http://<hostname>/tor/status-vote/current/bandwidth.z
+   once the voting period ends, regardless of the number of signatures.
 
    The authorities serve another consensus of each flavor "F" from the
    locations
       /tor/status-vote/(current|next)/consensus-F.z. and
       /tor/status-vote/(current|next)/consensus-F/<FP1>+....z.
 
+   The standard URLs for bandwidth list files first-appeared in Tor 0.3.5.
 
 4. Directory cache operation
 
diff --git a/proposals/xxx-expose-bwauth_votes.txt b/proposals/xxx-expose-bandwidth-files.txt
index 93a6f1a..12abe0e 100644
--- a/proposals/xxx-expose-bwauth_votes.txt
+++ b/proposals/xxx-expose-bandwidth-files.txt
@@ -1,5 +1,5 @@
-Filename: xxx-expose-bwauth_votes.txt
-Title: Have Directory Authorities expose raw bandwidth list file documents
+Filename: xxx-expose-bandwidth-files.txt
+Title: Have Directory Authorities expose raw bandwidth list files
 Author: Tom Ritter
 Created: 11-December-2017
 Status: Open
@@ -8,10 +8,10 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/21377
 1. Introduction
 
 Bandwidth Authorities (bwauths) perform scanning of the Tor Network
-and calculate observed speeds for each relay. They produce a bandwidth
+and calculate observed bandwidths for each relay. They produce a bandwidth
 list file that is given to a Directory Authority. The Directory
-Authority uses the speed value from this file in its vote file
-denoting its view of the speed of the relay.
+Authority uses the bw (bandwidth) value from this file in its vote file
+denoting its view of the bandwidth of the relay.
 
 After collecting all of the votes from other Authorities, a consensus
 is calculated, and the consensus's view of a relay's speed is
@@ -23,16 +23,21 @@ Directory Authority's vote, however the original file contains
 considerably more diagnostic information about how the bwauth arrives
 at that measurement for that relay.
 
+For more details, see the bandwidth list file specification in
+bandwidth-file-spec.txt.
+
 2. Motivation
 
 The bandwidth list file contains more information than is exposed in the
-overall vote file. This information is useful to debug anomalies in
-relays' utilization and suspected bugs in the (decrepit) bwauth code.
+overall vote file. This information is useful to debug:
+  * anomalies in relays' utilization,
+  * suspected bugs in the (decrepit) bwauth code, and
+  * the transition to a replacement bwauth implementation.
 
 Currently, all bwauths expose the bandwidth list file through various (non-
 standard) means, and that file is downloaded (hourly) by a single person
 (as long as his home internet connection and home server is working)
-and archived (with a small amount of robustness.)  
+and archived (with a small amount of robustness.)
 
 It would be preferable to have this exposed in a standard manner.
 Doing so would no longer require bwauths to run HTTP servers to expose
@@ -43,19 +48,25 @@ parties.  We hope that Collector will begin archiving the files.
 3. Specification
 
 An authority SHOULD publish the bandwidth list file used to calculate its
-current vote. It SHOULD make the bandwidth list file available at all
-times, and provide the file that it has most recently used for its
-vote (even if the vote is not currently published.) It SHOULD make
-the file available at
+next vote. It SHOULD make the bandwidth list file available whenever the
+corresponding vote is available, at the corresponding URL. (See
+dir-spec for the exact details.)
+
+It SHOULD make the file available at
   http://<hostname>/tor/status-vote/next/bandwidth.z
+  http://<hostname>/tor/status-vote/current/bandwidth.z
 
 It MUST NOT attempt to send its bandwidth list file in a HTTP POST to
 other authorities and it SHOULD NOT make bandwidth list files from other
 authorities available.
 
-Clients interested in consuming the document should download it when
-votes are created. (For the existing Tor network, this is at HH:50,
-or 50 minutes after each hour.)
+Clients interested in consuming these documents should download them from
+each authority's:
+  * next URL when votes are created. (In the public Tor network, this is
+    after HH:50 during normal operation, and after HH:20 during a
+    consensus failure.)
+  * current URL after the valid-after time in the consensus.
+    (After HH:00, and HH:30 during consensus failure.)
 
 4. Security Implications