document running_long_enough_to_decide_unreachable()

It came as a surprise that Serge, the bridge authority, omits the Running
flag for all bridges in its first 30 minutes after a restart:
https://bugs.torproject.org/tpo/anti-censorship/rdsys/102

The fix we're doing for now is to accept it as correct behavior in
Tor, and change all the supporting tools to be able to handle bridge
networkstatus docs that have no Running bridges.

I'm documenting it here inside Tor too so the next person might not
be so surprised.

diff --git a/src/feature/dirauth/voteflags.c b/src/feature/dirauth/voteflags.c
index 05c19ff5012081ecb8d087c3d2d5dbf0b0ef3208..9aefc6c5b441aafa98163218d7da72aa121a6c44 100644 (file)
--- a/src/feature/dirauth/voteflags.c
+++ b/src/feature/dirauth/voteflags.c
@@ -457,7 +457,26 @@ dirserv_get_flag_thresholds_line(void)
   return result;
 }
 
-/* DOCDOC running_long_enough_to_decide_unreachable */
+/** Directory authorities should avoid expressing an opinion on the
+ * Running flag if their own uptime is too low for the opinion to be
+ * accurate. They implement this step by not listing Running on the
+ * "known-flags" line in their vote.
+ *
+ * The default threshold is 30 minutes, because authorities do a full
+ * reachability sweep of the ID space every 10*128=1280 seconds
+ * (see REACHABILITY_TEST_CYCLE_PERIOD).
+ *
+ * For v3 dir auths, as long as some authorities express an opinion about
+ * Running, it's fine if a few authorities don't. There's an explicit
+ * check, when making the consensus, to abort if *no* authorities list
+ * Running as a known-flag.
+ *
+ * For the bridge authority, if it doesn't vote about Running, the
+ * resulting networkstatus file simply won't list any bridges as Running.
+ * That means the supporting tools, like bridgedb/rdsys and onionoo, need
+ * to be able to handle getting a bridge networkstatus document with no
+ * Running flags. For more details, see
+ * https://bugs.torproject.org/tpo/anti-censorship/rdsys/102 */
 int
 running_long_enough_to_decide_unreachable(void)
 {