docs: explain how the second relay is selected

docs/source/activity_second_relay.puml

+@startuml
+
+start
+
+if (relay to measure is exit?) then (yes)
+  :obtain non-exits;
+else (no)
+  :obtain an exits
+  without bad flag
+  that can exit
+  to port 443;
+endif
+:potential second relays;
+:obtain a relay
+from potential
+sencond relays
+randomly;
+if (second relay has 2x bandwidth?) then (yes)
+elseif (other second relay has 1.5x bandwidth?) then (yes)
+elseif (other second relay has 1x bandwidth?) then (yes)
+else (nothing)
+  stop
+endif
+:second relay selected!;
+:Build a circuit
+whith exit as
+second hop;
+stop
+
+@enduml
\ No newline at end of file

docs/source/images/activity_second_relay.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="625px" preserveAspectRatio="none" style="width:812px;height:625px;" version="1.1" viewBox="0 0 812 625" width="812px" zoomAndPan="magnify"><defs><filter height="300%" id="fd9ikek" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><ellipse cx="415" cy="20" fill="#000000" filter="url(#fd9ikek)" rx="10" ry="10" style="stroke: none; stroke-width: 1.0;"/><polygon fill="#FEFECE" filter="url(#fd9ikek)" points="344,50,486,50,498,62,486,74,344,74,332,62,344,50" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="142" x="344" y="65.8081">relay to measure is exit?</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="20" x="312" y="59.4058">yes</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="14" x="498" y="59.4058">no</text><rect fill="#FEFECE" filter="url(#fd9ikek)" height="33.9688" rx="12.5" ry="12.5" style="stroke: #A80036; stroke-width: 1.5;" width="121" x="261.5" y="84"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="101" x="271.5" y="105.1387">obtain non-exits</text><rect fill="#FEFECE" filter="url(#fd9ikek)" height="75.875" rx="12.5" ry="12.5" style="stroke: #A80036; stroke-width: 1.5;" width="121" x="447.5" y="84"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="93" x="457.5" y="105.1387">obtain an exits</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="101" x="457.5" y="119.1074">without bad flag</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="79" x="457.5" y="133.0762">that can exit</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="71" x="457.5" y="147.0449">to port 443</text><polygon fill="#FEFECE" filter="url(#fd9ikek)" points="415,165.875,427,177.875,415,189.875,403,177.875,415,165.875" style="stroke: #A80036; stroke-width: 1.5;"/><rect fill="#FEFECE" filter="url(#fd9ikek)" height="33.9688" rx="12.5" ry="12.5" style="stroke: #A80036; stroke-width: 1.5;" width="167" x="331.5" y="209.875"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="147" x="341.5" y="231.0137">potential second relays</text><rect fill="#FEFECE" filter="url(#fd9ikek)" height="75.875" rx="12.5" ry="12.5" style="stroke: #A80036; stroke-width: 1.5;" width="115" x="357.5" y="263.8438"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="86" x="367.5" y="284.9824">obtain a relay</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="88" x="367.5" y="298.9512">from potential</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="95" x="367.5" y="312.9199">sencond relays</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="57" x="367.5" y="326.8887">randomly</text><polygon fill="#FEFECE" filter="url(#fd9ikek)" points="32,359.7188,215,359.7188,227,371.7188,215,383.7188,32,383.7188,20,371.7188,32,359.7188" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="20" x="127.5" y="393.9292">yes</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="183" x="32" y="375.5269">second relay has 2x bandwidth?</text><polygon fill="#FEFECE" filter="url(#fd9ikek)" points="259,359.7188,487,359.7188,499,371.7188,487,383.7188,259,383.7188,247,371.7188,259,359.7188" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="20" x="377" y="393.9292">yes</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="228" x="259" y="375.5269">other second relay has 1.5x bandwidth?</text><polygon fill="#FEFECE" filter="url(#fd9ikek)" points="531,359.7188,748,359.7188,760,371.7188,748,383.7188,531,383.7188,519,371.7188,531,359.7188" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="20" x="643.5" y="393.9292">yes</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="217" x="531" y="375.5269">other second relay has 1x bandwidth?</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacingAndGlyphs" textLength="42" x="760" y="369.1245">nothing</text><ellipse cx="795" cy="413.1211" fill="none" filter="url(#fd9ikek)" rx="10" ry="10" style="stroke: #000000; stroke-width: 1.0;"/><ellipse cx="795.5" cy="413.6211" fill="#000000" filter="url(#fd9ikek)" rx="6" ry="6" style="stroke: none; stroke-width: 1.0;"/><rect fill="#FEFECE" filter="url(#fd9ikek)" height="33.9688" rx="12.5" ry="12.5" style="stroke: #A80036; stroke-width: 1.5;" width="163" x="333.5" y="463.1211"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="143" x="343.5" y="484.2598">second relay selected!</text><rect fill="#FEFECE" filter="url(#fd9ikek)" height="61.9063" rx="12.5" ry="12.5" style="stroke: #A80036; stroke-width: 1.5;" width="104" x="363" y="517.0898"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="84" x="373" y="538.2285">Build a circuit</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="78" x="373" y="552.1973">whith exit as</text><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacingAndGlyphs" textLength="74" x="373" y="566.166">second hop</text><ellipse cx="415" cy="608.9961" fill="none" filter="url(#fd9ikek)" rx="10" ry="10" style="stroke: #000000; stroke-width: 1.0;"/><ellipse cx="415.5" cy="609.4961" fill="#000000" filter="url(#fd9ikek)" rx="6" ry="6" style="stroke: none; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="332" x2="322" y1="62" y2="62"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="322" x2="322" y1="62" y2="84"/><polygon fill="#A80036" points="318,74,322,84,326,74,322,78" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="498" x2="508" y1="62" y2="62"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="508" x2="508" y1="62" y2="84"/><polygon fill="#A80036" points="504,74,508,84,512,74,508,78" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="322" x2="322" y1="117.9688" y2="177.875"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="322" x2="403" y1="177.875" y2="177.875"/><polygon fill="#A80036" points="393,173.875,403,177.875,393,181.875,397,177.875" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="508" x2="508" y1="159.875" y2="177.875"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="508" x2="427" y1="177.875" y2="177.875"/><polygon fill="#A80036" points="437,173.875,427,177.875,437,181.875,433,177.875" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="30" y2="50"/><polygon fill="#A80036" points="411,40,415,50,419,40,415,44" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="189.875" y2="209.875"/><polygon fill="#A80036" points="411,199.875,415,209.875,419,199.875,415,203.875" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="243.8438" y2="263.8438"/><polygon fill="#A80036" points="411,253.8438,415,263.8438,419,253.8438,415,257.8438" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="123.5" x2="123.5" y1="383.7188" y2="443.1211"/><polygon fill="#A80036" points="119.5,433.1211,123.5,443.1211,127.5,433.1211,123.5,437.1211" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="373" x2="373" y1="383.7188" y2="443.1211"/><polygon fill="#A80036" points="369,433.1211,373,443.1211,377,433.1211,373,437.1211" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="639.5" x2="639.5" y1="383.7188" y2="443.1211"/><polygon fill="#A80036" points="635.5,433.1211,639.5,443.1211,643.5,433.1211,639.5,437.1211" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="227" x2="247" y1="371.7188" y2="371.7188"/><polygon fill="#A80036" points="237,367.7188,247,371.7188,237,375.7188,241,371.7188" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="499" x2="519" y1="371.7188" y2="371.7188"/><polygon fill="#A80036" points="509,367.7188,519,371.7188,509,375.7188,513,371.7188" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="339.7188" y2="344.7188"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="123.5" y1="344.7188" y2="344.7188"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="123.5" x2="123.5" y1="344.7188" y2="359.7188"/><polygon fill="#A80036" points="119.5,349.7188,123.5,359.7188,127.5,349.7188,123.5,353.7188" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="760" x2="795" y1="371.7188" y2="371.7188"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="795" x2="795" y1="371.7188" y2="403.1211"/><polygon fill="#A80036" points="791,393.1211,795,403.1211,799,393.1211,795,397.1211" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="123.5" x2="639.5" y1="443.1211" y2="443.1211"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="443.1211" y2="463.1211"/><polygon fill="#A80036" points="411,453.1211,415,463.1211,419,453.1211,415,457.1211" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="497.0898" y2="517.0898"/><polygon fill="#A80036" points="411,507.0898,415,517.0898,419,507.0898,415,511.0898" style="stroke: #A80036; stroke-width: 1.0;"/><line style="stroke: #A80036; stroke-width: 1.5;" x1="415" x2="415" y1="578.9961" y2="598.9961"/><polygon fill="#A80036" points="411,588.9961,415,598.9961,419,588.9961,415,592.9961" style="stroke: #A80036; stroke-width: 1.0;"/></g></svg>
\ No newline at end of file

docs/source/specification.rst

@@ -132,6 +132,24 @@ Measuring relays
 
 Source code: :func:`sbws.core.scanner.measure_relay`
 
+Selecting a second relay
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. If the relay to measure is an exit, use it as an exit and obtain the
+   non-exits.
+#. If the relay to measure is not an exit, use it as first hop and obtain
+   the exits.
+#. From non-exits or exits, select one randomly from the ones that have
+   double consensus bandwidth than the relay to measure.
+#. If there are no relays that satisfy this, lower the required bandwidth.
+
+.. image:: ./images/activity_second_relay.svg
+   :alt: activity select second relay
+   :height: 400px
+   :align: center
+
+Source code: :func:`sbws.core.scanner.measure_relay`
+
 Simple result storage
 ~~~~~~~~~~~~~~~~~~~~~