diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-11-01 08:52:54 -0400 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-11-01 08:52:54 -0400 |
commit | 00ae47caf7cf645b077f6d1b3e3c6e831c51b271 (patch) | |
tree | fc4c83475adda0998fd2bc7db117d51efcb120e0 | |
parent | a99440cd08200d8a860ed8db374805349a16070d (diff) | |
download | torspec-00ae47caf7cf645b077f6d1b3e3c6e831c51b271.tar.gz torspec-00ae47caf7cf645b077f6d1b3e3c6e831c51b271.zip |
guard algorithm: de-indent to avoid verbatim-status.
-rw-r--r-- | spec/guard-spec/algorithm.md | 112 |
1 files changed, 56 insertions, 56 deletions
diff --git a/spec/guard-spec/algorithm.md b/spec/guard-spec/algorithm.md index e109806..8a3e1ca 100644 --- a/spec/guard-spec/algorithm.md +++ b/spec/guard-spec/algorithm.md @@ -318,71 +318,71 @@ cells, and INTRODUCE cells on `<complete>` circuits.) The per-circuit state machine is: - * New circuits are `<usable_on_completion>` or - `<usable_if_no_better_guard>`. + * New circuits are `<usable_on_completion>` or + `<usable_if_no_better_guard>`. - * A `<usable_on_completion>` circuit may become `<complete>`, or may - fail. + * A `<usable_on_completion>` circuit may become `<complete>`, or may + fail. - * A `<usable_if_no_better_guard>` circuit may become - `<usable_on_completion>`; may become `<waiting_for_better_guard>`; or may - fail. + * A `<usable_if_no_better_guard>` circuit may become + `<usable_on_completion>`; may become `<waiting_for_better_guard>`; or may + fail. - * A `<waiting_for_better_guard>` circuit will become `<complete>`, or will - be closed, or will fail. + * A `<waiting_for_better_guard>` circuit will become `<complete>`, or will + be closed, or will fail. - * A `<complete>` circuit remains `<complete>` until it fails or is - closed. + * A `<complete>` circuit remains `<complete>` until it fails or is + closed. - * Each of these transitions is described below. + * Each of these transitions is described below. We keep, as global transient state: - * {tvar:last_time_on_internet} -- the last time at which we - successfully used a circuit or connected to a guard. At - startup we set this to "infinitely far in the past." + * {tvar:last_time_on_internet} -- the last time at which we + successfully used a circuit or connected to a guard. At + startup we set this to "infinitely far in the past." When we want to build a circuit, and we need to pick a guard: - * If any entry in PRIMARY_GUARDS has {is_reachable} status of - `<maybe>` or `<yes>`, check the first {NUM_USABLE_PRIMARY_GUARDS} or - {NUM_USABLE_PRIMARY_DIRECTORY_GUARDS} such guards against - any path selection restrictions, to build a temporary list of - usable guards. If the path restriction is circuit-specific and - excludes a primary guard, do not use that guard, but still - increment the number of usable guards that were considered. - If the restriction causes the number of guards considered to - exceed either usable limit count, then proceed to select another - primary guard. - - This usable list is temporary, but because the primary guard ordering - is persistent, it will be a stable set. At the end of this selection - process, chose uniformly at random from this usable list. The - circuit is `<usable_on_completion>`. - - [Note: We do not use {is_pending} on primary guards, since we - are willing to try to build multiple circuits through them - before we know for sure whether they work, and since we will - not use any non-primary guards until we are sure that the - primary guards are all down. (XX is this good?)] - - * Otherwise, if the ordered intersection of {CONFIRMED_GUARDS} - and {USABLE_FILTERED_GUARDS} is nonempty, return the first - entry in that intersection that has {is_pending} set to - false. Set its value of {is_pending} to true, - and set its {pending_since} to the current time. - The circuit - is now `<usable_if_no_better_guard>`. (If all entries have - {is_pending} true, pick the first one.) - - * Otherwise, if there is no such entry, select a member from - {USABLE_FILTERED_GUARDS} in sample order. Set its {is_pending} field to - true, and set its {pending_since} to the current time. - The circuit is `<usable_if_no_better_guard>`. - - * Otherwise, if USABLE_FILTERED_GUARDS is empty, we have exhausted - all the sampled guards. In this case we proceed by marking all guards - as `<maybe>` reachable so that we can keep on trying circuits. + * If any entry in PRIMARY_GUARDS has {is_reachable} status of + `<maybe>` or `<yes>`, check the first {NUM_USABLE_PRIMARY_GUARDS} or + {NUM_USABLE_PRIMARY_DIRECTORY_GUARDS} such guards against + any path selection restrictions, to build a temporary list of + usable guards. If the path restriction is circuit-specific and + excludes a primary guard, do not use that guard, but still + increment the number of usable guards that were considered. + If the restriction causes the number of guards considered to + exceed either usable limit count, then proceed to select another + primary guard. + + This usable list is temporary, but because the primary guard ordering + is persistent, it will be a stable set. At the end of this selection + process, chose uniformly at random from this usable list. The + circuit is `<usable_on_completion>`. + + [Note: We do not use {is_pending} on primary guards, since we + are willing to try to build multiple circuits through them + before we know for sure whether they work, and since we will + not use any non-primary guards until we are sure that the + primary guards are all down. (XX is this good?)] + + * Otherwise, if the ordered intersection of {CONFIRMED_GUARDS} + and {USABLE_FILTERED_GUARDS} is nonempty, return the first + entry in that intersection that has {is_pending} set to + false. Set its value of {is_pending} to true, + and set its {pending_since} to the current time. + The circuit + is now `<usable_if_no_better_guard>`. (If all entries have + {is_pending} true, pick the first one.) + + * Otherwise, if there is no such entry, select a member from + {USABLE_FILTERED_GUARDS} in sample order. Set its {is_pending} field to + true, and set its {pending_since} to the current time. + The circuit is `<usable_if_no_better_guard>`. + + * Otherwise, if USABLE_FILTERED_GUARDS is empty, we have exhausted + all the sampled guards. In this case we proceed by marking all guards + as `<maybe>` reachable so that we can keep on trying circuits. Whenever we select a guard for a new circuit attempt, we update the {last_tried_connect} time for the guard to 'now.' @@ -398,8 +398,8 @@ that circuit, since we will need them later (see \[UPDATE_WAITING\].). We're getting to the core of the algorithm here. Our main goals are to make sure that - 1. If it's possible to use a primary guard, we do. - 2. We probably use the first primary guard. + 1. If it's possible to use a primary guard, we do. + 2. We probably use the first primary guard. So we only try non-primary guards if we're pretty sure that all the primary guards are down, and we only try a given primary guard |