[tor-bugs] #22232 [Applications/Tor Launcher]: gather info on how Tor Launcher uses bootstrap status messages

[Tor Bug Tracker & Wiki]

#22232: gather info on how Tor Launcher uses bootstrap status messages
---------------------------------------+-----------------------
 Reporter:  catalyst                   |          Owner:  brade
     Type:  task                       |         Status:  new
 Priority:  Medium                     |      Milestone:
Component:  Applications/Tor Launcher  |        Version:
 Severity:  Normal                     |     Resolution:
 Keywords:  usability, ux              |  Actual Points:
Parent ID:  #21951                     |         Points:
 Reviewer:                             |        Sponsor:
---------------------------------------+-----------------------

Comment (by brade):

 To start monitoring events, Tor Launcher issues the following 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 log"):
 `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 processeed by
 the same code).

 Tor Launcher maintains two important pieces of 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).


 Replying to [ticket:22232 catalyst]:
 > Does the progress bar currently map phase numbers directly into percent-
 done on the bar?
 Tor Launcher uses the `PROGRESS` field of the STATUS_CLIENT event for
 displaying the percent-done on the bar. Do those numbers directly
 correspond to phases?


 > Does it do anything with `TAG=` keywords in the BOOTSTRAP messages?
 The `TAG=` keywords are used for two purposes:
 1. The values are mapped to localized strings and displayed in the
 progress window.
 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.


 > Does it do anything with `SUMMARY=` strings other than displaying them
 in the dialog box?
 No. If Tor Launcher can't map the `TAG` to a localized string, it will
 display the SUMMARY text instead; otherwise, it is not used at all.


 > How does it know when to display the "copy logs" button with the warning
 icon?
 The "copy log" 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`.


 > Which other of the `BOOTSTRAP` keywords does it use and how?
 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).


 > Does it use any other asynchronous control protocol messages?
 Only the log events that were mentioned above.

 Mark and I know this is somewhat complicated, so we expect some follow up
 questions.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/22232#comment:2>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online