[tor-commits] [tor-launcher/master] Bug 22232: gather info on use of bootstrap status messages

[brade at torproject.org]

commit ab8e081f3007f45e98171e163f080fea8caad964
Author: Kathy Brade <brade at pearlcrescent.com>
Date:   Tue Aug 29 15:55:21 2017 -0400

    Bug 22232: gather info on use of bootstrap status messages
---
 README-BOOTSTRAP | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/README-BOOTSTRAP b/README-BOOTSTRAP
new file mode 100644
index 0000000..8bc2a76
--- /dev/null
+++ b/README-BOOTSTRAP
@@ -0,0 +1,68 @@
+HOW TOR LAUNCHER USES BOOTSTRAP STATUS MESSAGES
+
+(This information was originally recorded in
+https://trac.torproject.org/projects/tor/ticket/22232)
+
+To start monitoring events, Tor Launcher issues the following Tor
+control port command:
+  SETEVENTS STATUS_CLIENT NOTICE WARN ERR
+Tor Launcher then looks for 650 responses.
+
+When one of the following responses is received, it is logged to
+the browser console and added to an in-memory log buffer (which is
+used to implement "Copy Tor Log To Clipboard"):
+  WARN, ERR, DEBUG, INFO, NOTICE
+
+Tor Launcher also issues a GETINFO status/bootstrap-phase command
+soon after the control port connection has been established.
+
+When a STATUS_CLIENT message is received, Tor Launcher uses the
+info contained within the message to detect bootstrap errors and
+to show progress. The GETINFO status/bootstrap-phase response is
+used for this same purpose (both kinds of response messages are
+parsed and processed by the same code).
+
+Tor Launcher maintains two important pieces of internal state
+information about the bootstrap process:
+
+mIsBootstrapDone (Boolean) This is set to true when a STATUS_CLIENT
+    BOOTSTRAP event with PROGRESS=100 is received. It is set to false
+    when any other STATUS_CLIENT BOOTSTRAP event is received.
+
+mBootstrapErrorOccurred (Boolean) This is set to true when a
+    STATUS_CLIENT BOOTSTRAP event with a severity of WARN or ERR, and
+    RECOMMENDATION of warn is received. It is set to false when
+    mIsBootstrapDone is set to true as well as after the user makes
+    changes to their settings (after a SAVECONF is done).
+
+The PROGRESS field of the STATUS_CLIENT messages are used directly
+to display the completion percentage (progress bar).
+
+The TAG= keywords within the STATUS_CLIENT messages are used for
+two purposes:
+
+1. The values are mapped to localized strings and displayed in the
+progress window. If Tor Launcher cannot map the TAG to a localized
+string, it displays the SUMMARY text instead (otherwise, the SUMMARY
+field is not used).
+
+2. The TAG value along with REASON is used to suppress repeated
+errors. When Tor Launcher sets mBootstrapErrorOccurred to true (see
+above), an error is shown to the user unless the previous error
+displayed had the same TAG and REASON values.
+
+The "Copy Tor Log To Clipboard" button is displayed with the warning
+icon when Tor Launcher detects a bootstrap error (see
+mBootstrapErrorOccurred above) or when it receives a log message
+event with severity of WARN or ERR.
+
+The severity value within a STATUS_CLIENT BOOTSTRAP event is used
+to detect bootstrap errors (as described above) and also to determine
+the level for local logging.
+
+When displaying errors, Tor Launcher tries to map the REASON values
+to localized strings. If this fails, the WARNING text is displayed
+instead. HOSTADDR is appended to the error text when it is present.
+
+RECOMMENDATION is part of the information that is used to determine
+if a bootstrap error has occurred (as described above).