Explain Arti's `DirStatus` and Tor's `RST_OUTDATED_MD_DIRSERVER`

These have the same effect: They apply early in the guard selection
algorithm, at the same level as looking at `{is_reachable}`, and
they tell us that when we are making a one-hop directory circuit, we
should not use directory caches which we have seen to fail.

Arti's formulation treats this as a separate kind of
`{is_reachable}` with similar rules to the normal `{is_reachable}`
tristate.  C Tor's formulation treats it as a special kind of
restriction that needs to get different treatment from the other
kind of restrictions.  (This is the "permanent" vs "temporary"
distinction of tor#40876.)

I believe these formulations are equivalent, but Arti's is simpler
to describe.

See tor#23817 for historical discussion of how this feature was
implemented in C Tor.

1 files changed, 27 insertions, 1 deletions

diff --git a/spec/guard-spec/algorithm.md b/spec/guard-spec/algorithm.md
index 1dc0b18..0eaeb0e 100644
--- a/spec/guard-spec/algorithm.md
+++ b/spec/guard-spec/algorithm.md
@@ -62,6 +62,17 @@ non-persistently:
                 worth trying. A guard is "yes" reachable if we tried
                 it and succeeded.]
 
+               [Note 2: This variable is, in fact, a combination
+               of different context-sensitive variables depending
+               on the _purpose_ for which we are selecting a guard.
+               When we are selecing a guard for an ordinary
+               circuit, we look at the regular {is_reachable}.
+               But when we are selecting the guard for a one-hop
+               directory circuit, we also look at an instance
+	       of {is_reachable} that tracks whether
+	       downloads of the types we are making have failed
+	       recently.]
+
       - {tvar:failing_since}: The first time when we failed to
         connect to this guard. Defaults to "never".  Reset to
         "never" when we successfully connect to this guard.
@@ -364,7 +375,7 @@ Each of these transitions is described in sections below.
 
 <a id="guard-spec.txt-4.6"></a>
 
-## Selecting guards for circuits. \[Section:SELECTING\]
+## Selecting guards for circuits. \[Section:SELECTING\] {#SELECTING}
 
 Now that we have described the various lists of guards, we can explain how
 guards are chosen for each circuit.
@@ -474,6 +485,21 @@ is not reachable, we take the following steps:
 circuits in response to some of these steps; and also see
 \[ON_CONSENSUS\].\]
 
+\[Note 2: In the case of a one-hop circuit made for a directory
+request, it is possible for the request to fail _after_ the circuit
+is built: for example, if we ask for the latest consensus and we are
+told "404". In this case, we mark the appropriate directory-specific
+`{is_reachable}` instance for that guard to `<no>`.\]
+
+> C tor implements the above "note 2" by treating requests for
+> directory guards for as if they had an
+> extra type of restriction, rather than a separate instance of
+> `{is_reachable}`.  (For more on restrictions, see ["Selecting
+> Guards"](#SELECTING) above.)  This requires the C tor
+> impementation to special-case this restriction type, so that
+> it is treated the same way as an `{is_reachable}` variable.
+
+
 **Rationale**
 
 See \[SELECTING\] above for rationale.