Explain why we use "mark_as_used_for_origin_circuit" where we do

Also, explain why it's relevant for bootstrapping.

This is a comments-only patch.

4 files changed, 22 insertions, 2 deletions

diff --git a/src/core/or/channel.c b/src/core/or/channel.c
index 0765f222c1..c163f53488 100644
--- a/src/core/or/channel.c
+++ b/src/core/or/channel.c
@@ -2447,6 +2447,9 @@ channel_get_for_extend,(const char *rsa_id_digest,
       if (matches_target) {
         ++n_inprogress_goodaddr;
         if (for_origin_circ) {
+          /* We were looking for a connection for an origin circuit; this one
+           * matches, so we'll note that we decided to use it for an origin
+           * circuit. */
           channel_mark_as_used_for_origin_circuit(chan);
         }
       }
diff --git a/src/core/or/channeltls.c b/src/core/or/channeltls.c
index 2c52c07bb5..32723fed1e 100644
--- a/src/core/or/channeltls.c
+++ b/src/core/or/channeltls.c
@@ -365,7 +365,10 @@ channel_tls_handle_incoming(or_connection_t *orconn)
  * corresponding to the provided channel.
  *
  * This flag indicates that if the connection fails, it might be interesting
- * to the bootstrapping subsystem.
+ * to the bootstrapping subsystem.  (The bootstrapping system only cares about
+ * channels that we have tried to use for our own circuits.  Other channels
+ * may have been launched in response to EXTEND cells from somebody else, and
+ * if they fail, it won't necessarily indicate a bootstrapping problem.)
  **/
 void
 channel_mark_as_used_for_origin_circuit(channel_t *chan)
diff --git a/src/core/or/circuitbuild.c b/src/core/or/circuitbuild.c
index 225a0112f7..0b53a4cda8 100644
--- a/src/core/or/circuitbuild.c
+++ b/src/core/or/circuitbuild.c
@@ -591,6 +591,10 @@ circuit_handle_first_hop(origin_circuit_t *circ)
         log_info(LD_CIRC,"connect to firsthop failed. Closing.");
         return -END_CIRC_REASON_CONNECTFAILED;
       }
+      /* We didn't find a channel, but we're launching one for an origin
+       * circuit.  (If we decided not to launch a channel, then we found at
+       * least one once good in-progress channel use for this circuit, and
+       * marked it in channel_get_for_extend().) */
       channel_mark_as_used_for_origin_circuit(n_chan);
       circuit_chan_publish(circ, n_chan);
     }
@@ -604,6 +608,7 @@ circuit_handle_first_hop(origin_circuit_t *circ)
   } else { /* it's already open. use it. */
     tor_assert(!circ->base_.n_hop);
     circ->base_.n_chan = n_chan;
+    /* We found a channel, and we're using it for an origin circuit. */
     channel_mark_as_used_for_origin_circuit(n_chan);
     circuit_chan_publish(circ, n_chan);
     log_debug(LD_CIRC,"Conn open for %s. Delivering first onion skin.",
diff --git a/src/feature/control/control_bootstrap.c b/src/feature/control/control_bootstrap.c
index cca2a81b1f..d6dfdad94e 100644
--- a/src/feature/control/control_bootstrap.c
+++ b/src/feature/control/control_bootstrap.c
@@ -348,8 +348,17 @@ control_event_bootstrap_prob_or, (const char *warn, int reason,
 {
   int dowarn = 0;
 
-  if (! or_conn->potentially_used_for_bootstrapping)
+  if (! or_conn->potentially_used_for_bootstrapping) {
+    /* We never decided that this channel was a good match for one of our
+     * origin_circuit_t objects.  That means that we probably launched it
+     * for somebody else, most likely in response to an EXTEND cell.
+     *
+     * Since EXTEND cells can contain arbitrarily broken descriptions of
+     * relays, a failure on this connection here won't necessarily indicate a
+     * bootstrapping problem.
+     */
     return;
+  }
 
   if (or_conn->have_noted_bootstrap_problem)
     return;