aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNick Mathewson <nickm@torproject.org>2023-11-01 08:51:20 -0400
committerNick Mathewson <nickm@torproject.org>2023-11-01 08:51:20 -0400
commita99440cd08200d8a860ed8db374805349a16070d (patch)
treea06a6fb457f74c4d06d0fbeb4f6863955241046c
parentbf1bf17eebbbe2b616ebd6ed2f7990cc20bfce2b (diff)
downloadtorspec-a99440cd08200d8a860ed8db374805349a16070d.tar.gz
torspec-a99440cd08200d8a860ed8db374805349a16070d.zip
guard algorithm: reformat a section to avoid ```s.
-rw-r--r--spec/guard-spec/algorithm.md44
1 files changed, 19 insertions, 25 deletions
diff --git a/spec/guard-spec/algorithm.md b/spec/guard-spec/algorithm.md
index e63031b..e109806 100644
--- a/spec/guard-spec/algorithm.md
+++ b/spec/guard-spec/algorithm.md
@@ -307,12 +307,10 @@ now from the fact that it was unreachable a few minutes ago.
Every origin circuit is now in one of these states:
-```text
- <state:usable_on_completion>,
- <state:usable_if_no_better_guard>,
- <state:waiting_for_better_guard>, or
- <state:complete>.
-```
+ * `<state:usable_on_completion>`
+ * `<state:usable_if_no_better_guard>`
+ * `<state:waiting_for_better_guard>`
+ * `<state:complete>`
You may only attach streams to `<complete>` circuits.
(Additionally, you may only send RENDEZVOUS cells, ESTABLISH_INTRO
@@ -320,35 +318,34 @@ cells, and INTRODUCE cells on `<complete>` circuits.)
The per-circuit state machine is:
-```text
- 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
+ * 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
+ * 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
+ * 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
+ * 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:
+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."
- When we want to build a circuit, and we need to pick a guard:
+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
+ `<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
@@ -361,7 +358,7 @@ The per-circuit state machine is:
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>.
+ 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
@@ -375,18 +372,17 @@ The per-circuit state machine is:
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 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>.
+ 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.
-```
+ 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.'
@@ -402,10 +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
-```text
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